@jjh32456/dsh-longlive 1.6.8 → 1.8.0

package/src/ui/panel-api.js

@@ -0,0 +1,367 @@
+// src/ui/panel-api.js — M2-F/M2-G 装配层（宿主接线 + HTTP 分派）
+//
+// 把权限门（panel-auth）、完整性（panel-integrity）、审计链（actions/audit）、
+// evidence 写路径（actions/evidence）、动作面（ui/actions）与 16 条只读路由
+// （ui/routes-readonly）装配成一个可测试的门面：
+//   - createPanelApi(options) 纯内存/文件装配，契约测试直接驱动；
+//   - registerPanelApiRoutes(ctx, options) 通过 ctx.inject(['webServer']) 注册
+//     16 条只读路由 + 5 条动作路由（POST preview/apply/undo、GET actions/audit）
+//     + G3 distill 详情前缀路由。宿主没有 Web server 时注册失败只 warn，不阻塞加载。
+//
+// 开关：由 src/index.js 读 `memoryV2.enabled`（默认 false）决定是否调用本模块；
+// 未开启时本模块不注册任何路由、不创建任何文件。
+
+import os from 'node:os';
+import path from 'node:path';
+
+import { AuditError } from '../actions/audit.js';
+import { createAuditLog } from '../actions/audit.js';
+import { EvidenceError } from '../actions/evidence.js';
+import { createEvidenceWriter } from '../actions/evidence.js';
+import { createEventsIndexReader } from '../memory/event-index.js';
+import { createActionService, PanelActionError } from './actions.js';
+import { createPanelAuth } from './panel-auth.js';
+import { createIntegrityGuard } from './panel-integrity.js';
+import {
+  DISTILL_DETAIL_PREFIX,
+  READONLY_ROUTES,
+  createReadonlyRouter,
+  registerReadonlyRoutes,
+} from './routes-readonly.js';
+
+export const ACTIONS_BODY_LIMIT = 64 * 1024;
+export const ACTION_ROUTE_PATHS = Object.freeze([
+  '/api/longlive/actions/preview',
+  '/api/longlive/actions/apply',
+  '/api/longlive/actions/undo',
+  '/api/longlive/actions',
+  '/api/longlive/audit',
+]);
+
+/** Host DSH home (never a machine path literal in this published file). */
+export function dshHomeDir() {
+  const raw = process.env.DSH_HOME;
+  if (typeof raw === 'string' && raw.trim() !== '') return path.resolve(raw.trim());
+  return path.join(os.homedir(), '.dsh');
+}
+
+/**
+ * Resolve the installed panel package root.
+ *
+ * P1-1(2): the default lives **outside** the memory root (`<DSH_HOME>/longlive-panel`)
+ * so a model/agent that can write memoryRoot cannot also own the signed manifest
+ * directory. Host installers may override via option/config; Gate-2 wires the
+ * real installed path.
+ */
+function defaultPanelRoot(memoryRoot, options) {
+  if (typeof options.panelRoot === 'string' && options.panelRoot.trim() !== '') return path.resolve(options.panelRoot);
+  if (typeof options.config?.memoryV2?.panelRoot === 'string' && options.config.memoryV2.panelRoot.trim() !== '') {
+    return path.resolve(options.config.memoryV2.panelRoot);
+  }
+  const candidate = path.join(dshHomeDir(), 'longlive-panel');
+  const resolvedMemory = memoryRoot !== '' ? path.resolve(memoryRoot) : null;
+  if (resolvedMemory !== null
+    && (candidate === resolvedMemory || candidate.startsWith(`${resolvedMemory}${path.sep}`))) {
+    // Never fall back inside memoryRoot; use the OS-local app data dir instead.
+    const localAppData = process.env.LOCALAPPDATA;
+    if (typeof localAppData === 'string' && localAppData.trim() !== '') {
+      return path.join(localAppData.trim(), 'dsh-longlive', 'panel');
+    }
+    return path.join(os.tmpdir(), 'dsh-longlive-panel');
+  }
+  return candidate;
+}
+
+/**
+ * Assemble the whole panel API (no host wiring).
+ * @param {object} options
+ * @param {string} options.memoryRoot
+ * @param {string} [options.panelRoot] installed panel package root (integrity manifest base)
+ * @param {() => Date} [options.now]
+ * @param {(size:number)=>Buffer} [options.randomBytes] CSPRNG seam
+ * @param {boolean} [options.panelPresent] false simulates uninstalled panel
+ * @param {() => object} [options.flagsSnapshot]
+ * @param {(query:object)=>object} [options.eventsReader]
+ * @param {(anchorId:string)=>object|null} [options.anchorResolver]
+ */
+export function createPanelApi(options = {}) {
+  const memoryRoot = String(options.memoryRoot ?? '');
+  const now = typeof options.now === 'function' ? options.now : () => new Date();
+  const monoNow = typeof options.monoNow === 'function' ? options.monoNow : undefined;
+  const auth = createPanelAuth({
+    now,
+    // P0-1: host-injected capability secret (profile-private env/file); absent => fail closed.
+    hostSecret: options.hostSecret,
+    monoNow,
+    randomBytes: options.randomBytes,
+    panelPresent: options.panelPresent,
+    panelIntegrityKey: options.panelIntegrityKey,
+  });
+  const panelRoot = defaultPanelRoot(memoryRoot, options);
+  const integrity = createIntegrityGuard({
+    panelRoot,
+    now,
+    signKey: auth.panelIntegrityKeyBytes(),
+  });
+  const auditKey = auth.auditKeyBytes();
+  const audit = createAuditLog({ memoryRoot, auditKey, now });
+  const evidence = createEvidenceWriter({ memoryRoot, auditKey, now });
+  const actions = createActionService({
+    memoryRoot,
+    auth,
+    auditKey,
+    integrity,
+    audit,
+    evidence,
+    now,
+    monoNow,
+    clockToleranceMs: options.clockToleranceMs,
+  });
+  const readonly = createReadonlyRouter({
+    memoryRoot,
+    auth,
+    auditKey,
+    integrity,
+    now,
+    flagsSnapshot: options.flagsSnapshot,
+    // M2-A: #11 events route reads the FTS5 event index when it has been built
+    // (`.longlive/index/events.db`); without an index the honest empty state
+    // (`present:false` + E_EVENTS_INDEX_NOT_BUILT) is returned unchanged.
+    eventsReader: options.eventsReader ?? createEventsIndexReader({ memoryRoot, now }),
+    anchorResolver: options.anchorResolver,
+  });
+
+  function handleReadonly(request = {}) {
+    return readonly.handle(request);
+  }
+
+  function actionResponse(status, body) {
+    return { status, body, headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' } };
+  }
+
+  function actionErrorResponse(error) {
+    if (error instanceof PanelActionError) {
+      return actionResponse(error.status, {
+        ok: false,
+        error: { code: error.code, message: error.message, ...(error.details !== undefined ? { details: error.details } : {}) },
+      });
+    }
+    if (error instanceof AuditError) {
+      return actionResponse(500, { ok: false, error: { code: error.code, message: error.message, ...(error.details !== undefined ? { details: error.details } : {}) } });
+    }
+    if (error instanceof EvidenceError) {
+      return actionResponse(error.status ?? 403, { ok: false, error: { code: error.code, message: error.message } });
+    }
+    return actionResponse(500, { ok: false, error: { code: 'E_ACTION_FAILED', message: error?.message ?? String(error) } });
+  }
+
+  /**
+   * Handle one in-process action request.
+   * @param {{method?:string, path:string, headers?:object, body?:object, source?:string, actorKind?:string, rawBodySize?:number}} request
+   */
+  function handleAction(request = {}) {
+    const method = String(request.method ?? 'POST').toUpperCase();
+    let url;
+    try {
+      url = new URL(String(request.path ?? ''), 'http://longlive.local');
+    } catch {
+      return actionResponse(400, { ok: false, error: { code: 'E_PATH', message: '非法请求路径。' } });
+    }
+    const query = {};
+    for (const [key, value] of url.searchParams.entries()) {
+      query[key] = /^\d+$/.test(value) ? Number.parseInt(value, 10) : value;
+    }
+    const gateRequest = { source: request.source ?? 'http', headers: request.headers ?? {}, actorKind: request.actorKind ?? 'host' };
+    const body = request.body !== null && typeof request.body === 'object' && !Array.isArray(request.body) ? request.body : {};
+    try {
+      if (url.pathname === '/api/longlive/actions/preview') {
+        if (method !== 'POST') return actionResponse(405, { ok: false, error: { code: 'E_METHOD', message: 'preview 只支持 POST。' } });
+        const size = Number.isInteger(request.rawBodySize) ? request.rawBodySize : Buffer.byteLength(JSON.stringify(body));
+        if (size > ACTIONS_BODY_LIMIT) return actionResponse(413, { ok: false, error: { code: 'E_BODY_TOO_LARGE', message: `请求体超过 ${ACTIONS_BODY_LIMIT} 字节。` } });
+        return actionResponse(200, actions.preview(gateRequest, body));
+      }
+      if (url.pathname === '/api/longlive/actions/apply') {
+        if (method !== 'POST') return actionResponse(405, { ok: false, error: { code: 'E_METHOD', message: 'apply 只支持 POST。' } });
+        const size = Number.isInteger(request.rawBodySize) ? request.rawBodySize : Buffer.byteLength(JSON.stringify(body));
+        if (size > ACTIONS_BODY_LIMIT) return actionResponse(413, { ok: false, error: { code: 'E_BODY_TOO_LARGE', message: `请求体超过 ${ACTIONS_BODY_LIMIT} 字节。` } });
+        return actionResponse(200, actions.apply(gateRequest, body));
+      }
+      if (url.pathname === '/api/longlive/actions/undo') {
+        if (method !== 'POST') return actionResponse(405, { ok: false, error: { code: 'E_METHOD', message: 'undo 只支持 POST。' } });
+        const size = Number.isInteger(request.rawBodySize) ? request.rawBodySize : Buffer.byteLength(JSON.stringify(body));
+        if (size > ACTIONS_BODY_LIMIT) return actionResponse(413, { ok: false, error: { code: 'E_BODY_TOO_LARGE', message: `请求体超过 ${ACTIONS_BODY_LIMIT} 字节。` } });
+        return actionResponse(200, actions.undo(gateRequest, body));
+      }
+      if (url.pathname === '/api/longlive/actions') {
+        if (method !== 'GET') return actionResponse(405, { ok: false, error: { code: 'E_METHOD', message: 'actions 列表只支持 GET。' } });
+        return actionResponse(200, actions.listActions(gateRequest, query));
+      }
+      if (url.pathname === '/api/longlive/audit') {
+        if (method !== 'GET') return actionResponse(405, { ok: false, error: { code: 'E_METHOD', message: 'audit 只支持 GET。' } });
+        return actionResponse(200, actions.readAudit(gateRequest, query));
+      }
+      return actionResponse(404, { ok: false, error: { code: 'E_ROUTE_UNKNOWN', message: `未知动作路由：${url.pathname}` } });
+    } catch (error) {
+      return actionErrorResponse(error);
+    }
+  }
+
+  return {
+    memoryRoot,
+    panelRoot,
+    auth,
+    integrity,
+    audit,
+    evidence,
+    actions,
+    readonly,
+    handleReadonly,
+    handleAction,
+    /** Host-internal channel: mint a one-shot capability token for the panel. */
+    issueCapability: (opts = {}) => auth.issue(opts),
+  };
+}
+
+const warned = new Set();
+function warnOnce(key, error) {
+  if (warned.has(key)) return;
+  warned.add(key);
+  try {
+    console.warn(`[longlive] ${key}: ${error?.stack ?? error?.message ?? String(error)}`);
+  } catch {
+    /* logging must never break activation */
+  }
+}
+
+function makeResponder(handler) {
+  return (req, res) => {
+    let body = {};
+    (async () => {
+      if (req?.method === 'POST') {
+        const chunks = [];
+        let size = 0;
+        let tooLarge = false;
+        await new Promise((resolve) => {
+          req.on('data', (chunk) => {
+            if (tooLarge) return;
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            size += buffer.length;
+            if (size > ACTIONS_BODY_LIMIT) {
+              tooLarge = true;
+              resolve();
+              return;
+            }
+            chunks.push(buffer);
+          });
+          req.on('end', resolve);
+          req.on('error', resolve);
+        });
+        if (tooLarge) {
+          const payload = JSON.stringify({ ok: false, error: { code: 'E_BODY_TOO_LARGE', message: `请求体超过 ${ACTIONS_BODY_LIMIT} 字节。` } });
+          try {
+            res.writeHead(413, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(payload) });
+            res.end(payload);
+          } catch {
+            /* peer gone */
+          }
+          return;
+        }
+        try {
+          body = chunks.length === 0 ? {} : JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        } catch {
+          body = {};
+        }
+      }
+      const host = String(req?.headers?.host ?? 'longlive.local');
+      const verdict = handler({
+        method: req?.method ?? 'GET',
+        path: `http://${host}${String(req?.url ?? '/')}`,
+        headers: req?.headers ?? {},
+        body,
+        source: 'http',
+      });
+      const payload = JSON.stringify(verdict.body ?? {});
+      try {
+        res.writeHead(verdict.status, {
+          'content-type': 'application/json; charset=utf-8',
+          'cache-control': 'no-store',
+          ...(verdict.headers ?? {}),
+          'content-length': Buffer.byteLength(payload),
+        });
+        res.end(payload);
+      } catch {
+        try {
+          res.destroy?.();
+        } catch {
+          /* peer gone */
+        }
+      }
+    })().catch((error) => warnOnce('panel api responder failed', error));
+  };
+}
+
+/**
+ * Register the panel API routes on the host Web server (memoryV2.enabled only).
+ * @returns {Promise<{api:object|null, registered:number}>} resolved after inject callback
+ *   is set up (the actual registration happens when the web server is available).
+ */
+export function registerPanelApiRoutes(ctx, options = {}) {
+  if (typeof ctx?.inject !== 'function') return false;
+  try {
+    ctx.inject(['webServer'], (webCtx) => {
+      const webServer = webCtx?.webServer;
+      if (webServer === undefined || typeof webServer.register !== 'function') return;
+      let api;
+      try {
+        api = createPanelApi(options);
+      } catch (error) {
+        warnOnce('panel api create failed', error);
+        return;
+      }
+      const readonlyResponder = makeResponder(api.handleReadonly);
+      const actionResponder = makeResponder(api.handleAction);
+      let registered = 0;
+      const register = (registration, label) => {
+        try {
+          const dispose = webServer.register(registration);
+          registered += 1;
+          if (typeof dispose === 'function' && typeof webCtx.effect === 'function') {
+            try {
+              webCtx.effect(() => () => dispose(), `longlive: panel api ${label}`);
+            } catch {
+              /* fake context without an effect scope */
+            }
+          }
+        } catch (error) {
+          warnOnce(`panel api route ${label} registration failed`, error);
+        }
+      };
+      for (const route of READONLY_ROUTES) {
+        register(
+          route.dynamic
+            ? { kind: 'prefix', path: route.path.replace(/\/:anchorId$/, '/'), handler: readonlyResponder }
+            : { kind: 'exact', path: route.path, handler: readonlyResponder },
+          `readonly ${route.id}`,
+        );
+      }
+      register({ kind: 'prefix', path: DISTILL_DETAIL_PREFIX, handler: readonlyResponder }, 'distill detail');
+      for (const routePath of ACTION_ROUTE_PATHS) {
+        register({ kind: 'exact', path: routePath, handler: actionResponder }, `action ${routePath}`);
+      }
+      if (typeof webCtx.effect === 'function') {
+        try {
+          webCtx.effect(() => () => { api = null; }, 'longlive: panel api scope');
+        } catch {
+          /* fake context */
+        }
+      }
+      warnOnce('panel api registration summary', { registered });
+    });
+    return true;
+  } catch (error) {
+    warnOnce('panel api inject failed', error);
+    return false;
+  }
+}
+
+export { registerReadonlyRoutes };

