@sema-agent/server 7.50.0 → 7.52.0

package/dist/config.js

@@ -2,7 +2,7 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, compileReadDeny, resolveReadDenyBuiltins, CODE_AGENT_PROMPT, formatUserScope, isThinkingLevel, PROTOCOL_TABLE, protocolOf, RECOMMENDED_SENSITIVE_PATTERNS, RETIRED_TOOL_NAMES, resolveLockedKeys, validatePermissionRules } from "@sema-agent/core";
+import { BUILTIN_COMPLIANCE_DENIES, COMPLIANCE_CAPABILITIES, compileReadDeny, resolveReadDenyBuiltins, CODE_AGENT_PROMPT, formatUserScope, isThinkingLevel, PROTOCOL_TABLE, protocolOf, RECOMMENDED_SENSITIVE_PATTERNS, RETIRED_TOOL_NAMES, resolveFileHistoryRetention, resolveLockedKeys, validatePermissionRules } from "@sema-agent/core";
 import { ROSTER_PRIMARY_ROLES, ROSTER_CHEAP_ROLES } from "@sema-agent/settings-schema";
 import { parseApprovalHmacKeys, parsePrincipalJwks } from "./auth-keys.js";
 import { DEFAULT_ELICITATION_THROTTLE } from "./elicitation.js";
