@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/docs/workspace-mcp.md

@@ -0,0 +1,284 @@
+# 工作区 + MCP 架构
+
+> 分支：`refactor/workspace-mcp`。这是 v3 架构说明；旧版“每个项目一个目录 + 嵌入式 SurrealDB”不再使用，也不做自动迁移。
+
+## 1. 目录布局
+
+第一次运行 `/fancy-bootstrap` 时由用户选择工作区 `A`：
+
+```text
+A/
+  .fancy/
+    workspace.json          # 工作区 ID、SurrealDB 端点、当前项目
+    secrets.json            # SurrealDB root/项目用户密码（0600）
+    surreal/
+      data/                 # SurrealDB 数据目录
+      server.log
+      server.pid
+    bin/surreal             # /fancy-db install 下载的二进制（可选）
+    trash/                  # 删除项目时的默认归档位置
+  projects/
+    <uuid>/                 # 一个小说项目
+      .fancy-project.json   # UUID、数据库名、数据库用户、工作区路径
+      导出/                  # fancy-export 输出
+      设定/                  # 项目本地资料（导入/兼容用）
+  扫榜结果/                  # 多个项目共享的扫榜产物
+  参考资料/                  # 待拆解的对标小说（fancy-analyze 读取）
+  对标/                      # 多个项目共享的对标分析
+  references/               # 共享写作参考
+  .fancy-deployed           # 扫榜/选题阶段状态
+```
+
+关键点：
+
+- 项目目录名是 UUID；小说名不参与目录名。
+- 项目标题只存在数据库（注册表 + `story:main`），改名不会移动目录。
+- `fancy-scan`、`fancy-analyze` 的产物在工作区根目录，多个项目共享。
+- 项目目录里的 `.fancy-project.json` 只保存连接信息，不保存小说名。
+
+## 2. 数据库模型
+
+一个工作区一个 SurrealDB server，所有项目共用：
+
+```text
+namespace: fancy
+  database: fancy_registry       # 项目注册表
+    project:<id> { project_id, name, db_name, db_user, dir, status, topic }
+  database: material_library     # 工作区级素材库，所有项目共享
+    material, material_relation
+    material_search              # 中文 ngram 全文索引
+  database: proj_<uuid>          # 每个项目一个库
+    story, scale, chapter, outline, ...
+    fn::fancy::validate(...)     # 数据库内置校验函数
+```
+
+项目用户：
+
+```text
+用户名：u_<uuid 前 16 位>
+角色：VIEWER
+权限：只能访问自己的 database；数据表 ALTER TABLE ... PERMISSIONS FOR select/create/update/delete FULL
+```
+
+- 项目用户不能 `DEFINE / REMOVE` 表、函数、事件。
+- schema、事件、校验函数由插件 root 会话创建。
+- root 密码和项目用户密码在 `A/.fancy/secrets.json`，文件权限 0600；不要把该文件提交到 git。
+- 默认只绑定 `127.0.0.1:8000`。需要远程访问时自行改 `workspace.json` 的 `surreal.bind/url`，并配置 TLS/防火墙。
+
+## 3. 命令
+
+### 工作区
+
+```text
+/fancy-bootstrap                 交互选择工作区并初始化
+/fancy-bootstrap <目录>          指定工作区
+/fancy-bootstrap status          查看工作区和服务
+/fancy-bootstrap list            列出本机记录的所有工作区
+/fancy-bootstrap help
+```
+
+初始化会创建目录、密钥、注册表、数据库校验函数和素材库 schema（`material_library`）。没有 `surreal` 时会尝试下载到 `A/.fancy/bin/`。
+
+### 数据库
+
+```text
+/fancy-db status
+/fancy-db install
+/fancy-db start | stop
+/fancy-db init [all]                     # 建 schema + 校验函数 + 权限 + fancy_meta
+/fancy-db init project <名字|UUID>
+/fancy-db list
+/fancy-db remove <名字|UUID> [--purge]   # 默认把项目目录移到 .fancy/trash
+```
+
+`/fancy-db init` 是幂等的；升级插件后重跑它即可更新 schema、`fn::fancy::validate` 和素材库表。
+
+### 素材库
+
+```text
+/fancy-material                  # 生成全部原子素材类型，按 kind 顺序
+/fancy-material 地名             # 只生成指定类型（其他质量/题材/追加规则仍保留）
+/fancy-material import <文件>    # 先校验 JSONL，再追加导入
+/fancy-material init             # 创建/补齐素材库 schema、索引、查询脚本
+/fancy-material remove           # 删除整个素材库（二次确认）
+/fancy-material prompt           # 展示全类型提示词，不发给 LLM
+/fancy-material export           # 导出 A/素材库.md
+```
+
+素材库是工作区级数据库 `material_library`，所有项目共享。每条素材只有
+`id / kind / name / tags / genres / note / source` 七个字段，是“小积木”而不是人物/金手指大卡。`source=builtin` 的 kind 受内置列表限制，`source=other` 可以使用任意自定义 kind。
+每次运行每个 kind 新增 50 条；每批最多 10 条，插件自动分批完成。无参数且有多份 topic_decision 文件时先弹窗选择使用哪一份。未指定类型时覆盖全部 kind，指定类型时只生成指定 kind；库内不设 50 条上限，运行两次就是每个 kind 100 条。只追加、不覆盖，
+同 `kind + name` 自动去重。表结构和查询说明见
+[`docs/material-library/README.md`](./material-library/README.md)。
+
+### 抖音图文采集
+
+```text
+/fancy-douyin add <主页地址>       # 记录一个抖音账号主页
+/fancy-douyin list                # 查看已记录账号
+/fancy-douyin remove <序号|地址>  # 删除账号记录
+/fancy-douyin                     # 依次采集所有账号下未处理的图文
+/fancy-douyin help
+```
+
+只处理 `/note/` 图文作品，跳过视频。每篇作品截图保存为 JPG，然后交给 LLM
+提取素材，按 material JSONL 写入数据库，`source` 固定为 `other`。已成功入库的
+作品记录在工作区 `/.fancy/douyin/crawled.json`，后续跳过。
+
+登录态保存在工作区 `/.fancy/douyin/chrome-profile/`，并镜像 cookies 到
+`login-state.json`。首次需要登录时使用有头 Chrome，登录态有效后后续运行自动
+使用无头 Chrome；无头登录态失效时会切回有头让你手动登录。遇到登录框或安全
+验证时会弹窗，完成后选择「已登陆」。每次运行结束会自动关闭 Chrome。浏览器脚本部署在 `/.fancy-tools/fancy-douyin/`。
+
+### 项目
+
+```text
+/fancy-project list
+/fancy-project find <关键词>
+/fancy-project id <小说名>        # 小说名 → UUID
+/fancy-project name <UUID>        # UUID → 小说名
+/fancy-project info <名字|UUID>
+/fancy-project use <名字|UUID>    # 设为当前项目
+/fancy-project rename <名字|UUID> <新小说名>
+```
+
+改名只更新注册表和 `story:main.title`；UUID、目录、数据库、项目用户都不变。
+
+### 创作
+
+```text
+/fancy-topic              # 在工作区读扫榜结果，生成选题建议
+/fancy-topic setup        # 敲定选题 → 创建 projects/<uuid>/ + 项目库 + 用户
+/fancy-build scale|macro|cast|rhythm|outline|write
+/fancy-export
+```
+
+项目解析顺序：
+
+1. 显式 `--project <名字|UUID>`
+2. 当前 cwd 所在的项目目录
+3. 工作区 `active_project`
+4. 工作区里只有一个项目时自动使用它
+
+### 共享分析
+
+```text
+/fancy-scan      → A/扫榜结果/
+/fancy-analyze   → 读取 A/参考资料/，产出到 A/对标/
+```
+
+多个项目引用同一份工作区产物，不再每个项目重复分析。
+
+## 4. 数据库内置校验
+
+`fancy-db init` / 每次 `openStoryGraph` 都会生成：
+
+- `fn::fancy::validate($scope)`：返回 `{ errors, pending, warnings }`
+- `fn::fancy::version()`：返回 `schema_version` / `validation_version`
+- `fancy_meta:main`：记录当前 schema/validation 版本
+
+校验范围：
+
+- requirement 生命周期（硬待办与 `complete` 状态冲突）
+- 钩子连续重复
+- 时间线倒退（`time.flashback=true` 例外）
+- 伏笔回收早于埋设
+- 爽点兑现早于铺垫
+- 伏笔/爽点未落地
+- 主线节点/冲突没有章节落点
+- 细纲场景过少、`must_write` 过少
+- 情绪连续平坦、黄金三章钩子不够强
+
+写入时的硬规则仍由 `DEFINE EVENT` 触发器拦截；读时校验由 `fn::fancy::validate` 统一返回。任何客户端（DSH、Hermes、CLI）都走同一份校验。
+
+## 5. MCP
+
+### 5.1 DSH 原生工具
+
+DSH 插件加载时会注册原生工具：
+
+```text
+fancy_workspace
+fancy_db
+fancy_story_read
+fancy_story_preview
+fancy_story_apply             # 自然语言写入：会弹窗要求用户确认
+fancy_story_apply_batch       # /fancy-build 阶段批量写入：不逐批弹窗
+fancy_story_export
+fancy_shared_assets
+```
+
+自然语言示例：
+
+```text
+“我如果把角色 A 和 B 的关系改成对立可行吗？有什么影响？”
+→ fancy_story_read action=impact kind=relation a=A b=B to=对立
+
+“把《测试书》改名为《新书名》”
+→ fancy_workspace action=rename project=测试书 title=新书名
+
+“把这段关系写入”
+→ fancy_story_apply（先预览，再弹窗确认）
+```
+
+### 5.2 独立 MCP server
+
+`plugins/fancy-story-builder/storydb/mcp.js` 是标准 MCP stdio server，可给 Hermes、Claude Desktop、Cursor 等使用：
+
+```bash
+FANCY_HOME=/path/to/A node plugins/fancy-story-builder/storydb/mcp.js
+```
+
+DSH 里如果要走 MCP 而不是原生工具，在 profile 的 `cordis.patch.yml` 增加：
+
+```yaml
+- insert:
+    - id: mcp-fancy
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: fancy
+        transport: stdio
+        command: node
+        args: ['/absolute/path/to/fancy-webnovel/plugins/fancy-story-builder/storydb/mcp.js']
+        env:
+          FANCY_HOME: '/absolute/path/to/A'
+```
+
+工具名会变成 `mcp__fancy__story_status`、`mcp__fancy__story_apply` 等。
+
+### 5.3 写操作二次确认
+
+自然语言写操作分两步：
+
+1. `story_preview` / `fancy_story_preview`：只做形状校验，返回 `preview` 和签名过的 `confirmation_token`。
+2. 用户确认后，`story_apply` / `fancy_story_apply` 带同一个 payload + token 才提交。
+
+- DSH 原生 `fancy_story_apply` 额外调用 `ctx.userQuestions` 弹窗确认。
+- `/fancy-build` 阶段是用户显式发起的批量创作，阶段提示词使用 `fancy_story_apply_batch`，不会逐批弹窗；自然语言改数据仍走 `fancy_story_apply`。
+- MCP 客户端没有 UI 时，工具描述要求 agent 先把预览给用户看；没有 token 的 `story_apply` 会返回 `CONFIRMATION_REQUIRED`，不会写入。
+- 只读分析（`story_impact`、`story_validate`、`story_status` 等）直接执行。
+
+## 6. 环境变量
+
+| 变量 | 作用 |
+| --- | --- |
+| `FANCY_HOME` | 指定工作区；优先于 cwd/全局指针 |
+| `FANCY_SURREAL_BIN` | 指定 `surreal` 二进制路径 |
+| `FANCY_STORY_GRAPH=0` | 仅保留给历史回归测试；新项目不要用 |
+
+工作区元数据里的时间统一使用**本机时区的 ISO-8601**，并带时区偏移，例如 `2026-11-11T17:16:08.219+08:00`。
+
+全局工作区注册表：`~/.config/fancy-webnovel/workspaces.json`（首次 bootstrap 后追加/更新，记录本机所有工作区；`/fancy-bootstrap list` 查看）。旧版单指针 `workspace.json` 仍会同步写入，供旧版本兼容。
+
+- 斜杠命令只从 **cwd / FANCY_HOME** 解析工作区，不会因为本机有另一个工作区就自动串过去。
+- MCP / 原生工具在 cwd 找不到工作区时，才使用全局注册表里最近使用的可用工作区。
+
+## 7. 旧项目
+
+新分支**不迁移**旧项目：
+
+- 不读取旧项目根目录的 `.fancy-storydb`
+- 不读取旧项目根目录的 `_novel_topic.json` 作为项目元数据
+- 旧版 `FANCY_STORY_GRAPH=0` 文件管线只作为历史测试兼容，不属于新架构
+
+旧项目如需保留，请在旧分支继续使用；新项目请从 `/fancy-bootstrap` + `/fancy-topic setup` 开始。

