@dshtrading/authority 0.0.0-stage → 0.6.1

package/LICENSE

@@ -0,0 +1,75 @@
+Copyright (c) 2026 zhu1090093659 (dsh-trading)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/lib/index.d.ts

@@ -0,0 +1,198 @@
+//#region src/index.d.ts
+/** 覆盖授权平面根目录的环境变量（**必须显式配置**；没有默认位置）。 */
+declare const AUTHORITY_DIR_ENV = "DSH_TRADING_AUTHORITY_DIR";
+/** 可选：平面必须归这个 uid（「允许的属主」钉死；缺省只要求 ≠ 运行 uid）。 */
+declare const AUTHORITY_OWNER_UID_ENV = "DSH_TRADING_AUTHORITY_OWNER_UID";
+/** 开发形态显式 opt-in（名字里带 dev）：同 uid 平面放行，但每次判定留痕。 */
+declare const AUTHORITY_DEV_ENV = "DSH_TRADING_AUTHORITY_DEV_SAME_UID";
+/** 运营 CLI 用：声明 trading agent 运行在哪个 uid 下（平面归它就是自铸）。 */
+declare const AUTHORITY_AGENT_UID_ENV = "DSH_TRADING_AUTHORITY_AGENT_UID";
+/** 人工签署的实盘授权文件名。 */
+declare const GRANT_FILENAME = "live-trading.grant.json";
+/** 受信任公钥目录文件名。 */
+declare const TRUSTED_KEYS_FILENAME = "trusted-keys.json";
+/** 授权文档协议版本（逐帧校验，未来换格式时旧文档必须被拒而不是被猜）。 */
+declare const GRANT_PROTOCOL_VERSION = 1;
+interface GrantPayload {
+  /** 恒为 true；false 或缺席都按「不是授权」拒绝（不可表达即不可自我扩权）。 */
+  liveTrading: boolean;
+  /** ISO-8601 签发时刻。 */
+  issuedAt: string;
+  /** ISO-8601 到期时刻；**必填**（设计文档 §12.3：授权带到期，续签 = 重新签名）。 */
+  expiresAt: string;
+  /** 签署人标识（自由文本，只用于审计与展示）。 */
+  operator?: string;
+  /** 备注（自由文本，只用于审计与展示）。 */
+  note?: string;
+  /**
+   * 开发形态标记（在**签名覆盖的 payload 里**）：由运营 CLI 在 dev 平面签出。
+   * 读取端没有同一个显式 opt-in 时拒绝它 —— 开发形态的授权不会变成生产授权。
+   */
+  dev?: boolean;
+}
+interface TrustedKey {
+  keyId: string;
+  alg: 'ed25519';
+  publicKeyPem: string;
+}
+/** 拒绝原因（机器可读；新增取值必须同时更新用例的期望表）。 */
+type LiveTradingDenyReason = 'granted' | 'dir-not-configured' | 'plane-not-isolated' | 'dev-grant-not-accepted' | 'no-grant-document' | 'no-trusted-keys' | 'malformed' | 'unknown-key' | 'bad-signature' | 'not-a-grant' | 'expired' | 'not-yet-valid';
+interface GrantVerification {
+  ok: boolean;
+  reason: LiveTradingDenyReason;
+  detail: string;
+  payload?: GrantPayload;
+  keyId?: string;
+}
+/** 平面目录的来源：显式选项 / 环境变量 / 未配置（未配置 ⇒ 拒绝）。 */
+type AuthorityDirSource = 'option' | 'env' | 'unset';
+interface AuthorityLocation {
+  /** 未显式配置时是 undefined —— 本模块没有默认位置。 */
+  dir: string | undefined;
+  source: AuthorityDirSource;
+}
+/** 平面隔离检查的机器可读结论。 */
+type PlaneIsolationCode =
+/** 归另一个 uid、无 group/other 写位、祖先链干净。 */
+'isolated' |
+/** 显式 dev opt-in：跳过检查（留痕见 devMode）。 */
+'dev-opt-in' |
+/** 目录还不存在（还谈不上隔离；判定会继续走到「没有信任锚」）。 */
+'dir-missing' |
+/** 平台没有 uid 语义（process.geteuid 不可用）⇒ 无法证明隔离。 */
+'no-uid-semantics' |
+/** 平面目录/文件归运行 uid 所有。 */
+'owner-is-agent-uid' |
+/** 平面目录/文件属主不是显式配置的「允许的属主」。 */
+'owner-not-allowed' |
+/** 「允许的属主」被配成了运行 uid 自身（等于没有边界）。 */
+'configured-owner-is-agent-uid' |
+/** 平面目录/文件带 group/other 写位。 */
+'group-or-other-writable' |
+/** 祖先目录归运行 uid 所有，或对 group/other 可写且无 sticky 位。 */
+'ancestor-agent-writable';
+interface PlaneIsolationReport {
+  isolated: boolean;
+  code: PlaneIsolationCode;
+  detail: string;
+  /** 本次判定是否在显式开发形态下做出（生产必须为 false）。 */
+  devMode: boolean;
+}
+interface LiveTradingDecision extends GrantVerification {
+  /** 授权平面是否授予（与 allowed 的区别：镜像可以再收紧一层）。 */
+  granted: boolean;
+  /** 最终判定：镜像与授权平面取合取（两个都为真才放行）。 */
+  allowed: boolean;
+  /** preset 资产里的镜像值（非权威，只能收紧）。 */
+  mirror: boolean;
+  /** 镜像为 true 而授权平面未授予 —— 资产被改写或与平面漂移，必须可见。 */
+  mismatch: boolean;
+  /** 判定所用的平面目录；未显式配置时 undefined（没有默认位置，见 authorityDir）。 */
+  dir: string | undefined;
+  /** 平面目录的来源。 */
+  dirSource: AuthorityDirSource;
+  /** 判定是否在显式开发形态下做出。 */
+  devMode: boolean;
+  /** 平面隔离检查结论；目录未配置时 undefined。 */
+  isolation: PlaneIsolationReport | undefined;
+}
+interface AuthorityOptions {
+  /** 显式指定平面目录（测试与 CLI 用）；缺省见 authorityDir —— 没有默认位置。 */
+  dir?: string;
+  /** 环境变量映射，缺省 process.env。 */
+  env?: Record<string, string | undefined>;
+  /** 判定时刻（毫秒），缺省 Date.now()；测试用来固定时间轴。 */
+  now?: number;
+  /**
+   * 判定进程的 euid，缺省 process.geteuid()。测试用来**模拟生产形态**（平面归另一个
+   * uid、进程跑在 agent uid 下）——本机同 uid 时无法真实制造这种文件属主。
+   *
+   * 只在有 uid 语义的平台上有效：见 uidSemantics。
+   */
+  euid?: number;
+  /**
+   * 本平台是否有 uid 语义（`process.geteuid` 可用）；缺省 hasUidSemantics()。
+   *
+   * 测试用 false 表达「没有 uid 语义的平台（Windows）」。此时注入 euid 也不构成隔离证据
+   * —— Windows 的 `fs.Stats.uid` 恒为 0、`mode` 是按只读属性合成的，拿它们比对只会把
+   * 「无从证明」说成某个具体结论。
+   */
+  uidSemantics?: boolean;
+}
+/** 显式 opt-in 的开发形态（名字里带 dev，且值必须是精确的 '1'）。 */
+declare function devOptIn(env?: Record<string, string | undefined>): boolean;
+/** 当前进程的 euid；没有 uid 语义的平台（Windows）返回 undefined ⇒ 读取端按未隔离拒绝。 */
+declare function processEuid(): number | undefined;
+/**
+ * 本平台是否有 uid 语义（`process.geteuid` 可用）——属主检查的**能力前提**。
+ *
+ * Windows 上没有：`fs.Stats.uid` 恒为 0、`mode` 是按只读属性合成的，两者都不是属主证据。
+ * 「平面归另一个 uid 所有」在 Windows 上无从证明，所以判定按能力而非按注入值走 —— 否则拿
+ * 合成的 stat 去比对只会得到 `ancestor-agent-writable` 这类假阳性结论（把「不知道」说成
+ * 「agent 可写」）。没有这条语义就一定 fail-closed。
+ */
+declare function hasUidSemantics(): boolean;
+/**
+ * 授权平面根目录：显式 dir > $DSH_TRADING_AUTHORITY_DIR > **未配置（undefined）**。
+ *
+ * 这里**没有**默认位置：旧的缺省 $DSH_HOME/authority 落在 agent 自己 uid 可写的 home
+ * 里，等于把「谁能授予实盘」交给 agent（验收发现 #1）。要授权就必须显式把平面指到
+ * 一个不属于 agent uid 的目录。
+ */
+declare function resolveAuthorityLocation(options?: AuthorityOptions): AuthorityLocation;
+/** 便捷形式：等价 resolveAuthorityLocation(options).dir（未配置 ⇒ undefined）。 */
+declare function authorityDir(options?: AuthorityOptions): string | undefined;
+/**
+ * 平面隔离检查：平面及其祖先链是否落在「运行 uid（= agent uid）可写」的位置上。
+ *
+ * 检查项逐条见 PlaneIsolationCode；任何一条不过都返回 isolated=false 与机器可读 code。
+ * 这是唯一**agent 无法伪造**的一层：它写得进文件，但改不了属主，也没法把自己的 uid
+ * 从祖先链里去掉。
+ */
+declare function inspectPlaneIsolation(dir: string, options?: AuthorityOptions): PlaneIsolationReport;
+/**
+ * 规范化序列化：对象键递归排序、无空白、undefined 丢弃。
+ * 签名覆盖的是这个字节串，**不是**文件字节 —— 否则换个格式化工具（缩进/键序）
+ * 就会让一份有效授权变成验签失败，或让「重排键序」变成一次静默的语义篡改。
+ */
+declare function canonicalize(value: unknown): string;
+/** 解析受信任公钥目录文本；形状不对一律当「没有可用信任锚」。 */
+declare function parseTrustedKeys(text: string | undefined): TrustedKey[];
+interface VerifyOptions {
+  /** 是否接受带 payload.dev=true 的开发形态授权；缺省 false（fail-closed）。 */
+  allowDevGrant?: boolean;
+}
+/**
+ * 纯验签：给定授权文档文本与信任锚文本，判定是否授予实盘。
+ * 不做任何 IO、不读环境、不抛异常 —— 全部失败路径都变成 { ok: false, reason }。
+ * 开发形态授权（payload.dev=true）缺省一律拒绝，只有显式 allowDevGrant 才接受。
+ */
+declare function verifyGrantDocument(grantText: string | undefined, trustedKeysText: string | undefined, now?: number, options?: VerifyOptions): GrantVerification;
+interface PlaneInspection {
+  isolation: PlaneIsolationReport;
+  verification: GrantVerification;
+}
+/**
+ * 判定一个平面目录：先做隔离检查，再验签（两者都按 stat 指纹缓存，文件/属主一变立刻重算）。
+ * 目录不存在时隔离检查返回 dir-missing，验签照旧走到「没有信任锚」——该结论在有 uid 语义的
+ * 平台上成立；无 uid 语义的平台（Windows）在能力门就先返回 no-uid-semantics。
+ */
+declare function inspectPlane(dir: string, options?: AuthorityOptions): PlaneInspection;
+/** 判定平面当前状态（按 stat 指纹缓存，文件一变立刻重算）。dev 形态授权缺省被拒。 */
+declare function verifyAtDirectory(dir: string, now?: number): GrantVerification;
+/** 替换告警出口（测试记录用；生产缺省走 process.emitWarning）。 */
+declare function setAuthorityMismatchSink(sink: ((message: string) => void) | undefined): void;
+/**
+ * 实盘判定。`mirror` 是 preset 资产/插件 config 里的 liveTrading 值。
+ *
+ * 合取语义（只收紧）：allowed = mirror===true && 授权平面授予。
+ * 镜像为 false 一律拒绝；镜像为 true 但平面未授予 ⇒ 拒绝 + 一次可见告警（mismatch）。
+ * 平面未配置 / 未与 agent uid 隔离 ⇒ 直接拒绝，**不读任何文件**（没有默认位置可读）。
+ */
+declare function liveTradingDecision(mirror: boolean | undefined, options?: AuthorityOptions): LiveTradingDecision;
+/** 判定便捷形式：只看放行/不放行。 */
+declare function liveTradingEnabled(mirror: boolean | undefined, options?: AuthorityOptions): boolean;
+/** 清空 stat 指纹缓存（测试与「删掉平面后立刻复验」的场景用）。 */
+declare function resetAuthorityCache(): void;
+//#endregion
+export { AUTHORITY_AGENT_UID_ENV, AUTHORITY_DEV_ENV, AUTHORITY_DIR_ENV, AUTHORITY_OWNER_UID_ENV, AuthorityDirSource, AuthorityLocation, AuthorityOptions, GRANT_FILENAME, GRANT_PROTOCOL_VERSION, GrantPayload, GrantVerification, LiveTradingDecision, LiveTradingDenyReason, PlaneInspection, PlaneIsolationCode, PlaneIsolationReport, TRUSTED_KEYS_FILENAME, TrustedKey, VerifyOptions, authorityDir, canonicalize, devOptIn, hasUidSemantics, inspectPlane, inspectPlaneIsolation, liveTradingDecision, liveTradingEnabled, parseTrustedKeys, processEuid, resetAuthorityCache, resolveAuthorityLocation, setAuthorityMismatchSink, verifyAtDirectory, verifyGrantDocument };

