@agent-native/core 0.151.2 → 0.152.1

package/dist/server/identity-sso-store.d.ts

@@ -1,88 +1,62 @@
 /**
- * Framework-table store for the cross-app SSO ("Sign in with Agent-Native")
- * CLIENT side. Backs two pieces of the federated login round-trip:
+ * Framework-table store for the cross-app SSO client.
  *
- *   - `identity_sso_state` — short-lived (10 min), single-use, crypto-random
- *     CSRF `state` values. Minted at `/_agent-native/identity/login`,
- *     consumed exactly once at `/_agent-native/identity/callback`. Carries an
- *     optional same-origin `return` path so the user lands back where they
- *     started after federated sign-in.
- *   - `identity_sso_jti` — replayed-token guard. The hub-issued identity JWT
- *     carries a random `jti`; the first callback that verifies a given `jti`
- *     records it here, and any later callback that presents the same `jti`
- *     is rejected. Best-effort: a DB blip never widens the trust boundary
- *     (signature + exp + scope + single-use state are still enforced), it
- *     only relaxes the extra replay gate.
+ * The current protocol uses a fresh flow-state table instead of extending the
+ * original `identity_sso_state` table. That keeps the migration additive for
+ * deployments that already have the merged PR's schema:
  *
- * Mirrors `mcp/connect-store.ts`: lazy `ensureTable()`, `getDbExec()`,
- * dialect-agnostic SQL via `intType()`, `isConnectionError()` swallow so a
- * transient Neon WS drop never 500s. `CREATE TABLE IF NOT EXISTS` only —
- * strictly additive, never DROP / ALTER (shared prod DB rule).
+ *   - `identity_sso_flow_state` binds state to the exact app, client,
+ *     authority, callback, and PKCE challenge. State is single-use.
+ *   - `identity_sso_jti` remains a defence-in-depth replay guard for the
+ *     server-to-server assertion. The assertion is never sent through the
+ *     browser; the one-time authorization code is the only browser credential.
  *
- * Node-only (crypto), bundled alongside the other framework auth modules.
- */
-/**
- * Read + normalise `AGENT_NATIVE_IDENTITY_HUB_URL`. Returns `undefined`
- * (feature OFF) unless it is set to a syntactically valid http(s) URL. A
- * malformed value is treated as OFF rather than throwing, so a typo can
- * never brick an app's login — it just behaves as if SSO were unconfigured.
+ * Uses the same portable raw-SQL pattern as the other framework stores. DDL is
+ * additive and lazy, and PostgreSQL creation goes through the DDL guard.
  */
+export declare const SSO_STATE_TTL_MS: number;
+export declare const SSO_LOGIN_MAX = 60;
+export declare const SSO_LOGIN_WINDOW_MS = 60000;
 export declare function getIdentityHubUrl(): string | undefined;
-/**
- * Whether the federated-SSO client is active. When false, NOTHING in the
- * SSO module has any effect: the route 404s, the guard bypass is inert, the
- * login button is not rendered. This is the single switch the
- * env-unset-no-op invariant is asserted against.
- */
 export declare function isIdentitySsoEnabled(): boolean;
 export declare function isDesktopSsoCanaryUserAgent(userAgent: string | undefined): boolean;
 export declare function isCanonicalAgentNativeAppOrigin(origin: string | undefined): boolean;
 export declare function isCanonicalAgentNativeAppRequest(host: string | undefined, forwardedProtocol: string | undefined): boolean;
 /**
- * The conditional "Sign in with Agent-Native" entry injected into the login
- * page — ONLY when the feature is enabled. Returns an empty string when
- * disabled so the login HTML is byte-for-byte identical to today's output
- * with the env unset (asserted by the env-unset-no-op regression test). Pure
- * string builder, no I/O — safe to call during HTML render. Lives in this
- * leaf module so `onboarding-html.ts` can import it without creating an
- * `auth.ts` ↔ `identity-sso.ts` import cycle.
+ * The conditional login entry is the only browser UI this feature adds. It
+ * stays byte-for-byte absent when the direct web federation env is unset.
  */
 export declare function identitySsoLoginButtonHtml(): string;
