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

package/lib/server.js

@@ -20,18 +20,43 @@
  * - `POST /requests/:id/decide`          → `{approved:boolean}`; approval writes the
  *                                          tier, either way the request's fields are
  *                                          wiped (admin; 409 unless pending)
+ * - `GET /cases`                         → case index rows, metadata only (read+)
+ * - `GET /cases/:id`                     → full case record (read+)
+ * - `POST /cases` / `PUT /cases/:id`     → create / update a troubleshooting case
+ *                                          (read+ — a deliberate relaxation: cases hold
+ *                                          no secrets and the agent only carries the
+ *                                          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';
-/** Profile name / kind charset; kinds additionally can never contain `/` (path segment). */
-export const NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._@-]*$/;
+export { NAME_PATTERN };
 const MAX_BODY_BYTES = 4 * 1024 * 1024;
 class HttpError extends Error {
     status;
@@ -50,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' });
@@ -136,6 +182,78 @@ function tierOf(raw) {
         return raw;
     throw new HttpError(400, "tier must be 'ro' or 'rw'");
 }
+/** One case record may not exceed this size once serialized (defense against an agent flooding the store). */
+const MAX_CASE_BYTES = 32 * 1024;
+const CASE_STRING_FIELDS = ['title', 'rootCause', 'fix', 'evidence', 'methodology', 'environment'];
+const CASE_LIST_FIELDS = ['symptoms', 'tags'];
+/**
+ * Validate a case write body. `partial` (PUT) requires at least one known
+ * field; otherwise (POST) title/rootCause/fix are required non-empty.
+ */
+function sanitizeCaseInput(raw, partial) {
+    if (!isPlainObject(raw))
+        throw new HttpError(400, 'request body must be a JSON object');
+    const out = {};
+    for (const key of CASE_STRING_FIELDS) {
+        const value = raw[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'string')
+            throw new HttpError(400, `${key} must be a string`);
+        out[key] = value;
+    }
+    for (const key of CASE_LIST_FIELDS) {
+        const value = raw[key];
+        if (value === undefined)
+            continue;
+        if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+            throw new HttpError(400, `${key} must be an array of strings`);
+        }
+        out[key] = value;
+    }
+    if (raw.difficulty !== undefined) {
+        const d = raw.difficulty;
+        if (typeof d !== 'number' || !Number.isInteger(d) || d < 1 || d > 5) {
+            throw new HttpError(400, 'difficulty must be an integer between 1 and 5');
+        }
+        out.difficulty = d;
+    }
+    if (Object.keys(out).length === 0)
+        throw new HttpError(400, 'no case fields to write');
+    if (!partial) {
+        for (const key of ['title', 'rootCause', 'fix']) {
+            if (typeof out[key] !== 'string' || out[key].trim() === '') {
+                throw new HttpError(400, `${key} is required and must be non-empty`);
+            }
+        }
+    }
+    if (JSON.stringify(out).length > MAX_CASE_BYTES) {
+        throw new HttpError(400, `case exceeds ${MAX_CASE_BYTES} bytes`);
+    }
+    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) {
@@ -150,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) => ({
@@ -168,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) {
@@ -181,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).
@@ -202,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');
@@ -216,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);
@@ -246,7 +470,68 @@ 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) {
+            if (method === 'GET') {
+                // Index rows only — full text comes from GET /cases/:id.
+                return send(res, 200, store.listCases());
+            }
+            if (method === 'POST') {
+                // Deliberate role relaxation: cases hold no secrets, and the agent
+                // only carries the read token — read+ may write the knowledge base.
+                const input = sanitizeCaseInput(await readBody(req), false);
+                let record;
+                try {
+                    record = store.putCase(input);
+                }
+                catch (err) {
+                    throw new HttpError(400, err.message);
+                }
+                await store.save();
+                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');
+        }
+        if (parts[0] === 'cases' && parts.length === 2) {
+            const id = parts[1];
+            if (method === 'GET') {
+                const record = store.getCase(id);
+                if (!record)
+                    throw new HttpError(404, 'case not found');
+                return send(res, 200, record);
+            }
+            if (method === 'PUT') {
+                const input = sanitizeCaseInput(await readBody(req), true);
+                const record = store.putCase(input, id);
+                if (!record)
+                    throw new HttpError(404, 'case not found');
+                await store.save();
+                await store.auditCase(principal.role, 'case-put', record, actor);
+                return send(res, 200, { ok: true });
+            }
+            if (method === 'DELETE') {
+                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(principal.role, 'case-delete', existing, actor);
+                return send(res, 200, { ok: true });
+            }
+            throw new HttpError(405, 'method not allowed');
+        }
+        if (parts[0] === 'cases' && parts.length === 3 && parts[2] === 'hit') {
+            if (method !== 'POST')
+                throw new HttpError(405, 'method not allowed');
+            const record = store.getCase(parts[1]);
+            if (!record || !store.hitCase(parts[1]))
+                throw new HttpError(404, 'case not found');
+            await store.save();
+            await store.auditCase(principal.role, 'case-hit', record, actor);
             return send(res, 200, { ok: true });
         }
         if (parts[0] === 'entries' && parts.length === 4) {
@@ -258,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,
@@ -268,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))
@@ -278,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

