@elinpf/dsh-ops-access 0.2.0 → 0.3.0

package/lib/backend.js

@@ -0,0 +1,227 @@
+/**
+ * Credential-source backends for the ops-access seam.
+ *
+ * The `OpsAccess` handle (index.ts) owns policy — broker decisions, profile
+ * validation via provider schemas, envelope merge semantics, probes — and
+ * delegates raw entry persistence to an `AccessBackend`. Two backends exist:
+ *
+ * - `YamlBackend` — the original local YAML registry file (default).
+ * - `HubBackend` (hub-backend.ts) — a remote ops-access-hub service; secret
+ *   content is fetched per resolve and materialized to managed local files.
+ *
+ * Both speak the same provider-shaped language: file fields are LOCAL PATHS
+ * in `fields` (the hub backend converts content ↔ path at its boundary), the
+ * envelope (`name`/`description`/`environment`) is per-entry, and a `probe`
+ * may ride beside each tier.
+ *
+ * @module @elinpf/dsh-ops-access/backend
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+// ── Shared helpers ───────────────────────────────────────────────────────────
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Build an EntryEnvelope from raw entry data, taking each envelope field from the first source that has it. */
+export function buildEnvelope(sources) {
+    const envelope = {};
+    for (const source of sources) {
+        if (!isPlainObject(source))
+            continue;
+        if (envelope.name === undefined && typeof source.name === 'string')
+            envelope.name = source.name;
+        if (envelope.description === undefined && typeof source.description === 'string')
+            envelope.description = source.description;
+        if (envelope.environment === undefined && typeof source.environment === 'string')
+            envelope.environment = source.environment;
+    }
+    return envelope;
+}
+/** Read a persisted probe result off a raw tier object (durable boundary — sanitize). */
+export function probeOf(tierRaw) {
+    if (!isPlainObject(tierRaw))
+        return undefined;
+    const p = tierRaw.probe;
+    if (!isPlainObject(p))
+        return undefined;
+    const probe = p;
+    if (probe.status !== 'verified' && probe.status !== 'mismatch' && probe.status !== 'unverifiable')
+        return undefined;
+    if (typeof probe.probedAt !== 'string')
+        return undefined;
+    const out = { status: probe.status, probedAt: probe.probedAt };
+    if (typeof probe.detail === 'string')
+        out.detail = probe.detail;
+    return out;
+}
+/**
+ * Apply the envelope patch discipline to a mutable target: undefined field =
+ * preserve, empty string = delete, else set. Shared by both backends so the
+ * merge semantics stay identical across sources.
+ */
+export function applyEnvelopePatch(target, envelope) {
+    if (envelope === undefined)
+        return;
+    for (const key of ['name', 'description', 'environment']) {
+        const value = envelope[key];
+        if (value === undefined)
+            continue;
+        if (value === '')
+            delete target[key];
+        else
+            target[key] = value;
+    }
+}
+/** Merge an envelope patch over an existing envelope, returning the result (hub backend variant). */
+export function mergeEnvelope(existing, patch) {
+    const target = { ...existing };
+    applyEnvelopePatch(target, patch);
+    return buildEnvelope([target]);
+}
+/** Thrown when the source itself is unavailable (yaml: registry file missing) — resolve surfaces it verbatim. */
+export class SourceUnavailableError extends Error {
+}
+/**
+ * Read and parse the registry file. Returns null when the file does not
+ * exist so callers can pick their own discipline (list → empty, resolve →
+ * error). Never includes raw file text in errors.
+ */
+async function loadRegistry(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        throw new Error(`ops-access: failed to read registry file ${file}: ${err?.message ?? err}`);
+    }
+    let doc;
+    try {
+        doc = parseYaml(text);
+    }
+    catch (err) {
+        // First line only — the yaml library appends a source snippet to its
+        // messages, and raw registry text must not leak into errors.
+        const summary = String(err?.message ?? err).split('\n')[0];
+        throw new Error(`ops-access: failed to parse registry file ${file}: ${summary}`);
+    }
+    // An empty file parses to null — treat it as an empty registry.
+    if (doc == null)
+        return {};
+    if (!isPlainObject(doc)) {
+        throw new Error(`ops-access: registry file ${file} must contain a top-level mapping`);
+    }
+    const registry = {};
+    for (const [kind, section] of Object.entries(doc)) {
+        if (kind === 'version')
+            continue;
+        if (!isPlainObject(section)) {
+            throw new Error(`ops-access: section "${kind}" in registry file ${file} must be a mapping of profile names`);
+        }
+        registry[kind] = section;
+    }
+    return registry;
+}
+/** Serialize a registry back to its YAML file with the version header. */
+async function saveRegistry(file, registry) {
+    const doc = { version: 1 };
+    for (const [kind, section] of Object.entries(registry)) {
+        doc[kind] = section;
+    }
+    await writeFile(file, stringifyYaml(doc), 'utf8');
+}
+/**
+ * The original local YAML registry. Every operation re-reads (and writes
+ * back) the whole file — edits take effect immediately, nothing is cached.
+ * Sections whose kind has no registered provider are preserved untouched.
+ */
+export class YamlBackend {
+    registryFile;
+    label;
+    constructor(registryFile) {
+        this.registryFile = registryFile;
+        this.label = `registry file ${registryFile}`;
+    }
+    async listEntries() {
+        const registry = await loadRegistry(this.registryFile);
+        if (registry === null)
+            return [];
+        const result = [];
+        for (const kind of Object.keys(registry).sort()) {
+            const section = registry[kind];
+            for (const name of Object.keys(section).sort()) {
+                const entry = section[name];
+                if (!isPlainObject(entry))
+                    continue;
+                const raw = entry;
+                const tiers = {};
+                if (isPlainObject(raw.ro))
+                    tiers.ro = { ...(probeOf(raw.ro) !== undefined ? { probe: probeOf(raw.ro) } : {}) };
+                if (isPlainObject(raw.rw))
+                    tiers.rw = { ...(probeOf(raw.rw) !== undefined ? { probe: probeOf(raw.rw) } : {}) };
+                result.push({ kind, name, envelope: buildEnvelope([raw]), tiers });
+            }
+        }
+        return result;
+    }
+    async loadTier(kind, name, tier) {
+        const registry = await loadRegistry(this.registryFile);
+        if (registry === null) {
+            throw new SourceUnavailableError(`ops-access: registry file not found: ${this.registryFile}`);
+        }
+        const entry = registry[kind]?.[name];
+        if (!isPlainObject(entry))
+            return null;
+        const raw = entry[tier];
+        if (!isPlainObject(raw))
+            return null;
+        const fields = { ...raw };
+        const probe = probeOf(raw);
+        delete fields.probe;
+        return { fields, envelope: buildEnvelope([entry]), ...(probe !== undefined ? { probe } : {}) };
+    }
+    async putTier(kind, name, tier, fields, envelope, probe) {
+        // Read → merge → write back. A missing file starts from an empty
+        // registry; an unparseable file throws (we will not overwrite a file we
+        // cannot read).
+        let registry = {};
+        const loaded = await loadRegistry(this.registryFile);
+        if (loaded !== null)
+            registry = loaded;
+        if (!registry[kind])
+            registry[kind] = {};
+        if (!isPlainObject(registry[kind][name]))
+            registry[kind][name] = {};
+        const entry = registry[kind][name];
+        const tierData = { ...fields };
+        if (probe !== undefined)
+            tierData.probe = probe;
+        entry[tier] = tierData;
+        applyEnvelopePatch(entry, envelope);
+        await saveRegistry(this.registryFile, registry);
+    }
+    async deleteTier(kind, name, tier) {
+        const registry = await loadRegistry(this.registryFile);
+        if (registry === null)
+            return 'missing';
+        const section = registry[kind];
+        if (!section || !(name in section))
+            return 'missing';
+        const entry = section[name];
+        if (!isPlainObject(entry))
+            return 'missing';
+        delete entry[tier];
+        // If neither tier remains, drop the whole entry and empty sections.
+        const remaining = ['ro', 'rw'].filter((t) => entry[t] !== undefined);
+        if (remaining.length > 0) {
+            await saveRegistry(this.registryFile, registry);
+            return 'tier';
+        }
+        delete section[name];
+        if (Object.keys(section).length === 0)
+            delete registry[kind];
+        await saveRegistry(this.registryFile, registry);
+        return 'entry';
+    }
+}

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

