shraga 0.1.112 → 0.1.113

package/src/server/security/policy.ts

@@ -0,0 +1,413 @@
+// Policy: principal → role → capability profile. Loads data/security/policy.json, validates, compiles
+// into Maps so resolve() is a few lookups with no I/O.
+//
+// Trust rules:
+// - Owners come ONLY from the OWNERS env (owners.ts) — never from the file, so a file edit can't mint one.
+// - Hot reload is PROVENANCE-CHECKED: only content whose sha256 matches what this process wrote via
+//   save() is loaded at runtime. Any other change keeps the last-good policy and fires onTamper.
+//   (The file present at boot is trusted — protecting it at rest is the protected-paths step.)
+// - Missing file ⇒ migration (from whitelist.json + optional hook), ONCE: a `.migrated` marker is
+//   written beside it, and a missing file with the marker present is deletion ⇒ fail closed + onTamper.
+// - Empty/invalid file, or migration/IO failure ⇒ fail closed: only owners resolve above anonymous.
+// - PASSIVE (`isActive` false: a standby sharing DATA_DIR) never writes: no migration, no marker, save() throws;
+//   a missing file fails closed in memory and hot-reload/tamper checks are off. activate() re-loads as at boot.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, watch, writeFileSync, type FSWatcher } from 'node:fs';
+import path from 'node:path';
+import { dataPath } from '../paths.ts';
+import { isOwnerEmail } from '../owners.ts';
+import { fromAuthUser, isSystemPrincipal, type Principal, type PrincipalKind } from './principal.ts';
+
+export type ReadScope = 'all' | 'own' | 'none';
+export interface Profile { tools: string[]; mcps: string[]; env: string[]; outbound: boolean; readScope: ReadScope; rate: string }
+export interface RoleDef { rank: number; profile: string }
+export interface BindingMatch { kind?: PrincipalKind; id?: string; emailIn?: string[]; domain?: string; verified?: boolean }
+export interface Binding { match: BindingMatch; role: string }
+export interface BlockEntry { match: BindingMatch; until: number | null; reason?: string }
+export interface PolicyFile {
+  roles: Record<string, RoleDef>;
+  profiles: Record<string, Profile>;
+  bindings: Binding[];
+  default: string;
+  blocklist: BlockEntry[];
+  /** principalId → epoch seconds; tokens issued before are invalid. */
+  tokensValidAfter: Record<string, number>;
+}
+export interface Resolved { role: string; rank: number; profile: Profile; profileName: string }
+export type TamperReason = 'hash-mismatch' | 'deleted';
+
+export const OWNER_ROLE = 'owner';
+/** Role of no-human system lanes (see resolve). */
+export const OPERATOR_ROLE = 'operator';
+const NONE_PROFILE: Profile = { tools: [], mcps: [], env: [], outbound: false, readScope: 'none', rate: '0' };
+const FULL_PROFILE: Profile = { tools: ['*'], mcps: ['*'], env: ['*'], outbound: true, readScope: 'all', rate: '600/h' };
+
+/** Defaults from the plan. Migration seeds bindings on top of this. */
+export function defaultPolicy(): PolicyFile {
+  return {
+    roles: {
+      owner: { rank: 100, profile: 'full' },
+      operator: { rank: 80, profile: 'full' },
+      member: { rank: 50, profile: 'standard' },
+      guest: { rank: 20, profile: 'reply-only' },
+      anonymous: { rank: 0, profile: 'none' },
+    },
+    profiles: {
+      full: { ...FULL_PROFILE },
+      standard: { tools: ['Read', 'Glob', 'LS', 'WebSearch'], mcps: [], env: [], outbound: true, readScope: 'own', rate: '120/h' },
+      'reply-only': { tools: ['escalate'], mcps: [], env: [], outbound: true, readScope: 'own', rate: '10/h' },
+      none: { ...NONE_PROFILE },
+    },
+    bindings: [],
+    default: 'anonymous',
+    blocklist: [],
+    tokensValidAfter: {},
+  };
+}
+
+const RATE_RE = /^\d+(\/[smhd])?$/;
+const KINDS = new Set(['user', 'email', 'slack', 'apikey', 'internal', 'anonymous']);
+const strArr = (v: unknown) => Array.isArray(v) && v.every(x => typeof x === 'string');
+
+function validateMatch(m: any, where: string, errs: string[]) {
+  if (!m || typeof m !== 'object' || Array.isArray(m)) return void errs.push(`${where}.match must be an object`);
+  const keys = Object.keys(m);
+  if (!keys.length) errs.push(`${where}.match is empty (would match everyone)`);
+  for (const k of keys) if (!['kind', 'id', 'emailIn', 'domain', 'verified'].includes(k)) errs.push(`${where}.match.${k} unknown`);
+  if (m.kind !== undefined && !KINDS.has(m.kind)) errs.push(`${where}.match.kind invalid`);
+  if (m.emailIn !== undefined && !strArr(m.emailIn)) errs.push(`${where}.match.emailIn must be string[]`);
+  if (m.id !== undefined && typeof m.id !== 'string') errs.push(`${where}.match.id must be string`);
+  if (m.domain !== undefined && typeof m.domain !== 'string') errs.push(`${where}.match.domain must be string`);
+  if (m.verified !== undefined && typeof m.verified !== 'boolean') errs.push(`${where}.match.verified must be boolean`);
+}
+
+/** Returns a list of errors; empty = valid. */
+export function validatePolicy(p: any): string[] {
+  const errs: string[] = [];
+  if (!p || typeof p !== 'object' || Array.isArray(p)) return ['policy must be an object'];
+  const roles = p.roles, profiles = p.profiles;
+  if (!roles || typeof roles !== 'object' || !Object.keys(roles).length) errs.push('roles missing/empty');
+  if (!profiles || typeof profiles !== 'object' || !Object.keys(profiles).length) errs.push('profiles missing/empty');
+  if (errs.length) return errs;
+  for (const [name, pr] of Object.entries<any>(profiles)) {
+    for (const f of ['tools', 'mcps', 'env']) if (!strArr(pr?.[f])) errs.push(`profiles.${name}.${f} must be string[]`);
+    if (typeof pr?.outbound !== 'boolean') errs.push(`profiles.${name}.outbound must be boolean`);
+    if (!['all', 'own', 'none'].includes(pr?.readScope)) errs.push(`profiles.${name}.readScope invalid`);
+    if (typeof pr?.rate !== 'string' || !RATE_RE.test(pr.rate)) errs.push(`profiles.${name}.rate invalid (e.g. "120/h")`);
+  }
+  // owner is env-rooted; its entry only picks rank/profile — but both are validated like any role
+  for (const [name, r] of Object.entries<any>(roles)) {
+    if (typeof r?.rank !== 'number' || !Number.isFinite(r.rank)) errs.push(`roles.${name}.rank must be a finite number`);
+    if (!profiles[r?.profile]) errs.push(`roles.${name}.profile "${r?.profile}" not defined`);
+  }
+  const ownerRank = roles[OWNER_ROLE]?.rank ?? 100;
+  if (Number.isFinite(ownerRank)) {
+    for (const [name, r] of Object.entries<any>(roles)) if (name !== OWNER_ROLE && r?.rank >= ownerRank) errs.push(`roles.${name}.rank must be below owner (${ownerRank})`);
+  }
+  if (!Array.isArray(p.bindings)) errs.push('bindings must be an array');
+  else p.bindings.forEach((b: any, i: number) => {
+    validateMatch(b?.match, `bindings[${i}]`, errs);
+    if (!roles[b?.role]) errs.push(`bindings[${i}].role "${b?.role}" not defined`);
+    if (b?.role === OWNER_ROLE) errs.push(`bindings[${i}] cannot grant owner (OWNERS env only)`);
+  });
+  if (!roles[p.default]) errs.push(`default role "${p.default}" not defined`);
+  if (p.default === OWNER_ROLE) errs.push('default cannot be owner');
+  if (p.blocklist !== undefined) {
+    if (!Array.isArray(p.blocklist)) errs.push('blocklist must be an array');
+    else p.blocklist.forEach((b: any, i: number) => {
+      validateMatch(b?.match, `blocklist[${i}]`, errs);
+      if (b?.until !== null && b?.until !== undefined && typeof b.until !== 'number') errs.push(`blocklist[${i}].until must be number|null`);
+    });
+  }
+  if (p.tokensValidAfter !== undefined && (typeof p.tokensValidAfter !== 'object' || Array.isArray(p.tokensValidAfter)
+    || !Object.values(p.tokensValidAfter).every(v => typeof v === 'number'))) errs.push('tokensValidAfter must be Record<string, number>');
+  return errs;
+}
+
+function matches(m: BindingMatch, p: Principal): boolean {
+  if (m.kind !== undefined && m.kind !== p.kind) return false;
+  if (m.id !== undefined && m.id !== p.id) return false;
+  if (m.verified !== undefined && m.verified !== p.verified) return false;
+  if (m.domain !== undefined && m.domain.toLowerCase() !== p.domain) return false;
+  if (m.emailIn !== undefined && !(p.email && m.emailIn.some(e => e.toLowerCase() === p.email))) return false;
+  return true;
+}
+
+interface Compiled {
+  file: PolicyFile;
+  roles: Map<string, RoleDef>;
+  profiles: Map<string, Profile>;
+  /** Roles sorted by rank desc — for effective(). */
+  byRank: [string, RoleDef][];
+  /** email → binding indexes that name it (emailIn); domain → indexes; rest = bindings keyed by neither. */
+  byEmail: Map<string, number[]>;
+  byDomain: Map<string, number[]>;
+  generic: number[];
+}
+
+function compile(file: PolicyFile): Compiled {
+  const byEmail = new Map<string, number[]>(), byDomain = new Map<string, number[]>(), generic: number[] = [];
+  const push = (m: Map<string, number[]>, k: string, i: number) => { const l = m.get(k); l ? l.push(i) : m.set(k, [i]); };
+  file.bindings.forEach((b, i) => {
+    if (b.match.emailIn) b.match.emailIn.forEach(e => push(byEmail, e.toLowerCase(), i));
+    else if (b.match.domain) push(byDomain, b.match.domain.toLowerCase(), i);
+    else generic.push(i);
+  });
+  const roles = new Map(Object.entries(file.roles));
+  if (!roles.has(OWNER_ROLE)) roles.set(OWNER_ROLE, { rank: 100, profile: 'full' });
+  const profiles = new Map(Object.entries(file.profiles));
+  if (!profiles.has(roles.get(OWNER_ROLE)!.profile)) profiles.set(roles.get(OWNER_ROLE)!.profile, { ...FULL_PROFILE });
+  return { file, roles, profiles, byRank: [...roles].sort((a, b) => b[1].rank - a[1].rank), byEmail, byDomain, generic };
+}
+
+/** The fail-closed policy: owner (env) + anonymous, nothing else. */
+function failClosed(): Compiled {
+  return compile({
+    roles: { owner: { rank: 100, profile: 'full' }, anonymous: { rank: 0, profile: 'none' } },
+    profiles: { full: { ...FULL_PROFILE }, none: { ...NONE_PROFILE } },
+    bindings: [], default: 'anonymous', blocklist: [], tokensValidAfter: {},
+  });
+}
+
+const sha256 = (s: string) => createHash('sha256').update(s).digest('hex');
+const serialize = (p: PolicyFile) => JSON.stringify(p, null, 2) + '\n';
+
+export class PolicyOptions {
+  /** Policy file location. */
+  path: string = dataPath('security', 'policy.json');
+  /** Legacy whitelist (string[] of emails) migrated into operator bindings when policy.json is missing. */
+  whitelistPath: string = dataPath('whitelist.json');
+  /** Consumer hook to extend the migrated policy (e.g. operators from a contacts store). */
+  migrate?: (draft: PolicyFile) => PolicyFile | void;
+  /** Called when an on-disk change was NOT made by save() and was rejected. */
+  onTamper?: (info: { path: string; reason: TamperReason; expected: string | null; actual: string | null }) => void;
+  /** Watch the file for hot reload. */
+  watch: boolean = true;
+  /** False on a PASSIVE standby sharing DATA_DIR: no writes (no migration, marker or save) and no tamper checks. */
+  isActive: () => boolean = () => true;
+  log: Pick<Console, 'info' | 'warn' | 'error'> = console;
+}
+
+export class Policy {
+  public options: PolicyOptions;
+  private compiled: Compiled = failClosed();
+  /** sha256 of the content currently trusted (loaded at boot or written by save()). */
+  private trustedHash: string | null = null;
+  private watcher?: FSWatcher;
+  private _valid = false;
+
+  public constructor(options?: Partial<PolicyOptions>) {
+    this.options = { ...new PolicyOptions(), ...options };
+    this.load();
+    if (this.options.watch && this.active()) this.startWatch(); // passive: events are ignored and the dir may not exist yet
+  }
+
+  /** True when a valid policy is loaded (false = fail-closed mode). */
+  public get valid(): boolean { return this._valid; }
+  public get current(): PolicyFile { return structuredClone(this.compiled.file); }
+
+  /** Marker proving migration already ran once — a later missing policy.json is deletion, not first boot. */
+  private get markerPath(): string { return path.join(path.dirname(this.options.path), '.migrated'); }
+
+  private failClosedNow(msg: string): void {
+    this.options.log.error(`[policy] ${msg} — failing closed (owners only)`);
+    this.compiled = failClosed(); this._valid = false;
+  }
+
+  /** Initial load: migrate once if missing; trust what's on disk; fail closed if invalid. Never throws. */
+  private load(): void {
+    const { path: p, log } = this.options;
+    try {
+      if (!existsSync(p)) {
+        if (!this.active()) return this.failClosedNow(`${p} missing while PASSIVE — not migrating (the active instance owns data/)`);
+        if (existsSync(this.markerPath)) {
+          this.failClosedNow(`TAMPER: ${p} missing after migration (${this.markerPath} exists) — not re-migrating`);
+          try { this.options.onTamper?.({ path: p, reason: 'deleted', expected: null, actual: null }); }
+          catch (e: any) { log.error(`[policy] onTamper threw: ${e.message}`); }
+          return;
+        }
+        this.save(this.migrate());
+        log.info(`[policy] migrated → ${p}`);
+        this.ensureMarker();
+        return;
+      }
+      const raw = readFileSync(p, 'utf8');
+      this.trustedHash = sha256(raw);
+      this.apply(raw);
+      if (this.active()) this.ensureMarker(); // heals a marker write that failed on an earlier boot
+    } catch (e: any) {
+      if (!existsSync(p)) this.trustedHash = null; // save() recorded a hash it never wrote
+      this.failClosedNow(`load/migration failed: ${e.message}`);
+    }
+  }
+
+  /** Write the `.migrated` marker if missing. Failure only logs — it never affects the loaded policy. */
+  private ensureMarker(): void {
+    try {
+      if (!existsSync(this.markerPath)) writeFileSync(this.markerPath, `${new Date().toISOString()}\n`, { mode: 0o600 });
+    } catch (e: any) { this.options.log.error(`[policy] marker write failed (${this.markerPath}): ${e.message}`); }
+  }
+
+  private apply(raw: string): boolean {
+    let parsed: any;
+    try { parsed = raw.trim() ? JSON.parse(raw) : null; } catch (e: any) { parsed = undefined; this.options.log.error(`[policy] parse failed: ${e.message}`); }
+    const errs = parsed ? validatePolicy(parsed) : ['policy file is empty or unparseable'];
+    if (errs.length) {
+      this.options.log.error(`[policy] INVALID — failing closed (owners only): ${errs.join('; ')}`);
+      this.compiled = failClosed(); this._valid = false;
+      return false;
+    }
+    this.compiled = compile({ blocklist: [], tokensValidAfter: {}, ...parsed });
+    this._valid = true;
+    return true;
+  }
+
+  /** Build the initial policy from the legacy whitelist + consumer hook. */
+  public migrate(): PolicyFile {
+    let draft = defaultPolicy();
+    try {
+      if (existsSync(this.options.whitelistPath)) {
+        const list = JSON.parse(readFileSync(this.options.whitelistPath, 'utf8'));
+        const emails = Array.isArray(list) ? list.filter((x): x is string => typeof x === 'string').map(e => e.trim().toLowerCase()).filter(Boolean) : [];
+        if (emails.length) draft.bindings.push({ match: { kind: 'user', emailIn: emails }, role: 'operator' });
+      }
+    } catch (e: any) { this.options.log.error(`[policy] whitelist migration failed: ${e.message}`); }
+    if (this.options.migrate) draft = this.options.migrate(draft) ?? draft;
+    return draft;
+  }
+
+  /** The ONLY trusted writer. Validates, writes atomically, records provenance, applies. */
+  public save(next: PolicyFile): void {
+    if (!this.active()) {
+      const msg = `save refused: PASSIVE standby must not write ${this.options.path}`;
+      this.options.log.error(`[policy] ${msg}`);
+      throw new Error(msg);
+    }
+    const errs = validatePolicy(next);
+    if (errs.length) throw new Error(`invalid policy: ${errs.join('; ')}`);
+    const content = serialize(next);
+    const p = this.options.path;
+    mkdirSync(path.dirname(p), { recursive: true });
+    this.trustedHash = sha256(content); // before the write, so the watcher sees a match
+    const tmp = `${p}.${process.pid}.tmp`;
+    writeFileSync(tmp, content, { mode: 0o600 });
+    renameSync(tmp, p);
+    this.apply(content);
+  }
+
+  /** Re-read disk; load only if it's content we wrote. Returns whether the disk state is trusted. */
+  public reload(): boolean {
+    // PASSIVE: the active instance legitimately saves this file; a standby would read that as tamper. Ignore.
+    if (!this.active()) return false;
+    const p = this.options.path;
+    const raw = existsSync(p) ? readFileSync(p, 'utf8') : null;
+    const actual = raw === null ? null : sha256(raw);
+    if (actual === this.trustedHash) return true; // our own write (or no-op touch) — already applied
+    const reason: TamperReason = raw === null ? 'deleted' : 'hash-mismatch';
+    this.options.log.error(`[policy] TAMPER: ${p} changed outside save() (${reason}) — keeping last-good policy`);
+    try { this.options.onTamper?.({ path: p, reason, expected: this.trustedHash, actual }); }
+    catch (e: any) { this.options.log.error(`[policy] onTamper threw: ${e.message}`); }
+    return false;
+  }
+
+  private startWatch(): void {
+    const dir = path.dirname(this.options.path), base = path.basename(this.options.path);
+    let t: ReturnType<typeof setTimeout> | undefined;
+    try {
+      this.watcher = watch(dir, (_ev, f) => {
+        if (f && f.toString() !== base) return;
+        clearTimeout(t);
+        t = setTimeout(() => this.reload(), 50);
+      });
+      this.watcher.unref?.();
+    } catch (e: any) { this.options.log.error(`[policy] watch failed: ${e.message}`); }
+  }
+
+  public close(): void { this.watcher?.close(); this.watcher = undefined; }
+
+  private active(): boolean {
+    try { return this.options.isActive(); }
+    catch (e: any) { this.options.log.error(`[policy] isActive threw — treating as PASSIVE: ${e.message}`); return false; }
+  }
+
+  /** Passive → active promotion: re-load from disk with the same trust as boot (migrating now if still missing). */
+  public activate(): void {
+    this.load();
+    if (this.options.watch && !this.watcher) this.startWatch();
+    this.options.log.info(`[policy] activated — loaded ${this.options.path} (valid=${this._valid})`);
+  }
+
+  private resolved(role: string): Resolved {
+    const c = this.compiled;
+    const def = c.roles.get(role) ?? c.roles.get(c.file.default) ?? { rank: 0, profile: 'none' };
+    const name = c.roles.has(role) ? role : c.file.default;
+    return { role: name, rank: def.rank, profileName: def.profile, profile: c.profiles.get(def.profile) ?? NONE_PROFILE };
+  }
+
+  /**
+   * principal → role/profile. First rule that applies:
+   * 1. SYSTEM LANE (`isSystemPrincipal`: built-in/module schedules, legacy raw internal token) → `operator`.
+   *    No human is behind it; the deployment itself runs it. (Fail-closed policy has no operator → default.)
+   * 2. OWNER (OWNERS env) — only for an authenticated login (`user`) or an `internal` principal acting FOR a user
+   *    (wake, web-retry, scheduler with a user `createdBy`, slack-retry, the agent's scoped token). That run was started
+   *    by that authenticated user, so it re-resolves exactly as their login would NOW: a revoked/downgraded creator
+   *    runs with their current role. The session floor (taint) still caps it at turn time.
+   *    A DKIM-verified email, a Slack sender or an api key carrying an owner address is NOT owner.
+   * 3. First matching binding. `internal` and `slack` principals with an email ALSO match bindings as that email's
+   *    verified login would (`kind:"user"` view) — so Slack senders resolve through the same email bindings as the
+   *    web, never to owner. Their own-kind bindings (`kind:"slack"`, id) still apply; the earliest binding wins.
+   * 4. Default role.
+   */
+  public resolve(p: Principal): Resolved {
+    if (isSystemPrincipal(p)) return this.resolved(OPERATOR_ROLE);
+    if ((p.kind === 'user' || p.kind === 'internal') && p.verified && p.email && isOwnerEmail(p.email)) return this.resolved(OWNER_ROLE);
+    const asUser = (p.kind === 'internal' || p.kind === 'slack') && p.verified && p.email
+      ? fromAuthUser({ uid: String(p.attrs.uid ?? p.attrs.slackUserId ?? p.email), email: p.email }) : undefined;
+    const best = Math.min(this.firstBinding(p), asUser ? this.firstBinding(asUser) : Infinity);
+    return this.resolved(best === Infinity ? this.compiled.file.default : this.compiled.file.bindings[best].role);
+  }
+
+  /** Index of the first binding matching `p`, or Infinity. */
+  private firstBinding(p: Principal): number {
+    const c = this.compiled, b = c.file.bindings;
+    let best = Infinity;
+    const scan = (idx?: number[]) => { if (idx) for (const i of idx) { if (i >= best) break; if (matches(b[i].match, p)) { best = i; break; } } };
+    if (p.email) scan(c.byEmail.get(p.email));
+    if (p.domain) scan(c.byDomain.get(p.domain));
+    scan(c.generic);
+    return best;
+  }
+
+  /** The highest-ranked role strictly below owner (else the default) — the ceiling for a non-interactive principal. */
+  public belowOwner(): Resolved {
+    const ownerRank = this.resolved(OWNER_ROLE).rank;
+    const top = this.compiled.byRank.find(([name, d]) => name !== OWNER_ROLE && d.rank < ownerRank);
+    return this.resolved(top ? top[0] : this.compiled.file.default);
+  }
+
+  /** Taint: a session's effective role is the lowest-ranked role that contributed. */
+  public effective(floorRank: number, role: string): Resolved {
+    const r = this.resolved(role);
+    if (r.rank <= floorRank) return r;
+    const lower = this.compiled.byRank.find(([, d]) => d.rank <= floorRank);
+    return lower ? this.resolved(lower[0]) : this.resolved(this.compiled.byRank[this.compiled.byRank.length - 1][0]);
+  }
+
+  /** Active blocklist entry for this principal, if any. */
+  public blocked(p: Principal, now = Date.now() / 1000): BlockEntry | undefined {
+    return this.compiled.file.blocklist.find(e => (e.until === null || e.until > now) && matches(e.match, p));
+  }
+
+  public tokensValidAfter(principalId: string): number | undefined {
+    return this.compiled.file.tokensValidAfter[principalId];
+  }
+
+  /** Set `tokensValidAfter[principalId]` (epoch seconds) through save(). Refuses in fail-closed mode: saving then
+   *  would overwrite the broken-but-fixable file on disk with the owners-only fallback. */
+  public setTokensValidAfter(principalId: string, epochSec: number): void {
+    if (!this._valid) throw new Error('policy is invalid (fail-closed) — fix policy.json before revoking');
+    const next = this.current;
+    next.tokensValidAfter = { ...next.tokensValidAfter, [principalId]: epochSec };
+    this.save(next);
+  }
+}

