@elinpf/dsh-ops-access 0.1.7 → 0.2.0

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/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>;
+}

package/lib/index.d.ts

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