@_mustachio/openauth 0.9.2 → 0.10.0

package/dist/types/types/idp.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Public-surface types for `createIdP` — the user-facing options object,
+ * the returned handle, the `success` callback contract, and observation
+ * hook event shapes.
+ */
+import type { AuditLog } from "../ports/audit-log";
+import type { ConfigStore } from "../ports/config-store";
+import type { KeyStore } from "../ports/key-store";
+import type { MethodStore } from "../ports/method-store";
+import type { SessionStore } from "../ports/session-store";
+import type { TokenStore } from "../ports/token-store";
+import type { AuthError } from "./error";
+import type { AnyAuthMethodFactory } from "./method";
+import type { Result } from "./result";
+import type { SubjectClaim, SubjectSchema } from "./subject";
+import type { StateKeyRing, TenantContext, TenantId, ThemeConfig } from "./tenant";
+import type { PickerContext, PickerMethod } from "./picker";
+/**
+ * Input handed to the user's `success` callback. The framework provides
+ * everything needed to map the upstream / credential result into the
+ * issued subject.
+ *
+ * `methodKind` tells you **which provider** produced the result (e.g.
+ * `"google"`); `methodId` tells you **which tenant-local instance** of
+ * that provider was used (e.g. `"google-workspace"` vs
+ * `"google-personal"`). Use `methodKind` for provider-specific branches;
+ * use `methodId` for instance-specific routing.
+ */
+export type SuccessMapInput = {
+    tenant: TenantContext;
+    methodId: string;
+    methodKind: string;
+    /** Upstream system's stable identifier (from `MethodResult.success`). */
+    providerSubject: string;
+    /** Typed per method via the factory's `P` generic at the call site. */
+    properties: unknown;
+    context: Record<string, unknown> | null;
+};
+/**
+ * Optional observation hook payload — fires after the subject claim has
+ * already been minted. **Does not** influence the issued subject; use it
+ * for audit, analytics, side effects only.
+ */
+export type SuccessEvent = SuccessMapInput & {
+    /** The final subject claim that became the JWT `sub`. */
+    claim: SubjectClaim;
+};
+/**
+ * Optional observation hook payload — fires on a failed auth attempt.
+ * Carries enough id information for operators to find the offending flow
+ * / config row without leaking secrets.
+ */
+export type FailureEvent = {
+    tenantId: TenantId | null;
+    clientId: string | null;
+    methodId?: string;
+    methodKind?: string;
+    flowId?: string;
+    error: AuthError;
+};
+/**
+ * Optional hook called at `/token` time, after PKCE has succeeded and
+ * after the `success` callback has produced a `SubjectClaim`, but
+ * **before** the access/refresh response is returned. Use this when you
+ * prefer not to persist upstream tokens in the code payload itself (see
+ * the "alternative split" note in the plan §"Code payload
+ * confidentiality"). If it throws, the IdP responds with OAuth
+ * `server_error` and the token issuance is aborted.
+ */
+export type PersistUpstreamTokens = (input: {
+    tenant: TenantContext;
+    methodId: string;
+    methodKind: string;
+    providerSubject: string;
+    properties: unknown;
+    subjectClaim: SubjectClaim;
+}) => Promise<void>;
+/**
+ * Optional hook called for RFC 8693 token-exchange requests at
+ * `/token`. The host decides whether the authenticated subject can
+ * obtain a token scoped to `request.audience` (a new tenant), and
+ * returns either:
+ *
+ *   - the `SubjectClaim` representing the subject's identity at the
+ *     new audience (often the same shape but different `properties` —
+ *     e.g. a different role), or
+ *   - an `AuthError` (typically `authError.invalidTarget(...)` if the
+ *     subject can't access that audience).
+ *
+ * If this hook is not supplied, token-exchange requests are rejected
+ * with `unsupported_grant_type`. This is the graceful-degradation
+ * default — the grant simply isn't enabled.
+ *
+ * The library does NOT inspect the audience string; it's an opaque
+ * `TenantId` that the host's `ConfigStore` must be able to resolve.
+ */
+export type ExchangeAudience = (currentClaim: SubjectClaim, request: {
+    /** The target tenant id (RFC 8693 `audience`). Opaque to the library. */
+    audience: string;
+    /** Subset of subject_token scopes the caller asked for. */
+    requestedScopes?: string[];
+    /** The authenticated client doing the exchange. */
+    clientId: string;
+    /** Tenant the subject_token came from. */
+    fromTenantId: string;
+}) => Promise<SubjectClaim | AuthError>;
+/**
+ * Optional override for the default provider picker shown when an
+ * `/authorize` request has multiple enabled methods and no `method_id`.
+ *
+ * The library ships a minimal styled default (see `src/ui/picker.ts`);
+ * supply this to render a fully custom selection screen. The returned
+ * `Response` is sent as-is; the framework applies `cache-control: no-store`
+ * unless the response already sets a `Cache-Control` header.
+ */
+export type RenderPicker = (methods: PickerMethod[], ctx: PickerContext) => Response | Promise<Response>;
+export type IdPOptions = {
+    /**
+     * Tenant resolution for the first request in a flow. Not consulted on
+     * callbacks — the framework recovers `(tenantId, flowId)` from the
+     * MAC-bound state envelope, partitioned host, or `flowId`-in-URI
+     * mechanism (see plan §"Tenant Recovery Across Redirects").
+     */
+    resolveTenant: (req: Request) => Promise<Result<TenantId, AuthError>>;
+    /** Opt-in for partitioned callback hosts (recovery mechanism #2). */
+    callbackHostFor?: (tenantId: TenantId) => string;
+    /**
+     * HMAC-SHA-256 key ring used to MAC the minimal state envelope. The
+     * envelope carries only `{ tenantId, flowId, nonce, kid }` — never
+     * sensitive data — so a global ring is acceptable and necessary
+     * (tenant config can't be loaded until we know the tenant). Operators
+     * who prefer storing the ring inside `KeyStore` can use the
+     * `loadStateKeyRingFromKeyStore` helper.
+     *
+     * REQUIRED.
+     */
+    stateKeys: StateKeyRing;
+    configStore: ConfigStore;
+    tokenStore: TokenStore;
+    keyStore: KeyStore;
+    /** Required: flow records need strong CAS / atomic delete-on-read. */
+    sessionStore: SessionStore;
+    /** Optional but recommended for any production deployment. */
+    auditLog?: AuditLog;
+    /** Optional — falls back to `ConfigStore` for `MethodConfig` lookups. */
+    methodStore?: MethodStore;
+    /** Issuer URL. Function form lets multi-tenant deployments derive it per request. */
+    issuerUrl: string | ((req: Request) => string);
+    /**
+     * Available method factories. **The KEY of this record MUST equal
+     * `factory.kind`.** `createIdP` throws on construction if any key
+     * disagrees with its factory's declared `kind`, with a list of
+     * offending keys in the error message.
+     */
+    methods: Record<string, AnyAuthMethodFactory>;
+    subjects: SubjectSchema;
+    /**
+     * REQUIRED. Maps method result → issued subject. Runs at `/token` time,
+     * after PKCE check, with the same conceptual role as the existing
+     * `auth.success` callback in `issuer.ts`.
+     */
+    success: (input: SuccessMapInput) => Promise<SubjectClaim>;
+    theme?: ThemeConfig;
+    hooks?: {
+        /** Observation only — does NOT influence the subject. */
+        onSuccess?: (event: SuccessEvent) => Promise<void>;
+        onFailure?: (event: FailureEvent) => Promise<void>;
+    };
+    /**
+     * Optional escape hatch for high-sensitivity deployments — see the
+     * `PersistUpstreamTokens` type doc.
+     */
+    persistUpstreamTokens?: PersistUpstreamTokens;
+    /**
+     * Optional RFC 8693 token-exchange hook. If absent, exchange
+     * requests at `/token` return `unsupported_grant_type`. See the
+     * `ExchangeAudience` type doc for the contract.
+     */
+    exchangeAudience?: ExchangeAudience;
+    /**
+     * Optional override for the default provider picker. See `RenderPicker`.
+     */
+    renderPicker?: RenderPicker;
+    /**
+     * Optional hook that builds the `TenantContext.request.custom` blob for
+     * each request the framework processes (the initial `/authorize`, the
+     * `/cb/*` callback, and any subsequent direct token endpoint hit).
+     *
+     * The returned record flows through to methods' `MethodContext`, to the
+     * `success` callback's `SuccessMapInput.context`, and to authorize-time
+     * `FlowRecord.context` (which is then re-presented on the
+     * `/cb/*` side as the flow proceeds). Typical contents: a request id,
+     * decoded JWT claims from a host edge layer, mTLS cert info, geo
+     * hints — anything per-request the host wants methods or `success` to
+     * see.
+     *
+     * Without this hook, `tenant.request.custom` is `{}` and
+     * `SuccessMapInput.context` is `null`. There is no semantic difference
+     * between an absent hook and one that returns `{}`.
+     */
+    buildCustomContext?: (req: Request) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Optional override for the framework's `Set-Cookie` defaults.
+     *
+     * Production deployments should rely on the built-in defaults
+     * (`secure: true`, no domain, `path: "/"`). Local development over plain
+     * HTTP — where Chrome rejects `Secure` cookies — can pass
+     * `cookies: { secure: false }` so the `idp.flow` / `auth.*` cookies
+     * round-trip on `localhost`. `domain` and `path` are passed through to
+     * every framework-issued cookie that doesn't set them itself.
+     */
+    cookies?: {
+        secure?: boolean;
+        domain?: string;
+        path?: string;
+    };
+};
+/**
+ * The returned IdP handle. `handle(req)` is the single fetch-style
+ * entrypoint suitable for `export default { fetch: idp.handle }` on
+ * Cloudflare Workers; the per-endpoint primitives are exposed for
+ * embedding inside a larger app (e.g. mounting alongside admin routes).
+ */
+export type IdP = {
+    handle: (req: Request) => Promise<Response>;
+    authorize: (req: Request) => Promise<Response>;
+    token: (req: Request) => Promise<Response>;
+    userinfo: (req: Request) => Promise<Response>;
+    jwks: (req: Request) => Promise<Response>;
+    discovery: (req: Request) => Promise<Response>;
+    revoke: (req: Request) => Promise<Response>;
+    introspect: (req: Request) => Promise<Response>;
+};
+//# sourceMappingURL=idp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"idp.d.ts","sourceRoot":"","sources":["../../../src/types/idp.ts"],"names":[],"mappings":"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"}

