shraga 0.1.111 → 0.1.113

package/src/client/lib/ws.ts

@@ -1,3 +1,8 @@
+import { reportWsDown, reportWsUp } from '@/lib/backendHealth';
+import { logger } from '@/lib/debug';
+
+const log = logger.forComponent('ws');
+
 /** Subprotocol marker used to carry a bearer token through a WebSocket handshake: open the socket as
  * `new WebSocket(url, [WS_AUTH_PROTOCOL, token])`. Browsers can't set headers on a WS handshake, and the
  * subprotocol list is the one field they can — used by the sidecar WS proxy (see authenticateWsUpgrade
@@ -72,7 +77,7 @@ export class AgentSocket {
     this.intentionalClose = false;
     const proto = location.protocol === 'https:' ? 'wss' : 'ws';
     const url = `${proto}://${location.host}/ws`;
-    console.log('[ws] connecting…');
+    log.debug('connecting…');
     this.ws = new WebSocket(url);
 
     this.ws.onopen = async () => {
@@ -81,11 +86,12 @@ export class AgentSocket {
       try {
         token = await this.tokenProvider();
       } catch (err) {
-        console.warn('[ws] token fetch failed', err);
+        log.warn('token fetch failed', err);
       }
       if (this.ws?.readyState !== WebSocket.OPEN) return;
-      console.log('[ws] open, sending auth');
+      log.debug('open, sending auth');
       this.ws.send(JSON.stringify({ type: 'auth', token }));
+      reportWsUp();
       if (this.reconnecting) {
         this.reconnecting = false;
         this.listeners.forEach((l) => l({ type: 'reconnected' }));
@@ -95,7 +101,7 @@ export class AgentSocket {
     this.ws.onmessage = (e) => {
       try {
         const data = JSON.parse(e.data) as ServerEvent;
-        if (data.type !== 'text_delta') console.log('[ws] ←', data.type);
+        if (data.type !== 'text_delta') log.verbose('←', data.type);
         if (data.type === 'auth_ok') {
           this.authRetries = 0;
           this.flushPending();
@@ -113,37 +119,38 @@ export class AgentSocket {
             this.intentionalClose = true;
           } else {
             this.authRetries++;
-            console.log(`[ws] auth failed (attempt ${this.authRetries}), will retry with fresh token`);
+            log.warn(`auth failed (attempt ${this.authRetries}), will retry with fresh token`);
           }
         }
         this.listeners.forEach((l) => l(data));
       } catch (err) {
-        console.warn('[ws] bad frame', err);
+        log.warn('bad frame', err);
       }
     };
 
     this.ws.onclose = (e) => {
-      console.log(`[ws] closed code=${e.code} intentional=${this.intentionalClose}`);
+      log.debug(`closed code=${e.code} intentional=${this.intentionalClose}`);
       if (!this.intentionalClose) {
         this.reconnecting = true;
         this.connectAttempts++;
+        reportWsDown(e.code);
         this.listeners.forEach((l) => l({ type: 'disconnected' }));
         const base = this.authRetries > 0 ? Math.min(2000 * this.authRetries, 10000) : Math.min(1000 * 2 ** this.connectAttempts, 30000);
         const jitter = Math.random() * 1000;
         const delay = base + jitter;
-        console.log(`[ws] reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${this.connectAttempts})`);
+        log.debug(`reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${this.connectAttempts})`);
         setTimeout(() => this.connect(this.tokenProvider), delay);
       }
     };
 
-    this.ws.onerror = (e) => console.warn('[ws] error', e);
+    this.ws.onerror = (e) => log.warn('error', e);
   }
 
   private flushPending() {
     if (this.pendingMessage) {
       const msg = this.pendingMessage;
       this.pendingMessage = null;
-      console.log('[ws] flushing pending message after reconnect');
+      log.debug('flushing pending message after reconnect');
       if (!this.send(msg)) {
         this.pendingMessage = msg;
       }
@@ -152,24 +159,25 @@ export class AgentSocket {
 
   disconnect() {
     this.intentionalClose = true;
+    reportWsUp(); // an intentional close is not a fault — don't leave a stale banner behind
     this.ws?.close();
     this.ws = null;
   }
 
   send(msg: object): boolean {
     if (this.ws?.readyState === WebSocket.OPEN) {
-      console.log('[ws] →', (msg as any).type);
+      log.verbose('→', (msg as any).type);
       this.ws.send(JSON.stringify(msg));
       return true;
     }
-    console.warn('[ws] send failed, readyState=', this.ws?.readyState);
+    log.warn('send failed, readyState=', this.ws?.readyState);
     return false;
   }
 
   sendOrQueue(msg: object): boolean {
     if (this.send(msg)) return true;
     this.pendingMessage = msg;
-    console.log('[ws] message queued for reconnect');
+    log.debug('message queued for reconnect');
     return false;
   }
 

package/src/scripts/harden-audit.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# harden-audit.sh — make shraga's audit log append-only at the OS level. Linux + root. Idempotent: run it from cron.
+#
+#   sudo harden-audit.sh <DATA_DIR>                 (or DATA_DIR=<dir> sudo -E harden-audit.sh)
+#   root crontab, hourly:  17 * * * *  /app/node_modules/shraga/src/scripts/harden-audit.sh /app/data-prod
+#
+# `chattr +a` on <DATA_DIR>/audit/: the server user can still create month files and append, but can't delete or
+# rename any entry. `chattr +a` on each YYYY-MM.jsonl: it opens for append only — no truncate, no rewrite.
+# New files do NOT inherit +a (it is not in ext4's EXT4_FL_INHERITED nor XFS's inherited flags), so a new month's
+# file stays truncatable until the next run — hence hourly cron. Retention/rotation is a root-only op (chattr -a).
+# +a can't stop the server user from CREATING a month entry as a symlink/directory (planted). Those are never hardened:
+# they're reported and the script exits non-zero — after +a is applied to every valid file. The server refuses to
+# append through them and alerts owners. Remove one as root: chattr -a "$audit"; rm -r <entry>; re-run.
+set -euo pipefail
+
+[ "$(uname -s)" = Linux ] || { echo "harden-audit: Linux only (chattr) — nothing done" >&2; exit 1; }
+[ "$(id -u)" -eq 0 ] || { echo "harden-audit: must run as root (chattr +a needs CAP_LINUX_IMMUTABLE)" >&2; exit 1; }
+data="${1:-${DATA_DIR:-}}"
+[ -n "$data" ] || { echo "usage: $0 <DATA_DIR>" >&2; exit 2; }
+audit="$(realpath "$data")/audit"
+[ -d "$audit" ] && [ ! -L "$audit" ] || { echo "harden-audit: $audit is not a directory (start the server once first)" >&2; exit 1; }
+# Builds before tamper protection lock INSIDE the audit dir; in an append-only dir that lock can never be released.
+if [ -e "$audit/.lock" ]; then
+  {
+    echo "harden-audit: $audit/.lock exists — left by a pre-tamper-protection shraga (it locks inside the audit dir)."
+    echo "  1. Verify no old build is running against $data (e.g. ps -eo pid,args | grep shraga); upgrade or stop it."
+    if lsattr -d "$audit" 2>/dev/null | awk '{print $1}' | grep -q a; then
+      echo "  2. $audit is already append-only, so first: chattr -a '$audit'"
+      echo "  3. As root: rmdir '$audit/.lock'"
+    else
+      echo "  2. As root: rmdir '$audit/.lock'"
+    fi
+    echo "  Then re-run: $0 $data"
+  } >&2
+  exit 1
+fi
+
+chattr +a "$audit"
+shopt -s nullglob
+files=() bad=()
+for f in "$audit"/*.jsonl; do
+  if [ -f "$f" ] && [ ! -L "$f" ]; then files+=("$f"); else bad+=("$f"); fi
+done
+for f in "${files[@]}"; do chattr +a "$f"; done
+
+lsattr -d "$audit"
+[ ${#files[@]} -eq 0 ] || lsattr "${files[@]}"
+echo "harden-audit: $audit append-only (+${#files[@]} month files) — server can append, not truncate/delete/rename"
+
+if [ ${#bad[@]} -gt 0 ]; then
+  for f in "${bad[@]}"; do
+    echo "harden-audit: ERROR — $f is not a regular file ($(stat -c %F "$f" 2>/dev/null || echo unknown)$([ -L "$f" ] && echo " -> $(readlink "$f")")); possibly PLANTED to divert or disable auditing. NOT hardened. Inspect, then as root: chattr -a '$audit' && rm -r '$f' && $0 $data" >&2
+  done
+  exit 1
+fi

package/src/server/api-key-routes.ts

@@ -0,0 +1,64 @@
+// API key list/create/delete, ONE implementation for both mounts: `/api/api-keys` (self) and `/api/owner/api-keys`
+// (owner console). Gates run per route, so mounting the router never gates unrelated requests.
+// Audit actor is always the caller's principal id. Store refusals (validation 400, PASSIVE 409) map to their status.
+import { Router, type Request, type RequestHandler, type Response } from 'express';
+import type { AuthUser } from './auth.ts';
+import { apiKeyStore, ApiKeyStoreError } from './api-keys.ts';
+import { security } from './security/runtime.ts';
+
+export class ApiKeyRoutesOptions {
+  base: string = '/api/api-keys';
+  gate: RequestHandler[] = [];
+  /** Owner console: sees/deletes every key and may set `role`/`expiresAt`. Self: own keys (all when the caller is an
+   *  owner, as before) and label only. */
+  asOwner: boolean = false;
+}
+
+const userOf = (req: Request) => (req as any).user as AuthUser;
+
+function fail(res: Response, e: any): void {
+  const status = e instanceof ApiKeyStoreError ? e.status : 400;
+  console.warn(`[api-keys] ${e?.message ?? e}`);
+  res.status(status).json({ error: e?.message ?? String(e) });
+}
+
+export function apiKeyRouter(options?: Partial<ApiKeyRoutesOptions>): Router {
+  const { base, gate, asOwner } = { ...new ApiKeyRoutesOptions(), ...options };
+  const router = Router();
+  const isOwner = (u: AuthUser) => asOwner || u.isOwner;
+
+  router.get(base, ...gate, (req, res) => {
+    const user = userOf(req);
+    res.json({ keys: apiKeyStore().list({ uid: user.uid, isOwner: isOwner(user) }) });
+  });
+
+  /** Body: { label?, role?, expiresAt? (epoch ms) } — role/expiresAt honored on the owner mount only. Plaintext returned once. */
+  router.post(base, ...gate, (req, res) => {
+    const user = userOf(req);
+    // Minting a key is minting a credential AS this identity — only an interactive login may (same rule as OAuth
+    // consent). Otherwise a role-capped or expiring key could mint itself an uncapped, non-expiring one.
+    const kind = user.principal?.kind ?? 'unknown';
+    if (kind !== 'user') {
+      console.warn(`[api-keys] create refused: non-interactive credential (${kind})`);
+      security()?.authDeny(`http:${base}`, `non-interactive:${kind}`, req.ip);
+      return void res.status(403).json({ error: 'Creating an API key requires an interactive login' });
+    }
+    const { label, role, expiresAt } = (req.body ?? {}) as { label?: string; role?: string; expiresAt?: number };
+    try {
+      const opts = asOwner ? { role, expiresAt } : {};
+      res.json(apiKeyStore().create(user.uid, user.email, label || 'Unnamed', { ...opts, actor: user.principal.id }));
+    } catch (e: any) { fail(res, e); }
+  });
+
+  router.delete(`${base}/:id`, ...gate, (req: Request<{ id: string }>, res) => {
+    const user = userOf(req);
+    try {
+      const r = apiKeyStore().delete(req.params.id, user.uid, isOwner(user), user.principal.id);
+      if (r === 'not_found') return void res.status(404).json({ error: 'Key not found' });
+      if (r === 'forbidden') return void res.status(403).json({ error: 'Cannot delete another user\'s key' });
+      res.json({ ok: true });
+    } catch (e: any) { fail(res, e); }
+  });
+
+  return router;
+}

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