@_mustachio/openauth 0.9.1 → 0.10.0

package/dist/types/ports/method-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `MethodStore` — per-tenant `MethodConfig` lookup.
+ *
+ * This is a subset of `ConfigStore` exposed as a separate port for two
+ * reasons:
+ *  1. Adapters may want to back `MethodStore` with a more frequently
+ *     invalidated cache than the full tenant config.
+ *  2. The management console can update auth-method config independently
+ *     of other tenant-level fields.
+ *
+ * Consistency: same as `ConfigStore` — eventual + bounded staleness
+ * (TTL ≤ 60 s). Invalidation hook fires on update.
+ */
+import type { Result } from "../types/result";
+import type { MethodConfig, TenantId } from "../types/tenant";
+export type MethodStore = {
+    /** All method instances configured for a tenant (enabled and disabled). */
+    listMethods(tenantId: TenantId): Promise<Result<MethodConfig[]>>;
+    /**
+     * Look up a single method instance by tenant-local id. Returns
+     * `method_not_found` if `methodId` does not exist in this tenant.
+     */
+    getMethodConfig(tenantId: TenantId, methodId: string): Promise<Result<MethodConfig>>;
+    /** Persist (create or update) a method instance. Triggers invalidation. */
+    putMethodConfig(tenantId: TenantId, method: MethodConfig): Promise<Result<void>>;
+    /** Delete a method instance. Tokens issued by it remain valid until expiry. */
+    deleteMethodConfig(tenantId: TenantId, methodId: string): Promise<Result<void>>;
+};
+//# sourceMappingURL=method-store.d.ts.map

package/dist/types/ports/method-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-store.d.ts","sourceRoot":"","sources":["../../../src/ports/method-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE7D,MAAM,MAAM,WAAW,GAAG;IACxB,2EAA2E;IAC3E,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAA;IAEhE;;;OAGG;IACH,eAAe,CACb,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAA;IAEhC,2EAA2E;IAC3E,eAAe,CACb,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IAExB,+EAA+E;IAC/E,kBAAkB,CAChB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;CACzB,CAAA"}

package/dist/types/ports/session-store.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `SessionStore` — flow records (required) and optional long-lived sessions.
+ *
+ * Flow records are the single server-side source of truth for an in-flight
+ * authorization. They are written at `/authorize`, updated when a method
+ * returns a `challenge` with `saveMethodState`, and consumed exactly once
+ * on the upstream callback.
+ *
+ * The framework owns flow-record I/O — methods only observe
+ * (`MethodContext.flow`) and request updates via
+ * `MethodResult.challenge.saveMethodState`. Methods MUST NOT call
+ * `saveFlow` / `consumeFlow` directly.
+ *
+ * See `ports/CONSISTENCY.md`.
+ */
+import type { FlowRecord } from "../types/flow";
+import type { Result } from "../types/result";
+export type SessionStore = {
+    /**
+     * Persist a new flow record under `flowId`. Strong, atomic write — the
+     * record must be visible to `consumeFlow` on any node by the time this
+     * resolves. `ttl` is in milliseconds and must equal `expiresAt -
+     * createdAt` on the supplied record (default 10 minutes).
+     */
+    saveFlow(flowId: string, payload: FlowRecord, ttl: number): Promise<Result<void>>;
+    /**
+     * Merge `methodState` into an existing flow record. The framework calls
+     * this when a method handler returns
+     * `{ kind: "challenge", saveMethodState }`, **before** sending the
+     * upstream redirect response — the user agent never sees the redirect
+     * until `methodState` is durably saved.
+     *
+     * Returns `unknown_state` if `flowId` is missing or already consumed.
+     */
+    updateFlowMethodState(flowId: string, methodState: unknown): Promise<Result<void>>;
+    /**
+     * **Peek** at a flow record without consuming it. Used by the method-route
+     * mount (Phase 4) where credential POSTs may need to dispatch the
+     * method multiple times before the flow is consumed on `success`.
+     *
+     * Consistency: strong (the record must be visible to a `consumeFlow`
+     * called immediately after). Returns `unknown_state` if missing /
+     * expired.
+     *
+     * The framework is the only legitimate caller; methods should never read
+     * the flow directly — they observe via `MethodContext.flow`.
+     */
+    readFlow(flowId: string): Promise<Result<FlowRecord>>;
+    /**
+     * Atomic delete-on-read. Returns the full `FlowRecord` on success — the
+     * framework needs every field to snapshot into the auth-code payload
+     * before the record is gone. Concurrent calls with the same `flowId`
+     * resolve to exactly one winner; losers receive `unknown_state` which
+     * the HTTP layer maps to `invalid_request` (audit
+     * `flow_replay_attempt`).
+     *
+     * This is the **only** consume; the framework does not call it twice.
+     * Methods receive the in-memory record via `MethodContext.flow` for the
+     * rest of the callback request.
+     */
+    consumeFlow(flowId: string): Promise<Result<FlowRecord>>;
+    /**
+     * Optional: long-lived session support (cross-request remember-me beyond
+     * the OAuth flow). Adapters that don't implement this can omit it; the
+     * framework only requires the flow-record methods above.
+     */
+    createSession?(sessionId: string, payload: SessionRecord, ttl: number): Promise<Result<void>>;
+    readSession?(sessionId: string): Promise<Result<SessionRecord>>;
+    revokeSession?(sessionId: string): Promise<Result<void>>;
+};
+/** Optional long-lived session payload (used by `createSession` family). */
+export type SessionRecord = {
+    sessionId: string;
+    tenantId: string;
+    subjectId: string;
+    /** Wall-clock issued / expires timestamps (ms). */
+    issuedAt: number;
+    expiresAt: number;
+    /** Free-form metadata adapters may use (device, user agent fingerprint, etc.). */
+    metadata?: Record<string, unknown>;
+};
+//# sourceMappingURL=session-store.d.ts.map

