@elinpf/dsh-ops-access 0.1.6 → 0.2.0

package/lib/index.js

@@ -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
@@ -40,35 +45,25 @@ import { readFile, writeFile, mkdir, rm, rmdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import os from 'node:os';
 import z from '@deepseek-ai/schemastery';
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { z as zod } from 'zod';
 import { createUserMessage, freezeMessage } from '@deepseek-ai/dsh-llm';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { formatAccessMention, parseAccessReferenceText } from './mention.js';
+import { YamlBackend, buildEnvelope, isPlainObject } from './backend.js';
+import { HubBackend, sweepMaterialized } from './hub-backend.js';
 // ── Plugin identity ───────────────────────────────────────────────────────────
 export const name = 'ops-access';
 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(''),
+    hubToken: z.string().default(''),
+    hubAdminToken: z.string().default(''),
+    materializeTtlMinutes: z.number().default(15),
+    hubCacheDir: z.string().default('~/.dsh-ops/hub-cache'),
 });
-/** Read a persisted probe result off a raw tier object (durable boundary — sanitize). */
-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;
-}
 // ── Provider registration helper ─────────────────────────────────────────────
 /**
  * Register a provider into the seam from a provider plugin's `apply()`. The
@@ -104,66 +99,23 @@ export function expandHome(p) {
         return home + p.slice(1);
     return p;
 }
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-/**
- * 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;
-}
 /**
  * Validate one tier sub-object against the provider schema and build the
  * profile. `raw` carries only the provider fields; the envelope
  * (description/environment) lives on the parent entry and is passed separately.
+ * `source` is the backend's label phrase (e.g. `registry file <path>` /
+ * `access hub at <url>`), interpolated as `in ${source}` in error messages.
  */
