@_mustachio/openauth 0.11.0 → 0.12.0

package/src/types/idp.ts

@@ -69,6 +69,56 @@ export type FailureEvent = {
   error: AuthError
 }
 
+/**
+ * Input to the optional `IdPOptions.onLogout` hook.
+ *
+ * Fires when an upstream provider notifies this IdP that a federated
+ * session has ended — today, a SAML front-channel `LogoutRequest`
+ * delivered to the SP's SLS endpoint. By the time this runs the library
+ * has already cryptographically verified the upstream logout message
+ * (XML-DSig via the SAML method), so the hook is purely the host's
+ * teardown point.
+ *
+ * The library deliberately does **not** know which OIDC `subject` an
+ * upstream identifier (`nameId`) maps to — that mapping lives in the
+ * host's `success` callback, not the library. So the host clears its
+ * own session and returns the subject (if any) whose library-issued
+ * tokens should be revoked; the library then runs the same
+ * `revokeAllForSubject` primitive `/end_session` uses. Returning
+ * nothing skips library-side revocation (the host handled everything,
+ * or there is nothing to revoke).
+ *
+ * Method-agnostic on purpose: any federation method that can verify an
+ * upstream logout signal reuses this. SAML SLO is the first caller;
+ * OIDC back-channel logout would be the next.
+ */
+export type LogoutEventInput = {
+  tenant: TenantContext
+  methodId: string
+  methodKind: string
+  /** What kind of upstream logout this is. Extensible discriminant. */
+  reason: "upstream_slo"
+  /**
+   * Upstream subject identifier from the verified logout message
+   * (SAML `LogoutRequest/NameID`). Absent if the message omitted it.
+   */
+  nameId?: string
+  /**
+   * Upstream session index from the verified logout message
+   * (SAML `SessionIndex`), when present. Lets a host that tracks
+   * per-session state scope its teardown.
+   */
+  sessionIndex?: string
+}
+
+/**
+ * Return of `IdPOptions.onLogout`. `revokeSubject` names the OIDC
+ * subject whose library-issued refresh tokens the library should
+ * revoke (the host resolves it from `nameId` — only the host has that
+ * map). Omit / return nothing to skip library-side revocation.
+ */
+export type LogoutHookResult = { revokeSubject?: string } | void
+
 /**
  * Optional hook called at `/token` time, after PKCE has succeeded and
  * after the `success` callback has produced a `SubjectClaim`, but
@@ -259,6 +309,30 @@ export type IdPOptions = {
     onFailure?: (event: FailureEvent) => Promise<void>
   }
 
+  /**
+   * Optional hook fired when an upstream provider signals that a
+   * federated session ended — SAML front-channel Single Logout today.
+   * The library has already verified the signed logout message; this
+   * hook is where the host tears down its own session and names the
+   * 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`.
+   *
+   * Absent ⇒ the library still verifies the logout, emits a
+   * `session_logout` audit event, and returns the protocol
+   * `LogoutResponse`, but performs no token revocation (it cannot map
+   * the upstream id to a subject without the host).
+   *
+   * If it throws, the SLS endpoint fails closed with an internal error
+   * rather than acknowledging a logout it could not fully process.
+   */
+  onLogout?: (
+    input: LogoutEventInput,
+  ) => Promise<LogoutHookResult> | LogoutHookResult
+
   /**
    * Optional escape hatch for high-sensitivity deployments — see the
    * `PersistUpstreamTokens` type doc.

package/src/types/method.ts

@@ -56,6 +56,37 @@ export type AuthMethod<P = unknown, S = unknown> = {
    * same factory get distinct URL spaces).
    */
   routes: Record<string, MethodHandler<P, S>>
+  /**
+   * Opt-in allowlist of route keys (same `"GET /metadata"` string form
+   * as `routes` keys) that the framework dispatches **without** a flow
+   * cookie or flow record — anonymous, unauthenticated GETs. The sole
+   * intended use is publishing static, per-instance descriptive
+   * documents (SAML SP metadata XML). The handler receives
+   * `ctx.flow === null` and `ctx.methodState === null` and MUST be a
+   * pure function of `ctx.tenant` + `ctx.dispatch` + its captured
+   * config — it must not assume an authenticated principal.
+   *
+   * Absent (the default for every method) ⇒ behaviour is unchanged:
+   * every `/m/<id>/*` request requires the `idp.flow` cookie. The
+   * cookie gate is skipped *only* for a route key a method explicitly
+   * lists here — fail-closed by construction.
+   */
+  publicRoutes?: ReadonlyArray<string>
+  /**
+   * Opt-in: this method instance handles **unsolicited** upstream
+   * callbacks — a `POST /cb/<methodId>` carrying a provider assertion
+   * with no framework state envelope and no prior flow (SAML
+   * IdP-initiated SSO). When `true`, the framework, instead of
+   * rejecting a stateless callback, dispatches `GET /callback` with
+   * `flow === null` and a derived `dispatch` (issuer/ACS); the handler
+   * verifies the assertion and returns `success` **with
+   * `unsolicitedBinding`**. Absent (every method's default) ⇒ a
+   * stateless callback stays an `invalid_request` (the conservative
+   * default — many deployments do not want IdP-initiated). General
+   * capability, not SAML-specific; set per instance (a SAML instance
+   * sets it only when its config enables IdP-initiated).
+   */
+  unsolicitedCallback?: boolean
   /**
    * Token-exchange function for the `/token` endpoint when the method
    * participates in client-credentials-style flows (e.g. `m2m`). Most
@@ -102,6 +133,47 @@ export type MethodContext<S = unknown> = {
    * and the relevant data is on `flow`).
    */
   dispatch: MethodDispatchData | null