package/src/ui/panel-auth.js

@@ -0,0 +1,251 @@
+// src/ui/panel-auth.js — M2-G 权限门（N38 / §12.2）
+//
+// 两个凭据**只存在于宿主进程内存**：capability secret 必须由宿主进程注入
+// （profile 私有文件 / 宿主环境变量 DSH_LONGLIVE_PANEL_SECRET），审计 key boot 时 32B CSPRNG 生成：
+//   - panelCap: 签发面板能力令牌的 HMAC key；
+//   - auditKey: HMAC 链式审计 / evidence 签名 key。
+// 磁盘上没有任何凭据文件，也没有任何 HTTP 路由能把它们读出来：
+// 面板经宿主内部通道拿到的是**短 TTL 一次性 nonce 能力令牌**
+//   capability = HMAC(panelCap, `${nonce}|${pid}|${windowNonce}|${sessionNonce}`)
+// 请求头 `x-longlive-cap` + `x-longlive-nonce`；服务端内存 nonce 注册表单次消费，TTL 默认 60s。
+//
+// 权限三门（HTTP / 工具 / CLI）走同一个 {@link actionGate}：
+//   - subagent 一律 403 `E_SUBAGENT_FORBIDDEN`（先于 token 校验）；
+//   - 面板未装 → 401 `E_PANEL_ABSENT`；
+//   - 无令牌 → 401 `E_NO_CAP`；错令牌 → 401 `E_CAP_INVALID`；nonce 已用/过期 → 401 `E_CAP_CONSUMED/E_CAP_EXPIRED`。
+// actor 由令牌绑定为 `host`，请求体里的 actor 字段一律忽略（绝不信任请求体）。
+
+import crypto from 'node:crypto';
+
+export const CAP_TTL_MS = 60_000;
+export const CAP_HEADER = 'x-longlive-cap';
+export const NONCE_HEADER = 'x-longlive-nonce';
+export const ACTOR = 'host';
+
+/** Errors carry `{code,status}` so the HTTP layer and the contract tests agree. */
+export class PanelAuthError extends Error {
+  constructor(code, message, status = 401, details = undefined) {
+    super(message);
+    this.name = 'PanelAuthError';
+    this.code = code;
+    this.status = status;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+export function hmacHex(key, text) {
+  return crypto.createHmac('sha256', key).update(String(text), 'utf8').digest('hex');
+}
+
+function normalizeHeaderValue(value) {
+  if (Array.isArray(value)) return value.length > 0 ? String(value[0]) : '';
+  return value === undefined || value === null ? '' : String(value);
+}
+
+function headerOf(headers, name) {
+  if (!headers || typeof headers !== 'object') return '';
+  const lower = name.toLowerCase();
+  if (headers[lower] !== undefined) return normalizeHeaderValue(headers[lower]);
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === lower) return normalizeHeaderValue(value);
+  }
+  return '';
+}
+
+/**
+ * Create the in-memory credential holder + permission gate.
+ *
+ * @param {object} [options]
+ * @param {() => Date} [options.now] clock seam for tests.
+ * @param {(size:number)=>Buffer} [options.randomBytes] CSPRNG seam for tests.
+ * @param {boolean} [options.panelPresent] false simulates "panel uninstalled".
+ * @returns auth facade (credentials intentionally not enumerable).
+ */
+export function createPanelAuth(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => new Date();
+  const randomBytes = typeof options.randomBytes === 'function' ? options.randomBytes : crypto.randomBytes;
+  // Monotonic clock: capability TTL must not stretch when the wall clock rolls
+  // back (N38: TTL ≤60s is enforced against elapsed process time).
+  const monoNow = typeof options.monoNow === 'function' ? options.monoNow : () => process.uptime() * 1000;
+  const panelPresent = options.panelPresent !== false;
+  // P0-1: capability secret is HOST-INJECTED. A module that merely imports this
+  // file cannot mint a usable capability: without the host secret, issue()/gate
+  // fail closed with E_PANEL_HOST_ONLY. The secret is never written to disk.
+  function decodeSecret(value) {
+    if (Buffer.isBuffer(value) && value.length >= 32) return Buffer.from(value);
+    if (typeof value === 'string' && value.trim() !== '') {
+      const raw = value.trim();
+      const hex = /^[0-9a-f]{64,}$/i.test(raw) ? Buffer.from(raw, 'hex') : null;
+      if (hex && hex.length >= 32) return hex;
+      try {
+        const b64 = Buffer.from(raw, 'base64');
+        if (b64.length >= 32) return b64;
+      } catch {
+        /* fallthrough */
+      }
+    }
+    return null;
+  }
+  const hostSecret = decodeSecret(options.hostSecret) ?? decodeSecret(process.env.DSH_LONGLIVE_PANEL_SECRET);
+  const hostCapable = hostSecret !== null;
+  const capabilitySecret = hostSecret ?? randomBytes(32); // host memory only
+  const auditKey = randomBytes(32); // host memory only
+  // R8/P1-1: independent in-memory key that anchors the panel integrity manifest.
+  // Tests may inject a fixed Buffer through options.panelIntegrityKey (host-side
+  // seam only); production always generates a fresh boot-scoped key.
+  const panelIntegrityKey = Buffer.isBuffer(options.panelIntegrityKey) && options.panelIntegrityKey.length >= 16
+    ? Buffer.from(options.panelIntegrityKey)
+    : randomBytes(32);
+  /** nonce → { pid, windowNonce, sessionNonce, expiresAt, consumed } */
+  const nonces = new Map();
+  const stats = { issued: 0, verified: 0, rejected: 0, consumedReplays: 0 };
+
+  function currentMs() {
+    return now().getTime();
+  }
+
+  function prune(nowMono) {
+    for (const [nonce, entry] of nonces) {
+      if (entry.consumed || nowMono - entry.expiresMono > CAP_TTL_MS) nonces.delete(nonce);
+    }
+  }
+
+  /**
+   * Host-internal channel mints a one-shot capability token for the panel.
+   * Never exposed over HTTP; never written to disk.
+   */
+  function issue(opts = {}) {
+    if (!hostCapable) {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_PANEL_HOST_ONLY', '能力签发只允许宿主进程（host-injected secret 缺失）：外部 import 不得发 cap。', 403);
+    }
+    const pid = Number.isInteger(opts.pid) ? opts.pid : process.pid;
+    const windowNonce = typeof opts.windowNonce === 'string' && opts.windowNonce !== '' ? opts.windowNonce : 'boot';
+    const sessionNonce = typeof opts.sessionNonce === 'string' ? opts.sessionNonce : '';
+    const ttlMs = Number.isFinite(opts.ttlMs) && opts.ttlMs > 0 ? Math.min(opts.ttlMs, CAP_TTL_MS) : CAP_TTL_MS;
+    const nonce = randomBytes(16).toString('hex');
+    const mac = hmacHex(capabilitySecret, `${nonce}|${pid}|${windowNonce}|${sessionNonce}`);
+    const token = `${nonce}.${mac}`;
+    const nowMs = currentMs();
+    const nowMono = monoNow();
+    prune(nowMono);
+    nonces.set(nonce, {
+      pid,
+      windowNonce,
+      sessionNonce,
+      expiresAt: nowMs + ttlMs,
+      expiresMono: nowMono + ttlMs,
+      consumed: false,
+    });
+    stats.issued += 1;
+    return { token, nonce, expiresAt: new Date(nowMs + ttlMs).toISOString(), actor: ACTOR };
+  }
+
+  function verifyToken(headers) {
+    if (!panelPresent) {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_PANEL_ABSENT', '面板未安装：所有面板接口暂停（长活核心不受影响）。');
+    }
+    const token = headerOf(headers, CAP_HEADER);
+    const nonceHeader = headerOf(headers, NONCE_HEADER);
+    if (token === '') {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_NO_CAP', '缺少能力令牌（x-longlive-cap）：动作与只读接口一律拒绝。');
+    }
+    const dot = token.indexOf('.');
+    if (dot <= 0 || dot === token.length - 1) {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_CAP_INVALID', '能力令牌格式非法。');
+    }
+    const tokenNonce = token.slice(0, dot);
+    const mac = token.slice(dot + 1);
+    if (nonceHeader !== '' && nonceHeader !== tokenNonce) {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_CAP_INVALID', '能力令牌与 nonce 请求头不匹配。');
+    }
+    const entry = nonces.get(tokenNonce);
+    if (entry === undefined) {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_CAP_CONSUMED', 'nonce 不存在或已被消费（能力令牌一次性）。');
+    }
+    if (entry.consumed) {
+      stats.consumedReplays += 1;
+      stats.rejected += 1;
+      throw new PanelAuthError('E_CAP_CONSUMED', 'nonce 已被消费（重放被拒绝）。');
+    }
+    // TTL is enforced on the monotonic clock: a wall-clock rollback cannot
+    // extend a capability token's lifetime.
+    if (monoNow() > entry.expiresMono) {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_CAP_EXPIRED', '能力令牌已过期（TTL ≤60s）。');
+    }
+    const expected = hmacHex(
+      capabilitySecret,
+      `${tokenNonce}|${entry.pid}|${entry.windowNonce}|${entry.sessionNonce}`,
+    );
+    const expectedBuf = Buffer.from(expected, 'utf8');
+    const macBuf = Buffer.from(mac, 'utf8');
+    // EA-12: timingSafeEqual throws RangeError on unequal lengths -> compare lengths first.
+    if (expectedBuf.length !== macBuf.length || !crypto.timingSafeEqual(expectedBuf, macBuf)) {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_CAP_INVALID', '能力令牌验签失败。');
+    }
+    entry.consumed = true;
+    stats.verified += 1;
+    return { ok: true, actor: ACTOR, actorId: ACTOR, pid: entry.pid, nonce: tokenNonce };
+  }
+
+  /**
+   * The single permission door for HTTP routes, tools and the CLI.
+   * `source` only changes the audit label — the checks are identical by design.
+   * The request body is never consulted for identity.
+   */
+  function actionGate({ source = 'http', headers = {}, actorKind = 'host' } = {}) {
+    if (!hostCapable) {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_PANEL_HOST_ONLY', '权限门只允许宿主进程（host-injected secret 缺失）。', 403);
+    }
+    if (source !== 'http' && source !== 'tool' && source !== 'cli') {
+      throw new PanelAuthError('E_SOURCE_INVALID', `未知入口：${source}`, 400);
+    }
+    if (actorKind === 'subagent') {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_SUBAGENT_FORBIDDEN', 'subagent 不具有面板动作权限（一律 403）。', 403);
+    }
+    const verdict = verifyToken(headers);
+    // P1-2: actor is injected by the host (token-bound); request bodies are never
+    // consulted. A verdict with no actor is refused instead of defaulting silently.
+    if (typeof verdict?.actor !== 'string' || verdict.actor === '') {
+      stats.rejected += 1;
+      throw new PanelAuthError('E_ACTOR_REQUIRED', 'actor 必须由宿主注入（令牌绑定），缺省拒绝。', 401);
+    }
+    return { ...verdict, source };
+  }
+
+  /** Host-internal accessor for the audit/evidence signer. Not exposed to the panel. */
+  function auditKeyBytes() {
+    return auditKey;
+  }
+
+  /** Host-internal accessor for the R8 manifest HMAC anchor (boot-scoped). */
+  function panelIntegrityKeyBytes() {
+    return panelIntegrityKey;
+  }
+
+  function hasCapabilitySecret() {
+    return hostCapable && Buffer.isBuffer(capabilitySecret) && capabilitySecret.length >= 32;
+  }
+
+  return {
+    panelPresent,
+    hostCapable,
+    issue,
+    verifyToken,
+    actionGate,
+    auditKeyBytes,
+    panelIntegrityKeyBytes,
+    hasCapabilitySecret,
+    stats,
+    CAP_TTL_MS,
+  };
+}