@udibo/oauth2 0.1.0

package/esm/identity/session.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Session revocation + step-up contracts for the identity layer.
+ *
+ * Three security primitives the own-auth flows need, kept as **contracts + a
+ * pure helper** — storage stays app-owned (the `SessionStore` philosophy, and
+ * the Lucia-deprecation lesson: don't ship a DB-adapter zoo):
+ *
+ * - {@link RevocableSessionService} — revoke a user's sessions on a credential
+ *   change. After a password reset the app must end the *other* sessions, or a
+ *   compromised account's other devices stay logged in. The reset flow calls
+ *   this; your app implements it over its session store.
+ * - {@link ListableSessionService} — the revocation seam's optional listing
+ *   half: a user's live sessions as {@link SessionSummary} display rows, so a
+ *   "where you're signed in" screen has one typed shape to render and wire the
+ *   revoke buttons against. Only a stateful store can honestly implement it.
+ * - {@link isRecentlyAuthenticated} — a recent-auth / step-up gate for sensitive
+ *   changes (change password/email, delete account, add MFA).
+ *
+ * @module
+ */
+/**
+ * Revocation operations a session store exposes so credential-change flows can
+ * end sessions. Implement over your own session storage (DB / Redis / KV).
+ */
+export interface RevocableSessionService {
+    /**
+     * Revoke **every** session belonging to `userId`. Call after a password reset
+     * or other full-account credential change. Returns the number revoked.
+     */
+    revokeAllByUser(userId: string): Promise<number>;
+    /**
+     * Revoke a user's sessions **except** `keepSessionId` — "sign out everywhere
+     * else" after a password change in the current session. Returns the number
+     * revoked.
+     */
+    revokeOthers(userId: string, keepSessionId: string): Promise<number>;
+}
+/**
+ * One live session as a "where you're signed in" screen renders it — a display
+ * projection, never the session's secret/hash or token material. The
+ * current-session marker is the caller's concern: compare
+ * {@link SessionSummary.id} against the id of the session backing the request
+ * being rendered, and label / disable "revoke" on the match ("revoke" on the
+ * current row is "sign out").
+ *
+ * Keep the optional client fields **coarse** — the contract omits raw address
+ * fields on purpose. `userAgent` is the raw header for a component to parse into
+ * a device label; `location` is a human-readable place (city / region /
+ * country) resolved from the IP at creation, not the raw address. Anything more
+ * precise turns a security screen into a tracking log; a store with nothing
+ * coarse to report leaves the field unset rather than reaching for the raw value.
+ */
+export interface SessionSummary {
+    /**
+     * Stable session id — the revoke action's target and the value a caller
+     * compares against the current session to mark "this device". Use a separate
+     * non-secret record identifier, never the cookie value or its hash.
+     */
+    id: string;
+    /** When the session was created. */
+    createdAt: Date;
+    /**
+     * Last-activity timestamp. Bump it on a throttle (once a minute, say), not on
+     * every request, or the session table becomes the hottest write path.
+     */
+    lastSeenAt: Date;
+    /** Raw user-agent header, for the UI to summarize into a device label. */
+    userAgent?: string;
+    /**
+     * Coarse, human-readable location resolved from the IP at creation (e.g.
+     * `"San Francisco, US"`) — never the raw address.
+     */
+    location?: string;
+}
+/**
+ * Optional {@link RevocableSessionService} capability: list a user's live
+ * sessions as {@link SessionSummary} rows so the "where you're signed in"
+ * screen you build renders one typed shape and wires its revoke buttons against
+ * it, instead of every app inventing a different list shape. The screen is
+ * app-owned — the package ships this seam and the row type, not a list
+ * component. A store opts in by implementing this method — it is duck-typed at
+ * runtime via
+ * {@link supportsSessionListing}, mirroring how the BFF's `BackchannelLogoutStore`
+ * is an optional capability a stateful `SessionStore` opts into.
+ *
+ * Only a store that keeps a server-side record can implement it: a listing seam
+ * implies the rows are authoritative, and the paired revoke buttons promise
+ * **immediate, not advisory** revocation. A stateless self-contained-token store
+ * the server never looks up can neither enumerate its sessions nor honor a
+ * revoke, so it omits this and the screen simply isn't offered.
+ */
+export interface ListableSessionService {
+    /**
+     * A user's live sessions as display summaries, most-recently-active first.
+     * Return only what a session screen renders — never the session secret/hash
+     * or token material. Excludes ended sessions (revoked, expired, idle-timed-out).
+     */
+    listByUser(userId: string): Promise<SessionSummary[]>;
+}
+/**
+ * Whether a session service also implements the optional
+ * {@link ListableSessionService} listing capability. Use it to decide whether to
+ * offer the "where you're signed in" screen: a stateful store returns `true`, a
+ * stateless one that only revokes returns `false`.
+ */
+export declare function supportsSessionListing(service: RevocableSessionService): service is RevocableSessionService & ListableSessionService;
+/**
+ * Whether a session authenticated within `maxAgeMs` — a recent-auth ("step-up")
+ * check to gate sensitive actions. Re-prompt for credentials when this is false.
+ *
+ * @param authenticatedAt When the session last actively authenticated (epoch ms).
+ * @param maxAgeMs How recent counts as "fresh" (e.g. 5 minutes).
+ * @param now Override the clock (for tests). Defaults to `Date.now()`.
+ *
+ * @example
+ * ```ts
+ * if (!isRecentlyAuthenticated(session.authenticatedAt, 5 * 60_000)) {
+ *   throw redirect("/reauthenticate?return_to=/settings/password");
+ * }
+ * ```
+ */
+export declare function isRecentlyAuthenticated(authenticatedAt: number, maxAgeMs: number, now?: number): boolean;

package/esm/identity/session.js

@@ -0,0 +1,48 @@
+/**
+ * Session revocation + step-up contracts for the identity layer.
+ *
+ * Three security primitives the own-auth flows need, kept as **contracts + a
+ * pure helper** — storage stays app-owned (the `SessionStore` philosophy, and
+ * the Lucia-deprecation lesson: don't ship a DB-adapter zoo):
+ *
+ * - {@link RevocableSessionService} — revoke a user's sessions on a credential
+ *   change. After a password reset the app must end the *other* sessions, or a
+ *   compromised account's other devices stay logged in. The reset flow calls
+ *   this; your app implements it over its session store.
+ * - {@link ListableSessionService} — the revocation seam's optional listing
+ *   half: a user's live sessions as {@link SessionSummary} display rows, so a
+ *   "where you're signed in" screen has one typed shape to render and wire the
+ *   revoke buttons against. Only a stateful store can honestly implement it.
+ * - {@link isRecentlyAuthenticated} — a recent-auth / step-up gate for sensitive
+ *   changes (change password/email, delete account, add MFA).
+ *
+ * @module
+ */
+/**
+ * Whether a session service also implements the optional
+ * {@link ListableSessionService} listing capability. Use it to decide whether to
+ * offer the "where you're signed in" screen: a stateful store returns `true`, a
+ * stateless one that only revokes returns `false`.
+ */
+export function supportsSessionListing(service) {
+    return typeof service.listByUser ===
+        "function";
+}
+/**
+ * Whether a session authenticated within `maxAgeMs` — a recent-auth ("step-up")
+ * check to gate sensitive actions. Re-prompt for credentials when this is false.
+ *
+ * @param authenticatedAt When the session last actively authenticated (epoch ms).
+ * @param maxAgeMs How recent counts as "fresh" (e.g. 5 minutes).
+ * @param now Override the clock (for tests). Defaults to `Date.now()`.
+ *
+ * @example
+ * ```ts
+ * if (!isRecentlyAuthenticated(session.authenticatedAt, 5 * 60_000)) {
+ *   throw redirect("/reauthenticate?return_to=/settings/password");
+ * }
+ * ```
+ */
+export function isRecentlyAuthenticated(authenticatedAt, maxAgeMs, now = Date.now()) {
+    return authenticatedAt > 0 && now - authenticatedAt <= maxAgeMs;
+}

package/esm/identity/token-flow.d.ts

@@ -0,0 +1,214 @@
+/**
+ * One token-flow primitive for the single-use, expiring links an identity layer
+ * needs — **email verification** and **password reset** are the same mechanics:
+ * mint a high-entropy token, store only its hash, hand the raw token to the app
+ * to deliver, then validate / single-use-consume it later.
+ *
+ * The app reimplements this once per flow today (random bytes → sha256 → store
+ * with expiry → consume). This collapses it into one tested, enumeration-safe
+ * building block. Storage is an app-owned {@link TokenFlowStore} (a
+ * {@link MemoryTokenFlowStore} ships for dev/tests); the package owns the
+ * lifecycle, not the database.
+ *
+ * @module
+ */
+/** Common token purposes. `purpose` is a free string; these are conventions. */
+export declare const TokenPurpose: {
+    readonly EmailVerification: "email-verification";
+    readonly PasswordReset: "password-reset";
+    readonly AccountUnlock: "account-unlock";
+    readonly SignIn: "signin";
+};
+/**
+ * A stored token record. Holds the token's **hash**, never the raw token — a
+ * leaked record (or log line) can't be replayed as a working link.
+ */
+export interface TokenFlowRecord {
+    /** sha256-hex of the raw token; the storage key and at-rest form. */
+    tokenHash: string;
+    /** What the token authorizes (e.g. {@link TokenPurpose.PasswordReset}). */
+    purpose: string;
+    /** The subject the token acts on (typically a user id). */
+    subject: string;
+    /** Optional extra payload (e.g. the email being verified). */
+    data?: Record<string, unknown>;
+    /** Expiry, epoch ms. */
+    expiresAt: number;
+    /** When consumed (epoch ms), or `undefined` while still usable. */
+    consumedAt?: number;
+    /** Created, epoch ms. */
+    createdAt: number;
+}
+/** App-owned persistence for {@link TokenFlowService}, keyed by `tokenHash`. */
+export interface TokenFlowStore {
+    /** Persist a new record. */
+    save(record: TokenFlowRecord): Promise<void>;
+    /**
+     * Look up a record by token hash, or `null` when no record was ever stored
+     * under it.
+     *
+     * Return the record **whatever its state** — expired and already-consumed
+     * records included. {@link TokenFlowService.inspect} classifies them
+     * (`expired` vs `consumed` vs `invalid`) after this read, so a store that
+     * filters them out in SQL (`... AND consumed_at IS NULL AND expires_at >
+     * now()`) collapses both into `invalid` and costs the caller the message it
+     * would otherwise show.
+     */
+    get(tokenHash: string): Promise<TokenFlowRecord | null>;
+    /**
+     * Atomically claim a record as consumed (single-use): stamp `consumedAt` and
+     * return `true` only when the record existed and was still unconsumed
+     * (`UPDATE … SET consumed_at = $now WHERE token_hash = $hash AND consumed_at
+     * IS NULL`, checking the row count). Return `false` without changing anything
+     * otherwise.
+     *
+     * This **must** be a conditional write, not a read-then-write.
+     * {@link TokenFlowService.consume} reads the record before calling this and
+     * treats a `false` as "someone else got it", which is the only thing making a
+     * link single-use under concurrent redemption — an unconditional overwrite
+     * that always reports success lets two requests racing one link both proceed.
+     */
+    markConsumed(tokenHash: string, consumedAt: number): Promise<boolean>;
+    /**
+     * Optional: delete every still-pending token for a `(purpose, subject)` — e.g.
+     * invalidate outstanding reset links once one succeeds, or when a new one is
+     * issued. Implement it to harden the flow; the service calls it only if present.
+     *
+     * Delete the **pending** records only. Leaving the consumed ones keeps
+     * {@link TokenFlowService.inspect} able to answer `consumed` for a token that
+     * really was used, instead of the generic `invalid`.
+     */
+    deleteBySubject?(purpose: string, subject: string): Promise<void>;
+}
+/** Options for {@link TokenFlowService.create}. */
+export interface CreateTokenOptions {
+    /** What the token authorizes (e.g. {@link TokenPurpose.PasswordReset}). */
+    purpose: string;
+    /** The subject the token acts on (typically a user id). */
+    subject: string;
+    /** Optional extra payload to carry on the record (e.g. the email being verified). */
+    data?: Record<string, unknown>;
+    /** Lifetime in milliseconds. */
+    ttlMs: number;
+    /**
+     * Invalidate any existing pending tokens for this `(purpose, subject)` first
+     * (requires {@link TokenFlowStore.deleteBySubject}). Defaults to `false`.
+     */
+    invalidateExisting?: boolean;
+}
+/** The raw token to deliver, available only at creation time. */
+export interface CreatedToken {
+    /** The raw token — send it to the user; it is never stored or recoverable. */
+    token: string;
+    /** When the token expires, epoch ms. */
+    expiresAt: number;
+}
+/** The result of validating/consuming a token. */
+export interface ResolvedToken {
+    /** The subject the token acts on (typically a user id). */
+    subject: string;
+    /** The extra payload supplied at creation, if any. */
+    data?: Record<string, unknown>;
+}
+/**
+ * The detailed outcome of {@link TokenFlowService.inspect}. Unlike the
+ * `null`-returning {@link TokenFlowService.validate}/{@link TokenFlowService.consume},
+ * this distinguishes **why** a token failed — so a verify/reset UI can say
+ * "this link has expired, request a new one" vs. a generic error. (A 32-byte
+ * random token isn't enumerable, so reporting `expired` vs `invalid` for the
+ * token is not a meaningful leak — distinct from email enumeration.)
+ */
+export type TokenStatus = {
+    status: "valid";
+    subject: string;
+    data?: Record<string, unknown>;
+} | {
+    status: "invalid";
+} | {
+    status: "expired";
+} | {
+    status: "consumed";
+};
+/**
+ * Issues, validates, and single-use-consumes purpose-scoped tokens.
+ *
+ * @example
+ * ```ts
+ * const tokens = new TokenFlowService(store);
+ * const { token } = await tokens.create({
+ *   purpose: TokenPurpose.PasswordReset, subject: user.id, ttlMs: 3_600_000,
+ * });
+ * // …email a link containing `token`…
+ * const resolved = await tokens.consume(TokenPurpose.PasswordReset, token);
+ * if (resolved) await resetPassword(resolved.subject, newPassword);
+ * ```
+ */
+export declare class TokenFlowService {
+    #private;
+    /** Wraps an app-owned {@linkcode TokenFlowStore} that persists the token records. */
+    constructor(store: TokenFlowStore);
+    /**
+     * Drop every pending token for a `(purpose, subject)` without redeeming one —
+     * e.g. voiding outstanding sign-in links when the user resets their password,
+     * so a link an attacker already has stops working.
+     *
+     * Best-effort by design: {@link TokenFlowStore.deleteBySubject} is optional.
+     * Returns `true` when the store implements it and the deletion ran, and
+     * `false` when the store does not, in which case those tokens stay redeemable
+     * until they expire — check the result if that gap matters to you. A store
+     * that throws propagates the error.
+     */
+    invalidate(purpose: string, subject: string): Promise<boolean>;
+    /** Mint a token; stores its hash and returns the raw token (once). */
+    create(opts: CreateTokenOptions): Promise<CreatedToken>;
+    /**
+     * Validate a token **without** consuming it (e.g. to render a reset form
+     * before the user submits). Returns the subject/data, or `null` if the token
+     * is unknown, wrong-purpose, expired, or already consumed — never reveals which.
+     */
+    validate(purpose: string, token: string): Promise<ResolvedToken | null>;
+    /**
+     * Validate **and** consume a token (single-use). Returns the subject/data, or
+     * `null` (see {@link validate} for the failure cases). A second `consume` of
+     * the same token returns `null` — including when the second one races the
+     * first, since only the caller whose {@link TokenFlowStore.markConsumed}
+     * claimed the record is handed the token.
+     */
+    consume(purpose: string, token: string): Promise<ResolvedToken | null>;
+    /**
+     * Inspect a token **without** consuming it, reporting the detailed
+     * {@link TokenStatus} — `valid` (with subject/data), `invalid` (unknown or
+     * wrong-purpose), `expired`, or `consumed`. Use this when the UI needs to tell
+     * "expired" apart from "invalid" (e.g. an email-verification page that offers
+     * to resend). {@link validate} is the `null`-returning shorthand.
+     */
+    inspect(purpose: string, token: string): Promise<TokenStatus>;
+}
+/**
+ * In-memory {@link TokenFlowStore} for development and tests. Records are lost
+ * on restart; back the contract with a database for production.
+ *
+ * Nothing is reclaimed: a consumed record is kept so
+ * {@link TokenFlowService.inspect} can still answer `consumed`, and no sweep
+ * ever removes it, so the map grows by one entry per token minted. That is
+ * fine for a fixture and wrong in a database-backed port — give the rows a TTL
+ * or a purge job that drops records already past `expiresAt`. Purge only
+ * records that are *also* consumed: dropping an expired-but-unconsumed record
+ * collapses `expired` into `invalid` and loses the distinction `inspect`
+ * reports.
+ */
+export declare class MemoryTokenFlowStore implements TokenFlowStore {
+    #private;
+    /** Persist a record, keyed by its token hash. */
+    save(record: TokenFlowRecord): Promise<void>;
+    /** Return the record for a token hash, or `null` if none is stored. */
+    get(tokenHash: string): Promise<TokenFlowRecord | null>;
+    /** Claim the record if still unconsumed; `false` when unknown or already spent. */
+    markConsumed(tokenHash: string, consumedAt: number): Promise<boolean>;
+    /**
+     * Drop every still-pending record matching the given `(purpose, subject)`.
+     * Already-consumed records are kept so {@link TokenFlowService.inspect} can
+     * still report `consumed` rather than the generic `invalid`.
+     */
+    deleteBySubject(purpose: string, subject: string): Promise<void>;
+}

package/esm/identity/token-flow.js

@@ -0,0 +1,173 @@
+/**
+ * One token-flow primitive for the single-use, expiring links an identity layer
+ * needs — **email verification** and **password reset** are the same mechanics:
+ * mint a high-entropy token, store only its hash, hand the raw token to the app
+ * to deliver, then validate / single-use-consume it later.
+ *
+ * The app reimplements this once per flow today (random bytes → sha256 → store
+ * with expiry → consume). This collapses it into one tested, enumeration-safe
+ * building block. Storage is an app-owned {@link TokenFlowStore} (a
+ * {@link MemoryTokenFlowStore} ships for dev/tests); the package owns the
+ * lifecycle, not the database.
+ *
+ * @module
+ */
+import { sha256Hash } from "../server/utils/hash.js";
+import { randomToken } from "../utils/crypto.js";
+/** Common token purposes. `purpose` is a free string; these are conventions. */
+export const TokenPurpose = {
+    EmailVerification: "email-verification",
+    PasswordReset: "password-reset",
+    AccountUnlock: "account-unlock",
+    SignIn: "signin",
+};
+/**
+ * Issues, validates, and single-use-consumes purpose-scoped tokens.
+ *
+ * @example
+ * ```ts
+ * const tokens = new TokenFlowService(store);
+ * const { token } = await tokens.create({
+ *   purpose: TokenPurpose.PasswordReset, subject: user.id, ttlMs: 3_600_000,
+ * });
+ * // …email a link containing `token`…
+ * const resolved = await tokens.consume(TokenPurpose.PasswordReset, token);
+ * if (resolved) await resetPassword(resolved.subject, newPassword);
+ * ```
+ */
+export class TokenFlowService {
+    #store;
+    /** Wraps an app-owned {@linkcode TokenFlowStore} that persists the token records. */
+    constructor(store) {
+        this.#store = store;
+    }
+    /**
+     * Drop every pending token for a `(purpose, subject)` without redeeming one —
+     * e.g. voiding outstanding sign-in links when the user resets their password,
+     * so a link an attacker already has stops working.
+     *
+     * Best-effort by design: {@link TokenFlowStore.deleteBySubject} is optional.
+     * Returns `true` when the store implements it and the deletion ran, and
+     * `false` when the store does not, in which case those tokens stay redeemable
+     * until they expire — check the result if that gap matters to you. A store
+     * that throws propagates the error.
+     */
+    async invalidate(purpose, subject) {
+        if (!this.#store.deleteBySubject)
+            return false;
+        await this.#store.deleteBySubject(purpose, subject);
+        return true;
+    }
+    /** Mint a token; stores its hash and returns the raw token (once). */
+    async create(opts) {
+        if (opts.invalidateExisting) {
+            await this.invalidate(opts.purpose, opts.subject);
+        }
+        const token = randomToken();
+        const now = Date.now();
+        const expiresAt = now + opts.ttlMs;
+        await this.#store.save({
+            tokenHash: await sha256Hash(token),
+            purpose: opts.purpose,
+            subject: opts.subject,
+            data: opts.data,
+            expiresAt,
+            createdAt: now,
+        });
+        return { token, expiresAt };
+    }
+    /**
+     * Validate a token **without** consuming it (e.g. to render a reset form
+     * before the user submits). Returns the subject/data, or `null` if the token
+     * is unknown, wrong-purpose, expired, or already consumed — never reveals which.
+     */
+    async validate(purpose, token) {
+        const status = await this.inspect(purpose, token);
+        return status.status === "valid"
+            ? { subject: status.subject, data: status.data }
+            : null;
+    }
+    /**
+     * Validate **and** consume a token (single-use). Returns the subject/data, or
+     * `null` (see {@link validate} for the failure cases). A second `consume` of
+     * the same token returns `null` — including when the second one races the
+     * first, since only the caller whose {@link TokenFlowStore.markConsumed}
+     * claimed the record is handed the token.
+     */
+    async consume(purpose, token) {
+        const tokenHash = await sha256Hash(token);
+        const status = this.#statusOf(await this.#store.get(tokenHash), purpose);
+        if (status.status !== "valid")
+            return null;
+        if (!await this.#store.markConsumed(tokenHash, Date.now()))
+            return null;
+        return { subject: status.subject, data: status.data };
+    }
+    /**
+     * Inspect a token **without** consuming it, reporting the detailed
+     * {@link TokenStatus} — `valid` (with subject/data), `invalid` (unknown or
+     * wrong-purpose), `expired`, or `consumed`. Use this when the UI needs to tell
+     * "expired" apart from "invalid" (e.g. an email-verification page that offers
+     * to resend). {@link validate} is the `null`-returning shorthand.
+     */
+    async inspect(purpose, token) {
+        return this.#statusOf(await this.#store.get(await sha256Hash(token)), purpose);
+    }
+    #statusOf(record, purpose) {
+        if (!record || record.purpose !== purpose)
+            return { status: "invalid" };
+        if (record.consumedAt !== undefined)
+            return { status: "consumed" };
+        if (record.expiresAt <= Date.now())
+            return { status: "expired" };
+        return { status: "valid", subject: record.subject, data: record.data };
+    }
+}
+/**
+ * In-memory {@link TokenFlowStore} for development and tests. Records are lost
+ * on restart; back the contract with a database for production.
+ *
+ * Nothing is reclaimed: a consumed record is kept so
+ * {@link TokenFlowService.inspect} can still answer `consumed`, and no sweep
+ * ever removes it, so the map grows by one entry per token minted. That is
+ * fine for a fixture and wrong in a database-backed port — give the rows a TTL
+ * or a purge job that drops records already past `expiresAt`. Purge only
+ * records that are *also* consumed: dropping an expired-but-unconsumed record
+ * collapses `expired` into `invalid` and loses the distinction `inspect`
+ * reports.
+ */
+export class MemoryTokenFlowStore {
+    #byHash = new Map();
+    /** Persist a record, keyed by its token hash. */
+    save(record) {
+        this.#byHash.set(record.tokenHash, record);
+        return Promise.resolve();
+    }
+    /** Return the record for a token hash, or `null` if none is stored. */
+    get(tokenHash) {
+        return Promise.resolve(this.#byHash.get(tokenHash) ?? null);
+    }
+    /** Claim the record if still unconsumed; `false` when unknown or already spent. */
+    markConsumed(tokenHash, consumedAt) {
+        const record = this.#byHash.get(tokenHash);
+        if (!record || record.consumedAt !== undefined) {
+            return Promise.resolve(false);
+        }
+        record.consumedAt = consumedAt;
+        return Promise.resolve(true);
+    }
+    /**
+     * Drop every still-pending record matching the given `(purpose, subject)`.
+     * Already-consumed records are kept so {@link TokenFlowService.inspect} can
+     * still report `consumed` rather than the generic `invalid`.
+     */
+    deleteBySubject(purpose, subject) {
+        for (const [hash, record] of this.#byHash) {
+            if (record.purpose === purpose && record.subject === subject &&
+                record.consumedAt === undefined) {
+                this.#byHash.delete(hash);
+            }
+        }
+        return Promise.resolve();
+    }
+}

package/esm/models/authentication.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Verified authentication claims for one event, supplied by application policy.
+ *
+ * Capture this context at authorization-code issuance and persist it on codes
+ * and tokens. Refresh rotations retain the original event. Omit unknown claims;
+ * neither a requested assurance level nor token issuance time is evidence.
+ *
+ * @example
+ * ```ts
+ * const event: AuthenticationContext = {
+ *   auth_time: 1_700_000_000,
+ *   acr: "urn:example:password",
+ *   amr: ["pwd"],
+ * };
+ * ```
+ */
+export interface AuthenticationContext {
+    /** Verified authentication time in Unix seconds, not token issuance time. */
+    readonly auth_time?: number;
+    /** Achieved authentication context, never the requested preference. */
+    readonly acr?: string;
+    /** Truthful authentication methods; omitted when the complete set is unknown. */
+    readonly amr?: readonly string[];
+}

package/esm/models/authentication.js

@@ -0,0 +1 @@
+export {};

package/esm/models/authorization-code.d.ts

@@ -0,0 +1,63 @@
+import type { AbstractScope, BasicScope } from "./scope.js";
+import type { ClientInterface } from "./client.js";
+import type { AuthenticationContext } from "./authentication.js";
+/**
+ * Authorization code model.
+ *
+ * Represents an authorization code issued by the authorization server
+ * after the resource owner grants authorization. The code is exchanged
+ * for tokens at the token endpoint.
+ */
+export interface AuthorizationCode<Client extends ClientInterface, User, Scope extends AbstractScope = BasicScope> {
+    /** The authorization code string. */
+    code: string;
+    /** When the code expires. */
+    expiresAt: Date;
+    /** The client that requested authorization. */
+    client: Client;
+    /** The user who authorized the request. */
+    user: User;
+    /** The scope that was authorized. */
+    scope?: Scope | null;
+    /** The redirect URI used in the authorization request. */
+    redirectUri?: string;
+    /** PKCE code challenge. */
+    challenge?: string;
+    /** PKCE challenge method (S256 or plain). */
+    challengeMethod?: string;
+    /** OIDC nonce from the authorization request, echoed into the id_token. */
+    nonce?: string;
+    /** Verified event captured at issuance; code stores must persist and restore it. */
+    authenticationContext?: AuthenticationContext;
+}
+/**
+ * Parameters from an authorization request.
+ *
+ * Parsed from the query string of an authorization endpoint request.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
+ */
+export interface AuthorizeParameters {
+    /** Raw space-delimited ACR preferences; application policy must validate and honor them. */
+    acrValues?: string;
+    /** Raw maximum authentication age in seconds; application policy must validate and enforce it. */
+    maxAge?: string;
+    /** Raw prompt values; application policy must honor or refuse every supported control. */
+    prompt?: string;
+    /** Must be "code" for authorization code flow. */
+    responseType?: string;
+    /** Client identifier issued to the client. */
+    clientId?: string;
+    /** URI to redirect to after authorization. */
+    redirectUri?: string;
+    /** Opaque state value for CSRF protection. */
+    state?: string;
+    /** Space-delimited list of requested scopes. */
+    scope?: string;
+    /** PKCE code challenge (RFC 7636). */
+    challenge?: string;
+    /** PKCE code challenge method ("S256" or "plain"). */
+    challengeMethod?: string;
+    /** OIDC nonce (echoed into the id_token when `openid` is granted). */
+    nonce?: string;
+}

package/esm/models/authorization-code.js

@@ -0,0 +1 @@
+export {};