package/dist/types/ports/session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../../../src/ports/session-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAE7C,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;OAKG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IAExB;;;;;;;;OAQG;IACH,qBAAqB,CACnB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,OAAO,GACnB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IAExB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAA;IAErD;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAA;IAExD;;;;OAIG;IACH,aAAa,CAAC,CACZ,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IACxB,WAAW,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAA;IAC/D,aAAa,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;CACzD,CAAA;AAED,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,CAAA"}

package/dist/types/ports/token-store.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `TokenStore` — authorization codes + refresh tokens.
+ *
+ * All methods on this port are **security-critical** and require strong,
+ * atomic semantics. Cloudflare KV is **not** an acceptable backing store
+ * for any method here; use D1 (Sessions API w/ bookmarks), Durable Objects,
+ * Postgres (`SELECT FOR UPDATE`), or DynamoDB with conditional writes.
+ *
+ * See `ports/CONSISTENCY.md` §"Per-method consistency contracts".
+ */
+import type { RefreshTokenPayload } from "../types/token";
+import type { Result } from "../types/result";
+import type { TenantId } from "../types/tenant";
+export type TokenStore = {
+    /**
+     * Persist an auth-code ciphertext blob under `code`.
+     *
+     * The blob is **opaque** to the adapter — the framework encrypts the
+     * `CodePayload` at the domain boundary (`domain/authorize.ts` →
+     * `domain/crypto.encryptPayload`) before calling `saveCode`. Adapters
+     * must not parse, transform, or otherwise interpret the blob; just
+     * store it verbatim and return it on `consumeCode`.
+     *
+     * Required semantics:
+     *  - Strong, atomic write (the row must be visible to the next
+     *    `consumeCode` call on any node).
+     *  - `ttl` must be ≤ the framework's auth-code TTL (60 s).
+     *    Implementations that receive a larger value must reject.
+     */
+    saveCode(code: string, ciphertext: string, ttl: number): Promise<Result<void>>;
+    /**
+     * Single-use, atomic compare-and-swap: return and delete the
+     * ciphertext blob in one logical operation. Concurrent calls with the
+     * same `code` must resolve to exactly one winner; losers receive
+     * `invalid_grant`. The caller (`domain/token.exchangeCode`) decrypts
+     * the returned blob.
+     */
+    consumeCode(code: string): Promise<Result<string>>;
+    /**
+     * Persist a refresh-token payload. Strong, atomic. New tokens issued
+     * during rotation must be immediately retrievable.
+     */
+    saveRefresh(refresh: string, payload: RefreshTokenPayload): Promise<Result<void>>;
+    /**
+     * Rotate a refresh token. Strong CAS with reuse-detection window.
+     *
+     * Implementations must:
+     *  - Atomically check the token is unconsumed, mark it consumed, and
+     *    return its payload — concurrent presentations of the same token
+     *    resolve to exactly one winner.
+     *  - Within the reuse window (default 60 s), the consumed token must
+     *    still be detectable so a second presentation can trigger
+     *    revoke-the-whole-family. Outside the window the row may be GC'd.
+     *  - On reuse-detection (second consume within the window), return an
+     *    `invalid_grant` error **with a `reuseSignal` carrier** containing
+     *    the compromised refresh chain's `family`, `tenantId`, and
+     *    `subjectId`. The framework's refresh-grant handler reads
+     *    `reuseSignal` directly to emit `refresh_reuse_detected` audit
+     *    events. Adapters that omit the signal degrade audit fidelity (the
+     *    framework falls back to the peeked-payload values) but remain
+     *    behavior-compatible.
+     */
+    consumeRefresh(refresh: string, options?: {
+        reuseWindowMs?: number;
+    }): Promise<Result<RefreshTokenPayload>>;
+    /**
+     * Non-destructive lookup. Returns the refresh-token payload without
+     * marking it consumed.
+     *
+     * Used by RFC 7009 `/revoke` to enforce token-to-client binding
+     * (§2.2) before destructively consuming. Returns `invalid_grant` for
+     * unknown or expired tokens; `peekRefresh` does **not** trigger
+     * reuse-detection — a token already past `consumeRefresh` is still
+     * reported here so the caller can decide whether to escalate.
+     *
+     * Eventual consistency is acceptable: callers race `peekRefresh` then
+     * `consumeRefresh`, and the atomicity guarantees of `consumeRefresh`
+     * remain authoritative.
+     */
+    peekRefresh(refresh: string): Promise<Result<RefreshTokenPayload>>;
+    /**
+     * Revoke all refresh tokens whose `RefreshTokenPayload.family` equals
+     * `family`. Used by reuse-detection to invalidate every descendant of a
+     * compromised refresh chain.
+     */
+    revokeFamily(family: string): Promise<Result<void>>;
+    /**
+     * Revoke every refresh token for the given (tenant, subject) pair. Strong
+     * preferred; documented eventual lag acceptable.
+     */
+    revokeBySubject(tenantId: TenantId, subjectId: string): Promise<Result<void>>;
+};
+//# sourceMappingURL=token-store.d.ts.map