@@ -11,6 +11,7 @@ import { DEFAULT_QUESTION_THROTTLE } from "./question.js";
 import { GIT_API_KINDS, isGitApiKind } from "./git-api-kind.js";
 import { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 import { normalizeSshFingerprint } from "./ssh-host-key.js";
+import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
 export { RETENTION_MODES, MEMORY_CONSOLIDATION_MIN_INTERVAL_SEC } from "./config-types.js";
 function csv(name) {
     return (process.env[name] ?? "")
@@ -251,6 +252,15 @@ function optNumEnvStrict(name) {
         return undefined;
     return parseNumOrFail(name, raw);
 }
+function parseFileHistoryRetention() {
+    const raw = process.env.FILE_HISTORY_RETENTION_KEEP;
+    if (raw === undefined || raw === "")
+        return undefined;
+    const keep = raw === "unbounded" ? "unbounded" : /^(?:0|[1-9]\d*)$/.test(raw) ? Number(raw) : raw;
+    const policy = { keep };
+    resolveFileHistoryRetention("FILE_HISTORY_RETENTION_KEEP", policy);
+    return { retention: policy };
+}
 function optFinitePositiveEnv(name) {
     const raw = process.env[name];
     if (raw === undefined || raw === "")
@@ -502,10 +512,10 @@ function parseStoreDomain(ctx) {
         sessionBackend,
         sessionCacheTtlSec: numEnv("SESSION_CACHE_TTL_SEC", "300"),
         storeProbeIntervalMs: numEnvBounded("STORE_PROBE_INTERVAL_MS", "15000", 0, 3_600_000),
-        rewindSnapshotMaxMb: optFinitePositiveEnv("REWIND_SNAPSHOT_MAX_MB"),
         dbBackend,
         dbBackendExplicit: dbBackendSet,
         localDataRoot,
+        runStoreStrictHydrate: parseRunStoreStrictHydrate(process.env.RUN_STORE_STRICT_HYDRATE),
         tidb: needsDb && dbBackend === "mysql"
             ? {
                 host: env("MYSQL_HOST"),
@@ -540,6 +550,7 @@ function parseStoreDomain(ctx) {
             : undefined,
         snapshotBlobSqlMaxBytes: optFinitePositiveEnv("SNAPSHOT_BLOB_SQL_MAX_BYTES"),
         snapshotBlobAllowSql: boolEnv("SNAPSHOT_BLOB_ALLOW_SQL_BYTES", false),
+        fileHistory: parseFileHistoryRetention(),
         sendUserFile: (process.env.MINIO_ENDPOINT || process.env.S3_ENDPOINT) && process.env.MINIO_ACCESS_KEY && process.env.MINIO_SECRET_KEY
             ? {
                 endpoint: (process.env.MINIO_ENDPOINT || process.env.S3_ENDPOINT),
@@ -736,11 +747,17 @@ function parseDegradeOn(words) {
     }
     return words;
 }
+const PRESENTED_NAME_MAX = 160;
+function presentToolName(name) {
+    const clean = name.replace(CONTROL_AND_BIDI_STRIP_RE, "");
+    return clean.length <= PRESENTED_NAME_MAX ? clean : `${clean.slice(0, PRESENTED_NAME_MAX)}…(${name.length} chars)`;
+}
 function ccRuleFormGuidance(name) {
     if (!name.includes("(") && !name.includes(")"))
         return undefined;
-    return (`CC-form rule specifier — this list matches the WHOLE tool name verbatim, so it can only ever match a tool literally named "${name}". ` +
-        `Drop the parentheses to gate the tool itself ("${name.split("(")[0] ?? name}"); ` +
+    const shown = presentToolName(name);
+    return (`CC-form rule specifier — this list matches the WHOLE tool name verbatim, so it can only ever match a tool literally named "${shown}". ` +
+        `Drop the parentheses to gate the tool itself ("${presentToolName(name.split("(")[0] ?? name)}"); ` +
         `to decide per COMMAND use \`runtime.commandPolicy\` ({command, decision} — bare argv[0] names); ` +
         `to put every shell call behind an approval use MANUAL_MODE_SHELL_GATE=always`);
 }
@@ -783,7 +800,7 @@ export function findUnmatchableToolNames(names) {
         const ns = protocolOf(name);
         if (ns === undefined) {
             if (name.includes("__"))
-                out.push({ name, guidance: `pre-prefix short form — the live name carries a protocol prefix: ${PROTOCOL_TABLE.map((e) => `${e.prefix}${name}`).join(" or ")}` });
+                out.push({ name, guidance: `pre-prefix short form — the live name carries a protocol prefix: ${PROTOCOL_TABLE.map((e) => `${e.prefix}${presentToolName(name)}`).join(" or ")}` });
             continue;
         }
         if (ns.parse(name) === undefined) {
@@ -794,9 +811,9 @@ export function findUnmatchableToolNames(names) {
 }
 export function formatUnmatchableToolNames(source, bad) {
     return (`${source} names tool(s) that can never match a live tool (these lists are RAW whole-name comparisons — core 5.0.0 RB-476 removed the alias/auto-prefix folds): ` +
-        bad.map((b) => `${b.name} → ${b.guidance}`).join("; "));
+        bad.map((b) => `${presentToolName(b.name)} → ${b.guidance}`).join("; ")).replace(CONTROL_AND_BIDI_STRIP_RE, "");
 }
-function streamApprovalConfig() {
+function streamApprovalConfig(gates) {
     const cfg = {
         enabled: boolEnv("STREAM_APPROVAL_ENABLED", true),
         windowMs: numEnv("STREAM_ASK_WINDOW_MS", "300000"),
@@ -807,10 +824,15 @@ function streamApprovalConfig() {
         pendingGraceMs: numEnvBounded("STREAM_APPROVAL_PENDING_GRACE_MS", "30000", 0, 3_600_000),
         adhocGraceMs: numEnvBounded("STREAM_APPROVAL_ADHOC_GRACE_MS", "60000", 0, 86_400_000),
         orphanTtlMs: numEnvBounded("STREAM_APPROVAL_ORPHAN_TTL_MS", String(7 * 24 * 60 * 60 * 1000), 60_000, 90 * 24 * 60 * 60 * 1000),
+        unreachedTtlMs: numEnvBounded("UNREACHED_ASK_TTL_MS", String(60 * 60 * 1000), 60_000, 24 * 60 * 60 * 1000),
     };
     if (cfg.windowMs + cfg.adhocGraceMs >= cfg.orphanTtlMs) {
         throw new Error(`env STREAM_ASK_WINDOW_MS=${cfg.windowMs} + STREAM_APPROVAL_ADHOC_GRACE_MS=${cfg.adhocGraceMs} must be STRICTLY LESS than STREAM_APPROVAL_ORPHAN_TTL_MS=${cfg.orphanTtlMs} — the adhoc arm fires at (createdAt + window + grace) while the orphan backstop fires at (createdAt + ttl); if the backstop wins, every adhoc-leg row is attributed "orphan_ttl_exceeded" instead of "adhoc_leg_no_durable_domain" (attribution honesty, design/172 §6.1)`);
     }
+    const suspendedRowsPossible = cfg.enabled && gates.toolApprovalEnabled && gates.unattendedPolicy !== "deny";
+    if (suspendedRowsPossible && cfg.unreachedTtlMs + cfg.adhocGraceMs >= cfg.orphanTtlMs) {
+        throw new Error(`env UNREACHED_ASK_TTL_MS=${cfg.unreachedTtlMs} + STREAM_APPROVAL_ADHOC_GRACE_MS=${cfg.adhocGraceMs} must be STRICTLY LESS than STREAM_APPROVAL_ORPHAN_TTL_MS=${cfg.orphanTtlMs} — an ask minted with NO live stream (case A: a workflow child ask) waits UNREACHED_ASK_TTL_MS, so its row expires at (createdAt + that window); the orphan backstop fires at (createdAt + ttl). If the backstop wins, every suspended row is attributed "orphan_ttl_exceeded" instead of its real cause (attribution honesty, same rule as the STREAM_ASK_WINDOW_MS line above)`);
+    }
     if (!Number.isInteger(cfg.reconcileBatch)) {
         throw new Error(`env STREAM_APPROVAL_RECONCILE_BATCH=${cfg.reconcileBatch} must be an INTEGER row count`);
     }
@@ -829,6 +851,8 @@ function unattendedApprovalPolicyEnv() {
 }
 function parseApprovalDomain(ctx) {
     const { postureOn } = ctx;
+    const unattendedPolicy = unattendedApprovalPolicyEnv();
+    const toolApprovalEnabled = postureOn("TOOL_APPROVAL_ENABLED");
     const directApprovalDoor = boolEnv("DIRECT_APPROVAL_DOOR", false);
     const dgHmacKeys = parseApprovalHmacKeys(process.env.APPROVAL_HMAC_KEYS, announceKeySetRejection("APPROVAL_HMAC_KEYS"));
     const durableApproval = boolEnv("DURABLE_APPROVAL", false);
@@ -896,12 +920,12 @@ function parseApprovalDomain(ctx) {
             maxTotalPerRun: numEnvBounded("QUESTION_MAX_TOTAL_PER_RUN", String(DEFAULT_QUESTION_THROTTLE.maxTotalPerRun), 1, 10_000),
             ttlMs: numEnvBounded("QUESTION_TTL_MS", String(DEFAULT_QUESTION_THROTTLE.ttlMs), 1_000, 3_600_000),
         },
-        toolApprovalEnabled: postureOn("TOOL_APPROVAL_ENABLED"),
+        toolApprovalEnabled,
         permissionRulesEnabled: boolEnv("PERMISSION_RULES_ENABLED", true),
         permissionRulesEnabledExplicit: parseBoolWord("PERMISSION_RULES_ENABLED", process.env["PERMISSION_RULES_ENABLED"]) !== undefined,
         streamAskWindowMarginMs: numEnv("STREAM_ASK_WINDOW_MARGIN_MS", "10000"),
-        streamApproval: streamApprovalConfig(),
-        unattendedApprovalPolicy: unattendedApprovalPolicyEnv(),
+        streamApproval: streamApprovalConfig({ unattendedPolicy, toolApprovalEnabled }),
+        unattendedApprovalPolicy: unattendedPolicy,
         approvalTimeoutSec: numEnv("APPROVAL_TIMEOUT_SEC", "0"),
     };
 }
@@ -932,6 +956,20 @@ function parseMemoryPersistenceCapable(raw) {
         `\`# Memory\` write instruction on a remote execution lane) or ${MEMORY_ENGINE_OFF_WORDS.join(" | ")} (it CANNOT — ` +
         `forces the read-only disclosure). Leave it UNSET to let the engine infer from the mounted roster.`);
 }
+function parseRunStoreStrictHydrate(raw) {
+    const w = (raw ?? "").trim().toLowerCase();
+    if (w === "")
+        return false;
+    if (MEMORY_ENGINE_ON_WORDS.includes(w))
+        return true;
+    if (MEMORY_ENGINE_OFF_WORDS.includes(w))
+        return false;
+    throw new Error(`env RUN_STORE_STRICT_HYDRATE="${raw}" is not a known on/off word — use one of: ${MEMORY_ENGINE_ON_WORDS.join(" | ")} ` +
+        "(the file run-store REFUSES TO BOOT when it cannot list its runs/ directory) or " +
+        `${MEMORY_ENGINE_OFF_WORDS.join(" | ")} (the default: boot anyway with an empty ledger, disclosed by the ` +
+        "file_run_store_hydrate_unreadable error line + the server.run-store.file-hydrate-unreadable counter). " +
+        "An unrecognized value must not fold to the default: that would silently swallow an operator's explicit fail-closed request.");
+}
 const SANDBOX_PKG_SOURCES = ["global", "cn", "custom", "none"];
 function pkgSourceEnv() {
     const v = env("SANDBOX_PKG_SOURCE", "global");
@@ -1137,6 +1175,9 @@ function parseMemoryDomain(ctx) {
         ...(process.env.MEMORY_PROVENANCE !== undefined
             ? { memoryProvenance: enumEnv("MEMORY_PROVENANCE", "carry", ["off", "carry"]) }
             : {}),
+        ...(process.env.MEMORY_CAPTURE_POLICY !== undefined
+            ? { memoryCapturePolicy: enumEnv("MEMORY_CAPTURE_POLICY", "open", ["open", "governed", "capture-required"]) }
+            : {}),
         memoryConsolidationDriver: parseMemoryConsolidationDriver(),
         ...(process.env.DELEGATION_MAX_CONCURRENT !== undefined || process.env.DELEGATION_MAX_PER_SESSION !== undefined
             ? {
@@ -1277,10 +1318,11 @@ function parseOrchestrationDomain(ctx) {
                 adb: ["ADB_SERIAL"],
                 host: [],
                 "local-docker": ["DOCKER_IMAGE"],
+                device: [],
             };
-            const required = Object.hasOwn(REQUIRED_ENVS_BY_LANE, lane) ? REQUIRED_ENVS_BY_LANE[lane] : undefined;
+            const required = Object.entries(REQUIRED_ENVS_BY_LANE).find(([word]) => word === lane)?.[1];
             if (required === undefined) {
-                throw new Error(`REMOTE_EXEC="${lane}" is not an execution lane — valid: e2b | k8s | ssh | adb | host | local-docker. ` +
+                throw new Error(`REMOTE_EXEC="${lane}" is not an execution lane — valid: ${Object.keys(REQUIRED_ENVS_BY_LANE).join(" | ")}. ` +
                     `An unrecognized value used to fall through to the host/in-process lane silently; refusing to start instead (#157).`);
             }
             const missing = required.filter((name) => !process.env[name]);
@@ -1385,9 +1427,19 @@ function parseOrchestrationDomain(ctx) {
                                                         ...(process.env.DOCKER_SANDBOX_ENV ? { env: resolveEnvForward(process.env.DOCKER_SANDBOX_ENV) } : {}),
                                                     }
                                                     :
-                                                        process.env.CONFIG_PROVIDER === "local"
-                                                            ? { provider: "host" }
-                                                            : undefined,
+                                                        process.env.REMOTE_EXEC === "device"
+                                                            ? {
+                                                                provider: "device",
+                                                                ...((n) => (n !== undefined ? { deliveryTimeoutMs: n } : {}))(optNumEnvStrict("DEVICE_DELIVERY_TIMEOUT_MS")),
+                                                                ...((n) => (n !== undefined ? { reconnectGraceMs: n } : {}))(optNumEnvStrict("DEVICE_RECONNECT_GRACE_MS")),
+                                                                ...((n) => (n !== undefined ? { execTimeoutMs: n } : {}))(optNumEnvStrict("DEVICE_EXEC_TIMEOUT_MS")),
+                                                                ...((n) => (n !== undefined ? { maxInflightPerDevice: n } : {}))(optNumEnvStrict("DEVICE_MAX_INFLIGHT_PER_DEVICE")),
+                                                                ...(process.env.DEVICE_SUPERSEDE ? { supersede: enumEnv("DEVICE_SUPERSEDE", "stale_only", ["stale_only", "deny"]) } : {}),
+                                                            }
+                                                            :
+                                                                process.env.CONFIG_PROVIDER === "local"
+                                                                    ? { provider: "host" }
+                                                                    : undefined,
         worktreeIsolation: boolEnv("WORKTREE_ISOLATION_ENABLED", false) && process.env.WORKTREE_REPO_ROOT
             ? {
                 repoRoot: process.env.WORKTREE_REPO_ROOT,
@@ -1651,8 +1703,9 @@ function parseA2aServeSkills(raw) {
     });
 }
 const STORE_GROUP_KEYS = [
-    "sessionBackend", "sessionCacheTtlSec", "storeProbeIntervalMs", "rewindSnapshotMaxMb", "dbBackend", "dbBackendExplicit", "localDataRoot",
-    "tidb", "pg", "dbQueryTimeoutMs", "snapshotBlobStore", "snapshotBlobSqlMaxBytes", "snapshotBlobAllowSql", "sendUserFile",
+    "sessionBackend", "sessionCacheTtlSec", "storeProbeIntervalMs", "dbBackend", "dbBackendExplicit", "localDataRoot",
+    "runStoreStrictHydrate",
+    "tidb", "pg", "dbQueryTimeoutMs", "snapshotBlobStore", "snapshotBlobSqlMaxBytes", "snapshotBlobAllowSql", "fileHistory", "sendUserFile",
 ];
 const MODEL_PLANE_GROUP_KEYS = [
     "gatewayBaseUrl", "gatewayApiKey", "gatewayFallbackUrls", "gatewayMaxRetries", "anthropic", "resilience", "model", "models",
@@ -1666,7 +1719,7 @@ const APPROVAL_GROUP_KEYS = [
 ];
 const MEMORY_GROUP_KEYS = [
     "memoryEngineEnabled", "memoryEngineDir", "memoryEngineRemoteLaneAllowed", "memoryEngineBackend", "memoryScope",
-    "memoryPersistenceCapable", "memorySync", "memoryEmbedder", "memoryOrgAdmissionMode", "memoryDelegationEvidence", "memoryProvenance", "memoryConsolidationDriver", "memoryOrgDirectoryJson", "memoryOrgGrantTtlMs", "memoryOrgUnavailableBackoffMs",
+    "memoryPersistenceCapable", "memorySync", "memoryEmbedder", "memoryOrgAdmissionMode", "memoryDelegationEvidence", "memoryProvenance", "memoryCapturePolicy", "memoryConsolidationDriver", "memoryOrgDirectoryJson", "memoryOrgGrantTtlMs", "memoryOrgUnavailableBackoffMs",
     "projectMemoryEnabled", "syncImportLeaseStaleSec",
 ];
 const AUTH_GROUP_KEYS = [
@@ -1774,7 +1827,7 @@ export function loadConfig() {
         if (dgOperators.length === 0)
             missing.push("OPERATOR_PRINCIPALS (else isOperator is true-for-all)");
         if (!requirePrincipal)
-            missing.push("REQUIRE_PRINCIPAL=true (a direct door is multi-tenant; without it an absent principal is anonymous and the spoofable header governs owner/quota checks)");
+            missing.push("REQUIRE_PRINCIPAL=true (a direct door is multi-tenant; without it an absent principal is anonymous and the self-asserted header governs owner/quota checks)");
         if (missing.length) {
             throw new Error(`DIRECT_APPROVAL_DOOR=true but D-G anchors are missing: ${missing.join(", ")} — refusing to start a half-open direct door (design/80 D-G boot invariant)`);
         }
@@ -1803,6 +1856,25 @@ export function loadConfig() {
             "push. Point the service at a durable store (DB_BACKEND=mysql|pg), or turn the leader off (unset LEADER_ENABLED) " +
             "(#193 车4 件2 / staleness ledger P1-9+P1-10 boot invariant)");
     }
+    {
+        const deviceLane = orchestration.remoteExec?.provider === "device";
+        const deviceSqlStore = (store.dbBackend === "mysql" && store.tidb !== undefined) || (store.dbBackend === "pg" && store.pg !== undefined);
+        if (deviceLane && !deviceSqlStore) {
+            throw new Error(`REMOTE_EXEC=device with DB_BACKEND=${store.dbBackend} and no SQL connection coordinates built is refused ` +
+                "[device-durable-store]: the device registry, the session↔device binding and the device audit trail are all " +
+                "SQL-backed — without a real SQL store the binding lives in this process only, so a restart forgets WHICH device " +
+                "a parked run must resume onto and a second replica cannot see it at all. Note DB_BACKEND alone is not enough: " +
+                "SESSION_BACKEND=memory (or auto with no MYSQL_HOST/PG_HOST) builds no coordinates at all. Configure a durable " +
+                "store (DB_BACKEND=mysql|pg + its *_HOST/*_USER/*_DATABASE), or unset REMOTE_EXEC " +
+                "(device-executor-lane-v2 §4.7 boot invariant)");
+        }
+        if (deviceLane && !dgDurable) {
+            throw new Error("REMOTE_EXEC=device without DURABLE_APPROVAL=true is refused [device-durable-approval]: a personal device goes " +
+                "offline (lid closed, network drop) at arbitrary points, so an in-flight approval that outlives the window MUST " +
+                "have a park exit — without the durable approval store there is none and the run is stuck with nowhere to persist. " +
+                "Set DURABLE_APPROVAL=true, or unset REMOTE_EXEC (device-executor-lane-v2 §4.7 boot invariant)");
+        }
+    }
     EXEC_LANE_NOTICE = buildExecLaneNotice(orchestration.remoteExec);
     return attachConfigGroups({
         ...store,

package/dist/deployment-governance.d.ts

@@ -57,7 +57,7 @@ export interface DurableApprovalSeat {
  */
 export declare function createDurableQuestionGate(live: LiveQuestionFace | undefined): ToolPolicy;
 /**
- * 沙箱 lane 上**相对形**写目标的守卫补层用 env(codex 对抗复审 round1 finding 1,红先复现)。
+ * 沙箱 lane 上**相对形**写目标的守卫补层用 env(codex 交叉复审 round1 finding 1,红先复现)。
  *
  * 缺口:沙箱 lane 的守卫策略拿不到 `rootPath`(沙箱 cwd 不是 server 能猜的,#165 裁定 1),而
  * `DeferredSandboxPathEnv.absolutePath` 对相对形一律报错。core 的 `canonicalizeTarget` 在

package/dist/device-enrollment.d.ts

@@ -0,0 +1,125 @@
+/**
+ * device lane 准入链(design/device-executor-lane-v2 §4.3.2 提交期准入 + §7-T5 enrollment 五件 +
+ * §7-T6 反枚举)—— **纯函数层**:没有 HTTP、没有 WS、没有 core 装配,只有「店 + 判据 → typed 判决」。
+ * 端点(`/v1/devices/*`、`GET /v1/device/ws`)由车A-3/车C 接;它们**必须**经由这里的判决,不得自建判据。
+ *
+ * ── 五件(§7-T5,逐条落在哪儿)────────────────────────────────────────────────────────────────────
+ *  ① TTL —— `DeviceStore.consumeEnrollToken` 的 CAS 谓词 `expires_at > NOW(3)`(**DB 时钟**,§4.6-F18)。
+ *  ② 绑定 principal —— 同一条 CAS 谓词里 `target_tenant/target_subject` 逐字节等值;不匹配 = 拒。
+ *  ③ 消费一次性 CAS —— `consumed_at IS NULL` 谓词 + `rev=rev+1`;**affected=0 时只有同 pubkey 放行**。
+ *  ④ 重用审计 —— 异 pubkey ⇒ `device_enroll_token_reuse` 审计行(告警级);principal 不符 ⇒
+ *     `device_identity_mismatch` 审计行。两条都在**拒绝之前**写,失败即整条请求失败(fail-closed:
+ *     审计写不进去 ≠ 放行)。
+ *  ⑤ 限速 —— {@link DeviceEnrollRateLimiter},注入式。缺席 = **不限速**,所以端点车必须传一个
+ *     (§7-T5 ⑤ 双限速);本层不替它兜底,也不假装限了。
+ *
+ * ── 反枚举(§4.8 + memory `anti-enum-404-ambiguity`)──────────────────────────────────────────────
+ * enrollment 的**全部**拒绝理由(token 不存在 / 过期 / principal 不符 / 被别的 pubkey 用过)在 wire
+ * 上是**同一个** `device.enrollment_invalid`;设备读面的「不存在」与「不是你的」是同一个
+ * `not_found.device`。细分只进审计。
+ *
+ * ── 吊销在途语义(§8-R4)──────────────────────────────────────────────────────────────────────────
+ * `revoked` 是终态:①绑定的 session 后续提交 = `device.revoked`(admitSession 步 2,**先于** presence
+ * 判定);②吊销同事务把连接租约作废并把 `conn_generation` 推进一格 ⇒ 在途连接的每一次带世代谓词的写
+ * 都会影响 0 行,设备侧因此立刻失权(§4.6 步 2);③重新 enrollment = 新 deviceId,不复活旧行。
+ */
+import { DEVICE_RATE_LIMIT_CODE, type DeviceErrorCode, type DeviceOwner, type DeviceRow, type DeviceSessionRow, type DeviceStore, type NewDeviceInput } from "./device-store.js";
+/** typed 拒绝 —— 端点层只负责把它翻成 HTTP(status 已在体内,不许调用方另算)。 */
+export interface DeviceRejection {
+    code: DeviceErrorCode | typeof DEVICE_RATE_LIMIT_CODE;
+    status: number;
+    message: string;
+    /** 限流专用:`Retry-After` 的秒值(附录 A 的 429 族纪律)。 */
+    retryAfterSec?: number;
+}
+export type DeviceOutcome<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reject: DeviceRejection;
+};
+/**
+ * 限速座(§7-T5 ⑤)。**fail-closed**:`check` 抛错 = 拒绝(不是放行)—— 限速器不可用时放行,正是
+ * token 撞库最想要的那一刻。
+ */
+export interface DeviceEnrollRateLimiter {
+    check(key: string): Promise<{
+        allowed: boolean;
+        retryAfterSec?: number;
+    }>;
+}
+export interface EnrollDeviceInput {
+    /** 明文 token(**只**在这里出现,落库前立刻摘要)。 */
+    token: string;
+    /** 请求方**验证过**的复合身份(SSO/凭据链产出,恒不取自可自造头)。 */
+    requester: DeviceOwner;
+    /** 🔴 `deviceId` 与 `owner` **不在**这里:前者恒由 server 铸(调用方选 id = 让请求方挑自己的设备身份,
+     *  与 §6「server 铸 dev_<ulid>」相悖),后者恒取自**验证过的** requester —— 两个字段都不接受请求体供给。
+     *  测试要确定性 id ⇒ 注入 {@link DeviceEnrollmentDeps.mintId},不是从入参开一个口子。 */
+    device: Omit<NewDeviceInput, "deviceId" | "owner">;
+}
+export interface EnrollDeviceValue {
+    device: DeviceRow;
+    /** `true` = 幂等重放(响应丢失重试),`false` = 本次真注册。wire 上两者同为 200 + 同 deviceId。 */
+    replayed: boolean;
+}
+export interface AdmitSessionInput {
+    rootSessionId: string;
+    requester: DeviceOwner;
+    /** 提交体携带的 deviceId(§4.3.2:仅根任务携;缺席 = 沿用绑定)。 */
+    requestedDeviceId?: string;
+}
+export interface AdmitSessionValue {
+    deviceId: string;
+    device: DeviceRow;
+    /**
+     * 判决**当刻**的连接世代(§4.6 fencing token)。
+     *
+     * 🔴 **准入判决是一个快照,不是一把锁**(codex 交叉轮 F4,判真但归属下一车):`admitSession` 返回后、
+     * 调用方真正下发指令前,一次 `revokeDevice` 可以提交 —— 它会作废租约并把 `conn_generation` 推进一格,
+     * 但它**追不回**已经基于旧判决发出去的指令。这不是本层能关掉的窗(§6 注③ 刻意不落指令表,所以持久层
+     * 没有「派发」这个写点可以带谓词);设计给的答案是**在下发边界重新断言世代**(§4.6 步 2/3:每一次带
+     * `conn_generation = ?` 谓词的写影响 0 行 = 本连接已失权 ⇒ 停发并断连)。
+     * 本字段就是那个断言要用的值 —— 车A-3 的 WS 汇聚端**必须**拿它去 fence,拿不到就不要下发。
+     * 残余诚实:窗口上界 = 心跳周期(吊销后设备侧最迟一个心跳失败即失权),§8-R4 对已发指令的账面处置是
+     * 「在途结果帧丢弃 + 审计,对应调用按 outcome-unknown 收尾」。
+     */
+    connGeneration: number;
+}
+export interface DeviceEnrollment {
+    enroll(input: EnrollDeviceInput): Promise<DeviceOutcome<EnrollDeviceValue>>;
+    bindPlacement(input: {
+        rootSessionId: string;
+        deviceId: string;
+        requester: DeviceOwner;
+    }): Promise<DeviceOutcome<DeviceSessionRow>>;
+    admitSession(input: AdmitSessionInput): Promise<DeviceOutcome<AdmitSessionValue>>;
+    revoke(input: {
+        deviceId: string;
+        requester: DeviceOwner;
+        revokedBy: string;
+        reason?: string | null;
+    }): Promise<DeviceOutcome<DeviceRow>>;
+}
+export interface DeviceEnrollmentDeps {
+    store: DeviceStore;
+    /** 缺席 = 不限速(端点车必须传;见文件头注 ⑤)。 */
+    rateLimiter?: DeviceEnrollRateLimiter;
+    /** 测试可注入确定性铸造;默认 `mintDeviceId()`。 */
+    mintId?: () => string;
+}
+export declare function createDeviceEnrollment(deps: DeviceEnrollmentDeps): DeviceEnrollment;
+/**
+ * 进程内固定窗限速(§7-T5 ⑤ 的**默认**实现)。
+ *
+ * 🔴 诚实边界:这是**每副本**的窗。跨副本的真限速属主是既有的 `observability/rate-limit.ts` RateGate
+ * (SQL 后端),端点车把它适配成 {@link DeviceEnrollRateLimiter} 传进来即可 —— 本函数不假装自己是
+ * 那个东西,也不在多副本部署下声称有全局上界。
+ */
+export declare function createFixedWindowRateLimiter(opts: {
+    limit: number;
+    windowMs: number;
+    now?: () => number;
+}): DeviceEnrollRateLimiter;
+//# sourceMappingURL=device-enrollment.d.ts.map

package/dist/device-enrollment.js

@@ -0,0 +1,156 @@
+import { DEVICE_ERROR_CODES, DEVICE_ERROR_STATUS, DEVICE_RATE_LIMIT_CODE, assertDeviceIdShape, assertDeviceOwnerShape, assertDevicePubkeyShape, assertEnrollTokenHashShape, assertRootSessionIdShape, hashEnrollToken, mintDeviceId, } from "./device-store.js";
+function reject(code, message, extra) {
+    return { ok: false, reject: { code, status: DEVICE_ERROR_STATUS[code], message, ...(extra?.retryAfterSec === undefined ? {} : { retryAfterSec: extra.retryAfterSec }) } };
+}
+function rejectEnrollment() {
+    return reject(DEVICE_ERROR_CODES.ENROLLMENT_INVALID, "enrollment token is not valid for this request");
+}
+function rejectNotFound() {
+    return reject(DEVICE_ERROR_CODES.NOT_FOUND, "device not found");
+}
+export function createDeviceEnrollment(deps) {
+    const { store } = deps;
+    const mintId = deps.mintId ?? mintDeviceId;
+    async function rateGate(key) {
+        if (!deps.rateLimiter)
+            return null;
+        try {
+            const verdict = await deps.rateLimiter.check(key);
+            if (verdict.allowed)
+                return null;
+            return reject(DEVICE_RATE_LIMIT_CODE, "too many device enrollment attempts", { retryAfterSec: verdict.retryAfterSec ?? 1 });
+        }
+        catch (err) {
+            return reject(DEVICE_RATE_LIMIT_CODE, `device enrollment rate check unavailable (fail-closed): ${err instanceof Error ? err.message : String(err)}`, { retryAfterSec: 1 });
+        }
+    }
+    async function enroll(input) {
+        assertDeviceOwnerShape(input.requester);
+        assertDevicePubkeyShape(input.device.pubkey);
+        const limited = await rateGate(`enroll:${input.requester.tenant}\u0000${input.requester.subject}`);
+        if (limited)
+            return limited;
+        const tokenHash = hashEnrollToken(input.token);
+        assertEnrollTokenHashShape(tokenHash);
+        const deviceId = mintId();
+        assertDeviceIdShape(deviceId);
+        const result = await store.consumeEnrollToken({
+            tokenHash,
+            requester: input.requester,
+            device: { ...input.device, deviceId, owner: input.requester },
+        });
+        switch (result.outcome) {
+            case "enrolled":
+                return { ok: true, value: { device: result.device, replayed: false } };
+            case "replayed":
+                if (!result.device)
+                    return rejectEnrollment();
+                if (result.device.status === "revoked")
+                    return reject(DEVICE_ERROR_CODES.REVOKED, "device has been revoked");
+                return { ok: true, value: { device: result.device, replayed: true } };
+            case "token_reuse": {
+                const row = await store.getEnrollToken(tokenHash);
+                await store.appendAudit({
+                    event: "device_enroll_token_reuse",
+                    deviceId: row?.consumedDeviceId ?? null,
+                    owner: input.requester,
+                    detail: { consumedAtMs: row?.consumedAtMs ?? null, presentedPubkeyDiffers: true },
+                });
+                return rejectEnrollment();
+            }
+            case "principal_mismatch":
+                await store.appendAudit({ event: "device_identity_mismatch", deviceId: null, owner: input.requester, detail: { at: "enrollment", reason: "token target principal mismatch" } });
+                return rejectEnrollment();
+            case "expired":
+            case "unknown_token":
+                return rejectEnrollment();
+            case "pubkey_taken":
+                await store.appendAudit({ event: "device_identity_mismatch", deviceId: null, owner: input.requester, detail: { at: "enrollment", reason: "pubkey already bound to another device in this tenant" } });
+                return rejectEnrollment();
+        }
+    }
+    async function bindPlacement(input) {
+        assertRootSessionIdShape(input.rootSessionId);
+        assertDeviceIdShape(input.deviceId);
+        assertDeviceOwnerShape(input.requester);
+        const result = await store.bindSession({ rootSessionId: input.rootSessionId, deviceId: input.deviceId, owner: input.requester });
+        switch (result.outcome) {
+            case "bound":
+            case "idempotent":
+                return { ok: true, value: result.row };
+            case "conflict":
+                return reject(DEVICE_ERROR_CODES.CLAIM_CONFLICT, "this session is already bound to a different device");
+            case "device_not_found":
+                return rejectNotFound();
+            case "device_revoked":
+                return reject(DEVICE_ERROR_CODES.REVOKED, "device has been revoked");
+        }
+    }
+    async function admitSession(input) {
+        assertRootSessionIdShape(input.rootSessionId);
+        assertDeviceOwnerShape(input.requester);
+        if (input.requestedDeviceId !== undefined)
+            assertDeviceIdShape(input.requestedDeviceId);
+        const binding = await store.getSessionBinding(input.rootSessionId);
+        if (!binding)
+            return reject(DEVICE_ERROR_CODES.NOT_BOUND, "this session has no device binding");
+        if (binding.owner.tenant !== input.requester.tenant || binding.owner.subject !== input.requester.subject)
+            return rejectNotFound();
+        if (input.requestedDeviceId !== undefined && input.requestedDeviceId !== binding.deviceId) {
+            return reject(DEVICE_ERROR_CODES.IDENTITY_MISMATCH, "the requested device is not the one bound to this session");
+        }
+        const view = await store.readDeviceForAdmission(binding.deviceId, input.requester);
+        if (!view)
+            return rejectNotFound();
+        if (view.row.status === "revoked")
+            return reject(DEVICE_ERROR_CODES.REVOKED, "device has been revoked");
+        if (!view.online)
+            return reject(DEVICE_ERROR_CODES.OFFLINE, "device is not connected");
+        return { ok: true, value: { deviceId: binding.deviceId, device: view.row, connGeneration: view.row.connGeneration } };
+    }
+    async function revoke(input) {
+        assertDeviceIdShape(input.deviceId);
+        assertDeviceOwnerShape(input.requester);
+        const result = await store.revokeDevice({ deviceId: input.deviceId, owner: input.requester, revokedBy: input.revokedBy, reason: input.reason ?? null });
+        switch (result.outcome) {
+            case "revoked":
+            case "already_revoked":
+                return { ok: true, value: result.row };
+            case "not_found":
+                return rejectNotFound();
+        }
+    }
+    return { enroll, bindPlacement, admitSession, revoke };
+}
+export function createFixedWindowRateLimiter(opts) {
+    const now = opts.now ?? (() => Date.now());
+    const windows = new Map();
+    const MAX_WINDOWS = 10_000;
+    const prune = (t) => {
+        for (const [k, w] of windows)
+            if (t - w.startedAtMs >= opts.windowMs)
+                windows.delete(k);
+        if (windows.size <= MAX_WINDOWS)
+            return;
+        const victims = [...windows.entries()].sort((a, b) => a[1].startedAtMs - b[1].startedAtMs).slice(0, Math.floor(windows.size / 2));
+        for (const [k] of victims)
+            windows.delete(k);
+    };
+    return {
+        check: async (key) => {
+            const t = now();
+            if (windows.size >= MAX_WINDOWS)
+                prune(t);
+            const cur = windows.get(key);
+            if (!cur || t - cur.startedAtMs >= opts.windowMs) {
+                windows.set(key, { startedAtMs: t, count: 1 });
+                return { allowed: true };
+            }
+            cur.count += 1;
+            if (cur.count > opts.limit)
+                return { allowed: false, retryAfterSec: Math.max(1, Math.ceil((cur.startedAtMs + opts.windowMs - t) / 1000)) };
+            return { allowed: true };
+        },
+    };
+}
+//# sourceMappingURL=device-enrollment.js.map