@oimlsmart/platform-server 0.1.6 → 0.1.8

package/migrations/0021_oidc_consent_grants.sql

@@ -0,0 +1,44 @@
+-- Migration 0021 — the remembered consent grants (TODO.identity-features/12):
+-- the OP remembers the account holder's "Allow" per (user, client, scope
+-- set), so a repeat authorization the grant COVERS skips the consent page
+-- (the OIDC-correct behavior — the page shows again only when the request
+-- carries prompt=consent, when the granted set no longer covers the asked
+-- scopes, or when the holder revoked the access from the account console).
+--
+-- The doctrines:
+--   - ONE LIVE grant per (user_id, client_id, scope): the partial unique
+--     index keys the live rows only (a live grant = revoked_at IS NULL) —
+--     a revoked triple's re-allow lands a FRESH row and the history keeps
+--     the revoked one;
+--   - scope is the CANONICAL spelling (the scope SET, space-joined,
+--     deduped, sorted — store.ts's normalizeOidcScopeSet): 'profile openid'
+--     and 'openid profile' are the same grant, so the unique triple holds
+--     honestly;
+--   - the skip check's COVERAGE math (the granted set ⊇ the requested set)
+--     is the store's (consentGrantCovers over the live rows), never a LIKE
+--     scan in SQL;
+--   - revocation flips revoked_at (the row STAYS — the audit chain carries
+--     the grant + the revoke, the row is their resolvable record); the
+--     account erasure removes the rows outright (a dead account's grants
+--     die with it — the personal_access_tokens doctrine, migration 0020).
+-- 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_consent_grants (
+  id 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).
+  scope TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  revoked_at TEXT
+);
+-- One LIVE grant per (user, client, scope set) — the predicate keeps the
+-- revoked rows out of the index, so the re-allow after a revoke inserts
+-- cleanly.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_oidc_consent_grants_live
+  ON oidc_consent_grants (user_id, client_id, scope) WHERE revoked_at IS NULL;
+-- The account console's "apps they can access" read.
+CREATE INDEX IF NOT EXISTS idx_oidc_consent_grants_user ON oidc_consent_grants (user_id);

package/migrations/0022_account_emails.sql

@@ -0,0 +1,45 @@
+-- Migration 0022 — multiple emails per account (TODO.identity-features/01):
+-- the account gains a primary + additional addresses, each verified
+-- independently, the sign-in and the recovery paths resolving by ANY
+-- verified one.
+--
+-- The model:
+--   - the PRIMARY address stays users.email (+ users.email_verified_at):
+--     the OIDC `email` claim never changes shape, every existing reader
+--     (the claims, the registry, the audit chain) is undisturbed, and the
+--     claims keep carrying the primary on a switch;
+--   - account_emails carries the ADDITIONAL addresses only — one row per
+--     (account, address), verified_at NULL until the per-address ceremony
+--     proves the mailbox. An address is globally unique across the estate
+--     of addresses: the unique index keys it here, and the store's writes
+--     check BOTH tables (an additional on account A blocks the address as
+--     a primary or an additional anywhere else);
+--   - the "primary" attribute is represented by WHERE the address lives
+--     (the users row vs account_emails), never a flag to keep in sync —
+--     the store's setPrimaryAccountEmail swaps the two residences with
+--     their verification stamps;
+--   - email_change_tokens gains `kind`: 'change' (the pre-0022 primary
+--     replacement — the default, so existing rows read honestly) and
+--     'add' (the per-address verification of an account_emails row; the
+--     row lands unverified at the request and the token's completion
+--     stamps verified_at). The same one-time, 24 h, atomically-consumed
+--     doctrine carries both.
+-- 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 account_emails (
+  user_id TEXT NOT NULL REFERENCES users(id),
+  email TEXT NOT NULL,
+  verified_at TEXT,
+  added_by TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (user_id, email)
+);
+-- An address names at most ONE account across the estate (the sign-in
+-- and recovery resolutions depend on it); the users.email UNIQUE covers
+-- the primaries, this index the additionals, and the store's writes
+-- check across both.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_account_emails_email ON account_emails (email);
+
+ALTER TABLE email_change_tokens ADD COLUMN kind TEXT NOT NULL DEFAULT 'change';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimlsmart/platform-server",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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