package/lib/index.js

@@ -0,0 +1,537 @@
+import { createPublicKey, verify } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+//#region src/index.ts
+/**
+* 实盘授权状态平面（live-trading authority plane）——设计文档 §5 与不变量 13.3 的执行点。
+*
+* 为什么存在（红队 RT-04，已复核）：今天「实盘开关」写在 agent 可写的 preset 资产 YAML
+* （packages/<market>/assets/preset/<market>-trader/agent.cordis.yml）与
+* packages/base/src/presets.ts 里 —— agent 改一个文件就能抹掉实盘闸门的第一段。
+* **文件权限不是答案**（同 uid 下没有边界，见设计文档 §2.1），签名才是：
+*
+*     实盘许可 = 人工用私钥签署的授权记录（权威）
+*     preset 资产里的 liveTrading = 非权威镜像，只能收紧、永远不能授予
+*
+* 状态平面（位于 agent 可写路径之外，见 authorityDir）：
+*   <dir>/trusted-keys.json        受信任公钥目录（人类持有私钥；本模块只读）
+*   <dir>/live-trading.grant.json  人工签署的实盘授权（本模块只读）
+*
+* 位置与隔离规则（fail-closed；**没有默认位置**）：
+*   1. 平面目录必须**显式配置**（dir 选项或 $DSH_TRADING_AUTHORITY_DIR）。未配置就是拒绝
+*      （dir-not-configured）—— 曾经缺省落在 $DSH_HOME/authority，那等于让权威住在
+*      agent 自己 uid 可写的目录里（验收发现 #1：同 uid 可自铸信任锚并自我授权）。
+*   2. 平面必须与**运行本判定的进程 uid**（= trading agent 的 uid）隔离：平面目录、两份
+*      文件、以及从根到平面目录的整条祖先链都不得归该 uid 所有（祖先归 agent ⇒ 它可以
+*      unlink 后替换整个平面），目录与文件还不得带 group/other 写位。任何一条不满足 ⇒
+*      plane-not-isolated。**这条是 agent 伪造不了的**：它写得进文件，改不了文件的属主。
+*      平台前提是 POSIX 属主/权限语义：**没有 uid 语义的平台（Windows 上 process.geteuid
+*      不可用，fs.Stats.uid 恒为 0、mode 按只读属性合成）无法证明隔离** ⇒ 一律
+*      no-uid-semantics 拒绝（fail-closed）；此时注入 euid 也不构成证据（见 hasUidSemantics）。
+*   3. 可选加固：$DSH_TRADING_AUTHORITY_OWNER_UID 把「允许的属主」钉成某个具体 uid
+*      （而不是「只要不是 agent 就行」）；把它配成运行 uid 自身按配置错误拒绝。
+*   4. 开发形态必须**显式 opt-in**：$DSH_TRADING_AUTHORITY_DEV_SAME_UID=1（名字带 dev），
+*      跳过 2/3，并**每次判定留痕**（decision.devMode=true + 一次可见告警）。dev 形态下
+*      签出的授权文档带 payload.dev=true，而读取端在没有同一个 opt-in 时拒绝它
+*      （dev-grant-not-accepted）—— 「开发形态签的东西不构成生产授权」写在签名里，
+*      抹掉这个标记会让签名失效。
+*
+* fail-closed：任何「缺失 / 读不到 / 解析失败 / 验签失败 / 过期 / 尚未生效 / 未配置 /
+* 未隔离」一律 granted=false 并给出机器可读 reason —— 绝不因为读不到而放行。
+*
+* 撤销语义：删掉 grant 文件即撤销。缓存按文件 stat 指纹失效（不是 TTL），所以撤销
+* 在下一次判定就生效，不需要重启任何进程。
+*
+* 诚实边界：本模块挡得住「agent 改写 preset 资产」与「agent 用自己 uid 自铸平面」，
+* 挡不住「agent 拿到签署私钥」。私钥必须由人在另一个 uid 下持有（0600）；生产形态里
+* 该目录归执行核 tradectl（P2）之外的 authority uid，本包届时仍是核心与连接器共用的
+* 读取端，路径与隔离规则不变。
+*/
+/** 覆盖授权平面根目录的环境变量（**必须显式配置**；没有默认位置）。 */
+const AUTHORITY_DIR_ENV = "DSH_TRADING_AUTHORITY_DIR";
+/** 可选：平面必须归这个 uid（「允许的属主」钉死；缺省只要求 ≠ 运行 uid）。 */
+const AUTHORITY_OWNER_UID_ENV = "DSH_TRADING_AUTHORITY_OWNER_UID";
+/** 开发形态显式 opt-in（名字里带 dev）：同 uid 平面放行，但每次判定留痕。 */
+const AUTHORITY_DEV_ENV = "DSH_TRADING_AUTHORITY_DEV_SAME_UID";
+/** 运营 CLI 用：声明 trading agent 运行在哪个 uid 下（平面归它就是自铸）。 */
+const AUTHORITY_AGENT_UID_ENV = "DSH_TRADING_AUTHORITY_AGENT_UID";
+/** 人工签署的实盘授权文件名。 */
+const GRANT_FILENAME = "live-trading.grant.json";
+/** 受信任公钥目录文件名。 */
+const TRUSTED_KEYS_FILENAME = "trusted-keys.json";
+/** 授权文档协议版本（逐帧校验，未来换格式时旧文档必须被拒而不是被猜）。 */
+const GRANT_PROTOCOL_VERSION = 1;
+/** 显式 opt-in 的开发形态（名字里带 dev，且值必须是精确的 '1'）。 */
+function devOptIn(env = process.env) {
+	return env[AUTHORITY_DEV_ENV] === "1";
+}
+/** 当前进程的 euid；没有 uid 语义的平台（Windows）返回 undefined ⇒ 读取端按未隔离拒绝。 */
+function processEuid() {
+	const geteuid = process.geteuid;
+	return typeof geteuid === "function" ? geteuid() : void 0;
+}
+/**
+* 本平台是否有 uid 语义（`process.geteuid` 可用）——属主检查的**能力前提**。
+*
+* Windows 上没有：`fs.Stats.uid` 恒为 0、`mode` 是按只读属性合成的，两者都不是属主证据。
+* 「平面归另一个 uid 所有」在 Windows 上无从证明，所以判定按能力而非按注入值走 —— 否则拿
+* 合成的 stat 去比对只会得到 `ancestor-agent-writable` 这类假阳性结论（把「不知道」说成
+* 「agent 可写」）。没有这条语义就一定 fail-closed。
+*/
+function hasUidSemantics() {
+	return processEuid() !== void 0;
+}
+function parseUid(value) {
+	if (value === void 0 || value.trim().length === 0) return {};
+	const uid = Number(value.trim());
+	if (!Number.isInteger(uid) || uid < 0) return { error: "uid 配置不合法（" + JSON.stringify(value) + "）——必须是非负整数" };
+	return { uid };
+}
+/**
+* 授权平面根目录：显式 dir > $DSH_TRADING_AUTHORITY_DIR > **未配置（undefined）**。
+*
+* 这里**没有**默认位置：旧的缺省 $DSH_HOME/authority 落在 agent 自己 uid 可写的 home
+* 里，等于把「谁能授予实盘」交给 agent（验收发现 #1）。要授权就必须显式把平面指到
+* 一个不属于 agent uid 的目录。
+*/
+function resolveAuthorityLocation(options = {}) {
+	if (options.dir !== void 0 && options.dir.trim().length > 0) return {
+		dir: options.dir,
+		source: "option"
+	};
+	const explicit = (options.env ?? process.env)[AUTHORITY_DIR_ENV];
+	if (explicit !== void 0 && explicit.trim().length > 0) return {
+		dir: explicit,
+		source: "env"
+	};
+	return {
+		dir: void 0,
+		source: "unset"
+	};
+}
+/** 便捷形式：等价 resolveAuthorityLocation(options).dir（未配置 ⇒ undefined）。 */
+function authorityDir(options = {}) {
+	return resolveAuthorityLocation(options).dir;
+}
+/** 解析真实路径：目录不存在时，用「最深已存在祖先的 realpath + 剩余段」继续走祖先链。 */
+function resolveRealPath(path) {
+	const missing = [];
+	let cursor = resolve(path);
+	for (;;) try {
+		const real = realpathSync(cursor);
+		return missing.length === 0 ? real : join(real, ...missing.reverse());
+	} catch {
+		const parent = dirname(cursor);
+		if (parent === cursor) return resolve(path);
+		missing.push(basename(cursor));
+		cursor = parent;
+	}
+}
+function statOrUndefined(path) {
+	try {
+		return statSync(path);
+	} catch {
+		return;
+	}
+}
+/**
+* 平面隔离检查：平面及其祖先链是否落在「运行 uid（= agent uid）可写」的位置上。
+*
+* 检查项逐条见 PlaneIsolationCode；任何一条不过都返回 isolated=false 与机器可读 code。
+* 这是唯一**agent 无法伪造**的一层：它写得进文件，但改不了属主，也没法把自己的 uid
+* 从祖先链里去掉。
+*/
+function inspectPlaneIsolation(dir, options = {}) {
+	const env = options.env ?? process.env;
+	if (devOptIn(env)) return {
+		isolated: true,
+		code: "dev-opt-in",
+		devMode: true,
+		detail: "开发形态：显式设置了 " + AUTHORITY_DEV_ENV + "=1，跳过属主/权限检查 —— 这条判定不构成生产授权（每次判定都留痕）"
+	};
+	const euid = options.uidSemantics ?? hasUidSemantics() ? options.euid ?? processEuid() : void 0;
+	if (euid === void 0) return {
+		isolated: false,
+		code: "no-uid-semantics",
+		devMode: false,
+		detail: "本平台没有 uid 语义（process.geteuid 不可用：fs.Stats.uid 恒为 0、mode 按只读属性合成），无法证明平面不归 agent 所有 ⇒ 按未隔离拒绝（开发形态请显式设置 " + AUTHORITY_DEV_ENV + "=1）"
+	};
+	const pinned = parseUid(env[AUTHORITY_OWNER_UID_ENV]);
+	if (pinned.error !== void 0) return {
+		isolated: false,
+		code: "owner-not-allowed",
+		devMode: false,
+		detail: AUTHORITY_OWNER_UID_ENV + " " + pinned.error
+	};
+	if (pinned.uid !== void 0 && pinned.uid === euid) return {
+		isolated: false,
+		code: "configured-owner-is-agent-uid",
+		devMode: false,
+		detail: AUTHORITY_OWNER_UID_ENV + "=" + pinned.uid + " 就是运行 uid 自身 —— 允许属主不能是 agent（那等于没有边界）"
+	};
+	const real = resolveRealPath(dir);
+	const ancestors = [];
+	for (let cursor = dirname(real);; cursor = dirname(cursor)) {
+		ancestors.push(cursor);
+		if (dirname(cursor) === cursor) break;
+	}
+	for (const ancestor of ancestors) {
+		const stat = statOrUndefined(ancestor);
+		if (stat === void 0) continue;
+		if (stat.uid === euid) return {
+			isolated: false,
+			code: "ancestor-agent-writable",
+			devMode: false,
+			detail: "祖先目录 " + ancestor + " 归运行 uid " + euid + " 所有 —— agent 可以删掉/替换整个平面，授权平面必须放在它够不到的位置"
+		};
+		if ((stat.mode & 18) !== 0 && (stat.mode & 512) === 0) return {
+			isolated: false,
+			code: "ancestor-agent-writable",
+			devMode: false,
+			detail: "祖先目录 " + ancestor + " 对 group/other 可写且没有 sticky 位（mode " + (stat.mode & 4095).toString(8) + "）—— agent 可以替换平面里的条目"
+		};
+	}
+	const offenders = [];
+	const dirStat = statOrUndefined(real);
+	if (dirStat === void 0) return {
+		isolated: false,
+		code: "dir-missing",
+		devMode: false,
+		detail: "授权平面目录不存在：" + dir
+	};
+	offenders.push({
+		path: real,
+		stat: dirStat
+	});
+	for (const name of [TRUSTED_KEYS_FILENAME, GRANT_FILENAME]) {
+		const stat = statOrUndefined(join(real, name));
+		if (stat !== void 0) offenders.push({
+			path: join(real, name),
+			stat
+		});
+	}
+	for (const entry of offenders) {
+		if (entry.stat.uid === euid) return {
+			isolated: false,
+			code: "owner-is-agent-uid",
+			devMode: false,
+			detail: entry.path + " 归运行 uid " + euid + " 所有 —— 这正是「agent 自铸信任锚」的形态；平面必须由人在另一个 uid 下持有"
+		};
+		if (pinned.uid !== void 0 && entry.stat.uid !== pinned.uid) return {
+			isolated: false,
+			code: "owner-not-allowed",
+			devMode: false,
+			detail: entry.path + " 的属主 uid 是 " + entry.stat.uid + "，而 DSH_TRADING_AUTHORITY_OWNER_UID 要求 " + pinned.uid
+		};
+		if ((entry.stat.mode & 18) !== 0) return {
+			isolated: false,
+			code: "group-or-other-writable",
+			devMode: false,
+			detail: entry.path + " 带 group/other 写位（mode " + (entry.stat.mode & 4095).toString(8) + "）—— 别的 uid 能改它就不是权威"
+		};
+	}
+	return {
+		isolated: true,
+		code: "isolated",
+		devMode: false,
+		detail: "平面归 uid " + dirStat.uid + "（≠ 运行 uid " + euid + "），目录与文件无 group/other 写位，祖先链无 agent 可写目录"
+	};
+}
+/**
+* 规范化序列化：对象键递归排序、无空白、undefined 丢弃。
+* 签名覆盖的是这个字节串，**不是**文件字节 —— 否则换个格式化工具（缩进/键序）
+* 就会让一份有效授权变成验签失败，或让「重排键序」变成一次静默的语义篡改。
+*/
+function canonicalize(value) {
+	if (value === void 0) return "null";
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return "[" + value.map((item) => canonicalize(item)).join(",") + "]";
+	const record = value;
+	return "{" + Object.keys(record).filter((key) => record[key] !== void 0).sort().map((key) => JSON.stringify(key) + ":" + canonicalize(record[key])).join(",") + "}";
+}
+function isTrustedKey(value) {
+	if (value === null || typeof value !== "object") return false;
+	const key = value;
+	return typeof key.keyId === "string" && key.keyId.length > 0 && key.alg === "ed25519" && typeof key.publicKeyPem === "string" && key.publicKeyPem.includes("BEGIN PUBLIC KEY");
+}
+/** 解析受信任公钥目录文本；形状不对一律当「没有可用信任锚」。 */
+function parseTrustedKeys(text) {
+	if (text === void 0) return [];
+	let doc;
+	try {
+		doc = JSON.parse(text);
+	} catch {
+		return [];
+	}
+	const keys = doc?.keys;
+	if (!Array.isArray(keys)) return [];
+	return keys.filter(isTrustedKey);
+}
+function isGrantPayload(value) {
+	if (value === null || typeof value !== "object") return false;
+	const payload = value;
+	return typeof payload.liveTrading === "boolean" && typeof payload.issuedAt === "string" && typeof payload.expiresAt === "string";
+}
+/**
+* 纯验签：给定授权文档文本与信任锚文本，判定是否授予实盘。
+* 不做任何 IO、不读环境、不抛异常 —— 全部失败路径都变成 { ok: false, reason }。
+* 开发形态授权（payload.dev=true）缺省一律拒绝，只有显式 allowDevGrant 才接受。
+*/
+function verifyGrantDocument(grantText, trustedKeysText, now = Date.now(), options = {}) {
+	const trustedKeys = parseTrustedKeys(trustedKeysText);
+	if (trustedKeys.length === 0) return {
+		ok: false,
+		reason: "no-trusted-keys",
+		detail: "受信任公钥目录缺失或为空（trusted-keys.json）——没有信任锚就没有授权"
+	};
+	if (grantText === void 0) return {
+		ok: false,
+		reason: "no-grant-document",
+		detail: "授权平面里没有实盘授权文档（live-trading.grant.json）"
+	};
+	let doc;
+	try {
+		doc = JSON.parse(grantText);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: "malformed",
+			detail: "授权文档不是合法 JSON：" + String(error?.message ?? error)
+		};
+	}
+	const record = doc;
+	if (record === null || typeof record !== "object") return {
+		ok: false,
+		reason: "malformed",
+		detail: "授权文档顶层必须是对象"
+	};
+	if (record.protocolVersion !== 1) return {
+		ok: false,
+		reason: "malformed",
+		detail: "授权文档 protocolVersion 期望 1，实际 " + JSON.stringify(record.protocolVersion) + "（版本不匹配一律拒绝，不做兼容猜测）"
+	};
+	const signature = record.signature;
+	if (signature === void 0 || typeof signature.sig !== "string" || typeof signature.keyId !== "string" || signature.alg !== "ed25519") return {
+		ok: false,
+		reason: "malformed",
+		detail: "授权文档 signature 形状不合法（需要 alg=ed25519 / keyId / sig）"
+	};
+	if (!isGrantPayload(record.payload)) return {
+		ok: false,
+		reason: "malformed",
+		detail: "授权文档 payload 形状不合法（需要 liveTrading / issuedAt / expiresAt）"
+	};
+	const payload = record.payload;
+	const trusted = trustedKeys.find((key) => key.keyId === signature.keyId);
+	if (trusted === void 0) return {
+		ok: false,
+		reason: "unknown-key",
+		detail: "签发密钥 " + signature.keyId + " 不在受信任公钥目录里"
+	};
+	let signatureOk = false;
+	try {
+		signatureOk = verify(null, Buffer.from(canonicalize(payload), "utf8"), createPublicKey(trusted.publicKeyPem), Buffer.from(signature.sig, "base64"));
+	} catch (error) {
+		return {
+			ok: false,
+			reason: "bad-signature",
+			detail: "验签过程失败（公钥或签名不是合法 Ed25519 材料）：" + String(error?.message ?? error)
+		};
+	}
+	if (!signatureOk) return {
+		ok: false,
+		reason: "bad-signature",
+		detail: "Ed25519 验签不通过（payload 被改过，或不是这把私钥签的）",
+		keyId: trusted.keyId
+	};
+	if (payload.liveTrading !== true) return {
+		ok: false,
+		reason: "not-a-grant",
+		detail: "授权文档 payload.liveTrading 不是 true —— 这份签名不构成实盘授权",
+		payload,
+		keyId: trusted.keyId
+	};
+	if (payload.dev === true && options.allowDevGrant !== true) return {
+		ok: false,
+		reason: "dev-grant-not-accepted",
+		detail: "这份授权是开发形态（payload.dev=true）签出的：它只对同样显式设置 " + AUTHORITY_DEV_ENV + "=1 的读取端生效。生产形态请在另一个 uid 下重新签署（dev 标记在签名覆盖范围内，抹掉它会让签名失效）",
+		payload,
+		keyId: trusted.keyId
+	};
+	const issuedAt = Date.parse(payload.issuedAt);
+	const expiresAt = Date.parse(payload.expiresAt);
+	if (Number.isNaN(issuedAt) || Number.isNaN(expiresAt)) return {
+		ok: false,
+		reason: "malformed",
+		detail: "issuedAt / expiresAt 不是可解析的时间戳",
+		payload,
+		keyId: trusted.keyId
+	};
+	if (now < issuedAt) return {
+		ok: false,
+		reason: "not-yet-valid",
+		detail: "授权尚未生效（issuedAt " + payload.issuedAt + "）",
+		payload,
+		keyId: trusted.keyId
+	};
+	if (now >= expiresAt) return {
+		ok: false,
+		reason: "expired",
+		detail: "授权已过期（expiresAt " + payload.expiresAt + "）—— 续签 = 重新签名，不做静默延期",
+		payload,
+		keyId: trusted.keyId
+	};
+	return {
+		ok: true,
+		reason: "granted",
+		detail: "人工签署的实盘授权有效（签署人 " + (payload.operator ?? "未署名") + "，到期 " + payload.expiresAt + "）",
+		payload,
+		keyId: trusted.keyId
+	};
+}
+function readTextOrUndefined(file) {
+	try {
+		return readFileSync(file, "utf8");
+	} catch {
+		return;
+	}
+}
+/** 指纹含属主与权限位：光看 mtime/size 会让一次 chown/chmod 逃过缓存。 */
+function stampOf(file) {
+	try {
+		const stat = statSync(file);
+		return stat.uid + ":" + stat.mode + ":" + stat.mtimeMs + ":" + stat.size;
+	} catch {
+		return "missing";
+	}
+}
+const cache = /* @__PURE__ */ new Map();
+function planeKeyOf(euid, env, semantics = true) {
+	return String(semantics) + "|" + String(euid) + "|" + String(env["DSH_TRADING_AUTHORITY_OWNER_UID"] ?? "") + "|" + String(devOptIn(env));
+}
+/**
+* 判定一个平面目录：先做隔离检查，再验签（两者都按 stat 指纹缓存，文件/属主一变立刻重算）。
+* 目录不存在时隔离检查返回 dir-missing，验签照旧走到「没有信任锚」——该结论在有 uid 语义的
+* 平台上成立；无 uid 语义的平台（Windows）在能力门就先返回 no-uid-semantics。
+*/
+function inspectPlane(dir, options = {}) {
+	const env = options.env ?? process.env;
+	const now = options.now ?? Date.now();
+	const grantFile = join(dir, GRANT_FILENAME);
+	const keysFile = join(dir, TRUSTED_KEYS_FILENAME);
+	const grantStamp = stampOf(grantFile);
+	const keysStamp = stampOf(keysFile);
+	const dirStamp = stampOf(dir);
+	const semantics = options.uidSemantics ?? hasUidSemantics();
+	const planeKey = planeKeyOf(options.euid ?? processEuid(), env, semantics);
+	const cached = cache.get(dir);
+	if (cached !== void 0 && cached.grantStamp === grantStamp && cached.keysStamp === keysStamp && cached.dirStamp === dirStamp && cached.planeKey === planeKey) {
+		const payload = cached.verification.payload;
+		if (cached.verification.reason !== "granted" || payload === void 0 || now >= Date.parse(payload.issuedAt) && now < Date.parse(payload.expiresAt)) return {
+			isolation: cached.isolation,
+			verification: cached.verification
+		};
+	}
+	const isolation = inspectPlaneIsolation(dir, {
+		...options,
+		env
+	});
+	const verification = verifyGrantDocument(readTextOrUndefined(grantFile), readTextOrUndefined(keysFile), now, { allowDevGrant: devOptIn(env) });
+	cache.set(dir, {
+		grantStamp,
+		keysStamp,
+		dirStamp,
+		planeKey,
+		isolation,
+		verification
+	});
+	return {
+		isolation,
+		verification
+	};
+}
+/** 判定平面当前状态（按 stat 指纹缓存，文件一变立刻重算）。dev 形态授权缺省被拒。 */
+function verifyAtDirectory(dir, now = Date.now()) {
+	return inspectPlane(dir, { now }).verification;
+}
+let warningSink = (message) => {
+	process.emitWarning(message, { code: "DSH_TRADING_LIVE_AUTHORITY_MISMATCH" });
+};
+/** 替换告警出口（测试记录用；生产缺省走 process.emitWarning）。 */
+function setAuthorityMismatchSink(sink) {
+	warningSink = sink ?? ((message) => process.emitWarning(message, { code: "DSH_TRADING_LIVE_AUTHORITY_MISMATCH" }));
+}
+const reportedMismatch = /* @__PURE__ */ new Set();
+/** 同一个 (目录, 原因) 只吼一次，避免热路径把 stderr 刷满。 */
+function reportMismatch(dir, mirror, verification) {
+	const key = dir + "|" + verification.reason;
+	if (reportedMismatch.has(key)) return;
+	reportedMismatch.add(key);
+	warningSink("[dsh-trading] 实盘镜像与授权平面不一致：preset 资产里 liveTrading=" + String(mirror) + "，但 " + dir + " 未授予实盘（" + verification.reason + "：" + verification.detail + "）。授权平面是唯一授予者，镜像不能授予 —— 资产写 true 只会产生这条告警，不会打开实盘。");
+}
+const reportedDev = /* @__PURE__ */ new Set();
+/** 开发形态每次判定留痕（同一个目录只吼一次，避免热路径刷屏）。 */
+function reportDevMode(dir, isolation) {
+	if (reportedDev.has(dir)) return;
+	reportedDev.add(dir);
+	warningSink("[dsh-trading][DEV] 实盘授权平面在开发形态下判定：" + dir + " —— " + isolation.detail + "。生产形态必须把平面放在不属于 agent uid 的目录下（DSH_TRADING_AUTHORITY_DIR + 属主隔离）。");
+}
+/**
+* 实盘判定。`mirror` 是 preset 资产/插件 config 里的 liveTrading 值。
+*
+* 合取语义（只收紧）：allowed = mirror===true && 授权平面授予。
+* 镜像为 false 一律拒绝；镜像为 true 但平面未授予 ⇒ 拒绝 + 一次可见告警（mismatch）。
+* 平面未配置 / 未与 agent uid 隔离 ⇒ 直接拒绝，**不读任何文件**（没有默认位置可读）。
+*/
+function liveTradingDecision(mirror, options = {}) {
+	const env = options.env ?? process.env;
+	const location = resolveAuthorityLocation(options);
+	const mirrorValue = mirror === true;
+	const dev = devOptIn(env);
+	let isolation;
+	let verification;
+	if (location.dir === void 0) verification = {
+		ok: false,
+		reason: "dir-not-configured",
+		detail: "授权平面目录未显式配置（DSH_TRADING_AUTHORITY_DIR 或 dir 选项）—— 本模块没有默认位置：缺省落在 $DSH_HOME/authority 等于把权威放进 agent 自己 uid 可写的目录（验收发现 #1）。请把平面指向一个不属于 agent uid 的目录。"
+	};
+	else {
+		const inspection = inspectPlane(location.dir, {
+			...options,
+			env
+		});
+		isolation = inspection.isolation;
+		verification = inspection.verification;
+		if (!inspection.isolation.isolated && inspection.isolation.code !== "dir-missing") verification = {
+			ok: false,
+			reason: "plane-not-isolated",
+			detail: "授权平面未与 agent uid 隔离（" + inspection.isolation.code + "）：" + inspection.isolation.detail + "。签名机制只解决「谁签的」，属主隔离才解决「平面归谁」—— 自铸的信任锚在这一步被挡下。"
+		};
+	}
+	if (dev && location.dir !== void 0 && isolation !== void 0) reportDevMode(location.dir, isolation);
+	const mismatch = mirrorValue && !verification.ok;
+	if (mismatch && location.dir !== void 0) reportMismatch(location.dir, mirrorValue, verification);
+	return {
+		...verification,
+		granted: verification.ok,
+		allowed: mirrorValue && verification.ok,
+		mirror: mirrorValue,
+		mismatch,
+		dir: location.dir,
+		dirSource: location.source,
+		devMode: dev,
+		isolation
+	};
+}
+/** 判定便捷形式：只看放行/不放行。 */
+function liveTradingEnabled(mirror, options = {}) {
+	return liveTradingDecision(mirror, options).allowed;
+}
+/** 清空 stat 指纹缓存（测试与「删掉平面后立刻复验」的场景用）。 */
+function resetAuthorityCache() {
+	cache.clear();
+	reportedMismatch.clear();
+	reportedDev.clear();
+}
+//#endregion
+export { AUTHORITY_AGENT_UID_ENV, AUTHORITY_DEV_ENV, AUTHORITY_DIR_ENV, AUTHORITY_OWNER_UID_ENV, GRANT_FILENAME, GRANT_PROTOCOL_VERSION, TRUSTED_KEYS_FILENAME, authorityDir, canonicalize, devOptIn, hasUidSemantics, inspectPlane, inspectPlaneIsolation, liveTradingDecision, liveTradingEnabled, parseTrustedKeys, processEuid, resetAuthorityCache, resolveAuthorityLocation, setAuthorityMismatchSink, verifyAtDirectory, verifyGrantDocument };

