@elinpf/dsh-ops-access-hub 0.3.0 → 0.4.0

package/README.md

@@ -7,9 +7,11 @@ Standalone credential hub for the dsh ops suite — **not a dsh plugin**. A smal
 ## 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.
+- **Token-authenticated HTTP API** (bare `node:http`, default bind `127.0.0.1:3090`), compared with `crypto.timingSafeEqual`, 401/403 distinguished. Two kinds of Bearer token:
+  - **Static bootstrap tokens** — one admin (everything), one read (resolving, case writes, the requests list), from CLI flag / env. Always accepted and impossible to revoke: the break-glass path.
+  - **Named tokens** (ADR-0009) — issue one per person with `POST /tokens` (or the CLI / web UI): a label, a role and an optional expiry. The plaintext is returned **once**; only its SHA-256 digest is stored. Revoke any single holder with `DELETE /tokens/:id` (terminal, effective immediately) without touching anyone else's credential. Edit a live record in place with `PATCH /tokens/:id` (ADR-0010): rename, change the role, extend or clear the expiry — the secret is untouched, so the holder never has to reconfigure.
+- **Append-only audit log** (`<data-dir>/audit.log`, JSONL): every successful resolve/put/delete with the token role — and, for named tokens, the holder label as `actor`, so multi-person usage is attributable. `token-update` lines also carry `changes` (the field names an edit touched, never values). Never field values.
+- **Single-file web UI** (`GET /`, Chinese): token input (localStorage, shows what it resolves to via `/whoami`), entry list with probe badges, create/edit/delete, a token roster and an audit viewer with the actor column. The page itself holds no secrets. The roster is the fine-grained control surface: a live/expiring/expired/revoked badge per record, search plus status/role filters with counts, local-time created/expires columns, issue with one-time plaintext, in-place edit, revoke.
 
 ## Usage
 
