@_mustachio/openauth 0.13.2 → 0.14.0

package/src/domain/method-dispatch.ts

@@ -33,6 +33,11 @@ export type DispatchInput = {
   flow: FlowRecord | null
   cookies: ReadonlyMap<string, string>
   sessionStore: SessionStore
+  /**
+   * Issuer URL of this IdP. Always required — unlike `dispatch`, methods
+   * need it on every route to emit mount-prefixed URLs of their own.
+   */
+  issuerUrl: string
   /** Populated at `GET /authorize`; null on callbacks. */
   dispatch: MethodDispatchData | null
 }
@@ -57,6 +62,7 @@ export async function dispatchMethod(
 
   const ctx: MethodContext<unknown> = {
     request: input.request,
+    issuerUrl: input.issuerUrl,
     subPath: input.subPath,
     tenant: input.tenant,
     flow: input.flow,

package/src/domain/method-route.ts

@@ -79,6 +79,12 @@ export type HandleMethodRouteInput = {
   /** flowId from the `idp.flow` cookie. */
   flowId: string
   cookies: ReadonlyMap<string, string>
+  /**
+   * Issuer URL — passed to the method so it can emit mount-prefixed URLs
+   * (a re-rendered form action, say). The inbound request URL cannot
+   * supply this: a proxy has already stripped the mount prefix from it.
+   */
+  issuerUrl: string
 }
 
 export type HandleMethodRouteDeps = {
@@ -139,6 +145,7 @@ export async function handleMethodRoute(
     flow,
     cookies: input.cookies,
     sessionStore: deps.sessionStore,
+    issuerUrl: input.issuerUrl,
     dispatch: null,
   })
   if (isErr(dispatched)) return err(dispatched.error)
@@ -185,6 +192,16 @@ async function translate(
         { keyStore: deps.keyStore, tokenStore: deps.tokenStore },
       )
       if (isErr(saved)) return err(saved.error)
+      await safeAudit(deps, {
+        kind: "authorize_succeeded",
+        tenantId: final.tenantId,
+        clientId: final.clientId,
+        methodId: final.methodId,
+        methodKind: final.methodKind,
+        flowId: final.flowId,
+        providerSubject: result.providerSubject,
+        timestamp: now,
+      })
       return ok({
         kind: "issue-code",
         code,
@@ -295,6 +312,7 @@ export async function handlePublicMethodRoute(
     flow: null,
     cookies: new Map(),
     sessionStore: deps.sessionStore,
+    issuerUrl: input.dispatch.issuerUrl,
     dispatch: input.dispatch,
   })
   if (isErr(dispatched)) return err(dispatched.error)

package/src/domain/mount.ts

@@ -0,0 +1,113 @@
+/**
+ * Mount prefix — where this IdP sits under its origin.
+ *
+ * The library serves its routes at its own root (`/authorize`, `/m/*`,
+ * `/cb/*`); a deployment may sit behind a reverse proxy that strips a path
+ * prefix before forwarding. Routing is unaffected — but every URL the
+ * library *emits* (form actions, upstream `redirect_uri`s, SAML metadata)
+ * is consumed on the public side of that proxy and must carry the prefix.
+ *
+ * `issuerUrl` already carries it. It is the single source of truth: there
+ * is deliberately no `basePath` option, because two sources could disagree
+ * and the `iss` claim would then contradict the URLs we hand out.
+ *
+ * All emitted-URL construction goes through this module. `metadata.test.ts`
+ * is an anti-drift test asserting the SAML entityID/ACS equal what
+ * `buildAuthnRequestRedirect` derives; funnelling every site through
+ * `callbackTarget` is what keeps that true.
+ */
+
+/**
+ * The normalised mount prefix of `issuerUrl`: `""` for a root-mounted
+ * deployment, otherwise a leading-slash, no-trailing-slash path.
+ *
+ *     https://example.com        -> ""
+ *     https://example.com/       -> ""
+ *     https://example.com/idp    -> "/idp"
+ *     https://example.com/idp/   -> "/idp"
+ *     https://example.com//idp// -> "/idp"
+ *
+ * A root-mounted issuer must yield `""` and not `"/"`, so that existing
+ * deployments emit byte-identical URLs to before this existed.
+ *
+ * An unparseable `issuerUrl` yields `""` rather than throwing: emitting a
+ * root-relative URL degrades to the pre-existing behaviour, whereas
+ * throwing would turn a misconfiguration into a 500 from inside form
+ * rendering. Misconfiguration still fails loudly at `/authorize`, which
+ * parses `issuerUrl` for the callback host.
+ */
+export function mountPath(issuerUrl: string): string {
+  let pathname: string
+  try {
+    pathname = new URL(issuerUrl).pathname
+  } catch {
+    return ""
+  }
+  const segments = pathname.split("/").filter(Boolean)
+  return segments.length === 0 ? "" : `/${segments.join("/")}`
+}
+
+/**
+ * A path-absolute URL for one of the library's own routes, carrying the
+ * deployment's mount prefix. `path` is the route as the service itself
+ * serves it, with a leading slash.
+ *
+ *     mountedPath("https://x/idp", "/m/code/send") -> "/idp/m/code/send"
+ *     mountedPath("https://x",     "/m/code/send") -> "/m/code/send"
+ */
+export function mountedPath(issuerUrl: string, path: string): string {
+  return `${mountPath(issuerUrl)}${path}`
+}
+
+/**
+ * Where a method's callback lives, in the two forms the framework needs.
+ *
+ * The distinction matters under a path-mounted deployment and is the
+ * reason these are derived together rather than one from the other:
+ * `url` is public (registered with upstream providers, advertised in SAML
+ * metadata) and carries the mount prefix, while `path` is what the
+ * inbound request actually looks like after the proxy has stripped that
+ * prefix, and so must not.
+ */
+export type CallbackTarget = {
+  /** Public, fully-qualified callback URL. Carries the mount prefix. */
+  url: string
+  /** Host the callback is expected to arrive on. */
+  host: string
+  /**
+   * Expected pathname of the inbound request — this service's own route,
+   * *without* the mount prefix, because the proxy has already stripped it.
+   * Persisted on `FlowRecord.callbackPath` and matched in `domain/callback.ts`.
+   */
+  path: string
+}
+
+/**
+ * The single derivation point for a method's callback URL.
+ *
+ * `callbackHost` is the optional per-tenant override from
+ * `IdPOptions.callbackHostFor`. **The issuer's mount prefix applies even
+ * when that override is in effect.** `callbackHostFor` exists to partition
+ * callbacks across hostnames so a tenant is recoverable from the `Host`
+ * header before the state envelope is verified (tenant-recovery mechanism
+ * #2) — it varies the authority of the *same* deployment, not the
+ * deployment itself. Those hosts are served by this service behind the
+ * same proxy, so they share its mount. A deployment needing partitioned
+ * hosts mounted differently from the issuer is describing two mounts,
+ * which one `issuerUrl` cannot express and a second option must not be
+ * introduced to paper over.
+ */
+export function callbackTarget(input: {
+  issuerUrl: string
+  methodId: string
+  callbackHost?: string | undefined
+}): CallbackTarget {
+  const issuer = new URL(input.issuerUrl)
+  const host = input.callbackHost ?? issuer.host
+  const path = `/cb/${input.methodId}`
+  return {
+    host,
+    path,
+    url: `${issuer.protocol}//${host}${mountPath(input.issuerUrl)}${path}`,
+  }
+}

package/src/domain/refresh.ts

@@ -57,6 +57,26 @@ export type RefreshTokensDeps = {
   customScopeClaims?: Record<string, ReadonlyArray<string>>
 }
 
+/**
+ * Requested scopes must be a subset of what the grant carries (RFC 6749
+ * §6). Returns the error rather than throwing so both call sites -- the
+ * pre-consume gate and the post-consume re-check -- read identically.
+ */
+function validateRequestedScopes(
+  requested: string | undefined,
+  granted: string[],
+): AuthError | null {
+  if (!requested) return null
+  for (const s of requested.split(" ").filter(Boolean)) {
+    if (!granted.includes(s)) {
+      return authError.invalidScope(
+        `requested scope "${s}" not granted by original refresh token`,
+      )
+    }
+  }
+  return null
+}
+
 export async function refreshTokens(
   req: RefreshGrantRequest,
   deps: RefreshTokensDeps,
@@ -123,6 +143,16 @@ export async function refreshTokens(
     }
   }
 
+  // Scope narrowing is validated against the *peeked* grant, before the
+  // token is consumed. Same reasoning as the client-auth and DPoP gates
+  // above: a request the grant cannot satisfy must not burn the token,
+  // or a client typo makes the next legitimate refresh look like theft
+  // and can revoke the whole family. `consumeRefresh` stays the
+  // authoritative atomic gate immediately below (TokenStore port:
+  // "callers race peekRefresh then consumeRefresh").
+  const scopeErr = validateRequestedScopes(req.scope, peekedPayload.scopes)
+  if (scopeErr) return err(scopeErr)
+
   const consumed = await deps.tokenStore.consumeRefresh(req.refreshToken, {
     reuseWindowMs: deps.reuseWindowMs,
   })
@@ -147,19 +177,18 @@ export async function refreshTokens(
   }
   const payload = consumed.value
 
-  // Narrow scope if requested (must be subset of original).
+  // Re-check against the consumed payload, which the port declares
+  // authoritative. In practice this cannot diverge from the peeked
+  // grant -- rotation preserves scopes -- so this is defence in depth,
+  // not the user-facing gate; that already ran above without burning.
+  const authoritativeScopeErr = validateRequestedScopes(
+    req.scope,
+    payload.scopes,
+  )
+  if (authoritativeScopeErr) return err(authoritativeScopeErr)
   const requestedScopes = req.scope
     ? req.scope.split(" ").filter(Boolean)
     : payload.scopes
-  for (const s of requestedScopes) {
-    if (!payload.scopes.includes(s)) {
-      return err(
-        authError.invalidScope(
-          `requested scope "${s}" not granted by original refresh token`,
-        ),
-      )
-    }
-  }
 
   const tenant: TenantContext = {
     id: payload.tenantId,

package/src/domain/register.ts

@@ -136,17 +136,36 @@ export async function registerNewClient(
   const hookResult = await deps.registerClient({
     tenant,
     request,
+    client: clientConfig,
+    ...(secret !== undefined ? { secret } : {}),
   })
-  // The hook may either:
-  //  - persist `clientConfig` as-is (most common) and return it,
-  //  - synthesize its own (host-owned id generation, custom scopes) and
-  //    return that — in which case the secret we minted is moot.
-  // We trust the hook's returned client + secret as authoritative.
-  void clientConfig
-
   if (isErr(hookResult)) return err(hookResult.error)
+
+  // The host returns what it actually persisted — normally `clientConfig`
+  // unchanged, sometimes adjusted (narrowed scopes, host-owned id). That
+  // return is authoritative; the framework does not second-guess it.
   const persisted = hookResult.value.client
-  const persistedSecret = hookResult.value.secret
+  // The plaintext may only be reused when the host persisted *our* hash;
+  // if it substituted its own, our secret would not verify and the RP
+  // would receive a credential that silently never works.
+  const keptOurSecret =
+    persisted.type === "confidential" &&
+    clientConfig.type === "confidential" &&
+    persisted.secretHash === clientConfig.secretHash
+  const persistedSecret =
+    hookResult.value.secret ?? (keptOurSecret ? secret : undefined)
+
+  // RFC 7591 §3.2.1 — a confidential client must leave registration with
+  // a usable secret. Better to fail loudly than to hand back a client
+  // that cannot authenticate.
+  if (persisted.type === "confidential" && persistedSecret === undefined) {
+    return err(
+      authError.serverError(
+        "registerClient persisted a confidential client with a substituted " +
+          "secretHash but returned no matching plaintext secret",
+      ),
+    )
+  }
 
   const issuedAt = Math.floor(deps.clock() / 1000)
   return ok({

package/src/domain/state-envelope.ts

@@ -140,3 +140,43 @@ function isEnvelopeShape(value: unknown): value is EnvelopeShape {
     typeof v.kid === "string"
   )
 }
+
+/**
+ * Pull the MAC state envelope off an inbound callback request.
+ *
+ * The envelope normally rides `?state=` on the upstream redirect.
+ * POST-binding callbacks carry it in the form body instead: OAuth
+ * `response_mode=form_post` uses `state`, SAML's HTTP-POST binding uses
+ * `RelayState`. Read the query first (cheap, the common case) and fall
+ * back to a **cloned** body read so the downstream method handler still
+ * gets an unconsumed request body (it needs it for `code` /
+ * `SAMLResponse`).
+ *
+ * Any body-parse failure degrades to "no state" — identical to the
+ * behaviour when the query param is simply absent.
+ *
+ * **This is the single extraction point**, shared by the tenant
+ * middleware and the callback domain. They ran near-identical copies
+ * until 0.14.0, and the middleware copy — which runs *first* — read only
+ * `state`. SP-initiated SAML callbacks therefore fell through to
+ * `resolveTenant`, breaking the documented guarantee that callbacks
+ * recover the tenant without it. Keep exactly one of these.
+ */
+export async function extractCallbackState(
+  req: Request,
+): Promise<string | null> {
+  const fromQuery = new URL(req.url).searchParams.get("state")
+  if (fromQuery) return fromQuery
+  if (req.method !== "POST") return null
+  const ct = req.headers.get("content-type") ?? ""
+  if (!ct.toLowerCase().includes("application/x-www-form-urlencoded")) {
+    return null
+  }
+  try {
+    const form = new URLSearchParams(await req.clone().text())
+    const v = form.get("state") ?? form.get("RelayState")
+    return v && v.length > 0 ? v : null
+  } catch {
+    return null
+  }
+}

package/src/domain/subject.ts

@@ -0,0 +1,103 @@
+/**
+ * Subject-claim validation at issuance.
+ *
+ * `IdPOptions.subjects` is a required option, and until 0.14.0 nothing on
+ * the server read it: `createIdP` accepted the schema and signed whatever
+ * `success()` returned. Two things went wrong as a result.
+ *
+ * First, the failure surfaced in the wrong place. `client.verify()` does
+ * validate against the same schema, so a malformed claim was caught by the
+ * relying party — after the token had been signed, written into the refresh
+ * payload, and handed to anything else holding it. Validating here turns a
+ * late failure in another service into an immediate local one.
+ *
+ * Second, the types were unsound. `SubjectPayload` declares
+ * `properties: v1.InferOutput<T[type]>` — the schema's *parsed output* —
+ * but with no parse anywhere the runtime value was the raw input. Any
+ * schema carrying a transform or a default had a declared type that lied.
+ * Returning the validated value is what makes that declaration true, and
+ * it makes the issued token agree with what `client.verify()` will hand
+ * back to the RP.
+ *
+ * Standard Schema keeps this validator spec-neutral (zod, valibot,
+ * arktype) and adds no dependency the public surface didn't already have.
+ */
+import type { AuthError } from "../types/error"
+import { authError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, ok } from "../types/result"
+import type { SubjectClaim, SubjectSchema } from "../types/subject"
+
+/** Why a claim was rejected — enough for an operator, never the values. */
+export type SubjectClaimRejection = {
+  reason: "unknown-type" | "invalid-properties"
+  /** The offending `claim.type`. Host-declared, safe to log. */
+  subjectType: string
+  /** Standard Schema issue path, or the list of declared types. */
+  detail: string
+}
+
+/**
+ * Validate the host's `SubjectClaim` against its own declared schema.
+ *
+ * On success the returned claim carries the **parsed** properties, which
+ * is what gets signed and persisted. On failure the caller emits an
+ * `invalid_subject_claim` audit event and returns a server error: the
+ * host's callback broke its own contract, which is a deployment fault,
+ * not something the relying party did wrong.
+ */
+export async function validateSubjectClaim(
+  subjects: SubjectSchema,
+  claim: SubjectClaim,
+): Promise<
+  Result<SubjectClaim, AuthError & { rejection: SubjectClaimRejection }>
+> {
+  const declared = Object.keys(subjects)
+  const subjectType = typeof claim?.type === "string" ? claim.type : ""
+
+  const schema = subjectType ? subjects[subjectType] : undefined
+  if (!schema) {
+    return err(
+      Object.assign(
+        authError.serverError(
+          `success() returned subject type "${subjectType}", which is not declared in \`subjects\``,
+        ),
+        {
+          rejection: {
+            reason: "unknown-type" as const,
+            subjectType,
+            detail: `declared: ${declared.join(", ") || "(none)"}`,
+          },
+        },
+      ),
+    )
+  }
+
+  const validated = await schema["~standard"].validate(claim.properties)
+  if (validated.issues) {
+    // Paths only — the values themselves may be personal data.
+    const detail =
+      validated.issues
+        .map((i) => (i.path ?? []).map(String).join(".") || "(root)")
+        .join(", ") || "(root)"
+    return err(
+      Object.assign(
+        authError.serverError(
+          `success() returned properties that violate the "${subjectType}" schema`,
+        ),
+        {
+          rejection: {
+            reason: "invalid-properties" as const,
+            subjectType,
+            detail,
+          },
+        },
+      ),
+    )
+  }
+
+  return ok({
+    type: subjectType,
+    properties: validated.value,
+  } as SubjectClaim)
+}

package/src/domain/token.ts

@@ -27,7 +27,7 @@ import { authError } from "../types/error"
 import type { PersistUpstreamTokens, SuccessMapInput } from "../types/idp"
 import type { Result } from "../types/result"
 import { err, isErr, ok } from "../types/result"
-import type { SubjectClaim } from "../types/subject"
+import type { SubjectClaim, SubjectSchema } from "../types/subject"
 import type { TenantContext } from "../types/tenant"
 import type {
   AccessTokenClaims,
@@ -50,6 +50,7 @@ import {
 import { buildIdTokenClaims, shouldIssueIdToken } from "./id-token"
 import { signAccessToken, signIdToken } from "./jwt"
 import { validatePkce } from "./pkce"
+import { validateSubjectClaim } from "./subject"
 
 /**
  * Encrypt a `CodePayload` with the active `KeyStore` encryption key and
@@ -104,6 +105,12 @@ export type ExchangeCodeDeps = {
   keyStore: KeyStore
   auditLog?: AuditLog
   success: (input: SuccessMapInput) => Promise<SubjectClaim>
+  /**
+   * The host's declared subject schemas. The claim `success()` returns is
+   * validated against these before anything is signed — see
+   * `domain/subject.ts` for why that is the library's job.
+   */
+  subjects: SubjectSchema
   persistUpstreamTokens?: PersistUpstreamTokens
   issuerUrl: string
   clock: () => number
@@ -204,6 +211,23 @@ export async function exchangeCode(
     return err(authError.serverError("success callback threw", e))
   }
 
+  const checked = await validateSubjectClaim(deps.subjects, claim)
+  if (isErr(checked)) {
+    await safeAudit(deps, {
+      kind: "invalid_subject_claim",
+      tenantId: payload.tenantId,
+      clientId: payload.clientId,
+      subjectType: checked.error.rejection.subjectType,
+      reason: checked.error.rejection.reason,
+      detail: checked.error.rejection.detail,
+      timestamp: deps.clock(),
+    })
+    return err(checked.error)
+  }
+  // Parsed value from here on, so the token matches what the schema
+  // declares and what `client.verify()` returns to the RP.
+  claim = checked.value
+
   // 7. Optional upstream-tokens hook (runs after success, before
   //    mint — failed mints below should NOT roll back this hook because
   //    by contract the hook itself decides whether to persist).

package/src/http/context.ts

@@ -16,6 +16,7 @@ import type { SessionStore } from "../ports/session-store"
 import type { TokenStore } from "../ports/token-store"
 import type { MethodCache } from "../domain/method-cache"
 import type { AuthError } from "../types/error"
+import type { SubjectSchema } from "../types/subject"
 import type {
   ExchangeAudience,
   LogoutEventInput,
@@ -52,6 +53,8 @@ export type HttpDeps = {
   resolveIssuer: (req: Request) => string
   /** Optional partitioned-host helper (recovery #2). */
   callbackHostFor?: (tenantId: TenantId) => string
+  /** Host-declared subject schemas, validated at issuance. */
+  subjects: SubjectSchema
   resolveTenant: (req: Request) => Promise<Result<TenantId, AuthError>>
   success: (input: SuccessMapInput) => Promise<SubjectClaim>
   /** See `IdPOptions.onLogout` — upstream Single Logout host hook. */

package/src/http/handlers/method-route.ts

@@ -12,6 +12,7 @@ import {
   handlePublicMethodRoute,
 } from "../../domain/method-route"
 import type { RouteKey } from "../../domain/method-dispatch"
+import { callbackTarget } from "../../domain/mount"
 import { authError } from "../../types/error"
 import { isErr } from "../../types/result"
 
@@ -51,13 +52,15 @@ export function makeMethodRouteHandler(deps: HttpDeps) {
           resolved.value.publicRoutes?.includes(routeKey)
         ) {
           const issuerUrl = c.get("issuerUrl")
-          const callbackHost =
-            deps.callbackHostFor?.(tenant.id) ?? new URL(issuerUrl).host
-          // Mirrors the ACS URL derivation in domain/authorize.ts
-          // (callbackHost/path/url). Source of truth is there; the
+          // Same derivation as domain/authorize.ts — both call
+          // `callbackTarget`, which is the single source of truth. The
           // metadata.test.ts anti-drift test asserts the emitted
           // entityID/ACS equal what buildAuthnRequestRedirect derives.
-          const callbackUrl = `${new URL(issuerUrl).protocol}//${callbackHost}/cb/${methodId}`
+          const { url: callbackUrl } = callbackTarget({
+            issuerUrl,
+            methodId,
+            callbackHost: deps.callbackHostFor?.(tenant.id),
+          })
           const pub = await handlePublicMethodRoute(
             {
               rawRequest: c.req.raw,
@@ -122,6 +125,7 @@ export function makeMethodRouteHandler(deps: HttpDeps) {
         httpMethod,
         flowId,
         cookies,
+        issuerUrl: c.get("issuerUrl"),
       },
       {
         sessionStore: deps.sessionStore,

package/src/http/handlers/token.ts

@@ -127,6 +127,7 @@ export function makeTokenHandler(deps: HttpDeps) {
           keyStore: deps.keyStore,
           ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
           success: deps.success,
+          subjects: deps.subjects,
           ...(deps.persistUpstreamTokens
             ? { persistUpstreamTokens: deps.persistUpstreamTokens }
             : {}),
@@ -174,6 +175,7 @@ export function makeTokenHandler(deps: HttpDeps) {
           ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
           methodCache: deps.methodCache,
           success: deps.success,
+          subjects: deps.subjects,
           ...(deps.persistUpstreamTokens
             ? { persistUpstreamTokens: deps.persistUpstreamTokens }
             : {}),

package/src/http/middleware/tenant.ts

@@ -17,7 +17,10 @@
  */
 import type { MiddlewareHandler } from "hono"
 
-import { verifyStateEnvelope } from "../../domain/state-envelope"
+import {
+  extractCallbackState,
+  verifyStateEnvelope,
+} from "../../domain/state-envelope"
 import { isErr } from "../../types/result"
 import type {
   TenantConfig,
@@ -174,7 +177,7 @@ async function runCallbackRecovery(
   req: Request,
   deps: HttpDeps,
 ): Promise<TenantRecovery> {
-  const state = await extractStateParam(req)
+  const state = await extractCallbackState(req)
   if (state) {
     const env = await verifyStateEnvelope(state, deps.stateKeys)
     if (env.ok) {
@@ -187,25 +190,3 @@ async function runCallbackRecovery(
   }
   return { kind: "fresh-request" }
 }
-
-/**
- * Pull `state` from the query for GET callbacks, or from a form body for
- * POST callbacks (Apple's `response_mode=form_post`). The body is cloned
- * so the handler can still read it.
- */
-async function extractStateParam(req: Request): Promise<string | null> {
-  const url = new URL(req.url)
-  const fromQuery = url.searchParams.get("state")
-  if (fromQuery) return fromQuery
-  if (req.method !== "POST") return null
-  const ct = req.headers.get("content-type") ?? ""
-  if (!ct.toLowerCase().startsWith("application/x-www-form-urlencoded")) {
-    return null
-  }
-  try {
-    const text = await req.clone().text()
-    return new URLSearchParams(text).get("state")
-  } catch {
-    return null
-  }
-}

package/src/index.ts

@@ -73,7 +73,6 @@ export type {
 
 export type {
   ExchangeAudience,
-  FailureEvent,
   IdP,
   IdPOptions,
   LogoutEventInput,
@@ -83,7 +82,6 @@ export type {
   RegisterClientRequest,
   RegisterClientResponse,
   RenderPicker,
-  SuccessEvent,
   SuccessMapInput,
 } from "./types/idp"
 
@@ -133,6 +131,23 @@ export type { TokenStore } from "./ports/token-store"
  */
 export { revokeAllForSubject } from "./domain/revoke"
 
+/**
+ * Build a path-absolute URL for one of the library's own routes, carrying
+ * the mount prefix from `issuerUrl`.
+ *
+ * Custom methods that render their own URLs — a form `action`, say — must
+ * use this rather than a path-absolute literal, or the URL will 404 under
+ * a deployment mounted behind a proxy at a path prefix. Root-mounted
+ * issuers yield the literal unchanged.
+ *
+ *     mountedPath(ctx.issuerUrl, `/m/${id}/send`)
+ *     // "https://x"     -> "/m/mycode/send"
+ *     // "https://x/idp" -> "/idp/m/mycode/send"
+ *
+ * See INTEGRATION.md § 8.
+ */
+export { mountedPath, mountPath } from "./domain/mount"
+
 // Phase 4 — credential + WebAuthn method factories.
 export { passwordMethod } from "./methods/password"
 export type {
@@ -268,6 +283,7 @@ export function createIdP(opts: IdPOptions): IdP {
     ...(opts.callbackHostFor ? { callbackHostFor: opts.callbackHostFor } : {}),
     resolveTenant: opts.resolveTenant,
     success: opts.success,
+    subjects: opts.subjects,
     ...(opts.onLogout ? { onLogout: opts.onLogout } : {}),
     ...(opts.persistUpstreamTokens
       ? { persistUpstreamTokens: opts.persistUpstreamTokens }