@@ -17,13 +17,27 @@
  *     "tiers": { "ro": { "fields": { ... }, "probe": { ... } }, "rw": { "fields": { ... } } },
  *     "updatedAt": "<ISO>" } },
  *   "requests": { "<uuid>": { "kind": "...", "name": "...", "tier": "rw",
- *     "fields": { ... }, "status": "pending", ... } } }
+ *     "fields": { ... }, "status": "pending", ... } },
+ *   "cases": { "<uuid>": { "title": "...", "symptoms": [...],
+ *     "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
  * `/requests` routes); a decided request keeps its metadata but its `fields`
  * are wiped.
  *
+ * `cases` is the troubleshooting knowledge base (see server.ts `/cases`
+ * 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.
  *
@@ -33,7 +47,10 @@
  *
  * @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;
 export interface ProbeState {
     status: 'verified' | 'mismatch' | 'unverifiable';
     detail?: string;
@@ -76,13 +93,53 @@ export interface RegistrationRequest {
     createdAt: string;
     decidedAt?: string;
 }
+/** Hard caps on the knowledge base, enforced by the store (it owns the doc). */
+export declare const MAX_CASES = 500;
+/**
+ * A distilled troubleshooting postmortem. `hitCount` rises every time a
+ * later session reports the case as useful, so the valuable cases float to
+ * the top of the index and the rest sink.
+ */
+export interface CaseRecord {
+    id: string;
+    title: string;
+    symptoms: string[];
+    rootCause: string;
+    fix: string;
+    evidence?: string;
+    /** How the root cause was found — the discriminating steps/commands, for reuse in similar-but-not-identical situations. */
+    methodology?: string;
+    /** Self-assessed diagnosis difficulty, 1 (obvious at a glance) to 5 (multi-day, cross-system). */
+    difficulty?: number;
+    tags: string[];
+    environment?: string;
+    hitCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Fields a client may write on a case; the server owns id/hitCount/timestamps. */
+export type CaseInput = Partial<Omit<CaseRecord, 'id' | 'hitCount' | 'createdAt' | 'updatedAt'>>;
 export interface AuditRecord {
     ts: string;
     role: 'admin' | 'read';
-    action: 'resolve' | 'put' | 'delete' | 'request' | 'approve' | 'reject';
+    action: 'resolve' | 'put' | 'delete' | 'request' | 'approve' | 'reject' | 'case-put' | 'case-hit' | 'case-delete' | 'token-create' | 'token-update' | 'token-revoke';
     kind: string;
     name: string;
-    tier: TierName;
+    /** 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;
@@ -134,8 +191,81 @@ export declare class HubStore {
      * pending.
      */
     decideRequest(id: string, approved: boolean): RegistrationRequest | null;
-    /** Append one audit line. Field values are never recorded. */
-    audit(role: AuditRecord['role'], action: AuditRecord['action'], kind: string, name: string, tier: TierName): Promise<void>;
+    /** The cases map, created lazily (old data files predate the knowledge base). */
+    private cases;
+    /** Case index rows — metadata only, never the full text fields. */
+    listCases(): Array<Pick<CaseRecord, 'id' | 'title' | 'symptoms' | 'tags' | 'hitCount' | 'updatedAt'>>;
+    getCase(id: string): CaseRecord | undefined;
+    /**
+     * Create a case, or update one when `id` is given (only the provided
+     * fields change; hitCount/createdAt survive). Returns null when updating
+     * an absent id. Throws when the knowledge base is at MAX_CASES.
+     */
+    putCase(input: CaseInput, id?: string): CaseRecord | null;
+    /** Bump a case's hit count. Returns false when absent. */
+    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;
+    }, 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[]>;
 }