@elinpf/dsh-ops-access 0.1.7 → 0.2.1

package/lib/hub-backend.js

@@ -0,0 +1,268 @@
+/**
+ * Hub backend: fetch credentials from a remote ops-access-hub service.
+ *
+ * The hub stores file-field CONTENT; this backend converts at the boundary:
+ *
+ * - `loadTier` downloads the tier's fields and MATERIALIZES each declared
+ *   file field to a managed local file (`<credentialsDir>/<kind>/<name>/<tier>/<field>`,
+ *   0600, atomic write, skipped when the content is unchanged), substituting
+ *   the local path — so downstream consumers (kubectl/ssh CLIs, provider
+ *   schemas, probes) see exactly the same provider-shaped profile the YAML
+ *   backend serves, and secret paths never leave the machine.
+ * - `putTier` reads the managed local files back and uploads their CONTENT
+ *   (the write path — register_access, the admin UI — stages content files
+ *   locally first, exactly as in YAML mode).
+ *
+ * Every call hits the hub — nothing is cached, mirroring the YAML backend's
+ * re-read-on-every-call discipline. Listing and metadata reads never carry
+ * field values; secret content crosses the wire only on the resolve and
+ * write paths, over the operator-managed channel (the hub binds loopback or
+ * sits behind a TLS-terminating reverse proxy).
+ *
+ * @module @elinpf/dsh-ops-access/hub-backend
+ */
+import { mkdir, readdir, readFile, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import os from 'node:os';
+import { buildEnvelope, isPlainObject, mergeEnvelope, probeOf } from './backend.js';
+/** Expand a leading `~` (or `~/`) to the user's home directory. */
+function expandHome(p) {
+    const home = process.env.HOME ?? os.homedir();
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/'))
+        return home + p.slice(1);
+    return p;
+}
+/**
+ * Write content to a managed file, skipping the write when the on-disk
+ * bytes already match (resolve runs on every tool call — touching the file
+ * every time would churn mtimes and race concurrent writers). Atomic via
+ * write-temp-then-rename; mode 0600 — the file carries secret material.
+ */
+async function writeIfChanged(filePath, content) {
+    try {
+        if ((await readFile(filePath, 'utf8')) === content)
+            return;
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            throw err;
+    }
+    await mkdir(dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    await writeFile(tmp, content, { encoding: 'utf8', mode: 0o600 });
+    await rename(tmp, filePath);
+}
+/**
+ * Delete materialized credential files older than maxAgeMs under
+ * credentialsDir (pass 0 to sweep everything), then remove the directories
+ * left empty. In hub mode every local credential file is a TTL-bound cache
+ * of hub content — never a permanent copy: resolve re-materializes on demand
+ * (writeIfChanged), so deletion is always safe and transparent to consumers.
+ * Best-effort: individual failures are skipped, the next sweep retries.
+ * Returns the number of files removed.
+ */
+export async function sweepMaterialized(credentialsDir, maxAgeMs) {
+    const now = Date.now();
+    let removed = 0;
+    const walk = async (dir, isRoot) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // missing/unreadable dir — nothing to sweep
+        }
+        for (const entry of entries) {
+            const p = `${dir}/${entry.name}`;
+            if (entry.isDirectory()) {
+                await walk(p, false);
+            }
+            else {
+                const st = await stat(p).catch(() => null);
+                if (!st || !st.isFile())
+                    continue;
+                if (maxAgeMs > 0 && now - st.mtimeMs <= maxAgeMs)
+                    continue;
+                await rm(p, { force: true }).catch(() => { });
+                removed++;
+            }
+        }
+        // Prune emptied dirs on the way up (rmdir refuses non-empty — a
+        // concurrent materialization racing the sweep is never harmed).
+        if (!isRoot)
+            await rmdir(dir).catch(() => { });
+    };
+    await walk(credentialsDir, true);
+    return removed;
+}
+/** Sanitize one entry of the hub's GET /entries response (durable boundary). */ function sanitizeEntry(raw) {
+    if (!isPlainObject(raw))
+        return null;
+    if (typeof raw.kind !== 'string' || typeof raw.name !== 'string')
+        return null;
+    const tiers = {};
+    if (isPlainObject(raw.tiers)) {
+        for (const tier of ['ro', 'rw']) {
+            const t = raw.tiers[tier];
+            if (t === undefined || t === null)
+                continue;
+            const probe = probeOf(t);
+            tiers[tier] = probe !== undefined ? { probe } : {};
+        }
+    }
+    return { kind: raw.kind, name: raw.name, envelope: buildEnvelope([isPlainObject(raw.envelope) ? raw.envelope : undefined]), tiers };
+}
+export class HubBackend {
+    opts;
+    label;
+    constructor(opts) {
+        this.opts = opts;
+        this.label = `access hub at ${opts.baseUrl}`;
+    }
+    /**
+     * One HTTP call. Returns null on 404; throws on every other failure with
+     * the hub's error message (which never carries field values). The auth
+     * token rides an Authorization header and never lands in error text.
+     */
+    async request(method, path, body, admin = false) {
+        const token = admin ? this.opts.adminToken : this.opts.readToken;
+        let res;
+        try {
+            res = await fetch(this.opts.baseUrl + path, {
+                method,
+                headers: {
+                    ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+                    ...(token !== '' ? { authorization: `Bearer ${token}` } : {}),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (err) {
+            throw new Error(`ops-access: cannot reach ${this.label}: ${err?.message ?? err}`);
+        }
+        if (res.status === 404)
+            return null;
+        const text = await res.text();
+        let parsed = null;
+        if (text !== '') {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                throw new Error(`ops-access: ${this.label} returned a non-JSON response (${res.status})`);
+            }
+        }
+        if (!res.ok) {
+            const message = isPlainObject(parsed) && typeof parsed.error === 'string' ? parsed.error : res.statusText;
+            throw new Error(`ops-access: ${this.label} rejected ${method} ${path} (${res.status}): ${message}`);
+        }
+        return parsed;
+    }
+    async listEntries() {
+        const data = await this.request('GET', '/entries');
+        if (!Array.isArray(data))
+            return [];
+        return data
+            .map(sanitizeEntry)
+            .filter((e) => e !== null)
+            .sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+    }
+    async loadTier(kind, name, tier, loadOpts) {
+        const data = await this.request('GET', `/entries/${encodeURIComponent(kind)}/${encodeURIComponent(name)}/${tier}`);
+        if (data === null || !isPlainObject(data) || !isPlainObject(data.fields))
+            return null;
+        const fields = { ...data.fields };
+        const provider = this.opts.getProvider(kind);
+        const materialize = loadOpts?.materialize !== false;
+        // File fields arrive as CONTENT; substitute the managed local path,
+        // writing the file only when the credential is actually being issued
+        // (materialize) — metadata reads must not persist secret material.
+        for (const ff of provider?.fileFields ?? []) {
+            const content = fields[ff];
+            if (typeof content !== 'string' || content === '')
+                continue;
+            const target = `${this.opts.cacheDir}/${kind}/${name}/${tier}/${ff}`;
+            if (materialize)
+                await writeIfChanged(target, content);
+            fields[ff] = target;
+        }
+        const probe = probeOf(data);
+        return {
+            fields,
+            envelope: buildEnvelope([isPlainObject(data.envelope) ? data.envelope : undefined]),
+            ...(probe !== undefined ? { probe } : {}),
+        };
+    }
+    async putTier(kind, name, tier, fields, envelope, probe) {
+        const provider = this.opts.getProvider(kind);
+        const out = { ...fields };
+        // Paths → content: the hub stores the secret material itself. An
+        // unreadable managed file fails loud — a half-written credential on the
+        // hub is worse than no write.
+        for (const ff of provider?.fileFields ?? []) {
+            const value = out[ff];
+            if (typeof value !== 'string' || value === '')
+                continue;
+            const source = expandHome(value);
+            try {
+                out[ff] = await readFile(source, 'utf8');
+            }
+            catch (err) {
+                throw new Error(`ops-access: cannot read credential file ${source} for upload to the hub: ${err?.message ?? err}`);
+            }
+        }
+        // Envelope merge needs the entry's current envelope (the hub replaces it
+        // wholesale); the fields-free listing carries it.
+        const entries = await this.listEntries().catch(() => []);
+        const existing = entries.find((e) => e.kind === kind && e.name === name);
+        const merged = mergeEnvelope(existing?.envelope ?? {}, envelope);
+        await this.request('PUT', `/entries/${encodeURIComponent(kind)}/${encodeURIComponent(name)}/${tier}`, {
+            fields: out,
+            envelope: merged,
+            ...(probe !== undefined ? { probe } : {}),
+        }, true);
+    }
+    async deleteTier(kind, name, tier) {
+        const res = await this.request('DELETE', `/entries/${encodeURIComponent(kind)}/${encodeURIComponent(name)}/${tier}`, undefined, true);
+        if (res === null)
+            return 'missing';
+        // Whether the whole entry went with the tier decides the managed-dir
+        // cleanup scope — re-list and look.
+        const entries = await this.listEntries().catch(() => []);
+        return entries.some((e) => e.kind === kind && e.name === name) ? 'tier' : 'entry';
+    }
+    // ── Registration-request queue (hub-only, not part of AccessBackend) ──────
+    // The agent-facing rw write path: submit a request, a human approves it in
+    // the admin UI, and only then does the hub write the tier. Fields carry
+    // CONTENT here (the agent pastes secret material directly — there is no
+    // local staging file on this path).
+    async submitRequest(req) {
+        const data = await this.request('POST', '/requests', {
+            kind: req.kind,
+            name: req.name,
+            tier: req.tier,
+            fields: req.fields,
+            ...(req.envelope !== undefined ? { envelope: req.envelope } : {}),
+            ...(req.reason !== undefined ? { reason: req.reason } : {}),
+        }, true);
+        if (!isPlainObject(data) || typeof data.id !== 'string') {
+            throw new Error(`ops-access: ${this.label} returned a malformed request id`);
+        }
+        return data.id;
+    }
+    /** Pending-request metadata for the approval UI — field values never cross. */
+    async listRequests(status) {
+        return this.request('GET', status === undefined ? '/requests' : `/requests?status=${status}`);
+    }
+    /** Full request incl. field values, for pre-approval review. Null when absent. */
+    async getRequest(id) {
+        return this.request('GET', `/requests/${encodeURIComponent(id)}`, undefined, true);
+    }
+    /** Approve (hub writes the tier) or reject. Returns false when already settled/absent. */
+    async decideRequest(id, approved) {
+        const data = await this.request('POST', `/requests/${encodeURIComponent(id)}/decide`, { approved }, true);
+        return data !== null;
+    }
+}

package/lib/index.d.ts

@@ -1,21 +1,26 @@
 /**
  * Ops access capability seam.
  *
- * Owns the YAML credential registry file (default `~/.dsh-ops/access.yaml`)
- * and exposes `ctx.opsAccess`: a generic `resolve(kind, name)` / `list()`
- * entry plus a `register(provider)` surface for provider plugins. Providers
- * (one per credential kind) supply the zod schema for their entry shape and
- * an optional `process` step (e.g. `~` expansion); secret material never
- * leaves the filesystem — profiles carry only paths and connection params.
+ * Exposes `ctx.opsAccess`: a generic `resolve(kind, name)` / `list()` entry
+ * plus a `register(provider)` surface for provider plugins. Providers (one
+ * per credential kind) supply the zod schema for their entry shape and an
+ * optional `process` step (e.g. `~` expansion); profiles carry only paths
+ * and connection params, never inline secret material.
  *
- * The registry file is re-read, re-parsed, and re-validated on every call —
- * edits take effect immediately, nothing is cached.
+ * The credential SOURCE is pluggable (see backend.ts):
+ * - 'yaml' (default) owns the local YAML registry file
+ *   (`~/.dsh-ops/access.yaml`), re-read, re-parsed, and re-validated on
+ *   every call — edits take effect immediately, nothing is cached.
+ * - 'hub' fetches entries from a remote ops-access-hub service on every
+ *   call (hub-backend.ts): file-field CONTENT is materialized to managed
+ *   local files at resolve time, so profiles still carry only paths.
  *
  * Also registers the `register_access` tool: the agent's self-service path
- * for writing the ro tier of a profile (rw tiers stay human-managed via the
- * admin HTTP routes below).
+ * for writing the ro tier of a profile. rw tiers stay human-approved — the
+ * tool can only QUEUE an rw registration request on the hub (hub mode);
+ * a human approves it in the admin UI before anything is written.
  *
- * Registry format:
+ * Registry format (yaml source):
  *
  * ```yaml
  * version: 1
@@ -42,10 +47,37 @@ import type { AccessProvider, AccessBroker, OpsAccess } from './types.js';
 export declare const name = "ops-access";
 export declare const inject: string[];
 export interface Config {
-    /** Path to the YAML access registry; a leading `~` expands to $HOME. */
+    /** Path to the YAML access registry; a leading `~` expands to $HOME. (source: 'yaml') */
     registryFile: string;
     /** Root directory for managed credential content files; a leading `~` expands to $HOME. */
     credentialsDir: string;
+    /**
+     * Credential source: 'yaml' (default) reads the local registry file;
+     * 'hub' fetches entries from a remote ops-access-hub service on every
+     * call and materializes file-field content to managed local files.
+     */
+    source?: 'yaml' | 'hub';
+    /** Hub base URL (source: 'hub'), e.g. http://127.0.0.1:3090. */
+    hubUrl?: string;
+    /** Hub read token (source: 'hub'); falls back to env ACCESS_HUB_READ_TOKEN. Never logged. */
+    hubToken?: string;
+    /** Hub admin token for write/delete (source: 'hub'); falls back to env ACCESS_HUB_ADMIN_TOKEN. Never logged. */
+    hubAdminToken?: string;
+    /**
+     * Minutes a materialized credential file may linger on this host (source:
+     * 'hub'). Materialized files are a TTL-bound cache of hub content, never a
+     * permanent copy — resolve re-materializes on demand, so expiry is
+     * transparent to consumers. Startup sweeps everything (a restart clears
+     * the grant ledger; cached rw material must not outlive it).
+     */
+    materializeTtlMinutes?: number;
+    /**
+     * Cache root for hub-mode materialized files (source: 'hub'; default
+     * `~/.dsh-ops/hub-cache`). Deliberately separate from credentialsDir: the
+     * sweeper only ever walks this dir, so files the yaml registry references
+     * (the documented fallback) are never touched.
+     */
+    hubCacheDir?: string;
 }
 export declare const Config: z<Config>;
 export type { AccessProvider, AccessProfile, EntryEnvelope, ProbeState, AdminTierStatus, AdminEntry, KindDescriptor, AccessAgent, AccessBrokerDecision, AccessBroker, OpsAccess, } from './types.js';