@@ -55,9 +55,12 @@ export interface Config {
      * 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.
+     * Unset + env ACCESS_HUB_URL present → 'hub' (upgrade-proof seam: the
+     * materialized preset file is rewritten on every suite upgrade, so the
+     * durable switch lives in the process environment, e.g. the systemd unit).
      */
     source?: 'yaml' | 'hub';
-    /** Hub base URL (source: 'hub'), e.g. http://127.0.0.1:3090. */
+    /** Hub base URL (source: 'hub'), e.g. http://127.0.0.1:3090. Falls back to env ACCESS_HUB_URL. */
     hubUrl?: string;
     /** Hub read token (source: 'hub'); falls back to env ACCESS_HUB_READ_TOKEN. Never logged. */
     hubToken?: string;

package/lib/index.js

@@ -57,8 +57,10 @@ export const inject = ['tools'];
 export const Config = z.object({
     registryFile: z.string().default('~/.dsh-ops/access.yaml'),
     credentialsDir: z.string().default('~/.dsh-ops/credentials'),
-    source: z.union(['yaml', 'hub']).default('yaml'),
-    hubUrl: z.string().default(''),
+    // No defaults here: an absent key must STAY absent so apply() can tell
+    // "unset" apart from an explicit value (the ACCESS_HUB_URL env seam).
+    source: z.union(['yaml', 'hub']),
+    hubUrl: z.string(),
     hubToken: z.string().default(''),
     hubAdminToken: z.string().default(''),
     materializeTtlMinutes: z.number().default(15),
@@ -381,7 +383,11 @@ export function apply(ctx, config) {
     // default and behaves byte-for-byte as before; hub fetches entries from a
     // remote ops-access-hub on every call and materializes file-field content
     // to managed local files under credentialsDir.
-    const source = config.source ?? 'yaml';
+    // Env seam (ACCESS_HUB_URL): setting it flips an unconfigured deployment to
+    // hub mode. The ops preset file is re-materialized on every suite upgrade,
+    // so config written into it is silently dropped — the process env (systemd
+    // unit) is the only upgrade-proof seam.
+    const source = config.source ?? (process.env.ACCESS_HUB_URL ? 'hub' : 'yaml');
     // In hub mode every local credential file — materialized reads AND staged
     // writes — lives under hubCacheDir as a TTL-bound cache. credentialsDir
     // stays yaml-mode territory: the sweeper must never touch files the yaml
@@ -389,9 +395,9 @@ export function apply(ctx, config) {
     const contentDir = source === 'hub' ? expandHome(config.hubCacheDir ?? '~/.dsh-ops/hub-cache') : credentialsDir;
     let backend;
     if (source === 'hub') {
-        const hubUrl = (config.hubUrl ?? '').replace(/\/+$/, '');
+        const hubUrl = (config.hubUrl || process.env.ACCESS_HUB_URL || '').replace(/\/+$/, '');
         if (hubUrl === '') {
-            throw new Error('ops-access: source "hub" requires hubUrl (e.g. http://127.0.0.1:3090)');
+            throw new Error('ops-access: source "hub" requires hubUrl (e.g. http://127.0.0.1:3090) or env ACCESS_HUB_URL');
         }
         backend = new HubBackend({
             baseUrl: hubUrl,

package/package.json

@@ -1,15 +1,12 @@
 {
   "name": "@elinpf/dsh-ops-access",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Ops access capability seam — owns the YAML credential registry and exposes ctx.opsAccess (resolve/list/register) to provider plugins.",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types.js",
-    "lib/mention.js",
+    "lib/**/*.js",
     "lib/**/*.d.ts",
     "cordis.patch.yml"
   ],