package/lib/sign.d.ts

@@ -0,0 +1,106 @@
+import { AUTHORITY_AGENT_UID_ENV, AUTHORITY_DEV_ENV, AUTHORITY_OWNER_UID_ENV, GrantPayload, TrustedKey } from "./index.js";
+//#region src/sign.d.ts
+interface OperatorKeyPair {
+  keyId: string;
+  publicKeyPem: string;
+  privateKeyPem: string;
+}
+/** 生成一把运营方（人类）Ed25519 密钥对。默认 keyId = operator-1。 */
+declare function generateOperatorKeyPair(keyId?: string): OperatorKeyPair;
+/** 受信任公钥目录文档（人工把它写进授权平面；本包运行期只读它）。 */
+declare function buildTrustedKeysDocument(keys: TrustedKey[]): string;
+/**
+ * 签署一份实盘授权。签名覆盖 canonicalize(payload)（键序无关、格式无关），
+ * 所以重排键序不改变语义、改动任何一个字段（含 dev 标记）都会验签失败。
+ */
+declare function signLiveTradingGrant(payload: GrantPayload, privateKeyPem: string, keyId: string): string;
+/** 到期时刻 = 签发时刻 + 天数（设计文档 §12.3 默认 30 天）。 */
+declare function expiryFromDays(issuedAtMs: number, days: number): string;
+/** 运营侧拒绝原因（机器可读；CLI 把 code 原样打出来）。 */
+type OperatorDenyCode = 'agent-uid-required' | 'agent-uid-invalid' | 'agent-uid-equals-operator' | 'no-uid-semantics' | 'key-exists' | 'key-missing' | 'trust-anchor-exists' | 'trust-anchor-missing' | 'plane-dir-missing' | 'plane-not-isolated' | 'key-not-trusted';
+declare class OperatorGuardError extends Error {
+  readonly code: OperatorDenyCode;
+  constructor(code: OperatorDenyCode, message: string);
+}
+interface OperatorContext {
+  /** 显式声明 trading agent 运行在哪个 uid 下（--agent-uid 或 $DSH_TRADING_AUTHORITY_AGENT_UID）。 */
+  agentUid?: number;
+  /** 显式开发形态（--force-dev，或 $DSH_TRADING_AUTHORITY_DEV_SAME_UID=1）。 */
+  forceDev?: boolean;
+  /** 环境变量映射，缺省 process.env。 */
+  env?: Record<string, string | undefined>;
+  /** 覆盖运行 uid（测试用来模拟「人在另一个 uid 下操作」）。 */
+  euid?: number;
+}
+interface OperatorIdentity {
+  /** 运行本命令的 uid；无 uid 语义的平台上是 undefined。 */
+  euid: number | undefined;
+  /** 声明的 agent uid；显式 dev 形态下允许缺席。 */
+  agentUid: number | undefined;
+  devMode: boolean;
+  detail: string;
+}
+/**
+ * 解析运营侧身份并**先拒绝自铸形态**：不声明 agent uid 就没有「这不是 agent 自己写的」
+ * 这句话；声明成自己就是自铸。两条都过不去时只有显式 dev 形态能继续。
+ */
+declare function resolveOperatorIdentity(context?: OperatorContext): OperatorIdentity;
+interface InitTrustAnchorRequest extends OperatorContext {
+  /** 授权平面目录（必须显式给出；本工具没有默认位置）。 */
+  dir: string;
+  /** 私钥落盘路径。 */
+  keyFile: string;
+  /** 密钥标识，缺省 operator-1。 */
+  keyId?: string;
+  /** 是否把 trusted-keys.json 写进平面；false = 只回内容给人手写（缺省 true）。 */
+  writeTrust?: boolean;
+}
+interface InitTrustAnchorResult {
+  keyId: string;
+  keyFile: string;
+  trustFile: string;
+  publicKeyPem: string;
+  /** 信任锚是否由本次调用写入（false = 调用方自己写）。 */
+  trustWritten: boolean;
+  devMode: boolean;
+  detail: string;
+}
+/**
+ * 建一对运营密钥并把信任锚写进平面。守卫见文件头：不声明 agent uid ⇒ 拒绝；声明的
+ * agent uid = 当前 uid ⇒ 拒绝（除非 --force-dev）；信任锚已存在 ⇒ 拒绝（除非 --force-dev）。
+ */
+declare function initTrustAnchor(request: InitTrustAnchorRequest): InitTrustAnchorResult;
+interface SignGrantRequest extends OperatorContext {
+  /** 授权平面目录（必须显式给出；本工具没有默认位置）。 */
+  dir: string;
+  /** 运营私钥路径。 */
+  keyFile: string;
+  keyId?: string;
+  days?: number;
+  operator?: string;
+  note?: string;
+  /** 判定时刻（毫秒），缺省 Date.now()。 */
+  now?: number;
+}
+interface SignGrantResult {
+  grantFile: string;
+  payload: GrantPayload;
+  keyId: string;
+  devMode: boolean;
+  detail: string;
+}
+/**
+ * 把一份带到期的实盘授权签进**已存在**的平面。
+ *
+ * 守卫：平面目录必须已存在（不在 agent 可写路径上先建好）、信任锚必须已存在、私钥的
+ * 公钥半边必须在锚里登记；不声明 agent uid 或声明成自己一律拒绝（除非 --force-dev）。
+ */
+declare function signGrantIntoPlane(request: SignGrantRequest): SignGrantResult;
+/** 平面里两份文件的现状（status 打印用；只读）。 */
+declare function describePlaneFiles(dir: string): Array<{
+  name: string;
+  path: string;
+  present: boolean;
+}>;
+//#endregion
+export { AUTHORITY_AGENT_UID_ENV, AUTHORITY_DEV_ENV, AUTHORITY_OWNER_UID_ENV, InitTrustAnchorRequest, InitTrustAnchorResult, OperatorContext, OperatorDenyCode, OperatorGuardError, OperatorIdentity, OperatorKeyPair, SignGrantRequest, SignGrantResult, buildTrustedKeysDocument, describePlaneFiles, expiryFromDays, generateOperatorKeyPair, initTrustAnchor, resolveOperatorIdentity, signGrantIntoPlane, signLiveTradingGrant };