package/src/server/security/principal.ts

@@ -0,0 +1,80 @@
+// Principal = WHO is calling, normalized across channels. Pure + sync: no I/O, no imports of auth
+// (auth.ts has boot side effects). Adapters take the structural shapes the channels already hold.
+
+export type PrincipalKind = 'user' | 'email' | 'slack' | 'apikey' | 'internal' | 'anonymous';
+
+export interface Principal {
+  /** Stable key, `<kind>:<identifier>` — used for rate buckets, audit, tokensValidAfter. */
+  id: string;
+  kind: PrincipalKind;
+  email?: string;
+  domain?: string;
+  /** Identity proven by the channel (signed token, DKIM+DMARC, Slack signature…). */
+  verified: boolean;
+  attrs: Record<string, unknown>;
+}
+
+export function normalizeEmail(email?: string | null): string | undefined {
+  const e = String(email ?? '').trim().toLowerCase();
+  return e.includes('@') ? e : undefined;
+}
+
+export function emailDomain(email?: string | null): string | undefined {
+  const e = normalizeEmail(email);
+  return e ? e.slice(e.lastIndexOf('@') + 1) : undefined;
+}
+
+function make(kind: PrincipalKind, key: string, verified: boolean, email?: string | null, attrs: Record<string, unknown> = {}): Principal {
+  const e = normalizeEmail(email);
+  return { id: `${kind}:${key}`, kind, email: e, domain: emailDomain(e), verified, attrs };
+}
+
+/** Authenticated web/MCP/local user (AuthUser shape). The token was verified upstream. */
+export function fromAuthUser(u: { uid: string; email?: string | null }): Principal {
+  const e = normalizeEmail(u.email);
+  return make('user', e ?? u.uid, true, e, { uid: u.uid });
+}
+
+/** Inbound email sender. `verified` = DKIM+DMARC aligned to the From domain (computed by the channel). */
+export function fromEmailSender(from: string, verified: boolean, attrs: Record<string, unknown> = {}): Principal {
+  const e = normalizeEmail(from) ?? String(from).trim().toLowerCase();
+  return make('email', e, verified, e, attrs);
+}
+
+/** Slack sender (signature-verified event). Email optional (from contacts / users.info). */
+export function fromSlack(slackUserId: string, opts: { email?: string | null; teamId?: string } = {}): Principal {
+  return make('slack', slackUserId, true, opts.email, { slackUserId, ...(opts.teamId ? { teamId: opts.teamId } : {}) });
+}
+
+/** API key holder (validateApiKey shape). */
+export function fromApiKey(k: { id?: string; uid: string; email?: string | null }): Principal {
+  return make('apikey', k.id ?? k.uid, true, k.email, { uid: k.uid });
+}
+
+/** Scoped internal token (agent subprocess acting for a user), or a no-human run (`lane`: wake, scheduler, retry…). */
+export function fromInternal(t: { uid: string; email?: string | null; lane?: string }): Principal {
+  return make('internal', t.uid, true, t.email, { uid: t.uid, ...(t.lane ? { lane: t.lane } : {}) });
+}
+
+export function anonymous(attrs: Record<string, unknown> = {}): Principal {
+  return { id: 'anonymous', kind: 'anonymous', verified: false, attrs };
+}
+
+// ── No-human lanes ─────────────────────────────────────────────────────────────
+// A system lane runs for the deployment itself, not for a person: built-in schedules (scheduler/builtins.ts),
+// module schedules (modules/service.ts) and the legacy raw INTERNAL_API_TOKEN caller. They resolve to `operator`
+// (policy.ts). BOTH the uid shape AND the lane's fixed identity email must match: a uid alone is not enough, since
+// a login/signup could pick an id that looks like `module:x` — but it can't also carry the lane's email as its uid
+// (local uid = the email itself; Firebase uids are opaque).
+export const SYSTEM_UID = '__system__';
+const SYSTEM_LANES: { uid: (uid: string) => boolean; email: string }[] = [
+  { uid: (u) => u === SYSTEM_UID, email: 'system@shraga.local' },
+  { uid: (u) => u.startsWith('module:') && u.length > 'module:'.length, email: 'module@shraga.local' },
+  { uid: (u) => u === 'agent-internal', email: 'agent@internal' },
+];
+
+export function isSystemPrincipal(p: Principal): boolean {
+  if (p.kind !== 'internal') return false;
+  const uid = String(p.attrs.uid ?? '');
+  return SYSTEM_LANES.some((l) => l.uid(uid) && p.email === l.email);
+}