@@ -21,6 +21,8 @@
 import type { D1Database, D1PreparedStatement } from '@cloudflare/workers-types'
 import {
   DEMO_PASSWORD,
+  type AccountEmail,
+  type AddAccountEmailResult,
   type AdvanceCounterResult,
   type AuthUserPayload,
   type CompleteEmailChangeResult,
@@ -47,7 +49,10 @@ import {
   type OidcClient,
   type OidcClientLaunch,
   type OidcCode,
+  type OidcConsentGrant,
   type OidcKeyRow,
+  consentGrantCovers,
+  normalizeOidcScopeSet,
   type OpAccountErasure,
   type OpClientRoleAssignment,
   type OpLiveSession,
@@ -478,6 +483,65 @@ export class D1ServerStore implements ServerStore {
     return this.personalAccessTokenSupportEnsured
   }
 
+  // TODO.identity-features/12 (the remembered consent grants): the
+  // oidc_consent_grants table arrives with migration 0021 — a dev D1
+  // migrated from before it lacks the table, so the grant methods ensure
+  // it defensively (the ensurePersonalAccessTokenSupport posture,
+  // memoized per store).
+  private consentGrantSupportEnsured: Promise<void> | null = null
+
+  private ensureConsentGrantSupport(): Promise<void> {
+    if (!this.consentGrantSupportEnsured) {
+      this.consentGrantSupportEnsured = (async () => {
+        await this.db.prepare(
+          `CREATE TABLE IF NOT EXISTS oidc_consent_grants (
+             id TEXT PRIMARY KEY,
+             user_id TEXT NOT NULL REFERENCES users(id),
+             client_id TEXT NOT NULL,
+             scope TEXT NOT NULL,
+             created_at TEXT NOT NULL DEFAULT (datetime('now')),
+             revoked_at TEXT
+           )`,
+        ).run()
+        await this.db.prepare(
+          'CREATE UNIQUE INDEX IF NOT EXISTS idx_oidc_consent_grants_live ON oidc_consent_grants (user_id, client_id, scope) WHERE revoked_at IS NULL',
+        ).run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_oidc_consent_grants_user ON oidc_consent_grants (user_id)').run()
+      })()
+    }
+    return this.consentGrantSupportEnsured
+  }
+
+  // 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,
+  // so the address methods ensure them defensively (the
+  // ensureConsentGrantSupport posture, memoized per store).
+  private accountEmailSupportEnsured: Promise<void> | null = null
+
+  private ensureAccountEmailSupport(): Promise<void> {
+    if (!this.accountEmailSupportEnsured) {
+      this.accountEmailSupportEnsured = (async () => {
+        await this.db.prepare(
+          `CREATE TABLE IF NOT EXISTS account_emails (
+             user_id TEXT NOT NULL REFERENCES users(id),
+             email TEXT NOT NULL,
+             verified_at TEXT,
+             added_by TEXT,
+             created_at TEXT NOT NULL DEFAULT (datetime('now')),
+             PRIMARY KEY (user_id, email)
+           )`,
+        ).run()
+        await this.db.prepare('CREATE UNIQUE INDEX IF NOT EXISTS idx_account_emails_email ON account_emails (email)').run()
+        const tokenCols = await this.db.prepare('PRAGMA table_info(email_change_tokens)').all<{ name: string }>()
+        if (!tokenCols.results.some(c => c.name === 'kind')) {
+          await this.db.prepare("ALTER TABLE email_change_tokens ADD COLUMN kind TEXT NOT NULL DEFAULT 'change'").run()
+        }
+      })()
+    }
+    return this.accountEmailSupportEnsured
+  }
+
   // ── users / sessions ─────────────────────────────────────────────
 
   async seedDemoAccounts(): Promise<void> {
@@ -1125,6 +1189,78 @@ export class D1ServerStore implements ServerStore {
     ).run()
   }
 
+  // ── the remembered consent grants (TODO.identity-features/12) ─────
+
+  private static toConsentGrant(row: Record<string, unknown>): OidcConsentGrant {
+    return {
+      id: row.id as string,
+      userId: row.user_id as string,
+      clientId: row.client_id as string,
+      scope: row.scope as string,
+      createdAt: D1ServerStore.storeTimeToIso(row.created_at as string)!,
+      revokedAt: D1ServerStore.storeTimeToIso((row.revoked_at as string | null) ?? null),
+    }
+  }
+
+  async getConsentGrant(userId: string, clientId: string, scope: string): Promise<OidcConsentGrant | null> {
+    await this.ensureConsentGrantSupport()
+    // The skip check's coverage math is the store.ts helper's, never a
+    // LIKE scan: the account's live rows for the client, the freshest
+    // covering grant wins.
+    const res = await this.stmt(
+      'SELECT * FROM oidc_consent_grants WHERE user_id = ? AND client_id = ? AND revoked_at IS NULL ORDER BY created_at DESC, rowid DESC',
+      userId, clientId,
+    ).all<Record<string, unknown>>()
+    for (const row of res.results) {
+      if (consentGrantCovers(row.scope as string, scope)) return D1ServerStore.toConsentGrant(row)
+    }
+    return null
+  }
+
+  async recordConsentGrant(input: { userId: string; clientId: string; scope: string }): Promise<OidcConsentGrant> {
+    await this.ensureConsentGrantSupport()
+    const scope = normalizeOidcScopeSet(input.scope)
+    // The upsert targets the partial unique index: a live triple's row
+    // refreshes its stamp (the re-affirmed consent); a REVOKED triple's
+    // re-allow falls out of the index's predicate and inserts FRESH —
+    // the history survives.
+    await this.stmt(
+      `INSERT INTO oidc_consent_grants (id, user_id, client_id, scope)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT (user_id, client_id, scope) WHERE revoked_at IS NULL
+       DO UPDATE SET created_at = datetime('now')`,
+      crypto.randomUUID(), input.userId, input.clientId, scope,
+    ).run()
+    const row = await this.stmt(
+      'SELECT * FROM oidc_consent_grants WHERE user_id = ? AND client_id = ? AND scope = ? AND revoked_at IS NULL',
+      input.userId, input.clientId, scope,
+    ).first<Record<string, unknown>>()
+    if (!row) throw new Error('recordConsentGrant: the upsert left no live row')
+    return D1ServerStore.toConsentGrant(row)
+  }
+
+  async listConsentGrants(userId: string): Promise<OidcConsentGrant[]> {
+    await this.ensureConsentGrantSupport()
+    // The console's list: the LIVE grants only (the revoked rows ride the
+    // audit chain), newest first — created_at is second-resolution, the
+    // rowid breaks the tie.
+    const res = await this.stmt(
+      'SELECT * FROM oidc_consent_grants WHERE user_id = ? AND revoked_at IS NULL ORDER BY created_at DESC, rowid DESC',
+      userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toConsentGrant)
+  }
+
+  /** The guarded revoke: the owner's LIVE row flips, once. */
+  async revokeConsentGrant(id: string, userId: string): Promise<boolean> {
+    await this.ensureConsentGrantSupport()
+    const res = await this.stmt(
+      "UPDATE oidc_consent_grants SET revoked_at = datetime('now') WHERE id = ? AND user_id = ? AND revoked_at IS NULL",
+      id, userId,
+    ).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
   // ── the upstream providers (TODO.identity/08) ─────────────────────
   // The provider + link rows port directly (D1 is SQLite).
 
@@ -1270,6 +1406,13 @@ export class D1ServerStore implements ServerStore {
     createdBy?: string | null
   }): Promise<UserAdminRow | null> {
     const id = crypto.randomUUID()
+    // TODO.identity-features/01: the address must be free across BOTH
+    // address tables — an additional on another account blocks the
+    // address as a new account's primary (an address names at most one
+    // account; the users.email UNIQUE remains the race backstop).
+    await this.ensureAccountEmailSupport()
+    const additional = await this.stmt('SELECT user_id FROM account_emails WHERE email = ?', input.email.trim().toLowerCase()).first<{ user_id: string }>()
+    if (additional) return null
     try {
       await this.stmt(
         "INSERT INTO users (id, email, name, provider, role) VALUES (?, ?, ?, 'password', ?)",
@@ -1284,14 +1427,28 @@ export class D1ServerStore implements ServerStore {
   }
 
   /** The password sign-in's lookup: the credential + the active flag, by
-   *  (normalized) email. The credential's EXISTENCE is the qualifier. */
+   *  (normalized) email. The credential's EXISTENCE is the qualifier.
+   *  TODO.identity-features/01: the address resolves by ANY of the
+   *  account's VERIFIED addresses — the primary first (the primary owner
+   *  always wins, the deterministic rule), then a proven account_emails
+   *  row; an unverified additional never resolves. */
   async getPasswordLogin(email: string): Promise<{ userId: string; hash: string; active: boolean } | null> {
-    const row = await this.stmt(
+    await this.ensureAccountEmailSupport()
+    const normalized = email.trim().toLowerCase()
+    let row = await this.stmt(
       `SELECT u.id AS user_id, u.active AS active, p.hash AS hash
        FROM users u JOIN passwords p ON p.user_id = u.id
        WHERE u.email = ?`,
-      email.trim().toLowerCase(),
+      normalized,
     ).first<{ user_id: string; active: number; hash: string }>()
+    if (!row) {
+      row = await this.stmt(
+        `SELECT u.id AS user_id, u.active AS active, p.hash AS hash
+         FROM users u JOIN passwords p ON p.user_id = u.id
+         WHERE u.id = (SELECT user_id FROM account_emails WHERE email = ? AND verified_at IS NOT NULL)`,
+        normalized,
+      ).first<{ user_id: string; active: number; hash: string }>()
+    }
     if (!row) return null
     return { userId: row.user_id, hash: row.hash, active: row.active !== 0 }
   }
@@ -1512,6 +1669,14 @@ export class D1ServerStore implements ServerStore {
     // again).
     await this.ensurePersonalAccessTokenSupport()
     const personalAccessTokens = await this.stmt('DELETE FROM personal_access_tokens WHERE user_id = ?', userId).run()
+    // TODO.identity-features/12: the remembered consent grants die with
+    // the account (a tombstone never skips a consent page again).
+    await this.ensureConsentGrantSupport()
+    const consentGrants = await this.stmt('DELETE FROM oidc_consent_grants WHERE user_id = ?', userId).run()
+    // TODO.identity-features/01: the additional addresses die with the
+    // account (a tombstone's addresses never resolve a sign-in again).
+    await this.ensureAccountEmailSupport()
+    const emails = await this.stmt('DELETE FROM account_emails WHERE user_id = ?', userId).run()
     await this.stmt(
       `UPDATE users SET
          email = ?, name = 'Deleted account', provider = 'erased',
@@ -1529,13 +1694,21 @@ export class D1ServerStore implements ServerStore {
       factors: (passkeys.meta.changes ?? 0) + (totp.meta.changes ?? 0) + (recovery.meta.changes ?? 0)
         + (challenges.meta.changes ?? 0) + (mfa.meta.changes ?? 0),
       personalAccessTokens: personalAccessTokens.meta.changes ?? 0,
+      consentGrants: consentGrants.meta.changes ?? 0,
+      emails: emails.meta.changes ?? 0,
     }
   }
 
   /** The registry's edit act (name/email). The email UNIQUE conflict
-   *  throws 'unique' (the route maps it to a 409, never a silent take). */
+   *  throws 'unique' (the route maps it to a 409, never a silent take).
+   *  TODO.identity-features/01: the conflict read spans BOTH address
+   *  tables — an additional row (on any account, this one included)
+   *  holds the address too. */
   async updateOpAccount(id: string, input: { name?: string; email?: string }): Promise<boolean> {
     if (input.email !== undefined) {
+      await this.ensureAccountEmailSupport()
+      const additional = await this.stmt('SELECT user_id FROM account_emails WHERE email = ?', input.email.trim().toLowerCase()).first<{ user_id: string }>()
+      if (additional) throw new Error(`unique: ${input.email}`)
       try {
         // TODO.identity/06: an admin-set address never went through the
         // verify-new-email ceremony, so the verification state resets.
@@ -1608,29 +1781,46 @@ export class D1ServerStore implements ServerStore {
       userId: row.user_id as string,
       newEmail: row.new_email as string,
       deliveredBy: row.delivered_by === 'mailer' ? 'mailer' : 'shown',
+      // TODO.identity-features/01: rows predating the kind column (or a
+      // store over a pre-0022 database) read as the legacy ceremony.
+      kind: row.kind === 'add' ? 'add' : 'change',
       createdAt: row.created_at as string,
       expiresAt: row.expires_at as string,
       consumedAt: (row.consumed_at as string | null) ?? null,
     }
   }
 
-  /** Mint the ceremony's token; the account's earlier pending rows are
-   *  VOIDED first (only the newest link works). */
+  /** Mint the ceremony's token. The void rule keeps ONE live link per
+   *  ceremony target: a 'change' request voids the account's earlier
+   *  pending 'change' rows (only the newest change link works — the
+   *  pre-01 doctrine); an 'add' request voids the account's earlier
+   *  pending 'add' rows FOR THE SAME address (other addresses' links
+   *  stand). */
   async createEmailChangeToken(input: {
     token: string
     userId: string
     newEmail: string
     deliveredBy: 'mailer' | 'shown'
+    kind?: 'change' | 'add'
     ttlMs: number
   }): Promise<EmailChangeToken> {
-    await this.stmt(
-      "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND consumed_at IS NULL",
-      input.userId,
-    ).run()
+    await this.ensureAccountEmailSupport()
+    const kind = input.kind ?? 'change'
+    if (kind === 'change') {
+      await this.stmt(
+        "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND kind = 'change' AND consumed_at IS NULL",
+        input.userId,
+      ).run()
+    } else {
+      await this.stmt(
+        "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE user_id = ? AND kind = 'add' AND new_email = ? AND consumed_at IS NULL",
+        input.userId, input.newEmail.trim().toLowerCase(),
+      ).run()
+    }
     const expiresAt = new Date(Date.now() + input.ttlMs).toISOString()
     await this.stmt(
-      'INSERT INTO email_change_tokens (token, user_id, new_email, delivered_by, expires_at) VALUES (?, ?, ?, ?, ?)',
-      input.token, input.userId, input.newEmail.trim().toLowerCase(), input.deliveredBy, expiresAt,
+      'INSERT INTO email_change_tokens (token, user_id, new_email, delivered_by, kind, expires_at) VALUES (?, ?, ?, ?, ?, ?)',
+      input.token, input.userId, input.newEmail.trim().toLowerCase(), input.deliveredBy, kind, expiresAt,
     ).run()
     return (await this.getEmailChangeToken(input.token))!
   }
@@ -1640,12 +1830,15 @@ export class D1ServerStore implements ServerStore {
     return row ? D1ServerStore.toEmailChangeToken(row) : null
   }
 
-  /** The account's pending change (the newest live row), so the console
-   *  can show it. */
+  /** The account's pending PRIMARY change (the newest live 'change'
+   *  row), so the console can show it. The per-address verifications are
+   *  the account_emails rows' own state (verified_at NULL = waiting),
+   *  never a pending read here. */
   async getPendingEmailChange(userId: string): Promise<EmailChangeToken | null> {
+    await this.ensureAccountEmailSupport()
     const row = await this.stmt(
       `SELECT * FROM email_change_tokens
-       WHERE user_id = ? AND consumed_at IS NULL AND expires_at > datetime('now')
+       WHERE user_id = ? AND kind = 'change' AND consumed_at IS NULL AND expires_at > datetime('now')
        ORDER BY created_at DESC LIMIT 1`,
       userId,
     ).first<Record<string, unknown>>()
@@ -1653,20 +1846,34 @@ export class D1ServerStore implements ServerStore {
   }
 
   /** Complete the ceremony: consume ATOMICALLY (a presented link works
-   *  exactly once, expired or not), judge the expiry, re-check the
-   *  address's uniqueness (a conflict burns the token honestly), then
-   *  move the account's email. A 'mailer'-delivered token verifies the
-   *  address; a shown one never does. */
+   *  exactly once, expired or not), judge the expiry, then act on the
+   *  kind. 'change' (the pre-01 primary replacement): re-check the
+   *  address's uniqueness across BOTH address tables (a conflict burns
+   *  the token honestly — an additional row anywhere holds the address
+   *  too, this account's included), then move users.email. 'add' (the
+   *  per-address verification): the account_emails row landed unverified
+   *  at the request; the completion stamps it (a row removed meanwhile
+   *  burns the link as 'unknown'). A 'mailer'-delivered token verifies
+   *  the address; a shown one never does. */
   async completeEmailChange(token: string): Promise<CompleteEmailChangeResult> {
+    await this.ensureAccountEmailSupport()
     const res = await this.stmt(
       "UPDATE email_change_tokens SET consumed_at = datetime('now') WHERE token = ? AND consumed_at IS NULL", token,
     ).run()
     if ((res.meta.changes ?? 0) === 0) return { kind: 'unknown' }
     const row = (await this.getEmailChangeToken(token))!
     if (new Date(row.expiresAt).getTime() <= Date.now()) return { kind: 'expired' }
+    const verified = row.deliveredBy === 'mailer'
+    if (row.kind === 'add') {
+      const standing = await this.stmt('SELECT 1 AS ok FROM account_emails WHERE user_id = ? AND email = ?', row.userId, row.newEmail).first<{ ok: number }>()
+      if (!standing) return { kind: 'unknown' }
+      if (verified) await this.markAccountEmailVerified(row.userId, row.newEmail)
+      return { kind: 'ok', userId: row.userId, newEmail: row.newEmail, verified }
+    }
     const taken = await this.stmt('SELECT id FROM users WHERE email = ?', row.newEmail).first<{ id: string }>()
     if (taken) return { kind: 'conflict' }
-    const verified = row.deliveredBy === 'mailer'
+    const takenAdditional = await this.stmt('SELECT user_id FROM account_emails WHERE email = ?', row.newEmail).first<{ user_id: string }>()
+    if (takenAdditional) return { kind: 'conflict' }
     await this.stmt(
       `UPDATE users SET email = ?, email_verified_at = ${verified ? "datetime('now')" : 'NULL'} WHERE id = ?`,
       row.newEmail, row.userId,
@@ -1674,6 +1881,116 @@ export class D1ServerStore implements ServerStore {
     return { kind: 'ok', userId: row.userId, newEmail: row.newEmail, verified }
   }
 
+  // ── multiple emails per account (TODO.identity-features/01) ────────
+
+  private static toAccountEmail(row: Record<string, unknown>, isPrimary: boolean): AccountEmail {
+    return {
+      userId: row.user_id as string,
+      email: row.email as string,
+      verifiedAt: (row.verified_at as string | null) ?? null,
+      isPrimary,
+      addedBy: (row.added_by as string | null) ?? null,
+      createdAt: row.created_at as string,
+    }
+  }
+
+  /** The account's addresses: the PRIMARY first (the users row's email +
+   *  its verification stamp), then the additional account_emails rows
+   *  (oldest first). */
+  async listAccountEmails(userId: string): Promise<AccountEmail[]> {
+    await this.ensureAccountEmailSupport()
+    const primary = await this.stmt(
+      'SELECT id AS user_id, email, email_verified_at AS verified_at, created_at FROM users WHERE id = ?', userId,
+    ).first<Record<string, unknown>>()
+    const res = await this.stmt(
+      'SELECT * FROM account_emails WHERE user_id = ? ORDER BY created_at, email', userId,
+    ).all<Record<string, unknown>>()
+    const out: AccountEmail[] = []
+    if (primary) out.push(D1ServerStore.toAccountEmail(primary, true))
+    out.push(...res.results.map(r => D1ServerStore.toAccountEmail(r, false)))
+    return out
+  }
+
+  /** Resolve the account by ANY of its addresses: the primary always
+   *  names it (and the primary owner always wins — the deterministic
+   *  rule); an additional ONLY when verified. */
+  async findUserByAnyEmail(email: string): Promise<AuthUserPayload | null> {
+    await this.ensureAccountEmailSupport()
+    const normalized = email.trim().toLowerCase()
+    const primary = await this.stmt('SELECT * FROM users WHERE email = ?', normalized).first<UserRecord>()
+    if (primary) return toPayload(primary)
+    const owner = await this.stmt(
+      'SELECT user_id FROM account_emails WHERE email = ? AND verified_at IS NOT NULL', normalized,
+    ).first<{ user_id: string }>()
+    if (!owner) return null
+    const user = await this.stmt('SELECT * FROM users WHERE id = ?', owner.user_id).first<UserRecord>()
+    return user ? toPayload(user) : null
+  }
+
+  /** Add an ADDITIONAL address (normalized lowercase; the row lands
+   *  UNVERIFIED). The account's own existing row answers 'present' (the
+   *  idempotent re-add); any other hold of the address — a primary
+   *  anywhere (this account's included) or another account's additional
+   *  — answers 'conflict'. The unique index is the race backstop. */
+  async addAccountEmail(userId: string, email: string, addedBy?: string | null): Promise<AddAccountEmailResult> {
+    await this.ensureAccountEmailSupport()
+    const normalized = email.trim().toLowerCase()
+    const takenPrimary = await this.stmt('SELECT id FROM users WHERE email = ?', normalized).first<{ id: string }>()
+    if (takenPrimary) return 'conflict'
+    const existing = await this.stmt('SELECT user_id FROM account_emails WHERE email = ?', normalized).first<{ user_id: string }>()
+    if (existing) return existing.user_id === userId ? 'present' : 'conflict'
+    try {
+      await this.stmt(
+        'INSERT INTO account_emails (user_id, email, added_by) VALUES (?, ?, ?)',
+        userId, normalized, addedBy ?? null,
+      ).run()
+    } catch (e) {
+      if (String((e as Error).message).includes('UNIQUE')) return 'conflict'
+      throw e
+    }
+    return 'added'
+  }
+
+  /** The verification ceremony's stamp on the account's OWN row: the
+   *  guarded UPDATE flips verified_at, once. */
+  async markAccountEmailVerified(userId: string, email: string): Promise<boolean> {
+    await this.ensureAccountEmailSupport()
+    const res = await this.stmt(
+      "UPDATE account_emails SET verified_at = datetime('now') WHERE user_id = ? AND email = ? AND verified_at IS NULL",
+      userId, email.trim().toLowerCase(),
+    ).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  /** Promote a VERIFIED additional to primary: the promoted address
+   *  becomes users.email with its verification stamp; the outgoing
+   *  primary takes the row's place in account_emails with ITS stamp
+   *  (it stays a verified additional — sign-in by it keeps working). */
+  async setPrimaryAccountEmail(userId: string, email: string): Promise<'ok' | 'unknown' | 'unverified'> {
+    await this.ensureAccountEmailSupport()
+    const normalized = email.trim().toLowerCase()
+    const row = await this.stmt('SELECT * FROM account_emails WHERE user_id = ? AND email = ?', userId, normalized).first<Record<string, unknown>>()
+    if (!row) return 'unknown'
+    if (!row.verified_at) return 'unverified'
+    const current = await this.stmt('SELECT email, email_verified_at FROM users WHERE id = ?', userId).first<{ email: string; email_verified_at: string | null }>()
+    if (!current) return 'unknown'
+    await this.stmt('UPDATE users SET email = ?, email_verified_at = ? WHERE id = ?', normalized, row.verified_at as string, userId).run()
+    await this.stmt('DELETE FROM account_emails WHERE user_id = ? AND email = ?', userId, normalized).run()
+    await this.stmt('INSERT INTO account_emails (user_id, email, verified_at) VALUES (?, ?, ?)', userId, current.email, current.email_verified_at).run()
+    return 'ok'
+  }
+
+  /** Remove an ADDITIONAL address. The primary refuses honestly
+   *  ('primary' — promote another address first). */
+  async removeAccountEmail(userId: string, email: string): Promise<'ok' | 'primary' | 'unknown'> {
+    await this.ensureAccountEmailSupport()
+    const normalized = email.trim().toLowerCase()
+    const current = await this.stmt('SELECT email FROM users WHERE id = ?', userId).first<{ email: string }>()
+    if (current?.email === normalized) return 'primary'
+    const res = await this.stmt('DELETE FROM account_emails WHERE user_id = ? AND email = ?', userId, normalized).run()
+    return (res.meta.changes ?? 0) > 0 ? 'ok' : 'unknown'
+  }
+
   // ── strong authentication: the factor registry (TODO.identity-sso/02 + /03) ──
   // The same SQL as the SQLite half (store/sqlite/factors-store.ts): the
   // one-time consumes are guarded UPDATEs, the counter advance is the

package/src/store/sqlite/consent-grants-store.ts

@@ -0,0 +1,85 @@
+// ═══════════════════════════════════════════════════════════════════
+// The remembered consent grants' SQLite half (TODO.identity-features/12)
+// — the sync implementations behind the ServerStore consent-grant
+// methods (sqlite-server-store.ts delegates here one-for-one, the
+// pat-store.ts pattern). The D1 store implements the same surface in
+// d1.ts.
+//
+// The doctrines carried:
+//   - ONE LIVE grant per (user, client, scope set): the partial unique
+//     index (migration 0021) is the backstop; the record path's upsert
+//     targets it, so a repeat allow refreshes the live row's stamp and a
+//     REVOKED triple's re-allow lands a fresh row (the history survives);
+//   - the scope cell is the CANONICAL spelling (normalizeOidcScopeSet) —
+//     written normalized, read defensively (a hand-edited row still reads
+//     as a set, never trusted as a string match);
+//   - the revoke is a GUARDED update (the owner's live row flips, once);
+//   - the erasure (op-accounts-store.ts's eraseOpAccount) removes the
+//     rows outright — a dead account's grants die with it.
+//
+// NODE-ONLY: better-sqlite3 through ./store's getDb. The Worker bundle
+// never sees this module.
+// ═══════════════════════════════════════════════════════════════════
+
+import { randomUUID } from 'crypto'
+import { getDb } from './store'
+import { storeTimeToIso } from './factors-store'
+import { consentGrantCovers, normalizeOidcScopeSet, type OidcConsentGrant } from '../../store'
+
+function toConsentGrant(row: Record<string, unknown>): OidcConsentGrant {
+  return {
+    id: row.id as string,
+    userId: row.user_id as string,
+    clientId: row.client_id as string,
+    scope: row.scope as string,
+    createdAt: storeTimeToIso(row.created_at as string)!,
+    revokedAt: storeTimeToIso((row.revoked_at as string | null) ?? null),
+  }
+}
+
+/** The authorize endpoint's remembered-consent read: the account's LIVE
+ *  grant for this client whose scope set COVERS the requested set (the
+ *  freshest first, when several cover). */
+export function getConsentGrant(userId: string, clientId: string, scope: string): OidcConsentGrant | null {
+  const rows = getDb().prepare(
+    'SELECT * FROM oidc_consent_grants WHERE user_id = ? AND client_id = ? AND revoked_at IS NULL ORDER BY created_at DESC, rowid DESC',
+  ).all(userId, clientId) as Array<Record<string, unknown>>
+  for (const row of rows) {
+    if (consentGrantCovers(row.scope as string, scope)) return toConsentGrant(row)
+  }
+  return null
+}
+
+/** The consent decision's remember (the allow): the upsert on the live
+ *  triple refreshes the stamp; a revoked triple's re-allow inserts fresh
+ *  (the partial unique index's predicate keeps the revoked row out of the
+ *  collision). Answers the live row. */
+export function recordConsentGrant(input: { userId: string; clientId: string; scope: string }): OidcConsentGrant {
+  const scope = normalizeOidcScopeSet(input.scope)
+  getDb().prepare(
+    `INSERT INTO oidc_consent_grants (id, user_id, client_id, scope)
+     VALUES (?, ?, ?, ?)
+     ON CONFLICT (user_id, client_id, scope) WHERE revoked_at IS NULL
+     DO UPDATE SET created_at = datetime('now')`,
+  ).run(randomUUID(), input.userId, input.clientId, scope)
+  const row = getDb().prepare(
+    'SELECT * FROM oidc_consent_grants WHERE user_id = ? AND client_id = ? AND scope = ? AND revoked_at IS NULL',
+  ).get(input.userId, input.clientId, scope) as Record<string, unknown> | undefined
+  if (!row) throw new Error('recordConsentGrant: the upsert left no live row')
+  return toConsentGrant(row)
+}
+
+/** The console's list: the account's LIVE grants, newest first. */
+export function listConsentGrants(userId: string): OidcConsentGrant[] {
+  const rows = getDb().prepare(
+    'SELECT * FROM oidc_consent_grants WHERE user_id = ? AND revoked_at IS NULL ORDER BY created_at DESC, rowid DESC',
+  ).all(userId) as Array<Record<string, unknown>>
+  return rows.map(toConsentGrant)
+}
+
+/** The guarded revoke: the owner's LIVE row flips, once. */
+export function revokeConsentGrant(id: string, userId: string): boolean {
+  return getDb().prepare(
+    "UPDATE oidc_consent_grants SET revoked_at = datetime('now') WHERE id = ? AND user_id = ? AND revoked_at IS NULL",
+  ).run(id, userId).changes > 0
+}