@elinpf/dsh-ops-access-hub 0.2.0

package/README.md

@@ -0,0 +1,53 @@
+# @elinpf/dsh-ops-access-hub
+
+English | [中文](README.zh.md)
+
+Standalone credential hub for the dsh ops suite — **not a dsh plugin**. A small, separately deployable service that stores every ops-access credential in a single AES-256-GCM-encrypted document and serves it over a token-authenticated HTTP API, with a minimal web UI and a YAML registry importer. `@elinpf/dsh-ops-access` (core) can use it as its credential source (`source: 'hub'`); the hub itself is dumb storage — kind schemas, validation, and probes all stay on the access side.
+
+## What it does
+
+- **Encrypted-at-rest storage.** The whole dataset is one JSON document (`<data-dir>/hub-data.json.enc`), AES-256-GCM with a random nonce per write, atomic write-temp-then-rename, mode 0600. The master key comes from env `ACCESS_HUB_KEY` (base64/hex) or a key file (default `<data-dir>/hub.key`, generated 0600 on first start). File fields hold their *content*, not paths.
+- **Dual-token HTTP API** (bare `node:http`, default bind `127.0.0.1:3090`): an admin token for everything, a read token for listing and resolve; compared with `crypto.timingSafeEqual`, 401/403 distinguished.
+- **Append-only audit log** (`<data-dir>/audit.log`, JSONL): every successful resolve/put/delete with the token role — never field values.
+- **Single-file web UI** (`GET /`, Chinese): token input (localStorage), entry list with probe badges, create/edit/delete, audit viewer. The page itself holds no secrets.
+
+## Usage
+
+```sh
+dsh-ops-access-hub serve [--port 3090] [--host 127.0.0.1] [--data-dir ~/.dsh-ops-hub] \
+  [--key-file <file>] [--admin-token <t>] [--read-token <t>]
+
+dsh-ops-access-hub import <access.yaml> \
+  (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+```
+
+Every `serve` flag has an env counterpart (`ACCESS_HUB_PORT`, `ACCESS_HUB_HOST`, `ACCESS_HUB_DATA_DIR`, `ACCESS_HUB_KEY_FILE`, `ACCESS_HUB_ADMIN_TOKEN`, `ACCESS_HUB_READ_TOKEN`). Tokens left unset are generated randomly and printed exactly once on first start.
+
+`import` converts an existing ops-access YAML registry: a single-line field value starting with `/`, `~/`, `./` or `../` that points at a readable file is replaced by the file's content (relative paths resolve against the registry file's directory); everything else passes through unchanged. Push into a running hub with `--url`, or write the data file directly with `--data-dir`.
+
+## API overview
+
+| Endpoint | Auth | Purpose |
+|---|---|---|
+| `GET /health` | none | `{ok:true}` |
+| `GET /` | none | the static web UI |
+| `GET /entries` | read+ | envelope + tier presence + probe per entry — **never field values** |
+| `GET /entries/:kind/:name/:tier` | read+ | full fields for one tier (audited as `resolve`); 404 when absent |
+| `PUT /entries/:kind/:name/:tier` | admin | upsert `{fields, envelope?, probe?}`; envelope replaces wholesale |
+| `DELETE /entries/:kind/:name/:tier` | admin | removing the last tier deletes the whole entry |
+| `GET /audit?limit=N` | admin | recent N audit records (default 100, cap 1000) |
+
+## Security notes
+
+- v1 speaks plain HTTP and binds loopback by default — remote deployments must put the hub behind a TLS-terminating reverse proxy.
+- The hub is a single point of custody: **back up both the data file and the master key.** Without the key the data file is unrecoverable.
+- Keep tokens out of logs and shell history (prefer env injection); the read token suffices for consumers — only writers need the admin token.
+
+## Testing
+
+```sh
+npm run build     # tsc → lib/
+npx vitest run    # crypto round-trip, key-file generation and permissions,
+                  # API auth (401/403), CRUD, last-tier cascade delete,
+                  # probe write-back, audit append, import path→content
+```

package/README.zh.md