-/** CSRF state values are valid for 10 minutes. */
-export declare const SSO_STATE_TTL_MS: number;
-/**
- * Rate limit for `identity/login`: at most this many state rows may be
- * created within `SSO_LOGIN_WINDOW_MS`. The endpoint is reachable without a
- * session (it's the entry point), so keep a coarse global cap to stop table
- * flooding without per-IP plumbing.
- */
-export declare const SSO_LOGIN_MAX = 60;
-export declare const SSO_LOGIN_WINDOW_MS = 60000;
-/**
- * Mint a fresh crypto-random `state` value, persist it with an optional
- * same-origin return path, and return it. Rate-limited at creation: at most
- * `SSO_LOGIN_MAX` rows within `SSO_LOGIN_WINDOW_MS`. Throws `RATE_LIMITED`
- * when the cap is exceeded so the route can map it to a 429.
- */
-export declare function createSsoState(returnPath: string | null): Promise<string>;
+export interface CreateSsoStateInput {
+    returnPath: string | null;
+    appId: string;
+    clientId: string;
+    redirectUri: string;
+    authority: string;
+    codeChallenge: string;
+}
+export interface SsoStateBinding {
+    appId: string;
+    clientId: string;
+    redirectUri: string;
+    authority: string;
+    codeChallenge: string;
+}
 export interface SsoStateConsumeResult {
     ok: boolean;
     returnPath: string | null;
 }
+/** Mint and persist a bound, crypto-random state value. */
+export declare function createSsoState(input: CreateSsoStateInput): Promise<string>;
 /**
- * Atomically consume a `state` value. Returns `{ ok: true, returnPath }` only
- * when the state existed, had not expired, and had not been consumed before —
- * and this call is the one that transitioned it to consumed (single-use,
- * enforced via a conditional UPDATE so a double callback can't both pass).
- * Any other condition returns `{ ok: false }`.
+ * Atomically consume state only when every security binding still matches.
+ * A missing or mismatched binding is indistinguishable from an unknown state.
  */
-export declare function consumeSsoState(state: string): Promise<SsoStateConsumeResult>;
+export declare function consumeSsoState(state: string, expected: SsoStateBinding): Promise<SsoStateConsumeResult>;
 /**
- * Returns true when the given identity-token `jti` has already been seen
- * (i.e. this is a replay). On the first sighting, records the `jti` and
- * returns false. Best-effort: a store/DB error returns `false` (not a
- * replay) so a transient Neon WS drop never blocks a legitimate first-time
- * sign-in — signature + exp + scope + single-use CSRF state remain the hard
- * gates; this only adds defence in depth against token replay.
+ * Strict replay defense for the server-to-server assertion. A database error
+ * fails closed here: code exchange already provides the primary single-use
+ * guarantee, and refusing a login is safer than accepting an unverifiable
+ * replay boundary.
  */
 export declare function isJtiReplayed(jti: string | undefined): Promise<boolean>;

package/dist/server/identity-sso-store.js