package/dist/types/ports/token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../../src/ports/token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AACzD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE/C,MAAM,MAAM,UAAU,GAAG;IACvB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IAE9E;;;;;;OAMG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;IAElD;;;OAGG;IACH,WAAW,CACT,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IAExB;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACnC,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAA;IAEvC;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAA;IAElE;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IAEnD;;;OAGG;IACH,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;CAC9E,CAAA"}

package/dist/types/types/authorization.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Authorization-request domain shapes. The HTTP layer parses the raw
+ * `/authorize` query into `AuthorizationRequest`; the domain operates on
+ * that.
+ */
+import type { TenantId } from "./tenant";
+/**
+ * Parsed `/authorize` request. The HTTP layer is responsible for schema
+ * validation (Zod) and for rejecting `response_type=token` per OAuth 2.1.
+ *
+ * `audience` and OIDC-specific fields (`prompt`, `uiLocales`, `nonce`) are
+ * optional and threaded into the `FlowRecord`.
+ */
+export type AuthorizationRequest = {
+    tenantId: TenantId;
+    clientId: string;
+    redirectUri: string;
+    /** OAuth 2.1: `code` only. */
+    responseType: "code";
+    scopes: string[];
+    /** Relying party's CSRF state. Echoed back at success; opaque to the IdP. */
+    state: string | null;
+    audience?: string;
+    /** Tenant-local method instance id (`MethodConfig.id`) the RP selected, if any. */
+    methodId?: string;
+    /**
+     * Relying-party PKCE challenge. Required for public clients; the framework
+     * additionally requires it for any client where `ClientConfig.pkceRequired`
+     * is true (default true).
+     */
+    codeChallenge?: string;
+    codeChallengeMethod?: "S256";
+    /** Standard OIDC. */
+    prompt?: string[];
+    /** Standard OIDC. */
+    uiLocales?: string[];
+    /** Standard OIDC. */
+    nonce?: string;
+};
+/**
+ * In-memory authorization state produced by `domain/authorize.startAuthorize`
+ * when it has not yet emitted a `Response` (e.g. method selection UI was
+ * not needed because only one method is configured, so the domain returns
+ * the chosen state directly for the next stage to act on).
+ */
+export type AuthorizationState = {
+    tenantId: TenantId;
+    flowId: string;
+    methodId: string;
+    methodKind: string;
+};
+//# sourceMappingURL=authorization.d.ts.map