@@ -0,0 +1,52 @@
+# @elinpf/dsh-ops-access-hub
+
+[English](README.md) | 中文
+
+dsh ops 插件集的独立凭证中心——**不是 dsh 插件**。一个小型、可独立部署的服务：全部 ops-access 凭证存于单一 AES-256-GCM 加密文档，对外提供 token 认证的 HTTP API，附带精简 Web 界面和 YAML 注册表导入器。`@elinpf/dsh-ops-access`（core）可以把它作为凭证来源（`source: 'hub'`）；hub 本身是哑存储——kind schema、校验、能力探针都留在 access 侧。
+
+## 功能
+
+- **加密落盘**：整个数据集是一个 JSON 文档（`<data-dir>/hub-data.json.enc`），AES-256-GCM、每次写随机 nonce、tmp+rename 原子写、0600。master key 来自环境变量 `ACCESS_HUB_KEY`（base64/hex）或 key 文件（默认 `<data-dir>/hub.key`，首启自动生成，0600）。文件类字段存**内容**而非路径。
+- **双 token HTTP API**（裸 `node:http`，默认绑 `127.0.0.1:3090`）：admin token 全量、read token 仅列表与解析；`crypto.timingSafeEqual` 比较，401/403 区分。
+- **append-only 审计日志**（`<data-dir>/audit.log`，JSONL）：每次成功的 resolve/put/delete 连同 token 角色各记一行——永不记字段值。
+- **单文件中文 Web UI**（`GET /`）：token 输入（localStorage）、带 probe 徽标的条目列表、新建/编辑/删除、审计查看。页面本身不含任何秘密。
+
+## 用法
+
+```sh
+dsh-ops-access-hub serve [--port 3090] [--host 127.0.0.1] [--data-dir ~/.dsh-ops-hub] \
+  [--key-file <file>] [--admin-token <t>] [--read-token <t>]
+
+dsh-ops-access-hub import <access.yaml> \
+  (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+```
+
+每个 `serve` flag 都有环境变量对应（`ACCESS_HUB_PORT`、`ACCESS_HUB_HOST`、`ACCESS_HUB_DATA_DIR`、`ACCESS_HUB_KEY_FILE`、`ACCESS_HUB_ADMIN_TOKEN`、`ACCESS_HUB_READ_TOKEN`）。未配置的 token 首启随机生成并**只打印一次**。
+
+`import` 把现有 ops-access YAML 注册表搬进 hub：单行且以 `/`、`~/`、`./`、`../` 开头并指向可读文件的字段值替换为文件内容（相对路径相对注册表文件目录解析），其余原样通过。`--url` 在线推送进运行中的 hub，或 `--data-dir` 离线直写数据文件。
+
+## API 一览
+
+| 端点 | 鉴权 | 用途 |
+|---|---|---|
+| `GET /health` | 无 | `{ok:true}` |
+| `GET /` | 无 | 静态 Web UI |
+| `GET /entries` | read+ | 每条目的 envelope + tier 存在性 + probe——**永不含字段值** |
+| `GET /entries/:kind/:name/:tier` | read+ | 单个 tier 的完整 fields（记 `resolve` 审计）；缺失 404 |
+| `PUT /entries/:kind/:name/:tier` | admin | upsert `{fields, envelope?, probe?}`；envelope 整体替换 |
+| `DELETE /entries/:kind/:name/:tier` | admin | 删除最后一个 tier 时整条删除 |
+| `GET /audit?limit=N` | admin | 最近 N 条审计（默认 100，上限 1000） |
+
+## 安全注意
+
+- v1 是明文 HTTP，默认只绑 loopback——远程部署必须把 hub 放在 TLS 反向代理之后。
+- hub 是单点：**数据文件和 master key 都要备份**。丢了 key，数据文件无法恢复。
+- token 不要进日志和 shell 历史（优先用环境变量注入）；消费方只配 read token，admin token 只给写入方。
+
+## 测试
+
+```sh
+npm run build     # tsc → lib/
+npx vitest run    # 加解密往返、key 文件生成与权限、API 鉴权（401/403）、
+                  # CRUD、最后-tier 连锁删除、probe 回写、审计追加、import 路径→内容
+```

