nx-sk 0.3.0

package/src/core/vault.js

@@ -0,0 +1,109 @@
+// 密钥解析：明文口令永不落盘，落盘的只有随机密钥文件 / 盐。
+//
+// 两种来源，优先级固定：
+//   1. 环境变量 NX_SK_PASSPHRASE → scrypt(口令, ~/nx-sk/.vaultsalt)
+//   2. ~/nx-sk/.vaultkey（32 字节随机密钥，首次使用时自动生成，尽量收紧权限）
+//
+// 同一份密文只能由**同一个**密钥解开。密钥指纹写进密文（core/crypto.js 的 kid），
+// 所以换来源时会得到明确的 BLOCKED 报错，而不是静默解出一堆乱码。
+import { randomBytes } from 'node:crypto';
+import fsp from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { ENV_PASSPHRASE, displayPath, vaultKeyFile, vaultSaltFile } from './paths.js';
+import { chmodPrivate, ensureDir, pathExists } from './fsx.js';
+import { KEY_BYTES, decryptValue, deriveKey, isCipherBlob, keyId, newKey } from './crypto.js';
+
+export const SOURCE_ENV = 'env';
+export const SOURCE_KEYFILE = 'keyfile';
+
+async function loadOrCreateSalt() {
+  const p = vaultSaltFile();
+  if (await pathExists(p)) {
+    const raw = (await fsp.readFile(p, 'utf8')).trim();
+    if (raw) return raw;
+  }
+  const salt = randomBytes(16);
+  await ensureDir(dirname(p));
+  await fsp.writeFile(p, salt.toString('base64') + '\n', 'utf8');
+  await chmodPrivate(p);
+  return salt.toString('base64');
+}
+
+async function loadOrCreateKeyFile() {
+  const p = vaultKeyFile();
+  if (await pathExists(p)) {
+    const raw = (await fsp.readFile(p, 'utf8')).trim();
+    if (raw) {
+      const buf = Buffer.from(raw, 'base64');
+      if (buf.length >= KEY_BYTES) return { key: buf.subarray(0, KEY_BYTES), created: false, path: p };
+    }
+  }
+  const key = newKey();
+  await ensureDir(dirname(p));
+  await fsp.writeFile(p, key.toString('base64') + '\n', { encoding: 'utf8', mode: 0o600 });
+  await chmodPrivate(p);
+  return { key, created: true, path: p };
+}
+
+/** 解析当前生效的密钥。会**按需创建**本地密钥文件——所以第一次就能直接用。 */
+export async function resolveVaultKey() {
+  const passphrase = process.env[ENV_PASSPHRASE];
+  if (passphrase) {
+    const salt = await loadOrCreateSalt();
+    const key = deriveKey(passphrase, salt);
+    return { key, source: SOURCE_ENV, saltFile: vaultSaltFile(), keyFile: null, created: false };
+  }
+  const { key, created, path } = await loadOrCreateKeyFile();
+  return { key, source: SOURCE_KEYFILE, saltFile: null, keyFile: path, created };
+}
+
+/** 只读状态查询：不创建任何文件，供 bootstrap / 面板展示。 */
+export async function vaultStatus() {
+  const passphrase = !!process.env[ENV_PASSPHRASE];
+  if (passphrase) {
+    const salt = vaultSaltFile();
+    return {
+      ready: true,
+      source: SOURCE_ENV,
+      keyFile: null,
+      saltFile: displayPath(salt),
+      saltExists: await pathExists(salt),
+      note: '密钥由环境变量 NX_SK_PASSPHRASE 派生（口令不落盘）。',
+    };
+  }
+  const p = vaultKeyFile();
+  const exists = await pathExists(p);
+  return {
+    ready: true,
+    source: SOURCE_KEYFILE,
+    keyFile: displayPath(p),
+    saltFile: null,
+    saltExists: false,
+    note: exists
+      ? '密钥来自本机密钥文件；删掉它会让已存密文无法解密。'
+      : '本机密钥文件尚未生成，首次写入密文字段时自动创建。',
+  };
+}
+
+/** 当前指纹，用于排查「密钥换过没有」。 */
+export async function currentKeyId() {
+  const { key } = await resolveVaultKey();
+  return keyId(key);
+}
+
+/**
+ * 造一个 `decrypt(blob) => 明文`，交给 core/render.js 做展示层解密。
+ *
+ * 为什么放在这里：render 是纯函数（可单测、无 IO），而「什么时候允许解密」
+ * 是安全决策——把它收成**一个**函数，就不会出现「某个出口忘了打码」。
+ * 只有当栏目里真有密文字段、且条目里真有密文时才去解析密钥（避免无谓地生成密钥文件）。
+ */
+export async function sensitiveViewer(section, entries = []) {
+  const sensitive = (section?.fields || []).filter((f) => f.sensitive || f.type === 'secret');
+  if (!sensitive.length) return undefined;
+  const keys = sensitive.map((f) => f.key);
+  const hasBlob = entries.some((e) => keys.some((k) => isCipherBlob(e?.values?.[k])));
+  if (!hasBlob) return undefined;
+  const { key } = await resolveVaultKey();
+  return (blob) => decryptValue(key, blob);
+}