package/dist/types/types/method.d.ts

@@ -0,0 +1,256 @@
+/**
+ * `AuthMethod` — the core pluggable authentication abstraction.
+ *
+ * AD2: methods are **data + handler functions**, not framework modules. They
+ * depend on Web Fetch `Request`/`Response` (Web standards available on every
+ * runtime) and on a small `MethodContext` of plain data. The full allowed
+ * import set for files under `src/methods/` is `src/types/`,
+ * `src/domain/crypto`, `src/ui/forms`, sibling `src/methods/*`, and
+ * method-specific third-party libraries (e.g. `zod`,
+ * `@simplewebauthn/server`); methods MUST NOT import from `src/http/`,
+ * `src/adapters/`, or `src/ports/`, and never from Hono or any other HTTP
+ * framework. This `types/method.ts` file in particular is enforced
+ * framework-import-free by CI lint. See ARCHITECTURE.md §"Methods plug
+ * in alongside this stack" for the full contract.
+ *
+ * Cookies and other policy-sensitive response headers are returned as data
+ * (`SetCookie[]`, `CachePolicy`) and applied to the final `Response` by the
+ * HTTP layer. The HTTP layer also strips a fixed allowlist-violating set of
+ * headers from method-returned `Response` instances (`Set-Cookie`, security
+ * headers, `Cache-Control`) so methods cannot bypass framework policy. See
+ * `ARCHITECTURE.md` §"Response sanitization".
+ */
+import type { v1 } from "@standard-schema/spec";
+import type { AuthError } from "./error";
+import type { FlowRecord } from "./flow";
+import type { Result } from "./result";
+import type { MethodType, TenantContext, TenantId } from "./tenant";
+/**
+ * A built, ready-to-dispatch auth method instance for a particular tenant.
+ *
+ * Generics:
+ *   - `P`: properties type emitted to the user's `success` callback on a
+ *     successful authentication. Typed per method.
+ *   - `S`: method-private state stashed in `FlowRecord.methodState`. Opaque
+ *     to the framework; the method reads and writes it through
+ *     `MethodContext.methodState` and `MethodResult.challenge.saveMethodState`.
+ */
+export type AuthMethod<P = unknown, S = unknown> = {
+    /**
+     * Tenant-local instance id. Populated by the factory from
+     * `MethodConfig.id`. The framework dispatches URL routes by this value.
+     */
+    id: string;
+    /**
+     * Factory kind. Populated by the factory from `MethodConfig.kind`. Used to
+     * tell the user's `success` callback which provider produced the result.
+     */
+    kind: string;
+    type: MethodType;
+    /**
+     * Routes the method declares. Key format: `"GET /authorize"`,
+     * `"POST /callback"`, etc. The HTTP layer mounts these under
+     * `/<AuthMethod.id>/*` (tenant-local instance id, so two instances of the
+     * same factory get distinct URL spaces).
+     */
+    routes: Record<string, MethodHandler<P, S>>;
+    /**
+     * Token-exchange function for the `/token` endpoint when the method
+     * participates in client-credentials-style flows (e.g. `m2m`). Most
+     * redirect-based methods do not set this.
+     */
+    client?: ClientFn<P>;
+};
+export type MethodHandler<P, S> = (ctx: MethodContext<S>) => Promise<MethodResult<P, S>>;
+/**
+ * Per-request context handed to a method handler.
+ *
+ * Methods **do not** receive raw `MethodConfig.config`. The factory captured
+ * the validated config via closure in `build`, so the handler only sees
+ * request-scoped data here.
+ *
+ * `cookies` is `ReadonlyMap` because methods don't get to mutate the
+ * incoming cookie jar — they return `SetCookie[]` instructions and the
+ * framework applies them.
+ */
+export type MethodContext<S = unknown> = {
+    /** The raw Web Fetch `Request`. Web standard, not Hono `Context`. */
+    request: Request;
+    /** Path within the method's mount, e.g. `"/callback"` (without the `/<id>` prefix). */
+    subPath: string;
+    tenant: TenantContext;
+    /** `null` while `/authorize` is being initiated; populated on callback. */
+    flow: FlowRecord | null;
+    /**
+     * Shortcut to `flow?.methodState`, narrowed to this method's `S` generic.
+     * `null` when there is no flow yet or no state has been written.
+     */
+    methodState: S | null;
+    /** Parsed cookies from the incoming `Request`. Read-only. */
+    cookies: ReadonlyMap<string, string>;
+    /**
+     * Framework-supplied dispatch data. Populated for the `GET /authorize`
+     * initiation so the method can build an upstream redirect carrying the
+     * framework-minted state envelope; `null` for callback handlers (the
+     * framework has already verified `state` and the flow record by then,
+     * and the relevant data is on `flow`).
+     */
+    dispatch: MethodDispatchData | null;
+};
+/** Framework-supplied data available to the method at `/authorize` time. */
+export type MethodDispatchData = {
+    /**
+     * The MAC-signed state envelope the method must include in any upstream
+     * redirect. Opaque to the method.
+     */
+    state: string;
+    /**
+     * Fully qualified callback URL the upstream provider should redirect to.
+     * Methods include this as `redirect_uri` (OAuth) or its equivalent.
+     */
+    callbackUrl: string;
+    /** The issuer URL of this IdP. Methods may include in upstream OIDC requests. */
+    issuerUrl: string;
+};
+/**
+ * Discriminated union returned by a `MethodHandler`. The HTTP layer applies
+ * the result: rendering the challenge response, kicking off token issuance
+ * on success, or surfacing the error.
+ */
+export type MethodResult<P = unknown, S = unknown> = 
+/**
+ * Render UI / redirect to upstream / otherwise pause the flow waiting for
+ * the user agent. `setCookies` is applied via the framework's serializer
+ * (which enforces `Secure`, `SameSite`, `HttpOnly` defaults).
+ * `saveMethodState` is merged into `FlowRecord.methodState` and persisted
+ * **before** the response is sent — the user agent never sees the
+ * upstream redirect until the upstream verifier / nonce / state is
+ * durably saved.
+ */
+{
+    kind: "challenge";
+    /** Body + non-policy headers. Policy-sensitive headers are stripped. */
+    response: Response;
+    setCookies?: SetCookie[];
+    saveMethodState?: S;
+    /** Serialized into a `Cache-Control` header by the framework. */
+    cache?: CachePolicy;
+}
+/**
+ * Authentication succeeded. The HTTP layer hands `providerSubject` +
+ * `properties` to the user's `IdPOptions.success` callback to mint the
+ * final `SubjectClaim`. Methods never construct the final subject.
+ */
+ | {
+    kind: "success";
+    /** Upstream system's stable identifier for the authenticated principal. */
+    providerSubject: string;
+    properties: P;
+    setCookies?: SetCookie[];
+}
+/** User refused / failed auth in a non-error way (e.g. consent declined). */
+ | {
+    kind: "denied";
+    reason: string;
+    setCookies?: SetCookie[];
+}
+/** Method hit an error. The HTTP layer maps to a standards-compliant response. */
+ | {
+    kind: "error";
+    error: AuthError;
+};
+/**
+ * Cache policy for `MethodResult.challenge`. Methods do **not** set
+ * `Cache-Control` directly — the framework strips that header from any
+ * method-returned `Response`. Opt in to caching via this typed field; the
+ * framework serializes it.
+ */
+export type CachePolicy = {
+    /** Seconds. `0` ≡ `no-store`. Default for auth UI. */
+    maxAge?: number;
+    /** Shared (CDN) cache TTL. */
+    sMaxAge?: number;
+    /** Adds `Cache-Control: private`. */
+    isPrivate?: boolean;
+    /** For static assets only. */
+    immutable?: boolean;
+};
+/**
+ * Cookie instruction returned from a method, applied by the framework's
+ * cookie serializer. Defaults enforced: `Secure` in production, `SameSite`
+ * defaults to `Lax`, `HttpOnly` defaults to true for any cookie name in the
+ * framework's reserved namespace (`auth.*` / `idp.*`).
+ */
+export type SetCookie = {
+    name: string;
+    /** `null` clears the cookie (`Max-Age=0`). */
+    value: string | null;
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "lax" | "strict" | "none";
+};
+/**
+ * Token-exchange function for methods that participate in `/token`
+ * (currently just `m2m`). Returns the same `P` properties shape as a
+ * `MethodResult.success`.
+ */
+export type ClientFn<P> = (input: {
+    clientID: string;
+    clientSecret: string;
+    params: Record<string, string>;
+}) => Promise<Result<P, AuthError>>;
+/**
+ * Factory that turns a tenant's per-method config into an `AuthMethod`.
+ *
+ * The factory owns config validation. The framework validates
+ * `MethodConfig.config` against `configSchema` before calling `build`;
+ * methods never observe `Record<string, unknown>` at runtime.
+ *
+ * `build` may be async (e.g. to fetch an OIDC discovery doc / JWKS). The
+ * result is cached per `(tenantId, MethodConfig.id)` — TTL matches the
+ * `ConfigStore` cache TTL; invalidation fires when tenant config changes.
+ *
+ * The framework verifies the returned `AuthMethod.id` and `AuthMethod.kind`
+ * match the `input.id` / `input.kind` passed into `build`. Mismatch fails
+ * the load with audit `factory_id_mismatch`.
+ */
+export type AnyAuthMethodFactory = AuthMethodFactory<any, // P — properties emitted to success callback
+any, // S — method-private state
+any>;
+export type AuthMethodFactory<P = unknown, S = unknown, Cfg = unknown> = {
+    /** Matches `MethodConfig.kind`. Multiple `MethodConfig` rows may share the same `kind`. */
+    kind: string;
+    /**
+     * Standard Schema for the tenant-supplied config blob. The framework
+     * runs this after `ConfigStore` returns a tenant's `MethodConfig.config`
+     * and rejects loads that don't validate (audit + log). The validated
+     * value is threaded into `build`.
+     *
+     * Any validation library implementing [Standard Schema v1] satisfies
+     * this contract — Zod 3.24+, Valibot 1.0+, Arktype 2.0+, Effect Schema,
+     * etc. This decouples the library from any one validator's version
+     * choices.
+     *
+     * [Standard Schema v1]: https://github.com/standard-schema/standard-schema
+     */
+    configSchema: v1.StandardSchema<unknown, Cfg>;
+    /**
+     * Build a concrete `AuthMethod` from validated config plus the binding
+     * context. The factory **must** set `AuthMethod.id` to `input.id` and
+     * `AuthMethod.kind` to `input.kind` — the framework verifies and audits
+     * on mismatch (`factory_id_mismatch`).
+     */
+    build: (input: {
+        /** `MethodConfig.id` — tenant-local instance id, becomes `AuthMethod.id`. */
+        id: string;
+        /** `MethodConfig.kind` — factory id, becomes `AuthMethod.kind`. */
+        kind: string;
+        tenantId: TenantId;
+        /** Validated against `configSchema`. */
+        config: Cfg;
+    }) => Promise<AuthMethod<P, S>>;
+};
+//# sourceMappingURL=method.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../../../src/types/method.ts"],"names":[],"mappings":"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"}