package/lib/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * `dsh-ops-access-hub` CLI. Hand-rolled minimal argv parsing — no commander
+ * & co. by design (dependency floor: `yaml` only).
+ *
+ * Commands:
+ *
+ * - `serve` — run the hub HTTP service.
+ * - `import <access.yaml>` — convert an ops-access YAML registry and push it
+ *   into a running hub (`--url` + `--admin-token`) or straight into a data
+ *   directory (`--data-dir`, needs the master key).
+ * - `--help` — usage.
+ *
+ * @module
+ */
+export {};

package/lib/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * `dsh-ops-access-hub` CLI. Hand-rolled minimal argv parsing — no commander
+ * & co. by design (dependency floor: `yaml` only).
+ *
+ * Commands:
+ *
+ * - `serve` — run the hub HTTP service.
+ * - `import <access.yaml>` — convert an ops-access YAML registry and push it
+ *   into a running hub (`--url` + `--admin-token`) or straight into a data
+ *   directory (`--data-dir`, needs the master key).
+ * - `--help` — usage.
+ *
+ * @module
+ */
+import { randomBytes } from 'node:crypto';
+import os from 'node:os';
+import { join } from 'node:path';
+import { HubStore } from './store.js';
+import { createHubServer } from './server.js';
+import { applyToStore, importRegistry, pushToHub } from './import.js';
+const USAGE = `dsh-ops-access-hub — standalone credential hub for the dsh ops suite
+
+Usage:
+  dsh-ops-access-hub serve [options]
+  dsh-ops-access-hub import <access.yaml> (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+  dsh-ops-access-hub --help
+
+serve options (flag / env / default):
+  --port         ACCESS_HUB_PORT          3090
+  --host         ACCESS_HUB_HOST          127.0.0.1
+  --data-dir     ACCESS_HUB_DATA_DIR      ~/.dsh-ops-hub
+  --key-file     ACCESS_HUB_KEY_FILE      <data-dir>/hub.key
+  --admin-token  ACCESS_HUB_ADMIN_TOKEN   (generated + printed once when unset)
+  --read-token   ACCESS_HUB_READ_TOKEN    (generated + printed once when unset)
+
+Master key: env ACCESS_HUB_KEY (base64/hex) wins; otherwise the key file is
+used and generated (0600) on first start.
+`;
+/** Minimal parser: `--flag value` pairs; everything else is positional. */
+function parseArgs(argv) {
+    const out = { positional: [], flags: {} };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const eq = arg.indexOf('=');
+            if (eq !== -1)
+                out.flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+            else if (i + 1 < argv.length && !argv[i + 1].startsWith('--'))
+                out.flags[arg.slice(2)] = argv[++i];
+            else
+                out.flags[arg.slice(2)] = 'true';
+        }
+        else {
+            out.positional.push(arg);
+        }
+    }
+    return out;
+}
+/** Expand a leading `~` to $HOME. */
+function expandHome(p) {
+    return p === '~' ? os.homedir() : p.startsWith('~/') ? join(os.homedir(), p.slice(2)) : p;
+}
+function pick(flags, flag, env, fallback) {
+    return flags[flag] ?? env ?? fallback;
+}
+async function serve(args) {
+    const { flags } = args;
+    const port = Number.parseInt(pick(flags, 'port', process.env.ACCESS_HUB_PORT, '3090'), 10);
+    if (!Number.isFinite(port) || port < 1 || port > 65535)
+        throw new Error(`invalid port`);
+    const host = pick(flags, 'host', process.env.ACCESS_HUB_HOST, '127.0.0.1');
+    const dataDir = expandHome(pick(flags, 'data-dir', process.env.ACCESS_HUB_DATA_DIR, '~/.dsh-ops-hub'));
+    const keyFile = expandHome(pick(flags, 'key-file', process.env.ACCESS_HUB_KEY_FILE, join(dataDir, 'hub.key')));
+    // Any token not injected via flag/env is generated randomly and printed
+    // exactly once — there is no recovery path other than reconfiguring.
+    let adminToken = flags['admin-token'] ?? process.env.ACCESS_HUB_ADMIN_TOKEN;
+    let readToken = flags['read-token'] ?? process.env.ACCESS_HUB_READ_TOKEN;
+    if (!adminToken) {
+        adminToken = randomBytes(24).toString('base64url');
+        console.log(`generated admin token (save it now — it will not be shown again):\n  ${adminToken}`);
+    }
+    if (!readToken) {
+        do {
+            readToken = randomBytes(24).toString('base64url');
+        } while (readToken === adminToken);
+        console.log(`generated read token (save it now — it will not be shown again):\n  ${readToken}`);
+    }
+    const store = new HubStore({ dataDir, keyFile, envKey: process.env.ACCESS_HUB_KEY });
+    await store.init();
+    const server = createHubServer({ store, adminToken, readToken });
+    await new Promise((resolveListen, rejectListen) => {
+        server.once('error', rejectListen);
+        server.listen(port, host, () => resolveListen());
+    });
+    console.log(`dsh-ops-access-hub listening on http://${host}:${port} (data dir: ${dataDir})`);
+}
+async function importCmd(args) {
+    const { positional, flags } = args;
+    const registryFile = positional[1];
+    if (!registryFile)
+        throw new Error('import: missing <access.yaml> argument');
+    const hubUrl = flags.url;
+    const adminToken = flags['admin-token'] ?? process.env.ACCESS_HUB_ADMIN_TOKEN;
+    const dataDir = flags['data-dir'] ? expandHome(flags['data-dir']) : undefined;
+    if (!hubUrl && !dataDir)
+        throw new Error('import: specify either --url <hubUrl> or --data-dir <dir>');
+    if (hubUrl && dataDir)
+        throw new Error('import: --url and --data-dir are mutually exclusive');
+    if (hubUrl && !adminToken)
+        throw new Error('import: --url mode requires --admin-token (or ACCESS_HUB_ADMIN_TOKEN)');
+    const { entries, stats } = await importRegistry(expandHome(registryFile));
+    if (hubUrl) {
+        await pushToHub(hubUrl, adminToken, entries);
+    }
+    else {
+        const keyFile = expandHome(pick(flags, 'key-file', process.env.ACCESS_HUB_KEY_FILE, join(dataDir, 'hub.key')));
+        const store = new HubStore({ dataDir: dataDir, keyFile, envKey: process.env.ACCESS_HUB_KEY });
+        await store.init();
+        applyToStore(store, entries);
+        await store.save();
+    }
+    console.log(`imported ${stats.entries} entries, ${stats.tiers} tiers, ${stats.fileFields} file fields inlined`);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    const command = args.positional[0];
+    if (command === 'serve')
+        return serve(args);
+    if (command === 'import')
+        return importCmd(args);
+    if (command === 'help' || args.flags.help === 'true' || args.flags.h === 'true' || command === undefined) {
+        console.log(USAGE);
+        return;
+    }
+    console.error(`unknown command: ${command}\n\n${USAGE}`);
+    process.exitCode = 1;
+}
+main().catch((err) => {
+    console.error(err.message);
+    process.exitCode = 1;
+});

