Authentication contract
Authentication answers "who are you?". It is a delegable question, so it is served by adapters; "what may you do?" is not, and has none — see adapters .
Identity and rejection
/**
* A successfully authenticated principal.
*
* `subject` is the only value that may participate in an authorization decision;
* `email` is presentation metadata. Email addresses are mutable and reassignable,
* so binding permissions to them would let a recycled address inherit the
* permissions of its previous holder.
*/
interface Identity {
subject: string
email: string
}
/**
* Why a provider refused a sign-in (AUTHN-2).
*
* `credentials` covers an unknown email and a wrong password alike, and is the reason whenever the
* provider cannot tell. The other two are reported only once the password is known to be right.
*/
type RejectionReason = 'credentials' | 'disabled' | 'second-factor-required'
/** A refused sign-in. Core shows the user one message for every reason, and logs the reason. */
interface Rejection {
readonly rejected: RejectionReason
}
export type {
Identity,
Rejection,
RejectionReason
} ts
subject is a stable, provider-issued identifier, and the only value that takes part in an
authorization decision. email is shown to the user and carried in the session: addresses change
hands, and a recycled address must not inherit its previous holder's permissions.
Adapter
import type { Identity, Rejection } from './types.d.ts'
export declare namespace Adapter {
/** AUTHN-2. A provider that cannot decide throws `authentication/…` instead (AUTHN-3). */
type authenticate = (email: string, password: string) => Promise<Identity | Rejection>
/** AUTHN-4. `null` for a subject that is unknown, deleted or disabled. */
type getIdentity = (subject: string) => Promise<Identity | null>
}
/** One constructed authentication provider. */
export interface Adapter {
authenticate: Adapter.authenticate
getIdentity: Adapter.getIdentity
} ts
authenticatereturns theIdentitythe credentials belong to, or aRejection.credentialscovers an unknown email and a wrong password alike, and is the reason whenever the adapter cannot tell.disabledandsecond-factor-requiredare reported only when the password is known to be right.getIdentityreturns theIdentityof a subject that exists and could sign in now, with its current email, andnullfor one that is unknown, deleted or disabled. GenoaCMS calls it on every session refresh.- An adapter that cannot decide — its service failed, refused to answer, or is misconfigured — throws an
Errorwhose message starts withauthentication/, such asauthentication/provider-failed: …. A throttled service throwsauthentication/throttled…. A failure is never reported as aRejection, or asnull.
How GenoaCMS combines several providers is under identity and sessions .
import type { Adapter } from './adapter.d.ts'
import type { Identity, Rejection, RejectionReason } from './types.d.ts'
/** True for a Rejection, false for an Identity (AUTHN-2). */
declare function isRejection (result: Identity | Rejection): result is Rejection
export { isRejection }
export type { Adapter, Identity, Rejection, RejectionReason } ts
runAuthenticationConformance in @genoacms/conformance checks an adapter against this contract.