shraga 0.1.112 → 0.1.114

package/src/server/api-keys.ts

@@ -1,63 +1,201 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { randomBytes, timingSafeEqual } from 'node:crypto';
+// API keys (`uck_…`). Stored as sha256(key) + a display preview — the plaintext is returned ONCE, by create().
+//
+// Migration (one-time, idempotent, at load): a file still holding plaintext `key` entries is hashed in place —
+// the original bytes are kept at `<path>.bak` (mode 600, written only if absent), then the hashed file is written
+// atomically (tmp + rename, mode 600). Only the ACTIVE instance migrates: a PASSIVE standby sharing DATA_DIR hashes
+// in memory and serves the same keys without writing. A file with no plaintext entries is never rewritten.
+// A failed migration is retried only after the file changes or `retryMs` passes (logged once per failing file state).
+// Every store write (create/delete) is refused while PASSIVE.
+//
+// Rollback: code from before hashing expects a plaintext `key` on every entry and breaks on hashed ones, so rolling
+// back invalidates EVERY API key. Before rolling back, restore `api-keys.json.bak` (keys created after the migration
+// are lost), or re-issue the keys afterwards.
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
 import { dataPath } from './paths.ts';
-
-const KEYS_PATH = dataPath('api-keys.json');
+import { fromApiKey, fromAuthUser, type Principal } from './security/principal.ts';
+import { OWNER_ROLE } from './security/policy.ts';
+import { security } from './security/runtime.ts';
 
 export interface ApiKey {
   id: string;
-  key: string;
+  /** sha256 hex of the full key. */
+  hash: string;
+  keyPreview: string;
   label: string;
   uid: string;
   email: string;
   createdAt: number;
+  /** Policy role name the key's principal carries (never owner). */
+  role?: string;
+  /** Epoch ms; the key is rejected from then on. */
+  expiresAt?: number;
 }
+export type ApiKeyView = Omit<ApiKey, 'hash'>;
+export interface ApiKeyIdentity { id: string; uid: string; email: string; role?: string }
+export interface CreateApiKeyOptions { role?: string; expiresAt?: number; /** Principal id of the creator, for the audit. */ actor?: string }
 