package/lib/sign.js

@@ -0,0 +1,233 @@
+import { AUTHORITY_AGENT_UID_ENV, AUTHORITY_DEV_ENV, AUTHORITY_OWNER_UID_ENV, GRANT_FILENAME, TRUSTED_KEYS_FILENAME, canonicalize, devOptIn, inspectPlaneIsolation, parseTrustedKeys, processEuid } from "./index.js";
+import { createPrivateKey, createPublicKey, generateKeyPairSync, sign } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/sign.ts
+/**
+* 授权平面的**签署侧**：只给运营 CLI 与测试用。
+*
+* 运行期（连接器、宿主、未来的 tradectl 判定路径）**不得** import 本模块 —— 见
+* test/live-trading-authority.test.ts 的依赖方向断言。把它留在运行期代码路径之外，
+* 「谁能签发」就不依赖运行期纪律，而依赖模块图。
+*
+* 这里同时是**运营侧守卫**的家（验收发现 #1：同 uid 可以自己 init 一对密钥、自己写
+* trusted-keys.json、自己 sign 一份 grant，然后 status 输出放行）：
+*
+*   - 写平面的人必须**声明 agent 跑在哪个 uid 下**（--agent-uid / $DSH_TRADING_AUTHORITY_AGENT_UID）。
+*     声明不了就不写 —— 否则「这个平面不是 agent 自己写的」无法成立。
+*   - 声明的 agent uid **就是当前进程 uid** ⇒ 拒绝（agent-uid-equals-operator）：这正是
+*     自铸形态。只有在**显式开发形态**（--force-dev，名字里带 dev）下才放行，且签出的
+*     授权文档会带 payload.dev=true —— 读取端没有同一个 opt-in 时拒绝它。
+*   - `init` 拒绝覆盖已存在的 trusted-keys.json（trust-anchor-exists），除非显式 --force-dev。
+*   - `sign` 要求信任锚已存在、且签名私钥的公钥半边确实登记在锚里（key-not-trusted），
+*     并且拒绝写一个「归声明的 agent uid 所有」的平面（plane-not-isolated）。
+*
+* 注意：私钥不出现在本包的运行期导出里；CLI 从磁盘读私钥文件（由人在另一个 uid 下
+* 持有，0600）。运营侧守卫是纵深防御，不是安全边界本身 —— 边界在读取端的属主检查
+* （见 ./index.ts 的 inspectPlaneIsolation）：agent 写得进文件，改不了文件的属主。
+*/
+/** 生成一把运营方（人类）Ed25519 密钥对。默认 keyId = operator-1。 */
+function generateOperatorKeyPair(keyId = "operator-1") {
+	const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+	return {
+		keyId,
+		publicKeyPem: publicKey.export({
+			type: "spki",
+			format: "pem"
+		}).toString(),
+		privateKeyPem: privateKey.export({
+			type: "pkcs8",
+			format: "pem"
+		}).toString()
+	};
+}
+/** 受信任公钥目录文档（人工把它写进授权平面；本包运行期只读它）。 */
+function buildTrustedKeysDocument(keys) {
+	return JSON.stringify({
+		version: 1,
+		keys
+	}, null, 2) + "\n";
+}
+/**
+* 签署一份实盘授权。签名覆盖 canonicalize(payload)（键序无关、格式无关），
+* 所以重排键序不改变语义、改动任何一个字段（含 dev 标记）都会验签失败。
+*/
+function signLiveTradingGrant(payload, privateKeyPem, keyId) {
+	const signature = sign(null, Buffer.from(canonicalize(payload), "utf8"), createPrivateKey(privateKeyPem)).toString("base64");
+	return JSON.stringify({
+		protocolVersion: 1,
+		payload,
+		signature: {
+			alg: "ed25519",
+			keyId,
+			sig: signature
+		}
+	}, null, 2) + "\n";
+}
+/** 到期时刻 = 签发时刻 + 天数（设计文档 §12.3 默认 30 天）。 */
+function expiryFromDays(issuedAtMs, days) {
+	if (!Number.isFinite(days) || days <= 0) throw new Error("days 必须是正数");
+	return new Date(issuedAtMs + days * 24 * 60 * 60 * 1e3).toISOString();
+}
+var OperatorGuardError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "OperatorGuardError";
+		this.code = code;
+	}
+};
+function parseAgentUid(context, env) {
+	if (context.agentUid !== void 0) {
+		if (!Number.isInteger(context.agentUid) || context.agentUid < 0) throw new OperatorGuardError("agent-uid-invalid", "--agent-uid 必须是非负整数，实际 " + JSON.stringify(context.agentUid));
+		return context.agentUid;
+	}
+	const raw = env[AUTHORITY_AGENT_UID_ENV];
+	if (raw === void 0 || raw.trim().length === 0) return void 0;
+	const uid = Number(raw.trim());
+	if (!Number.isInteger(uid) || uid < 0) throw new OperatorGuardError("agent-uid-invalid", AUTHORITY_AGENT_UID_ENV + " 必须是非负整数，实际 " + JSON.stringify(raw));
+	return uid;
+}
+/**
+* 解析运营侧身份并**先拒绝自铸形态**：不声明 agent uid 就没有「这不是 agent 自己写的」
+* 这句话；声明成自己就是自铸。两条都过不去时只有显式 dev 形态能继续。
+*/
+function resolveOperatorIdentity(context = {}) {
+	const env = context.env ?? process.env;
+	const devMode = context.forceDev === true || devOptIn(env);
+	const euid = context.euid ?? processEuid();
+	const agentUid = parseAgentUid(context, env);
+	if (devMode) return {
+		euid,
+		agentUid,
+		devMode: true,
+		detail: "开发形态（" + (context.forceDev === true ? "--force-dev" : AUTHORITY_DEV_ENV + "=1") + "）：允许在 agent uid 下写平面，签出的授权带 payload.dev=true，读取端没有同一个 opt-in 时拒绝它"
+	};
+	if (agentUid === void 0) throw new OperatorGuardError("agent-uid-required", "必须声明 trading agent 的 uid（--agent-uid <uid> 或 " + AUTHORITY_AGENT_UID_ENV + "=<uid>）：不声明就无法证明这个平面不是 agent 自己写的。只有在显式开发形态（--force-dev）下才允许省略。");
+	if (euid === void 0) throw new OperatorGuardError("no-uid-semantics", "本平台没有 uid 语义（process.geteuid 不可用），无法证明「写平面的不是 agent」⇒ 拒绝。开发形态请显式 --force-dev。");
+	if (euid === agentUid) throw new OperatorGuardError("agent-uid-equals-operator", "当前进程 uid " + euid + " 就是声明的 agent uid —— 这正是「agent 自铸信任锚」的形态：自己生成密钥、自己写 trusted-keys.json、自己签 grant。生产形态请在另一个 uid 下运行本命令（或由人工把私钥与信任锚带过去）；显式开发形态请用 --force-dev，它会在授权文档里留下 dev 标记。");
+	return {
+		euid,
+		agentUid,
+		devMode: false,
+		detail: "运行 uid " + euid + " ≠ 声明的 agent uid " + agentUid + "：平面不归 agent 所有"
+	};
+}
+/** 从读取端（agent uid）角度看，这个目录是否可写 —— 可写就不许写信任锚/授权。 */
+function assertWriterPlaneIsolated(dir, identity, context) {
+	if (identity.devMode || identity.agentUid === void 0) return;
+	const env = { ...context.env ?? process.env };
+	delete env[AUTHORITY_DEV_ENV];
+	const report = inspectPlaneIsolation(dir, {
+		env,
+		euid: identity.agentUid
+	});
+	if (!report.isolated && report.code !== "dir-missing") throw new OperatorGuardError("plane-not-isolated", "平面目录 " + dir + " 对 agent uid " + identity.agentUid + " 可写（" + report.code + "）：" + report.detail + "。换到 agent 够不到的位置（先由人在该 uid 下建目录），或用 --force-dev 显式声明开发形态。");
+}
+function publicKeyPemOf(privateKeyPem) {
+	try {
+		return createPublicKey(createPrivateKey(privateKeyPem)).export({
+			type: "spki",
+			format: "pem"
+		}).toString();
+	} catch {
+		return;
+	}
+}
+/**
+* 建一对运营密钥并把信任锚写进平面。守卫见文件头：不声明 agent uid ⇒ 拒绝；声明的
+* agent uid = 当前 uid ⇒ 拒绝（除非 --force-dev）；信任锚已存在 ⇒ 拒绝（除非 --force-dev）。
+*/
+function initTrustAnchor(request) {
+	const identity = resolveOperatorIdentity(request);
+	const keyId = request.keyId ?? "operator-1";
+	const trustFile = join(request.dir, TRUSTED_KEYS_FILENAME);
+	if (existsSync(request.keyFile)) throw new OperatorGuardError("key-exists", "私钥文件已存在，拒绝覆盖：" + request.keyFile);
+	if (existsSync(trustFile) && !identity.devMode) throw new OperatorGuardError("trust-anchor-exists", "信任锚已存在，拒绝覆盖：" + trustFile + " —— 覆盖信任锚 = 换掉「谁说了算」，正是 agent 自铸的形态。要重建请先由人工移除该文件；显式开发形态请用 --force-dev。");
+	if (existsSync(request.dir)) assertWriterPlaneIsolated(request.dir, identity, request);
+	const pair = generateOperatorKeyPair(keyId);
+	mkdirSync(request.dir, {
+		recursive: true,
+		mode: 493
+	});
+	writeFileSync(request.keyFile, pair.privateKeyPem, { mode: 384 });
+	chmodSync(request.keyFile, 384);
+	const keysDoc = buildTrustedKeysDocument([{
+		keyId,
+		alg: "ed25519",
+		publicKeyPem: pair.publicKeyPem
+	}]);
+	const trustWritten = request.writeTrust !== false;
+	if (trustWritten) {
+		writeFileSync(trustFile, keysDoc, { mode: 420 });
+		chmodSync(trustFile, 420);
+	}
+	return {
+		keyId,
+		keyFile: request.keyFile,
+		trustFile,
+		publicKeyPem: pair.publicKeyPem,
+		trustWritten,
+		devMode: identity.devMode,
+		detail: identity.detail
+	};
+}
+/**
+* 把一份带到期的实盘授权签进**已存在**的平面。
+*
+* 守卫：平面目录必须已存在（不在 agent 可写路径上先建好）、信任锚必须已存在、私钥的
+* 公钥半边必须在锚里登记；不声明 agent uid 或声明成自己一律拒绝（除非 --force-dev）。
+*/
+function signGrantIntoPlane(request) {
+	const identity = resolveOperatorIdentity(request);
+	const keyId = request.keyId ?? "operator-1";
+	if (!existsSync(request.dir)) throw new OperatorGuardError("plane-dir-missing", "授权平面目录不存在：" + request.dir + " —— sign 只写入已经存在的平面（先由人在允许属主下建目录并写信任锚）。");
+	assertWriterPlaneIsolated(request.dir, identity, request);
+	const trustFile = join(request.dir, TRUSTED_KEYS_FILENAME);
+	if (!existsSync(trustFile)) throw new OperatorGuardError("trust-anchor-missing", "平面里没有信任锚（" + trustFile + "）—— 先由人工在允许属主下建立信任锚；sign 不会顺手造一个（那正是自铸）。");
+	if (!existsSync(request.keyFile)) throw new OperatorGuardError("key-missing", "私钥文件不存在：" + request.keyFile);
+	const trusted = parseTrustedKeys(readFileSync(trustFile, "utf8")).find((key) => key.keyId === keyId);
+	if (trusted === void 0) throw new OperatorGuardError("key-not-trusted", "密钥 " + keyId + " 不在信任锚里（" + trustFile + "）—— 签出来也没人认；先用运营 CLI 的 init 登记公钥。");
+	const privateKeyPem = readFileSync(request.keyFile, "utf8");
+	const derived = publicKeyPemOf(privateKeyPem);
+	if (derived === void 0 || derived.trim() !== trusted.publicKeyPem.trim()) throw new OperatorGuardError("key-not-trusted", "私钥 " + request.keyFile + " 的公钥半边与信任锚里 " + keyId + " 登记的不是同一把 —— 拒绝签一份验不过的授权。");
+	const issuedAtMs = request.now ?? Date.now();
+	const days = request.days ?? 30;
+	const payload = {
+		liveTrading: true,
+		issuedAt: new Date(issuedAtMs).toISOString(),
+		expiresAt: expiryFromDays(issuedAtMs, days),
+		operator: request.operator ?? process.env.USER ?? "operator",
+		note: request.note ?? "",
+		...identity.devMode ? { dev: true } : {}
+	};
+	const grantFile = join(request.dir, GRANT_FILENAME);
+	writeFileSync(grantFile, signLiveTradingGrant(payload, privateKeyPem, keyId), { mode: 420 });
+	chmodSync(grantFile, 420);
+	return {
+		grantFile,
+		payload,
+		keyId,
+		devMode: identity.devMode,
+		detail: identity.detail
+	};
+}
+/** 平面里两份文件的现状（status 打印用；只读）。 */
+function describePlaneFiles(dir) {
+	return [TRUSTED_KEYS_FILENAME, GRANT_FILENAME].map((name) => {
+		const path = join(dir, name);
+		let present = false;
+		try {
+			present = statSync(path).isFile();
+		} catch {
+			present = false;
+		}
+		return {
+			name,
+			path,
+			present
+		};
+	});
+}
+//#endregion
+export { AUTHORITY_AGENT_UID_ENV, AUTHORITY_DEV_ENV, AUTHORITY_OWNER_UID_ENV, OperatorGuardError, buildTrustedKeysDocument, describePlaneFiles, expiryFromDays, generateOperatorKeyPair, initTrustAnchor, resolveOperatorIdentity, signGrantIntoPlane, signLiveTradingGrant };