package/dist/types/types/picker.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Public-surface types for the default provider picker and any
+ * host-supplied override (`IdPOptions.renderPicker`). Kept under `types/`
+ * — separate from `ui/picker.ts` which holds the default renderer — so
+ * the public-API layer doesn't depend on the UI implementation file.
+ */
+/** Minimal shape of a method as seen by the picker. */
+export type PickerMethod = {
+    /** Tenant-local id (e.g. "google-workspace"). Goes into method_id. */
+    id: string;
+    /** Factory kind (e.g. "google"). Identifies the provider family. */
+    kind: string;
+    /** "redirect" for upstream OAuth/OIDC, "credential" for password/code/passkey. */
+    type: string;
+    /** Optional human-readable label provided by tenant config. */
+    displayName?: string;
+};
+/** Query params propagated into each picker option's link. */
+export type PickerContext = {
+    clientId: string;
+    redirectUri: string;
+    state?: string | null;
+    scope?: string | null;
+    nonce?: string | null;
+    codeChallenge?: string | null;
+    codeChallengeMethod?: string | null;
+    audience?: string | null;
+    prompt?: string | null;
+    uiLocales?: string | null;
+};
+//# sourceMappingURL=picker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"picker.d.ts","sourceRoot":"","sources":["../../../src/types/picker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG;IACzB,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAA;IACV,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B,CAAA"}