-function buildProfile(provider, kind, profileName, tier, raw, file, parentEntry) {
+function buildProfile(provider, kind, profileName, tier, raw, source, parentEntry) {
     if (!isPlainObject(raw)) {
-        throw new Error(`ops-access: entry ${kind}.${profileName} in registry file ${file} must be a mapping`);
+        throw new Error(`ops-access: entry ${kind}.${profileName} in ${source} must be a mapping`);
     }
     const result = provider.schema.safeParse(raw);
     if (!result.success) {
         const issues = result.error.issues
             .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
             .join('; ');
-        throw new Error(`ops-access: invalid entry ${kind}.${profileName} in registry file ${file}: ${issues}`);
+        throw new Error(`ops-access: invalid entry ${kind}.${profileName} in ${source}: ${issues}`);
     }
     const fields = provider.process
         ? provider.process(result.data, profileName)
@@ -178,13 +130,56 @@ function buildProfile(provider, kind, profileName, tier, raw, file, parentEntry)
         profile.environment = env.environment;
     return profile;
 }
-/** 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;
+/**
+ * The final step of building a profile: expand the provider's declared
+ * reference fields through the SAME backend and tier, then run the
+ * provider's post-merge validation. Referenced fields are merged UNDER the
+ * referring entry's (the referring entry wins conflicts — e.g. a per-host
+ * user override of a shared credential's default user). One level only: a
+ * referenced entry's own reference fields are not expanded. The broker is
+ * NOT consulted for the reference — it is an implementation detail of the
+ * referring resolve, which was already gated.
+ *
+ * References load through the backend (`loadTier`), so in hub mode the
+ * referenced credential's file-field content is fetched and materialized by
+ * the same machinery as a direct resolve — `materialize` propagates the
+ * caller's intent (resolve issues credentials → write the files; canResolve/
+ * list are metadata reads → paths only, nothing touches disk). Shared by
+ * resolve, canResolve, and list so all three see the same resolved shape.
+ */
+async function finalizeProfile(backend, providers, provider, profile, opts) {
+    if (provider.references) {
+        const merged = {};
+        let any = false;
+        for (const [field, refKind] of Object.entries(provider.references)) {
+            const refName = profile.fields[field];
+            if (refName === undefined)
+                continue;
+            if (typeof refName !== 'string' || refName.length === 0) {
+                throw new Error(`ops-access: entry ${profile.kind}.${profile.name} ${profile.tier} field "${field}" must be a non-empty string naming a ${refKind} profile`);
+            }
+            const refProvider = providers.get(refKind);
+            if (!refProvider) {
+                throw new Error(`ops-access: entry ${profile.kind}.${profile.name} references ${refKind}/${refName}, but no provider is registered for kind "${refKind}"`);
+            }
+            const loaded = await backend.loadTier(refKind, refName, profile.tier, { materialize: opts.materialize });
+            if (loaded === null) {
+                const entries = await backend.listEntries().catch(() => []);
+                const available = entries.filter((e) => e.kind === refKind).map((e) => e.name).sort();
+                throw new Error(`ops-access: entry ${profile.kind}.${profile.name} references ${refKind}/${refName}, which has no ${profile.tier} tier in ${backend.label} (available: ${available.join(', ') || '(none)'})`);
+            }
+            const refProfile = buildProfile(refProvider, refKind, refName, profile.tier, loaded.fields, backend.label, loaded.envelope);
+            Object.assign(merged, refProfile.fields);
+            any = true;
+        }
+        if (any)
+            profile.fields = { ...merged, ...profile.fields };
+    }
+    const problem = provider.validateResolved?.(profile.fields);
+    if (problem) {
+        throw new Error(`ops-access: invalid entry ${profile.kind}.${profile.name} in ${backend.label}: ${problem}`);
     }
-    await writeFile(file, stringifyYaml(doc), 'utf8');
+    return profile;
 }
 /** Read the full HTTP request body as a string. */
 function readRequestBody(req) {
@@ -201,21 +196,6 @@ function sendJsonError(res, status, err) {
     res.writeHead(status, { 'content-type': 'application/json' });
     res.end(JSON.stringify({ ok: false, error: String(err?.message ?? err) }));
 }
-/** Build an EntryEnvelope from raw entry data, taking each envelope field from the first source that has it. */
-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;
-}
 /** Split "kind/name" on the FIRST slash — profile names may contain '@' etc. */
 function parseProfile(raw) {
     if (typeof raw !== 'string')
@@ -225,6 +205,17 @@ function parseProfile(raw) {
         return undefined;
     return { kind: raw.slice(0, slash), profileName: raw.slice(slash + 1) };
 }
+/**
+ * Tolerate a redundant kind prefix on a profile name: the mention/recall
+ * syntax writes profiles as `kind/name` and agents routinely pass that whole
+ * token as the bare name (2026-09-10: ssh/ssh/b200-02 failed three times
+ * across the ssh tool and request_access). Registered names can never
+ * contain '/', so stripping `${kind}/` is unambiguous and idempotent.
+ */
+function stripKindPrefix(kind, profileName) {
+    const prefix = kind + '/';
+    return profileName.startsWith(prefix) ? profileName.slice(prefix.length) : profileName;
+}
 /**
  * Write credential CONTENT to managed files under
  * `<credentialsDir>/<kind>/<name>/<tier>/<field>` and record the resulting
@@ -341,7 +332,7 @@ async function rollbackContentFiles(credentialsDir, kind, profileName, tier, wri
  * the session holds no grant. listAll (not list) so rw-only entries render
  * too — they exist in the registry, the agent just cannot read them yet.
  */
-async function renderAccessReferences(handle, references) {
+async function renderAccessReferences(handle, providers, references) {
     // A listAll failure (unreadable/corrupt registry file) degrades the mention
     // render to name-only lines — the registry being temporarily unreadable must
     // not break prompt assembly for the whole turn.
@@ -366,6 +357,19 @@ async function renderAccessReferences(handle, references) {
             : '';
         lines.push(`- ${key}${label}${env}${desc}${tierNote}`);
     }
+    // Kind-level credential boundaries, once per referenced kind: the agent
+    // should learn "view does not cover nodes" from this line, not from a
+    // Forbidden it will misread as a cluster problem (and re-hit after every
+    // compaction).
+    const limitsSeen = new Set();
+    for (const ref of references) {
+        if (limitsSeen.has(ref.kind))
+            continue;
+        limitsSeen.add(ref.kind);
+        const limits = providers.get(ref.kind)?.knownLimits;
+        if (limits)
+            lines.push(`- [${ref.kind} ro-tier limits] ${limits}`);
+    }
     return `<referenced-access>\nThe user explicitly referenced these access profiles (use them with the matching tools):\n${lines.join('\n')}\n</referenced-access>`;
 }
 // ── Plugin apply ─────────────────────────────────────────────────────────────
@@ -373,6 +377,50 @@ export function apply(ctx, config) {
     const registryFile = expandHome(config.registryFile);
     const credentialsDir = expandHome(config.credentialsDir);
     const providers = new Map();
+    // Credential source backend (see backend.ts / hub-backend.ts): yaml is the
+    // 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';
+    // 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
+    // registry still references (the documented fallback).
+    const contentDir = source === 'hub' ? expandHome(config.hubCacheDir ?? '~/.dsh-ops/hub-cache') : credentialsDir;
+    let backend;
+    if (source === 'hub') {
+        const hubUrl = (config.hubUrl ?? '').replace(/\/+$/, '');
+        if (hubUrl === '') {
+            throw new Error('ops-access: source "hub" requires hubUrl (e.g. http://127.0.0.1:3090)');
+        }
+        backend = new HubBackend({
+            baseUrl: hubUrl,
+            readToken: config.hubToken || process.env.ACCESS_HUB_READ_TOKEN || '',
+            adminToken: config.hubAdminToken || process.env.ACCESS_HUB_ADMIN_TOKEN || '',
+            cacheDir: contentDir,
+            getProvider: (kind) => providers.get(kind),
+        });
+        // Hub mode: local credential files are a TTL-bound cache of hub content,
+        // never permanent copies. Startup sweeps EVERYTHING in the cache dir (the
+        // grant ledger is in-memory and cleared by this very restart — cached rw
+        // material must not outlive it); the interval sweep then expires files
+        // past the TTL. Both tiers: ro cache expiry is equally transparent
+        // (resolve re-fetches and re-materializes on demand). apply is sync — the
+        // boot sweep runs detached; a resolve re-materializes anything it needs
+        // anyway, so a slow boot sweep can only leave a stale file for seconds.
+        const ttlMs = (config.materializeTtlMinutes ?? 15) * 60_000;
+        void sweepMaterialized(contentDir, 0).catch(() => { });
+        ctx.effect(() => {
+            const timer = setInterval(() => {
+                void sweepMaterialized(contentDir, ttlMs).catch(() => { });
+            }, Math.min(ttlMs, 60_000));
+            timer.unref?.();
+            return () => clearInterval(timer);
+        });
+    }
+    else {
+        backend = new YamlBackend(registryFile);
+    }
     // At most one broker is active; a later registration replaces an earlier one.
     // The replaced broker's disposer is folded into the replacement's, so each
     // registration's effect cleanup runs exactly once even under replacement or
@@ -409,36 +457,34 @@ export function apply(ctx, config) {
             return dispose;
         },
         async canResolve(kind, profileName, tier) {
+            profileName = stripKindPrefix(kind, profileName);
             const provider = providers.get(kind);
             if (!provider)
                 return { ok: false };
-            // Load + locate the entry in its own try/catch: a missing or unparseable
-            // file is a structural "not resolvable" with no validation reason — the
-            // admin does not need a zod message to fix a file that isn't there.
-            let raw;
-            let parentEntry;
+            // Load + locate the entry in its own try/catch: a missing source or
+            // entry is a structural "not resolvable" with no validation reason —
+            // the admin does not need a zod message to fix an entry that isn't
+            // there. materialize: false — a precheck must not write secret files
+            // (hub mode), e.g. the gate's pre-approval check on the rw tier.
+            let loaded;
             try {
-                const registry = await loadRegistry(registryFile);
-                if (registry === null)
-                    return { ok: false };
-                const entry = registry[kind]?.[profileName];
-                if (!isPlainObject(entry))
-                    return { ok: false };
-                parentEntry = entry;
-                raw = parentEntry[tier];
+                loaded = await backend.loadTier(kind, profileName, tier, { materialize: false });
             }
             catch {
                 return { ok: false };
             }
-            if (!isPlainObject(raw))
+            if (loaded === null)
                 return { ok: false };
             // Run the same buildProfile validation resolve would run — a precheck
             // shallower than the real issuance approves grants that cannot be
             // fulfilled. The profile itself is discarded: existence, not fields.
-            // A validation failure surfaces the reason (zod issue paths + messages,
-            // never raw field values) so the admin UI can show it.
+            // Reference expansion runs too (finalizeProfile): a dangling credential
+            // reference is exactly the kind of undeliverable resolve this precheck
+            // exists to catch. A validation failure surfaces the reason (zod issue
+            // paths + messages, never raw field values) so the admin UI can show it.
             try {
-                buildProfile(provider, kind, profileName, tier, raw, registryFile, parentEntry);
+                const profile = buildProfile(provider, kind, profileName, tier, loaded.fields, backend.label, loaded.envelope);
+                await finalizeProfile(backend, providers, provider, profile, { materialize: false });
                 return { ok: true };
             }
             catch (err) {
@@ -446,6 +492,7 @@ export function apply(ctx, config) {
             }
         },
         async resolve(kind, profileName, agent) {
+            profileName = stripKindPrefix(kind, profileName);
             const provider = providers.get(kind);
             if (!provider) {
                 const registered = [...providers.keys()].sort();
@@ -464,52 +511,53 @@ export function apply(ctx, config) {
                 if (decision === 'rw')
                     tier = 'rw';
             }
-            const registry = await loadRegistry(registryFile);
-            if (registry === null) {
-                throw new Error(`ops-access: registry file not found: ${registryFile}`);
-            }
-            const section = registry[kind];
-            const entry = section?.[profileName];
-            if (!isPlainObject(entry)) {
-                const available = Object.keys(section ?? {}).sort();
-                const hint = tier === 'rw' ? ' — a grant was approved but no rw credential is registered; ask the operator to add it via the admin UI' : '';
-                throw new Error(`ops-access: no profile "${profileName}" for kind "${kind}" in registry file ${registryFile} (available: ${available.join(', ') || '(none)'})${hint}`);
-            }
-            const tierData = entry[tier];
-            if (!isPlainObject(tierData)) {
+            // A missing SOURCE (yaml: no registry file) throws from the backend
+            // verbatim (SourceUnavailableError); an unreadable source propagates
+            // its read/parse error the same way.
+            const loaded = await backend.loadTier(kind, profileName, tier);
+            if (loaded === null) {
+                // Distinguish "no such entry" from "entry without this tier" via the
+                // fields-free listing — the hints below guide the agent's next move.
+                const entries = await backend.listEntries().catch(() => []);
+                const inKind = entries.filter((e) => e.kind === kind);
+                const entry = inKind.find((e) => e.name === profileName);
+                if (!entry) {
+                    const available = inKind.map((e) => e.name).sort();
+                    const hint = tier === 'rw' ? ' — a grant was approved but no rw credential is registered; ask the operator to add it via the admin UI' : '';
+                    throw new Error(`ops-access: no profile "${profileName}" for kind "${kind}" in ${backend.label} (available: ${available.join(', ') || '(none)'})${hint}`);
+                }
                 // On the rw tier the grant was already approved — say so, so the agent
                 // reports "no rw credential registered" to the operator instead of
                 // re-requesting a grant that can never be fulfilled. On the ro tier
                 // with rw present, point at the self-service derivation path.
                 const hint = tier === 'rw'
                     ? ' — a grant was approved but no rw credential is registered; ask the operator to add it via the admin UI'
-                    : isPlainObject(entry.rw)
+                    : entry.tiers.rw !== undefined
                         ? ' — the rw tier is registered; derive a read-only credential from it (list_access help: true has the recipe) and register it via the register_access tool'
                         : '';
-                throw new Error(`ops-access: no ${tier} tier for profile "${profileName}" (kind "${kind}") in registry file ${registryFile}${hint}`);
+                throw new Error(`ops-access: no ${tier} tier for profile "${profileName}" (kind "${kind}") in ${backend.label}${hint}`);
             }
-            return buildProfile(provider, kind, profileName, tier, tierData, registryFile, entry);
+            const profile = buildProfile(provider, kind, profileName, tier, loaded.fields, backend.label, loaded.envelope);
+            return finalizeProfile(backend, providers, provider, profile, { materialize: true });
         },
         async list() {
-            const registry = await loadRegistry(registryFile);
-            if (registry === null)
-                return [];
+            // A missing source lists empty; an unreadable/corrupt source throws
+            // (same discipline as the pre-backend list).
+            const entries = await backend.listEntries();
             const profiles = [];
-            for (const [kind, section] of Object.entries(registry)) {
-                // Sections whose kind has no registered provider are skipped —
-                // an unrecognized kind must not fail the whole listing.
-                const provider = providers.get(kind);
-                if (!provider)
+            for (const entry of entries) {
+                // Kinds without a registered provider are skipped — an unrecognized
+                // kind must not fail the whole listing. list() surfaces the
+                // agent-readable ro tier only. materialize: false — listing is not
+                // issuance; file fields carry their would-be managed path.
+                const provider = providers.get(entry.kind);
+                if (!provider || entry.tiers.ro === undefined)
                     continue;
-                for (const [profileName, entry] of Object.entries(section)) {
-                    // list() surfaces the agent-readable ro tier only.
-                    if (!isPlainObject(entry))
-                        continue;
-                    const roData = entry.ro;
-                    if (!isPlainObject(roData))
-                        continue;
-                    profiles.push(buildProfile(provider, kind, profileName, 'ro', roData, registryFile, entry));
-                }
+                const loaded = await backend.loadTier(entry.kind, entry.name, 'ro', { materialize: false }).catch(() => null);
+                if (loaded === null)
+                    continue;
+                const profile = buildProfile(provider, entry.kind, entry.name, 'ro', loaded.fields, backend.label, loaded.envelope);
+                profiles.push(await finalizeProfile(backend, providers, provider, profile, { materialize: false }));
             }
             return profiles;
         },
@@ -517,23 +565,14 @@ export function apply(ctx, config) {
             const lines = [
                 'Ops access registry — how to manage credentials',
                 '',
-                `File: ${registryFile}`,
-                'Re-read, re-parsed, and re-validated on EVERY call — edit it with the fs tools and the change takes effect immediately, no restart.',
-                '',
-                'Format:',
-                '  version: 1',
-                '  <kind>:',
-                '    <profile-id>:                            # stable id: letters/digits plus . _ - @; used in paths, mentions, grants',
-                '      name: display label, freely editable   # optional, UI-facing only',
-                '      description: what this profile is for   # optional, shown by list_access',
-                '      environment: prod | staging | ...        # optional; the future audit gate reads this',
-                '      ro:                                      # ro tier fields (agent-readable default)',
-                '        <kind-specific fields, see below>',
-                '      rw:                                      # rw tier fields (grant-gated)',
-                '        probe: {...}                            # auto-managed capability check (ticket 10): status/detail/probedAt, written at save time — do not edit',
-                '',
-                'Registered kinds and their entry fields:',
             ];
+            if (source === 'hub') {
+                lines.push(`Source: ${backend.label}`, 'Entries are fetched from the hub on EVERY call — edits in the hub UI take effect immediately, no restart.', `File-field contents live in the hub; at resolve time they are materialized to cache files under ${contentDir} (0600, TTL-bound — swept on expiry and at startup, re-materialized on demand) and profiles carry those paths — secret material never enters logs or model context.`);
+            }
+            else {
+                lines.push(`File: ${registryFile}`, 'Re-read, re-parsed, and re-validated on EVERY call — edit it with the fs tools and the change takes effect immediately, no restart.', '', 'Format:', '  version: 1', '  <kind>:', '    <profile-id>:                            # stable id: letters/digits plus . _ - @; used in paths, mentions, grants', '      name: display label, freely editable   # optional, UI-facing only', '      description: what this profile is for   # optional, shown by list_access', '      environment: prod | staging | ...        # optional; the future audit gate reads this', '      ro:                                      # ro tier fields (agent-readable default)', '        <kind-specific fields, see below>', '      rw:                                      # rw tier fields (grant-gated)', '        probe: {...}                            # auto-managed capability check (ticket 10): status/detail/probedAt, written at save time — do not edit');
+            }
+            lines.push('', 'Registered kinds and their entry fields:');
             const kinds = [...providers.values()].sort((a, b) => a.kind.localeCompare(b.kind));
             if (kinds.length === 0) {
                 lines.push('- (none registered)');
@@ -542,9 +581,11 @@ export function apply(ctx, config) {
                 lines.push(`- ${p.kind}: ${p.fieldsDoc ?? '(no field docs provided by this provider)'}`);
                 if (p.derivationDoc)
                     lines.push(`  derive ro: ${p.derivationDoc}`);
+                if (p.knownLimits)
+                    lines.push(`  ro-tier limits: ${p.knownLimits}`);
             }
             lines.push('');
-            lines.push('Agents register ro tiers with the register_access tool — rw tiers stay human-managed via the admin UI.');
+            lines.push('Agents register ro tiers with the register_access tool; rw tiers are human-approved — the tool can submit an rw registration REQUEST (tier: "rw") which takes effect only after an operator approves it in the admin UI (hub mode).');
             lines.push('Registering: pass the full file CONTENT for file fields, or a single-line path to an existing readable file (read server-side, content never passes through the model). Multi-line pastes are always treated as content.');
             lines.push('In the REGISTRY itself, file fields carry the managed file paths — secrets never go inline, so logs and model context never contain secret material.');
             return lines.join('\n');
@@ -559,121 +600,62 @@ export function apply(ctx, config) {
             // The tier sub-object carries only provider fields; the envelope
             // (name/description/environment) lives on the parent entry.
             const tierData = { ...fields };
-            // Read → merge → validate → 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(registryFile);
-            if (loaded !== null)
-                registry = loaded;
-            if (!registry[kind])
-                registry[kind] = {};
-            if (!isPlainObject(registry[kind][profileName]))
-                registry[kind][profileName] = {};
-            const entry = registry[kind][profileName];
-            entry[tier] = tierData;
-            // Envelope discipline: omitted = preserve, empty string = delete, else set.
-            // The admin UI always sends all three so the operator can clear them.
-            if (envelope?.name !== undefined) {
-                if (envelope.name === '')
-                    delete entry.name;
-                else
-                    entry.name = envelope.name;
-            }
-            if (envelope?.description !== undefined) {
-                if (envelope.description === '')
-                    delete entry.description;
-                else
-                    entry.description = envelope.description;
-            }
-            if (envelope?.environment !== undefined) {
-                if (envelope.environment === '')
-                    delete entry.environment;
-                else
-                    entry.environment = envelope.environment;
-            }
             // Validate via buildProfile BEFORE writing — a schema failure must not
-            // touch the file. buildProfile throws with zod issue paths + messages,
-            // never raw field values. (The in-memory merged entry is what we
-            // validate, matching the spec's read→merge→validate→write sequence.)
-            const writtenProfile = buildProfile(provider, kind, profileName, tier, tierData, registryFile, entry);
+            // touch the source. buildProfile throws with zod issue paths + messages,
+            // never raw field values.
+            const writtenProfile = buildProfile(provider, kind, profileName, tier, tierData, backend.label);
             // Capability probe (ticket 10): verify claims against reality at save
             // time — the credential files are already on disk (the caller writes
             // them first). A probe failure degrades to 'unverifiable', never a
             // write rejection.
+            let probe;
             if (provider.probe) {
                 const probed = await provider.probe(writtenProfile.fields, tier)
                     .catch((err) => ({
                     status: 'unverifiable',
                     detail: err instanceof Error ? err.message.split('\n')[0] : String(err),
                 }));
-                tierData.probe = { ...probed, probedAt: new Date().toISOString() };
+                probe = { ...probed, probedAt: new Date().toISOString() };
             }
-            await saveRegistry(registryFile, registry);
+            // The backend applies the envelope patch discipline (undefined =
+            // preserve, empty string = delete) and persists the tier.
+            await backend.putTier(kind, profileName, tier, tierData, envelope, probe);
         },
         async deleteEntry(kind, profileName, tier) {
-            const registry = await loadRegistry(registryFile);
-            if (registry === null)
-                return false;
-            const section = registry[kind];
-            if (!section || !(profileName in section))
+            const outcome = await backend.deleteTier(kind, profileName, tier);
+            if (outcome === 'missing')
                 return false;
-            const entry = section[profileName];
-            if (!isPlainObject(entry))
-                return false;
-            // Remove the tier sub-object and its managed credential files.
-            delete entry[tier];
+            // Remove the tier's managed credential files; when the whole entry
+            // went, remove its credential directory too. (contentDir: the hub cache
+            // in hub mode, the yaml-mode managed dir otherwise.)
             const provider = providers.get(kind);
             if (provider?.fileFields && provider.fileFields.length > 0) {
-                await rm(credentialsDir + '/' + kind + '/' + profileName + '/' + tier, { recursive: true, force: true });
-            }
-            // If neither tier remains, remove the whole entry, its credential
-            // directory, and drop empty sections.
-            const remaining = ['ro', 'rw'].filter((t) => entry[t] !== undefined);
-            if (remaining.length === 0) {
-                delete section[profileName];
-                if (Object.keys(section).length === 0)
-                    delete registry[kind];
-                if (provider?.fileFields && provider.fileFields.length > 0) {
-                    await rm(credentialsDir + '/' + kind + '/' + profileName, { recursive: true, force: true });
+                await rm(contentDir + '/' + kind + '/' + profileName + '/' + tier, { recursive: true, force: true });
+                if (outcome === 'entry') {
+                    await rm(contentDir + '/' + kind + '/' + profileName, { recursive: true, force: true });
                 }
             }
-            await saveRegistry(registryFile, registry);
             return true;
         },
         async listAll() {
-            // Load the single registry for enumeration. A parse error degrades to
-            // an empty list — canResolve reports the failure per tier.
-            let registry = {};
+            // A source failure degrades to an empty list — canResolve reports the
+            // failure per tier.
+            let entries = [];
             try {
-                const r = await loadRegistry(registryFile);
-                if (r)
-                    registry = r;
+                entries = await backend.listEntries();
             }
             catch { /* canResolve reports the failure */ }
             const result = [];
-            for (const kind of Object.keys(registry).sort()) {
-                if (!providers.has(kind))
+            for (const entry of entries) {
+                if (!providers.has(entry.kind))
                     continue;
-                const section = registry[kind];
-                if (!section)
-                    continue;
-                for (const name of Object.keys(section).sort()) {
-                    const entry = section[name];
-                    if (!isPlainObject(entry))
-                        continue;
-                    const envelope = buildEnvelope([entry]);
-                    const roStatus = await handle.canResolve(kind, name, 'ro');
-                    const rwStatus = await handle.canResolve(kind, name, 'rw');
-                    const rawEntry = entry;
-                    const roProbe = probeOf(rawEntry.ro);
-                    if (roProbe !== undefined)
-                        roStatus.probe = roProbe;
-                    const rwProbe = probeOf(rawEntry.rw);
-                    if (rwProbe !== undefined)
-                        rwStatus.probe = rwProbe;
-                    result.push({ kind, name, envelope, tiers: { ro: roStatus, rw: rwStatus } });
-                }
+                const roStatus = await handle.canResolve(entry.kind, entry.name, 'ro');
+                const rwStatus = await handle.canResolve(entry.kind, entry.name, 'rw');
+                if (entry.tiers.ro?.probe !== undefined)
+                    roStatus.probe = entry.tiers.ro.probe;
+                if (entry.tiers.rw?.probe !== undefined)
+                    rwStatus.probe = entry.tiers.rw.probe;
+                result.push({ kind: entry.kind, name: entry.name, envelope: entry.envelope, tiers: { ro: roStatus, rw: rwStatus } });
             }
             return result;
         },
@@ -691,32 +673,24 @@ export function apply(ctx, config) {
             const provider = providers.get(kind);
             if (!provider)
                 return null;
-            let registry;
+            let loaded;
             try {
-                registry = await loadRegistry(registryFile);
+                loaded = await backend.loadTier(kind, profileName, tier, { materialize: false });
             }
             catch {
-                // Registry file unreadable/corrupt → the entry is unknowable; getEntry
+                // Source unreadable/corrupt → the entry is unknowable; getEntry
                 // reports null (not found) rather than failing the caller's whole flow.
                 return null;
             }
-            if (registry === null)
-                return null;
-            const entry = registry[kind]?.[profileName];
-            if (!isPlainObject(entry))
+            if (loaded === null)
                 return null;
-            const parent = entry;
-            const raw = parent[tier];
-            if (!isPlainObject(raw))
-                return null;
-            // Return the tier's NON-file fields plus the parent's envelope. File
+            // Return the tier's NON-file fields plus the entry's envelope. File
             // fields (credential content) are write-only after save: content is
             // never read back — not even the managed path — only the set status
             // rides along so the UI can render "已保存，粘贴新内容以覆盖". This
             // keeps stored credentials unreachable for anyone (or anything) that
             // can merely reach the admin routes.
-            const { name: displayName, description, environment } = parent;
-            const fields = { ...raw };
+            const fields = { ...loaded.fields };
             const fileFields = {};
             for (const ff of provider.fileFields ?? []) {
                 const stored = fields[ff];
@@ -724,30 +698,35 @@ export function apply(ctx, config) {
                 delete fields[ff];
             }
             const result = { fields, fileFields };
-            if (typeof displayName === 'string')
-                result.displayName = displayName;
-            if (typeof description === 'string')
-                result.description = description;
-            if (typeof environment === 'string')
-                result.environment = environment;
+            if (loaded.envelope.name !== undefined)
+                result.displayName = loaded.envelope.name;
+            if (loaded.envelope.description !== undefined)
+                result.description = loaded.envelope.description;
+            if (loaded.envelope.environment !== undefined)
+                result.environment = loaded.envelope.environment;
             return result;
         },
     };
     ctx.provide('opsAccess', handle);
-    // ── register_access tool (agent-facing ro-tier writer) ────────────────────
+    // ── register_access tool (agent-facing ro writer / rw requester) ──────────
     // The agent's self-service registration path: it derives a read-only
     // credential from the rw one (per-kind recipe in the provider's
     // derivationDoc, surfaced by help()) and writes the ro tier here.
     // Deliberately ungated — the ro tier is the agent's default operating
-    // level and the operator can overwrite it from the admin UI at any time;
-    // the rw tier stays human-only (no tool writes it). Tool calls sit in the
-    // session event log, so every registration is reconstructable.
+    // level and the operator can overwrite it from the admin UI at any time.
+    // The rw tier stays approval-gated: tier:"rw" only QUEUES a registration
+    // request on the hub (validated like a real write); a human reviews the
+    // content in the admin UI and only an approval persists the tier.
+    // Tool calls sit in the session event log, so every registration and
+    // request is reconstructable.
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'register_access',
-        description: 'Register or overwrite the read-only (ro) credential tier of an access profile — typically a credential you derived from the rw tier (a read-only ServiceAccount token, a read-only cephx keyring, a dedicated SSH key). The rw tier is human-managed via the admin UI; this tool writes ro only. File fields (kubeconfig, conf, keyring, key) take the full file CONTENT, stored to a managed path automatically; a path to an existing readable file also works and is read server-side, so the content never needs to pass through this call. Other fields are inline values. Run list_access with help: true for per-kind field docs and derivation recipes.',
+        description: 'Register or overwrite the read-only (ro) credential tier of an access profile — typically a credential you derived from the rw tier (a read-only ServiceAccount token, a read-only cephx keyring, a dedicated SSH key). Pass tier: "rw" to instead SUBMIT an rw registration request for human approval (hub mode only) — it writes nothing until an operator approves it in the access admin UI. File fields (kubeconfig, conf, keyring, key) take the full file CONTENT, stored to a managed path automatically; a path to an existing readable file also works and is read server-side, so the content never needs to pass through this call. Other fields are inline values. Run list_access with help: true for per-kind field docs and derivation recipes.',
         parameters: {
             profile: { type: 'string', required: true, description: '"kind/id", e.g. "k8s/prod". The entry is created when it does not exist yet.' },
-            fields: { type: 'object', additionalProperties: true, required: true, description: 'The ro tier field values for this kind. File fields (kubeconfig, conf, keyring, key) take the full file CONTENT — or a single-line path to an existing readable file, which is read server-side. Multi-line pastes are always treated as content.' },
+            fields: { type: 'object', additionalProperties: true, required: true, description: 'The tier field values for this kind. File fields (kubeconfig, conf, keyring, key) take the full file CONTENT — or a single-line path to an existing readable file, which is read server-side. Multi-line pastes are always treated as content.' },
+            tier: { type: 'string', description: '"ro" (default) writes the read-only tier directly. "rw" does NOT write anything: in hub mode it submits a registration REQUEST that takes effect only after a human approves it in the access admin UI; in yaml mode it fails (rw stays human-managed).' },
+            reason: { type: 'string', description: 'For tier "rw": why this rw credential is needed — shown to the approving human.' },
             description: { type: 'string', description: 'Optional envelope description (empty string clears it).' },
             environment: { type: 'string', description: 'Optional envelope environment label (empty string clears it).' },
         },
@@ -776,7 +755,7 @@ export function apply(ctx, config) {
                 return { ok: false, message: `unknown kind "${kind}" (registered kinds: ${registered.join(', ') || '(none)'})` };
             }
             if (!isPlainObject(args.fields)) {
-                return { ok: false, message: 'fields must be an object of ro tier field values' };
+                return { ok: false, message: 'fields must be an object of tier field values' };
             }
             // File fields take CONTENT from the agent; everything else is inline.
             const entryFields = {};
@@ -794,7 +773,7 @@ export function apply(ctx, config) {
             if (typeof args.environment === 'string')
                 envelope.environment = args.environment;
             // Reject a bad id BEFORE any file IO, and roll back written files when
-            // writeEntry fails — a rejected registration must not leave orphan
+            // the write fails — a rejected registration must not leave orphan
             // credential files on disk.
             try {
                 assertValidProfileName(profileName);
@@ -802,10 +781,52 @@ export function apply(ctx, config) {
             catch (err) {
                 return { ok: false, message: String(err?.message ?? err) };
             }
+            // ── rw tier: approval-gated registration request (hub mode only) ──────
+            // Nothing is written to the credential store here. The fields are
+            // validated exactly as a real write would be (staging + provider
+            // content hooks + zod schema), then queued on the hub; a human reviews
+            // the actual content in the admin UI and only an approval writes the
+            // tier. Staging files are removed before returning either way.
+            if (args.tier === 'rw') {
+                if (!(backend instanceof HubBackend)) {
+                    return { ok: false, message: 'The rw tier is human-managed: ask the operator to register it in the admin UI (凭证管理 settings section). Agent-submitted rw registration requests require hub mode; this registry is local yaml.' };
+                }
+                const reason = typeof args.reason === 'string' ? args.reason : undefined;
+                let written = [];
+                try {
+                    if (Object.keys(contentFiles).length > 0) {
+                        written = await writeContentFiles(contentDir, kind, profileName, 'rw', descriptor.fileFields ?? [], contentFiles, entryFields, providers.get(kind));
+                    }
+                    const provider = providers.get(kind);
+                    buildProfile(provider, kind, profileName, 'rw', entryFields, backend.label);
+                    // The hub stores CONTENT; convert the staged paths back.
+                    const requestFields = { ...entryFields };
+                    for (const ff of descriptor.fileFields ?? []) {
+                        const p = requestFields[ff];
+                        if (typeof p === 'string' && p !== '')
+                            requestFields[ff] = await readFile(expandHome(p), 'utf8');
+                    }
+                    const id = await backend.submitRequest({
+                        kind,
+                        name: profileName,
+                        tier: 'rw',
+                        fields: requestFields,
+                        ...(Object.keys(envelope).length > 0 ? { envelope } : {}),
+                        ...(reason !== undefined ? { reason } : {}),
+                    });
+                    return { ok: true, message: `rw registration request for ${kind}/${profileName} submitted (id ${id}). It takes effect ONLY after a human approves it in the access admin UI (凭证管理 settings section) — tell the operator it is waiting. Do not retry; poll list_access to see when the rw tier appears.` };
+                }
+                catch (err) {
+                    return { ok: false, message: `registration request failed: ${String(err?.message ?? err)}` };
+                }
+                finally {
+                    await rollbackContentFiles(contentDir, kind, profileName, 'rw', written);
+                }
+            }
             let written = [];
             try {
                 if (Object.keys(contentFiles).length > 0) {
-                    written = await writeContentFiles(credentialsDir, kind, profileName, 'ro', descriptor.fileFields ?? [], contentFiles, entryFields, providers.get(kind));
+                    written = await writeContentFiles(contentDir, kind, profileName, 'ro', descriptor.fileFields ?? [], contentFiles, entryFields, providers.get(kind));
                 }
                 // writeEntry validates against the provider schema BEFORE touching
                 // the registry; its errors carry zod issue paths + messages, never
@@ -813,7 +834,7 @@ export function apply(ctx, config) {
                 await handle.writeEntry(kind, profileName, 'ro', entryFields, Object.keys(envelope).length > 0 ? envelope : undefined);
             }
             catch (err) {
-                await rollbackContentFiles(credentialsDir, kind, profileName, 'ro', written);
+                await rollbackContentFiles(contentDir, kind, profileName, 'ro', written);
                 return { ok: false, message: `registration failed: ${String(err?.message ?? err)}` };
             }
             return { ok: true, message: `Registered the ro tier of ${kind}/${profileName}. Verify it with a read command before relying on it.` };
@@ -932,21 +953,22 @@ export function apply(ctx, config) {
                         assertValidProfileName(name);
                         let writtenFiles = [];
                         if (isPlainObject(contentFiles)) {
-                            writtenFiles = await writeContentFiles(credentialsDir, kind, name, tier, provider?.fileFields ?? [], contentFiles, entryFields, provider);
+                            writtenFiles = await writeContentFiles(contentDir, kind, name, tier, provider?.fileFields ?? [], contentFiles, entryFields, provider);
                         }
                         // Write-only-after-save preserve: file fields never come back
                         // from the UI (getEntry withholds them), so an edit request
                         // cannot carry them. Carry over the stored path for any declared
                         // file field the request omits — otherwise the tier-replace
-                        // write would silently drop the credential.
+                        // write would silently drop the credential. Hub mode materializes
+                        // the carry-over (the hub backend's putTier re-uploads file
+                        // CONTENT read from the path, so the file must actually exist;
+                        // the cache dir is TTL-bound, so this leaves no permanent copy).
                         if (provider?.fileFields?.length) {
-                            const existing = await loadRegistry(registryFile);
-                            const existingEntry = existing?.[kind]?.[name];
-                            const existingTier = isPlainObject(existingEntry) ? existingEntry[tier] : undefined;
-                            if (isPlainObject(existingTier)) {
+                            const existing = await backend.loadTier(kind, name, tier, { materialize: source === 'hub' }).catch(() => null);
+                            if (existing !== null) {
                                 for (const ff of provider.fileFields) {
-                                    if (entryFields[ff] === undefined && typeof existingTier[ff] === 'string') {
-                                        entryFields[ff] = existingTier[ff];
+                                    if (entryFields[ff] === undefined && typeof existing.fields[ff] === 'string') {
+                                        entryFields[ff] = existing.fields[ff];
                                     }
                                 }
                             }
@@ -956,7 +978,7 @@ export function apply(ctx, config) {
                             await handle.writeEntry(kind, name, tier, entryFields, Object.keys(envelope).length > 0 ? envelope : undefined);
                         }
                         catch (err) {
-                            await rollbackContentFiles(credentialsDir, kind, name, tier, writtenFiles);
+                            await rollbackContentFiles(contentDir, kind, name, tier, writtenFiles);
                             throw err;
                         }
                         res.writeHead(200, { 'content-type': 'application/json' });
@@ -1004,6 +1026,87 @@ export function apply(ctx, config) {
                 }
             },
         }));
+        // ── Registration-request proxy routes (hub mode only) ──────────────────
+        // The approval UI for agent-submitted rw registration requests lives in
+        // the dsh settings section (ops-access-ui); these routes proxy the hub's
+        // /requests API so the browser never needs the hub's admin token. Yaml
+        // mode has no remote queue — the routes are simply not mounted there.
+        if (backend instanceof HubBackend) {
+            wctx.effect(() => wctx.webServer.register({
+                kind: 'exact',
+                path: '/ops-access/admin/requests',
+                handler: async (req, res) => {
+                    try {
+                        if (req.method !== 'GET') {
+                            sendJsonError(res, 405, new Error('method not allowed'));
+                            return;
+                        }
+                        const list = await backend.listRequests('pending');
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify(list));
+                    }
+                    catch (err) {
+                        sendJsonError(res, 500, err);
+                    }
+                },
+            }));
+            wctx.effect(() => wctx.webServer.register({
+                kind: 'exact',
+                path: '/ops-access/admin/requests/detail',
+                handler: async (req, res) => {
+                    try {
+                        if (req.method !== 'GET') {
+                            sendJsonError(res, 405, new Error('method not allowed'));
+                            return;
+                        }
+                        const id = new URL(req.url, 'http://localhost').searchParams.get('id');
+                        if (!id) {
+                            sendJsonError(res, 400, new Error('id query parameter is required'));
+                            return;
+                        }
+                        // Full field values cross here — pre-approval review is exactly
+                        // the moment a human must see the secret material being asked for.
+                        const request = await backend.getRequest(id);
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify(request));
+                    }
+                    catch (err) {
+                        sendJsonError(res, 500, err);
+                    }
+                },
+            }));
+            wctx.effect(() => wctx.webServer.register({
+                kind: 'exact',
+                path: '/ops-access/admin/requests/decide',
+                handler: async (req, res) => {
+                    try {
+                        if (req.method !== 'POST') {
+                            sendJsonError(res, 405, new Error('method not allowed'));
+                            return;
+                        }
+                        const body = await readRequestBody(req);
+                        let parsed;
+                        try {
+                            parsed = JSON.parse(body);
+                        }
+                        catch {
+                            sendJsonError(res, 400, new Error('request body must be valid JSON'));
+                            return;
+                        }
+                        if (typeof parsed.id !== 'string' || typeof parsed.approved !== 'boolean') {
+                            sendJsonError(res, 400, new Error('id (string) and approved (boolean) are required'));
+                            return;
+                        }
+                        const decided = await backend.decideRequest(parsed.id, parsed.approved);
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify(decided ? { ok: true } : { ok: false, error: 'request not found or already decided' }));
+                    }
+                    catch (err) {
+                        sendJsonError(res, 500, err);
+                    }
+                },
+            }));
+        }
     });
     ctx.on('agent/pre-step', async (payload, next) => {
         const decision = await next();
@@ -1033,7 +1136,7 @@ export function apply(ctx, config) {
             out.push(freezeMessage({ ...message, content }));
             out.push(createUserMessage({
                 source: { kind: 'plugin', plugin: name, form: 'recall' },
-                content: [{ type: 'text', text: await renderAccessReferences(handle, references) }],
+                content: [{ type: 'text', text: await renderAccessReferences(handle, providers, references) }],
             }));
         }
         return changed ? { kind: 'enter', messages: out } : decision;