@oimlsmart/platform-server 0.1.6 → 0.1.8

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
@@ -551,7 +589,11 @@ export interface OpClientRoleAssignment {
  *  rows removed (passkeys, TOTP secrets, recovery codes, and the
  *  account's pending ceremony state). TODO.identity-features/08 adds
  *  `personalAccessTokens`: the developer-token rows (a dead account's
- *  tokens die with it). */
+ *  tokens die with it). TODO.identity-features/12 adds `consentGrants`:
+ *  the remembered consent rows (a dead account's grants die with it).
+ *  TODO.identity-features/01 adds `emails`: the additional-address rows
+ *  (every address of the account goes — the tombstone's primary is the
+ *  anonymized users.email). */
 export interface OpAccountErasure {
   sessions: number
   accessTokens: number
@@ -563,21 +605,29 @@ export interface OpAccountErasure {
   tokens: number
   factors: number
   personalAccessTokens: number
+  consentGrants: number
+  emails: number
 }
 
 // ── the account console (TODO.identity/06) ───────────────────────────
 
-/** The verify-new-email ceremony's row (the enrollment link's doctrine:
+/** The verify-an-address ceremony's row (the enrollment link's doctrine:
  *  a 256-bit random token backed by the D1 row; one-time, 24 h).
  *  deliveredBy records the channel the link traveled: 'mailer' (sent to
  *  the NEW address; completing verifies it) or 'shown' (no mailer
  *  configured, the link was displayed to the signed-in holder; the change
- *  applies but the address stays unverified, honestly). */
+ *  applies but the address stays unverified, honestly).
+ *  TODO.identity-features/01: kind names the ceremony — 'change' (the
+ *  primary-address replacement; completion moves users.email) or 'add'
+ *  (the per-address verification of an account_emails row; completion
+ *  stamps the row's verified_at). Rows predating the kind column read
+ *  'change' (the migration's default). */
 export interface EmailChangeToken {
   token: string
   userId: string
   newEmail: string
   deliveredBy: 'mailer' | 'shown'
+  kind: 'change' | 'add'
   createdAt: string
   expiresAt: string
   consumedAt: string | null
@@ -595,6 +645,38 @@ export type CompleteEmailChangeResult =
    *  (the token is burned; the change must start over). */
   | { kind: 'conflict' }
 
+// ── multiple emails per account (TODO.identity-features/01) ──────────
+
+/** One of the account's addresses. The PRIMARY is the users row's email
+ *  (isPrimary — the OIDC `email` claim's source, never an
+ *  account_emails row); the ADDITIONAL addresses are the account_emails
+ *  rows. verifiedAt NULL = the mailbox is unproven: an unverified
+ *  additional NEVER names the account (not to sign-in, not to recovery,
+ *  never a notification's target). */
+export interface AccountEmail {
+  userId: string
+  email: string
+  verifiedAt: string | null
+  isPrimary: boolean
+  /** Who added the row (the holder's session email, an admin's); NULL on
+   *  the primary line (the users row carries no such provenance). */
+  addedBy: string | null
+  createdAt: string
+}
+
+/** The additional-address add's honest outcomes. */
+export type AddAccountEmailResult =
+  /** The row landed (unverified — the verification ceremony follows). */
+  | 'added'
+  /** The account ALREADY carries the address as an additional (the add
+   *  is an idempotent no-op; the route re-sends the verification for an
+   *  unverified row). */
+  | 'present'
+  /** Another account holds the address (as its primary or an
+   *  additional), or it IS this account's primary — an address names at
+   *  most one account across the estate. */
+  | 'conflict'
+
 // ── strong authentication: the factor registry (TODO.identity-sso/02 + /03)
 
 /** A registered passkey (the webauthn_credentials row). publicKeyCose is
@@ -1468,6 +1550,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. */
@@ -1519,7 +1623,13 @@ export interface ServerStore {
   /** The password sign-in's lookup: the credential + the account's
    *  active flag by email (normalized). Null = no such credential — the
    *  route still runs one full-cost verify (the timing-shape rule,
-   *  auth/passwords.ts). The hash never leaves the server. */
+   *  auth/passwords.ts). The hash never leaves the server.
+   *  TODO.identity-features/01: the address resolves by ANY of the
+   *  account's VERIFIED addresses — the primary (users.email) or a
+   *  proven account_emails row. An unverified additional never resolves
+   *  (the mailbox is unproven), and a primary owner always wins over an
+   *  additional row (the deterministic rule — a stray duplicate shadows,
+   *  never ambiguates). */
   getPasswordLogin(email: string): Promise<{ userId: string; hash: string; active: boolean } | null>
   /** Set/replace the account's password credential (enrollment
    *  completion, the account page's change). */
@@ -1618,15 +1728,20 @@ export interface ServerStore {
    *  "sign out everywhere else" action + the password change's
    *  best-practice revocation). Answers the revoked count. */
   deleteOtherSessions(userId: string, keepToken: string): Promise<number>
-  /** Mint the verify-new-email ceremony's token. A fresh request VOIDS
-   *  the account's earlier pending rows (only the newest link works).
-   *  deliveredBy is stamped at request time and decides whether
-   *  completion may verify the address. */
+  /** Mint the verify-an-address 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). deliveredBy is stamped at request time and
+   *  decides whether completion may verify the address. kind defaults
+   *  'change'. */
   createEmailChangeToken(input: {
     token: string
     userId: string
     newEmail: string
     deliveredBy: 'mailer' | 'shown'
+    kind?: 'change' | 'add'
     ttlMs: number
   }): Promise<EmailChangeToken>
   getEmailChangeToken(token: string): Promise<EmailChangeToken | null>
@@ -1634,12 +1749,51 @@ export interface ServerStore {
    *  so the console can show it. */
   getPendingEmailChange(userId: string): Promise<EmailChangeToken | null>
   /** Complete the ceremony: consume the token 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. verified = the token traveled by mailer
-   *  (mailbox proven); a shown link never verifies. */
+   *  link works exactly once, expired or not), judge the expiry, then
+   *  act on the kind: 'change' re-checks the address's uniqueness across
+   *  BOTH address tables (a conflict burns the token honestly) and moves
+   *  the account's primary (users.email); 'add' stamps the
+   *  account_emails row's verified_at (a row removed between request and
+   *  completion answers 'unknown'). verified = the token traveled by
+   *  mailer (mailbox proven); a shown link never verifies. */
   completeEmailChange(token: string): Promise<CompleteEmailChangeResult>
 
+  // ── multiple emails per account (TODO.identity-features/01) ──
+  /** The account's addresses, the PRIMARY first (the users row's email +
+   *  its verification stamp), then the additional account_emails rows
+   *  (oldest first). The console's emails section and the security-mail
+   *  fan-out read this. */
+  listAccountEmails(userId: string): Promise<AccountEmail[]>
+  /** Resolve the account by ANY of its addresses (normalized): the
+   *  primary always names it; an additional ONLY when verified (an
+   *  unproven address never names the account — not to sign-in, not to
+   *  recovery). The primary owner wins over an additional row (the
+   *  deterministic rule). */
+  findUserByAnyEmail(email: string): Promise<AuthUserPayload | null>
+  /** Add an ADDITIONAL address (normalized lowercase; the row lands
+   *  UNVERIFIED — the verify-an-address ceremony's kind 'add' token
+   *  proves the mailbox). The tagged result names the outcome; the
+   *  unique index + the cross-table check make an address name at most
+   *  one account. */
+  addAccountEmail(userId: string, email: string, addedBy?: string | null): Promise<AddAccountEmailResult>
+  /** The verification ceremony's stamp on the account's OWN additional
+   *  row (the kind 'add' completion): verified_at flips, once (the
+   *  guarded update). Answers false when no such row stands. */
+  markAccountEmailVerified(userId: string, email: string): Promise<boolean>
+  /** Promote a VERIFIED additional to primary: the promoted address
+   *  becomes users.email (its verification stamp travels, so the claims
+   *  stay verified), and the previous primary takes the row's place in
+   *  account_emails with ITS stamp (it stays a verified additional —
+   *  sign-in by it keeps working). 'unknown' = no such additional row;
+   *  'unverified' = the row stands unproven (a primary is always
+   *  proven). */
+  setPrimaryAccountEmail(userId: string, email: string): Promise<'ok' | 'unknown' | 'unverified'>
+  /** Remove an ADDITIONAL address. 'primary' = the address IS the
+   *  account's primary (promote another first — the primary is never
+   *  removed from under the holder); 'unknown' = no such additional
+   *  row. */
+  removeAccountEmail(userId: string, email: string): Promise<'ok' | 'primary' | 'unknown'>
+
   // ── strong authentication: the factor registry (TODO.identity-sso/02 + /03) ──
   /** The one-time WebAuthn ceremony challenge. The challenge value IS the
    *  key (the clientDataJSON binds it); expires_at = now + ttlMs. */