@oimlsmart/platform-server 0.2.5 → 0.2.7

package/migrations/0025_oidc_refresh_tokens.sql

@@ -0,0 +1,61 @@
+-- Migration 0025 — the SSO wave-C token surface (TODO.identity-sso: the
+-- refresh-token grant with rotation + revocation): the OP's refresh
+-- tokens. A refresh token is the offline half of the remembered consent
+-- (the Relying Party keeps the authorization while the holder is away),
+-- so the row carries the granting code's full provenance: the canonical
+-- scope spelling, the context_org, the amr, and the ORIGINAL
+-- authentication instant (auth_time never advances on a refresh — the
+-- refreshed ID token proves the original authentication, never a new
+-- one).
+--
+-- The doctrines:
+--   - ONE-TIME, atomically consumed (the oidc_codes / email_change_tokens
+--     posture): the exchange's UPDATE … WHERE consumed_at IS NULL flips
+--     exactly once — a replay loses the race;
+--   - the FAMILY: every rotation descends from the first mint and carries
+--     its family_id. A presented CONSUMED token is the theft signal
+--     (RFC 6819 §5.2.2.3): the whole family dies (DELETE WHERE
+--     family_id), so the attacker's copy and the holder's legitimate
+--     chain both end;
+--   - the consumed row STAYS (the reuse detector reads it) until the
+--     family's end: revocation (RFC 7009, client-bound — a client revokes
+--     only its own, and revoking one refresh token revokes the family),
+--     the consent's revocation, the deactivation sweep, and the account
+--     erasure remove the rows outright (the personal_access_tokens
+--     doctrine);
+--   - expiry is per row (the consumer passes ttlMs at each mint; a
+--     rotation slides the window forward on the NEW row). An expired
+--     present is consumed anyway — never a second chance.
+-- schema.sql carries the same end state for fresh databases —
+-- test/migrations.test.ts pins the UNION of every migration to
+-- schema.sql's CREATE set.
+
+CREATE TABLE IF NOT EXISTS oidc_refresh_tokens (
+  token TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id),
+  client_id TEXT NOT NULL,
+  -- The granted scope set, the canonical space-joined spelling
+  -- (normalizeOidcScopeSet) — a refresh never widens it (the route's
+  -- math), the row is the grant's record.
+  scope TEXT NOT NULL,
+  -- The granting code's context — a refreshed access token answers the
+  -- SAME claims the original carried.
+  context_org TEXT,
+  -- The authorizing authentication's amr provenance (a JSON array; NULL =
+  -- none recorded).
+  amr TEXT,
+  -- The ORIGINAL authentication instant (verbatim from the consenting
+  -- session; NULL = none recorded) — carried into every refreshed ID
+  -- token's auth_time.
+  auth_time TEXT,
+  -- The rotation lineage: the first mint's generated id, inherited by
+  -- every rotation. Reuse of a consumed row kills the family.
+  family_id TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  expires_at TEXT NOT NULL,
+  consumed_at TEXT
+);
+-- The deactivation/erasure sweeps + the account console's per-app read.
+CREATE INDEX IF NOT EXISTS idx_oidc_refresh_tokens_user ON oidc_refresh_tokens (user_id);
+-- The reuse-kill + the RFC 7009 family revocation.
+CREATE INDEX IF NOT EXISTS idx_oidc_refresh_tokens_family ON oidc_refresh_tokens (family_id);

package/migrations/0026_entity_changes_store_seq.sql