@@ -19,18 +21,29 @@ dsh-ops-access-hub serve [--port 3090] [--host 127.0.0.1] [--data-dir ~/.dsh-ops
 
 dsh-ops-access-hub import <access.yaml> \
   (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+
+dsh-ops-access-hub token create --name <name> --role <admin|read> [--expires-at <ISO>] \
+  (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+dsh-ops-access-hub token list   (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+dsh-ops-access-hub token update --id <id> [--name <name>] [--role <admin|read>] \
+  [--expires-at <ISO> | --clear-expires] \
+  (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+dsh-ops-access-hub token revoke --id <id> (--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`.
 
+`token create` prints the new plaintext exactly once — hand it to its holder out of band; the hub cannot show it again. The static `--admin-token` is the issuing credential (and stays valid as break-glass afterwards). `token update` edits a live record in place and prints only the field names it changed (nothing when the patch matched the current values); `token revoke` is terminal, so a token that should work again gets a new one. `token list` marks each record `active` / `expiring <date> (<N>d left)` / `EXPIRED <date>` / `REVOKED <date>`.
+
 ## API overview
 
 | Endpoint | Auth | Purpose |
 |---|---|---|
 | `GET /health` | none | `{ok:true}` |
 | `GET /` | none | the static web UI |
+| `GET /whoami` | read+ | what the presented token resolved to: `{role,actor,source}` |
 | `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 |
@@ -41,12 +54,18 @@ Every `serve` flag has an env counterpart (`ACCESS_HUB_PORT`, `ACCESS_HUB_HOST`,
 | `POST /cases` / `PUT /cases/:id` | read+ | create / update a case — **deliberate role relaxation**: cases hold no secrets and the agent only carries the read token |
 | `POST /cases/:id/hit` | read+ | bump a case's hit count |
 | `DELETE /cases/:id` | admin | remove a case |
+| `POST /tokens` | admin | issue a named token `{name,role,expiresAt?}` — **plaintext in this response only**; 409 on a duplicate live label |
+| `GET /tokens` | admin | the roster, metadata only — never the digest nor the plaintext |
+| `PATCH /tokens/:id` | admin | edit a live token `{name?,role?,expiresAt?}` — absent keeps, `null`/`''` clears the expiry; the secret is untouched (404 unknown, 409 revoked or label taken, 400 invalid/empty) |
+| `DELETE /tokens/:id` | admin | revoke one named token (terminal; 404 unknown, 409 already revoked) |
 
 ## 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.
+- Named tokens are stored as SHA-256 digests, not secrets: leaking the data file (or a backup) does not hand out working credentials. The static bootstrap tokens are the exception — they live in env/flag config, are the break-glass path, and cannot be revoked through the API.
+- An edit never touches the secret (same digest, same prefix): "wrong label" or "needs three more months" is not a reason to make a holder reconfigure. Making a credential stop working is revocation's job, and revocation stays terminal — a record is never un-revoked.
 
 ## Testing
 
@@ -54,5 +73,9 @@ Every `serve` flag has an env counterpart (`ACCESS_HUB_PORT`, `ACCESS_HUB_HOST`,
 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
+                  # probe write-back, audit append, import path→content,
+                  # named tokens (issue / one-time plaintext / role / revoke /
+                  # expiry / actor attribution), fine-grained token admin
+                  # (status buckets, in-place PATCH edit, renewal, no-op
+                  # patches, audit changes), web-shell inline-script compile
 ```

package/README.zh.md

@@ -7,9 +7,11 @@ dsh ops 插件集的独立凭证中心——**不是 dsh 插件**。一个小型
 ## 功能
 
 - **加密落盘**：整个数据集是一个 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 徽标的条目列表、新建/编辑/删除、审计查看。页面本身不含任何秘密。
+- **token 认证的 HTTP API**（裸 `node:http`，默认绑 `127.0.0.1:3090`），`crypto.timingSafeEqual` 比较，401/403 区分。两种 Bearer token：
+  - **静态 bootstrap token**——admin（全量）与 read（解析、病例写入、申请列表）各一把，来自 CLI flag / env。始终有效、不可吊销：break-glass 路径。
+  - **具名 token**（ADR-0009）——用 `POST /tokens`（或 CLI / Web UI）**按人**签发：标签 + 角色 + 可选有效期。明文**只返回一次**，落库只存 SHA-256 摘要；`DELETE /tokens/:id` 按人吊销（终态、立即生效），不影响其他人的凭证。`PATCH /tokens/:id` 就地编辑活记录（ADR-0010）：改标签、改角色、延期或清除有效期——**秘密不变**，持有人无需重新配置。
+- **append-only 审计日志**（`<data-dir>/audit.log`，JSONL）：每次成功的 resolve/put/delete 连同 token 角色各记一行——具名 token 还记持有人标签 `actor`，多人使用可归属；`token-update` 行另记 `changes`（改动涉及的字段名，不是值）。永不记字段值。
+- **单文件中文 Web UI**（`GET /`）：token 输入（localStorage，经 `/whoami` 显示解析出的角色与标签）、带 probe 徽标的条目列表、新建/编辑/删除、token 名册、审计查看（含操作者列）。页面本身不含任何秘密。名册即精细控制面：每行四态徽标（有效 / 即将过期 / 已过期 / 已吊销）、关键字搜索 + 状态/角色筛选 + 计数汇总、本地时区的创建与到期时间、签发与一次性明文展示、就地编辑、吊销。
 
 ## 用法
 
@@ -19,34 +21,59 @@ dsh-ops-access-hub serve [--port 3090] [--host 127.0.0.1] [--data-dir ~/.dsh-ops
 
 dsh-ops-access-hub import <access.yaml> \
   (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+
+dsh-ops-access-hub token create --name <name> --role <admin|read> [--expires-at <ISO>] \
+  (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+dsh-ops-access-hub token list   (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+dsh-ops-access-hub token update --id <id> [--name <name>] [--role <admin|read>] \
+  [--expires-at <ISO> | --clear-expires] \
+  (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+dsh-ops-access-hub token revoke --id <id> (--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` 离线直写数据文件。
 
+`token create` 只打印一次明文——请线下交付持有人，hub 无法再次展示。签发凭证是静态 `--admin-token`（它自己作为 break-glass 继续有效）。`token update` 就地编辑活记录并只打印实际改动的字段名（补丁与现值一致时什么都不打印）；`token revoke` 是终态，需要恢复访问就重新签发。`token list` 的状态列区分 `active` / `expiring <时间> (<N>d left)` / `EXPIRED <时间>` / `REVOKED <时间>`。
+
 ## API 一览
 
 | 端点 | 鉴权 | 用途 |
 |---|---|---|
 | `GET /health` | 无 | `{ok:true}` |
 | `GET /` | 无 | 静态 Web UI |
+| `GET /whoami` | read+ | 当前 token 解析结果：`{role,actor,source}` |
 | `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） |
+| `GET /cases` | read+ | 排错病例索引行——只有元数据，无全文 |
+| `GET /cases/:id` | read+ | 单条病例完整记录 |
+| `POST /cases` / `PUT /cases/:id` | read+ | 新建/更新病例——**刻意的角色放宽**：病例不含机密，agent 只持 read token |
+| `POST /cases/:id/hit` | read+ | 病例命中数 +1 |
+| `DELETE /cases/:id` | admin | 删除病例 |
+| `POST /tokens` | admin | 签发具名 token `{name,role,expiresAt?}`——**明文只在这个响应里**；活标签重名 409 |
+| `GET /tokens` | admin | token 名册，只有元数据——永不含摘要与明文 |
+| `PATCH /tokens/:id` | admin | 就地编辑活 token `{name?,role?,expiresAt?}`——缺席=不改、`null`/`''`=清除有效期；**秘密不变**（404 不存在、409 已吊销或标签被占、400 非法值/空补丁） |
+| `DELETE /tokens/:id` | admin | 吊销一个具名 token（终态；404 不存在、409 已吊销） |
 
 ## 安全注意
 
 - v1 是明文 HTTP，默认只绑 loopback——远程部署必须把 hub 放在 TLS 反向代理之后。
 - hub 是单点：**数据文件和 master key 都要备份**。丢了 key，数据文件无法恢复。
 - token 不要进日志和 shell 历史（优先用环境变量注入）；消费方只配 read token，admin token 只给写入方。
+- 具名 token 落库的是 SHA-256 摘要而非秘密本身：数据文件（或备份）泄露不会直接交出可用凭证。静态 bootstrap token 是例外——它们活在 env/flag 配置里，是 break-glass 路径，无法通过 API 吊销。
+- 编辑从不碰秘密（摘要、前缀原样）：「标签写错」「想再延三个月」不该让持有人重新配置。让一把钥匙失效是吊销的职责，而吊销保持终态——记录不会被"复活"。
 
 ## 测试
 
 ```sh
 npm run build     # tsc → lib/
 npx vitest run    # 加解密往返、key 文件生成与权限、API 鉴权（401/403）、
-                  # CRUD、最后-tier 连锁删除、probe 回写、审计追加、import 路径→内容
+                  # CRUD、最后-tier 连锁删除、probe 回写、审计追加、import 路径→内容、
+                  # 具名 token（签发/一次性明文/角色/吊销/过期/actor 归属）、
+                  # token 精细管理（状态四分、PATCH 就地编辑、续期、无操作补丁、审计 changes）、
+                  # Web UI 内联脚本可编译检查
 ```

package/lib/cli.d.ts

@@ -9,6 +9,9 @@
  * - `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).
+ * - `token create|list|update|revoke` — issue, list, edit and revoke named
+ *   tokens (ADR-0009 / ADR-0010), against a running hub (`--url` +
+ *   `--admin-token`) or directly in a data directory (`--data-dir`).
  * - `--help` — usage.
  *
  * @module

package/lib/cli.js

@@ -9,6 +9,9 @@
  * - `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).
+ * - `token create|list|update|revoke` — issue, list, edit and revoke named
+ *   tokens (ADR-0009 / ADR-0010), against a running hub (`--url` +
+ *   `--admin-token`) or directly in a data directory (`--data-dir`).
  * - `--help` — usage.
  *
  * @module
@@ -19,11 +22,16 @@ import { join } from 'node:path';
 import { HubStore } from './store.js';
 import { createHubServer } from './server.js';
 import { applyToStore, importRegistry, pushToHub } from './import.js';
+import { generateToken, hashToken, parseExpiresAt, parseExpiresAtPatch, parseTokenName, parseTokenRole, toTokenView, tokenPrefix, tokenStatus, } from './tokens.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 token create --name <name> --role <admin|read> [--expires-at <ISO>] (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+  dsh-ops-access-hub token list (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+  dsh-ops-access-hub token update --id <id> [--name <name>] [--role <admin|read>] [--expires-at <ISO> | --clear-expires] (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
+  dsh-ops-access-hub token revoke --id <id> (--url <hubUrl> --admin-token <token> | --data-dir <dir>) [--key-file <file>]
   dsh-ops-access-hub --help
 
 serve options (flag / env / default):
@@ -34,6 +42,15 @@ serve options (flag / env / default):
   --admin-token  ACCESS_HUB_ADMIN_TOKEN   (generated + printed once when unset)
   --read-token   ACCESS_HUB_READ_TOKEN    (generated + printed once when unset)
 
+Named tokens (ADR-0009): issue one per holder with 'token create' and hand the
+printed value over out of band — it is shown once and stored only as a digest.
+--admin-token is the issuing credential (the static bootstrap token).
+'token update' edits a live record in place (label / role / expiry) — the
+secret itself never changes, so the holder keeps working without re-issuing
+(pass --clear-expires to drop an expiry). 'token list' marks each record
+active / expiring / EXPIRED / REVOKED.
+The static admin/read tokens stay valid as break-glass credentials.
+
 Master key: env ACCESS_HUB_KEY (base64/hex) wins; otherwise the key file is
 used and generated (0600) on first start.
 `;
@@ -64,6 +81,188 @@ function expandHome(p) {
 function pick(flags, flag, env, fallback) {
     return flags[flag] ?? env ?? fallback;
 }
+/**
+ * Resolve the shared `--url <hubUrl> --admin-token <t>` vs `--data-dir <dir>`
+ * target. The two are mutually exclusive; the HTTP form needs the admin token.
+ * Errors carry the caller's command name as prefix.
+ */
+function resolveTarget(flags, command) {
+    const hubUrl = flags.url;
+    const dataDir = flags['data-dir'] ? expandHome(flags['data-dir']) : undefined;
+    const adminToken = flags['admin-token'] ?? process.env.ACCESS_HUB_ADMIN_TOKEN;
+    if (!hubUrl && !dataDir)
+        throw new Error(`${command}: specify either --url <hubUrl> or --data-dir <dir>`);
+    if (hubUrl && dataDir)
+        throw new Error(`${command}: --url and --data-dir are mutually exclusive`);
+    if (hubUrl && !adminToken)
+        throw new Error(`${command}: --url mode requires --admin-token (or ACCESS_HUB_ADMIN_TOKEN)`);
+    return { hubUrl, adminToken, dataDir };
+}
+/** Open the encrypted store behind a `--data-dir` target. */
+async function openStore(flags, dataDir) {
+    const keyFile = expandHome(pick(flags, 'key-file', process.env.ACCESS_HUB_KEY_FILE, join(dataDir, 'hub.key')));
+    const store = new HubStore({ dataDir, keyFile, envKey: process.env.ACCESS_HUB_KEY });
+    await store.init();
+    return store;
+}
+/**
+ * One HTTP call against a running hub with the admin token. Errors never
+ * embed the token, and a non-2xx response surfaces the hub's own `error`.
+ */
+async function hubRequest(hubUrl, adminToken, path, init) {
+    const res = await fetch(`${hubUrl.replace(/\/$/, '')}${path}`, {
+        method: init?.method ?? 'GET',
+        headers: {
+            authorization: `Bearer ${adminToken}`,
+            ...(init?.body === undefined ? {} : { 'content-type': 'application/json' }),
+        },
+        body: init?.body === undefined ? undefined : JSON.stringify(init.body),
+    });
+    const text = await res.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = undefined;
+    }
+    if (!res.ok) {
+        const detail = body && typeof body === 'object' && 'error' in body ? String(body.error) : text.slice(0, 200);
+        throw new Error(`hub returned ${res.status}: ${detail}`);
+    }
+    return body;
+}
+/** Whole days until an ISO expiry, rounded up so a live token never reads "0d left". */
+function daysLeft(expiresAt, now) {
+    return Math.ceil((Date.parse(expiresAt) - now.getTime()) / 86_400_000);
+}
+/** One roster line for `token list`; the state column mirrors the web UI's badges (ADR-0010). */
+function formatToken(t, now = new Date()) {
+    const status = tokenStatus(t, now);
+    let state;
+    if (status === 'revoked')
+        state = `REVOKED ${t.revokedAt}`;
+    else if (status === 'expired')
+        state = `EXPIRED ${t.expiresAt}`;
+    else if (status === 'expiring')
+        state = `expiring ${t.expiresAt} (${daysLeft(t.expiresAt, now)}d left)`;
+    else
+        state = 'active';
+    return `${t.id}  ${t.role.padEnd(5)}  ${t.prefix}...  ${t.name}  (created ${t.createdAt} by ${t.createdBy})  ${state}`;
+}
+/** Build the `token update` patch from CLI flags; throws when there is nothing to change. */
+function patchFromFlags(flags) {
+    try {
+        if (flags['clear-expires'] === 'true' && flags['expires-at'] !== undefined) {
+            throw new Error('--expires-at and --clear-expires are mutually exclusive');
+        }
+        const patch = {};
+        if (flags.name !== undefined)
+            patch.name = parseTokenName(flags.name);
+        if (flags.role !== undefined)
+            patch.role = parseTokenRole(flags.role);
+        if (flags['clear-expires'] === 'true')
+            patch.expiresAt = null;
+        else if (flags['expires-at'] !== undefined)
+            patch.expiresAt = parseExpiresAtPatch(flags['expires-at']) ?? null;
+        if (patch.name === undefined && patch.role === undefined && patch.expiresAt === undefined) {
+            throw new Error('nothing to change (use --name, --role, --expires-at or --clear-expires)');
+        }
+        return patch;
+    }
+    catch (err) {
+        throw new Error(`token update: ${err.message}`);
+    }
+}
+/** Edit one token in an offline store (the caller saves when something changed). */
+function updateTokenInStore(store, id, patch) {
+    let updated;
+    try {
+        updated = store.updateToken(id, patch);
+    }
+    catch (err) {
+        throw new Error(`token update: ${err.message}`);
+    }
+    if (!updated)
+        throw new Error(`token update: token ${id} not found`);
+    return updated.changes;
+}
+/** `token create|list|update|revoke` — issue and manage named tokens (ADR-0009/0010). */
+async function tokenCmd(args) {
+    const { positional, flags } = args;
+    const action = positional[1];
+    if (action !== 'create' && action !== 'list' && action !== 'update' && action !== 'revoke') {
+        throw new Error('token: expected one of create | list | update | revoke');
+    }
+    const { hubUrl, adminToken, dataDir } = resolveTarget(flags, `token ${action}`);
+    const store = dataDir === undefined ? undefined : await openStore(flags, dataDir);
+    if (action === 'list') {
+        const tokens = store ? store.listTokens().map(toTokenView) : (await hubRequest(hubUrl, adminToken, '/tokens'));
+        if (tokens.length === 0)
+            console.log('no named tokens issued');
+        else
+            for (const t of tokens)
+                console.log(formatToken(t));
+        return;
+    }
+    if (action === 'create') {
+        const name = parseTokenName(flags.name ?? '');
+        const role = parseTokenRole(flags.role ?? '');
+        const expiresAt = parseExpiresAt(flags['expires-at']);
+        const entity = store
+            ? createTokenInStore(store, { name, role, expiresAt })
+            : (await hubRequest(hubUrl, adminToken, '/tokens', {
+                method: 'POST',
+                body: { name, role, ...(expiresAt !== undefined ? { expiresAt } : {}) },
+            }));
+        if (store)
+            await store.save();
+        console.log(`issued ${role} token '${name}' (id ${entity.id}) — hand it over out of band; it will not be shown again:`);
+        console.log(`  ${entity.token}`);
+        return;
+    }
+    const id = flags.id;
+    if (!id)
+        throw new Error(`token ${action}: missing --id <id>`);
+    if (action === 'update') {
+        const patch = patchFromFlags(flags);
+        const changes = store
+            ? updateTokenInStore(store, id, patch)
+            : (await hubRequest(hubUrl, adminToken, `/tokens/${encodeURIComponent(id)}`, { method: 'PATCH', body: patch })).changes;
+        // A no-op patch must not rewrite (and re-encrypt) the whole document.
+        if (store && changes.length > 0)
+            await store.save();
+        console.log(changes.length === 0 ? `token ${id}: already up to date` : `updated token ${id}: ${changes.join(', ')}`);
+        return;
+    }
+    if (store) {
+        const token = store.getToken(id);
+        if (!token)
+            throw new Error(`token revoke: token ${id} not found`);
+        if (!store.revokeToken(id))
+            throw new Error(`token revoke: token ${id} is already revoked`);
+        await store.save();
+    }
+    else {
+        await hubRequest(hubUrl, adminToken, `/tokens/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    }
+    console.log(`revoked token ${id}`);
+}
+/** Mint + record one token in an offline store (the caller saves). */
+function createTokenInStore(store, input) {
+    if (store.findTokenByName(input.name))
+        throw new Error(`token create: name '${input.name}' is already in use`);
+    const token = generateToken();
+    const issued = store.putToken({
+        name: input.name,
+        role: input.role,
+        hash: hashToken(token),
+        prefix: tokenPrefix(token),
+        createdBy: 'cli',
+        ...(input.expiresAt !== undefined ? { expiresAt: input.expiresAt } : {}),
+    });
+    return { id: issued.id, token };
+}
 async function serve(args) {
     const { flags } = args;
     const port = Number.parseInt(pick(flags, 'port', process.env.ACCESS_HUB_PORT, '3090'), 10);
@@ -100,23 +299,13 @@ async function importCmd(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 { hubUrl, adminToken, dataDir } = resolveTarget(flags, 'import');
     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();
+        const store = await openStore(flags, dataDir);
         applyToStore(store, entries);
         await store.save();
     }
@@ -129,6 +318,8 @@ async function main() {
         return serve(args);
     if (command === 'import')
         return importCmd(args);
+    if (command === 'token')
+        return tokenCmd(args);
     if (command === 'help' || args.flags.help === 'true' || args.flags.h === 'true' || command === undefined) {
         console.log(USAGE);
         return;

package/lib/index.d.ts

@@ -5,14 +5,17 @@
  *
  * - encrypted-at-rest single-document store (AES-256-GCM), see `./store.js`;
  * - token-authenticated REST API + minimal web UI, see `./server.js`;
+ * - named, revocable tokens with roles and audit attribution, see `./tokens.js`;
  * - YAML registry importer, see `./import.js`;
- * - `dsh-ops-access-hub` bin (`serve` / `import`), see `./cli.js`.
+ * - `dsh-ops-access-hub` bin (`serve` / `import` / `token`), see `./cli.js`.
  *
  * @module @elinpf/dsh-ops-access-hub
  */
 export { MASTER_KEY_BYTES, generateMasterKey, parseMasterKey, loadMasterKey, encryptDoc, decryptDoc } from './crypto.js';
 export { HubStore, MAX_CASES } from './store.js';
 export type { TierName, ProbeState, EntryEnvelope, TierData, HubEntry, AuditRecord, HubStoreOptions, CaseRecord, CaseInput } from './store.js';
+export { MAX_TOKENS, TOKEN_NAME_PATTERN, TOKEN_PREFIX_CHARS, TOKEN_ROLES, generateToken, hashEqual, hashToken, isTokenActive, parseExpiresAt, parseTokenName, parseTokenRole, toTokenView, tokenPrefix, } from './tokens.js';
+export type { HubToken, TokenRole, TokenView } from './tokens.js';
 export { createHubServer, NAME_PATTERN } from './server.js';
 export type { HubServerOptions } from './server.js';
 export { importRegistry, pushToHub, applyToStore } from './import.js';

package/lib/index.js

@@ -5,13 +5,15 @@
  *
  * - encrypted-at-rest single-document store (AES-256-GCM), see `./store.js`;
  * - token-authenticated REST API + minimal web UI, see `./server.js`;
+ * - named, revocable tokens with roles and audit attribution, see `./tokens.js`;
  * - YAML registry importer, see `./import.js`;
- * - `dsh-ops-access-hub` bin (`serve` / `import`), see `./cli.js`.
+ * - `dsh-ops-access-hub` bin (`serve` / `import` / `token`), see `./cli.js`.
  *
  * @module @elinpf/dsh-ops-access-hub
  */
 export { MASTER_KEY_BYTES, generateMasterKey, parseMasterKey, loadMasterKey, encryptDoc, decryptDoc } from './crypto.js';
 export { HubStore, MAX_CASES } from './store.js';
+export { MAX_TOKENS, TOKEN_NAME_PATTERN, TOKEN_PREFIX_CHARS, TOKEN_ROLES, generateToken, hashEqual, hashToken, isTokenActive, parseExpiresAt, parseTokenName, parseTokenRole, toTokenView, tokenPrefix, } from './tokens.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

@@ -28,10 +28,26 @@
  *                                          read token)
  * - `POST /cases/:id/hit`                → bump a case's hit count (read+)
  * - `DELETE /cases/:id`                  → remove a case (admin)
+ * - `GET /whoami`                        → `{ok,role,actor,source}` for the presented
+ *                                          token (read+)
+ * - `POST /tokens`                       → issue a named token, body `{name,role,expiresAt?}`;
+ *                                          the plaintext is in this response only (admin)
+ * - `GET /tokens`                        → issued-token roster, metadata only — never
+ *                                          the digest or the plaintext (admin)
+ * - `PATCH /tokens/:id`                  → edit a live token's `{name?,role?,expiresAt?}`
+ *                                          (`null`/`''` clears the expiry); 404 unknown,
+ *                                          409 revoked or label taken (admin)
+ * - `DELETE /tokens/:id`                 → revoke a named token; 404 unknown, 409 already
+ *                                          revoked (admin)
  *
- * 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.
+ * Auth: `Authorization: Bearer <token>`, compared with `crypto.timingSafeEqual`.
+ * Two roles — admin (everything) and read (resolving, case writes, the
+ * requests list). A token is either one of the two static bootstrap tokens
+ * (CLI flag / env, always accepted, the break-glass path) or a named token
+ * issued through `POST /tokens` (ADR-0009): independently revocable,
+ * optionally expiring, and recorded as the audit `actor`. Named tokens are
+ * stored as SHA-256 digests only. Every error response is JSON
+ * `{ok:false,error}` and `error` never contains field values.
  *
  * @module
  */
@@ -41,7 +57,13 @@ import { NAME_PATTERN } from './store.js';
 export { NAME_PATTERN };
 export interface HubServerOptions {
     store: HubStore;
+    /**
+     * Static bootstrap admin token (flag/env). Always accepted — the
+     * break-glass path that keeps the hub reachable after every named token
+     * has been revoked, and the credential from before ADR-0009 existed.
+     */
     adminToken: string;
+    /** Static bootstrap read token (flag/env); same bootstrap role as `adminToken`. */
     readToken: string;
 }
 export declare function createHubServer(opts: HubServerOptions): Server;