package/lib/crypto.d.ts

@@ -0,0 +1,38 @@
+/**
+ * At-rest encryption for the hub data document.
+ *
+ * AES-256-GCM with a random 12-byte nonce per write. The on-disk file is a
+ * base64-encoded JSON document `{ nonce, data }` where `data` is
+ * ciphertext || 16-byte auth tag — a text container (chosen over raw binary
+ * concatenation) so the file stays inspectable and survives text-oriented
+ * tooling.
+ *
+ * The master key is 32 bytes and comes from, in priority order:
+ *
+ * 1. env `ACCESS_HUB_KEY` — base64 or hex (64 hex chars, checked first since
+ *    a hex string is also valid base64 input);
+ * 2. a key file (default `<data-dir>/hub.key`, base64-encoded) — generated
+ *    on first start with mode 0600 when absent.
+ *
+ * @module
+ */
+export declare const MASTER_KEY_BYTES = 32;
+/** Generate a fresh random master key. */
+export declare function generateMasterKey(): Buffer;
+/**
+ * Parse a master key from its text form: 64 hex chars, or base64 decoding to
+ * exactly 32 bytes. Hex is tried first (a hex string also parses as base64).
+ */
+export declare function parseMasterKey(raw: string): Buffer;
+/**
+ * Resolve the master key: `envKey` wins; otherwise read `keyFile`, generating
+ * it (mode 0600, parent dirs created) on first start.
+ */
+export declare function loadMasterKey(opts: {
+    envKey?: string;
+    keyFile: string;
+}): Promise<Buffer>;
+/** Encrypt a UTF-8 document; returns the base64 text container for the file. */
+export declare function encryptDoc(plaintext: string, key: Buffer): string;
+/** Decrypt a document produced by {@link encryptDoc}; throws on any tampering (GCM tag check). */
+export declare function decryptDoc(blob: string, key: Buffer): string;

