@elinpf/dsh-ops-access-hub 0.3.0 → 0.4.0

package/lib/server.js

@@ -28,16 +28,33 @@
  *                                          read token)
  * - `POST /cases/:id/hit`                → bump a case's hit count (read+)
  * - `DELETE /cases/:id`                  → remove a case (admin)
+ * - `GET /whoami`                        → `{ok,role,actor,source}` for the presented
+ *                                          token (read+)
+ * - `POST /tokens`                       → issue a named token, body `{name,role,expiresAt?}`;
+ *                                          the plaintext is in this response only (admin)
+ * - `GET /tokens`                        → issued-token roster, metadata only — never
+ *                                          the digest or the plaintext (admin)
+ * - `PATCH /tokens/:id`                  → edit a live token's `{name?,role?,expiresAt?}`
+ *                                          (`null`/`''` clears the expiry); 404 unknown,
+ *                                          409 revoked or label taken (admin)
+ * - `DELETE /tokens/:id`                 → revoke a named token; 404 unknown, 409 already
+ *                                          revoked (admin)
  *
- * Auth: two Bearer tokens — admin (everything) and read (`GET /entries*`
- * only). Comparisons use `crypto.timingSafeEqual`. Every error response is
- * JSON `{ok:false,error}` and `error` never contains field values.
+ * Auth: `Authorization: Bearer <token>`, compared with `crypto.timingSafeEqual`.
+ * Two roles — admin (everything) and read (resolving, case writes, the
+ * requests list). A token is either one of the two static bootstrap tokens
+ * (CLI flag / env, always accepted, the break-glass path) or a named token
+ * issued through `POST /tokens` (ADR-0009): independently revocable,
+ * optionally expiring, and recorded as the audit `actor`. Named tokens are
+ * stored as SHA-256 digests only. Every error response is JSON
+ * `{ok:false,error}` and `error` never contains field values.
  *
  * @module
  */
 import { timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
 import { NAME_PATTERN } from './store.js';
+import { generateToken, hashToken, parseExpiresAt, parseExpiresAtPatch, parseTokenName, parseTokenRole, toTokenView, tokenPrefix, } from './tokens.js';
 import { WEB_UI_HTML } from './web.js';
 export { NAME_PATTERN };
 const MAX_BODY_BYTES = 4 * 1024 * 1024;
@@ -58,17 +75,38 @@ function tokenEqual(a, b) {
         return false;
     return timingSafeEqual(ba, bb);
 }
-function roleOf(req, opts) {
+/** The presented Bearer token, or null when the header is absent/malformed. */
+function bearerToken(req) {
     const header = req.headers.authorization;
     if (!header || !header.startsWith('Bearer '))
         return null;
-    const token = header.slice('Bearer '.length).trim();
+    return header.slice('Bearer '.length).trim();
+}
+/**
+ * Resolve the presented Bearer token to a principal, or null.
+ *
+ * Static bootstrap tokens win first (a plain constant-time string compare);
+ * otherwise the digest is matched against the named-token roster. A token
+ * whose only match is revoked or expired is *not* a principal — it fails
+ * authentication like any unknown token.
+ */
+function principalOf(req, opts) {
+    const token = bearerToken(req);
+    if (token === null)
+        return null;
     if (tokenEqual(token, opts.adminToken))
-        return 'admin';
+        return { role: 'admin', actor: 'admin', source: 'static' };
     if (tokenEqual(token, opts.readToken))
-        return 'read';
+        return { role: 'read', actor: 'read', source: 'static' };
+    const named = opts.store.findActiveTokenByHash(hashToken(token));
+    if (named)
+        return { role: named.role, actor: named.name, source: 'named' };
     return null;
 }
+/** The audit `actor` of a principal: named tokens only (see `Principal`). */
+function actorOf(principal) {
+    return principal.source === 'named' ? principal.actor : undefined;
+}
 function send(res, status, body) {
     const text = JSON.stringify(body);
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
@@ -194,6 +232,28 @@ function sanitizeCaseInput(raw, partial) {
     }
     return out;
 }
+/**
+ * Validate a `PATCH /tokens/:id` body into a `TokenPatch` (ADR-0010). Keeps
+ * "field absent" (keep) distinct from `expiresAt: null`/`''` (clear) and
+ * refuses an empty patch — a body with nothing to change is a caller error,
+ * not a silent 200. Label clashes are a conflict (409), so they are checked by
+ * the route, not here (which maps everything to 400).
+ */
+function parseTokenPatch(raw) {
+    if (!isPlainObject(raw))
+        throw new Error('request body must be a JSON object');
+    const patch = {};
+    if (raw.name !== undefined)
+        patch.name = parseTokenName(raw.name);
+    if (raw.role !== undefined)
+        patch.role = parseTokenRole(raw.role);
+    if (raw.expiresAt !== undefined)
+        patch.expiresAt = parseExpiresAtPatch(raw.expiresAt) ?? null;
+    if (patch.name === undefined && patch.role === undefined && patch.expiresAt === undefined) {
+        throw new Error('no updatable fields (name, role, expiresAt)');
+    }
+    return patch;
+}
 export function createHubServer(opts) {
     const { store } = opts;
     async function handle(req, res) {
@@ -208,9 +268,18 @@ export function createHubServer(opts) {
             res.end(WEB_UI_HTML);
             return;
         }
-        const role = roleOf(req, opts);
-        if (!role)
-            throw new HttpError(401, 'missing or invalid bearer token');
+        const principal = principalOf(req, opts);
+        if (!principal) {
+            // A digest that matches a revoked/expired record deserves a clearer
+            // message than an outright unknown token (the holder already has it).
+            const token = bearerToken(req);
+            const known = token !== null && opts.store.hasTokenHash(hashToken(token));
+            throw new HttpError(401, known ? 'token revoked or expired' : 'missing or invalid bearer token');
+        }
+        const actor = actorOf(principal);
+        if (method === 'GET' && path === '/whoami') {
+            return send(res, 200, { ok: true, role: principal.role, actor: principal.actor, source: principal.source });
+        }
         if (method === 'GET' && path === '/entries') {
             // Listing never exposes field values — tiers carry only probe state.
             const list = store.list().map((e) => ({
@@ -226,8 +295,8 @@ export function createHubServer(opts) {
             return send(res, 200, list);
         }
         if (method === 'GET' && path === '/audit') {
-            if (role !== 'admin')
-                throw new HttpError(403, 'read token cannot access admin endpoints');
+            if (principal.role !== 'admin')
+                throw new HttpError(403, 'read role cannot access admin endpoints');
             const raw = url.searchParams.get('limit');
             let limit = 100;
             if (raw !== null) {
@@ -239,6 +308,103 @@ export function createHubServer(opts) {
             return send(res, 200, await store.readAudit(limit));
         }
         const parts = path.split('/').filter((p) => p !== '');
+        if (parts[0] === 'tokens' && parts.length === 1) {
+            if (principal.role !== 'admin')
+                throw new HttpError(403, 'read role cannot access admin endpoints');
+            if (method === 'GET') {
+                // Roster metadata only — the digest never leaves the store, and the
+                // plaintext cannot be reconstructed from anything here.
+                return send(res, 200, store.listTokens().map(toTokenView));
+            }
+            if (method === 'POST') {
+                const body = await readBody(req);
+                let name;
+                let role;
+                let expiresAt;
+                try {
+                    name = parseTokenName(body.name);
+                    role = parseTokenRole(body.role);
+                    expiresAt = parseExpiresAt(body.expiresAt);
+                }
+                catch (err) {
+                    throw new HttpError(400, err.message);
+                }
+                if (store.findTokenByName(name))
+                    throw new HttpError(409, `token name '${name}' is already in use`);
+                // Mint, store only the digest, and hand the plaintext back exactly once.
+                const plaintext = generateToken();
+                let issued;
+                try {
+                    issued = store.putToken({
+                        name,
+                        role,
+                        hash: hashToken(plaintext),
+                        prefix: tokenPrefix(plaintext),
+                        createdBy: principal.actor,
+                        ...(expiresAt !== undefined ? { expiresAt } : {}),
+                    });
+                }
+                catch (err) {
+                    throw new HttpError(400, err.message);
+                }
+                await store.save();
+                await store.auditToken(principal.role, 'token-create', issued, actor);
+                return send(res, 200, { ok: true, ...toTokenView(issued), token: plaintext });
+            }
+            throw new HttpError(405, 'method not allowed');
+        }
+        if (parts[0] === 'tokens' && parts.length === 2) {
+            if (principal.role !== 'admin')
+                throw new HttpError(403, 'read role cannot access admin endpoints');
+            const token = store.getToken(parts[1]);
+            if (method === 'PATCH') {
+                // Edit in place (ADR-0010): a holder whose label, role or expiry is
+                // wrong gets a correction, not a revoke-and-reissue.
+                if (!token)
+                    throw new HttpError(404, 'token not found');
+                if (token.revokedAt !== undefined) {
+                    throw new HttpError(409, 'token is revoked and can no longer be edited; issue a new one');
+                }
+                const body = await readBody(req);
+                let patch;
+                try {
+                    patch = parseTokenPatch(body);
+                }
+                catch (err) {
+                    throw new HttpError(400, err.message);
+                }
+                // A label another live token holds is a conflict, not a bad request.
+                const holder = patch.name === undefined ? undefined : store.findTokenByName(patch.name);
+                if (holder && holder.id !== token.id) {
+                    throw new HttpError(409, `token name '${patch.name}' is already in use`);
+                }
+                let updated;
+                try {
+                    updated = store.updateToken(token.id, patch);
+                }
+                catch (err) {
+                    throw new HttpError(409, err.message);
+                }
+                if (!updated)
+                    throw new HttpError(404, 'token not found');
+                // A patch that matched the current values is a no-op: no write, no
+                // audit noise (the roster rewrite costs a full re-encrypt).
+                if (updated.changes.length > 0) {
+                    await store.save();
+                    await store.auditToken(principal.role, 'token-update', updated.token, actor, updated.changes);
+                }
+                return send(res, 200, { ok: true, ...toTokenView(updated.token), changes: updated.changes });
+            }
+            if (method !== 'DELETE')
+                throw new HttpError(405, 'method not allowed');
+            if (!token)
+                throw new HttpError(404, 'token not found');
+            if (!store.revokeToken(parts[1]))
+                throw new HttpError(409, 'token already revoked');
+            await store.save();
+            await store.auditToken(principal.role, 'token-revoke', token, actor);
+            return send(res, 200, { ok: true });
+        }
         if (parts[0] === 'requests' && parts.length === 1) {
             if (method === 'GET') {
                 // Metadata only — the reviewer fetches values per request (admin).
@@ -260,8 +426,8 @@ export function createHubServer(opts) {
                 }));
                 return send(res, 200, list);
             }
-            if (role !== 'admin')
-                throw new HttpError(403, 'read token cannot access admin endpoints');
+            if (principal.role !== 'admin')
+                throw new HttpError(403, 'read role cannot access admin endpoints');
             if (method === 'POST') {
                 const body = await readBody(req);
                 const kind = segment(String(body.kind ?? ''), 'kind');
@@ -274,23 +440,23 @@ export function createHubServer(opts) {
                     throw new HttpError(400, 'reason must be a string');
                 const request = store.putRequest({ kind, name, tier, fields: body.fields, envelope, reason: body.reason });
                 await store.save();
-                await store.audit(role, 'request', kind, name, tier);
+                await store.audit(principal.role, 'request', kind, name, tier, actor);
                 return send(res, 200, { ok: true, id: request.id });
             }
             throw new HttpError(405, 'method not allowed');
         }
         if (parts[0] === 'requests' && parts.length === 2 && method === 'GET') {
             // Full field values for pre-approval review — admin only.
-            if (role !== 'admin')
-                throw new HttpError(403, 'read token cannot review request contents');
+            if (principal.role !== 'admin')
+                throw new HttpError(403, 'read role cannot review request contents');
             const request = store.getRequest(parts[1]);
             if (!request)
                 throw new HttpError(404, 'request not found');
             return send(res, 200, request);
         }
         if (parts[0] === 'requests' && parts.length === 3 && parts[2] === 'decide') {
-            if (role !== 'admin')
-                throw new HttpError(403, 'read token cannot access admin endpoints');
+            if (principal.role !== 'admin')
+                throw new HttpError(403, 'read role cannot access admin endpoints');
             if (method !== 'POST')
                 throw new HttpError(405, 'method not allowed');
             const body = await readBody(req);
@@ -304,7 +470,7 @@ export function createHubServer(opts) {
                     : new HttpError(404, 'request not found');
             }
             await store.save();
-            await store.audit(role, body.approved ? 'approve' : 'reject', request.kind, request.name, request.tier);
+            await store.audit(principal.role, body.approved ? 'approve' : 'reject', request.kind, request.name, request.tier, actor);
             return send(res, 200, { ok: true });
         }
         if (parts[0] === 'cases' && parts.length === 1) {
@@ -324,7 +490,7 @@ export function createHubServer(opts) {
                     throw new HttpError(400, err.message);
                 }
                 await store.save();
-                await store.auditCase(role, 'case-put', record);
+                await store.auditCase(principal.role, 'case-put', record, actor);
                 return send(res, 200, { ok: true, id: record.id });
             }
             throw new HttpError(405, 'method not allowed');
@@ -343,17 +509,17 @@ export function createHubServer(opts) {
                 if (!record)
                     throw new HttpError(404, 'case not found');
                 await store.save();
-                await store.auditCase(role, 'case-put', record);
+                await store.auditCase(principal.role, 'case-put', record, actor);
                 return send(res, 200, { ok: true });
             }
             if (method === 'DELETE') {
-                if (role !== 'admin')
-                    throw new HttpError(403, 'read token cannot access admin endpoints');
+                if (principal.role !== 'admin')
+                    throw new HttpError(403, 'read role cannot access admin endpoints');
                 const existing = store.getCase(id);
                 if (!existing || !store.deleteCase(id))
                     throw new HttpError(404, 'case not found');
                 await store.save();
-                await store.auditCase(role, 'case-delete', existing);
+                await store.auditCase(principal.role, 'case-delete', existing, actor);
                 return send(res, 200, { ok: true });
             }
             throw new HttpError(405, 'method not allowed');
@@ -365,7 +531,7 @@ export function createHubServer(opts) {
             if (!record || !store.hitCase(parts[1]))
                 throw new HttpError(404, 'case not found');
             await store.save();
-            await store.auditCase(role, 'case-hit', record);
+            await store.auditCase(principal.role, 'case-hit', record, actor);
             return send(res, 200, { ok: true });
         }
         if (parts[0] === 'entries' && parts.length === 4) {
@@ -377,7 +543,7 @@ export function createHubServer(opts) {
                 const tierData = entry?.tiers[tier];
                 if (!entry || !tierData)
                     throw new HttpError(404, 'entry not found');
-                await store.audit(role, 'resolve', kind, name, tier);
+                await store.audit(principal.role, 'resolve', kind, name, tier, actor);
                 return send(res, 200, {
                     kind,
                     name,
@@ -387,8 +553,8 @@ export function createHubServer(opts) {
                     ...(tierData.probe ? { probe: tierData.probe } : {}),
                 });
             }
-            if (role !== 'admin')
-                throw new HttpError(403, 'read token cannot access admin endpoints');
+            if (principal.role !== 'admin')
+                throw new HttpError(403, 'read role cannot access admin endpoints');
             if (method === 'PUT') {
                 const body = await readBody(req);
                 if (!isPlainObject(body.fields))
@@ -397,14 +563,14 @@ export function createHubServer(opts) {
                 const probe = body.probe === undefined ? undefined : sanitizeProbe(body.probe);
                 store.putTier(kind, name, tier, { fields: body.fields, envelope, probe });
                 await store.save();
-                await store.audit(role, 'put', kind, name, tier);
+                await store.audit(principal.role, 'put', kind, name, tier, actor);
                 return send(res, 200, { ok: true });
             }
             if (method === 'DELETE') {
                 if (!store.deleteTier(kind, name, tier))
                     throw new HttpError(404, 'entry not found');
                 await store.save();
-                await store.audit(role, 'delete', kind, name, tier);
+                await store.audit(principal.role, 'delete', kind, name, tier, actor);
                 return send(res, 200, { ok: true });
             }
             throw new HttpError(405, 'method not allowed');

package/lib/store.d.ts

@@ -19,7 +19,10 @@
  *   "requests": { "<uuid>": { "kind": "...", "name": "...", "tier": "rw",
  *     "fields": { ... }, "status": "pending", ... } },
  *   "cases": { "<uuid>": { "title": "...", "symptoms": [...],
- *     "rootCause": "...", "fix": "...", "hitCount": 0, ... } } }
+ *     "rootCause": "...", "fix": "...", "hitCount": 0, ... } },
+ *   "tokens": { "<uuid>": { "name": "alice", "role": "read",
+ *     "hash": "<sha256 hex>", "prefix": "AbCdEfGh", "createdAt": "<ISO>",
+ *     "createdBy": "admin", "expiresAt": "<ISO>" } } }
  * ```
  *
  * `requests` is the agent-registration approval queue (see server.ts
@@ -30,6 +33,11 @@
  * routes): distilled postmortems an agent records after an investigation
  * resolves, searchable by later sessions. Cases hold no secret material.
  *
+ * `tokens` is the named-token roster (ADR-0009, see tokens.ts): every issued
+ * credential keeps its label, role, digest and lifecycle timestamps — never
+ * the plaintext, which exists only in the create response. The static
+ * bootstrap tokens are env/flag configuration and have no record here.
+ *
  * The hub is dumb storage: file fields hold their *content* (inlined at
  * import time) and no kind-specific schema validation happens here.
  *
@@ -39,6 +47,7 @@
  *
  * @module
  */
+import type { HubToken, TokenChange, TokenPatch, TokenRole } from './tokens.js';
 export type TierName = 'ro' | 'rw';
 /** Profile name / kind charset; kinds additionally can never contain `/` (path segment). Shared by the HTTP surface and the offline importer. */
 export declare const NAME_PATTERN: RegExp;
@@ -113,13 +122,24 @@ export type CaseInput = Partial<Omit<CaseRecord, 'id' | 'hitCount' | 'createdAt'
 export interface AuditRecord {
     ts: string;
     role: 'admin' | 'read';
-    action: 'resolve' | 'put' | 'delete' | 'request' | 'approve' | 'reject' | 'case-put' | 'case-hit' | 'case-delete';
+    action: 'resolve' | 'put' | 'delete' | 'request' | 'approve' | 'reject' | 'case-put' | 'case-hit' | 'case-delete' | 'token-create' | 'token-update' | 'token-revoke';
     kind: string;
     name: string;
     /** Absent on `case-*` actions (cases have no tiers). */
     tier?: TierName;
     /** Case title, recorded on `case-*` actions only. */
     title?: string;
+    /**
+     * Label of the named token that performed the action (ADR-0009). Absent for
+     * the static bootstrap tokens — their `role` field already says all there is
+     * to know about them.
+     */
+    actor?: string;
+    /**
+     * Which token fields an edit touched (`token-update` only) — the field
+     * names, never the values, so the line stays a metadata-only record.
+     */
+    changes?: TokenChange[];
 }
 export interface HubStoreOptions {
     dataDir: string;
@@ -186,13 +206,65 @@ export declare class HubStore {
     hitCase(id: string): boolean;
     /** Delete a case. Returns false when absent. */
     deleteCase(id: string): boolean;
+    /** The tokens map, created lazily (old data files predate named tokens). */
+    private tokens;
+    /** Every issued token record, revoked ones included (callers project to `TokenView`). */
+    listTokens(): HubToken[];
+    getToken(id: string): HubToken | undefined;
+    /**
+     * The first *non-revoked* token carrying this label, for uniqueness checks.
+     * A revoked label is reusable — the person it named is gone.
+     */
+    findTokenByName(name: string): HubToken | undefined;
+    /**
+     * The token a presented digest authenticates as, or undefined when no live
+     * token matches. Callers must reject the request either way — a digest that
+     * matches only revoked/expired records is an authentication failure.
+     */
+    findActiveTokenByHash(hash: string, now?: string): HubToken | undefined;
+    /** Whether a digest belongs to any record at all (live or not), for error wording only. */
+    hasTokenHash(hash: string): boolean;
+    /**
+     * Record one issued token. The caller mints the plaintext and passes only
+     * its digest + prefix; uniqueness of `name` and validation of the parsed
+     * inputs are the caller's job. Throws when the roster is at MAX_TOKENS.
+     */
+    putToken(data: {
+        name: string;
+        role: TokenRole;
+        hash: string;
+        prefix: string;
+        createdBy: string;
+        expiresAt?: string;
+    }): HubToken;
+    /**
+     * Revoke one token. Returns false when the id is unknown or the token is
+     * already revoked — revocation is a one-way, terminal state.
+     */
+    revokeToken(id: string): boolean;
+    /**
+     * Apply an operator edit to a live token (ADR-0010). Returns the record plus
+     * the fields that actually changed — an empty list means the patch matched
+     * the current values, so the caller can skip both the save and the audit
+     * line. Throws on a revoked record or a label clash; `null` when the id is
+     * unknown. Validation of the patch values is the caller's job.
+     */
+    updateToken(id: string, patch: TokenPatch): {
+        token: HubToken;
+        changes: TokenChange[];
+    } | null;
+    /** Append one audit line for a token-roster action (kind fixed to 'token', name = token label). */
+    auditToken(role: AuditRecord['role'], action: 'token-create' | 'token-update' | 'token-revoke', token: {
+        id: string;
+        name: string;
+    }, actor?: string, changes?: TokenChange[]): Promise<void>;
     /** Append one audit line for a case action (kind fixed to 'case', name = case id). */
     auditCase(role: AuditRecord['role'], action: 'case-put' | 'case-hit' | 'case-delete', record: {
         id: string;
         title: string;
-    }): Promise<void>;
-    /** Append one audit line. Field values are never recorded. */
-    audit(role: AuditRecord['role'], action: AuditRecord['action'], kind: string, name: string, tier: TierName): Promise<void>;
+    }, actor?: string): Promise<void>;
+    /** Append one audit line. Field values are never recorded; `actor` names the (named) token used. */
+    audit(role: AuditRecord['role'], action: AuditRecord['action'], kind: string, name: string, tier: TierName, actor?: string): Promise<void>;
     private appendAudit;
     /** Read the most recent `limit` audit records, oldest first. */
     readAudit(limit: number): Promise<AuditRecord[]>;

package/lib/store.js

@@ -19,7 +19,10 @@
  *   "requests": { "<uuid>": { "kind": "...", "name": "...", "tier": "rw",
  *     "fields": { ... }, "status": "pending", ... } },
  *   "cases": { "<uuid>": { "title": "...", "symptoms": [...],
- *     "rootCause": "...", "fix": "...", "hitCount": 0, ... } } }
+ *     "rootCause": "...", "fix": "...", "hitCount": 0, ... } },
+ *   "tokens": { "<uuid>": { "name": "alice", "role": "read",
+ *     "hash": "<sha256 hex>", "prefix": "AbCdEfGh", "createdAt": "<ISO>",
+ *     "createdBy": "admin", "expiresAt": "<ISO>" } } }
  * ```
  *
  * `requests` is the agent-registration approval queue (see server.ts
@@ -30,6 +33,11 @@
  * routes): distilled postmortems an agent records after an investigation
  * resolves, searchable by later sessions. Cases hold no secret material.
  *
+ * `tokens` is the named-token roster (ADR-0009, see tokens.ts): every issued
+ * credential keeps its label, role, digest and lifecycle timestamps — never
+ * the plaintext, which exists only in the create response. The static
+ * bootstrap tokens are env/flag configuration and have no record here.
+ *
  * The hub is dumb storage: file fields hold their *content* (inlined at
  * import time) and no kind-specific schema validation happens here.
  *
@@ -43,6 +51,7 @@ import { appendFile, chmod, mkdir, open, readFile, rename } from 'node:fs/promis
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { decryptDoc, encryptDoc, loadMasterKey } from './crypto.js';
+import { hashEqual, isTokenActive, MAX_TOKENS } from './tokens.js';
 /** Profile name / kind charset; kinds additionally can never contain `/` (path segment). Shared by the HTTP surface and the offline importer. */
 export const NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._@-]*$/;
 /** Hard caps on the knowledge base, enforced by the store (it owns the doc). */
@@ -250,13 +259,134 @@ export class HubStore {
         delete this.cases()[id];
         return true;
     }
+    /** The tokens map, created lazily (old data files predate named tokens). */
+    tokens() {
+        return (this.doc.tokens ??= {});
+    }
+    /** Every issued token record, revoked ones included (callers project to `TokenView`). */
+    listTokens() {
+        return Object.values(this.tokens());
+    }
+    getToken(id) {
+        return this.tokens()[id];
+    }
+    /**
+     * The first *non-revoked* token carrying this label, for uniqueness checks.
+     * A revoked label is reusable — the person it named is gone.
+     */
+    findTokenByName(name) {
+        return Object.values(this.tokens()).find((t) => t.revokedAt === undefined && t.name === name);
+    }
+    /**
+     * The token a presented digest authenticates as, or undefined when no live
+     * token matches. Callers must reject the request either way — a digest that
+     * matches only revoked/expired records is an authentication failure.
+     */
+    findActiveTokenByHash(hash, now) {
+        return Object.values(this.tokens()).find((t) => isTokenActive(t, now) && hashEqual(t.hash, hash));
+    }
+    /** Whether a digest belongs to any record at all (live or not), for error wording only. */
+    hasTokenHash(hash) {
+        return Object.values(this.tokens()).some((t) => hashEqual(t.hash, hash));
+    }
+    /**
+     * Record one issued token. The caller mints the plaintext and passes only
+     * its digest + prefix; uniqueness of `name` and validation of the parsed
+     * inputs are the caller's job. Throws when the roster is at MAX_TOKENS.
+     */
+    putToken(data) {
+        if (Object.keys(this.tokens()).length >= MAX_TOKENS) {
+            throw new Error(`token roster is full (${MAX_TOKENS} tokens); revoke stale tokens first`);
+        }
+        const token = {
+            id: randomUUID(),
+            name: data.name,
+            role: data.role,
+            hash: data.hash,
+            prefix: data.prefix,
+            createdAt: new Date().toISOString(),
+            createdBy: data.createdBy,
+            ...(data.expiresAt !== undefined ? { expiresAt: data.expiresAt } : {}),
+        };
+        this.tokens()[token.id] = token;
+        return token;
+    }
+    /**
+     * Revoke one token. Returns false when the id is unknown or the token is
+     * already revoked — revocation is a one-way, terminal state.
+     */
+    revokeToken(id) {
+        const token = this.tokens()[id];
+        if (!token || token.revokedAt !== undefined)
+            return false;
+        token.revokedAt = new Date().toISOString();
+        return true;
+    }
+    /**
+     * Apply an operator edit to a live token (ADR-0010). Returns the record plus
+     * the fields that actually changed — an empty list means the patch matched
+     * the current values, so the caller can skip both the save and the audit
+     * line. Throws on a revoked record or a label clash; `null` when the id is
+     * unknown. Validation of the patch values is the caller's job.
+     */
+    updateToken(id, patch) {
+        const token = this.tokens()[id];
+        if (!token)
+            return null;
+        if (token.revokedAt !== undefined)
+            throw new Error('token is revoked and can no longer be edited');
+        const changes = [];
+        if (patch.name !== undefined && patch.name !== token.name) {
+            const clash = Object.values(this.tokens()).find((t) => t.id !== id && t.revokedAt === undefined && t.name === patch.name);
+            if (clash)
+                throw new Error(`token name '${patch.name}' is already in use`);
+            token.name = patch.name;
+            changes.push('name');
+        }
+        if (patch.role !== undefined && patch.role !== token.role) {
+            token.role = patch.role;
+            changes.push('role');
+        }
+        if (patch.expiresAt !== undefined) {
+            // null = clear the expiry (back to a never-expiring token).
+            const next = patch.expiresAt ?? undefined;
+            if (next !== token.expiresAt) {
+                if (next === undefined)
+                    delete token.expiresAt;
+                else
+                    token.expiresAt = next;
+                changes.push('expiresAt');
+            }
+        }
+        return { token, changes };
+    }
+    /** Append one audit line for a token-roster action (kind fixed to 'token', name = token label). */
+    async auditToken(role, action, token, actor, changes) {
+        await this.appendAudit({
+            ts: new Date().toISOString(),
+            role,
+            action,
+            kind: 'token',
+            name: token.name,
+            ...(actor !== undefined ? { actor } : {}),
+            ...(changes !== undefined ? { changes } : {}),
+        });
+    }
     /** Append one audit line for a case action (kind fixed to 'case', name = case id). */
-    async auditCase(role, action, record) {
-        await this.appendAudit({ ts: new Date().toISOString(), role, action, kind: 'case', name: record.id, title: record.title });
+    async auditCase(role, action, record, actor) {
+        await this.appendAudit({
+            ts: new Date().toISOString(),
+            role,
+            action,
+            kind: 'case',
+            name: record.id,
+            title: record.title,
+            ...(actor !== undefined ? { actor } : {}),
+        });
     }
-    /** Append one audit line. Field values are never recorded. */
-    async audit(role, action, kind, name, tier) {
-        await this.appendAudit({ ts: new Date().toISOString(), role, action, kind, name, tier });
+    /** Append one audit line. Field values are never recorded; `actor` names the (named) token used. */
+    async audit(role, action, kind, name, tier, actor) {
+        await this.appendAudit({ ts: new Date().toISOString(), role, action, kind, name, tier, ...(actor !== undefined ? { actor } : {}) });
     }
     async appendAudit(record) {
         await mkdir(this.dataDir, { recursive: true });