package/lib/testing.d.ts

@@ -0,0 +1,40 @@
+import { AuthorityOptions } from "./index.js";
+//#region src/testing.d.ts
+interface TestAuthority {
+  /** 临时授权平面目录（用完即删）。 */
+  dir: string;
+  keyId: string;
+  privateKeyPem: string;
+  publicKeyPem: string;
+  /** 夹具形态：true = 显式开发形态，false = 生产形态（无 dev opt-in）。 */
+  devMode: boolean;
+  /**
+   * 把这份平面当成**生产形态**判定的选项：注入一个与文件属主不同的 euid，等价于
+   * 「平面归人在的另一个 uid、判定跑在 agent uid 下」。dev 形态的夹具也可用它。
+   */
+  authorityOptions: AuthorityOptions;
+  /** 重签一份授权（换到期天数或签署人）。 */
+  sign(overrides?: {
+    days?: number;
+    operator?: string;
+  }): void;
+  /** 撤销：删掉授权文档、保留信任锚。 */
+  revoke(): void;
+  /** 还原环境变量、清缓存、删临时目录。 */
+  uninstall(): void;
+}
+interface TestAuthorityOptions {
+  /** 授权有效期（天），缺省 30。 */
+  days?: number;
+  /** 签署人标识，缺省 test-operator。 */
+  operator?: string;
+  /** 环境变量表，缺省 process.env（决定 DSH_TRADING_AUTHORITY_DIR 写在哪）。 */
+  env?: Record<string, string | undefined>;
+  /** 只放信任锚不签授权（覆盖「平面就绪但未授权」的形态）。 */
+  withoutGrant?: boolean;
+  /** 夹具形态，缺省 true（显式开发形态）；false = 生产形态见文件头。 */
+  dev?: boolean;
+}
+declare function installTestAuthority(options?: TestAuthorityOptions): TestAuthority;
+//#endregion
+export { TestAuthority, TestAuthorityOptions, installTestAuthority };

