@_mustachio/openauth 0.11.0 → 0.12.0

package/dist/types/types/method.d.ts

@@ -54,6 +54,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
@@ -96,6 +127,46 @@ 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. */
 export type MethodDispatchData = {
@@ -135,6 +206,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` +
@@ -147,6 +239,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). */
  | {

package/dist/types/types/method.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../../../src/types/method.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"method.d.ts","sourceRoot":"","sources":["../../../src/types/method.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_mustachio/openauth",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -37,6 +37,12 @@
       "import": "./dist/esm/adapters/*/index.js",
       "types": "./dist/types/adapters/*/index.d.ts"
     },
+    "./methods/saml-sp": {
+      "node": {
+        "import": "./dist/esm/methods/saml-sp/index.js",
+        "types": "./dist/types/methods/saml-sp/index.d.ts"
+      }
+    },
     "./*": {
       "import": "./dist/esm/*.js",
       "types": "./dist/types/*.d.ts"
@@ -73,8 +79,10 @@
   },
   "dependencies": {
     "@noble/hashes": "2.2.0",
+    "@node-saml/node-saml": "5.1.0",
     "@simplewebauthn/server": "13.1.1",
     "@standard-schema/spec": "1.0.0-beta.3",
+    "@xmldom/xmldom": "0.8.13",
     "aws4fetch": "1.0.20",
     "jose": "5.9.6",
     "oauth4webapi": "3.8.6",

package/src/adapters/d1/migrations.ts

@@ -67,6 +67,11 @@ export const INITIAL_SCHEMA_SQL = [
     payload TEXT NOT NULL,
     expires_at INTEGER NOT NULL
   )`,
+  `CREATE TABLE IF NOT EXISTS openauth_scratch (
+    scratch_key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    expires_at INTEGER NOT NULL
+  )`,
   `CREATE TABLE IF NOT EXISTS openauth_audit_events (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     ts INTEGER NOT NULL,

package/src/adapters/d1/session-store.ts

@@ -227,4 +227,72 @@ export class D1SessionStore implements SessionStore {
     }
     return ok(undefined)
   }
+
+  async saveScratch(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>> {
+    if (ttlMs <= 0) {
+      return err(
+        authError.internalError(
+          `saveScratch: ttlMs must be positive, got ${ttlMs}`,
+        ),
+      )
+    }
+    const expiresAt = this.#clock() + ttlMs
+    try {
+      // Pinned to the primary — scratch backs InResponseTo replay
+      // protection, which is read-after-write sensitive at the ACS.
+      await primarySession(this.#db)
+        .prepare(
+          `INSERT INTO openauth_scratch (scratch_key, value, expires_at) VALUES (?1, ?2, ?3)
+           ON CONFLICT(scratch_key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at`,
+        )
+        .bind(key, value, expiresAt)
+        .run()
+    } catch (e) {
+      return err(authError.internalError("saveScratch: upsert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readScratch(key: string): Promise<Result<string>> {
+    let row: { value: string; expires_at: number } | null
+    try {
+      row = await primarySession(this.#db)
+        .prepare(
+          `SELECT value, expires_at FROM openauth_scratch WHERE scratch_key = ?1`,
+        )
+        .bind(key)
+        .first<{ value: string; expires_at: number }>()
+    } catch (e) {
+      return err(authError.internalError("readScratch: query failed", e))
+    }
+    if (!row) {
+      return err(authError.unknownState(`scratch "${key}" unknown`))
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      try {
+        await primarySession(this.#db)
+          .prepare(`DELETE FROM openauth_scratch WHERE scratch_key = ?1`)
+          .bind(key)
+          .run()
+      } catch {}
+      return err(authError.unknownState(`scratch "${key}" expired`))
+    }
+    return ok(row.value)
+  }
+
+  async deleteScratch(key: string): Promise<Result<void>> {
+    try {
+      await primarySession(this.#db)
+        .prepare(`DELETE FROM openauth_scratch WHERE scratch_key = ?1`)
+        .bind(key)
+        .run()
+    } catch (e) {
+      return err(authError.internalError("deleteScratch: delete failed", e))
+    }
+    return ok(undefined)
+  }
 }

package/src/adapters/durable-object/session-store.ts

@@ -51,6 +51,11 @@ type StoredSession = {
   expiresAt: number
 }
 
+type StoredScratch = {
+  value: string
+  expiresAt: number
+}
+
 export type DurableObjectSessionStoreOptions = {
   storage: DurableObjectStorageLike
   clock?: () => number
@@ -218,10 +223,66 @@ export class DurableObjectSessionStore implements SessionStore {
     }
     return ok(undefined)
   }
+
+  async saveScratch(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>> {
+    if (ttlMs <= 0) {
+      return err(
+        authError.internalError(
+          `saveScratch: ttlMs must be positive, got ${ttlMs}`,
+        ),
+      )
+    }
+    const stored: StoredScratch = {
+      value,
+      expiresAt: this.#clock() + ttlMs,
+    }
+    try {
+      // Plain put — scratch overwrites any prior value for the key. No
+      // transaction needed: it is a single write, and the DO serializes
+      // all operations on this instance.
+      await this.#storage.put(scratchKey(key), stored)
+    } catch (e) {
+      return err(authError.internalError("saveScratch: put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readScratch(key: string): Promise<Result<string>> {
+    let stored: StoredScratch | undefined
+    try {
+      stored = await this.#storage.get<StoredScratch>(scratchKey(key))
+    } catch (e) {
+      return err(authError.internalError("readScratch: get failed", e))
+    }
+    if (!stored) {
+      return err(authError.unknownState(`scratch "${key}" unknown`))
+    }
+    if (this.#clock() >= stored.expiresAt) {
+      try {
+        await this.#storage.delete(scratchKey(key))
+      } catch {}
+      return err(authError.unknownState(`scratch "${key}" expired`))
+    }
+    return ok(stored.value)
+  }
+
+  async deleteScratch(key: string): Promise<Result<void>> {
+    try {
+      await this.#storage.delete(scratchKey(key))
+    } catch (e) {
+      return err(authError.internalError("deleteScratch: delete failed", e))
+    }
+    return ok(undefined)
+  }
 }
 
 const flowKey = (flowId: string) => `flow:${flowId}`
 const sessionKey = (sessionId: string) => `session:${sessionId}`
+const scratchKey = (key: string) => `scratch:${key}`
 
 // Re-exported for adapter users wiring `storage.transaction` callbacks.
 export type { DurableObjectStorageLike, DurableObjectTransactionLike }

package/src/adapters/dynamo/session-store.ts

@@ -211,6 +211,69 @@ export class DynamoSessionStore implements SessionStore {
     }
     return ok(undefined)
   }
+
+  async saveScratch(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>> {
+    if (ttlMs <= 0) {
+      return err(
+        authError.internalError(
+          `saveScratch: ttlMs must be positive, got ${ttlMs}`,
+        ),
+      )
+    }
+    const expiresAtMs = this.#clock() + ttlMs
+    try {
+      // Unconditional put — scratch overwrites any prior value for the key.
+      await this.#exec.put({
+        item: {
+          pk: "scratch",
+          sk: key,
+          value,
+          expires_at: expiresAtMs,
+          ttl: Math.floor(expiresAtMs / 1000),
+        },
+      })
+    } catch (e) {
+      return err(authError.internalError("saveScratch: put failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readScratch(key: string): Promise<Result<string>> {
+    let row: Record<string, unknown> | undefined
+    try {
+      row = await this.#exec.get({
+        key: { pk: "scratch", sk: key },
+        consistentRead: true,
+      })
+    } catch (e) {
+      return err(authError.internalError("readScratch: get failed", e))
+    }
+    if (!row) {
+      return err(authError.unknownState(`scratch "${key}" unknown`))
+    }
+    // Native DynamoDB TTL eviction is best-effort (can lag up to ~48h), so
+    // filter on the adapter clock for correctness.
+    if (this.#clock() >= Number(row.expires_at)) {
+      try {
+        await this.#exec.delete({ key: { pk: "scratch", sk: key } })
+      } catch {}
+      return err(authError.unknownState(`scratch "${key}" expired`))
+    }
+    return ok(String(row.value))
+  }
+
+  async deleteScratch(key: string): Promise<Result<void>> {
+    try {
+      await this.#exec.delete({ key: { pk: "scratch", sk: key } })
+    } catch (e) {
+      return err(authError.internalError("deleteScratch: delete failed", e))
+    }
+    return ok(undefined)
+  }
 }
 
 function parseFlowPayload(raw: unknown): FlowRecord {

package/src/adapters/memory/session-store.ts

@@ -28,6 +28,11 @@ type StoredPar = {
   expiresAt: number
 }
 
+type StoredScratch = {
+  value: string
+  expiresAt: number
+}
+
 export type MemorySessionStoreOptions = {
   clock?: Clock
 }
@@ -37,6 +42,7 @@ export class MemorySessionStore implements SessionStore {
   #flows = new Map<string, StoredFlow>()
   #sessions = new Map<string, SessionRecord>()
   #par = new Map<string, StoredPar>()
+  #scratch = new Map<string, StoredScratch>()
 
   constructor(opts: MemorySessionStoreOptions = {}) {
     this.#clock = opts.clock ?? realClock
@@ -168,4 +174,37 @@ export class MemorySessionStore implements SessionStore {
     }
     return ok(stored.record)
   }
+
+  async saveScratch(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>> {
+    if (ttlMs <= 0) {
+      return err(
+        authError.internalError(
+          `saveScratch: ttlMs must be positive, got ${ttlMs}`,
+        ),
+      )
+    }
+    this.#scratch.set(key, { value, expiresAt: this.#clock() + ttlMs })
+    return ok(undefined)
+  }
+
+  async readScratch(key: string): Promise<Result<string>> {
+    const stored = this.#scratch.get(key)
+    if (!stored) {
+      return err(authError.unknownState(`scratch "${key}" unknown`))
+    }
+    if (this.#clock() >= stored.expiresAt) {
+      this.#scratch.delete(key)
+      return err(authError.unknownState(`scratch "${key}" expired`))
+    }
+    return ok(stored.value)
+  }
+
+  async deleteScratch(key: string): Promise<Result<void>> {
+    this.#scratch.delete(key)
+    return ok(undefined)
+  }
 }

package/src/adapters/postgres/migrations.ts

@@ -89,6 +89,12 @@ CREATE TABLE IF NOT EXISTS openauth_sessions (
   expires_at bigint NOT NULL
 );
 
+CREATE TABLE IF NOT EXISTS openauth_scratch (
+  scratch_key text PRIMARY KEY,
+  value text NOT NULL,
+  expires_at bigint NOT NULL
+);
+
 CREATE TABLE IF NOT EXISTS openauth_audit_events (
   id bigserial PRIMARY KEY,
   ts bigint NOT NULL,

package/src/adapters/postgres/session-store.ts

@@ -203,6 +203,75 @@ export class PostgresSessionStore implements SessionStore {
     }
     return ok(undefined)
   }
+
+  async saveScratch(
+    key: string,
+    value: string,
+    ttlMs: number,
+  ): Promise<Result<void>> {
+    if (ttlMs <= 0) {
+      return err(
+        authError.internalError(
+          `saveScratch: ttlMs must be positive, got ${ttlMs}`,
+        ),
+      )
+    }
+    const expiresAt = this.#clock() + ttlMs
+    try {
+      await this.#exec.query(
+        `INSERT INTO openauth_scratch (scratch_key, value, expires_at)
+         VALUES ($1, $2, $3)
+         ON CONFLICT (scratch_key)
+         DO UPDATE SET value = EXCLUDED.value, expires_at = EXCLUDED.expires_at`,
+        [key, value, expiresAt],
+      )
+    } catch (e) {
+      return err(authError.internalError("saveScratch: upsert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async readScratch(key: string): Promise<Result<string>> {
+    let row: { value: string; expires_at: string | number } | undefined
+    try {
+      const result = await this.#exec.query<{
+        value: string
+        expires_at: string | number
+      }>(
+        `SELECT value, expires_at FROM openauth_scratch WHERE scratch_key = $1`,
+        [key],
+      )
+      row = result.rows[0]
+    } catch (e) {
+      return err(authError.internalError("readScratch: query failed", e))
+    }
+    if (!row) {
+      return err(authError.unknownState(`scratch "${key}" unknown`))
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      // Lazy GC — best-effort, don't fail the read if the delete races.
+      try {
+        await this.#exec.query(
+          `DELETE FROM openauth_scratch WHERE scratch_key = $1`,
+          [key],
+        )
+      } catch {}
+      return err(authError.unknownState(`scratch "${key}" expired`))
+    }
+    return ok(row.value)
+  }
+
+  async deleteScratch(key: string): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `DELETE FROM openauth_scratch WHERE scratch_key = $1`,
+        [key],
+      )
+    } catch (e) {
+      return err(authError.internalError("deleteScratch: delete failed", e))
+    }
+    return ok(undefined)
+  }
 }
 
 function parseFlowRecord(raw: unknown): FlowRecord {