package/dist/types/types/authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../../../src/types/authorization.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,qBAAqB;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,qBAAqB;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,QAAQ,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA"}

package/dist/types/types/error.d.ts

@@ -0,0 +1,92 @@
+/**
+ * AuthError — the closed taxonomy returned by every domain function on failure.
+ *
+ * Codes map 1:1 to OAuth 2.0 / RFC 6749 §5.2 error identifiers, plus a handful
+ * of framework-internal codes used before the HTTP layer is reached. The HTTP
+ * layer translates `AuthError` into a response (`server_error` is the public
+ * mapping for `internal_error` at OAuth endpoints).
+ */
+export type AuthError = {
+    code: "invalid_request";
+    description: string;
+    field?: string;
+} | {
+    code: "invalid_client";
+    description: string;
+}
+/**
+ * `invalid_grant`. `reuseSignal`, when present, is the structured
+ * reuse-detection hint `TokenStore.consumeRefresh` adapters emit on a
+ * second-use-within-the-window — used by the refresh-grant handler to
+ * audit `refresh_reuse_detected` with branded `TenantId` / `subjectId`
+ * fields rather than parsing strings out of `description`.
+ */
+ | {
+    code: "invalid_grant";
+    description: string;
+    reuseSignal?: {
+        family: string;
+        tenantId: string;
+        subjectId: string;
+    };
+} | {
+    code: "unauthorized_client";
+    description: string;
+} | {
+    code: "unsupported_grant_type";
+    description: string;
+} | {
+    code: "invalid_scope";
+    description: string;
+} | {
+    code: "access_denied";
+    description: string;
+} | {
+    code: "unknown_state";
+    description: string;
+} | {
+    code: "server_error";
+    description: string;
+    cause?: unknown;
+} | {
+    code: "tenant_not_found";
+    description: string;
+    tenantId: string;
+} | {
+    code: "invalid_target";
+    description: string;
+} | {
+    code: "method_not_found";
+    description: string;
+    methodId?: string;
+    methodKind?: string;
+} | {
+    code: "internal_error";
+    description: string;
+    cause?: unknown;
+};
+export type AuthErrorCode = AuthError["code"];
+/** Narrow constructor helpers — keep call sites short and types tight. */
+export declare const authError: {
+    invalidRequest: (description: string, field?: string) => AuthError;
+    invalidClient: (description: string) => AuthError;
+    invalidGrant: (description: string, reuseSignal?: {
+        family: string;
+        tenantId: string;
+        subjectId: string;
+    }) => AuthError;
+    unauthorizedClient: (description: string) => AuthError;
+    unsupportedGrantType: (description: string) => AuthError;
+    invalidScope: (description: string) => AuthError;
+    accessDenied: (description: string) => AuthError;
+    unknownState: (description: string) => AuthError;
+    serverError: (description: string, cause?: unknown) => AuthError;
+    tenantNotFound: (description: string, tenantId: string) => AuthError;
+    methodNotFound: (description: string, refs: {
+        methodId?: string;
+        methodKind?: string;
+    }) => AuthError;
+    invalidTarget: (description: string) => AuthError;
+    internalError: (description: string, cause?: unknown) => AuthError;
+};
+//# sourceMappingURL=error.d.ts.map

package/dist/types/types/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/types/error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE;AACjD;;;;;;GAMG;GACD;IACE,IAAI,EAAE,eAAe,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE;QACZ,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,SAAS,EAAE,MAAM,CAAA;KAClB,CAAA;CACF,GACD;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAI9C;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAGnE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAG/C;IACE,IAAI,EAAE,kBAAkB,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GAID;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAEpE,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,CAAC,CAAA;AAE7C,0EAA0E;AAC1E,eAAO,MAAM,SAAS;kCACU,MAAM,UAAU,MAAM,KAAG,SAAS;iCAKnC,MAAM,KAAG,SAAS;gCAKhC,MAAM,gBACL;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KACpE,SAAS;sCAKsB,MAAM,KAAG,SAAS;wCAIhB,MAAM,KAAG,SAAS;gCAI1B,MAAM,KAAG,SAAS;gCAIlB,MAAM,KAAG,SAAS;gCAIlB,MAAM,KAAG,SAAS;+BAInB,MAAM,UAAU,OAAO,KAAG,SAAS;kCAKhC,MAAM,YAAY,MAAM,KAAG,SAAS;kCAMnD,MAAM,QACb;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,KAC/C,SAAS;iCAMiB,MAAM,KAAG,SAAS;iCAIlB,MAAM,UAAU,OAAO,KAAG,SAAS;CAKjE,CAAA"}