package/lib/crypto.js

@@ -0,0 +1,82 @@
+/**
+ * At-rest encryption for the hub data document.
+ *
+ * AES-256-GCM with a random 12-byte nonce per write. The on-disk file is a
+ * base64-encoded JSON document `{ nonce, data }` where `data` is
+ * ciphertext || 16-byte auth tag — a text container (chosen over raw binary
+ * concatenation) so the file stays inspectable and survives text-oriented
+ * tooling.
+ *
+ * The master key is 32 bytes and comes from, in priority order:
+ *
+ * 1. env `ACCESS_HUB_KEY` — base64 or hex (64 hex chars, checked first since
+ *    a hex string is also valid base64 input);
+ * 2. a key file (default `<data-dir>/hub.key`, base64-encoded) — generated
+ *    on first start with mode 0600 when absent.
+ *
+ * @module
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export const MASTER_KEY_BYTES = 32;
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+/** Generate a fresh random master key. */
+export function generateMasterKey() {
+    return randomBytes(MASTER_KEY_BYTES);
+}
+/**
+ * Parse a master key from its text form: 64 hex chars, or base64 decoding to
+ * exactly 32 bytes. Hex is tried first (a hex string also parses as base64).
+ */
+export function parseMasterKey(raw) {
+    const text = raw.trim();
+    if (/^[0-9a-fA-F]{64}$/.test(text))
+        return Buffer.from(text, 'hex');
+    const key = Buffer.from(text, 'base64');
+    if (key.length !== MASTER_KEY_BYTES) {
+        throw new Error(`invalid master key: expected ${MASTER_KEY_BYTES} bytes (base64 or hex)`);
+    }
+    return key;
+}
+/**
+ * Resolve the master key: `envKey` wins; otherwise read `keyFile`, generating
+ * it (mode 0600, parent dirs created) on first start.
+ */
+export async function loadMasterKey(opts) {
+    if (opts.envKey)
+        return parseMasterKey(opts.envKey);
+    try {
+        return parseMasterKey(await readFile(opts.keyFile, 'utf8'));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    const key = generateMasterKey();
+    await mkdir(dirname(opts.keyFile), { recursive: true });
+    await writeFile(opts.keyFile, key.toString('base64') + '\n', { mode: 0o600 });
+    return key;
+}
+/** Encrypt a UTF-8 document; returns the base64 text container for the file. */
+export function encryptDoc(plaintext, key) {
+    const nonce = randomBytes(NONCE_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    const data = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final(), cipher.getAuthTag()]);
+    return Buffer.from(JSON.stringify({ nonce: nonce.toString('base64'), data: data.toString('base64') }), 'utf8')
+        .toString('base64');
+}
+/** Decrypt a document produced by {@link encryptDoc}; throws on any tampering (GCM tag check). */
+export function decryptDoc(blob, key) {
+    const packed = JSON.parse(Buffer.from(blob.trim(), 'base64').toString('utf8'));
+    const nonce = Buffer.from(packed.nonce, 'base64');
+    const data = Buffer.from(packed.data, 'base64');
+    if (nonce.length !== NONCE_BYTES || data.length < TAG_BYTES)
+        throw new Error('corrupt hub data file');
+    const tag = data.subarray(data.length - TAG_BYTES);
+    const ciphertext = data.subarray(0, data.length - TAG_BYTES);
+    const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+}