package/src/index.js

@@ -0,0 +1,14 @@
+// 库入口：导出各模块 service，供程序化调用（别的项目可以 `import { entries } from 'nx-sk'`）。
+export * as system from './modules/system/service.js';
+export * as settings from './modules/settings/service.js';
+export * as sections from './modules/sections/service.js';
+export * as entries from './modules/entries/service.js';
+// `export` 是保留字，不能直接当绑定名，用别名导出
+export * as exportApi from './modules/export/service.js';
+export * as skill from './modules/skill/service.js';
+
+export { CODES, AppError } from './core/errors.js';
+export { APP_NAME, VERSION, appHome, storeFile } from './core/paths.js';
+export { loadStore, saveStore, mutateStore, storePathInUse } from './core/store.js';
+export { MODULES, ACTIONS, commandEntry } from './runtime/registry.js';
+export { ALL_COMMANDS } from './runtime/cli.js';

package/src/modules/entries/index.js

@@ -0,0 +1,152 @@
+import * as service from './service.js';
+
+export default {
+  id: 'entries',
+  title: '条目',
+  order: 600,
+  // 有视图，但**不是独立 tab**——它由「栏目」动态挂载（每个栏目一个 tab，共用这个视图）
+  view: () => import('./view.jsx'),
+  tab: false,
+  // 一组同级实体，每条有标识，用户会想改其中一条或删其中一条 → 集合资源
+  resource: 'entry',
+  actions: [
+    {
+      id: 'entry.list',
+      cli: ['entry', 'list'],
+      http: ['GET', '/api/entries'],
+      summary: '列条目（可按栏目过滤、按关键字搜索）；返回完整度与未填清单',
+      flags: {
+        // 读命令的过滤 flag 不带 default：「不传」代表「全部栏目」
+        section: { type: 'string', hint: '栏目 id 或标题' },
+        q: { type: 'string', hint: '关键字' },
+      },
+      run: (ctx) => service.listEntries(ctx),
+      render: (d) => service.renderEntryList(d),
+    },
+    {
+      id: 'entry.fields',
+      cli: ['entry', 'fields'],
+      http: ['GET', '/api/entries/fields'],
+      summary: '已知字段的台账：模板给的建议字段 + 你实际写过的字段（写入不受它限制，没见过的键会自动登记）',
+      flags: { section: { type: 'string' } },
+      run: (ctx) => service.fieldDictionary(ctx),
+      render: (d) => service.renderFields(d),
+    },
+    {
+      id: 'entry.get',
+      cli: ['entry', 'get'],
+      http: ['GET', '/api/entries/:ref'],
+      summary: '读单条（id 或条目名都接受）；密文字段默认原文，--mask 才打码',
+      args: ['ref'],
+      flags: {
+        mask: { type: 'boolean', hint: '密文字段打码显示（投屏/截图时用）' },
+        section: { type: 'string', hint: '限定栏目，解决同名歧义' },
+      },
+      run: (ctx) => service.getEntry(ctx.ref, ctx),
+      render: (d) => service.renderEntryGet(d),
+    },
+    {
+      id: 'entry.add',
+      cli: ['entry', 'add'],
+      http: ['POST', '/api/entries'],
+      summary: '新增条目。同栏目同名报 CONFLICT（不静默 upsert）；字段值用 --set 字段=值 或 --data @file.json，没见过的键会自动登记',
+      flags: {
+        section: { type: 'string', required: true, hint: '栏目 id 或标题' },
+        title: { type: 'string', hint: '条目名，缺省取栏目的名称字段' },
+        set: { type: 'kv', hint: '字段=值，可重复；键可用 key 或中文标签' },
+        data: { type: 'json', hint: '整份 JSON，或 @文件路径' },
+        tags: { type: 'array' },
+        'dry-run': { type: 'boolean' },
+      },
+      run: (ctx) => service.addEntry(ctx),
+      render: (d) => service.renderEntryChange(d),
+    },
+    {
+      id: 'entry.update',
+      cli: ['entry', 'update'],
+      http: ['PATCH', '/api/entries/:ref'],
+      summary: '改条目（PATCH 语义：只改传入字段）。字典里没有的字段会自动登记，直接写就行',
+      args: ['ref'],
+      flags: {
+        set: { type: 'kv', hint: '字段=值，可重复；键可以用 key 或中文标签，没见过的键会自动登记' },
+        data: { type: 'json', hint: '整份 JSON，或 @文件路径' },
+        unset: { type: 'array', hint: '要清空的字段 key，逗号分隔' },
+        title: { type: 'string' },
+        tags: { type: 'array' },
+        section: { type: 'string' },
+        'dry-run': { type: 'boolean' },
+      },
+      run: (ctx) => service.updateEntry(ctx.ref, ctx),
+      render: (d) => service.renderEntryChange(d),
+    },
+    {
+      id: 'entry.remove',
+      cli: ['entry', 'remove'],
+      http: ['DELETE', '/api/entries/:ref'],
+      summary: '删条目。目标不存在报 NOT_FOUND（不静默成功）。写前自动留快照',
+      args: ['ref'],
+      flags: {
+        section: { type: 'string' },
+        'dry-run': { type: 'boolean' },
+      },
+      run: (ctx) => service.removeEntry(ctx.ref, ctx),
+      render: (d) => service.renderEntryChange(d),
+    },
+
+    // —— 密钥 KV 直通命令 ——
+    // 作用在**标了 kv 的栏目**（密钥模板自带 kv: true）上，可以用 --section 指定别的。
+    // 它们是同一套 service 函数的语法糖，不是第二份业务逻辑。
+    {
+      id: 'key.list',
+      cli: ['key', 'list'],
+      http: ['GET', '/api/keys'],
+      summary: '列出全部密钥（值默认原文，要打码加 --mask）',
+      flags: {
+        mask: { type: 'boolean' },
+        section: { type: 'string', hint: '指定 KV 栏目，缺省用标了 kv 的那个' },
+      },
+      run: (ctx) => service.keyList(ctx),
+      render: (d) => service.renderKeyList(d),
+    },
+    {
+      id: 'key.get',
+      cli: ['key', 'get'],
+      http: ['GET', '/api/keys/:name'],
+      summary: '取一个密钥的值（默认原文；投屏/截图时加 --mask 打码）',
+      args: ['name'],
+      flags: {
+        mask: { type: 'boolean' },
+        section: { type: 'string' },
+      },
+      run: (ctx) => service.keyGet(ctx.name, ctx),
+      render: (d) => service.renderKeyGet(d),
+    },
+    {
+      id: 'key.set',
+      cli: ['key', 'set'],
+      http: ['PUT', '/api/keys/:name'],
+      summary: '写入密钥：不存在则新建，存在则覆盖（KV 的 SET 语义，返回值里带 created）。值以密文落盘',
+      args: ['name', 'value'],
+      flags: {
+        value: { type: 'string', hint: '值的另一种给法（值以 - 开头时用 --value=<值>）' },
+        section: { type: 'string' },
+        'dry-run': { type: 'boolean' },
+      },
+      run: (ctx) => service.keySet(ctx.name, ctx.value, ctx),
+      render: (d) => service.renderKeySet(d),
+    },
+    {
+      id: 'key.remove',
+      cli: ['key', 'remove'],
+      http: ['DELETE', '/api/keys/:name'],
+      summary: '删一个密钥。目标不存在报 NOT_FOUND；写前自动留快照',
+      args: ['name'],
+      flags: {
+        section: { type: 'string' },
+        'dry-run': { type: 'boolean' },
+      },
+      run: (ctx) => service.keyRemove(ctx.name, ctx),
+      render: (d) => service.renderKeyRemove(d),
+    },
+  ],
+};