package/dist/types/types/result.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Result<T, E> — explicit success / failure encoding used throughout the domain.
+ *
+ * Domain functions return `Result` instead of throwing. The HTTP layer is the
+ * one place that converts `AuthError` into an HTTP response. Keeping the domain
+ * throw-free makes composition (chaining validators, branching on error code)
+ * straightforward and avoids hidden control flow.
+ *
+ * AD5 in `docs/plans/claude/idp-rebuild-plan.md`.
+ */
+import type { AuthError } from "./error";
+export type Result<T, E = AuthError> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+export declare const ok: <T>(value: T) => Result<T, never>;
+export declare const err: <E>(error: E) => Result<never, E>;
+export declare const isOk: <T, E>(r: Result<T, E>) => r is {
+    ok: true;
+    value: T;
+};
+export declare const isErr: <T, E>(r: Result<T, E>) => r is {
+    ok: false;
+    error: E;
+};
+//# sourceMappingURL=result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/types/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAExC,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,IAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAA;AAE3B,eAAO,MAAM,EAAE,GAAI,CAAC,SAAS,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAA0B,CAAA;AAC1E,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,CAAC,KAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAA2B,CAAA;AAE5E,eAAO,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CACvD,CAAA;AACf,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAC,IAAI;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CACxD,CAAA"}