package/lib/testing.js

@@ -0,0 +1,86 @@
+import { AUTHORITY_DEV_ENV, AUTHORITY_DIR_ENV, GRANT_FILENAME, TRUSTED_KEYS_FILENAME, processEuid, resetAuthorityCache } from "./index.js";
+import { buildTrustedKeysDocument, expiryFromDays, generateOperatorKeyPair, signLiveTradingGrant } from "./sign.js";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+//#region src/testing.ts
+/**
+* 授权平面的测试夹具（只经 ./testing 子路径导出，运行期入口不引用它）。
+*
+* 它替换的不是被测逻辑，而是「人已经签过授权」这个**前置条件**：在临时目录里搭一份
+* 真实的 Ed25519 密钥、真实的 trusted-keys.json、真实的签名授权文档，并把
+* DSH_TRADING_AUTHORITY_DIR 指向它。
+*
+* 为什么不是 mock：禁 mock 的棘轮与设计文档同向——判定逻辑必须读真实文件、验真实签名，
+* 否则「镜像 true + 已授权 → 放行」这条路径就只能靠伪造判定来覆盖，等于没测。
+*
+* **两种形态（验收发现 #1 之后必须显式选）**：
+*   - dev: true（缺省）= 开发形态：同 uid 平面 + $DSH_TRADING_AUTHORITY_DEV_SAME_UID=1，
+*     授权文档带 payload.dev=true。名字里带 dev、每次判定留痕（decision.devMode=true +
+*     一次可见告警）。连接器用例走的就是这一形态——因为它们的判定调用不传选项。
+*   - dev: false = 生产形态：不设 dev opt-in、签名不带 dev 标记。本机同 uid 下制造不出
+*     「平面归另一个 uid」的真实属主，所以要用 fixture.authorityOptions（注入 euid 模拟
+*     生产形态的 uid 关系）去判定；直接 liveTradingEnabled(true) 会按 plane-not-isolated
+*     拒绝 —— 那正是本机同 uid 的诚实结论。
+*/
+function installTestAuthority(options = {}) {
+	const env = options.env ?? process.env;
+	const devMode = options.dev !== false;
+	const previousDir = env[AUTHORITY_DIR_ENV];
+	const previousDev = env[AUTHORITY_DEV_ENV];
+	const dir = mkdtempSync(join(tmpdir(), "dsh-authority-fixture-"));
+	const keyId = "operator-test";
+	const pair = generateOperatorKeyPair(keyId);
+	writeFileSync(join(dir, TRUSTED_KEYS_FILENAME), buildTrustedKeysDocument([{
+		keyId,
+		alg: "ed25519",
+		publicKeyPem: pair.publicKeyPem
+	}]));
+	const sign = (overrides = {}) => {
+		const now = Date.now();
+		writeFileSync(join(dir, GRANT_FILENAME), signLiveTradingGrant({
+			liveTrading: true,
+			issuedAt: (/* @__PURE__ */ new Date(now - 6e4)).toISOString(),
+			expiresAt: expiryFromDays(now, overrides.days ?? options.days ?? 30),
+			operator: overrides.operator ?? options.operator ?? "test-operator",
+			...devMode ? { dev: true } : {}
+		}, pair.privateKeyPem, keyId));
+		resetAuthorityCache();
+	};
+	if (options.withoutGrant !== true) sign();
+	env[AUTHORITY_DIR_ENV] = dir;
+	if (devMode) env[AUTHORITY_DEV_ENV] = "1";
+	else delete env[AUTHORITY_DEV_ENV];
+	resetAuthorityCache();
+	const syntheticEuid = (processEuid() ?? 0) + 12345;
+	return {
+		dir,
+		keyId,
+		privateKeyPem: pair.privateKeyPem,
+		publicKeyPem: pair.publicKeyPem,
+		devMode,
+		authorityOptions: {
+			dir,
+			env: devMode ? { [AUTHORITY_DEV_ENV]: "1" } : {},
+			euid: syntheticEuid
+		},
+		sign,
+		revoke: () => {
+			rmSync(join(dir, GRANT_FILENAME), { force: true });
+			resetAuthorityCache();
+		},
+		uninstall: () => {
+			if (previousDir === void 0) delete env[AUTHORITY_DIR_ENV];
+			else env[AUTHORITY_DIR_ENV] = previousDir;
+			if (previousDev === void 0) delete env[AUTHORITY_DEV_ENV];
+			else env[AUTHORITY_DEV_ENV] = previousDev;
+			resetAuthorityCache();
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		}
+	};
+}
+//#endregion
+export { installTestAuthority };

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@dshtrading/authority",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Live-trading authority plane for dsh-trading: a fail-closed, human-signed (Ed25519) grant outside every agent-writable path. The preset asset's liveTrading flag is demoted to a non-authoritative mirror that can only deny (design doc §5 / invariant 13.3).",
+  "version": "0.6.1",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./sign": {
+      "types": "./lib/sign.d.ts",
+      "default": "./lib/sign.js"
+    },
+    "./testing": {
+      "types": "./lib/testing.d.ts",
+      "default": "./lib/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "@dshtrading/dsh-home": "^0.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsdown": "^0.22.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0",
+    "yaml": "^2.9.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.