+  /**
+   * Per-method-instance scratch storage scoped to
+   * `(tenant.id, method.id)`. Survives across flows — distinct from
+   * `methodState`, which is per-flow.
+   *
+   * Most methods do NOT need this. It exists for cross-flow
+   * deduplication patterns such as SAML SP assertion-ID replay
+   * protection.
+   *
+   * Backed by `SessionStore.{saveScratch,readScratch,deleteScratch}`
+   * when those optional methods are implemented. Against adapters that
+   * don't implement them, every call returns
+   * `{ ok: false, error: unsupported }` — the method should surface a
+   * `MethodResult.error` with a clear message, not silently degrade.
+   */
+  methodScratch: MethodScratch
+}
+
+/**
+ * Caller-facing API for per-method-instance scratch. The framework
+ * scopes user-supplied keys with a `(tenantId, methodId)` prefix before
+ * delegating to `SessionStore` — adapters never see raw method keys.
+ *
+ * Values are UTF-8 strings; methods JSON-encode if they want to stash
+ * objects. Keeping the port-level type narrow simplifies adapter
+ * implementations (one TEXT column, one Dynamo `S` attribute, etc.).
+ */
+export type MethodScratch = {
+  /**
+   * Persist `value` under `key` with the given TTL. Overwrites prior
+   * value for the same key. `ttlMs` must be positive.
+   */
+  put(key: string, value: string, ttlMs: number): Promise<Result<void>>
+  /**
+   * Read the value previously stored at `key`. Returns `unknown_state`
+   * if the key is missing or expired (the underlying adapter MAY
+   * lazily evict expired entries on read).
+   */
+  get(key: string): Promise<Result<string>>
+  /** Idempotent. Resolves `ok` whether the key existed or not. */
+  delete(key: string): Promise<Result<void>>
 }
 
 /** Framework-supplied data available to the method at `/authorize` time. */
@@ -143,6 +215,27 @@ export type MethodResult<P = unknown, S = unknown> =
       saveMethodState?: S
       /** Serialized into a `Cache-Control` header by the framework. */
       cache?: CachePolicy
+      /**
+       * Verified upstream-logout notification. Set **only** by a
+       * flowless **public** logout route (e.g. SAML front-channel SLS)
+       * once it has cryptographically verified the inbound logout
+       * message. The method stays port-free — it proves authenticity
+       * and builds the protocol response (`response` = the signed
+       * `LogoutResponse` redirect / ack); the privileged side effect
+       * runs in the framework.
+       *
+       * When present on a public route the framework fires
+       * `IdPOptions.onLogout` and, if that returns `{ revokeSubject }`,
+       * runs `revokeAllForSubject` — then returns `response`. Ignored
+       * on non-public (flow-bearing) routes: an authenticated method
+       * route never logs anyone out. Mirrors the Phase 2 V′ pattern
+       * (`success.unsolicitedBinding`): an optional field on an
+       * existing variant, not a new `MethodResult` kind.
+       */
+      logout?: {
+        nameId?: string
+        sessionIndex?: string
+      }
     }
   /**
    * Authentication succeeded. The HTTP layer hands `providerSubject` +
@@ -155,6 +248,23 @@ export type MethodResult<P = unknown, S = unknown> =
       providerSubject: string
       properties: P
       setCookies?: SetCookie[]
+      /**
+       * RP binding for a **flowless** (unsolicited / IdP-initiated)
+       * authentication. Consulted **only** when the method ran with no
+       * `flow` (e.g. an unsolicited SAML Response — see
+       * `AuthMethod.unsolicitedCallback`). On the normal SP-initiated
+       * path a `flow` exists and this is ignored; on the flowless path
+       * it is **required** (the framework has no pending RP request to
+       * read `client_id` / `redirect_uri` / `scope` from, so the method
+       * supplies the operator-configured defaults). The framework still
+       * validates `clientId` / `redirectUri` against the tenant's
+       * registered client before issuing a code.
+       */
+      unsolicitedBinding?: {
+        clientId: string
+        redirectUri: string
+        scopes: string[]
+      }
     }
   /** User refused / failed auth in a non-error way (e.g. consent declined). */
   | { kind: "denied"; reason: string; setCookies?: SetCookie[] }