package/dist/types/types/flow.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `FlowRecord` — the single server-side source of truth for an in-flight
+ * authorization. Persisted in `SessionStore` between `/authorize` and the
+ * upstream provider's callback.
+ *
+ * The `state` envelope round-tripped through the upstream provider carries
+ * **only** `{ tenantId, flowId, nonce, kid }`. Sensitive data
+ * (`clientPkce`, `appRedirectUri`, scopes, audience, etc.) lives here and
+ * here only.
+ *
+ * Lifecycle:
+ *   1. Create — at `/authorize`, after schema validation + tenant resolve.
+ *   2. Update — when a method handler returns `{ kind: "challenge",
+ *      saveMethodState }`, the framework merges `saveMethodState` into
+ *      `methodState` and persists **before** sending the upstream redirect
+ *      response.
+ *   3. Consume — on callback, atomically (`consumeFlow`) — single delete-on-read.
+ *   4. Snapshot + dispose — on `success`, the framework snapshots the fields
+ *      needed at `/token` into the auth-code payload; `methodState` is
+ *      dropped.
+ */
+import type { TenantId } from "./tenant";
+export type FlowRecord = {
+    flowId: string;
+    tenantId: TenantId;
+    /** Tenant-local instance id (`MethodConfig.id`), e.g. `"google-workspace"`. */
+    methodId: string;
+    /** Factory kind (`MethodConfig.kind`), e.g. `"google"`. */
+    methodKind: string;
+    /** Relying party's registered client id. */
+    clientId: string;
+    /** Final redirect to the relying party. */
+    appRedirectUri: string;
+    /** Full expected request pathname for this specific flow on callback. */
+    callbackPath: string;
+    /** Expected request host on callback. */
+    callbackHost: string;
+    /** Relying party's `state` param, echoed back at success. */
+    appState: string | null;
+    /** Scopes requested at `/authorize`. */
+    scopes: string[];
+    /**
+     * OAuth 2.1 — `code` only. Implicit (`response_type=token`) is removed; see
+     * plan §"OAuth 2.1 — `code` only".
+     */
+    responseType: "code";
+    audience?: string;
+    /** Standard OIDC prompt values (`none`, `login`, `consent`, …). */
+    prompt?: string[];
+    uiLocales?: string[];
+    /**
+     * Per-flow CSRF nonce stamped into the `state` envelope. Distinct from
+     * `appState`. Compared at callback against the consumed record.
+     */
+    nonce: string;
+    /**
+     * Relying-party → IdP PKCE. The RP generates the verifier and sends the
+     * challenge to `/authorize`. Verified at `/token`.
+     * Required for public clients.
+     */
+    clientPkce?: {
+        challenge: string;
+        method: "S256";
+    };
+    /**
+     * Method-private state — opaque to the framework, typed via the
+     * `AuthMethod<P, S>` generic on the owning method. Examples:
+     *   - OAuth provider:  `{ upstreamPkceVerifier, upstreamState }`
+     *   - OIDC provider:   `{ upstreamPkceVerifier, upstreamNonce }`
+     *   - Passkey:         `{ challenge, allowedCredentialIds }`
+     *   - Password:        typically `null` (no upstream callback)
+     *
+     * Methods do not write this directly; they request a merge via
+     * `MethodResult.challenge.saveMethodState`.
+     */
+    methodState?: unknown;
+    /** User's `requestContext` snapshot, if any. */
+    context?: Record<string, unknown>;
+    createdAt: number;
+    /**
+     * Pre-callback lifetime — covers upstream login, MFA, consent, mobile app
+     * switching, etc. Default 10 minutes. Distinct from the auth-code TTL
+     * (60 s) which covers the post-callback span.
+     */
+    expiresAt: number;
+};
+//# sourceMappingURL=flow.d.ts.map

package/dist/types/types/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../../../src/types/flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAExC,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,QAAQ,CAAA;IAElB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAA;IAChB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAA;IAElB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAA;IACtB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAA;IACpB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAA;IACpB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,wCAAwC;IACxC,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IAElD;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEjC,SAAS,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA"}