@@ -1,28 +1,21 @@
 /**
- * Framework-table store for the cross-app SSO ("Sign in with Agent-Native")
- * CLIENT side. Backs two pieces of the federated login round-trip:
+ * Framework-table store for the cross-app SSO client.
  *
- *   - `identity_sso_state` — short-lived (10 min), single-use, crypto-random
- *     CSRF `state` values. Minted at `/_agent-native/identity/login`,
- *     consumed exactly once at `/_agent-native/identity/callback`. Carries an
- *     optional same-origin `return` path so the user lands back where they
- *     started after federated sign-in.
- *   - `identity_sso_jti` — replayed-token guard. The hub-issued identity JWT
- *     carries a random `jti`; the first callback that verifies a given `jti`
- *     records it here, and any later callback that presents the same `jti`
- *     is rejected. Best-effort: a DB blip never widens the trust boundary
- *     (signature + exp + scope + single-use state are still enforced), it
- *     only relaxes the extra replay gate.
+ * The current protocol uses a fresh flow-state table instead of extending the
+ * original `identity_sso_state` table. That keeps the migration additive for
+ * deployments that already have the merged PR's schema:
  *
- * Mirrors `mcp/connect-store.ts`: lazy `ensureTable()`, `getDbExec()`,
- * dialect-agnostic SQL via `intType()`, `isConnectionError()` swallow so a
- * transient Neon WS drop never 500s. `CREATE TABLE IF NOT EXISTS` only —
- * strictly additive, never DROP / ALTER (shared prod DB rule).
+ *   - `identity_sso_flow_state` binds state to the exact app, client,
+ *     authority, callback, and PKCE challenge. State is single-use.
+ *   - `identity_sso_jti` remains a defence-in-depth replay guard for the
+ *     server-to-server assertion. The assertion is never sent through the
+ *     browser; the one-time authorization code is the only browser credential.
  *
- * Node-only (crypto), bundled alongside the other framework auth modules.
+ * Uses the same portable raw-SQL pattern as the other framework stores. DDL is
+ * additive and lazy, and PostgreSQL creation goes through the DDL guard.
  */
 import { randomBytes } from "node:crypto";
-import { getDbExec, isConnectionError, intType, isPostgres, } from "../db/client.js";
+import { getDbExec, intType, isConnectionError, isPostgres, } from "../db/client.js";
 import { ensureTableExists } from "../db/ddl-guard.js";
 let _initPromise;
 const DESKTOP_SSO_CANARY_USER_AGENT = /AgentNativeDesktopSsoCanary\//i;
@@ -44,39 +37,38 @@ const CANONICAL_IDENTITY_SSO_APP_ORIGINS = new Set([
     "https://slides.agent-native.com",
     "https://tasks.agent-native.com",
 ]);
+export const SSO_STATE_TTL_MS = 10 * 60_000;
+export const SSO_LOGIN_MAX = 60;
+export const SSO_LOGIN_WINDOW_MS = 60_000;
+const STATE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const APP_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const CLIENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const CODE_CHALLENGE_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+const LOCALHOST_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
 // ---------------------------------------------------------------------------
-// Feature switch — the SINGLE source of truth for whether the federated-SSO
-// client is active. Lives here (a leaf module with no dependency on auth.ts)
-// so BOTH the auth guard and the route handler import the identical
-// validator and can never drift. Pure env read, no I/O — safe on the guard
-// hot path.
+// Feature switch — this module is intentionally dependency-light because the
+// auth guard and the route handler both import the same pure switch.
 // ---------------------------------------------------------------------------
-/**
- * Read + normalise `AGENT_NATIVE_IDENTITY_HUB_URL`. Returns `undefined`
- * (feature OFF) unless it is set to a syntactically valid http(s) URL. A
- * malformed value is treated as OFF rather than throwing, so a typo can
- * never brick an app's login — it just behaves as if SSO were unconfigured.
- */
 export function getIdentityHubUrl() {
     const raw = process.env.AGENT_NATIVE_IDENTITY_HUB_URL?.trim();
     if (!raw)
         return undefined;
     try {
         const u = new URL(raw);
-        if (u.protocol !== "https:" && u.protocol !== "http:")
+        if (u.protocol !== "https:" &&
+            !(u.protocol === "http:" && LOCALHOST_HOSTS.has(u.hostname))) {
+            return undefined;
+        }
+        if (u.username || u.password || u.search || u.hash)
             return undefined;
         return `${u.protocol}//${u.host}${u.pathname}`.replace(/\/+$/, "");
     }
-    catch {
+    catch (error) {
+        void error;
         return undefined;
     }
 }
-/**
- * Whether the federated-SSO client is active. When false, NOTHING in the
- * SSO module has any effect: the route 404s, the guard bypass is inert, the
- * login button is not rendered. This is the single switch the
- * env-unset-no-op invariant is asserted against.
- */
 export function isIdentitySsoEnabled() {
     return !!getIdentityHubUrl();
 }
@@ -96,24 +88,19 @@ export function isCanonicalAgentNativeAppOrigin(origin) {
             !parsed.hash &&
             CANONICAL_IDENTITY_SSO_APP_ORIGINS.has(parsed.origin));
     }
