@_mustachio/openauth 0.9.2 → 0.10.0

package/src/types/idp.ts

@@ -0,0 +1,269 @@
+/**
+ * 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>
+}

package/src/types/method.ts

@@ -0,0 +1,270 @@
+/**
+ * `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`.
+ */
+// `AnyAuthMethodFactory` is the variance-permissive form used by
+// `IdPOptions.methods` and `MethodCache.factories`. Each entry in such a
+// map may be a `AuthMethodFactory<P, S, Cfg>` with concrete generics —
+// the `any` defaults keep the map type assignable without losing strict
+// typing inside individual factories.
+export type AnyAuthMethodFactory = AuthMethodFactory<
+  any, // P — properties emitted to success callback
+  any, // S — method-private state
+  any // Cfg — tenant-supplied config (validated by configSchema)
+>
+
+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>>
+}

package/src/types/picker.ts

@@ -0,0 +1,32 @@
+/**
+ * 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
+}

package/src/types/result.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 const ok = <T>(value: T): Result<T, never> => ({ ok: true, value })
+export const err = <E>(error: E): Result<never, E> => ({ ok: false, error })
+
+export const isOk = <T, E>(r: Result<T, E>): r is { ok: true; value: T } =>
+  r.ok === true
+export const isErr = <T, E>(r: Result<T, E>): r is { ok: false; error: E } =>
+  r.ok === false

package/src/types/subject.ts

@@ -0,0 +1,50 @@
+/**
+ * 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>