-function load(): ApiKey[] {
-  if (!existsSync(KEYS_PATH)) return [];
-  try { return JSON.parse(readFileSync(KEYS_PATH, 'utf-8')); } catch { return []; }
+/** A refused store operation; `status` is the HTTP status a route should answer with. */
+export class ApiKeyStoreError extends Error {
+  public constructor(message: string, public status = 400) { super(message); }
 }
 
-function save(keys: ApiKey[]) {
-  mkdirSync(dataPath(''), { recursive: true });
-  writeFileSync(KEYS_PATH, JSON.stringify(keys, null, 2));
-}
+const sha256 = (s: string) => createHash('sha256').update(s).digest('hex');
+const previewOf = (key: string) => `${key.slice(0, 8)}…`;
+const view = ({ hash: _h, ...rest }: ApiKey): ApiKeyView => rest;
 
-export function createApiKey(uid: string, email: string, label: string): ApiKey {
-  const keys = load();
-  const entry: ApiKey = {
-    id: randomBytes(8).toString('hex'),
-    key: `uck_${randomBytes(32).toString('hex')}`,
-    label,
-    uid,
-    email,
-    createdAt: Date.now(),
-  };
-  keys.push(entry);
-  save(keys);
-  return entry;
+export class ApiKeyStoreOptions {
+  path: string = dataPath('api-keys.json');
+  /** Migration writes only while true (PASSIVE standby ⇒ false). Default: the security runtime's flag. */
+  isActive: () => boolean = () => security()?.options.isActive() ?? true;
+  clock: () => number = Date.now;
+  /** After a failed migration, don't retry until the file changes or this many ms pass. */
+  retryMs: number = 60_000;
+  log: Pick<Console, 'info' | 'warn' | 'error'> = console;
 }
 
-export function deleteApiKey(id: string, callerUid: string, isOwner: boolean): 'ok' | 'not_found' | 'forbidden' {
-  const keys = load();
-  const idx = keys.findIndex(k => k.id === id);
-  if (idx < 0) return 'not_found';
-  if (keys[idx].uid !== callerUid && !isOwner) return 'forbidden';
-  keys.splice(idx, 1);
-  save(keys);
-  return 'ok';
-}
+interface Snapshot { mtimeMs: number; size: number; keys: ApiKey[]; byHash: Map<string, ApiKey>; legacy: boolean; failedAt?: number }
 
-export function listApiKeys() {
-  return load().map(({ key, ...rest }) => ({ ...rest, keyPreview: `${key.slice(0, 8)}…` }));
-}
+export class ApiKeyStore {
+  public options: ApiKeyStoreOptions;
+  private snap?: Snapshot;
+
+  public constructor(options?: Partial<ApiKeyStoreOptions>) {
+    this.options = { ...new ApiKeyStoreOptions(), ...options };
+  }
+
+  private active(): boolean {
+    try { return this.options.isActive(); }
+    catch (e: any) { this.options.log.error(`[api-keys] isActive threw — treating as PASSIVE: ${e.message}`); return false; }
+  }
 
-export function validateApiKey(key: string): { uid: string; email: string } | null {
-  const keys = load();
-  for (const k of keys) {
-    if (k.key.length === key.length && timingSafeEqual(Buffer.from(k.key), Buffer.from(key))) {
-      return { uid: k.uid, email: k.email };
+  /** Current keys; re-parses only when the file changed (stat), migrating plaintext entries on the active instance. */
+  private read(): Snapshot {
+    const p = this.options.path;
+    const st = existsSync(p) ? statSync(p) : null;
+    const s = this.snap;
+    const unchanged = !!(s && st && s.mtimeMs === st.mtimeMs && s.size === st.size);
+    const backingOff = s?.failedAt !== undefined && this.options.clock() - s.failedAt < this.options.retryMs;
+    if (unchanged && !(s!.legacy && this.active() && !backingOff)) return s!;
+    if (!st) return (this.snap = { mtimeMs: 0, size: -1, keys: [], byHash: new Map(), legacy: false });
+    const raw = readFileSync(p, 'utf8');
+    let parsed: unknown;
+    try { parsed = JSON.parse(raw); } catch (e: any) {
+      this.options.log.error(`[api-keys] ${p} unparseable — no keys valid until fixed: ${e.message}`);
+      parsed = [];
     }
+    let legacy = false;
+    const keys: ApiKey[] = (Array.isArray(parsed) ? parsed : []).map((k: any) => {
+      if (typeof k?.key !== 'string') return k as ApiKey;
+      legacy = true;
+      const { key, ...rest } = k;
+      return { ...rest, hash: sha256(key), keyPreview: previewOf(key) };
+    });
+    if (legacy && this.active()) return this.migrate(raw, keys, st, unchanged && s?.failedAt !== undefined);
+    return (this.snap = { mtimeMs: st.mtimeMs, size: st.size, keys, byHash: this.index(keys), legacy });
   }
-  return null;
+
+  private index(keys: ApiKey[]): Map<string, ApiKey> {
+    return new Map(keys.filter(k => typeof k?.hash === 'string').map(k => [k.hash, k]));
+  }
+
+  /** `retry` = the same file state already failed once (don't log again). */
+  private migrate(raw: string, keys: ApiKey[], st: { mtimeMs: number; size: number }, retry: boolean): Snapshot {
+    const bak = `${this.options.path}.bak`;
+    try {
+      if (existsSync(bak)) this.options.log.warn(`[api-keys] ${bak} exists — keeping it, not overwriting`);
+      else writeFileSync(bak, raw, { mode: 0o600, flag: 'wx' });
+      const snap = this.write(keys);
+      this.options.log.info(`[api-keys] migrated ${keys.length} key(s) to hashed storage (backup: ${bak})`);
+      return snap;
+    } catch (e: any) {
+      if (!retry) this.options.log.error(`[api-keys] migration failed — serving hashed in memory, retrying when the file changes or every ${this.options.retryMs}ms: ${e.message}`);
+      return (this.snap = { mtimeMs: st.mtimeMs, size: st.size, keys, byHash: this.index(keys), legacy: true, failedAt: this.options.clock() });
+    }
+  }
+
+  /** Atomic write (tmp + rename, mode 600); refreshes the snapshot from what landed. */
+  private write(keys: ApiKey[]): Snapshot {
+    const p = this.options.path;
+    mkdirSync(path.dirname(p), { recursive: true });
+    const tmp = `${p}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(keys, null, 2), { mode: 0o600 });
+    renameSync(tmp, p);
+    const st = statSync(p);
+    return (this.snap = { mtimeMs: st.mtimeMs, size: st.size, keys, byHash: this.index(keys), legacy: false });
+  }
+
+  /** Mint a key. Returns its public view plus the plaintext `key` — the only time it is ever available. */
+  public create(uid: string, email: string, label: string, opts: CreateApiKeyOptions = {}): ApiKeyView & { key: string } {
+    this.assertWritable();
+    const { role, expiresAt, actor } = opts;
+    if (role !== undefined) {
+      if (typeof role !== 'string' || !role) throw new Error('role must be a non-empty string');
+      if (role === OWNER_ROLE) throw new Error('an API key cannot carry the owner role');
+      const policy = security()?.policy;
+      if (policy && !policy.current.roles[role]) throw new Error(`role "${role}" is not defined in the policy`);
+    }
+    if (expiresAt !== undefined && !(Number.isFinite(expiresAt) && expiresAt > this.options.clock())) {
+      throw new Error('expiresAt must be a future epoch (ms)');
+    }
+    const key = `uck_${randomBytes(32).toString('hex')}`;
+    const entry: ApiKey = {
+      id: randomBytes(8).toString('hex'), hash: sha256(key), keyPreview: previewOf(key), label, uid, email,
+      createdAt: this.options.clock(), ...(role ? { role } : {}), ...(expiresAt !== undefined ? { expiresAt } : {}),
+    };
+    this.write([...this.read().keys, entry]);
+    security()?.record({
+      type: 'key.create', principal: actor ?? fromAuthUser({ uid, email }).id, target: `apikey:${entry.id}`, role,
+      meta: { uid, ...(expiresAt !== undefined ? { expiresAt } : {}) },
+    });
+    return { ...view(entry), key };
+  }
+
+  /** `actor` = the caller's principal id (`req.user.principal.id`), for the audit. */
+  public delete(id: string, callerUid: string, isOwner: boolean, actor: string): 'ok' | 'not_found' | 'forbidden' {
+    this.assertWritable();
+    const keys = this.read().keys;
+    const k = keys.find(x => x.id === id);
+    if (!k) return 'not_found';
+    if (k.uid !== callerUid && !isOwner) return 'forbidden';
+    this.write(keys.filter(x => x !== k));
+    security()?.record({ type: 'key.revoke', principal: actor, target: `apikey:${id}`, meta: { uid: k.uid } });
+    return 'ok';
+  }
+
+  /** PASSIVE standby shares DATA_DIR: it must never write the key file (nor migrate it as a side effect of a write). */
+  private assertWritable(): void {
+    if (!this.active()) throw new ApiKeyStoreError('API keys are read-only on a PASSIVE standby — use the active instance', 409);
+  }
+
+  /** Keys visible to the caller: an owner sees every key, anyone else only their own. Never hash or plaintext. */
+  public list(caller: { uid: string; isOwner: boolean }): ApiKeyView[] {
+    return this.read().keys.filter(k => caller.isOwner || k.uid === caller.uid).map(view);
+  }
+
+  /** Hash lookup (the Map key is sha256 of the secret, so timing reveals nothing usable); expired ⇒ null. */
+  public validate(key: string): ApiKeyIdentity | null {
+    if (typeof key !== 'string' || !key.startsWith('uck_')) return null;
+    const k = this.read().byHash.get(sha256(key));
+    if (!k) return null;
+    if (k.expiresAt !== undefined && this.options.clock() >= k.expiresAt) return null;
+    return { id: k.id, uid: k.uid, email: k.email, ...(k.role ? { role: k.role } : {}) };
+  }
+}
+
+let store: ApiKeyStore | undefined;
+/** The process-wide store over data/api-keys.json. */
+export const apiKeyStore = (): ApiKeyStore => (store ??= new ApiKeyStore());
+
+export const createApiKey = (uid: string, email: string, label: string, opts?: CreateApiKeyOptions) => apiKeyStore().create(uid, email, label, opts);
+export const deleteApiKey = (id: string, callerUid: string, isOwner: boolean, actor: string) => apiKeyStore().delete(id, callerUid, isOwner, actor);
+export const listApiKeys = (caller: { uid: string; isOwner: boolean }) => apiKeyStore().list(caller);
+export const validateApiKey = (key: string) => apiKeyStore().validate(key);
+
+/** Principal for a validated key. The key's role rides in `attrs.role` (principal.ts's fromApiKey takes no attrs). */
+export function apiKeyPrincipal(k: ApiKeyIdentity): Principal {
+  const p = fromApiKey(k);
+  if (k.role) p.attrs.role = k.role;
+  return p;
 }

package/src/server/auth.ts

@@ -28,7 +28,25 @@ const _origGetKey = (JwtHelper as any)['getGooglePublicKey'].bind(JwtHelper);
   return p;
 };
 import { dataPath } from './paths.ts';
-import { validateApiKey } from './api-keys.ts';
+import { apiKeyPrincipal, validateApiKey } from './api-keys.ts';
+import { isOwnerEmail } from './owners.ts';
+import { fromAuthUser, fromInternal, type Principal } from './security/principal.ts';
+import { security } from './security/runtime.ts';
+import { firebaseIssuedAt, tokenRevoked } from './security/revocation.ts';
+
+// Issued-at (`iat`) + revocation: every token format below carries `iat` for NEW tokens, in a shape the pre-iat
+// verifier REJECTS (never mis-parses into a different identity) — so for these tokens a rollback only forces re-auth.
+// API keys are NOT covered: pre-hashing code breaks on hashed entries, so a rollback invalidates every key (see the
+// Rollback note in api-keys.ts). Old tokens
+// without iat still verify here, with an implied iat (see security/revocation.ts). Checked against
+// policy.tokensValidAfter for the token's principal: an in-memory lookup, no I/O.
+const nowSec = () => Math.floor(Date.now() / 1000);
+const hmacEq = (a: string, b: string) => a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+const userPrincipalId = (uid: string, email: string) => fromAuthUser({ uid, email }).id;
+
+/** Fixed TTLs (seconds). Legacy tokens without iat are treated as issued at `exp - TTL`. */
+export const MCP_TOKEN_TTL = { access: 3600, refresh: 60 * 60 * 24 * 30 } as const;
+export const LOCAL_TOKEN_TTL = 30 * 24 * 3600;
 
 /** Server secret for signing scoped internal tokens — stable per startup. */
 const INTERNAL_SECRET = process.env.INTERNAL_API_TOKEN || randomBytes(32).toString('hex');
@@ -36,23 +54,36 @@ process.env.INTERNAL_API_TOKEN = INTERNAL_SECRET;
 const tmpDir = join(dataPath('..'), '.tmp');
 try { mkdirSync(tmpDir, { recursive: true }); writeFileSync(join(tmpDir, '.internal-token'), INTERNAL_SECRET); } catch (e: any) { console.error('[auth] failed to write .internal-token:', e.message); }
 
-/** Sign a scoped internal token embedding user identity. Agent subprocess uses this as INTERNAL_API_TOKEN — single env var carries both auth + identity. */
+/** Sign a scoped internal token embedding user identity. Agent subprocess uses this as INTERNAL_API_TOKEN — single env var carries both auth + identity.
+ *  Format `<sig64>.<iat>:<uid>:<email>`, sig = HMAC("v2:<iat>:<uid>:<email>"). (Legacy: `<sig64>:<uid>:<email>`, no iat.) */
 export function signInternalToken(uid: string, email: string): string {
-  const payload = `${uid}:${email}`;
-  const sig = createHmac('sha256', INTERNAL_SECRET).update(payload).digest('hex');
-  return `${sig}:${payload}`;
+  const rest = `${nowSec()}:${uid}:${email}`;
+  const sig = createHmac('sha256', INTERNAL_SECRET).update(`v2:${rest}`).digest('hex');
+  return `${sig}.${rest}`;
 }
 
-/** Verify and extract user identity from a scoped internal token. Falls back to legacy global token check. */
+/** Verify and extract user identity from a scoped internal token. Falls back to legacy global token check.
+ *  Revocation: rejected if issued before tokensValidAfter of `internal:<uid>` or of the user it acts for. */
 function verifyInternalToken(token: string): { uid: string; email: string } | null {
+  const scoped = (uid: string, email: string, iat: number) =>
+    tokenRevoked([fromInternal({ uid }).id, userPrincipalId(uid, email)], iat) ? null : { uid, email };
+  if (token[64] === '.') {
+    const rest = token.slice(65);
+    if (!hmacEq(token.slice(0, 64), createHmac('sha256', INTERNAL_SECRET).update(`v2:${rest}`).digest('hex'))) return null;
+    const [iatStr, uid, ...emailParts] = rest.split(':');
+    const iat = Number(iatStr);
+    if (!Number.isInteger(iat) || !uid || !emailParts.length) return null;
+    return scoped(uid, emailParts.join(':'), iat);
+  }
   const firstColon = token.indexOf(':');
   if (firstColon === 64) {
     const sig = token.slice(0, 64);
     const payload = token.slice(65);
     const expected = createHmac('sha256', INTERNAL_SECRET).update(payload).digest('hex');
-    if (sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
+    if (hmacEq(sig, expected)) {
       const sepIdx = payload.indexOf(':');
-      if (sepIdx > 0) return { uid: payload.slice(0, sepIdx), email: payload.slice(sepIdx + 1) };
+      // Legacy scoped token: no exp, no iat ⇒ issued at 0, so any revocation of the principal kills it.
+      if (sepIdx > 0) return scoped(payload.slice(0, sepIdx), payload.slice(sepIdx + 1), 0);
     }
     return null;
   }
@@ -91,9 +122,10 @@ function getMcpSecret(): string {
  * Provider-agnostic: identity is established upstream by requireAuth (Firebase today,
  * email-password later) — this only carries the resulting {uid, email}. No storage needed.
  */
-export function signMcpToken(uid: string, email: string, kind: 'access' | 'refresh' = 'access', ttlSec = 3600): string {
-  const exp = Math.floor(Date.now() / 1000) + ttlSec;
-  const payload = `mcp:${kind}:${uid}:${email}:${exp}`;
+/** Payload `mcp2:kind:uid:email:iat:exp`. (Legacy `mcp:kind:uid:email:exp` — the pre-iat verifier rejects `mcp2`.) */
+export function signMcpToken(uid: string, email: string, kind: 'access' | 'refresh' = 'access', ttlSec: number = MCP_TOKEN_TTL[kind]): string {
+  const iat = nowSec();
+  const payload = `mcp2:${kind}:${uid}:${email}:${iat}:${iat + ttlSec}`;
   const sig = createHmac('sha256', getMcpSecret()).update(payload).digest('hex');
   return `mcp_${sig}.${Buffer.from(payload).toString('base64url')}`;
 }
@@ -107,12 +139,19 @@ export function verifyMcpToken(token: string): { uid: string; email: string; kin
   let payload: string;
   try { payload = Buffer.from(body.slice(dot + 1), 'base64url').toString(); } catch { return null; }
   const expected = createHmac('sha256', getMcpSecret()).update(payload).digest('hex');
-  if (sig.length !== expected.length || !timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) return null;
-  const parts = payload.split(':'); // mcp:kind:uid:email:exp  (uid/email never contain ':')
-  if (parts[0] !== 'mcp' || parts.length < 5) return null;
+  if (!hmacEq(sig, expected)) return null;
+  const parts = payload.split(':'); // tag:kind:uid:email[:iat]:exp  (uid never contains ':')
+  const v2 = parts[0] === 'mcp2';
+  if (!(v2 || parts[0] === 'mcp') || parts.length < (v2 ? 6 : 5)) return null;
+  const kind = parts[1];
+  if (kind !== 'access' && kind !== 'refresh') return null;
   const exp = Number(parts[parts.length - 1]);
-  if (!exp || Math.floor(Date.now() / 1000) > exp) return null;
-  return { kind: parts[1] as 'access' | 'refresh', uid: parts[2], email: parts.slice(3, parts.length - 1).join(':') };
+  if (!exp || nowSec() > exp) return null;
+  const iat = v2 ? Number(parts[parts.length - 2]) : exp - MCP_TOKEN_TTL[kind];
+  if (!Number.isInteger(iat)) return null;
+  const uid = parts[2], email = parts.slice(3, parts.length - (v2 ? 2 : 1)).join(':');
+  if (tokenRevoked(userPrincipalId(uid, email), iat)) return null;
+  return { kind, uid, email };
 }
 
 const WHITELIST_PATH = dataPath('whitelist.json');
@@ -131,20 +170,19 @@ export interface AuthUser {
   email: string;
   /** Owners can see all sessions/schedules across users (view-only bypass — mutations still restricted to owner of record). */
   isOwner: boolean;
+  /** Who is calling, per auth branch (login → user, api key → apikey, internal token → internal). */
+  principal: Principal;
 }
 
-/** Owners from env: OWNERS="email1,email2" (case-insensitive). */
-function loadOwners(): string[] {
-  return (process.env.OWNERS ?? '')
-    .split(',')
-    .map((s) => s.trim().toLowerCase())
-    .filter(Boolean);
-}
-
-function isOwnerEmail(email?: string): boolean {
-  // Emailless tokens (e.g. anonymous Firebase users) are never owners — guard the .toLowerCase() crash.
-  return !!email && loadOwners().includes(email.toLowerCase());
-}
+// Owner comes from an interactive login, a server-minted scoped internal token acting for one, or an UNCAPPED API key
+// (a delegated login credential — only an interactive login can mint a key, e.g. `shraga term`'s /cli-auth consent).
+// A role-capped key is never owner. OWNERS is read per call, so removing the creator takes effect on the next request.
+const ownerCapable = (p: Principal) => p.kind === 'user' || p.kind === 'internal' || (p.kind === 'apikey' && typeof p.attrs.role !== 'string');
+const authUser = (uid: string, email: string, principal: Principal): AuthUser => ({
+  uid, email, principal, isOwner: ownerCapable(principal) && isOwnerEmail(email),
+});
+const internalUser = (t: { uid: string; email: string }) => authUser(t.uid, t.email, fromInternal(t));
+const apiKeyUser = (k: { id: string; uid: string; email: string; role?: string }) => authUser(k.uid, k.email, apiKeyPrincipal(k));
 
 export async function verifyToken(token: string): Promise<AuthUser> {
   const projectId = JSON.parse(process.env.FIREBASE_CONFIG_PROD ?? process.env.VITE_FIREBASE_CONFIG_PROD ?? '{}').projectId;
@@ -161,7 +199,11 @@ export async function verifyToken(token: string): Promise<AuthUser> {
   if (whitelist.length > 0 && !whitelist.includes(payload.email)) {
     throw new Error('User not in whitelist');
   }
-  return { uid: payload.user_id || payload.sub, email: payload.email, isOwner: isOwnerEmail(payload.email) };
+  const uid = payload.user_id || payload.sub;
+  const principal = fromAuthUser({ uid, email: payload.email });
+  // auth_time = sign-in time; the hourly-refreshed iat would outlive a revocation.
+  if (tokenRevoked(principal.id, firebaseIssuedAt(payload))) throw new Error('Token revoked — sign in again');
+  return authUser(uid, payload.email, principal);
 }
 
 // ── Pluggable auth provider ──────────────────────────────────────────────────
@@ -201,15 +243,17 @@ function localSecret(): string {
   } catch { _localSecret = INTERNAL_SECRET; }
   return _localSecret;
 }
-/** Issue a signed local session token: sha_<sig>.<base64url(email:exp)>. */
+/** Issue a signed local session token: sha_<sig>.<base64url(email:iat:exp)>, sig = HMAC("v2:" + payload).
+ *  (Legacy: payload `email:exp`, sig over the payload alone — the "v2:" domain separation makes the pre-iat verifier
+ *  reject new tokens instead of reading `email:iat` as the email.) */
 export function localLogin(email: string, password: string): string | null {
   const rec = loadLocalUsers().find((u) => u.email === email);
   if (!rec) return null;
   const { hash } = hashPw(password, rec.salt);
   if (hash.length !== rec.hash.length || !timingSafeEqual(Buffer.from(hash), Buffer.from(rec.hash))) return null;
-  const exp = Math.floor(Date.now() / 1000) + 30 * 24 * 3600;
-  const payload = `${email}:${exp}`;
-  const sig = createHmac('sha256', localSecret()).update(payload).digest('hex');
+  const iat = nowSec();
+  const payload = `${email}:${iat}:${iat + LOCAL_TOKEN_TTL}`;
+  const sig = createHmac('sha256', localSecret()).update(`v2:${payload}`).digest('hex');
   return `sha_${sig}.${Buffer.from(payload).toString('base64url')}`;
 }
 function verifyLocalToken(token: string): AuthUser {
@@ -219,12 +263,18 @@ function verifyLocalToken(token: string): AuthUser {
   if (dot < 0) throw new Error('Malformed token');
   const sig = body.slice(0, dot);
   const payload = Buffer.from(body.slice(dot + 1), 'base64url').toString();
-  const expected = createHmac('sha256', localSecret()).update(payload).digest('hex');
-  if (sig.length !== expected.length || !timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) throw new Error('Bad token signature');
+  const v2 = hmacEq(sig, createHmac('sha256', localSecret()).update(`v2:${payload}`).digest('hex'));
+  if (!v2 && !hmacEq(sig, createHmac('sha256', localSecret()).update(payload).digest('hex'))) throw new Error('Bad token signature');
   const sep = payload.lastIndexOf(':');
-  const email = payload.slice(0, sep);
-  if (Math.floor(Date.now() / 1000) > Number(payload.slice(sep + 1))) throw new Error('Token expired — sign in again');
-  return { uid: email, email, isOwner: isOwnerEmail(email) };
+  const exp = Number(payload.slice(sep + 1));
+  let head = payload.slice(0, sep), iat = exp - LOCAL_TOKEN_TTL;
+  if (v2) { const s = head.lastIndexOf(':'); iat = Number(head.slice(s + 1)); head = head.slice(0, s); }
+  const email = head;
+  if (!Number.isFinite(exp) || nowSec() > exp) throw new Error('Token expired — sign in again');
+  const principal = fromAuthUser({ uid: email, email });
+  if (!Number.isInteger(iat)) throw new Error('Malformed token');
+  if (tokenRevoked(principal.id, iat)) throw new Error('Token revoked — sign in again');
+  return authUser(email, email, principal);
 }
 
 /** Dispatch bearer verification to the active provider. */
@@ -239,10 +289,10 @@ export async function authenticateToken(token: string | undefined | null): Promi
   if (!token) return null;
   if (token.startsWith('uck_')) {
     const identity = validateApiKey(token);
-    return identity ? { uid: identity.uid, email: identity.email, isOwner: isOwnerEmail(identity.email) } : null;
+    return identity ? apiKeyUser(identity) : null;
   }
   const internal = verifyInternalToken(token);
-  if (internal) return { uid: internal.uid, email: internal.email, isOwner: isOwnerEmail(internal.email) };
+  if (internal) return internalUser(internal);
   try { return await verifyBearer(token); } catch { return null; }
 }
 
@@ -251,26 +301,42 @@ export async function requireAuth(req: Request, res: Response, next: NextFunctio
   if (internalToken) {
     const identity = verifyInternalToken(internalToken);
     if (identity) {
-      (req as any).user = { uid: identity.uid, email: identity.email, isOwner: isOwnerEmail(identity.email) } as AuthUser;
+      const user = internalUser(identity);
+      (req as any).user = user;
+      security()?.authAllow(user.principal, 'http:internal');
       return next();
     }
   }
 
   const token = req.headers.authorization?.replace('Bearer ', '') || (req.query.token as string);
-  if (!token) return void res.status(401).json({ error: 'Missing token' });
+  if (!token) {
+    security()?.authDeny('http', 'missing-token', req.ip);
+    return void res.status(401).json({ error: 'Missing token' });
+  }
 
   // API key auth (uck_…)
   if (token.startsWith('uck_')) {
     const identity = validateApiKey(token);
-    if (!identity) return void res.status(401).json({ error: 'Invalid API key' });
-    (req as any).user = { uid: identity.uid, email: identity.email, isOwner: isOwnerEmail(identity.email) } as AuthUser;
+    if (!identity) {
+      security()?.authDeny('http:apikey', 'invalid-api-key', req.ip);
+      return void res.status(401).json({ error: 'Invalid API key' });
+    }
+    const user = apiKeyUser(identity);
+    (req as any).user = user;
+    security()?.authAllow(user.principal, 'http:apikey');
     return next();
   }
 
+  let user: AuthUser;
   try {
-    (req as any).user = await verifyBearer(token);
-    next();
+    user = await verifyBearer(token);
   } catch (err: any) {
-    return void res.status(err?.message?.includes('whitelist') ? 403 : 401).json({ error: err.message });
+    const whitelisted = err?.message?.includes('whitelist');
+    const reason = whitelisted ? 'not-whitelisted' : err?.message?.includes('revoked') ? 'token-revoked' : 'invalid-bearer';
+    security()?.authDeny('http:bearer', reason, req.ip);
+    return void res.status(whitelisted ? 403 : 401).json({ error: err.message });
   }
+  (req as any).user = user;
+  security()?.authAllow(user.principal, 'http:bearer');
+  next();
 }