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

package/README.md

@@ -36,6 +36,11 @@ Every `serve` flag has an env counterpart (`ACCESS_HUB_PORT`, `ACCESS_HUB_HOST`,
 | `PUT /entries/:kind/:name/:tier` | admin | upsert `{fields, envelope?, probe?}`; envelope replaces wholesale |
 | `DELETE /entries/:kind/:name/:tier` | admin | removing the last tier deletes the whole entry |
 | `GET /audit?limit=N` | admin | recent N audit records (default 100, cap 1000) |
+| `GET /cases` | read+ | troubleshooting case index rows — metadata only, never full text |
+| `GET /cases/:id` | read+ | one full case record |
+| `POST /cases` / `PUT /cases/:id` | read+ | create / update a case — **deliberate role relaxation**: cases hold no secrets and the agent only carries the read token |
+| `POST /cases/:id/hit` | read+ | bump a case's hit count |
+| `DELETE /cases/:id` | admin | remove a case |
 
 ## Security notes
 

package/lib/import.js

@@ -20,6 +20,7 @@ import { readFile } from 'node:fs/promises';
 import os from 'node:os';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
+import { NAME_PATTERN } from './store.js';
 const PATH_PREFIX = /^(\/|~\/|\.\/|\.\.\/)/;
 /** A value is path-shaped when it is a single-line string with a path prefix. */
 function looksLikePath(v) {
@@ -113,6 +114,13 @@ export async function pushToHub(hubUrl, adminToken, entries) {
 /** Write imported entries directly into a store (offline mode; caller owns init/save). */
 export function applyToStore(store, entries) {
     for (const entry of entries) {
+        // Same charset rule as the HTTP surface (spec 0006): an offline import
+        // bypasses segment(), so a hand-edited registry could otherwise smuggle
+        // a name the API can neither resolve nor delete into the store.
+        for (const [what, value] of [['kind', entry.kind], ['name', entry.name]]) {
+            if (!NAME_PATTERN.test(value))
+                throw new Error(`import: invalid ${what} ${JSON.stringify(value)}: must match ${NAME_PATTERN.source}`);
+        }
         for (const tier of ['ro', 'rw']) {
             const tierData = entry.tiers[tier];
             if (!tierData)

package/lib/index.d.ts

@@ -11,8 +11,8 @@
  * @module @elinpf/dsh-ops-access-hub
  */
 export { MASTER_KEY_BYTES, generateMasterKey, parseMasterKey, loadMasterKey, encryptDoc, decryptDoc } from './crypto.js';
-export { HubStore } from './store.js';
-export type { TierName, ProbeState, EntryEnvelope, TierData, HubEntry, AuditRecord, HubStoreOptions } from './store.js';
+export { HubStore, MAX_CASES } from './store.js';
+export type { TierName, ProbeState, EntryEnvelope, TierData, HubEntry, AuditRecord, HubStoreOptions, CaseRecord, CaseInput } from './store.js';
 export { createHubServer, NAME_PATTERN } from './server.js';
 export type { HubServerOptions } from './server.js';
 export { importRegistry, pushToHub, applyToStore } from './import.js';

package/lib/index.js

@@ -11,7 +11,7 @@
  * @module @elinpf/dsh-ops-access-hub
  */
 export { MASTER_KEY_BYTES, generateMasterKey, parseMasterKey, loadMasterKey, encryptDoc, decryptDoc } from './crypto.js';
-export { HubStore } from './store.js';
+export { HubStore, MAX_CASES } from './store.js';
 export { createHubServer, NAME_PATTERN } from './server.js';
 export { importRegistry, pushToHub, applyToStore } from './import.js';
 export { WEB_UI_HTML } from './web.js';

package/lib/server.d.ts

@@ -20,6 +20,14 @@
  * - `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)
  *
  * Auth: two Bearer tokens — admin (everything) and read (`GET /entries*`
  * only). Comparisons use `crypto.timingSafeEqual`. Every error response is
@@ -29,8 +37,8 @@
  */
 import type { Server } from 'node:http';
 import type { HubStore } from './store.js';
-/** Profile name / kind charset; kinds additionally can never contain `/` (path segment). */
-export declare const NAME_PATTERN: RegExp;
+import { NAME_PATTERN } from './store.js';
+export { NAME_PATTERN };
 export interface HubServerOptions {
     store: HubStore;
     adminToken: string;

package/lib/server.js

@@ -20,6 +20,14 @@
  * - `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)
  *
  * Auth: two Bearer tokens — admin (everything) and read (`GET /entries*`
  * only). Comparisons use `crypto.timingSafeEqual`. Every error response is
@@ -29,9 +37,9 @@
  */
 import { timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
+import { NAME_PATTERN } from './store.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;
@@ -136,6 +144,56 @@ 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;
+}
 export function createHubServer(opts) {
     const { store } = opts;
     async function handle(req, res) {
@@ -249,6 +307,67 @@ export function createHubServer(opts) {
             await store.audit(role, body.approved ? 'approve' : 'reject', request.kind, request.name, request.tier);
             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(role, 'case-put', record);
+                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(role, 'case-put', record);
+                return send(res, 200, { ok: true });
+            }
+            if (method === 'DELETE') {
+                if (role !== 'admin')
+                    throw new HttpError(403, 'read token 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);
+                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(role, 'case-hit', record);
+            return send(res, 200, { ok: true });
+        }
         if (parts[0] === 'entries' && parts.length === 4) {
             const kind = segment(parts[1], 'kind');
             const name = segment(parts[2], 'name');

package/lib/store.d.ts

@@ -17,13 +17,19 @@
  *     "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, ... } } }
  * ```
  *
  * `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.
+ *
  * The hub is dumb storage: file fields hold their *content* (inlined at
  * import time) and no kind-specific schema validation happens here.
  *
@@ -34,6 +40,8 @@
  * @module
  */
 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 +84,42 @@ 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';
     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;
 }
 export interface HubStoreOptions {
     dataDir: string;
@@ -134,8 +171,29 @@ export declare class HubStore {
      * pending.
      */
     decideRequest(id: string, approved: boolean): RegistrationRequest | null;
+    /** 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;
+    /** 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>;
+    private appendAudit;
     /** Read the most recent `limit` audit records, oldest first. */
     readAudit(limit: number): Promise<AuditRecord[]>;
 }

package/lib/store.js

@@ -17,13 +17,19 @@
  *     "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, ... } } }
  * ```
  *
  * `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.
+ *
  * The hub is dumb storage: file fields hold their *content* (inlined at
  * import time) and no kind-specific schema validation happens here.
  *
@@ -37,6 +43,10 @@ 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';
+/** 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). */
+export const MAX_CASES = 500;
 export class HubStore {
     dataDir;
     dataFile;
@@ -171,9 +181,84 @@ export class HubStore {
         request.fields = {};
         return request;
     }
+    /** The cases map, created lazily (old data files predate the knowledge base). */
+    cases() {
+        return (this.doc.cases ??= {});
+    }
+    /** Case index rows — metadata only, never the full text fields. */
+    listCases() {
+        return Object.values(this.cases()).map((c) => ({
+            id: c.id,
+            title: c.title,
+            symptoms: c.symptoms,
+            tags: c.tags,
+            hitCount: c.hitCount,
+            updatedAt: c.updatedAt,
+        }));
+    }
+    getCase(id) {
+        return this.cases()[id];
+    }
+    /**
+     * 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, id) {
+        const now = new Date().toISOString();
+        if (id !== undefined) {
+            const existing = this.cases()[id];
+            if (!existing)
+                return null;
+            Object.assign(existing, input);
+            existing.updatedAt = now;
+            return existing;
+        }
+        if (Object.keys(this.cases()).length >= MAX_CASES) {
+            throw new Error(`knowledge base is full (${MAX_CASES} cases); delete stale cases first`);
+        }
+        const record = {
+            id: randomUUID(),
+            title: input.title ?? '',
+            symptoms: input.symptoms ?? [],
+            rootCause: input.rootCause ?? '',
+            fix: input.fix ?? '',
+            ...(input.evidence !== undefined ? { evidence: input.evidence } : {}),
+            ...(input.methodology !== undefined ? { methodology: input.methodology } : {}),
+            ...(input.difficulty !== undefined ? { difficulty: input.difficulty } : {}),
+            tags: input.tags ?? [],
+            ...(input.environment !== undefined ? { environment: input.environment } : {}),
+            hitCount: 0,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.cases()[record.id] = record;
+        return record;
+    }
+    /** Bump a case's hit count. Returns false when absent. */
+    hitCase(id) {
+        const record = this.cases()[id];
+        if (!record)
+            return false;
+        record.hitCount += 1;
+        return true;
+    }
+    /** Delete a case. Returns false when absent. */
+    deleteCase(id) {
+        if (!this.cases()[id])
+            return false;
+        delete this.cases()[id];
+        return true;
+    }
+    /** 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 });
+    }
     /** Append one audit line. Field values are never recorded. */
     async audit(role, action, kind, name, tier) {
-        const record = { ts: new Date().toISOString(), role, action, kind, name, tier };
+        await this.appendAudit({ ts: new Date().toISOString(), role, action, kind, name, tier });
+    }
+    async appendAudit(record) {
         await mkdir(this.dataDir, { recursive: true });
         // A crash mid-append can leave a torn tail line without a newline; a
         // naive append would fuse the next record onto it and lose both. Start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elinpf/dsh-ops-access-hub",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Standalone credential hub for the dsh ops suite: encrypted-at-rest storage, token-authenticated REST API, minimal web UI, and a YAML registry importer. Not a dsh plugin.",
   "type": "module",
   "main": "lib/index.js",
@@ -17,7 +17,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.4.0",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "@elinpf/dsh-ops-test-support": "0.0.0"
   },
   "license": "MIT",
   "exports": {