package/lib/import.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Import an existing ops-access YAML registry into the hub.
+ *
+ * Registry format (see `@elinpf/dsh-ops-access`): `version: 1` at the top;
+ * every other top-level key is a kind; keys inside a kind are profile names;
+ * an entry carries optional envelope fields (`name` / `description` /
+ * `environment`) and `ro` / `rw` tier sub-objects holding the fields.
+ *
+ * Conversion rule: within a tier, a field whose value is a single-line
+ * string starting with `/`, `~/`, `./` or `../` is treated as a file path;
+ * when it points at a readable file the value is replaced by the file's
+ * content (the hub stores content, not paths). A path-shaped value that
+ * cannot be read aborts the import with an error naming the entry and
+ * field. All other values pass through unchanged. Relative paths resolve
+ * against the registry file's directory; `~` expands to `$HOME`.
+ *
+ * @module
+ */
+import type { EntryEnvelope, HubStore, ProbeState } from './store.js';
+export interface ImportedEntry {
+    kind: string;
+    name: string;
+    envelope: EntryEnvelope;
+    tiers: {
+        ro?: {
+            fields: Record<string, unknown>;
+            probe?: ProbeState;
+        };
+        rw?: {
+            fields: Record<string, unknown>;
+            probe?: ProbeState;
+        };
+    };
+}
+export interface ImportStats {
+    entries: number;
+    tiers: number;
+    /** Tier fields whose path value was replaced by file content. */
+    fileFields: number;
+}
+export interface ImportResult {
+    entries: ImportedEntry[];
+    stats: ImportStats;
+}
+/** Parse and convert a registry file. Throws on malformed YAML or an unreadable path-shaped field. */
+export declare function importRegistry(registryFile: string): Promise<ImportResult>;
+/** Push imported entries into a running hub over HTTP (one PUT per tier). */
+export declare function pushToHub(hubUrl: string, adminToken: string, entries: ImportedEntry[]): Promise<void>;
+/** Write imported entries directly into a store (offline mode; caller owns init/save). */
+export declare function applyToStore(store: HubStore, entries: ImportedEntry[]): void;

package/lib/import.js

