@oimlsmart/platform-server 0.1.5 → 0.1.7

package/migrations/0020_personal_access_tokens.sql

@@ -0,0 +1,51 @@
+-- Migration 0020 — the personal access tokens (TODO.identity-features/08,
+-- the GitHub fine-grained pattern mapped to the estate): an ACCOUNT-minted
+-- developer credential that NEVER rides a request directly — it exchanges
+-- at the OP's token endpoint (the RFC 8693 grant, subject_token_type
+-- urn:oimlsmart:params:oauth:token-type:pat) for a short-lived OP JWT, so
+-- every relying party keeps validating the one token shape.
+--
+-- The store doctrines (the recovery codes' precedent, migration 0012):
+--   - the plaintext shows ONCE at mint; the row holds only the SHA-256 of
+--     the presented token (256 bits of random — an unsalted hash resists
+--     the offline attack), and token_hash IS the exchange's lookup key
+--     (UNIQUE doubles as its index);
+--   - token_prefix is the display fragment ('ospt_' + the leading
+--     characters — the console's row label, GitHub's list convention),
+--     never enough to authenticate;
+--   - expiration is MANDATORY (expires_at NOT NULL — the fine-grained
+--     lesson: no permanent tokens);
+--   - the audit chain rides the row conservatively: last_used_at +
+--     last_exchange_audit_at carry the exchange path's THROTTLED
+--     heartbeat (never a write per exchange), expiry_notified_at the
+--     expiry-soon mailer's one-shot mark;
+--   - revocation flips revoked_at/revoked_by (the row stays — the audit
+--     + the org inventory carry the history); the account erasure removes
+--     the rows outright (a dead account's tokens die with it).
+-- 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 personal_access_tokens (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id),
+  name TEXT NOT NULL,
+  token_hash TEXT NOT NULL,
+  token_prefix TEXT NOT NULL,
+  -- The granted scope set (JSON array of '<service>:<action-class>' — the
+  -- kernel's PAT grammar; narrowing-only against the holder's standing).
+  scopes TEXT NOT NULL DEFAULT '[]',
+  -- The org context the token was minted under (the console session's
+  -- active org — the token acts within the account's active-org
+  -- visibility, never wider). NULL = the account's primary context.
+  org_context TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  expires_at TEXT NOT NULL,
+  last_used_at TEXT,
+  last_exchange_audit_at TEXT,
+  expiry_notified_at TEXT,
+  revoked_at TEXT,
+  revoked_by TEXT,
+  UNIQUE (token_hash)
+);
+CREATE INDEX IF NOT EXISTS idx_personal_access_tokens_user ON personal_access_tokens (user_id);

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/package.json

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

@@ -47,7 +47,10 @@ import {
   type OidcClient,
   type OidcClientLaunch,
   type OidcCode,
+  type OidcConsentGrant,
   type OidcKeyRow,
+  consentGrantCovers,
+  normalizeOidcScopeSet,
   type OpAccountErasure,
   type OpClientRoleAssignment,
   type OpLiveSession,
@@ -62,6 +65,7 @@ import {
   type InstrumentRegistration,
   type InstrumentRegistrationLifecycle,
   type InstrumentRegistrationScopeStatus,
+  type PersonalAccessToken,
   type PlatformEvent,
   resolveOrgContext,
   parseOrgMemberCone,
@@ -442,6 +446,70 @@ export class D1ServerStore implements ServerStore {
     return this.oidcColumnsEnsured
   }
 
+  // TODO.identity-features/08 (the personal access tokens): the
+  // personal_access_tokens table arrives with migration 0020 — a dev D1
+  // migrated from before it lacks the table, so the PAT methods ensure
+  // it defensively (the ensureOrgRegistrySupport posture, memoized per
+  // store).
+  private personalAccessTokenSupportEnsured: Promise<void> | null = null
+
+  private ensurePersonalAccessTokenSupport(): Promise<void> {
+    if (!this.personalAccessTokenSupportEnsured) {
+      this.personalAccessTokenSupportEnsured = (async () => {
+        await this.db.prepare(
+          `CREATE TABLE IF NOT EXISTS personal_access_tokens (
+             id TEXT PRIMARY KEY,
+             user_id TEXT NOT NULL REFERENCES users(id),
+             name TEXT NOT NULL,
+             token_hash TEXT NOT NULL,
+             token_prefix TEXT NOT NULL,
+             scopes TEXT NOT NULL DEFAULT '[]',
+             org_context TEXT,
+             created_at TEXT NOT NULL DEFAULT (datetime('now')),
+             expires_at TEXT NOT NULL,
+             last_used_at TEXT,
+             last_exchange_audit_at TEXT,
+             expiry_notified_at TEXT,
+             revoked_at TEXT,
+             revoked_by TEXT,
+             UNIQUE (token_hash)
+           )`,
+        ).run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_personal_access_tokens_user ON personal_access_tokens (user_id)').run()
+      })()
+    }
+    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
+  }
+
   // ── users / sessions ─────────────────────────────────────────────
 
   async seedDemoAccounts(): Promise<void> {
@@ -1089,6 +1157,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).
 
@@ -1471,6 +1611,15 @@ export class D1ServerStore implements ServerStore {
     const recovery = await this.stmt('DELETE FROM recovery_codes WHERE user_id = ?', userId).run()
     const challenges = await this.stmt('DELETE FROM webauthn_challenges WHERE user_id = ?', userId).run()
     const mfa = await this.stmt('DELETE FROM mfa_pending WHERE user_id = ?', userId).run()
+    // TODO.identity-features/08: the developer tokens die with the
+    // account (the hashed rows go — a tombstone's tokens never exchange
+    // 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()
     await this.stmt(
       `UPDATE users SET
          email = ?, name = 'Deleted account', provider = 'erased',
@@ -1487,6 +1636,8 @@ export class D1ServerStore implements ServerStore {
       tokens: (passwords.meta.changes ?? 0) + (enrollments.meta.changes ?? 0) + (emailChanges.meta.changes ?? 0),
       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,
     }
   }
 
@@ -1843,6 +1994,92 @@ export class D1ServerStore implements ServerStore {
     return row ? D1ServerStore.toMfaPending(row) : null
   }
 
+  // ── the personal access tokens (TODO.identity-features/08) ─────────
+
+  async createPersonalAccessToken(input: {
+    id: string
+    userId: string
+    name: string
+    tokenHash: string
+    tokenPrefix: string
+    scopes: string[]
+    orgContext: string | null
+    expiresAt: string
+  }): Promise<PersonalAccessToken> {
+    await this.ensurePersonalAccessTokenSupport()
+    await this.stmt(
+      `INSERT INTO personal_access_tokens
+         (id, user_id, name, token_hash, token_prefix, scopes, org_context, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      input.id, input.userId, input.name, input.tokenHash, input.tokenPrefix,
+      JSON.stringify(input.scopes), input.orgContext, input.expiresAt,
+    ).run()
+    return (await this.getPersonalAccessToken(input.id))!
+  }
+
+  async listPersonalAccessTokens(userId: string): Promise<PersonalAccessToken[]> {
+    await this.ensurePersonalAccessTokenSupport()
+    // created_at is second-resolution (datetime('now')) — the rowid
+    // breaks the tie so the newest mint leads even within one second.
+    const res = await this.stmt(
+      'SELECT * FROM personal_access_tokens WHERE user_id = ? ORDER BY created_at DESC, rowid DESC', userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toPersonalAccessToken)
+  }
+
+  async listOrgPersonalAccessTokens(orgId: string): Promise<PersonalAccessToken[]> {
+    await this.ensurePersonalAccessTokenSupport()
+    // The org inventory: every token whose holder carries a membership
+    // row for the org (ANY state — a disabled member's live token is
+    // exactly what the oversight surface hunts). org_memberships arrived
+    // with 0011, long before the PAT table — the join needs no ensure of
+    // its own beyond the membership support's.
+    await this.ensureMembershipSupport()
+    const res = await this.stmt(
+      `SELECT p.* FROM personal_access_tokens p
+       JOIN org_memberships m ON m.user_id = p.user_id
+       WHERE m.org_id = ?
+       ORDER BY p.created_at DESC, p.id`,
+      orgId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toPersonalAccessToken)
+  }
+
+  async getPersonalAccessToken(id: string): Promise<PersonalAccessToken | null> {
+    await this.ensurePersonalAccessTokenSupport()
+    const row = await this.stmt('SELECT * FROM personal_access_tokens WHERE id = ?', id).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toPersonalAccessToken(row) : null
+  }
+
+  async findPersonalAccessTokenByHash(tokenHash: string): Promise<PersonalAccessToken | null> {
+    await this.ensurePersonalAccessTokenSupport()
+    const row = await this.stmt('SELECT * FROM personal_access_tokens WHERE token_hash = ?', tokenHash).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toPersonalAccessToken(row) : null
+  }
+
+  async revokePersonalAccessToken(id: string, userId: string, revokedBy: string): Promise<boolean> {
+    await this.ensurePersonalAccessTokenSupport()
+    const res = await this.stmt(
+      "UPDATE personal_access_tokens SET revoked_at = datetime('now'), revoked_by = ? WHERE id = ? AND user_id = ? AND revoked_at IS NULL",
+      revokedBy, id, userId,
+    ).run()
+    return (res.meta.changes ?? 0) > 0
+  }
+
+  async stampPersonalAccessTokenUse(
+    id: string,
+    stamps: { usedAt: string; auditAt?: string | null; expiryNotifiedAt?: string | null },
+  ): Promise<void> {
+    await this.ensurePersonalAccessTokenSupport()
+    await this.stmt('UPDATE personal_access_tokens SET last_used_at = ? WHERE id = ?', stamps.usedAt, id).run()
+    if (stamps.auditAt) {
+      await this.stmt('UPDATE personal_access_tokens SET last_exchange_audit_at = ? WHERE id = ?', stamps.auditAt, id).run()
+    }
+    if (stamps.expiryNotifiedAt) {
+      await this.stmt('UPDATE personal_access_tokens SET expiry_notified_at = ? WHERE id = ?', stamps.expiryNotifiedAt, id).run()
+    }
+  }
+
   // ── organization administration (TODO.identity/10) ────────────────
 
   /** The store's time columns arrive in two shapes (datetime('now')'s
@@ -1910,6 +2147,28 @@ export class D1ServerStore implements ServerStore {
     }
   }
 
+  /** The personal_access_tokens row → the seam's shape (TODO.identity-
+   *  features/08). The scopes cell parses defensively — a hand-edited
+   *  row's malformed JSON reads as the empty set, never trusted. */
+  private static toPersonalAccessToken(row: Record<string, unknown>): PersonalAccessToken {
+    return {
+      id: row.id as string,
+      userId: row.user_id as string,
+      name: row.name as string,
+      tokenHash: row.token_hash as string,
+      tokenPrefix: row.token_prefix as string,
+      scopes: parseRoles((row.scopes as string | null) ?? null) ?? [],
+      orgContext: (row.org_context as string | null) ?? null,
+      createdAt: D1ServerStore.storeTimeToIso(row.created_at as string)!,
+      expiresAt: D1ServerStore.storeTimeToIso(row.expires_at as string)!,
+      lastUsedAt: D1ServerStore.storeTimeToIso((row.last_used_at as string | null) ?? null),
+      lastExchangeAuditAt: D1ServerStore.storeTimeToIso((row.last_exchange_audit_at as string | null) ?? null),
+      expiryNotifiedAt: D1ServerStore.storeTimeToIso((row.expiry_notified_at as string | null) ?? null),
+      revokedAt: D1ServerStore.storeTimeToIso((row.revoked_at as string | null) ?? null),
+      revokedBy: (row.revoked_by as string | null) ?? null,
+    }
+  }
+
   private static toOrgJoinRequest(row: Record<string, unknown>): OrgJoinRequest {
     return {
       id: row.id as string,

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
+}

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

@@ -312,6 +312,8 @@ export function eraseOpAccount(userId: string): {
   memberships: number
   tokens: number
   factors: number
+  personalAccessTokens: number
+  consentGrants: number
 } | null {
   const db = getDb()
   const row = db.prepare('SELECT 1 AS ok FROM users WHERE id = ?').get(userId)
@@ -335,6 +337,12 @@ export function eraseOpAccount(userId: string): {
     db.prepare('DELETE FROM recovery_codes WHERE user_id = ?').run(userId).changes +
     db.prepare('DELETE FROM webauthn_challenges WHERE user_id = ?').run(userId).changes +
     db.prepare('DELETE FROM mfa_pending WHERE user_id = ?').run(userId).changes
+  // TODO.identity-features/08: the developer tokens die with the account
+  // (the hashed rows go — a tombstone's tokens never exchange again).
+  const personalAccessTokens = db.prepare('DELETE FROM personal_access_tokens WHERE user_id = ?').run(userId).changes
+  // TODO.identity-features/12: the remembered consent grants die with the
+  // account (a tombstone never skips a consent page again).
+  const consentGrants = db.prepare('DELETE FROM oidc_consent_grants WHERE user_id = ?').run(userId).changes
   db.prepare(
     `UPDATE users SET
        email = ?, name = 'Deleted account', provider = 'erased',
@@ -342,7 +350,7 @@ export function eraseOpAccount(userId: string): {
        avatar_url = NULL, email_verified_at = NULL, active = 0
      WHERE id = ?`,
   ).run(`deleted-${userId}@erased.invalid`, userId)
-  return { ...revoked, links, clientRoles, memberships, tokens, factors }
+  return { ...revoked, links, clientRoles, memberships, tokens, factors, personalAccessTokens, consentGrants }
 }
 
 /** The last OP-side sign-in per account, FROM THE AUDIT CHAIN: the

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

@@ -0,0 +1,127 @@
+// ═══════════════════════════════════════════════════════════════════
+// The personal access tokens' SQLite half (TODO.identity-features/08) —
+// the sync implementations behind the ServerStore PAT methods
+// (sqlite-server-store.ts delegates here one-for-one, the
+// factors-store.ts pattern). The D1 store implements the same surface
+// in d1.ts.
+//
+// The doctrines carried:
+//   - the plaintext NEVER crosses the seam: the row holds the SHA-256
+//     (token_hash, the exchange's UNIQUE lookup key) + the display
+//     prefix, and no read projects the hash onto a list surface;
+//   - the revoke is a GUARDED update (the live row, the owner's) — a
+//     replay or a foreign owner answers false, the row stays for the
+//     audit + the org inventory;
+//   - the erasure (op-accounts-store.ts's eraseOpAccount) removes the
+//     rows outright — a dead account's tokens die with it.
+//
+// NODE-ONLY: better-sqlite3 through ./store's getDb. The Worker bundle
+// never sees this module.
+// ═══════════════════════════════════════════════════════════════════
+
+import { getDb } from './store'
+import { storeTimeToIso } from './factors-store'
+import type { PersonalAccessToken } from '../../store'
+
+/** The row → the seam's shape. The scopes cell parses defensively (a
+ *  hand-edited row's malformed JSON reads as the empty set — never
+ *  trusted, never breaking the read). */
+function toPersonalAccessToken(row: Record<string, unknown>): PersonalAccessToken {
+  let scopes: string[] = []
+  try {
+    const parsed = JSON.parse((row.scopes as string | null) ?? '[]') as unknown
+    if (Array.isArray(parsed)) scopes = parsed.filter((s): s is string => typeof s === 'string')
+  } catch { /* a malformed scopes cell reads as none — the token exchanges nothing */ }
+  return {
+    id: row.id as string,
+    userId: row.user_id as string,
+    name: row.name as string,
+    tokenHash: row.token_hash as string,
+    tokenPrefix: row.token_prefix as string,
+    scopes,
+    orgContext: (row.org_context as string | null) ?? null,
+    createdAt: storeTimeToIso(row.created_at as string)!,
+    expiresAt: storeTimeToIso(row.expires_at as string)!,
+    lastUsedAt: storeTimeToIso((row.last_used_at as string | null) ?? null),
+    lastExchangeAuditAt: storeTimeToIso((row.last_exchange_audit_at as string | null) ?? null),
+    expiryNotifiedAt: storeTimeToIso((row.expiry_notified_at as string | null) ?? null),
+    revokedAt: storeTimeToIso((row.revoked_at as string | null) ?? null),
+    revokedBy: (row.revoked_by as string | null) ?? null,
+  }
+}
+
+export function createPersonalAccessToken(input: {
+  id: string
+  userId: string
+  name: string
+  tokenHash: string
+  tokenPrefix: string
+  scopes: string[]
+  orgContext: string | null
+  expiresAt: string
+}): PersonalAccessToken {
+  getDb().prepare(
+    `INSERT INTO personal_access_tokens
+       (id, user_id, name, token_hash, token_prefix, scopes, org_context, expires_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    input.id, input.userId, input.name, input.tokenHash, input.tokenPrefix,
+    JSON.stringify(input.scopes), input.orgContext, input.expiresAt,
+  )
+  return getPersonalAccessToken(input.id)!
+}
+
+export function listPersonalAccessTokens(userId: string): PersonalAccessToken[] {
+  // created_at is second-resolution (datetime('now')) — the rowid breaks
+  // the tie so the newest mint leads even within one second.
+  const rows = getDb().prepare(
+    'SELECT * FROM personal_access_tokens WHERE user_id = ? ORDER BY created_at DESC, rowid DESC',
+  ).all(userId) as Array<Record<string, unknown>>
+  return rows.map(toPersonalAccessToken)
+}
+
+/** The org inventory: every token whose holder carries a membership row
+ *  for the org (ANY state — the oversight surface hunts the disabled
+ *  member's live token too), newest first. */
+export function listOrgPersonalAccessTokens(orgId: string): PersonalAccessToken[] {
+  const rows = getDb().prepare(
+    `SELECT p.* FROM personal_access_tokens p
+     JOIN org_memberships m ON m.user_id = p.user_id
+     WHERE m.org_id = ?
+     ORDER BY p.created_at DESC, p.id`,
+  ).all(orgId) as Array<Record<string, unknown>>
+  return rows.map(toPersonalAccessToken)
+}
+
+export function getPersonalAccessToken(id: string): PersonalAccessToken | null {
+  const row = getDb().prepare('SELECT * FROM personal_access_tokens WHERE id = ?').get(id) as Record<string, unknown> | undefined
+  return row ? toPersonalAccessToken(row) : null
+}
+
+export function findPersonalAccessTokenByHash(tokenHash: string): PersonalAccessToken | null {
+  const row = getDb().prepare('SELECT * FROM personal_access_tokens WHERE token_hash = ?').get(tokenHash) as Record<string, unknown> | undefined
+  return row ? toPersonalAccessToken(row) : null
+}
+
+/** The guarded revoke: the owner's LIVE row flips, once. */
+export function revokePersonalAccessToken(id: string, userId: string, revokedBy: string): boolean {
+  return getDb().prepare(
+    "UPDATE personal_access_tokens SET revoked_at = datetime('now'), revoked_by = ? WHERE id = ? AND user_id = ? AND revoked_at IS NULL",
+  ).run(revokedBy, id, userId).changes > 0
+}
+
+/** The exchange path's stamp (the throttled heartbeat + the expiry-soon
+ *  mailer's one-shot mark — the route decides, the store writes). */
+export function stampPersonalAccessTokenUse(
+  id: string,
+  stamps: { usedAt: string; auditAt?: string | null; expiryNotifiedAt?: string | null },
+): void {
+  const db = getDb()
+  db.prepare('UPDATE personal_access_tokens SET last_used_at = ? WHERE id = ?').run(stamps.usedAt, id)
+  if (stamps.auditAt) {
+    db.prepare('UPDATE personal_access_tokens SET last_exchange_audit_at = ? WHERE id = ?').run(stamps.auditAt, id)
+  }
+  if (stamps.expiryNotifiedAt) {
+    db.prepare('UPDATE personal_access_tokens SET expiry_notified_at = ? WHERE id = ?').run(stamps.expiryNotifiedAt, id)
+  }
+}

package/src/store/sqlite/schema.sql

@@ -787,3 +787,65 @@ CREATE TABLE IF NOT EXISTS instrument_registrations (
 CREATE INDEX IF NOT EXISTS idx_instrument_registrations_certificate ON instrument_registrations (certificate_id);
 CREATE INDEX IF NOT EXISTS idx_instrument_registrations_holder ON instrument_registrations (holder_org_id);
 CREATE INDEX IF NOT EXISTS idx_instrument_registrations_lifecycle ON instrument_registrations (lifecycle);
+
+-- ═══════════════════════════════════════════════════════════════════
+-- TODO.identity-features/08 — the personal access tokens (the developer
+-- surface, the GitHub fine-grained pattern): an ACCOUNT-minted
+-- credential that NEVER rides a request directly — it exchanges at the
+-- OP's token endpoint (the RFC 8693 grant) for a short-lived OP JWT.
+-- The plaintext shows ONCE at mint; the row holds only the SHA-256
+-- (token_hash, the exchange's UNIQUE lookup key) + the display prefix.
+-- Expiration is MANDATORY (expires_at NOT NULL — no permanent tokens).
+-- scopes is the pinned JSON set ('<service>:<action-class>' — the
+-- store.ts grammar; narrowing-only against the holder's standing);
+-- org_context pins the mint's active-org context (NULL = the primary).
+-- last_used_at + last_exchange_audit_at carry the exchange path's
+-- THROTTLED heartbeat (never a write per exchange); expiry_notified_at
+-- is the expiry-soon mailer's one-shot mark. Revocation flips
+-- revoked_at/revoked_by and the row STAYS (the audit + the org
+-- inventory carry the history); the account erasure removes the rows.
+-- The D1 migration set carries the identical end state
+-- (0020_personal_access_tokens.sql).
+-- ═══════════════════════════════════════════════════════════════════
+CREATE TABLE IF NOT EXISTS personal_access_tokens (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id),
+  name TEXT NOT NULL,
+  token_hash TEXT NOT NULL,
+  token_prefix TEXT NOT NULL,
+  scopes TEXT NOT NULL DEFAULT '[]',
+  org_context TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  expires_at TEXT NOT NULL,
+  last_used_at TEXT,
+  last_exchange_audit_at TEXT,
+  expiry_notified_at TEXT,
+  revoked_at TEXT,
+  revoked_by TEXT,
+  UNIQUE (token_hash)
+);
+CREATE INDEX IF NOT EXISTS idx_personal_access_tokens_user ON personal_access_tokens (user_id);
+
+-- ═══════════════════════════════════════════════════════════════════
+-- The remembered consent grants (TODO.identity-features/12): the OP
+-- remembers the account holder's "Allow" per (user, client, scope set) —
+-- a repeat authorization the grant COVERS skips the consent page (unless
+-- the request carries prompt=consent). scope is the canonical space-joined
+-- set spelling (normalizeOidcScopeSet); the partial unique index keys ONE
+-- LIVE grant per (user_id, client_id, scope) — revocation flips
+-- revoked_at (the row stays for the audit + the history), a revoked
+-- triple's re-allow lands a fresh row, and the account erasure removes
+-- the rows outright. The D1 migration set carries the identical end state
+-- (0021_oidc_consent_grants.sql).
+-- ═══════════════════════════════════════════════════════════════════
+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
+);
+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;
+CREATE INDEX IF NOT EXISTS idx_oidc_consent_grants_user ON oidc_consent_grants (user_id);

package/src/store/sqlite.ts

@@ -172,7 +172,7 @@ import {
   updateOpAccount,
   updateUserName,
 } from './sqlite/op-accounts-store'
-import { installStore, type AuthUserPayload, type CertificateHolderClaim, type CertificateHolderOrg, type CompleteEmailChangeResult, type CompleteEnrollmentResult, type EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, 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 OidcKeyRow, type OpAccountErasure, type OpClientRoleAssignment, type OpLiveSession, type OrgJoinRequest, type OrgMembership, type OrgMembershipState, type OrgRegistryContact, type OrgRegistryOrg, type OrgRegistryState, 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 AuthUserPayload, type CertificateHolderClaim, type CertificateHolderOrg, type CompleteEmailChangeResult, type CompleteEnrollmentResult, type EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, 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 {
   advanceWebauthnCounter,
   consumeMfaPending,
@@ -196,6 +196,21 @@ import {
   replaceRecoveryCodes,
   recoveryCodeState,
 } from './sqlite/factors-store'
+import {
+  createPersonalAccessToken,
+  findPersonalAccessTokenByHash,
+  getPersonalAccessToken,
+  listOrgPersonalAccessTokens,
+  listPersonalAccessTokens,
+  revokePersonalAccessToken,
+  stampPersonalAccessTokenUse,
+} from './sqlite/pat-store'
+import {
+  getConsentGrant,
+  listConsentGrants,
+  recordConsentGrant,
+  revokeConsentGrant,
+} from './sqlite/consent-grants-store'
 
 
 /** The workflow tables the reset wipe covers (the D1 store's
@@ -643,6 +658,20 @@ export function createSqliteServerStore(): ServerStore {
       retireOidcKey(kid)
     },
 
+    // ── the remembered consent grants (TODO.identity-features/12) ──
+    async getConsentGrant(userId: string, clientId: string, scope: string): Promise<OidcConsentGrant | null> {
+      return getConsentGrant(userId, clientId, scope)
+    },
+    async recordConsentGrant(input: { userId: string; clientId: string; scope: string }): Promise<OidcConsentGrant> {
+      return recordConsentGrant(input)
+    },
+    async listConsentGrants(userId: string): Promise<OidcConsentGrant[]> {
+      return listConsentGrants(userId)
+    },
+    async revokeConsentGrant(id: string, userId: string): Promise<boolean> {
+      return revokeConsentGrant(id, userId)
+    },
+
     // ── the upstream providers (TODO.identity/08) ──
     async listIdentityProviders(): Promise<IdentityProvider[]> {
       return listIdentityProviders()
@@ -845,6 +874,41 @@ export function createSqliteServerStore(): ServerStore {
       return recordMfaPendingFailure(token)
     },
 
+    // ── the personal access tokens (TODO.identity-features/08) ──
+    async createPersonalAccessToken(input: {
+      id: string
+      userId: string
+      name: string
+      tokenHash: string
+      tokenPrefix: string
+      scopes: string[]
+      orgContext: string | null
+      expiresAt: string
+    }): Promise<PersonalAccessToken> {
+      return createPersonalAccessToken(input)
+    },
+    async listPersonalAccessTokens(userId: string): Promise<PersonalAccessToken[]> {
+      return listPersonalAccessTokens(userId)
+    },
+    async listOrgPersonalAccessTokens(orgId: string): Promise<PersonalAccessToken[]> {
+      return listOrgPersonalAccessTokens(orgId)
+    },
+    async getPersonalAccessToken(id: string): Promise<PersonalAccessToken | null> {
+      return getPersonalAccessToken(id)
+    },
+    async findPersonalAccessTokenByHash(tokenHash: string): Promise<PersonalAccessToken | null> {
+      return findPersonalAccessTokenByHash(tokenHash)
+    },
+    async revokePersonalAccessToken(id: string, userId: string, revokedBy: string): Promise<boolean> {
+      return revokePersonalAccessToken(id, userId, revokedBy)
+    },
+    async stampPersonalAccessTokenUse(
+      id: string,
+      stamps: { usedAt: string; auditAt?: string | null; expiryNotifiedAt?: string | null },
+    ): Promise<void> {
+      stampPersonalAccessTokenUse(id, stamps)
+    },
+
     // ── the central user registry (TODO.identity/03) ──
     async listOpClientRoles(userId: string): Promise<OpClientRoleAssignment[]> {
       return listOpClientRoles(userId)

package/src/store.ts

@@ -436,6 +436,44 @@ export interface OidcKeyRow {
   retiredAt: string | null
 }
 
+// ── the remembered consent grants (TODO.identity-features/12) ────────
+
+/** A remembered consent grant (the oidc_consent_grants row): the account
+ *  holder's "Allow", remembered per (user, client, scope set) so a repeat
+ *  authorization the grant COVERS skips the consent page. A LIVE grant
+ *  carries revoked_at NULL — revocation flips the stamp and the row stays
+ *  (the audit chain's resolvable record); the account erasure removes the
+ *  rows outright (the PAT doctrine). scope is the CANONICAL set spelling
+ *  (normalizeOidcScopeSet) — the partial unique index keys one live row
+ *  per (user, client, scope) triple. */
+export interface OidcConsentGrant {
+  id: string
+  userId: string
+  clientId: string
+  /** The granted scope set, space-joined in the canonical spelling. */
+  scope: string
+  createdAt: string
+  revokedAt: string | null
+}
+
+/** The scope set's canonical spelling: split on whitespace, drop empties
+ *  and duplicates, sort — 'profile openid' and 'openid profile' are the
+ *  SAME set, so the (user, client, scope) triple's uniqueness holds
+ *  honestly. */
+export function normalizeOidcScopeSet(scope: string): string {
+  return [...new Set(scope.split(/\s+/).filter(Boolean))].sort().join(' ')
+}
+
+/** The skip check's coverage math (the authorize endpoint's rule): a live
+ *  grant covers the request when EVERY requested scope is in the granted
+ *  set. Both sides normalize first, so a hand-edited row still reads as a
+ *  set — never trusted as a string match. */
+export function consentGrantCovers(grantScope: string, requestedScope: string): boolean {
+  const granted = new Set(normalizeOidcScopeSet(grantScope).split(' ').filter(Boolean))
+  const requested = normalizeOidcScopeSet(requestedScope).split(' ').filter(Boolean)
+  return requested.length > 0 && requested.every(s => granted.has(s))
+}
+
 // ── the upstream providers (TODO.identity/08) ────────────────────────
 
 /** An upstream identity provider the OP links + accepts (a registry
@@ -549,7 +587,10 @@ export interface OpClientRoleAssignment {
  *  credential/token rows (passwords, enrollment tokens, email-change
  *  tokens). TODO.identity-sso/02+03 adds `factors`: the factor-registry
  *  rows removed (passkeys, TOTP secrets, recovery codes, and the
- *  account's pending ceremony state). */
+ *  account's pending ceremony state). TODO.identity-features/08 adds
+ *  `personalAccessTokens`: the developer-token rows (a dead account's
+ *  tokens die with it). TODO.identity-features/12 adds `consentGrants`:
+ *  the remembered consent rows (a dead account's grants die with it). */
 export interface OpAccountErasure {
   sessions: number
   accessTokens: number
@@ -560,6 +601,8 @@ export interface OpAccountErasure {
   memberships: number
   tokens: number
   factors: number
+  personalAccessTokens: number
+  consentGrants: number
 }
 
 // ── the account console (TODO.identity/06) ───────────────────────────
@@ -676,6 +719,121 @@ export interface MfaPending {
   consumedAt: string | null
 }
 
+// ── the personal access tokens (TODO.identity-features/08) ───────────
+// The developer surface: an ACCOUNT-minted credential for programmatic
+// access (the lab CLI, scripts, the agent pipelines). The GitHub
+// fine-grained pattern mapped to the estate:
+//
+//   - the PAT NEVER rides a request directly — it exchanges at the OP's
+//     token endpoint (the RFC 8693 grant, subject_token_type
+//     urn:oimlsmart:params:oauth:token-type:pat) for a short-lived OP
+//     JWT, so every relying party keeps validating the ONE token shape;
+//   - the plaintext shows ONCE at mint; the row holds only the SHA-256
+//     (256 bits of random — the recovery codes' unsalted-hash posture),
+//     and token_hash IS the exchange's lookup key;
+//   - expiration is MANDATORY (90 days default, 1 year the ceiling);
+//   - a token only ever NARROWS the account: its scopes are a subset of
+//     the holder's standing, enforced at mint AND re-judged at exchange;
+//   - never an ORG credential: org-level automation speaks the org's
+//     registered clients (the machine cone), never a person's token.
+
+/** The PAT wire prefix (the GitHub `github_pat_` convention): the
+ *  minted token is `${PAT_TOKEN_PREFIX}${43 base64url chars}` (32 random
+ *  bytes). The prefix lets the exchange path recognize the cone and lets
+ *  leak scanners catch a committed token. */
+export const PAT_TOKEN_PREFIX = 'ospt_'
+
+/** The action class's ordinality: admin ⊃ write ⊃ read. The RP's at-use
+ *  check (patScopeCovers) reads it — a write token never mints admin
+ *  acts, an admin token covers the read. */
+export const PAT_ACTION_CLASSES = ['read', 'write', 'admin'] as const
+export type PatActionClass = (typeof PAT_ACTION_CLASSES)[number]
+
+/** One parsed scope: the service (a registered application-class OIDC
+ *  client id — the estate's service registry IS the OP's client
+ *  registry) × the action class. */
+export interface PatScope {
+  service: string
+  action: PatActionClass
+}
+
+/** Parse one scope spelling ('<service>:<action-class>'). Total, never
+ *  throws: a malformed spelling answers null (the mint refuses it, a
+ *  stored row's malformed cell is skipped on read — never trusted). */
+export function parsePatScope(raw: unknown): PatScope | null {
+  if (typeof raw !== 'string') return null
+  const m = /^([a-z0-9][a-z0-9._-]{0,127}):(read|write|admin)$/.exec(raw.trim())
+  if (!m) return null
+  return { service: m[1]!, action: m[2] as PatActionClass }
+}
+
+/** The canonical spelling (the store column's cell, the JWT's scope
+ *  claim's word). */
+export function encodePatScope(scope: PatScope): string {
+  return `${scope.service}:${scope.action}`
+}
+
+/** Normalize a scope set: parse every cell (a malformed cell refuses the
+ *  WHOLE set at mint — null), drop duplicates, and fold a service's
+ *  classes to the WIDEST (hub:read + hub:write is hub:write — the
+ *  ordinal subsumes). The answer sorts for a stable wire/claim shape. */
+export function normalizePatScopes(raw: unknown): PatScope[] | null {
+  if (!Array.isArray(raw) || raw.length === 0) return null
+  const widest = new Map<string, PatActionClass>()
+  for (const cell of raw) {
+    const scope = parsePatScope(cell)
+    if (!scope) return null
+    const held = widest.get(scope.service)
+    if (!held || PAT_ACTION_CLASSES.indexOf(scope.action) > PAT_ACTION_CLASSES.indexOf(held)) {
+      widest.set(scope.service, scope.action)
+    }
+  }
+  return [...widest.entries()]
+    .map(([service, action]) => ({ service, action }))
+    .sort((a, b) => a.service.localeCompare(b.service))
+}
+
+/** THE NARROWING INVARIANT (the spec's core: scopes ≤ the holder's,
+ *  enforced at exchange AND at use): every granted scope must be covered
+ *  by the ceiling set — the account's current standing at mint/exchange,
+ *  the token's own pinned set when a caller narrows per exchange. */
+export function patScopesWithin(granted: readonly PatScope[], ceiling: readonly PatScope[]): boolean {
+  return granted.every(g => patScopeCovers(ceiling, g.service, g.action))
+}
+
+/** The at-use check (the RP's bearer gate — the RBAC map's token-scope
+ *  cone): does the granted set cover this service at this action class?
+ *  Ordinal: a wider class covers the narrower. */
+export function patScopeCovers(granted: readonly PatScope[], service: string, action: PatActionClass): boolean {
+  const need = PAT_ACTION_CLASSES.indexOf(action)
+  return granted.some(g => g.service === service && PAT_ACTION_CLASSES.indexOf(g.action) >= need)
+}
+
+/** A personal access token's row (the personal_access_tokens table).
+ *  NEVER the plaintext, never reversible material: tokenHash is the
+ *  SHA-256 lookup key, tokenPrefix the console's display fragment.
+ *  orgContext pins the mint's active-org context (null = the account's
+ *  primary); lastUsedAt / lastExchangeAuditAt carry the exchange path's
+ *  throttled heartbeat; expiryNotifiedAt the expiry-soon mailer's
+ *  one-shot mark. */
+export interface PersonalAccessToken {
+  id: string
+  userId: string
+  name: string
+  tokenHash: string
+  tokenPrefix: string
+  /** The pinned scope set (the encoded spellings, normalized at mint). */
+  scopes: string[]
+  orgContext: string | null
+  createdAt: string
+  expiresAt: string
+  lastUsedAt: string | null
+  lastExchangeAuditAt: string | null
+  expiryNotifiedAt: string | null
+  revokedAt: string | null
+  revokedBy: string | null
+}
+
 
 // ── organization administration (TODO.identity/10) ───────────────────
 
@@ -1350,6 +1508,28 @@ export interface ServerStore {
   upsertOidcKey(input: { kid: string; publicJwk: string }): Promise<void>
   retireOidcKey(kid: string): Promise<void>
 
+  // ── the remembered consent grants (TODO.identity-features/12) ──
+  /** The authorize endpoint's remembered-consent read: the account's
+   *  LIVE grant for this client whose scope set COVERS the requested set
+   *  (the consentGrantCovers math over the live rows), or null — the
+   *  consent page shows. Both scope spellings normalize before the math. */
+  getConsentGrant(userId: string, clientId: string, scope: string): Promise<OidcConsentGrant | null>
+  /** The consent decision's remember (the allow): the upsert per
+   *  (user, client, scope) — a live triple's row refreshes its stamp (the
+   *  re-affirmed consent); a REVOKED triple's re-allow lands a FRESH live
+   *  row (the partial unique index keeps the revoked rows out of the
+   *  collision, so the history survives). The scope cell stores the
+   *  canonical spelling (normalizeOidcScopeSet). Answers the live row. */
+  recordConsentGrant(input: { userId: string; clientId: string; scope: string }): Promise<OidcConsentGrant>
+  /** The account console's "apps they can access": the account's LIVE
+   *  grants, newest first (the revoked rows never list — the audit chain
+   *  carries them). */
+  listConsentGrants(userId: string): Promise<OidcConsentGrant[]>
+  /** The console's "Revoke access": flips revoked_at on the account's OWN
+   *  live row — a second revoke or another account's row answers false
+   *  (the PAT guard's posture). The row STAYS. */
+  revokeConsentGrant(id: string, userId: string): Promise<boolean>
+
   // ── the upstream providers (TODO.identity/08) ──
   /** The upstream registry (admin-managed; OP_UPSTREAM_SEED bootstraps).
    *  Secrets are NEVER in these rows — clientSecretRef is an env name. */
@@ -1606,6 +1786,46 @@ export interface ServerStore {
    *  fresh row (null when the token is gone). */
   recordMfaPendingFailure(token: string): Promise<MfaPending | null>
 
+  // ── the personal access tokens (TODO.identity-features/08) ──
+  /** The mint: one row per token. The plaintext NEVER crosses the seam —
+   *  the caller hashes (SHA-256) and the row holds the hash + the
+   *  display prefix. expiresAt is mandatory (the route enforces the
+   *  1-year ceiling; the store trusts the route's arithmetic). */
+  createPersonalAccessToken(input: {
+    id: string
+    userId: string
+    name: string
+    tokenHash: string
+    tokenPrefix: string
+    scopes: string[]
+    orgContext: string | null
+    expiresAt: string
+  }): Promise<PersonalAccessToken>
+  /** The console's own list (newest first) — metadata only, never the
+   *  hash even (the list is a display surface). */
+  listPersonalAccessTokens(userId: string): Promise<PersonalAccessToken[]>
+  /** The org's token inventory (the org detail page's section): every
+   *  token whose holder carries an org_memberships row for the org —
+   *  ANY membership state (a disabled member's live token is exactly
+   *  what the oversight surface hunts). Metadata only. */
+  listOrgPersonalAccessTokens(orgId: string): Promise<PersonalAccessToken[]>
+  getPersonalAccessToken(id: string): Promise<PersonalAccessToken | null>
+  /** The exchange's lookup: by the presented token's SHA-256. */
+  findPersonalAccessTokenByHash(tokenHash: string): Promise<PersonalAccessToken | null>
+  /** The revoke act (the owner's console): flips revoked_at/revoked_by
+   *  guarded on the LIVE row (a second revoke answers false; another
+   *  account's row answers false). The row STAYS — the audit + the org
+   *  inventory carry the history. */
+  revokePersonalAccessToken(id: string, userId: string, revokedBy: string): Promise<boolean>
+  /** The exchange path's throttled heartbeat: the caller decides the
+   *  throttle from the row it already read; the store stamps. auditAt
+   *  rides along when the heartbeat crossed the audit window; the
+   *  expiry-soon mailer's one-shot mark lands through expiryNotifiedAt. */
+  stampPersonalAccessTokenUse(
+    id: string,
+    stamps: { usedAt: string; auditAt?: string | null; expiryNotifiedAt?: string | null },
+  ): Promise<void>
+
   // ── organization administration (TODO.identity/10) ──
   /** File a join request (the public "Request an account" page). */
   createOrgJoinRequest(input: {