@_mustachio/openauth 0.13.3 → 0.15.0

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.
  *
@@ -120,6 +96,63 @@ export type LogoutEventInput = {
  */
 export type LogoutHookResult = { revokeSubject?: string } | void
 
+/**
+ * Fired when tokens are minted, naming the derived subject id.
+ *
+ * This is the only way a host can learn `subjectId` — the value the
+ * library signs as `sub`, and the key `TokenStore.revokeBySubject` and
+ * `revokeAllForSubject` take. It is derived inside the library from the
+ * claim and the receiving client's `sectorIdentifier`, so without this
+ * hook a host holds a revocation primitive it can never call, and
+ * `onLogout`'s `revokeSubject` has no map to resolve against.
+ *
+ * That matters because refresh rotation never re-consults the host:
+ * `refreshTokens` mints from the claim captured on the stored payload.
+ * Revoking the chain is the only way to stop an offboarded user's tokens
+ * from being renewed indefinitely.
+ *
+ * **A principal maps to many subject ids, not one.** Record them; do not
+ * overwrite. Two reasons, both silent if you assume otherwise:
+ *
+ *  - **Pairwise** — with `ClientConfig.sectorIdentifier` set, derivation
+ *    mixes the sector in (OIDC Core §8.1), so the same person has a
+ *    distinct `sub` per sector. Revoking one leaves the others minting.
+ *  - **Claim contents** — derivation hashes `claim.properties`. If your
+ *    `success()` returns anything mutable (an email, a role), the subject
+ *    id changes when that value changes, and chains issued under the old
+ *    one survive. Returning a single immutable id is the way to avoid
+ *    this; OIDC Core §2 wants `sub` never reassigned.
+ *
+ * Runs **before** the refresh token is persisted, so throwing aborts
+ * issuance with `server_error` and leaves no chain behind. That is
+ * deliberate: recording the mapping after the token is durable would let
+ * a hook failure produce exactly the unrevokable token this exists to
+ * prevent. Like `success` and `persistUpstreamTokens`, and unlike
+ * `AuditLog`, a failure here stops the grant.
+ */
+export type OnTokenIssued = (input: {
+  tenant: TenantContext
+  /** Client the tokens were minted for. */
+  clientId: string
+  /**
+   * The `sub` of the issued access token — the key `revokeBySubject` and
+   * `revokeAllForSubject` take.
+   */
+  subjectId: string
+  /**
+   * The claim your `success()` (or token-exchange audience mapping)
+   * returned, already validated against `subjects`. Use it to attribute
+   * `subjectId` to one of your own principals.
+   */
+  claim: SubjectClaim
+  /**
+   * Refresh-token family, for `TokenStore.revokeFamily`. Absent when the
+   * grant issued no refresh token (`client_credentials`, RFC 6749
+   * §4.4.3), because then there is no chain to revoke.
+   */
+  family?: string
+}) => Promise<void> | void
+
 /**
  * Optional hook called at `/token` time, after PKCE has succeeded and
  * after the `success` callback has produced a `SubjectClaim`, but
@@ -217,19 +250,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>>
 
 /**
@@ -328,12 +383,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.
@@ -342,9 +391,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
@@ -364,6 +413,23 @@ export type IdPOptions = {
    */
   persistUpstreamTokens?: PersistUpstreamTokens
 
+  /**
+   * Optional hook fired as tokens are minted, carrying the derived
+   * `subjectId` alongside the claim it came from.
+   *
+   * Supply this if you need to revoke a user's tokens later — on
+   * offboarding, deactivation, or a membership change. `subjectId` is
+   * computed inside the library and appears nowhere else, so without
+   * this hook `TokenStore.revokeBySubject` / `revokeAllForSubject` are
+   * uncallable and `onLogout`'s `revokeSubject` has nothing to resolve
+   * against. See {@link OnTokenIssued} — in particular, one principal
+   * has many subject ids and they must be accumulated, not overwritten.
+   *
+   * Throwing aborts the grant; it runs before the refresh token is
+   * persisted so no unrecorded chain can survive a failure.
+   */
+  onTokenIssued?: OnTokenIssued
+
   /**
    * Optional RFC 8693 token-exchange hook. If absent, exchange
    * requests at `/token` return `unsupported_grant_type`. See the