package/dist/types/types/subject.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Subject — the typed principal the IdP issues at the end of an auth flow.
+ *
+ * Per AD4 / plan §"Subject", Zod is the canonical schema library. The
+ * subject schema type is library-agnostic at the boundary (any schema that
+ * implements the [Standard Schema v1] spec — including Zod 3.24+, Valibot,
+ * and Arktype) so existing consumers can migrate from Valibot/Arktype
+ * without rewriting subject definitions.
+ *
+ * [Standard Schema v1]: https://github.com/standard-schema/standard-schema
+ */
+import type { v1 } from "@standard-schema/spec";
+/**
+ * Map of subject-type id → schema for that subject's `properties`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod"
+ *
+ * const subjects: SubjectSchema = {
+ *   user:  z.object({ userId: z.string(), email: z.string().email() }),
+ *   admin: z.object({ adminId: z.string(), roles: z.array(z.string()) }),
+ * }
+ * ```
+ */
+export type SubjectSchema = Record<string, v1.StandardSchema>;
+/**
+ * Helper that infers the discriminated-union `{ type, properties }` shape
+ * from a `SubjectSchema`. Used to type the IdP's `success` callback return
+ * and the access-token `claim` payload.
+ */
+export type SubjectPayload<T extends SubjectSchema> = {
+    [type in keyof T & string]: {
+        type: type;
+        properties: v1.InferOutput<T[type]>;
+    };
+}[keyof T & string];
+/**
+ * Generic typed-subject claim — what the user's `IdPOptions.success`
+ * callback returns and what is inlined as `claim` on the access token.
+ *
+ * Domain / port signatures keep the generic open (`SubjectClaim`) so the
+ * framework doesn't need to know each consumer's subject schema. Concrete
+ * call sites narrow `T extends SubjectSchema` for type safety.
+ */
+export type SubjectClaim<T extends SubjectSchema = SubjectSchema> = SubjectPayload<T>;
+//# sourceMappingURL=subject.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../../src/types/subject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,uBAAuB,CAAA;AAE/C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,CAAA;AAE7D;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,aAAa,IAAI;KACnD,IAAI,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG;QAC1B,IAAI,EAAE,IAAI,CAAA;QACV,UAAU,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;KACpC;CACF,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAA;AAEnB;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,IAC9D,cAAc,CAAC,CAAC,CAAC,CAAA"}