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
Expand code

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
  • authenticate returns the Identity the credentials belong to, or a Rejection. credentials covers an unknown email and a wrong password alike, and is the reason whenever the adapter cannot tell. disabled and second-factor-required are reported only when the password is known to be right.
  • getIdentity returns the Identity of a subject that exists and could sign in now, with its current email, and null for 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 Error whose message starts with authentication/, such as authentication/provider-failed: …. A throttled service throws authentication/throttled…. A failure is never reported as a Rejection, or as null.

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.