@oimlsmart/platform-server 0.1.5 → 0.1.6

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

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

@@ -62,6 +62,7 @@ import {
   type InstrumentRegistration,
   type InstrumentRegistrationLifecycle,
   type InstrumentRegistrationScopeStatus,
+  type PersonalAccessToken,
   type PlatformEvent,
   resolveOrgContext,
   parseOrgMemberCone,
@@ -442,6 +443,41 @@ 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
+  }
+
   // ── users / sessions ─────────────────────────────────────────────
 
   async seedDemoAccounts(): Promise<void> {
@@ -1471,6 +1507,11 @@ 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()
     await this.stmt(
       `UPDATE users SET
          email = ?, name = 'Deleted account', provider = 'erased',
@@ -1487,6 +1528,7 @@ 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,
     }
   }
 
@@ -1843,6 +1885,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 +2038,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/op-accounts-store.ts

@@ -312,6 +312,7 @@ export function eraseOpAccount(userId: string): {
   memberships: number
   tokens: number
   factors: number
+  personalAccessTokens: number
 } | null {
   const db = getDb()
   const row = db.prepare('SELECT 1 AS ok FROM users WHERE id = ?').get(userId)
@@ -335,6 +336,9 @@ 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
   db.prepare(
     `UPDATE users SET
        email = ?, name = 'Deleted account', provider = 'erased',
@@ -342,7 +346,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 }
 }
 
 /** 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,41 @@ 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);

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 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,15 @@ import {
   replaceRecoveryCodes,
   recoveryCodeState,
 } from './sqlite/factors-store'
+import {
+  createPersonalAccessToken,
+  findPersonalAccessTokenByHash,
+  getPersonalAccessToken,
+  listOrgPersonalAccessTokens,
+  listPersonalAccessTokens,
+  revokePersonalAccessToken,
+  stampPersonalAccessTokenUse,
+} from './sqlite/pat-store'
 
 
 /** The workflow tables the reset wipe covers (the D1 store's
@@ -845,6 +854,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

@@ -549,7 +549,9 @@ 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). */
 export interface OpAccountErasure {
   sessions: number
   accessTokens: number
@@ -560,6 +562,7 @@ export interface OpAccountErasure {
   memberships: number
   tokens: number
   factors: number
+  personalAccessTokens: number
 }
 
 // ── the account console (TODO.identity/06) ───────────────────────────
@@ -676,6 +679,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) ───────────────────
 
@@ -1606,6 +1724,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: {