@@ -0,0 +1,123 @@
+/**
+ * Import an existing ops-access YAML registry into the hub.
+ *
+ * Registry format (see `@elinpf/dsh-ops-access`): `version: 1` at the top;
+ * every other top-level key is a kind; keys inside a kind are profile names;
+ * an entry carries optional envelope fields (`name` / `description` /
+ * `environment`) and `ro` / `rw` tier sub-objects holding the fields.
+ *
+ * Conversion rule: within a tier, a field whose value is a single-line
+ * string starting with `/`, `~/`, `./` or `../` is treated as a file path;
+ * when it points at a readable file the value is replaced by the file's
+ * content (the hub stores content, not paths). A path-shaped value that
+ * cannot be read aborts the import with an error naming the entry and
+ * field. All other values pass through unchanged. Relative paths resolve
+ * against the registry file's directory; `~` expands to `$HOME`.
+ *
+ * @module
+ */
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+const PATH_PREFIX = /^(\/|~\/|\.\/|\.\.\/)/;
+/** A value is path-shaped when it is a single-line string with a path prefix. */
+function looksLikePath(v) {
+    return typeof v === 'string' && !v.includes('\n') && PATH_PREFIX.test(v);
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Parse and convert a registry file. Throws on malformed YAML or an unreadable path-shaped field. */
+export async function importRegistry(registryFile) {
+    const doc = parseYaml(await readFile(registryFile, 'utf8'));
+    if (!isPlainObject(doc))
+        throw new Error(`import: ${registryFile} is not a YAML mapping`);
+    const baseDir = dirname(resolve(registryFile));
+    const entries = [];
+    const stats = { entries: 0, tiers: 0, fileFields: 0 };
+    for (const [kind, section] of Object.entries(doc)) {
+        if (kind === 'version')
+            continue;
+        if (!isPlainObject(section))
+            throw new Error(`import: kind '${kind}' is not a mapping`);
+        for (const [name, rawEntry] of Object.entries(section)) {
+            if (!isPlainObject(rawEntry))
+                throw new Error(`import: entry '${kind}/${name}' is not a mapping`);
+            const envelope = {};
+            if (typeof rawEntry.name === 'string')
+                envelope.name = rawEntry.name;
+            if (typeof rawEntry.description === 'string')
+                envelope.description = rawEntry.description;
+            if (typeof rawEntry.environment === 'string')
+                envelope.environment = rawEntry.environment;
+            const entry = { kind, name, envelope, tiers: {} };
+            for (const tier of ['ro', 'rw']) {
+                const rawTier = rawEntry[tier];
+                if (rawTier === undefined)
+                    continue;
+                if (!isPlainObject(rawTier))
+                    throw new Error(`import: tier '${kind}/${name} ${tier}' is not a mapping`);
+                // The auto-managed `probe` key rides BESIDE the fields in the
+                // registry (written at save time by the access probe) — lift it to
+                // the tier level instead of importing it as a field.
+                const { probe: rawProbe, ...rawFields } = rawTier;
+                const probe = isPlainObject(rawProbe) ? rawProbe : undefined;
+                const fields = {};
+                for (const [field, value] of Object.entries(rawFields)) {
+                    if (looksLikePath(value)) {
+                        const expanded = value.startsWith('~') ? os.homedir() + value.slice(1) : value;
+                        const filePath = isAbsolute(expanded) ? expanded : resolve(baseDir, expanded);
+                        try {
+                            fields[field] = await readFile(filePath, 'utf8');
+                        }
+                        catch (err) {
+                            throw new Error(`import: cannot read file field '${kind}/${name} ${tier}.${field}' (${filePath}): ${err.message}`);
+                        }
+                        stats.fileFields++;
+                    }
+                    else {
+                        fields[field] = value;
+                    }
+                }
+                entry.tiers[tier] = probe !== undefined ? { fields, probe } : { fields };
+                stats.tiers++;
+            }
+            entries.push(entry);
+            stats.entries++;
+        }
+    }
+    return { entries, stats };
+}
+/** Push imported entries into a running hub over HTTP (one PUT per tier). */
+export async function pushToHub(hubUrl, adminToken, entries) {
+    const base = hubUrl.replace(/\/+$/, '');
+    for (const entry of entries) {
+        for (const tier of ['ro', 'rw']) {
+            const tierData = entry.tiers[tier];
+            if (!tierData)
+                continue;
+            const url = `${base}/entries/${encodeURIComponent(entry.kind)}/${encodeURIComponent(entry.name)}/${tier}`;
+            const res = await fetch(url, {
+                method: 'PUT',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${adminToken}` },
+                body: JSON.stringify({ fields: tierData.fields, envelope: entry.envelope, ...(tierData.probe !== undefined ? { probe: tierData.probe } : {}) }),
+            });
+            if (!res.ok) {
+                const body = (await res.json().catch(() => undefined));
+                throw new Error(`import: PUT ${entry.kind}/${entry.name} ${tier} failed (${res.status}): ${body?.error ?? res.statusText}`);
+            }
+        }
+    }
+}
+/** Write imported entries directly into a store (offline mode; caller owns init/save). */
+export function applyToStore(store, entries) {
+    for (const entry of entries) {
+        for (const tier of ['ro', 'rw']) {
+            const tierData = entry.tiers[tier];
+            if (!tierData)
+                continue;
+            store.putTier(entry.kind, entry.name, tier, { fields: tierData.fields, envelope: entry.envelope, ...(tierData.probe !== undefined ? { probe: tierData.probe } : {}) });
+        }
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Ops access hub — a standalone, centrally deployable credential management
+ * service for the dsh ops suite. **Not a dsh plugin**: no cordis patch, no
+ * preset row. The access side pulls secret content from it over HTTP.
+ *
+ * - encrypted-at-rest single-document store (AES-256-GCM), see `./store.js`;
+ * - token-authenticated REST API + minimal web UI, see `./server.js`;
+ * - YAML registry importer, see `./import.js`;
+ * - `dsh-ops-access-hub` bin (`serve` / `import`), see `./cli.js`.
+ *
+ * @module @elinpf/dsh-ops-access-hub
+ */
+export { MASTER_KEY_BYTES, generateMasterKey, parseMasterKey, loadMasterKey, encryptDoc, decryptDoc } from './crypto.js';
+export { HubStore } from './store.js';
+export type { TierName, ProbeState, EntryEnvelope, TierData, HubEntry, AuditRecord, HubStoreOptions } from './store.js';
+export { createHubServer, NAME_PATTERN } from './server.js';
+export type { HubServerOptions } from './server.js';
+export { importRegistry, pushToHub, applyToStore } from './import.js';
+export type { ImportedEntry, ImportStats, ImportResult } from './import.js';
+export { WEB_UI_HTML } from './web.js';

package/lib/index.js

@@ -0,0 +1,17 @@
+/**
+ * Ops access hub — a standalone, centrally deployable credential management
+ * service for the dsh ops suite. **Not a dsh plugin**: no cordis patch, no
+ * preset row. The access side pulls secret content from it over HTTP.
+ *
+ * - encrypted-at-rest single-document store (AES-256-GCM), see `./store.js`;
+ * - token-authenticated REST API + minimal web UI, see `./server.js`;
+ * - YAML registry importer, see `./import.js`;
+ * - `dsh-ops-access-hub` bin (`serve` / `import`), see `./cli.js`.
+ *
+ * @module @elinpf/dsh-ops-access-hub
+ */
+export { MASTER_KEY_BYTES, generateMasterKey, parseMasterKey, loadMasterKey, encryptDoc, decryptDoc } from './crypto.js';
+export { HubStore } from './store.js';
+export { createHubServer, NAME_PATTERN } from './server.js';
+export { importRegistry, pushToHub, applyToStore } from './import.js';
+export { WEB_UI_HTML } from './web.js';

package/lib/server.d.ts

@@ -0,0 +1,39 @@
+/**
+ * HTTP API for the hub, built on bare `node:http` (no framework by design).
+ *
+ * Endpoints (default bind `127.0.0.1:3090`):
+ *
+ * - `GET /health`                        → `{ok:true}`, no auth
+ * - `GET /`                              → the static web UI, no auth (it holds no secrets)
+ * - `GET /entries`                       → `[{kind,name,envelope,tiers:{ro?:{probe?},rw?:{probe?}},updatedAt}]`
+ *                                          (read+; field values never appear here)
+ * - `GET /entries/:kind/:name/:tier`     → `{kind,name,tier,fields,envelope,probe?}` (read+; audited as `resolve`)
+ * - `PUT /entries/:kind/:name/:tier`     → upsert, body `{fields,envelope?,probe?}` (admin)
+ * - `DELETE /entries/:kind/:name/:tier`  → `{ok:true}` / 404 (admin; last tier removes the entry)
+ * - `GET /audit?limit=N`                 → recent N audit records (admin, default 100)
+ * - `POST /requests`                     → queue a tier-registration request, body
+ *                                          `{kind,name,tier,fields,envelope?,reason?}` (admin)
+ * - `GET /requests?status=pending`       → request list, metadata only — field
+ *                                          names + byte sizes, never values (read+)
+ * - `GET /requests/:id`                  → full request incl. field values, for
+ *                                          pre-approval review (admin)
+ * - `POST /requests/:id/decide`          → `{approved:boolean}`; approval writes the
+ *                                          tier, either way the request's fields are
+ *                                          wiped (admin; 409 unless pending)
+ *
+ * Auth: two Bearer tokens — admin (everything) and read (`GET /entries*`
+ * only). Comparisons use `crypto.timingSafeEqual`. Every error response is
+ * JSON `{ok:false,error}` and `error` never contains field values.
+ *
+ * @module
+ */
+import type { Server } from 'node:http';
+import type { HubStore } from './store.js';
+/** Profile name / kind charset; kinds additionally can never contain `/` (path segment). */
+export declare const NAME_PATTERN: RegExp;
+export interface HubServerOptions {
+    store: HubStore;
+    adminToken: string;
+    readToken: string;
+}
+export declare function createHubServer(opts: HubServerOptions): Server;