@@ -0,0 +1,15 @@
+-- The per-store journal high-water (the ServerStore seam's
+-- latestChangeSeqFor(store), the 2026-09-07 performance audit's G1):
+-- the seam's DOC-ONLY contract since 0.2.2 ("the (store, seq) walk —
+-- the index rides the same commit") lands. The read answers MAX(seq)
+-- over one store's slice of the ONE global journal — the seq stays
+-- global and monotone, this is a projection, never a second sequence.
+-- Without the index the projection scans the journal's rowid walk and
+-- filters; with it the read is a single indexed probe, which is the
+-- contract's whole point (per-store conditional revalidation / SSE
+-- resume probes paying one read, never a payload fetch).
+--
+-- CREATE INDEX IF NOT EXISTS is the idempotent guard (the migration
+-- contract's expand-only discipline; a consumer that already carries
+-- the index converges). schema.sql's mirror lands in the same commit.
+CREATE INDEX IF NOT EXISTS idx_entity_changes_store_seq ON entity_changes (store, seq);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimlsmart/platform-server",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "The OIML SMART platform server kernel: the store seam (ServerStore + the D1 and SQLite implementations), the canonical D1 migration set both deployments apply, the instance profile, the mailer, the RBAC map, the OIDC/OAuth client cones, and the shared role/permission vocabulary. Consumed by the smart monorepo (browser/) and the identity service.",
   "type": "module",
   "repository": {

package/src/store/d1.ts

@@ -39,6 +39,7 @@ import {
   type AuthUserPayload,
   type CompleteEmailChangeResult,
   type CompleteEnrollmentResult,
+  type ConsumeOidcRefreshTokenResult,
   type EmailChangeToken,
   type EnrollmentToken,
   type EntityChange,
@@ -64,6 +65,7 @@ import {
   type OidcCode,
   type OidcConsentGrant,
   type OidcKeyRow,
+  type OidcRefreshToken,
   consentGrantCovers,
   normalizeOidcScopeSet,
   type OpAccountErasure,
@@ -227,6 +229,7 @@ interface EnsureMemos {
   oidcColumns: Promise<void> | null
   personalAccessTokenSupport: Promise<void> | null
   consentGrantSupport: Promise<void> | null
+  oidcRefreshTokenSupport: Promise<void> | null
   accountEmailSupport: Promise<void> | null
   notifyDeliverySupport: Promise<void> | null
 }
@@ -243,6 +246,7 @@ function ensured(binding: D1Database, slot: keyof EnsureMemos, run: () => Promis
       orgRegistrySupport: null, holderAttributionSupport: null,
       instrumentRegistrationSupport: null, oidcColumns: null,
       personalAccessTokenSupport: null, consentGrantSupport: null,
+      oidcRefreshTokenSupport: null,
       accountEmailSupport: null, notifyDeliverySupport: null,
     }
     ensureMemosByBinding.set(binding, memos)
@@ -706,6 +710,33 @@ export class D1ServerStore implements ServerStore {
     })
   }
 
+  // TODO.identity-sso (the wave-C token surface): the oidc_refresh_tokens
+  // table arrives with migration 0025 — a dev D1 migrated from before it
+  // lacks the table, so the refresh methods (and the deactivation sweep)
+  // ensure it defensively (the ensureConsentGrantSupport posture,
+  // memoized per (binding, chain) at module scope).
+  private ensureOidcRefreshTokenSupport(): Promise<void> {
+    return ensured(this.binding, 'oidcRefreshTokenSupport', async () => {
+      await this.db.prepare(
+        `CREATE TABLE IF NOT EXISTS oidc_refresh_tokens (
+           token TEXT PRIMARY KEY,
+           user_id TEXT NOT NULL REFERENCES users(id),
+           client_id TEXT NOT NULL,
+           scope TEXT NOT NULL,
+           context_org TEXT,
+           amr TEXT,
+           auth_time TEXT,
+           family_id TEXT NOT NULL,
+           created_at TEXT NOT NULL DEFAULT (datetime('now')),
+           expires_at TEXT NOT NULL,
+           consumed_at TEXT
+         )`,
+      ).run()
+      await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_oidc_refresh_tokens_user ON oidc_refresh_tokens (user_id)').run()
+      await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_oidc_refresh_tokens_family ON oidc_refresh_tokens (family_id)').run()
+    })
+  }
+
   // TODO.identity-features/01 (multiple emails per account): the
   // account_emails table + the email_change_tokens.kind column arrive
   // with migration 0022 — a dev D1 migrated from before it lacks both,
@@ -1373,7 +1404,7 @@ export class D1ServerStore implements ServerStore {
   async getOidcAccessToken(token: string): Promise<OidcAccessToken | null> {
     await this.ensureMembershipSupport()
     const row = await this.stmt(
-      "SELECT * FROM oidc_access_tokens WHERE token = ? AND expires_at > datetime('now')", token,
+      "SELECT * FROM oidc_access_tokens WHERE token = ? AND datetime(expires_at) > datetime('now')", token,
     ).first<Record<string, unknown>>()
     if (!row) return null
     return {
@@ -1387,6 +1418,124 @@ export class D1ServerStore implements ServerStore {
     }
   }
 
+  /** The account console's per-app read + the governance view's per-user
+   *  slice: the account's LIVE access tokens, newest first — created_at
+   *  is second-resolution, the rowid breaks the tie. */
+  async listOidcAccessTokens(userId: string): Promise<OidcAccessToken[]> {
+    await this.ensureMembershipSupport()
+    const res = await this.stmt(
+      "SELECT * FROM oidc_access_tokens WHERE user_id = ? AND datetime(expires_at) > datetime('now') ORDER BY created_at DESC, rowid DESC", userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(row => ({
+      token: row.token as string,
+      userId: row.user_id as string,
+      clientId: row.client_id as string,
+      scope: row.scope as string,
+      contextOrg: (row.context_org as string | null) ?? null,
+      amr: parseRoles((row.amr as string | null) ?? null) ?? null,
+      expiresAt: row.expires_at as string,
+    }))
+  }
+
+  /** The RFC 7009 access-token revocation: the row goes, client-bound. */
+  async deleteOidcAccessToken(token: string, clientId: string): Promise<boolean> {
+    await this.ensureMembershipSupport()
+    const res = await this.stmt(
+      'DELETE FROM oidc_access_tokens WHERE token = ? AND client_id = ?', token, clientId,
+    ).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  private static toRefreshToken(row: Record<string, unknown>): OidcRefreshToken {
+    return {
+      token: row.token as string,
+      userId: row.user_id as string,
+      clientId: row.client_id as string,
+      scope: row.scope as string,
+      contextOrg: (row.context_org as string | null) ?? null,
+      amr: parseRoles((row.amr as string | null) ?? null) ?? null,
+      authTime: (row.auth_time as string | null) ?? null,
+      familyId: row.family_id as string,
+      createdAt: row.created_at as string,
+      expiresAt: row.expires_at as string,
+      consumedAt: (row.consumed_at as string | null) ?? null,
+    }
+  }
+
+  async createOidcRefreshToken(input: {
+    token: string
+    userId: string
+    clientId: string
+    scope: string
+    contextOrg?: string | null
+    amr?: string[] | null
+    authTime?: string | null
+    familyId: string
+    ttlMs: number
+  }): Promise<OidcRefreshToken> {
+    await this.ensureMembershipSupport()
+    await this.ensureOidcRefreshTokenSupport()
+    const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
+    await this.stmt(
+      `INSERT INTO oidc_refresh_tokens (token, user_id, client_id, scope, context_org, amr, auth_time, family_id, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      input.token, input.userId, input.clientId, input.scope, input.contextOrg ?? null,
+      input.amr?.length ? JSON.stringify(input.amr) : null, input.authTime ?? null, input.familyId, expiresAt,
+    ).run()
+    const row = await this.stmt('SELECT * FROM oidc_refresh_tokens WHERE token = ?', input.token).first<Record<string, unknown>>()
+    return D1ServerStore.toRefreshToken(row as Record<string, unknown>)
+  }
+
+  /** The refresh exchange's consume: the UPDATE flips consumed_at exactly
+   *  once — a replay loses the race, reads the consumed row back, and the
+   *  WHOLE FAMILY dies (the theft signal, RFC 6819 §5.2.2.3; a concurrent
+   *  double-present lands the same verdict — fail toward invalidation).
+   *  An expired live row is consumed anyway (never a second chance) and
+   *  answers 'invalid'. */
+  async consumeOidcRefreshToken(token: string): Promise<ConsumeOidcRefreshTokenResult> {
+    await this.ensureMembershipSupport()
+    await this.ensureOidcRefreshTokenSupport()
+    const res = await this.stmt(
+      "UPDATE oidc_refresh_tokens SET consumed_at = datetime('now') WHERE token = ? AND consumed_at IS NULL", token,
+    ).run()
+    if ((res.meta.changes ?? 0) > 0) {
+      const row = await this.stmt('SELECT * FROM oidc_refresh_tokens WHERE token = ?', token).first<Record<string, unknown>>()
+      if (!row) return { kind: 'invalid' }
+      if (new Date(row.expires_at as string).getTime() <= Date.now()) return { kind: 'invalid' }
+      return { kind: 'ok', token: D1ServerStore.toRefreshToken(row) }
+    }
+    const row = await this.stmt('SELECT * FROM oidc_refresh_tokens WHERE token = ?', token).first<Record<string, unknown>>()
+    if (!row) return { kind: 'invalid' }
+    // The reuse signal: the consumed row's family dies outright.
+    const familyId = row.family_id as string
+    await this.stmt('DELETE FROM oidc_refresh_tokens WHERE family_id = ?', familyId).run()
+    return { kind: 'reuse', familyId, userId: row.user_id as string, clientId: row.client_id as string }
+  }
+
+  /** The RFC 7009 refresh revocation, client-bound: the presented token's
+   *  family goes (never another client's rows). */
+  async revokeOidcRefreshToken(token: string, clientId: string): Promise<boolean> {
+    await this.ensureMembershipSupport()
+    await this.ensureOidcRefreshTokenSupport()
+    const row = await this.stmt(
+      'SELECT family_id FROM oidc_refresh_tokens WHERE token = ? AND client_id = ?', token, clientId,
+    ).first<{ family_id: string }>()
+    if (!row) return false
+    await this.stmt('DELETE FROM oidc_refresh_tokens WHERE family_id = ?', row.family_id).run()
+    return true
+  }
+
+  /** The consent revocation's companion: the (account, client) pair's
+   *  refresh rows all go. */
+  async deleteOidcRefreshTokensForUserClient(userId: string, clientId: string): Promise<number> {
+    await this.ensureMembershipSupport()
+    await this.ensureOidcRefreshTokenSupport()
+    const res = await this.stmt(
+      'DELETE FROM oidc_refresh_tokens WHERE user_id = ? AND client_id = ?', userId, clientId,
+    ).run()
+    return res.meta.changes ?? 0
+  }
+
   async listOidcKeys(): Promise<OidcKeyRow[]> {
     const res = await this.stmt('SELECT * FROM oidc_keys ORDER BY created_at, kid').all<Record<string, unknown>>()
     return res.results.map(row => ({
@@ -1842,16 +1991,21 @@ export class D1ServerStore implements ServerStore {
   }
 
   /** The deactivation's revocation half: every live session, every issued
-   *  access token, every unconsumed code and pending authorization goes.
-   *  The user row STAYS (the history). */
-  async revokeOpUserCredentials(userId: string): Promise<{ sessions: number; accessTokens: number; codes: number; authorizations: number }> {
+   *  access token, every refresh token (migration 0025 — the ensure runs
+   *  first: a dev D1 from before it lacks the table), every unconsumed
+   *  code and pending authorization goes. The user row STAYS (the
+   *  history). */
+  async revokeOpUserCredentials(userId: string): Promise<{ sessions: number; accessTokens: number; refreshTokens: number; codes: number; authorizations: number }> {
+    await this.ensureOidcRefreshTokenSupport()
     const sessions = await this.stmt('DELETE FROM sessions WHERE user_id = ?', userId).run()
     const accessTokens = await this.stmt('DELETE FROM oidc_access_tokens WHERE user_id = ?', userId).run()
+    const refreshTokens = await this.stmt('DELETE FROM oidc_refresh_tokens WHERE user_id = ?', userId).run()
     const codes = await this.stmt('DELETE FROM oidc_codes WHERE user_id = ? AND consumed_at IS NULL', userId).run()
     const authorizations = await this.stmt('DELETE FROM oidc_authorizations WHERE user_id = ? AND decision IS NULL', userId).run()
     return {
       sessions: sessions.meta.changes ?? 0,
       accessTokens: accessTokens.meta.changes ?? 0,
+      refreshTokens: refreshTokens.meta.changes ?? 0,
       codes: codes.meta.changes ?? 0,
       authorizations: authorizations.meta.changes ?? 0,
     }
@@ -3326,6 +3480,16 @@ export class D1ServerStore implements ServerStore {
     return row?.seq ?? 0
   }
 
+  async latestChangeSeqFor(store: string): Promise<number> {
+    // One indexed probe over idx_entity_changes_store_seq (migration
+    // 0026) — the per-store projection of the one journal; 0 when the
+    // store carries no rows (MAX answers NULL on the empty set).
+    const row = await this.stmt(
+      'SELECT MAX(seq) AS seq FROM entity_changes WHERE store = ?', store,
+    ).first<{ seq: number | null }>()
+    return row?.seq ?? 0
+  }
+
   // ── the platform event store (TODO.notify/01) ─────────────────────
   // The event rows port directly (D1 is SQLite) — the same statements
   // as sqlite/events.ts's sync half.

package/src/store/sqlite/entities.ts

@@ -74,3 +74,14 @@ export function latestChangeSeq(): number {
   const row = getDb().prepare('SELECT MAX(seq) AS seq FROM entity_changes').get() as { seq: number | null }
   return row.seq ?? 0
 }
+
+/** The per-store projection of the one journal (the seam's contract):
+ *  MAX(seq) over the store's own slice, 0 on a store with no writes.
+ *  Walks idx_entity_changes_store_seq — one indexed probe, never a
+ *  journal scan. */
+export function latestChangeSeqFor(store: string): number {
+  const row = getDb()
+    .prepare('SELECT MAX(seq) AS seq FROM entity_changes WHERE store = ?')
+    .get(store) as { seq: number | null }
+  return row.seq ?? 0
+}

package/src/store/sqlite/op-accounts-store.ts

@@ -299,15 +299,18 @@ export function deleteOpClientRoles(userId: string, clientId: string): boolean {
 }
 
 /** The deactivation's revocation half: every live session, every issued
- *  access token, every unconsumed code and pending authorization goes.
- *  The user row STAYS (the history). */
-export function revokeOpUserCredentials(userId: string): { sessions: number; accessTokens: number; codes: number; authorizations: number } {
+ *  access token, every refresh token (migration 0025 — consumed or not;
+ *  the reuse detector has no more verdicts to give), every unconsumed
+ *  code and pending authorization goes. The user row STAYS (the
+ *  history). */
+export function revokeOpUserCredentials(userId: string): { sessions: number; accessTokens: number; refreshTokens: number; codes: number; authorizations: number } {
   const db = getDb()
   const sessions = db.prepare('DELETE FROM sessions WHERE user_id = ?').run(userId).changes
   const accessTokens = db.prepare('DELETE FROM oidc_access_tokens WHERE user_id = ?').run(userId).changes
+  const refreshTokens = db.prepare('DELETE FROM oidc_refresh_tokens WHERE user_id = ?').run(userId).changes
   const codes = db.prepare('DELETE FROM oidc_codes WHERE user_id = ? AND consumed_at IS NULL').run(userId).changes
   const authorizations = db.prepare('DELETE FROM oidc_authorizations WHERE user_id = ? AND decision IS NULL').run(userId).changes
-  return { sessions, accessTokens, codes, authorizations }
+  return { sessions, accessTokens, refreshTokens, codes, authorizations }
 }
 
 /** The registry's edit act (name/email). The email UNIQUE conflict
@@ -351,6 +354,7 @@ export function updateOpAccount(id: string, input: { name?: string; email?: stri
 export function eraseOpAccount(userId: string): {
   sessions: number
   accessTokens: number
+  refreshTokens: number
   codes: number
   authorizations: number
   links: number

package/src/store/sqlite/op-store.ts

@@ -11,12 +11,14 @@
 
 import { getDb } from './store'
 import type {
+  ConsumeOidcRefreshTokenResult,
   OidcAccessToken,
   OidcAuthorization,
   OidcClient,
   OidcClientLaunch,
   OidcCode,
   OidcKeyRow,
+  OidcRefreshToken,
 } from '../../store'
 
 function toOidcClient(row: Record<string, unknown>): OidcClient {
@@ -235,7 +237,7 @@ export function createOidcAccessToken(input: {
 
 export function getOidcAccessToken(token: string): OidcAccessToken | null {
   const row = getDb().prepare(
-    "SELECT * FROM oidc_access_tokens WHERE token = ? AND expires_at > datetime('now')",
+    "SELECT * FROM oidc_access_tokens WHERE token = ? AND datetime(expires_at) > datetime('now')",
   ).get(token) as Record<string, unknown> | undefined
   if (!row) return null
   return {
@@ -249,6 +251,109 @@ export function getOidcAccessToken(token: string): OidcAccessToken | null {
   }
 }
 
+/** The account console's per-app read + the governance view's per-user
+ *  slice: the account's LIVE access tokens, newest first — created_at is
+ *  second-resolution, the rowid breaks the tie. */
+export function listOidcAccessTokens(userId: string): OidcAccessToken[] {
+  const rows = getDb().prepare(
+    "SELECT * FROM oidc_access_tokens WHERE user_id = ? AND datetime(expires_at) > datetime('now') ORDER BY created_at DESC, rowid DESC",
+  ).all(userId) as Array<Record<string, unknown>>
+  return rows.map(row => ({
+    token: row.token as string,
+    userId: row.user_id as string,
+    clientId: row.client_id as string,
+    scope: row.scope as string,
+    contextOrg: (row.context_org as string | null) ?? null,
+    amr: parseJsonStringList(row.amr),
+    expiresAt: row.expires_at as string,
+  }))
+}
+
+/** The RFC 7009 access-token revocation: the row goes, client-bound. */
+export function deleteOidcAccessToken(token: string, clientId: string): boolean {
+  const res = getDb().prepare('DELETE FROM oidc_access_tokens WHERE token = ? AND client_id = ?').run(token, clientId)
+  return res.changes > 0
+}
+
+function toOidcRefreshToken(row: Record<string, unknown>): OidcRefreshToken {
+  return {
+    token: row.token as string,
+    userId: row.user_id as string,
+    clientId: row.client_id as string,
+    scope: row.scope as string,
+    contextOrg: (row.context_org as string | null) ?? null,
+    amr: parseJsonStringList(row.amr),
+    authTime: (row.auth_time as string | null) ?? null,
+    familyId: row.family_id as string,
+    createdAt: row.created_at as string,
+    expiresAt: row.expires_at as string,
+    consumedAt: (row.consumed_at as string | null) ?? null,
+  }
+}
+
+/** The refresh mint (migration 0025): the row carries the granting code's
+ *  provenance verbatim — a rotation re-mints the SAME truth, auth_time
+ *  never advances. */
+export function createOidcRefreshToken(input: {
+  token: string
+  userId: string
+  clientId: string
+  scope: string
+  contextOrg?: string | null
+  amr?: string[] | null
+  authTime?: string | null
+  familyId: string
+  ttlMs: number
+}): OidcRefreshToken {
+  const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
+  getDb().prepare(`
+    INSERT INTO oidc_refresh_tokens (token, user_id, client_id, scope, context_org, amr, auth_time, family_id, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(input.token, input.userId, input.clientId, input.scope, input.contextOrg ?? null,
+    input.amr?.length ? JSON.stringify(input.amr) : null, input.authTime ?? null, input.familyId, expiresAt)
+  return toOidcRefreshToken(
+    getDb().prepare('SELECT * FROM oidc_refresh_tokens WHERE token = ?').get(input.token) as Record<string, unknown>,
+  )
+}
+
+/** The refresh exchange's consume: the UPDATE flips consumed_at exactly
+ *  once — a replay loses the race, reads the consumed row back, and the
+ *  WHOLE FAMILY dies (the theft signal, RFC 6819 §5.2.2.3; a concurrent
+ *  double-present lands the same verdict — fail toward invalidation). An
+ *  expired live row is consumed anyway (never a second chance) and
+ *  answers 'invalid'. */
+export function consumeOidcRefreshToken(token: string): ConsumeOidcRefreshTokenResult {
+  const db = getDb()
+  const res = db.prepare("UPDATE oidc_refresh_tokens SET consumed_at = datetime('now') WHERE token = ? AND consumed_at IS NULL").run(token)
+  if (res.changes > 0) {
+    const row = db.prepare('SELECT * FROM oidc_refresh_tokens WHERE token = ?').get(token) as Record<string, unknown>
+    if (new Date(row.expires_at as string).getTime() <= Date.now()) return { kind: 'invalid' }
+    return { kind: 'ok', token: toOidcRefreshToken(row) }
+  }
+  const row = db.prepare('SELECT * FROM oidc_refresh_tokens WHERE token = ?').get(token) as Record<string, unknown> | undefined
+  if (!row) return { kind: 'invalid' }
+  // The reuse signal: the consumed row's family dies outright.
+  const familyId = row.family_id as string
+  db.prepare('DELETE FROM oidc_refresh_tokens WHERE family_id = ?').run(familyId)
+  return { kind: 'reuse', familyId, userId: row.user_id as string, clientId: row.client_id as string }
+}
+
+/** The RFC 7009 refresh revocation, client-bound: the presented token's
+ *  family goes (never another client's rows). */
+export function revokeOidcRefreshToken(token: string, clientId: string): boolean {
+  const db = getDb()
+  const row = db.prepare('SELECT family_id FROM oidc_refresh_tokens WHERE token = ? AND client_id = ?').get(token, clientId) as { family_id: string } | undefined
+  if (!row) return false
+  db.prepare('DELETE FROM oidc_refresh_tokens WHERE family_id = ?').run(row.family_id)
+  return true
+}
+
+/** The consent revocation's companion: the (account, client) pair's
+ *  refresh rows all go. */
+export function deleteOidcRefreshTokensForUserClient(userId: string, clientId: string): number {
+  return getDb().prepare('DELETE FROM oidc_refresh_tokens WHERE user_id = ? AND client_id = ?').run(userId, clientId).changes
+}
+
 /** The amr column's honest parse (a JSON array of strings, else null —
  *  the provenance is absent on rows that predate the wave). */
 function parseJsonStringList(raw: unknown): string[] | null {

package/src/store/sqlite/schema.sql

@@ -132,6 +132,12 @@ CREATE TABLE IF NOT EXISTS entity_changes (
   id TEXT NOT NULL,
   at TEXT NOT NULL DEFAULT (datetime('now'))
 );
+-- The per-store high-water's walk (migration 0026, the seam's
+-- latestChangeSeqFor(store)): MAX(seq) over one store's slice of the
+-- one global journal costs a single indexed probe, never a journal
+-- scan. The seq stays global and monotone — a projection, never a
+-- second sequence.
+CREATE INDEX IF NOT EXISTS idx_entity_changes_store_seq ON entity_changes (store, seq);
 
 -- TODO.notify/01 — the platform event store (the notification system's
 -- source of truth): one row per DECLARED notifiable act (the catalog,
@@ -364,6 +370,31 @@ CREATE TABLE IF NOT EXISTS oidc_access_tokens (
   created_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
+-- The refresh tokens (migration 0025 — the SSO wave-C token surface): the
+-- offline half of the remembered consent. One-time, atomically consumed
+-- (WHERE consumed_at IS NULL); every rotation inherits the first mint's
+-- family_id, and a presented CONSUMED token is the theft signal that kills
+-- the whole family. The row carries the granting code's provenance
+-- (canonical scope, context_org, amr, the ORIGINAL auth_time — a refresh
+-- never advances it). Consumed rows STAY for the reuse detector;
+-- revocation (client-bound, per family), the consent's revocation, the
+-- deactivation sweep and the erasure remove rows outright.
+CREATE TABLE IF NOT EXISTS oidc_refresh_tokens (
+  token TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id),
+  client_id TEXT NOT NULL,
+  scope TEXT NOT NULL,
+  context_org TEXT,
+  amr TEXT,
+  auth_time TEXT,
+  family_id TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  expires_at TEXT NOT NULL,
+  consumed_at TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_oidc_refresh_tokens_user ON oidc_refresh_tokens (user_id);
+CREATE INDEX IF NOT EXISTS idx_oidc_refresh_tokens_family ON oidc_refresh_tokens (family_id);
+
 -- The OP's signing-key rotation history: the PUBLIC halves. JWKS serves
 -- every row not retired beyond the token lifetime, so a rotation never
 -- strands an in-flight ID token. The private half rides the

package/src/store/sqlite.ts

@@ -84,6 +84,7 @@ import {
   deleteEntity,
   getEntity,
   latestChangeSeq,
+  latestChangeSeqFor,
   listEntities,
   putEntity,
 } from './sqlite/entities'
@@ -117,16 +118,22 @@ import {
 } from './sqlite/notify'
 import {
   consumeOidcCode,
+  consumeOidcRefreshToken,
   createOidcAccessToken,
   createOidcAuthorization,
   createOidcCode,
+  createOidcRefreshToken,
   decideOidcAuthorization,
+  deleteOidcAccessToken,
+  deleteOidcRefreshTokensForUserClient,
   getOidcAccessToken,
   getOidcAuthorization,
   getOidcClient,
+  listOidcAccessTokens,
   listOidcClients,
   listOidcKeys,
   retireOidcKey,
+  revokeOidcRefreshToken,
   setOidcClientStatus,
   setOidcClientLaunch,
   upsertOidcClient,
@@ -179,7 +186,7 @@ import {
   updateOpAccount,
   updateUserName,
 } from './sqlite/op-accounts-store'
-import { installStore, type AccountEmail, type AddAccountEmailResult, type AuthUserPayload, type CertificateHolderClaim, type CertificateHolderOrg, type CompleteEmailChangeResult, type CompleteEnrollmentResult, type EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, type EventEntityKey, type EventKeyFilter, type FederationPeer, type IdentityApproval, type IdentityLink, type IdentityProvider, type InstrumentRegistration, type InstrumentRegistrationLifecycle, type InstrumentRegistrationScopeStatus, type NotifyDelivery, type NotifyDeliveryStatus, type NotifyEntityMute, type NotifyInboxState, type NotifyPreferences, type NotifyRule, type OAuthInitialAssignment, type OidcAccessToken, type OidcAuthorization, type OidcClient, type OidcClientLaunch, type OidcCode, type OidcConsentGrant, type OidcKeyRow, type OpAccountErasure, type OpClientRoleAssignment, type OpLiveSession, type OrgJoinRequest, type OrgMembership, type OrgMembershipState, type OrgRegistryContact, type OrgRegistryOrg, type OrgRegistryState, type PersonalAccessToken, type PlatformEvent, type ServerStore, type SessionView, type SsoSignInState, type UserAdminRow, type AdvanceCounterResult, type MfaPending, type RecoveryCodeState, type TotpSecret, type WebauthnChallenge, type WebauthnCredential } from '../store'
+import { installStore, type AccountEmail, type AddAccountEmailResult, type AuthUserPayload, type CertificateHolderClaim, type CertificateHolderOrg, type CompleteEmailChangeResult, type CompleteEnrollmentResult, type ConsumeOidcRefreshTokenResult, type EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, type EventEntityKey, type EventKeyFilter, type FederationPeer, type IdentityApproval, type IdentityLink, type IdentityProvider, type InstrumentRegistration, type InstrumentRegistrationLifecycle, type InstrumentRegistrationScopeStatus, type NotifyDelivery, type NotifyDeliveryStatus, type NotifyEntityMute, type NotifyInboxState, type NotifyPreferences, type NotifyRule, type OAuthInitialAssignment, type OidcAccessToken, type OidcAuthorization, type OidcClient, type OidcClientLaunch, type OidcCode, type OidcConsentGrant, type OidcKeyRow, type OidcRefreshToken, type OpAccountErasure, type OpClientRoleAssignment, type OpLiveSession, type OrgJoinRequest, type OrgMembership, type OrgMembershipState, type OrgRegistryContact, type OrgRegistryOrg, type OrgRegistryState, type PersonalAccessToken, type PlatformEvent, type ServerStore, type SessionView, type SsoSignInState, type UserAdminRow, type AdvanceCounterResult, type MfaPending, type RecoveryCodeState, type TotpSecret, type WebauthnChallenge, type WebauthnCredential } from '../store'
 import {
   advanceWebauthnCounter,
   consumeMfaPending,
@@ -658,6 +665,34 @@ export function createSqliteServerStore(): ServerStore {
     async getOidcAccessToken(token: string): Promise<OidcAccessToken | null> {
       return getOidcAccessToken(token)
     },
+    async listOidcAccessTokens(userId: string): Promise<OidcAccessToken[]> {
+      return listOidcAccessTokens(userId)
+    },
+    async deleteOidcAccessToken(token: string, clientId: string): Promise<boolean> {
+      return deleteOidcAccessToken(token, clientId)
+    },
+    async createOidcRefreshToken(input: {
+      token: string
+      userId: string
+      clientId: string
+      scope: string
+      contextOrg?: string | null
+      amr?: string[] | null
+      authTime?: string | null
+      familyId: string
+      ttlMs: number
+    }): Promise<OidcRefreshToken> {
+      return createOidcRefreshToken(input)
+    },
+    async consumeOidcRefreshToken(token: string): Promise<ConsumeOidcRefreshTokenResult> {
+      return consumeOidcRefreshToken(token)
+    },
+    async revokeOidcRefreshToken(token: string, clientId: string): Promise<boolean> {
+      return revokeOidcRefreshToken(token, clientId)
+    },
+    async deleteOidcRefreshTokensForUserClient(userId: string, clientId: string): Promise<number> {
+      return deleteOidcRefreshTokensForUserClient(userId, clientId)
+    },
     async listOidcKeys(): Promise<OidcKeyRow[]> {
       return listOidcKeys()
     },
@@ -956,7 +991,7 @@ export function createSqliteServerStore(): ServerStore {
     async deleteOpClientRoles(userId: string, clientId: string): Promise<boolean> {
       return deleteOpClientRoles(userId, clientId)
     },
-    async revokeOpUserCredentials(userId: string): Promise<{ sessions: number; accessTokens: number; codes: number; authorizations: number }> {
+    async revokeOpUserCredentials(userId: string): Promise<{ sessions: number; accessTokens: number; refreshTokens: number; codes: number; authorizations: number }> {
       return revokeOpUserCredentials(userId)
     },
     async eraseOpAccount(userId: string): Promise<OpAccountErasure | null> {
@@ -988,6 +1023,9 @@ export function createSqliteServerStore(): ServerStore {
     async latestChangeSeq(): Promise<number> {
       return latestChangeSeq()
     },
+    async latestChangeSeqFor(store: string): Promise<number> {
+      return latestChangeSeqFor(store)
+    },
 
     // ── the platform event store (TODO.notify/01) ──
     async appendEvent(input: {

package/src/store.ts

@@ -454,6 +454,41 @@ export interface OidcAccessToken {
   expiresAt: string
 }
 
+/** An issued refresh token (migration 0025 — the SSO wave-C token
+ *  surface): the offline half of the remembered consent. The row carries
+ *  the granting code's full provenance — the canonical scope spelling, the
+ *  context_org, the amr, and the ORIGINAL authentication instant (authTime
+ *  never advances on a refresh: the refreshed ID token proves the original
+ *  authentication). familyId is the rotation lineage: every rotation
+ *  inherits the first mint's id. consumedAt flips atomically at the
+ *  exchange; the consumed row STAYS so a re-present detects the reuse. */
+export interface OidcRefreshToken {
+  token: string
+  userId: string
+  clientId: string
+  scope: string
+  contextOrg: string | null
+  amr: string[] | null
+  authTime: string | null
+  familyId: string
+  createdAt: string
+  expiresAt: string
+  consumedAt: string | null
+}
+
+/** The refresh exchange's honest outcomes. 'ok' carries the freshly
+ *  consumed row (the route rotates from its provenance). 'reuse' is the
+ *  theft signal (RFC 6819 §5.2.2.3): a presented CONSUMED token — the
+ *  store already killed the whole family (the attacker's copy and the
+ *  legitimate chain both end); a concurrent double-present loses the
+ *  atomic race to the same verdict, the fail-toward-invalidation posture.
+ *  'invalid' covers the never-existed, the revoked (the row is gone), and
+ *  the expired (consumed anyway — never a second chance). */
+export type ConsumeOidcRefreshTokenResult =
+  | { kind: 'ok'; token: OidcRefreshToken }
+  | { kind: 'reuse'; familyId: string; userId: string; clientId: string }
+  | { kind: 'invalid' }
+
 /** The OP key rotation history — the PUBLIC half only. */
 export interface OidcKeyRow {
   kid: string
@@ -609,7 +644,7 @@ export interface OpClientRoleAssignment {
 }
 
 /** The erasure act's removal counts (the audit event's metadata):
- *  revokeOpUserCredentials' four plus the links, the per-client
+ *  revokeOpUserCredentials' five plus the links, the per-client
  *  assignments, the org memberships (TODO.identity/11), and the
  *  credential/token rows (passwords, enrollment tokens, email-change
  *  tokens). TODO.identity-sso/02+03 adds `factors`: the factor-registry
@@ -624,6 +659,7 @@ export interface OpClientRoleAssignment {
 export interface OpAccountErasure {
   sessions: number
   accessTokens: number
+  refreshTokens: number
   codes: number
   authorizations: number
   links: number
@@ -1617,6 +1653,50 @@ export interface ServerStore {
     ttlMs: number
   }): Promise<void>
   getOidcAccessToken(token: string): Promise<OidcAccessToken | null>
+  /** The account's LIVE access tokens (unexpired, never revoked — the
+   *  row's absence IS the revocation), newest first. The account console's
+   *  per-app read and the client-registry governance view's per-user
+   *  slice; the introspection endpoint never lists (it resolves ONE
+   *  presented token). */
+  listOidcAccessTokens(userId: string): Promise<OidcAccessToken[]>
+  /** The RFC 7009 access-token revocation: delete the row, client-bound —
+   *  a client revokes only its OWN tokens (a token minted for another
+   *  client answers false). An absent row answers false too (the endpoint
+   *  masks both behind its 200). */
+  deleteOidcAccessToken(token: string, clientId: string): Promise<boolean>
+  /** The refresh tokens (migration 0025 — the SSO wave-C token surface).
+   *  The mint: token is the opaque value the route generated, familyId the
+   *  rotation lineage (a fresh id at the code exchange's first mint, the
+   *  consumed row's familyId at every rotation). scope is the CANONICAL
+   *  spelling of the granted set (a refresh never widens it). authTime is
+   *  the ORIGINAL authentication instant — it never advances. */
+  createOidcRefreshToken(input: {
+    token: string
+    userId: string
+    clientId: string
+    scope: string
+    contextOrg?: string | null
+    amr?: string[] | null
+    authTime?: string | null
+    familyId: string
+    ttlMs: number
+  }): Promise<OidcRefreshToken>
+  /** The refresh exchange's consume: the UPDATE … WHERE consumed_at IS
+   *  NULL flips exactly once (the oidc_codes doctrine). A presented
+   *  CONSUMED token is the reuse signal — the whole family is deleted
+   *  before the verdict answers. An expired live row is consumed anyway
+   *  and answers 'invalid'. */
+  consumeOidcRefreshToken(token: string): Promise<ConsumeOidcRefreshTokenResult>
+  /** The RFC 7009 refresh-token revocation, client-bound: the presented
+   *  token's WHOLE FAMILY goes (the grant lineage ends), never another
+   *  client's rows. Answers false when the token never existed, was
+   *  already gone, or belongs to another client (the endpoint masks all
+   *  three behind its 200). */
+  revokeOidcRefreshToken(token: string, clientId: string): Promise<boolean>
+  /** The consent revocation's companion: every refresh row of the
+   *  (account, client) pair goes — the "Revoke access" act ends the
+   *  offline half with the remembered consent. Answers the count. */
+  deleteOidcRefreshTokensForUserClient(userId: string, clientId: string): Promise<number>
   /** The key rotation history (public halves). */
   listOidcKeys(): Promise<OidcKeyRow[]>
   upsertOidcKey(input: { kid: string; publicJwk: string }): Promise<void>
@@ -1763,10 +1843,12 @@ export interface ServerStore {
   /** Clear the per-client assignment (the account default is restored). */
   deleteOpClientRoles(userId: string, clientId: string): Promise<boolean>
   /** The deactivation's revocation half: delete EVERY live session, every
-   *  issued OIDC access token, every unconsumed authorization code and
-   *  every pending authorization of the account. Answers the counts (the
-   *  audit event's metadata). The user row STAYS (the history). */
-  revokeOpUserCredentials(userId: string): Promise<{ sessions: number; accessTokens: number; codes: number; authorizations: number }>
+   *  issued OIDC access token, every refresh token (consumed or not — the
+   *  reuse detector has no more verdicts to give), every unconsumed
+   *  authorization code and every pending authorization of the account.
+   *  Answers the counts (the audit event's metadata). The user row STAYS
+   *  (the history). */
+  revokeOpUserCredentials(userId: string): Promise<{ sessions: number; accessTokens: number; refreshTokens: number; codes: number; authorizations: number }>
   /** The offboarding runbook's DELETE path (the erasure): every credential,
    *  token, link and per-client assignment removed, the user row anonymized
    *  in place (provider 'erased' — it drops out of every account surface;
@@ -2271,20 +2353,20 @@ export interface ServerStore {
   changesAfter(seq: number, limit?: number): Promise<EntityChange[]>
   /** The GLOBAL journal high-water: the bootstrap snapshot's ETag leg
    *  (any write anywhere bumps the one seq — conservative, never
-   *  stale).
-   *
-   *  NAMED FOLLOW-UP, DOC ONLY (the smart side references it from
-   *  server/routes/bootstrap.ts: the per-store `seqs` snapshot carries
-   *  the journal position a delta-loading client would resume from):
-   *  the PER-STORE high-water — `latestChangeSeqFor(store)` — answering
-   *  MAX(seq) over one store's slice of the SAME journal. The contract
-   *  when it lands: the seq stays global and monotone (the per-store
-   *  read is a PROJECTION of the one journal, never a second
-   *  sequence); it exists so a per-store conditional revalidation /
-   *  SSE resume probe costs one indexed read instead of a payload
-   *  fetch; and its query wants the (store, seq) walk — the index
-   *  rides the same commit, expand-only per the migration contract. */
+   *  stale). */
   latestChangeSeq(): Promise<number>
+  /** The PER-STORE high-water: MAX(seq) over one store's slice of the
+   *  SAME journal. The seq stays global and monotone — the per-store
+   *  read is a PROJECTION of the one journal, never a second sequence.
+   *  A store with no writes answers 0 (the empty journal's floor, the
+   *  same as the global form's). The read is one indexed probe over
+   *  idx_entity_changes_store_seq (migration 0026 — the (store, seq)
+   *  walk rode that commit, expand-only per the migration contract),
+   *  so a per-store conditional revalidation / SSE resume probe never
+   *  pays a journal scan. Landed for the 2026-09-07 performance
+   *  audit's G1: the smart side's bootstrap composite ETag switches
+   *  from the global seq to the per-set composite of these. */
+  latestChangeSeqFor(store: string): Promise<number>
 
   // ── the platform event store (TODO.notify/01) ──
   /** Append one declared event (the emitter's write; one row inside the