-    catch {
+    catch (error) {
+        void error;
         return false;
     }
 }
 export function isCanonicalAgentNativeAppRequest(host, forwardedProtocol) {
-    if (!host || forwardedProtocol !== "https") {
+    if (!host || forwardedProtocol !== "https")
         return false;
-    }
     return isCanonicalAgentNativeAppOrigin(`https://${host}`);
 }
 /**
- * The conditional "Sign in with Agent-Native" entry injected into the login
- * page — ONLY when the feature is enabled. Returns an empty string when
- * disabled so the login HTML is byte-for-byte identical to today's output
- * with the env unset (asserted by the env-unset-no-op regression test). Pure
- * string builder, no I/O — safe to call during HTML render. Lives in this
- * leaf module so `onboarding-html.ts` can import it without creating an
- * `auth.ts` ↔ `identity-sso.ts` import cycle.
+ * The conditional login entry is the only browser UI this feature adds. It
+ * stays byte-for-byte absent when the direct web federation env is unset.
  */
 export function identitySsoLoginButtonHtml() {
     if (!isIdentitySsoEnabled())
@@ -126,24 +113,16 @@ export function identitySsoLoginButtonHtml() {
         `color:inherit;font:inherit;font-weight:600;text-decoration:none;` +
         `cursor:pointer">Sign in with Agent-Native</a>\n`);
 }