package/index.js

@@ -5,16 +5,16 @@ import { apply as applyTopic } from './plugins/fancy-topic/index.js';
 import { apply as applyAnalyze } from './plugins/fancy-analyze/index.js';
 import { apply as applyStoryBuilder } from './plugins/fancy-story-builder/index.js';
 import { apply as applyImport } from './plugins/fancy-import/index.js';
-import { registerSafeRmPrompt } from './lib/safe-rm.js';
+import { apply as applyExport } from './plugins/fancy-export/index.js';
+import { apply as applyDb } from './plugins/fancy-db/index.js';
+import { apply as applyProject } from './plugins/fancy-project/index.js';
+import { apply as applyMaterial } from './plugins/fancy-material/index.js';
+import { apply as applyDouyin } from './plugins/fancy-douyin/index.js';
 
-export const inject = ['commands', 'userQuestions'];
+export const name = 'fancy-webnovel';
+export const inject = ['commands', 'userQuestions', 'tools'];
 
 export async function apply(ctx) {
-  // bundle 级提示：沙箱下 rm 会挂死（见 lib/safe-rm.js）。
-  // 放在这里而不是各子插件里，是因为每个子插件都可能让模型删临时文件，
-  // 逐个加必然漏 —— 一次注册对整个 bundle 的所有会话生效。
-  registerSafeRmPrompt(ctx);
-
   await applyBootstrap(ctx);
   await applyScan(ctx);
   await applyTopic(ctx);
@@ -22,4 +22,9 @@ export async function apply(ctx) {
   await applyStoryBuilder(ctx);
   // 导入放在最后：它要用 story-builder 的模板与校验器
   await applyImport(ctx);
+  await applyExport(ctx);
+  await applyDb(ctx);
+  await applyProject(ctx);
+  await applyMaterial(ctx);
+  await applyDouyin(ctx);
 }

package/lib/atomic-write.js

@@ -0,0 +1,109 @@
+/**
+ * atomic-write.js —— 同目录临时文件 + rename 的原子写
+ *
+ * ## 为什么不用 `writeFileSync(path)`
+ *
+ * 直接覆盖写，进程写到一半被杀（OOM / 磁盘满 / 用户 Ctrl-C）会把文件截断。
+ * 对 `.fancy-deployed` 来说就是项目状态没了，对 `_novel_topic.json` 来说
+ * 就是已敲定的选题没了。rename 在同一文件系统内是原子的：要么旧内容完整，
+ * 要么新内容完整，不会出现半份文件。
+ *
+ * ## 为什么临时文件名要随机 + `wx`
+ *
+ * 旧实现用 `${file}.tmp-${process.pid}`，名字可预测。项目根是用户可写的，
+ * 攻击者可以提前放一个同名符号链接，`writeFileSync` 会跟着链接写进
+ * 项目外的文件。现在用随机后缀，并以 `wx`（O_CREAT|O_EXCL）打开：
+ * 已存在就失败，不会跟随符号链接写；rename 覆盖目标时也只会替换目录项，
+ * 不会写到符号链接指向的地方。
+ *
+ * ## 权限
+ *
+ * `.fancy-deployed` 里有 llm_wiki_token，默认 0600；普通 JSON 用 0644。
+ * 调用方按内容决定 mode。
+ */
+import {
+  chmodSync,
+  closeSync,
+  fsyncSync,
+  lstatSync,
+  openSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'fs';
+import { basename, dirname, join } from 'path';
+import { randomBytes } from 'crypto';
+
+/**
+ * 原子写文本文件。
+ *
+ * @param {string} file 目标文件（必须已存在父目录）
+ * @param {string|Buffer} content 内容
+ * @param {{mode?: number}} [opts]
+ * @returns {void}
+ */
+export function atomicWriteFile(file, content, opts = {}) {
+  const mode = typeof opts.mode === 'number' ? opts.mode : 0o644;
+  const dir = dirname(file);
+  const tmp = join(
+    dir,
+    `.${basename(file)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`
+  );
+
+  let fd = null;
+  try {
+    // wx：文件已存在（含符号链接）就失败，绝不跟随链接写
+    fd = openSync(tmp, 'wx', mode);
+    writeFileSync(fd, content, 'utf-8');
+    // 落盘后再 rename，避免 rename 成功、内容还在页缓存时断电
+    try { fsyncSync(fd); } catch { /* 某些文件系统不支持 fsync，不阻塞主流程 */ }
+    closeSync(fd);
+    fd = null;
+    try {
+      renameSync(tmp, file);
+    } catch (e) {
+      // Windows 不允许 rename 覆盖只读文件。工具/清单以 0444/0400 部署，
+      // 下次更新或同日重跑时必须先临时恢复写权限；rename 成功后文件仍是
+      // 临时文件的只读 mode。非权限错误照常抛出。
+      if (e.code !== 'EPERM' && e.code !== 'EACCES') throw e;
+      // lstat：目标若是符号链接，绝不能 chmod（会改到链接指向的文件）。
+      // 这种情况直接重试 rename；替换链接本身是安全的。
+      let oldMode = null;
+      try {
+        const st = lstatSync(file);
+        if (!st.isSymbolicLink()) oldMode = st.mode & 0o777;
+      } catch { /* 目标不存在 */ }
+      if (oldMode === null) {
+        renameSync(tmp, file);
+      } else {
+        try { chmodSync(file, 0o644); } catch { /* 由下面的 rename 报错 */ }
+        try {
+          renameSync(tmp, file);
+        } catch (e2) {
+          try { chmodSync(file, oldMode); } catch { /* ignore */ }
+          throw e2;
+        }
+      }
+    }
+  } catch (e) {
+    if (fd !== null) {
+      try { closeSync(fd); } catch { /* ignore */ }
+    }
+    // 临时文件按目标 mode 创建；Windows 上 0444 只读文件不能直接删除，
+    // 先恢复写权限再清理，避免失败路径留下只读垃圾。
+    try { chmodSync(tmp, 0o644); } catch { /* 文件可能没创建成功 */ }
+    try { unlinkSync(tmp); } catch { /* ignore */ }
+    throw e;
+  }
+}
+
+/**
+ * 原子写 JSON（2 空格缩进，不追加尾随换行，保持旧文件格式）。
+ *
+ * @param {string} file
+ * @param {unknown} data
+ * @param {{mode?: number}} [opts]
+ */
+export function atomicWriteJSON(file, data, opts = {}) {
+  atomicWriteFile(file, JSON.stringify(data, null, 2), opts);
+}

package/lib/chapter-order.js

@@ -0,0 +1,100 @@
+/**
+ * chapter-order.js —— 按（书名, 章号）排序章节列表
+ *
+ * ## 为什么需要
+ *
+ * 几处"章节列表"的顺序全是随机的：
+ *
+ *   · llm_wiki 的 querystatus 返回的 missingFiles —— 服务端怎么存的就怎么给；
+ *   · /fancy-analyze status 的"缺失检测"和"列表未找到" —— 本地算的，
+ *     遍历的是 readdirSync 的返回顺序（ext4 的目录项哈希序，不是字典序）；
+ *   · 写进 .retry 的 items —— 继承上面的顺序。
+ *
+ * 结果就是用户看到
+ *
+ *   - 全球高武/第7章-武科五大关.txt
+ *   - 全球高武/第4章-人穷万事休.txt
+ *   - 全球高武/第8章-心好痛.txt
+ *
+ * 这种顺序。对"还剩哪些章没拆"这种问题，人是按章号顺序扫的，
+ * 乱序反而让人怀疑是不是漏了、重复了。
+ *
+ * ## 排序口径
+ *
+ *   1. 书名自然序（`localeCompare(..., {numeric:true})`，"第2章" < "第10章"）；
+ *   2. 同书名内按章号数字升序；
+ *   3. 解析不出章号的排在有章号的**后面**；
+ *   4. 最后按原字符串自然序兜底，保证排序稳定且确定。
+ *
+ * 章号只认阿拉伯数字（`第7章`）。中文数字（`第七章`）在 analyze 侧
+ * 不会出现 —— split_source.js 落盘时已经把章号统一成阿拉伯数字了。
+ */
+
+/** 章号：第 N 章（N 是阿拉伯数字，允许中间有空格） */
+const CHAPTER_NUM_RE = /第\s*(\d+)\s*章/;
+
+/**
+ * 从任意文本（或带 chapter 字段的对象）里取章号。
+ *
+ * 对象形态是 `.retry` 里的 { bookName, chapter }。
+ *
+ * @param {string|{chapter?: string}} text
+ * @returns {number|null} 取不到返回 null
+ */
+export function chapterNumber(text) {
+  const raw = (text && typeof text === 'object')
+    ? (text.chapter ?? '')
+    : text;
+  const m = CHAPTER_NUM_RE.exec(String(raw || ''));
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * 取"第一个章号之前"的部分作为书名。
+ *
+ *   "全球高武/第7章-武科五大关.txt"  → "全球高武"
+ *   "全球高武第7章的ingest有缺失"    → "全球高武"
+ *
+ * @param {string} text
+ * @returns {string} 取不到章号时返回整个字符串（当兜底书名用）
+ */
+export function bookBeforeChapter(text) {
+  const s = String(text || '');
+  const m = CHAPTER_NUM_RE.exec(s);
+  // 取不到章号时不能返回空串 —— 空串比任何非空串都小，会让它排到
+  // 所有有章号的项前面，跟"解析不出的排后面"这条规则正好相反。
+  if (!m) return s.trim();
+  return s.slice(0, m.index).replace(/[/\\]+$/, '').trim();
+}
+
+/**
+ * 按（书名, 章号）排序。
+ *
+ * 不改原数组，返回新数组。
+ *
+ * @param {Array} items
+ * @param {(item:any)=>string} [getBook] - 取书名的函数，默认用"章号之前的部分"
+ * @returns {Array} 排序后的新数组
+ */
+export function sortByChapter(items, getBook = bookBeforeChapter) {
+  if (!Array.isArray(items)) return [];
+  return [...items].sort((a, b) => {
+    const numA = chapterNumber(a);
+    const numB = chapterNumber(b);
+
+    // 先分组：有章号的在前，解析不出的统一排到后面。
+    // 这一步必须排在书名比较之前 —— 否则取不到章号的项用的是兜底书名，
+    // 跟别的书一比就会插到中间去。
+    if (numA !== null && numB === null) return -1;
+    if (numA === null && numB !== null) return 1;
+
+    const bookA = String(getBook(a) || '');
+    const bookB = String(getBook(b) || '');
+    const byBook = bookA.localeCompare(bookB, undefined, { numeric: true });
+    if (byBook !== 0) return byBook;
+
+    if (numA !== null && numB !== null) return numA - numB;
+
+    return String(a).localeCompare(String(b), undefined, { numeric: true });
+  });
+}

package/lib/confirmation.js

@@ -0,0 +1,80 @@
+/**
+ * Two-phase confirmation tokens for natural-language writes.
+ *
+ * The server cannot see the chat window, so it enforces a protocol-level
+ * two-step flow: `story_preview` returns a signed token over the exact payload;
+ * `story_apply` refuses to write without it. The tool description instructs the
+ * agent to show the preview to the user and only pass the token after an
+ * explicit confirmation. DSH's native adapter adds a real UI confirmation on
+ * top of this.
+ */
+
+import crypto from 'crypto';
+import { readSecrets, readWorkspace } from './workspace.js';
+
+const TTL_MS = 10 * 60 * 1000;
+
+function secretFor(workspace) {
+  try {
+    const secrets = readSecrets(workspace);
+    if (secrets.confirmation_secret) return secrets.confirmation_secret;
+    // Fall back to the SurrealDB root password: it is already workspace-local
+    // and 0600. Never expose it in the token itself.
+    if (secrets.surreal?.password) return 'surreal:' + secrets.surreal.password;
+  } catch { /* ignore */ }
+  return 'fancy-confirmation-fallback';
+}
+
+function canonical(value) {
+  if (value === null || value === undefined) return 'null';
+  if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']';
+  if (typeof value === 'object') {
+    return '{' + Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+
+function sign(secret, body) {
+  return crypto.createHmac('sha256', secret).update(body).digest('base64url');
+}
+
+export function createConfirmation(workspace, project, payload) {
+  const body = Buffer.from(JSON.stringify({
+    v: 1,
+    workspace: workspace,
+    project: project.project_id,
+    exp: Date.now() + TTL_MS,
+    payload,
+  }), 'utf8').toString('base64url');
+  const token = body + '.' + sign(secretFor(workspace), body);
+  return {
+    confirmation_token: token,
+    expires_at: new Date(Date.now() + TTL_MS).toISOString(),
+    ttl_seconds: Math.floor(TTL_MS / 1000),
+  };
+}
+
+export function verifyConfirmation(workspace, project, token, payload) {
+  const text = String(token || '');
+  const idx = text.lastIndexOf('.');
+  if (idx <= 0) return { ok: false, reason: 'malformed' };
+  const body = text.slice(0, idx);
+  const signature = text.slice(idx + 1);
+  const expected = sign(secretFor(workspace), body);
+  if (signature.length !== expected.length
+    || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+    return { ok: false, reason: 'signature' };
+  }
+  let decoded;
+  try {
+    decoded = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+  } catch {
+    return { ok: false, reason: 'body' };
+  }
+  if (decoded.v !== 1) return { ok: false, reason: 'version' };
+  if (decoded.workspace !== workspace) return { ok: false, reason: 'workspace' };
+  if (decoded.project !== project.project_id) return { ok: false, reason: 'project' };
+  if (Number(decoded.exp) < Date.now()) return { ok: false, reason: 'expired' };
+  if (canonical(decoded.payload) !== canonical(payload)) return { ok: false, reason: 'payload' };
+  return { ok: true };
+}