package/src/modules/entries/kvTable.jsx

@@ -0,0 +1,158 @@
+import { useCallback, useEffect, useState } from 'react';
+import { api } from '../../web/frontend/api/client.js';
+import { useStore } from '../../web/frontend/store.jsx';
+import { CliHints, Copyable, Empty } from '../../web/frontend/components/ui.jsx';
+
+/**
+ * KV 表格：`kv: true` 栏目的**唯一**编辑界面。
+ *
+ * 一行 = 一个键值对（名称 → 值）。**没有**条目列表、没有字段表单、没有完整性百分比 ——
+ * 密钥就是一张表，别的一概不需要。
+ *
+ * 读写走 `key *` 那套接口（它本来就是 entry 命令的语法糖，共用同一份 service），
+ * 所以这里每个操作都有等价的 CLI 命令，且不可能和 CLI 分叉。
+ */
+export default function KvTable({ sectionId, sectionTitle }) {
+  const { ui, patchUi, toast, guard, dialog, reload } = useStore();
+  const [data, setData] = useState(null);
+  const [draft, setDraft] = useState({}); // 名称 → 正在编辑的值
+  const [added, setAdded] = useState({ name: '', value: '' });
+  const mask = !!ui.mask;
+
+  const load = useCallback(async () => {
+    try {
+      const q = `section=${encodeURIComponent(sectionId)}${mask ? '&mask=1' : ''}`;
+      const d = await api(`/api/keys?${q}`);
+      setData(d);
+      const next = {};
+      for (const k of d.keys) next[k.name] = k.value ?? '';
+      setDraft(next);
+    } catch (e) {
+      toast(e.message, 'bad');
+      setData(null);
+    }
+  }, [sectionId, mask, toast]);
+
+  useEffect(() => { load(); }, [load]);
+
+  const saveValue = guard(async (row) => {
+    const next = draft[row.name];
+    if ((row.value ?? '') === next) return; // 没改就不发请求
+    // 写操作的参数必须放 body —— 后端对非 GET 只合并 body（与 ?query= 无关）
+    await api(`/api/keys/${encodeURIComponent(row.name)}`, {
+      method: 'PUT', body: { value: next, section: sectionId },
+    });
+    toast(`已保存 ${row.name}`);
+    await load();
+  });
+
+  const rename = guard(async (row, newName) => {
+    const name = String(newName || '').trim();
+    if (!name || name === row.name) { setDraft((d) => ({ ...d, [row.name]: d[row.name] })); return; }
+    if (data.keys.some((k) => k.name === name)) { toast(`已经有叫「${name}」的键了`, 'bad'); await load(); return; }
+    await api(`/api/entries/${encodeURIComponent(row.id)}`, { method: 'PATCH', body: { title: name } });
+    toast(`已重命名为 ${name}`);
+    await load();
+    await reload();
+  });
+
+  const addKey = guard(async () => {
+    const name = added.name.trim();
+    if (!name) { toast('先填键名，例如 OPENAI_KEY', 'bad'); return; }
+    if (data.keys.some((k) => k.name === name)) { toast(`已经有叫「${name}」的键了——直接在上面那行改值即可`, 'bad'); return; }
+    await api(`/api/keys/${encodeURIComponent(name)}`, {
+      method: 'PUT', body: { value: added.value, section: sectionId },
+    });
+    setAdded({ name: '', value: '' });
+    toast(`已新增 ${name}`);
+    await load();
+    await reload();
+  });
+
+  const removeKey = guard(async (row) => {
+    const ok = await dialog({
+      message: `删除「${row.name}」？删除前会自动留一份整库快照在 ~/nx-sk/backup。`,
+      danger: true, confirmText: '删除',
+    });
+    if (!ok) return;
+    await api(`/api/keys/${encodeURIComponent(row.name)}`, { method: 'DELETE', body: { section: sectionId } });
+    toast(`已删除 ${row.name}`);
+    await load();
+    await reload();
+  });
+
+  if (!data) return <div className="pad muted">加载中…</div>;
+
+  return (
+    <>
+      <div className="toolbar rowgap pad">
+        <strong>{sectionTitle}</strong>
+        <span className="muted">{data.count} 个键 · 名称 → 值</span>
+        <span className="grow" />
+        <label className="inline hint">
+          <input type="checkbox" checked={mask} onChange={() => patchUi({ mask: !mask })} />
+          打码显示（投屏/截图时用）
+        </label>
+        <button className="btn small ghost" onClick={load}>刷新</button>
+      </div>
+
+      <div className="card">
+        <div className="colhead">
+          <span style={{ width: 200 }}>名称</span>
+          <span className="grow">值</span>
+        </div>
+        <div className="colbody">
+          {data.keys.length ? data.keys.map((row) => (
+            <div key={row.id} className="row">
+              <input
+                className="mono"
+                style={{ width: 200 }}
+                defaultValue={row.name}
+                title="改完按回车或点开别处即重命名"
+                onBlur={(e) => rename(row, e.target.value)}
+                onKeyDown={(e) => { if (e.key === 'Enter') e.currentTarget.blur(); }}
+              />
+              <input
+                className="mono grow"
+                value={draft[row.name] ?? ''}
+                onChange={(e) => setDraft((d) => ({ ...d, [row.name]: e.target.value }))}
+                onBlur={() => saveValue(row)}
+                onKeyDown={(e) => { if (e.key === 'Enter') e.currentTarget.blur(); }}
+              />
+              <span className="acts">
+                <Copyable className="tag" text={draft[row.name] ?? ''} title="点击复制值">复制</Copyable>
+                <button className="btn small ghost" onClick={() => removeKey(row)}>删除</button>
+              </span>
+            </div>
+          )) : <Empty>还没有密钥。在下面一行填「名称 / 值」按添加，或 CLI：nx-sk key set OPENAI_KEY sk-xxx</Empty>}
+
+          <div className="row">
+            <input
+              className="mono"
+              style={{ width: 200 }}
+              placeholder="新键名，例如 OPENAI_KEY"
+              value={added.name}
+              onChange={(e) => setAdded((a) => ({ ...a, name: e.target.value }))}
+              onKeyDown={(e) => { if (e.key === 'Enter') addKey(); }}
+            />
+            <input
+              className="mono grow"
+              placeholder="值（留空也行，之后再填）"
+              value={added.value}
+              onChange={(e) => setAdded((a) => ({ ...a, value: e.target.value }))}
+              onKeyDown={(e) => { if (e.key === 'Enter') addKey(); }}
+            />
+            <span className="acts"><button className="btn small" onClick={addKey}>添加</button></span>
+          </div>
+        </div>
+      </div>
+
+      <div className="pad hint">
+        改值：直接在「值」列改完按回车（或点开别处）即保存。改键名同理。
+        值以密文落盘，这里显示的是原文；要打码勾上方那个框。删除前自动整库快照。
+      </div>
+
+      <CliHints module="entries" />
+    </>
+  );
+}