package/src/server/security/revocation.ts

@@ -0,0 +1,50 @@
+// Token revocation: `policy.tokensValidAfter[principalId]` (epoch seconds). A token whose issued-at is BEFORE it is
+// rejected. The check is one object lookup on the compiled policy — no I/O per request.
+//
+// Issued-at per token format (auth.ts):
+// - local `sha_` / MCP `mcp_` / scoped internal tokens carry `iat` since this step. Tokens minted earlier have none:
+//   local + MCP ones are treated as issued at `exp - TTL` (their TTL is fixed), scoped internal ones (no exp) at 0,
+//   so ANY revocation of that principal kills them.
+// - Firebase ID tokens: `auth_time` (the sign-in time — `iat` is refreshed hourly and would survive revocation).
+// Granularity is one second: a token minted in the same second as, but before, the revocation still passes.
+import { fromAuthUser, fromInternal } from './principal.ts';
+import { security } from './runtime.ts';
+
+/** Canonical id for a revocable principal (`user:` / `internal:` — the kinds a token verifier checks), built by the
+ *  same principal builders the verifiers use (emails lowercased). Other kinds ⇒ null: nothing would ever check them. */
+export function revocablePrincipalId(input: string): string | null {
+  const s = String(input ?? '').trim();
+  if (/[\p{Cc}\p{Cf}\p{Z}]/u.test(s)) return null; // invisible/control/space chars (e.g. U+200B) would never match a verifier's id
+  const m = /^(user|internal):(\S+)$/.exec(s);
+  if (!m) return null;
+  return m[1] === 'user' ? fromAuthUser({ uid: m[2], email: m[2] }).id : fromInternal({ uid: m[2] }).id;
+}
+
+/** True when any of `principalIds` has `tokensValidAfter` later than `issuedAtSec`. Uninitialized runtime ⇒ false. */
+export function tokenRevoked(principalIds: string | string[], issuedAtSec: number): boolean {
+  const policy = security()?.policy;
+  if (!policy) return false;
+  for (const id of Array.isArray(principalIds) ? principalIds : [principalIds]) {
+    const after = policy.tokensValidAfter(id);
+    if (after !== undefined && issuedAtSec < after) return true;
+  }
+  return false;
+}
+
+/** Issued-at of a verified Firebase ID token payload, for revocation: sign-in time, falling back to iat, else 0. */
+export function firebaseIssuedAt(payload: { auth_time?: unknown; iat?: unknown }): number {
+  const t = Number(payload.auth_time ?? payload.iat ?? 0);
+  return Number.isFinite(t) ? t : 0;
+}
+
+/** Invalidate every token issued to `principalId` until now. `actor` = who did it (principal id), for the audit.
+ *  Throws when the runtime is missing, PASSIVE, or the policy is invalid. Returns the new epoch (seconds). */
+export function revokeTokens(principalId: string, actor?: string, now = Date.now()): number {
+  const sec = security();
+  if (!sec) throw new Error('security runtime not initialized');
+  const validAfter = Math.floor(now / 1000);
+  sec.policy.setTokensValidAfter(principalId, validAfter);
+  sec.record({ type: 'token.revoke', principal: actor, target: principalId, meta: { validAfter } });
+  sec.options.log.info(`[revocation] tokens revoked for ${principalId} (validAfter=${validAfter}) by ${actor ?? 'system'}`);
+  return validAfter;
+}