@_mustachio/openauth 0.13.2 → 0.14.0

package/src/methods/code.ts

@@ -31,6 +31,7 @@ import type {
   MethodContext,
   MethodResult,
 } from "../types/method"
+import { mountedPath } from "../domain/mount"
 import { renderForm } from "../ui/forms"
 
 export type CodeProperties = {
@@ -120,12 +121,12 @@ export function codeMethod(
         kind,
         type: "code",
         routes: {
-          "GET /authorize": async (_ctx) => ({
+          "GET /authorize": async (ctx) => ({
             kind: "challenge",
             response: htmlResponse(
               renderForm({
                 title: titleRequest,
-                action: `/m/${id}/send`,
+                action: mountedPath(ctx.issuerUrl, `/m/${id}/send`),
                 fields: destinationField(destinationKind),
                 submit: "Send code",
               }),
@@ -169,7 +170,7 @@ async function handleSend(
       response: htmlResponse(
         renderForm({
           title: titleRequest,
-          action: `/m/${methodId}/send`,
+          action: mountedPath(ctx.issuerUrl, `/m/${methodId}/send`),
           fields: destinationField(destinationKind),
           submit: "Send code",
           error: "Please enter a valid destination.",
@@ -193,7 +194,7 @@ async function handleSend(
     response: htmlResponse(
       renderForm({
         title: titleVerify,
-        action: `/m/${methodId}/verify`,
+        action: mountedPath(ctx.issuerUrl, `/m/${methodId}/verify`),
         fields: [
           {
             name: "code",
@@ -238,7 +239,13 @@ async function handleVerify(
   const form = await safeForm(ctx.request)
   const parsed = verifyBody.safeParse(form)
   if (!parsed.success) {
-    return verifyError(methodId, state, titleVerify, "Please enter the code.")
+    return verifyError(
+      ctx.issuerUrl,
+      methodId,
+      state,
+      titleVerify,
+      "Please enter the code.",
+    )
   }
 
   const submittedHash = base64url.encode(
@@ -246,6 +253,7 @@ async function handleVerify(
   )
   if (!timingSafeEqualStr(submittedHash, state.codeHash)) {
     return verifyError(
+      ctx.issuerUrl,
       methodId,
       { ...state, attempts: state.attempts + 1 },
       titleVerify,
@@ -261,6 +269,7 @@ async function handleVerify(
 }
 
 function verifyError(
+  issuerUrl: string,
   methodId: string,
   next: CodeState,
   titleVerify: string,
@@ -271,7 +280,7 @@ function verifyError(
     response: htmlResponse(
       renderForm({
         title: titleVerify,
-        action: `/m/${methodId}/verify`,
+        action: mountedPath(issuerUrl, `/m/${methodId}/verify`),
         fields: [
           {
             name: "code",

package/src/methods/oauth2-generic.ts

@@ -37,6 +37,7 @@ import { createRemoteJWKSet, jwtVerify } from "jose"
  */
 type IdTokenClaims = Record<string, unknown>
 
+import { mountedPath } from "../domain/mount"
 import { authError } from "../types/error"
 import type { AuthMethod, MethodContext, MethodResult } from "../types/method"
 import type { MethodType } from "../types/tenant"
@@ -212,7 +213,11 @@ async function exchangeAndSucceed(
       error: authError.internalError("flow missing on callback"),
     }
   }
-  const callbackUrl = `${new URL(ctx.request.url).protocol}//${ctx.flow.callbackHost}${ctx.flow.callbackPath}`
+  // The `redirect_uri` on the token exchange must be byte-identical to the
+  // one sent on the authorize redirect (OAuth 2.1 §4.1.3). `flow.callbackPath`
+  // is the *inbound* route, which a path-mounted proxy has stripped the mount
+  // prefix from, so re-apply it here rather than replaying the stored path.
+  const callbackUrl = `${new URL(ctx.request.url).protocol}//${ctx.flow.callbackHost}${mountedPath(ctx.issuerUrl, ctx.flow.callbackPath)}`
 
   const body = new URLSearchParams({
     grant_type: "authorization_code",

package/src/methods/passkey.ts

@@ -32,6 +32,7 @@ import type {
   MethodContext,
   MethodResult,
 } from "../types/method"
+import { mountedPath } from "../domain/mount"
 import { renderForm } from "../ui/forms"
 
 export type PasskeyProperties = {
@@ -146,12 +147,15 @@ export function passkeyMethod(
         kind,
         type: "passkey",
         routes: {
-          "GET /authorize": async () => ({
+          "GET /authorize": async (ctx) => ({
             kind: "challenge",
             response: htmlResponse(
               renderForm({
                 title: settings.title,
-                action: `/m/${id}/authenticate-options`,
+                action: mountedPath(
+                  ctx.issuerUrl,
+                  `/m/${id}/authenticate-options`,
+                ),
                 fields: [
                   {
                     name: "username",

package/src/methods/password.ts

@@ -26,6 +26,7 @@ import type {
   MethodContext,
   MethodResult,
 } from "../types/method"
+import { mountedPath } from "../domain/mount"
 import { renderForm } from "../ui/forms"
 
 export type PasswordProperties = {
@@ -140,7 +141,7 @@ async function renderLogin(
 ): Promise<MethodResult<PasswordProperties, PasswordState>> {
   const body = renderForm({
     title,
-    action: `/m/${methodId}/login`,
+    action: mountedPath(ctx.issuerUrl, `/m/${methodId}/login`),
     fields: [
       {
         name: "email",
@@ -180,6 +181,7 @@ async function handleLogin(
   const parsed = loginBodySchema.safeParse(form)
   if (!parsed.success) {
     return reLoginWithError(
+      ctx.issuerUrl,
       methodId,
       title,
       "Please enter your email and password.",
@@ -188,12 +190,22 @@ async function handleLogin(
 
   const user = await users.findByEmail(parsed.data.email, ctx.tenant.id)
   if (!user) {
-    return reLoginWithError(methodId, title, "Invalid email or password.")
+    return reLoginWithError(
+      ctx.issuerUrl,
+      methodId,
+      title,
+      "Invalid email or password.",
+    )
   }
 
   const verified = await hasher.verify(parsed.data.password, user.passwordHash)
   if (!verified) {
-    return reLoginWithError(methodId, title, "Invalid email or password.")
+    return reLoginWithError(
+      ctx.issuerUrl,
+      methodId,
+      title,
+      "Invalid email or password.",
+    )
   }
 
   return {
@@ -218,6 +230,7 @@ async function handleRegister(
   const parsed = registerBodySchema.safeParse(form)
   if (!parsed.success) {
     return reLoginWithError(
+      ctx.issuerUrl,
       methodId,
       title,
       "Password must be at least 8 characters and email must be valid.",
@@ -227,6 +240,7 @@ async function handleRegister(
   const existing = await users.findByEmail(parsed.data.email, ctx.tenant.id)
   if (existing) {
     return reLoginWithError(
+      ctx.issuerUrl,
       methodId,
       title,
       "An account with that email already exists.",
@@ -250,6 +264,7 @@ async function handleRegister(
 }
 
 function reLoginWithError(
+  issuerUrl: string,
   methodId: string,
   title: string,
   error: string,
@@ -259,7 +274,7 @@ function reLoginWithError(
     response: new Response(
       renderForm({
         title,
-        action: `/m/${methodId}/login`,
+        action: mountedPath(issuerUrl, `/m/${methodId}/login`),
         fields: [
           {
             name: "email",

package/src/methods/saml-sp/metadata.ts

@@ -22,6 +22,7 @@
  * `WantAssertionsSigned` are both read from config, so they state
  * actual runtime behaviour rather than a hardcoded assumption.
  */
+import { mountedPath } from "../../domain/mount"
 import { authError } from "../../types/error"
 import type { MethodContext, MethodResult } from "../../types/method"
 
@@ -184,7 +185,10 @@ export async function buildSpMetadata(
   // served (idp.sloUrl set ⇒ /sls is in publicRoutes). Derived from the
   // same dispatch input as the ACS so it cannot drift.
   const cb = new URL(ctx.dispatch.callbackUrl)
-  const slsUrl = `${cb.protocol}//${cb.host}/m/${methodId}/sls`
+  const slsUrl = `${cb.protocol}//${cb.host}${mountedPath(
+    ctx.dispatch.issuerUrl,
+    `/m/${methodId}/sls`,
+  )}`
   const xml = buildSpMetadataXml({
     spEntityId,
     acsUrl: ctx.dispatch.callbackUrl,

package/src/ports/audit-log.ts

@@ -28,13 +28,24 @@ export type AuditEvent =
       flowId: string
     }
   | {
+      /**
+       * A method authenticated the end user and an authorization code was
+       * minted. Completes the `authorize_started` / `authorize_failed`
+       * pair, which shipped without it.
+       */
       kind: "authorize_succeeded"
       tenantId: TenantId
       clientId: string
       methodId: string
       methodKind: string
       flowId: string
-      subjectId: string
+      /**
+       * The **upstream** identifier the method returned. Deliberately not
+       * `subjectId`: the OIDC subject is derived from the host's
+       * `success()` claim at `/token`, which has not run yet. Correlate
+       * with `token_issued.subjectId` via `clientId` + `flowId`.
+       */
+      providerSubject: string
     }
   | {
       kind: "authorize_failed"
@@ -162,6 +173,20 @@ export type AuditEvent =
       /** Zod error path string. Never the raw config blob. */
       errorPath: string
     }
+  | {
+      /**
+       * `IdPOptions.success` returned a claim that violates the host's
+       * own `subjects` schema. A deployment fault, not RP behaviour —
+       * token issuance is refused. Carries paths, never values.
+       */
+      kind: "invalid_subject_claim"
+      tenantId: TenantId
+      clientId: string
+      subjectType: string
+      reason: "unknown-type" | "invalid-properties"
+      /** Standard Schema issue path, or the declared type list. */
+      detail: string
+    }
   | {
       kind: "unknown_method_kind"
       tenantId: TenantId

package/src/types/idp.ts

@@ -46,30 +46,6 @@ export type SuccessMapInput = {
   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
-}
-
 /**
  * Input to the optional `IdPOptions.onLogout` hook.
  *
@@ -217,19 +193,41 @@ export type RegisterClientResponse = {
 /**
  * Optional Dynamic Client Registration hook. Hosts that want to expose
  * RFC 7591 client provisioning supply this; the framework validates the
- * wire format, then defers persistence to the host. If absent, the
- * `/register` endpoint returns `invalid_request` so RPs receive a clear
- * "not enabled" signal rather than a 404.
+ * wire format and mints credentials, then defers **persistence** to the
+ * host. If absent, the `/register` endpoint returns `invalid_request` so
+ * RPs receive a clear "not enabled" signal rather than a 404.
+ *
+ * The library owns credential generation — entropy, hashing, and the
+ * `ClientConfig` discriminated union, which requires `pkceRequired: true`
+ * as a literal on public clients and a `secretHash` on confidential ones.
+ * Those are protocol and security concerns, and making every host
+ * reimplement them is how they get done wrong. The host owns the table:
+ * write `client` through your own `ConfigStore` and return it.
+ *
+ * Before 0.14.0 this hook received only `{ tenant, request }` and the
+ * framework discarded what it had generated, so hosts had to mint their
+ * own — contradicting both this doc comment and `ARCHITECTURE.md`.
  *
- * The hook receives the parsed request, the resolved tenant, and the
- * plaintext client secret (if any) the framework minted — hosts hash it
- * with `hashClientSecret` before storing on `ClientConfig.secretHash`,
- * then return the final `ClientConfig` along with the secret in the
- * `RegisterClientResponse` so the RP can record it.
+ * Return the config you actually persisted. Adjusting it first is fine
+ * (narrowing `scopes`, substituting your own `id`); if you replace `id`
+ * or `secretHash`, return the matching plaintext as `secret` so the RP
+ * receives something that works.
  */
 export type RegisterClient = (input: {
   tenant: TenantContext
   request: RegisterClientRequest
+  /**
+   * Framework-minted `ClientConfig`, ready to persist as-is. Public
+   * clients carry `pkceRequired: true`; confidential clients carry
+   * `secretHash` for `secret` below.
+   */
+  client: ClientConfig
+  /**
+   * Plaintext secret matching `client.secretHash`. Present only for
+   * confidential clients. Return it in the result so the RP can record
+   * it — this is the only time it exists.
+   */
+  secret?: string
 }) => Promise<Result<{ client: ClientConfig; secret?: string }, AuthError>>
 
 /**
@@ -255,7 +253,22 @@ export type IdPOptions = {
    */
   resolveTenant: (req: Request) => Promise<Result<TenantId, AuthError>>
 
-  /** Opt-in for partitioned callback hosts (recovery mechanism #2). */
+  /**
+   * Opt-in for partitioned callback hosts (recovery mechanism #2).
+   *
+   * Returns the hostname a given tenant's callbacks arrive on, so the
+   * tenant is recoverable from the `Host` header before the state
+   * envelope is verified.
+   *
+   * **The issuer's mount prefix still applies to the returned host.** If
+   * `issuerUrl` is `https://example.com/idp`, a tenant host of
+   * `acme.example.com` produces `https://acme.example.com/idp/cb/<id>`.
+   * This option varies the *authority* of one deployment — those hosts
+   * are served by this same 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; a second option must not be added to paper over it.
+   */
   callbackHostFor?: (tenantId: TenantId) => string
 
   /**
@@ -313,12 +326,6 @@ export type IdPOptions = {
 
   theme?: ThemeConfig
 
-  hooks?: {
-    /** Observation only — does NOT influence the subject. */
-    onSuccess?: (event: SuccessEvent) => Promise<void>
-    onFailure?: (event: FailureEvent) => Promise<void>
-  }
-
   /**
    * Optional hook fired when an upstream provider signals that a
    * federated session ended — SAML front-channel Single Logout today.
@@ -327,9 +334,9 @@ export type IdPOptions = {
    * OIDC subject (if any) whose library-issued tokens to revoke. See
    * the `LogoutEventInput` / `LogoutHookResult` type docs.
    *
-   * Unlike `hooks.onSuccess`/`onFailure` (observation only) this hook
-   * **influences** library behaviour — its return drives token
-   * revocation — so it sits at the top level alongside `success`.
+   * Unlike `AuditLog` (observation only) this hook **influences**
+   * library behaviour — its return drives token revocation — so it sits
+   * at the top level alongside `success`.
    *
    * Absent ⇒ the library still verifies the logout, emits a
    * `session_logout` audit event, and returns the protocol

package/src/types/method.ts

@@ -113,6 +113,17 @@ export type MethodHandler<P, S> = (
 export type MethodContext<S = unknown> = {
   /** The raw Web Fetch `Request`. Web standard, not Hono `Context`. */
   request: Request
+  /**
+   * The issuer URL of this IdP, always present.
+   *
+   * Distinct from `dispatch.issuerUrl`, which is only populated for
+   * `GET /authorize`. Methods that render their own URLs — a form action
+   * re-rendered on a validation error, say — need it on every route, and
+   * must build those URLs with `mountedPath` so they carry the
+   * deployment's mount prefix. `ctx.request.url` is not a substitute: a
+   * proxy-stripped inbound URL has already lost that prefix.
+   */
+  issuerUrl: string
   /** Path within the method's mount, e.g. `"/callback"` (without the `/<id>` prefix). */
   subPath: string
   tenant: TenantContext