-/** CSRF state values are valid for 10 minutes. */
-export const SSO_STATE_TTL_MS = 10 * 60_000;
-/**
- * Rate limit for `identity/login`: at most this many state rows may be
- * created within `SSO_LOGIN_WINDOW_MS`. The endpoint is reachable without a
- * session (it's the entry point), so keep a coarse global cap to stop table
- * flooding without per-IP plumbing.
- */
-export const SSO_LOGIN_MAX = 60;
-export const SSO_LOGIN_WINDOW_MS = 60_000;
-// Build the CREATE SQL lazily (not at module scope) so intType() runs at
-// RUNTIME, not import time — a module-scope call breaks any consumer whose
-// db/client mock doesn't stub intType (e.g. db-admin specs).
-function buildIdentitySsoStateCreateSql() {
+function buildIdentitySsoFlowStateCreateSql() {
     return `
-        CREATE TABLE IF NOT EXISTS identity_sso_state (
+        CREATE TABLE IF NOT EXISTS identity_sso_flow_state (
           state TEXT PRIMARY KEY,
           return_path TEXT,
+          app_id TEXT NOT NULL,
+          client_id TEXT NOT NULL,
+          redirect_uri TEXT NOT NULL,
+          authority TEXT NOT NULL,
+          code_challenge TEXT NOT NULL,
           created_at ${intType()},
           expires_at ${intType()},
           consumed_at ${intType()}
@@ -161,94 +140,138 @@ function buildIdentitySsoJtiCreateSql() {
 async function ensureTable() {
     if (!_initPromise) {
         _initPromise = (async () => {
-            const client = getDbExec();
-            const identitySsoStateCreateSql = buildIdentitySsoStateCreateSql();
-            const identitySsoJtiCreateSql = buildIdentitySsoJtiCreateSql();
-            // Additive only. Never DROP / ALTER — this DB is shared across every
-            // deploy context (preview/branch/prod) for hosted templates.
+            const flowStateSql = buildIdentitySsoFlowStateCreateSql();
+            const jtiSql = buildIdentitySsoJtiCreateSql();
             if (isPostgres()) {
-                // PG guard: probe → guarded DDL → re-probe; skips lock on already-migrated path
-                await ensureTableExists("identity_sso_state", identitySsoStateCreateSql);
-                await ensureTableExists("identity_sso_jti", identitySsoJtiCreateSql);
+                await ensureTableExists("identity_sso_flow_state", flowStateSql);
+                await ensureTableExists("identity_sso_jti", jtiSql);
                 return;
             }
-            // SQLite (local dev): no lock problem — keep the original behaviour.
-            await client.execute(identitySsoStateCreateSql);
-            await client.execute(identitySsoJtiCreateSql);
-        })().catch((err) => {
-            // Don't cache a rejection — let the next caller retry a fresh init.
+            const client = getDbExec();
+            await client.execute(flowStateSql);
+            await client.execute(jtiSql);
+        })().catch((error) => {
             _initPromise = undefined;
-            throw err;
+            throw error;
         });
     }
     return _initPromise;
 }
-function numOrNull(v) {
-    if (v == null)
+function numOrNull(value) {
+    if (value == null)
         return null;
-    const n = Number(v);
-    return Number.isFinite(n) ? n : null;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
 }
-// ---------------------------------------------------------------------------
-// CSRF state
-// ---------------------------------------------------------------------------
-/**
- * Mint a fresh crypto-random `state` value, persist it with an optional
- * same-origin return path, and return it. Rate-limited at creation: at most
- * `SSO_LOGIN_MAX` rows within `SSO_LOGIN_WINDOW_MS`. Throws `RATE_LIMITED`
- * when the cap is exceeded so the route can map it to a 429.
- */
-export async function createSsoState(returnPath) {
+function stringOrNull(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function affectedRows(result) {
+    return Number(result?.rowsAffected ?? result?.rowCount ?? result?.count ?? 0);
+}
+function isSafeStateInput(input) {
+    if (!input.appId ||
+        !input.clientId ||
+        !input.redirectUri ||
+        !input.authority ||
+        !input.codeChallenge) {
+        return false;
+    }
+    if (!APP_ID_PATTERN.test(input.appId))
+        return false;
+    if (!CLIENT_ID_PATTERN.test(input.clientId))
+        return false;
+    if (!CODE_CHALLENGE_PATTERN.test(input.codeChallenge))
+        return false;
+    if (CONTROL_CHARS.test(input.redirectUri) ||
+        CONTROL_CHARS.test(input.authority)) {
+        return false;
+    }
+    try {
+        const redirect = new URL(input.redirectUri);
+        const authority = new URL(input.authority);
+        if (redirect.username ||
+            redirect.password ||
+            authority.username ||
+            authority.password) {
+            return false;
+        }
+        const secureOrLoopback = (url) => url.protocol === "https:" ||
+            (url.protocol === "http:" && LOCALHOST_HOSTS.has(url.hostname));
+        if (!secureOrLoopback(redirect) || !secureOrLoopback(authority)) {
+            return false;
+        }
+    }
+    catch (error) {
+        void error;
+        return false;
+    }
+    return true;
+}
+/** Mint and persist a bound, crypto-random state value. */
+export async function createSsoState(input) {
+    if (!isSafeStateInput(input))
+        throw new Error("INVALID_SSO_STATE");
     await ensureTable();
     const client = getDbExec();
     const now = Date.now();
     try {
         const { rows } = await client.execute({
-            sql: `SELECT COUNT(*) AS n FROM identity_sso_state WHERE created_at > ?`,
+            sql: "SELECT COUNT(*) AS n FROM identity_sso_flow_state WHERE created_at > ?",
             args: [now - SSO_LOGIN_WINDOW_MS],
         });
-        const n = Number(rows[0]?.n ?? rows[0]?.["COUNT(*)"] ?? 0);
-        if (Number.isFinite(n) && n >= SSO_LOGIN_MAX) {
+        const count = Number(rows[0]?.n ?? rows[0]?.["COUNT(*)"] ?? 0);
+        if (Number.isFinite(count) && count >= SSO_LOGIN_MAX) {
             throw new Error("RATE_LIMITED");
         }
     }
-    catch (err) {
-        if (err?.message === "RATE_LIMITED")
-            throw err;
-        // A read failure must not block legitimate logins — single-use +
-        // short-TTL state is the primary protection. Continue.
+    catch (error) {
+        if (error?.message === "RATE_LIMITED")
+            throw error;
+        // A rate-limit read failure does not widen the auth boundary. The state
+        // remains high entropy, bound, short-lived, and single-use.
     }
     const state = randomBytes(32).toString("base64url");
-    const expiresAt = now + SSO_STATE_TTL_MS;
     await client.execute({
-        sql: `INSERT INTO identity_sso_state (state, return_path, created_at, expires_at, consumed_at) VALUES (?, ?, ?, ?, ?)`,
-        args: [state, returnPath ?? null, now, expiresAt, null],
+        sql: "INSERT INTO identity_sso_flow_state " +
+            "(state, return_path, app_id, client_id, redirect_uri, authority, code_challenge, created_at, expires_at, consumed_at) " +
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        args: [
+            state,
+            input.returnPath,
+            input.appId,
+            input.clientId,
+            input.redirectUri,
+            input.authority,
+            input.codeChallenge,
+            now,
+            now + SSO_STATE_TTL_MS,
+            null,
+        ],
     });
-    // Fire-and-forget: prune fully-expired rows (consumed or abandoned). Without
-    // this the table grows unbounded and the rate-limit COUNT(*) above slows down.
     void client
         .execute({
-        sql: `DELETE FROM identity_sso_state WHERE expires_at < ?`,
+        sql: "DELETE FROM identity_sso_flow_state WHERE expires_at < ?",
         args: [now],
     })
         .catch(() => { });
     return state;
 }
 /**
- * Atomically consume a `state` value. Returns `{ ok: true, returnPath }` only
- * when the state existed, had not expired, and had not been consumed before —
- * and this call is the one that transitioned it to consumed (single-use,
- * enforced via a conditional UPDATE so a double callback can't both pass).
- * Any other condition returns `{ ok: false }`.
+ * Atomically consume state only when every security binding still matches.
+ * A missing or mismatched binding is indistinguishable from an unknown state.
  */
-export async function consumeSsoState(state) {
-    if (!state)
+export async function consumeSsoState(state, expected) {
+    if (!STATE_PATTERN.test(state) ||
+        !isSafeStateInput({ ...expected, returnPath: null })) {
         return { ok: false, returnPath: null };
+    }
     await ensureTable();
     const client = getDbExec();
     const now = Date.now();
     const { rows } = await client.execute({
-        sql: `SELECT state, return_path, expires_at, consumed_at FROM identity_sso_state WHERE state = ?`,
+        sql: "SELECT return_path, app_id, client_id, redirect_uri, authority, code_challenge, expires_at, consumed_at " +
+            "FROM identity_sso_flow_state WHERE state = ?",
         args: [state],
     });
     if (rows.length === 0)
@@ -256,62 +279,76 @@ export async function consumeSsoState(state) {
     const row = rows[0];
     const expiresAt = numOrNull(row.expires_at ?? row.expiresAt);
     const consumedAt = numOrNull(row.consumed_at ?? row.consumedAt);
-    if (consumedAt != null)
+    if (consumedAt != null || (expiresAt != null && expiresAt < now)) {
         return { ok: false, returnPath: null };
-    if (expiresAt != null && expiresAt < now) {
+    }
+    const appId = stringOrNull(row.app_id ?? row.appId);
+    const clientId = stringOrNull(row.client_id ?? row.clientId);
+    const redirectUri = stringOrNull(row.redirect_uri ?? row.redirectUri);
+    const authority = stringOrNull(row.authority);
+    const codeChallenge = stringOrNull(row.code_challenge ?? row.codeChallenge);
+    if (appId !== expected.appId ||
+        clientId !== expected.clientId ||
+        redirectUri !== expected.redirectUri ||
+        authority !== expected.authority ||
+        codeChallenge !== expected.codeChallenge) {
         return { ok: false, returnPath: null };
     }
-    // Single-use: only the caller that flips `consumed_at` from NULL wins.
     const result = await client.execute({
-        sql: `UPDATE identity_sso_state SET consumed_at = ? WHERE state = ? AND consumed_at IS NULL`,
-        args: [now, state],
+        sql: "UPDATE identity_sso_flow_state SET consumed_at = ? " +
+            "WHERE state = ? AND consumed_at IS NULL AND app_id = ? AND client_id = ? " +
+            "AND redirect_uri = ? AND authority = ? AND code_challenge = ?",
+        args: [
+            now,
+            state,
+            expected.appId,
+            expected.clientId,
+            expected.redirectUri,
+            expected.authority,
+            expected.codeChallenge,
+        ],
     });
-    if (result.rowsAffected === 0) {
-        // Lost the race to a concurrent callback — treat as already consumed.
+    if (affectedRows(result) !== 1)
         return { ok: false, returnPath: null };
-    }
-    const returnPath = (row.return_path ?? row.returnPath ?? null);
-    return { ok: true, returnPath };
+    return {
+        ok: true,
+        returnPath: stringOrNull(row.return_path ?? row.returnPath),
+    };
 }
-// ---------------------------------------------------------------------------
-// Replay (jti) guard
-// ---------------------------------------------------------------------------
 /**
- * Returns true when the given identity-token `jti` has already been seen
- * (i.e. this is a replay). On the first sighting, records the `jti` and
- * returns false. Best-effort: a store/DB error returns `false` (not a
- * replay) so a transient Neon WS drop never blocks a legitimate first-time
- * sign-in — signature + exp + scope + single-use CSRF state remain the hard
- * gates; this only adds defence in depth against token replay.
+ * Strict replay defense for the server-to-server assertion. A database error
+ * fails closed here: code exchange already provides the primary single-use
+ * guarantee, and refusing a login is safer than accepting an unverifiable
+ * replay boundary.
  */
 export async function isJtiReplayed(jti) {
     if (!jti)
-        return false;
+        return true;
     try {
         await ensureTable();
         const client = getDbExec();
+        const now = Date.now();
         await client.execute({
-            sql: `INSERT INTO identity_sso_jti (jti, seen_at) VALUES (?, ?)`,
-            args: [jti, Date.now()],
+            sql: "INSERT INTO identity_sso_jti (jti, seen_at) VALUES (?, ?)",
+            args: [jti, now],
         });
-        // The INSERT completed without throwing → this jti was never seen → not a
-        // replay. (A replay manifests as a PK-conflict *exception*, handled below.)
-        // Don't key off rowsAffected: some drivers report 0 for a successful insert,
-        // which would wrongly flag a legitimate first-time sign-in as a replay.
+        void client
+            .execute({
+            sql: "DELETE FROM identity_sso_jti WHERE seen_at < ?",
+            args: [now - SSO_STATE_TTL_MS],
+        })
+            .catch(() => { });
         return false;
     }
-    catch (err) {
-        // Primary-key conflict = the jti already exists = replay.
-        const msg = String(err?.message ?? "").toLowerCase();
-        if (msg.includes("unique") ||
-            msg.includes("duplicate") ||
-            msg.includes("constraint")) {
+    catch (error) {
+        const message = String(error?.message ?? "").toLowerCase();
+        if (message.includes("unique") ||
+            message.includes("duplicate") ||
+            message.includes("constraint")) {
             return true;
         }
-        // Any other error (incl. connection blips): fail open — do not block a
-        // legitimate first sign-in over a transient DB issue.
-        if (isConnectionError(err))
-            return false;
-        return false;
+        if (isConnectionError(error))
+            return true;
+        return true;
     }
 }