@elinpf/dsh-ops-access 0.1.7 → 0.2.1

package/README.md

@@ -7,9 +7,11 @@ The ops access capability seam — owns the YAML credential registry (default `~
 - **Single registry file, zero cache**: every `resolve`/`list`/`writeEntry` re-reads, re-parses, and re-validates the YAML — edits take effect immediately, no restart.
 - **Tiered entries**: each profile carries an `ro` tier (agent-readable default) and an `rw` tier (served only through a registered broker grant).
 - **Provider seam**: one provider per credential kind (`k8s`/`ceph`/`ssh` packages) supplies only a zod schema plus field processing (`~` expansion, content validation, capability probe). Providers register via `registerAccessProvider(ctx, provider)` — never hand-write `ctx.inject` for sibling services, it deadlocks the loader.
-- **`register_access` tool**: the agent's self-service path for writing the ro tier (rw stays human-managed via the admin HTTP routes).
+- **Reference fields** (`references`): a provider may declare that a field names another KIND's entry (ssh's `cred` → `ssh-cred`), so many entries share one credential instead of each carrying a copy. At resolve time core merges the referenced entry's fields UNDER the referring entry's (same registry, same tier, one level only); the broker is consulted once, on the referring entry. `validateResolved` is the post-merge hook for requirements that only hold on the merged shape (ssh needs a login user from either side). A dangling reference fails the referring resolve AND its `canResolve` precheck.
+- **`register_access` tool**: the agent's self-service path for writing the ro tier; with `tier: "rw"` it instead **submits an rw registration request** (hub mode only, ADR-0008) — the request queues on the hub and is written only after an operator reviews the field contents and approves it in the admin settings section.
 - **Mention support**: `@[kind/name](dsh-access:<payload>)` mentions are parsed on `agent/pre-step` and rewritten to readable references with envelope context; `GET /ops-access/list` feeds the browser's `@` picker. The encoding lives in the `./mention` subpath.
 - **Admin routes**: `GET /ops-access/admin/list`, `GET /ops-access/admin/kinds`, `GET|POST|DELETE /ops-access/admin/entry` — envelope + validation status only, never field values.
+- **Pluggable credential source** (`source`): `yaml` (default) is the local registry file; `hub` fetches entries from a standalone [ops-access-hub](../../ops-access-hub/) service on every call. In hub mode, file-field content is materialized to a SEPARATE cache dir (`hubCacheDir`, default `~/.dsh-ops/hub-cache`) as a TTL-bound cache (`materializeTtlMinutes`, default 15) — never a permanent copy: startup sweeps the whole cache (the grant ledger dies with the process, so cached rw material must not outlive it), the interval sweep expires by age, and resolve re-materializes transparently on demand. The yaml-mode `credentialsDir` (the documented fallback) is never swept.
 
 ## Design notes
 
@@ -25,6 +27,12 @@ The ops access capability seam — owns the YAML credential registry (default `~
   name: '@elinpf/dsh-ops-access'
   registryFile: ~/.dsh-ops/access.yaml   # default
   credentialsDir: ~/.dsh-ops/credentials # default; managed credential content files (0600)
+  # source: hub                          # optional; default yaml
+  # hubUrl: http://127.0.0.1:3090        # hub source: hub base URL
+  # hubToken: ...                        # hub source: read token (or env ACCESS_HUB_READ_TOKEN)
+  # hubAdminToken: ...                   # hub source: write token (or env ACCESS_HUB_ADMIN_TOKEN)
+  # hubCacheDir: ~/.dsh-ops/hub-cache    # hub source: TTL materialization cache (never credentialsDir)
+  # materializeTtlMinutes: 15            # hub source: cache TTL; startup sweeps all
 ```
 
 ## Testing

package/README.zh.md

@@ -7,9 +7,11 @@
 - **单注册表文件、零缓存**：每次 `resolve`/`list`/`writeEntry` 都重新读取、解析、校验 YAML — 改文件立即生效，无需重启。
 - **分层条目**：每个 profile 携带 `ro` 层（agent 默认可读）和 `rw` 层（只有注册了 broker 授权后才发放）。
 - **Provider 缝**：每种凭据类型一个 provider（`k8s`/`ceph`/`ssh` 包），只提供 zod schema 加字段处理（`~` 展开、内容校验、能力探测）。provider 通过 `registerAccessProvider(ctx, provider)` 注册 — 绝不要手写 `ctx.inject` 依赖兄弟服务，会死锁 loader。
-- **`register_access` 工具**：agent 自助写入 ro 层的路径（rw 层始终由人通过 admin HTTP 路由管理）。
+- **引用字段**（`references`）：provider 可声明某字段指向另一个种类的条目（ssh 的 `cred` → `ssh-cred`），让多个条目共享一份凭证而不是各自复制。resolve 时 core 把被引用条目的字段合并到引用方**之下**（同注册表、同 tier、只展开一层）；broker 只被咨询一次，针对引用方条目。`validateResolved` 是合并后的校验钩子，承载只在合并形状上成立的要求（ssh 的登录用户可来自任一侧）。悬挂引用会让引用方的 resolve 及其 `canResolve` 预检一起失败。
+- **`register_access` 工具**：agent 自助写入 ro 层的路径；传 `tier: "rw"` 则**提交 rw 注册申请**（仅 hub 模式，ADR-0008）——申请排队在 hub 上，管理员在凭证管理设置区审查字段内容并批准后才真正写入。
 - **Mention 支持**：`@[kind/name](dsh-access:<payload>)` mention 在 `agent/pre-step` 上被解析、重写为可读引用并注入 envelope 上下文；`GET /ops-access/list` 给浏览器的 `@` 选择器供数。编码在 `./mention` 子路径。
 - **Admin 路由**：`GET /ops-access/admin/list`、`GET /ops-access/admin/kinds`、`GET|POST|DELETE /ops-access/admin/entry` — 只出 envelope + 校验状态，绝不出字段值。
+- **可插拔凭证来源**（`source`）：`yaml`（默认）读本地注册表文件；`hub` 每次调用都从独立部署的 [ops-access-hub](../../ops-access-hub/) 服务拉取。hub 模式下，文件类字段的内容物化到**独立的缓存目录**（`hubCacheDir`，默认 `~/.dsh-ops/hub-cache`），是受 TTL 约束的缓存（`materializeTtlMinutes`，默认 15 分钟），**绝不是永久副本**：启动时全量清扫（grant 账本随进程消亡，缓存的 rw 材料不得比它活得久），定时清扫按年龄过期，resolve 现取现物化、到期透明重建。yaml 模式的 `credentialsDir`（文档化的回退路径）永不被清扫。
 
 ## 设计要点
 
@@ -25,6 +27,12 @@
   name: '@elinpf/dsh-ops-access'
   registryFile: ~/.dsh-ops/access.yaml   # 默认值
   credentialsDir: ~/.dsh-ops/credentials # 默认值；托管凭据内容文件（0600）
+  # source: hub                          # 可选；默认 yaml
+  # hubUrl: http://127.0.0.1:3090        # hub 来源：hub 服务地址
+  # hubToken: ...                        # hub 来源：读 token（或用环境变量 ACCESS_HUB_READ_TOKEN）
+  # hubAdminToken: ...                   # hub 来源：写 token（或用环境变量 ACCESS_HUB_ADMIN_TOKEN）
+  # hubCacheDir: ~/.dsh-ops/hub-cache    # hub 来源：TTL 物化缓存目录（绝不用 credentialsDir）
+  # materializeTtlMinutes: 15            # hub 来源：缓存 TTL；启动时全量清扫
 ```
 
 ## 测试

package/lib/backend.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 type { EntryEnvelope, ProbeState } from './types.js';
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Build an EntryEnvelope from raw entry data, taking each envelope field from the first source that has it. */
+export declare function buildEnvelope(sources: Array<Record<string, unknown> | undefined>): EntryEnvelope;
+/** Read a persisted probe result off a raw tier object (durable boundary — sanitize). */
+export declare function probeOf(tierRaw: unknown): ProbeState | undefined;
+/**
+ * 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 declare function applyEnvelopePatch(target: Record<string, unknown>, envelope: EntryEnvelope | undefined): void;
+/** Merge an envelope patch over an existing envelope, returning the result (hub backend variant). */
+export declare function mergeEnvelope(existing: EntryEnvelope, patch: EntryEnvelope | undefined): EntryEnvelope;
+/** Tier presence + probe for the fields-free listing view. */
+export interface BackendTierStatus {
+    probe?: ProbeState;
+}
+/** One entry in the fields-free listing view (listAll, resolve error hints). */
+export interface BackendEntry {
+    kind: string;
+    name: string;
+    envelope: EntryEnvelope;
+    tiers: {
+        ro?: BackendTierStatus;
+        rw?: BackendTierStatus;
+    };
+}
+/** One tier's raw data: provider-shaped fields (file fields are LOCAL PATHS) + envelope + probe. */
+export interface BackendTier {
+    fields: Record<string, unknown>;
+    envelope: EntryEnvelope;
+    probe?: ProbeState;
+}
+/** Thrown when the source itself is unavailable (yaml: registry file missing) — resolve surfaces it verbatim. */
+export declare class SourceUnavailableError extends Error {
+}
+export interface AccessBackend {
+    /**
+     * Human phrase for error messages, used as `in ${label}`: yaml →
+     * `registry file <path>`, hub → `access hub at <url>`.
+     */
+    readonly label: string;
+    /**
+     * The fields-free listing of every entry: envelope + tier presence +
+     * probes. A missing source yields an empty list; an unreadable/corrupt
+     * source THROWS (callers pick their own degrade discipline, matching the
+     * pre-backend behavior per method).
+     */
+    listEntries(): Promise<BackendEntry[]>;
+    /**
+     * One tier's provider-shaped fields + envelope. Null when the entry or the
+     * tier does not exist. Throws SourceUnavailableError when the source
+     * itself is missing, and rethrows read/parse failures.
+     *
+     * `materialize` (default true) matters only for the hub backend: true
+     * writes fetched file-field contents to managed local files (resolve —
+     * the credential is being issued); false substitutes the would-be managed
+     * path WITHOUT touching disk (canResolve/list/getEntry — metadata reads
+     * must not write secret material, e.g. the gate's pre-approval check).
+     */
+    loadTier(kind: string, name: string, tier: 'ro' | 'rw', opts?: {
+        materialize?: boolean;
+    }): Promise<BackendTier | null>;
+    /**
+     * Persist one tier. `fields` is provider-shaped (file fields are local
+     * paths — the hub backend reads their content and uploads THAT; paths
+     * never leave the machine). `envelope` follows the patch discipline
+     * (undefined = preserve, '' = delete). `probe`, when given, is stored
+     * beside the tier.
+     */
+    putTier(kind: string, name: string, tier: 'ro' | 'rw', fields: Record<string, unknown>, envelope: EntryEnvelope | undefined, probe?: ProbeState): Promise<void>;
+    /**
+     * Remove one tier. Returns 'missing' when the entry did not exist, 'tier'
+     * when the tier is gone but the entry survives, 'entry' when the last
+     * tier went and the whole entry was dropped. (A tier that was already
+     * absent on an existing entry reports as if deleted — the pre-backend
+     * deleteEntry answered true for an existing entry regardless.)
+     */
+    deleteTier(kind: string, name: string, tier: 'ro' | 'rw'): Promise<'missing' | 'tier' | 'entry'>;
+}
+/**
+ * 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 declare class YamlBackend implements AccessBackend {
+    readonly registryFile: string;
+    readonly label: string;
+    constructor(registryFile: string);
+    listEntries(): Promise<BackendEntry[]>;
+    loadTier(kind: string, name: string, tier: 'ro' | 'rw'): Promise<BackendTier | null>;
+    putTier(kind: string, name: string, tier: 'ro' | 'rw', fields: Record<string, unknown>, envelope: EntryEnvelope | undefined, probe?: ProbeState): Promise<void>;
+    deleteTier(kind: string, name: string, tier: 'ro' | 'rw'): Promise<'missing' | 'tier' | 'entry'>;
+}

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.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 type { AccessProvider, EntryEnvelope, ProbeState } from './types.js';
+import type { AccessBackend, BackendEntry, BackendTier } from './backend.js';
+export interface HubBackendOptions {
+    /** Hub base URL, trailing slashes stripped (e.g. `http://127.0.0.1:3090`). */
+    baseUrl: string;
+    /** Bearer token for reads (resolve/list); empty = anonymous. */
+    readToken: string;
+    /** Bearer token for writes (put/delete); empty = anonymous. */
+    adminToken: string;
+    /**
+     * Cache root for materialized credential files (already `~`-expanded).
+     * Deliberately NOT the yaml mode's credentialsDir: hub-mode local files are
+     * a TTL-bound cache, never permanent copies, and the sweeper must never
+     * touch files the yaml registry still references (the documented fallback).
+     */
+    cacheDir: string;
+    /** Provider lookup — file-field declarations drive the content ↔ path conversion. */
+    getProvider: (kind: string) => AccessProvider | undefined;
+}
+/**
+ * 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 declare function sweepMaterialized(credentialsDir: string, maxAgeMs: number): Promise<number>;
+export declare class HubBackend implements AccessBackend {
+    private readonly opts;
+    readonly label: string;
+    constructor(opts: HubBackendOptions);
+    /**
+     * 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.
+     */
+    private request;
+    listEntries(): Promise<BackendEntry[]>;
+    loadTier(kind: string, name: string, tier: 'ro' | 'rw', loadOpts?: {
+        materialize?: boolean;
+    }): Promise<BackendTier | null>;
+    putTier(kind: string, name: string, tier: 'ro' | 'rw', fields: Record<string, unknown>, envelope: EntryEnvelope | undefined, probe?: ProbeState): Promise<void>;
+    deleteTier(kind: string, name: string, tier: 'ro' | 'rw'): Promise<'missing' | 'tier' | 'entry'>;
+    submitRequest(req: {
+        kind: string;
+        name: string;
+        tier: 'ro' | 'rw';
+        fields: Record<string, unknown>;
+        envelope?: EntryEnvelope;
+        reason?: string;
+    }): Promise<string>;
+    /** Pending-request metadata for the approval UI — field values never cross. */
+    listRequests(status?: 'pending' | 'approved' | 'rejected'): Promise<unknown>;
+    /** Full request incl. field values, for pre-approval review. Null when absent. */
+    getRequest(id: string): Promise<unknown>;
+    /** Approve (hub writes the tier) or reject. Returns false when already settled/absent. */
+    decideRequest(id: string, approved: boolean): Promise<boolean>;
+}