@sema-agent/server 7.43.0 → 7.44.0

package/dist/security.js

@@ -1,33 +1,6 @@
 import { uuidv7, PROJECT_ID_REGEX } from "@sema-agent/core";
-// design/158 A4: the env→key-set decoders (parseApprovalHmacKeys / parsePrincipalJwks + their row types) moved to
-// the leaf ./auth-keys.js so config.ts's env-load no longer value-imports this whole auth module (lens2 §F). The
-// verifiers that consume the parsed key-sets now live in ./approval-hmac.js / ./principal-jwt.js (design/158 A13);
-// import all four names from ./auth-keys.js directly ([2354] 兼容面全清 — the compat re-export here is gone).
-import { memoryScopeFor } from "./memory-scope.js"; // design/158 N17: moved to ./memory-scope.js (this file's createAuthorizer still calls it)
-// design/158 A13: the approval-envelope HMAC (integrity) group and the principal-JWT/direct-door (identity)
-// group moved VERBATIM to ./approval-hmac.js and ./principal-jwt.js respectively — this file's own
-// `verifiedPrincipal` still calls verifyPrincipalJwt for the direct-door branch (value import below); every
-// symbol from both groups is re-exported near the bottom of this file so existing importers keep working.
+import { memoryScopeFor } from "./memory-scope.js";
 import { verifyPrincipalJwt } from "./principal-jwt.js";
-/** A SessionStore that may additionally expose tenant-ownership ops (the TiDB store does) AND the
- *  `SessionRepo` enumeration/lifecycle seam (§0.5: list/fork/delete homed on the session abstraction's own
- *  tables, not the `task_run` runs ledger). All optional — an in-memory dev store implements none. */
-/**
- * E6 fail-closed 守卫的辖域判据:**这个请求是不是一次「破坏性会话写」**。
- *
- * 🔴 2026-08-01 复审逮到:守卫原本是**逐条路由白名单**(`PUT …/policy`、`POST …/sync/import`),
- * 而 `DELETE /v1/sessions/:id`(删整条会话)不在其中 —— 同一威胁形、爆炸半径**更大**,却没门。
- *
- * 威胁形逐字同源(守卫自己的注释):「无 service token + 未开 `ALLOW_UNAUTHED_WRITES`」这一形下
- * `sessionOwnerScopeForWrite` 判 fleet-wide ⇒ 集群内**任意**调用方可对**任意** session 动手。
- * policy 腿担心的是「forged principal 能 tighten/DoS 一个会话的工具」;DELETE 直接把会话删掉。
- *
- * ⇒ 枚举改**族判定**:新增一条破坏性会话路由时自动落进门内,不必记得回来加白名单。
- * 这是本仓「同一条论证只在枚举到的路径上执行」这一族的第 N 次,修法统一为把判据提成函数。
- *
- * 辖域**只含**对**既有会话**的破坏性写:改规则 / 整段替换 / 删除 / 分叉(读源会话全历史)。
- * 不含读面,也不含 `POST /v1/tasks` 那条提交腿 —— 它有自己的同族门(别重复拦,双拦会让错误归因变糊)。
- */
 export function isDestructiveSessionWrite(method, url) {
     if (method === "DELETE")
         return /^\/v1\/sessions\/[^/]+$/.test(url);
@@ -37,88 +10,21 @@ export function isDestructiveSessionWrite(method, url) {
         return /^\/v1\/sessions\/[^/]+\/(sync\/import|fork)$/.test(url);
     return false;
 }
-/** [4198] 窄互认第二臂的租户键字面量 —— 单机形下 core 写侧 `spec.principal ?? "default"` 铸出的那一个,
- *  也是壳 [4195]G1 翻面后随请求带的那一个。**不是哨兵**([4183] 措辞):它是单机形的真租户键。 */
 export const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
-/**
- * [4198] 窄互认**第二臂**(clay 裁 A / [4225] 下达;cli [4238] 表态即发)—— `legacyShellOwner`
- * (本文件 createAuthorizer 内 + http/server.ts `runOwnerOk`)的对称孪生。
- *
- * 病灶:7.8.0 第一臂承接的是 `owner === "anon:shell-live"` 哨兵行;此后壳把无主表示法归一为
- * **缺席**,于是 1.0.82 及更早留下的存量会话 owner 列是 **null**。壳 1.0.83 起随请求带
- * `default` 主([4195] G1 闸口),`null !== "default"` ⇒ 存量会话在 session 面
- * **列表不出现 / fork 404 / delete 静默 {deleted:false} / workspace 404**(三面矩阵 [4198] 面3;
- * fleet 面与 run 读面天然连续,面1/面2 零施工)。
- *
- * 🔒 **三条件缺一不放行**(与第一臂同源,不是兼容臂):
- *   ① 单机形 `!requirePrincipal` —— 多租部署本臂**死路**(header 必到、键必具名);
- *   ② 存量行恰为无主 `owner === null` —— 任何具名 owner 的行不受影响;
- *   ③ 调用方恰为 `default` 主 —— 非 default 的具名主对无主行仍走原门(404 / deleted:false)。
- * 反向风险有界:①限定的单机形本就单用户,把无主行判给 default 主不产生跨租泄露。
- *
- * 🪦 墓碑注(与第一臂同源):这是两个表示法之间的**过渡承接**。存量随会话生命周期消亡后,本臂
- * 连同 {@link LEGACY_UNOWNED_AMNESTY_TENANT} 与几处调用点可**整删**,不留兼容层。
- *
- * ── 逐面判过、**刻意不放行**的三处(免得后人当遗漏再补一次)────────────────────────────────
- *  · `runOwnerOk` 三读面(head / audit 单读 / events):`owner === null` 那一支**本来就放行**
- *    (判据是 `owner !== null && principal !== owner`),不需要本臂。[4198] 帖文里「单读 404」一句
- *    经亲读实现行**不成立**,已加现状钉(session-head-probe.test.ts)锁住这个事实。
- *  · `PUT /v1/sessions/:id/policy` 的 `owner === null ⇒ 409 conflict.session_ownerless`:那是**有意的
- *    fail-closed** —— 无主会话没有稳定的 run-principal,存下去的规则读不到、静默失效。放宽它等于制造
- *    一条 fail-open,不在本臂辖域。
- *  · `…/sync/*`(PULL/PUSH/import):PULL 虽是只读、形同 workspace,但这一族**带一条破坏性 import 腿**
- *    (`isDestructiveSessionWrite` 明列),而 [4198]/[4225] 裁的是会话**读面与生命周期**四门。放宽一个
- *    写面族超出裁定射程 —— 要做另立一次表态,不在本臂里顺手带过。
- *
- * @param requirePrincipal `config.requirePrincipal`(条件①)
- * @param gateOwner `sessionOwnerScope(ForWrite)` 判出的**已验证**主(条件③;fleet-wide 面不经本臂)
- * @param owner 存量行的 owner 列(条件②)
- */
 export function legacyUnownedSessionOk(requirePrincipal, gateOwner, owner) {
     return owner === null && legacyUnownedAmnestyOpen(requirePrincipal, gateOwner);
 }
-/**
- * {@link legacyUnownedSessionOk} 的**条件①③**半支 —— 只判「这个部署形 × 这个调用方」是否落在窄臂辖域内。
- *
- * 🔴 单独存在的唯一理由是**列表面**:`GET /v1/sessions` 的第三条件(`owner === null`)不在 JS 里判,
- * 它是 store 侧 `owner = ? OR owner IS NULL` 这一句 SQL 谓词 —— 三条件仍然齐,只是第三条件由 SQL 承载
- * (`listSessions({ owner, includeUnowned })` 的 `includeUnowned` 位即本函数的返回值)。
- * 单实体读/写点(fork/delete/workspace)**一律**用三条件齐的 {@link legacyUnownedSessionOk},不要用本函数。
- */
 export function legacyUnownedAmnestyOpen(requirePrincipal, gateOwner) {
     return !requirePrincipal && gateOwner === LEGACY_UNOWNED_AMNESTY_TENANT;
 }
-/** The shape core's `uuidv7()` mints: canonical 8-4-4-4-12 lowercase hex with version nibble `7` and the RFC-4122
- *  variant (`8`/`9`/`a`/`b`). Used to shape-validate a caller-supplied session id on the §0.5 fork/delete routes so
- *  a crafted id (LIKE metacharacters, over-long, non-canonical) is rejected up front — a SECOND layer behind the
- *  tool-result LIKE-escape, not the only one. NB: deliberately NOT enforced on the task-submission `body.sessionId`
- *  path (the authorizer) — historical callers/tests pass arbitrary short ids there, and the LIKE-escape +
- *  VARCHAR(64) column already neutralize the metacharacter risk; tightening that path is a separate, breaking change.
- *  ASYMMETRY (GAP #15, INTENTIONAL): a client MAY create a session via submit with an arbitrary id (e.g. run-local
- *  `--session foo`, dev anonymous-share ids) yet then CANNOT fork/delete it (those routes 400 a non-uuidv7 id). This
- *  is by design — the wire contract types sessionId as an opaque string, so submit stays permissive; fork/delete add
- *  the uuidv7 gate only as defense-in-depth for store ops on a caller-supplied `:id`. Do NOT add a uuidv7 check to
- *  submit (breaks the contract + run-local + single-tenant dev). The ONE submit-side guard that IS safe and present
- *  is a LENGTH cap (≤64, the column width) in prepareSpec — see server.ts `body.sessionId` check — which prevents a
- *  500/truncation at the INSERT without constraining the id shape. */
 const UUIDV7_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
-/** True iff `s` matches the canonical uuidv7 shape core mints (see {@link UUIDV7_RE}). */
 export function isUuidV7(s) {
     return UUIDV7_RE.test(s);
 }
-/** Canonical uuid of ANY version (v4 legacy shell sessions included) — the SYNC
- *  face's shape gate. Sync stays stricter than submit (arbitrary ≤64 ids) because it is a bulk write
- *  face: the shape still shuts out crafted ids (LIKE metacharacters, over-long), but no longer strands a
- *  v4-keyed legacy session as unsyncable (it was CREATABLE via the lenient submit yet REJECTED by the v7-only
- *  sync gate — a real contradiction). fork/purge/policy keep the v7-only gate (ids we mint ourselves). */
 const UUID_ANY_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 export function isUuidShape(s) {
     return UUID_ANY_RE.test(s);
 }
-/** An HTTP error the server maps to a status code (instead of a generic 500). `code` (optional) is a stable
- *  machine-readable identifier the HTTP layer echoes as `{code}` beside the human `{error}` message — the
- *  "typed rejection" posture (structured code on the wire, prose stays with the shell/web).
- *  `extra` (optional) is folded into the error body verbatim (e.g. the scenario allowlist on a reject). */
 export class HttpError extends Error {
     status;
     code;
@@ -133,46 +39,12 @@ export class HttpError extends Error {
             this.extra = opts.extra;
     }
 }
-/**
- * S6 — close the "sessionId / scope are bearer capabilities" hole.
- *
- * The principal is read from a trusted header set by the authenticated caller (e.g. the OA backend
- * that already holds the service token). It is NOT taken from the request body, so a caller cannot
- * forge identity by passing `scope`/`sessionId` for another tenant.
- *
- * Then:
- *   - a supplied `sessionId` is ownership-checked against `session_meta.owner` (403 on mismatch);
- *     an unknown id is claimed for this principal; a missing id mints a fresh owned session;
- *   - the memory scope is derived from the principal.
- *
- * Returns a function shaped for `ServiceDeps.authorize`. When `sessionStore` is not the TiDB store
- * (e.g. in-memory dev backend) ownership can't be enforced, so it only derives principal + sessionId.
- */
 export function createAuthorizer(config, sessionStore) {
     return async ({ req, body }) => {
-        // F-fix (direct-door principal spoofing, core-steered): the authoritative identity for governance + cost +
-        // ownership + memory + checkpoint scope is the VERIFIED principal, never the spoofable header. This swap covers
-        // every consumer that flows THROUGH the authorizer (spec.principal + cost/owner/memory/checkpoint scope); the
-        // non-authorizer owner/cost sites (runOwnerOk / quotaExceeded / leader / idemKey / the run-route + worker-global
-        // presence gates) call `gatedPrincipal` directly, same invariant. BFF/gated = unchanged (no-op there).
         const principal = verifiedPrincipal(req, config);
         if (config.requirePrincipal && !principal) {
             throw new HttpError(401, `missing principal header '${config.principalHeader}'`);
         }
-        // 142-S4 projectId 线程化(design/142 §2 行为面):body.projectId 是「哪个项目」的选择器,不是身份 —
-        // scope 的 tenant 段永远来自 verified principal(上面),所以它过 SHAPE 门即可。不合形状 = 422 typed
-        // fail-loud(注入串/任意路径段绝不进 scope 键或 config.projects 查表)。RESUME 腿不过此门
-        // (checkpoint 重建 auth 不跑 authorizer)— 持久化 body 在原始提交时已验过,形状不变。
-        //
-        // 🔴 A-033.1(#256)单源换装 + **宽读严写**两半:
-        //  ① 形状词法改从 core 取(`PROJECT_ID_REGEX`,core 自陈「projectId 格式单源」[637]①)。此前取自
-        //    registry-core 的**自持镜像**,而那份镜像与 core 已实证漂移:core 带 `/i`、registry-core 不带 ⇒
-        //    一个 projectId 能过 core 的 scope 面(`parseProjectMarker`/`resolveProjectId` 都认大小写)却被
-        //    本仓的门 422。registry-core 自己的 `types.d.ts` 就挂着「core 公开导出后即改从 core 取」的 TODO。
-        //  ② 收下之后**立即折小写**再往下走 —— core 的铸造面同款纪律(`formatProjectMarker` 亲读:验形用
-        //    带 `/i` 的同一条正则,写盘 `projectId.toLowerCase()`)。这一折是承重的:`formatProjScope` 不做
-        //    任何归一化,不折的话 `proj:<t>/ABC…` 与 `proj:<t>/abc…` 是**两只不同的记忆盘**,同一个项目按
-        //    大小写分家(而 registry-core 的 `ProjectsConfig` 只收小写键 ⇒ 大写形还会在 config.projects 恒 miss)。
         let projectId;
         if (body.projectId !== undefined) {
             if (typeof body.projectId !== "string" || !PROJECT_ID_REGEX.test(body.projectId)) {
@@ -180,69 +52,26 @@ export function createAuthorizer(config, sessionStore) {
             }
             projectId = body.projectId.toLowerCase();
         }
-        // design/114 Phase3 (reuse-path warm-resume): the caller requires the session to ALREADY exist. The authorizer
-        // must NOT claim-create a missing id — that would materialize an empty session_meta row and DEFEAT core's
-        // acquire({requireExisting}) fail-loud, silently turning a resume of a PURGED/EXPIRED session into a fresh empty
-        // run (the exact "looks warm, actually fresh" bug the flag prevents). So with it set: a missing requested id
-        // FAILS LOUD with a clean 404 HERE (eager — before any SSE headers, so BOTH the sync and stream legs get a real
-        // status, not an SSE-buried error) and is NEVER claim-created; a request with NO sessionId is a caller error (the
-        // authorizer would otherwise mint a fresh id — there is no existing session to resume). This is the SERVICE-side
-        // complement to core's store-level fail-loud (which still covers run-local / no-ownerOf backends / direct core):
-        // without it the store never SEES a missing session (the authorizer pre-registers it), so store honoring alone is
-        // inert on the HTTP path.
         const requireExisting = body.requireExistingSession === true;
         const ownerOf = sessionStore.ownerOf?.bind(sessionStore);
         const register = sessionStore.register?.bind(sessionStore);
         const requested = typeof body.sessionId === "string" && body.sessionId ? body.sessionId : undefined;
         let sessionId;
         if (requested) {
-            // 🔴 [2195]:两个能力**解耦判**(旧码是 `if (ownerOf && register)` 一把抓)。它们回答的是两个
-            // 不同的问题:`ownerOf` = 「这个 session 归谁」(判归属),`register` = 「把新 id 记在谁名下」
-            // (能记账)。旧码把两者绑成一个开关,于是 `ownerOf` 在、`register` 缺时,**明明判得了归属却
-            // 整条不判** —— 仓里有一条特征化测试逐字钉着这个结果(principal 直接叫 `user:intruder`,
-            // 注释写「would be a mismatch IF enforced」),它 describe 名却是 "in-memory dev backend",
-            // 而配的是 `requirePrincipal: true`(多租)。描述与执行面脱钩,读标题的人以为那是 dev-only 的事。
             if (ownerOf) {
                 let owner = await ownerOf(requested);
                 if (owner === undefined) {
                     if (requireExisting) {
-                        // design/114 Phase3: the session is genuinely missing (no owner row) AND the caller requires it to
-                        // EXIST → FAIL LOUD with a clean HTTP 404 on BOTH the sync AND the streaming leg. The authorizer runs
-                        // (in prepareSpec) BEFORE any SSE headers are committed, so the stream leg gets a real status code — not
-                        // a `resume.session_not_found` buried in an SSE `done` payload, which a 200-committed stream cannot
-                        // upgrade. We must NOT claim-create it either (that would defeat the fail-loud). The durable stores ALSO
-                        // honor `{requireExisting}` (run-local / a no-ownerOf memory backend / direct core), so the fail-loud
-                        // still holds on the paths that never reach this authorizer.
                         throw new HttpError(404, "requireExistingSession: session does not exist (resume.session_not_found)");
                     }
                     if (register) {
-                        await register(requested, principal ?? null); // unknown id → claim for this principal
-                        // Re-read the authoritative stored owner: register is an idempotent upsert that keeps the
-                        // FIRST owner, so a concurrent first-claim of the same id by another principal could have won
-                        // the race. Without this re-check the loser would silently attach to the winner's session.
+                        await register(requested, principal ?? null);
                         owner = await ownerOf(requested);
                     }
                     else if (config.requirePrincipal) {
-                        // 🔴 [2195] 的第二半:能判归属但**记不了账**。放行的话这个 id 的归属永远不会被写下,
-                        // 于是下一个租户带同一个 id 来,同样看到「不存在」、同样被放行 —— 两个租户共用一条会话,
-                        // 第二个人读得到第一个人的对话。多租下这与「归属不匹配」是同一类越权,同样拒。
                         throw new HttpError(403, "cannot claim a caller-supplied sessionId on a multi-tenant deployment: this worker's session store cannot record session ownership, so the id would stay unowned and the next caller could attach to it. Configure a durable session backend (SESSION_BACKEND), or omit sessionId to start a new session.");
                     }
                 }
-                // Enforce ownership whenever the session HAS an owner — including against callers that present
-                // no principal (audit B — the fix IS this guard, right here in `createAuthorizer`; no line-number
-                // anchor on purpose, the old `security.ts:77` pointer had drifted onto an unrelated JSDoc):
-                // with the old `principal &&` guard, a caller that
-                // omitted the header under requirePrincipal=false could attach to ANY owned session by id.
-                // Anonymous callers may still attach to anonymous (owner=null) sessions, so single-tenant dev
-                // (no principals anywhere) is unaffected; flipping the requirePrincipal default is NOT needed.
-                //
-                // [3262] 存量哨兵窄互认([3260] cli live 取证→本仓裁 (a)):cli ≤1.0.70 对本地单用户自发
-                // `anon:shell-live` header,存量 session 的 owner 列全是这一个哨兵;cli 停发(表示法归一为
-                // 「缺席」,[3239] 复裁)后若仍逐字比对,缺席请求 attach 存量会话恒 401 —— 用户全部既存
-                // resume 即断。互认=同一主体(本地单用户)两个表示法的过渡承接,不是兼容臂:三条件缺一
-                // 不可(单机形 ∧ owner 恰为哨兵字面量 ∧ 请求 principal 缺席),带任何具名 principal 的请求
-                // 对哨兵会话仍走下方 403;多租形 header 必到,本臂不可达。存量随会话生命周期消亡后本臂可整删。
                 const legacyShellOwner = !config.requirePrincipal && owner === "anon:shell-live" && principal === undefined;
                 if (!legacyShellOwner && owner != null && owner !== principal) {
                     throw principal
@@ -251,31 +80,11 @@ export function createAuthorizer(config, sessionStore) {
                 }
             }
             else if (config.requirePrincipal) {
-                // 🔴 [2195](cli 七版实测:bob 续聊 alice 的 session,期望 403 实测 200)的根因修。
-                //
-                // 上面整段 owner 门挂在 `ownerOf && register` 上,而 core 的**默认内存店 `TtlSessionStore`
-                // 这两个方法都没有**。能力缺席时,旧码不是「拒绝」而是让门**整条消失** —— caller 自报的
-                // sessionId 被原样受理,于是多租部署里 bob 直接续聊 alice 的会话。
-                //
-                // 这也解释了 cli 观察到的 GET/POST 不对称:GET 走 `routes/sessions.ts` 的
-                // `deps.sessionStorage.ownerOf`(durable session 面,**另一个对象**)⇒ 判别在场 ⇒ 404;
-                // POST 走这里的 runner sessionStore ⇒ 门蒸发。也解释了为什么按路由 diff 定位不到:
-                // **路由代码没变**,变的是装配里塞进来的 store 实现有没有这两个方法。
-                //
-                // 判据改成 fail-closed:多租形下拿不到归属判别能力,就不能允许复用一个 caller 自报的
-                // sessionId(拒绝的是「复用」,不是「提交」—— 不带 sessionId 的新会话照常受理)。
-                // 单租/dev 形(requirePrincipal=false)零行为变化:那里没有租户边界可越。
-                // ⚠️ 消息必须点名「连本 worker 自己刚铸的 id 也一样」:无 `register` 的 store 上,新会话的
-                // 归属**根本没被记下**,所以第二个 turn 带回引擎自己给的 id 时同样落到这里。不说清楚的话,
-                // 这个 403 从消费端看是纯粹的反直觉(「这 id 是你给我的,你现在说我无权用」)——
-                // 实测:客户端「首 turn 不发 sessionId、后续 turn 带回铸值」这一常见形状,第二个 turn 起必拒。
                 throw new HttpError(403, "session reuse needs an owner-aware session store on a multi-tenant deployment: this worker's session store cannot attest who owns a session, so a sessionId cannot be authorized — including one this worker itself minted a moment ago (without a register seam it was never recorded as yours). Configure a durable session backend (SESSION_BACKEND), or omit sessionId on every turn to start fresh.");
             }
             sessionId = requested;
         }
         else {
-            // design/114 Phase3 (M2 parity): requireExistingSession with NO sessionId is a caller error — the authorizer
-            // mints a fresh id otherwise, so core's own no-sessionId M2 check can never fire on the service path.
             if (requireExisting) {
                 throw new HttpError(422, "requireExistingSession requires a sessionId — there is no existing session to resume (resume.session_not_found)");
             }
@@ -286,113 +95,36 @@ export function createAuthorizer(config, sessionStore) {
         return { principal, sessionId, memoryScope: memoryScopeFor(config, principal, projectId), resolvedProjectId: projectId };
     };
 }
-/** F1/F3 (codex scope-ledger audit 2026-07-14) — the auth-boundary principal SHAPE gate, applied to every
- *  verified identity source (trusted header, SSO-bridge sub, direct-door JWT sub) so no downstream consumer
- *  ever sees an ambiguous or over-wide principal:
- *   - RESERVED internal identifiers are REJECTED (修1, 三路复审 A 组 HIGH — see {@link RESERVED_PRINCIPALS} /
- *     {@link RESERVED_PRINCIPAL_PREFIXES} below): a REAL tenant whose principal string-equals an internal scope
- *     sentinel would pass the plain string-compare owner/scope gates downstream and merge with internal rows —
- *     e.g. `"_"` merges with the anonymous scope family (the checkpoint scope column `auth?.principal ?? "_"`
- *     at suspend, and the decide owner-gate treats `cp.scope === "_"` as anonymous-OPEN, server.ts ~L3710; the
- *     SendUserFile ledger scope + the /v1/sendfile-links fleet-wide default; the resource-suspend isolation
- *     key), `"_leader"` merges with the leader durable-approval owner scope (a tenant so named could list/
- *     decide internal leader approvals), `"_leader-…"` with the leader resource-suspend scope family, and
- *     `"__none__"` with the missing-principal placeholder scope on the decide/pending gates.
- *   - length > 190 is REJECTED: every scope/owner column the principal lands in VERBATIM is VARCHAR(190)
- *     (sendfile_link.scope, approval.owner/scope, memory-engine scope, rate-limit keys, …) — an over-long
- *     principal would truncate/500 at the INSERT and split one identity into two.
- *  Throws a typed 400 `HttpError` (the HTTP layer maps it); the message names the rule (a reserved identifier /
- *  the length cap), never a secret and never the internal scope's semantics. */
 export const PRINCIPAL_MAX_LENGTH = 190;
-/** 修1 — the SINGLE registry of internal sentinel/scope identifiers a tenant principal must never equal.
- *  🔴 新增内部 sentinel scope 必须在此登记(精确值加 RESERVED_PRINCIPALS,前缀族加
- *  RESERVED_PRINCIPAL_PREFIXES),否则 assertPrincipalShape 会放行同名租户 = 与内部 scope 行合流的越权面。
- *  Current entries (where each is minted): `"_"` = single-user/anonymous sentinel (checkpoint/sendfile/
- *  resource-suspend scope family); `"__none__"` = missing-principal placeholder on the decide/pending gates
- *  (http/server.ts `principal ?? "__none__"`); `"_leader"` = leader durable-approval scope
- *  (src/leader/wire.ts); prefix `"_leader-"` = the leader resource-suspend scope family
- *  (`_leader-resource-<workerId>`, src/leader/wire.ts). NB the prefix REQUIRES the hyphen — a tenant named
- *  `_leaderX` collides with nothing internal and stays valid (boundary pinned by test). */
 export const RESERVED_PRINCIPALS = ["_", "__none__", "_leader"];
 export const RESERVED_PRINCIPAL_PREFIXES = ["_leader-"];
 export function assertPrincipalShape(principal) {
     if (RESERVED_PRINCIPALS.includes(principal) || RESERVED_PRINCIPAL_PREFIXES.some((p) => principal.startsWith(p))) {
-        // Wording deliberately names the RULE (reserved internal scope sentinel), not what the sentinel does.
         throw new HttpError(400, `principal ${JSON.stringify(principal)} is reserved (an internal scope sentinel) — authenticate with a real tenant identifier`, { code: "principal_reserved" });
     }
     if (principal.length > PRINCIPAL_MAX_LENGTH) {
         throw new HttpError(400, `principal exceeds ${PRINCIPAL_MAX_LENGTH} characters (the scope-column width every store pins, e.g. sendfile_link.scope VARCHAR(190)); got ${principal.length}`, { code: "principal_too_long" });
     }
 }
-/** The checkpoint `scope` column's single-user/anonymous sentinel — the same "_" documented above
- *  ({@link RESERVED_PRINCIPALS}) as the checkpoint/sendfile/resource-suspend scope family's shared value.
- *  Single attested constant + codec pair (naming precedent: {@link SENDFILE_SINGLE_USER_SCOPE} in
- *  ./plugins/send-file-ledger.js) so every checkpoint scope read/write goes through one place instead of
- *  each call site re-deriving the "_" ⇄ no-principal mapping inline. */
 export const CHECKPOINT_PUBLIC_SCOPE = "_";
-/**
- * 🔴 A-057.44(2026-08-19)—— **后台子代注册簿的匿名租户键**,与上面那只 checkpoint 哨兵是
- * 「同一件事(没有 principal)的两套写法」。
- *
- * 写侧不是本仓能单方面改的:core 的 `treeScope = reviveClaim?.row.scope ?? ctx.principal ??
- * opts.background?.scope` 同时喂**进程内** `defaultTaskRegistry` 与 **durable** 行,而本仓/`core` 全域的
- * 读侧是一整族 `principal ?? "default"`(`runs.ts` markStopSourceForOwner、`boot/session-faces.ts`
- * reapSessionBackground、`http/routes/runs.ts` 的 subagent output/stream 三口、`agents-roster.ts`、
- * `fleet.ts`)。⇒ **把铸点改成 `"_"` 会把这一整族读者一起打瞎**(本车实测:`subagent-tail-content-supply`
- * 的 tail 建连当场 404)。所以归一只能发生在**读侧**:checkpoint 侧拿着 `"_"` 去查 bg 分区时,
- * 显式把这两个键当同一格。
- */
 export const BACKGROUND_REGISTRY_ANON_SCOPE = "default";
-/**
- * checkpoint 的 scope → 该在哪些 **bg 注册簿分区**里找它的 parked 子代(A-057.44)。
- *
- * 匿名(`"_"`)⇒ 两个都查:`"_"`(将来若统一了写侧)与 `"default"`(今天 core 真写下去的那个)。
- * 其余 ⇒ 原样单查:有 principal 时两套约定折出**同一个**串(`encodeCheckpointScope` 只在 null/undefined
- * 时才替换,core 那侧也只在 `ctx.principal` 缺席时才落兜底),不存在第二个候选;而多租户部署里一个
- * **真名叫 `default`** 的租户必须只匹配自己那格 —— 所以别把别名做成双向。
- */
 export function backgroundScopesForCheckpointScope(scope) {
     return scope === CHECKPOINT_PUBLIC_SCOPE ? [CHECKPOINT_PUBLIC_SCOPE, BACKGROUND_REGISTRY_ANON_SCOPE] : [scope];
 }
-/** Encode a principal (or none) as the checkpoint `scope` column value. */
 export const encodeCheckpointScope = (principal) => principal ?? CHECKPOINT_PUBLIC_SCOPE;
-/** Decode a checkpoint `scope` column value back to a principal — {@link CHECKPOINT_PUBLIC_SCOPE} maps to
- *  `undefined` (no principal), everything else passes through verbatim. */
 export const decodeCheckpointScope = (scope) => (scope === CHECKPOINT_PUBLIC_SCOPE ? undefined : scope);
-/** Read the authenticated principal from the trusted header. Never from the body. */
 export function principalFrom(req, config) {
     if (!config.principalHeader)
-        return undefined; // no header configured → no principal (defensive; real config always sets it)
+        return undefined;
     const raw = req.headers[config.principalHeader.toLowerCase()];
     const principal = (Array.isArray(raw) ? raw[0] : raw)?.trim() || undefined;
     if (principal !== undefined)
-        assertPrincipalShape(principal); // F1/F3: reserved-sentinel + length gate at the boundary
+        assertPrincipalShape(principal);
     return principal;
 }
-/** Header carrying the crypto-verified principal JWT on a direct-door worker (the issuer signs it; the worker only
- *  verifies). The trusted twin of `config.principalHeader` (the latter is client-spoofable on a direct door). */
 export const PRINCIPAL_TOKEN_HEADER = "x-approval-principal-token";
-/**
- * direct-door 决策证明三件套的另外两个头名(JWT 在上面那个常量里)。
- *
- * 为什么也具名(2026-08-08,#176 二轮扫描 finding):这三个头名此前在
- * `http/routes/approvals-assistant.ts` 的两个 `verifyDirectDoorProof` 调用点、以及 `http/server.ts` 的
- * CORS `access-control-allow-headers` 串里**各手抄一份**——而 CORS 那一行同一句里已经在用
- * `${principalHeader}` 插值另一个头名,证明具名写法在该处本就可用。改任一头名时漏改 CORS 串的后果
- * 是**静默的**:浏览器预检把该头挡下,请求到不了 handler ⇒ 表现成「direct-door 上审批面莫名失效」,
- * 而不是任何一处报错。低危(改头名本身即 wire BREAKING、不太可能单边发生),但零成本可消。
- */
 export const APPROVAL_MAC_HEADER = "x-approval-mac";
 export const APPROVAL_MAC_KID_HEADER = "x-approval-mac-kid";
-/** The DIRECT-DOOR-SAFE principal — the VERIFIED identity for governance + cost + isolation. On a BFF/gated deployment
- *  the header is already verified upstream (return it); on a direct-door worker the `principalHeader` is client-
- *  spoofable, so identity comes from the crypto-verified `x-approval-principal-token` JWT (the issuer's private key
- *  never lives on a worker). `spec.principal` MUST be this, NEVER `principalFrom` — keying a gate or a bill on a
- *  spoofable header is a multi-tenant governance/cost bypass (core's TaskSpec.principal contract). Single source for
- *  `createAuthorizer` AND every `gatedPrincipal` call site (F-fix: direct-door principal spoofing, core-steered). */
-/** 鉴权桥:请求入口 async 预认证把验过的 registry-JWT principal 挂在这个 symbol 上——它是
- *  request-local 真源(来自签名,非自报头),优先于任何头读取。setSsoPrincipal 在 server.ts 的入口块设,
- *  verifiedPrincipal 在此读。 */
 const SSO_PRINCIPAL = Symbol.for("sema.ssoVerifiedPrincipal");
 export function setSsoPrincipal(req, principal) {
     req[SSO_PRINCIPAL] = principal;
@@ -401,9 +133,6 @@ export function ssoVerifiedPrincipal(req) {
     const v = req[SSO_PRINCIPAL];
     return typeof v === "string" && v.length > 0 ? v : undefined;
 }
-/** 鉴权桥 scope 透传:registry-JWT 的 `scope` claim(多租户活动租户,registry-core 0.3.0+
- *  `VerifiedIdentity.scope`)也挂 request-local——与 principal 同真源(来自签名,非自报头)。用途=可观测/审计
- *  归因,以及未来 scope 级 quota/过滤的读取地基(单一真源)。ABSENT = pre-scope/默认 token,语义"global"。 */
 const SSO_SCOPE = Symbol.for("sema.ssoVerifiedScope");
 export function setSsoScope(req, scope) {
     req[SSO_SCOPE] = scope;
@@ -413,15 +142,13 @@ export function ssoVerifiedScope(req) {
     return typeof v === "string" && v.length > 0 ? v : undefined;
 }
 export function verifiedPrincipal(req, config) {
-    // 鉴权桥优先:registry-JWT 验过的 principal 来自签名,在 directDoor 与 BFF/gated 两种部署都胜出
-    // (directDoor 下原走 x-approval-principal-token,SSO principal 在其之前返回,成为下游的可信身份)。
     const sso = ssoVerifiedPrincipal(req);
     if (sso) {
-        assertPrincipalShape(sso); // F1/F3: the SSO-bridge sub is a verified identity source too — same boundary gate
+        assertPrincipalShape(sso);
         return sso;
     }
     if (!config.directDoorActive)
-        return principalFrom(req, config); // BFF/gated: the header is already verified upstream
+        return principalFrom(req, config);
     const h = req.headers[PRINCIPAL_TOKEN_HEADER];
     const token = (Array.isArray(h) ? h[0] : h) ?? "";
     const sub = verifyPrincipalJwt(token, config.principalJwtPubkeys, {
@@ -429,20 +156,8 @@ export function verifiedPrincipal(req, config) {
         aud: config.principalJwtAud ?? "\0",
         maxTtlSec: config.principalJwtMaxTtlSec,
     })?.sub;
-    // F1/F3: gate the direct-door JWT sub as well — a typed 400 naming the rule beats a silent-null 401 (the
-    // minter must not be able to issue a "_"-sub token that merges with the anonymous scope family downstream).
     if (sub !== undefined)
         assertPrincipalShape(sub);
     return sub;
 }
-// design/158 N17: memoryScopeFor / memoryEngineRemoteLanePosture / memoryEngineBackendFor / memorySpecForRequest
-// moved VERBATIM to the leaf ./memory-scope.js (security.ts's name says auth; these four resolve memory-plane
-// config, unrelated). Import them from ./memory-scope.js directly ([2354] 兼容面全清 — the compat re-export here
-// is gone); this file's own createAuthorizer below still calls memoryScopeFor.
-// design/158 A13: approval-envelope HMAC (integrity, verifyApprovalHmac/approvalHmacMessage/
-// MAX_APPROVAL_REASON_CHARS) and principal-JWT/direct-door proof (identity, verifyPrincipalJwt/
-// approvalBnd/verifyDirectDoorProof) moved VERBATIM to ./approval-hmac.js and ./principal-jwt.js — this file
-// keeps only the authenticator/principal-shape/SSO-mount group (createAuthorizer, verifiedPrincipal,
-// assertPrincipalShape, principalFrom, setSsoPrincipal/setSsoScope). Import the moved names from their
-// new homes directly ([2354] 兼容面全清 — the compat re-exports here are gone).
 //# sourceMappingURL=security.js.map

package/dist/session-leaf-bus.js

@@ -1,44 +1,12 @@
-/**
- * Session leaf-advance bus — the S2 fast path of the session-level SSE subscription
- * ([1196]/[1208]③: an append that lands on THIS replica fans out to watchers synchronously,
- * zero latency on single-replica deployments; cross-replica watchers still ride the probe lane).
- *
- * Deliberately a REPLICA-LOCAL singleton (module state), not a constructor-threaded dependency:
- * the leaf write sits at the bottom of the per-session storage stack (TiDB/Pg `persist()` — a
- * static-factory + N-arg constructor chain away from main.ts), while the one consumer
- * (SessionWatchRegistry.notifyLocal) is replica-local by design. A bus keeps the wiring one line
- * per write site and one line in main; anything smarter re-plumbs four layers for the same effect.
- *
- * Contract:
- *  - `emitLeafAdvance` MUST be fire-and-forget from the writer's perspective: it never throws
- *    (listener errors are swallowed) and does no async work — a broken watcher must not fail or
- *    slow a session write.
- *  - Emit AFTER the storage commit succeeds (a rolled-back CAS must not fan out a leaf that never
- *    became durable).
- *  - Owner IS carried and MUST be the COMMIT-TIME row owner (codex two rounds: without owner the
- *    generation fence is skipped; a wake-time snapshot is worse — stale-A over a reclaimed row false-
- *    matches an old A entry and leaks the new tenant's leaf into the old stream). Zero-cost source:
- *    the persist transaction's own leaf_seq SELECT carries the owner column — the emitted owner is the
- *    row's tenant at the moment the write committed.
- *  - `leafSeq`(the row's committed leaf_seq)rides every emit: DB commits serialize, but the
- *    post-commit continuations don't — without an ordering token a delayed leaf-N delivery after
- *    leaf-N+1 would walk the registry BACKWARD (and a stale notification could false-drop a newer
- *    generation on owner mismatch). The registry keeps the highest accepted seq and ignores lower.
- *  - The local (file/in-mem) lane does not emit: those sessions persist inside core's storage
- *    backend with no server-side write hook; the probe lane covers them at its normal cadence.
- */
 let listener;
-/** main.ts wires this once at boot (→ SessionWatchRegistry.notifyLocal). Last write wins; tests reset with undefined. */
 export function setLeafAdvanceListener(fn) {
     listener = fn;
 }
-/** Called by the SQL session-storage write sites post-commit. Never throws, never awaits. */
 export function emitLeafAdvance(sessionId, leafId, owner, leafSeq) {
     try {
         listener?.(sessionId, leafId, owner, leafSeq);
     }
     catch {
-        /* a broken watcher must never fail a session write */
     }
 }
 //# sourceMappingURL=session-leaf-bus.js.map

package/dist/session-sync-content.js

@@ -1,70 +1,9 @@
-/**
- * session-sync 的**内容判据**——回答一个 id-集合分类器回答不了的问题:
- * 「两条 entry id 集合相等的日志,**内容**是否也相同?」
- *
- * ── 为什么需要它(深挖第一轮 + 2026-07-26 顺着往下查出的第二半)────────────────────────────────────
- * §7 的 `classifySyncRelationshipByIds` 只比 **id 集合**,而 entry id 是 uuidv7、**不是内容寻址** ⇒
- * 「同 id、异载荷」结构上完全可能(wire 本身就收调用方给的 entries)。第一半的后果已知:Phase A 判 `identical`
- * ⇒ 整段跳过、调用方拿 200 而目的端仍是自己那份内容(真 HTTP 复现过)。
- *
- * 🔴 **第二半是我一开始判错的地方**:我在黑板 [1701] 说「server 单方面修不了」。那句只对 **Phase A** 成立
- * (那时 server 手上没有源端内容,必须靠调用方送摘要)。但 **commit 时 server 同时握着两份日志**
- * (staged + dst),所以内容比较**根本不需要调用方配合** —— 而 4 处 commit/import 路径当时都写着
- * 「`relation === "identical"` ⇒ 跳过 entries 写入」,把「id 集合相等」当成了「内容相同」。
- * 后果:一个**已经把整条日志上传完**的调用方(没送摘要、或送了但不可比),在 commit 处仍然拿到 no-op。
- * ⇒ 两半都要修:Phase A 需要调用方的 `logDigest`(省掉无谓上传),commit 这一半是 server 自己的活。
- *
- * ── 判据来源:core 1.414 导出的 `sessionLogDigest` ──────────────────────────────────────────────────
- * 覆盖每条 entry 的**全部字段**(id / parentId / type / timestamp / 载荷)且**顺序显著**,逐条带长度前缀
- * (所以两份日志不可能被重新切分成同样的字节)。core 明确它可以两端各算 —— 与 `boundInputHash` 不同,
- * 因为这里**分叉的代价是多同步一趟,不是错答案、也不是拒绝**(审批路径上分叉会拒掉一个合法的人类决定,
- * 方向相反)。
- *
- * ── ⚠️ v1 摘要下本判据的**退化行为**(core 黑板 [1709];1.415.0 已修,现行下限已远高于此 ——
- *     承重下限与理由见 `test/core-dependency-floor.test.ts`,别在这里记版本号)────────────────
- * v1 的摘要区分 `{a: undefined}` 与 `{}`,而 core 自己成规模产 own-key=undefined 的 entry ⇒ 同一份日志的
- * 内存形与 JSON 往返形摘要必然不同。本函数在 commit 处比的是 **staged**(刚从 wire 解析,JSON 形)与 **dst**
- * (从存储读回,也是 JSON 形)—— 两侧同形,所以**这一处**不受那条影响;但若某个后端把 staged 留在内存形,
- * 判据会退化成「恒不相等 ⇒ 恒改写」。
- * 🔴 那个退化方向是**安全**的(多写一遍,不会丢数据),这是刻意选的:判据不确定时**宁可改写**,
- * 因为反方向的错(误判"内容相同"而跳过写入)正是本函数要修的那个缺陷。
- * ⇒ 所以这里**不加 scheme 门**。(Phase A 那条路曾加过 scheme **名字门**,后被 tsc 判恒真并撤掉,
- *   换成「依赖下限 + 行为门」—— 名字门只认识旧名字,守不住这条性质;见 server.ts Phase A 段注释与
- *   `test/sync-content-digest.test.ts`。)
- *
- * ⚠️ 抽成共享函数而不是在 4 处各写一遍:core [1689] RB-74 的教训(宣布"同族类修完成"而三个实现只落了一个),
- * 本仓今天也刚在 33 处 exec→FileError 包装上吃过同款。判据收成一处,才谈得上机器看守。
- */
 import { sessionLogDigest } from "@sema-agent/core";
-/**
- * id 集合已判 `identical` 的两条日志,**内容是否真的相同**。
- *
- * `true`  ⇒ 内容也相同,跳过 entries 写入是**对的**(只需 owner 重戳)。
- * `false` ⇒ **同 id 异内容**:必须真正改写目的端,否则调用方拿到的是一句"已同步"的谎。
- *
- * 🔴 这里**不抛错、不拒绝**:core 定的消费口径是「digest 不符永远不得变成 error / 409 / 拒绝同步」——
- * 不符只意味着"多干一趟活",而不是"这次同步非法"。
- */
 export function identicalIdsAlsoIdenticalContent(staged, dst) {
     if (dst === null)
-        return false; // 目的端没有日志 ⇒ 谈不上"内容相同",按需改写
+        return false;
     return sessionLogDigest(staged) === sessionLogDigest(dst);
 }
-/**
- * `fast_forward` 的**内容判据**([2557] 审计 A5/F2,2-i)——id 分类器的另一格盲区:
- * `dst ⊆ src` 只说明 **id 集合**是子集,共享 id 的**载荷**可能已分叉(目的端把某条 entry
- * 补写/纠正过、id 不变,源端拿着旧版本 + 新追加)。此时按「clean append」整段换装,
- * 目的端那几条纠正会被**静默销毁** —— §7「会丢目的端历史必须 409(除非显式 overwrite-dst)」
- * 在载荷层同样成立。与 `identical` 格的口径**方向不同**是刻意的:identical 格 core 已定
- * 「不符=多干一趟活、照常改写」(那里 src 按 id 完整覆盖 dst,push 语义=以源为准);本格
- * dst 的共享版本与 src 的追加互为对方没有的东西,是真分叉,归 409 那一族。
- *
- * 入参:`stagedShared` = staged 里 id ∈ dst 集合的那部分(**staged 顺序**);`dst` = 目的端全量
- * (**dst 顺序**)。两侧都保留各自顺序 —— 摘要顺序显著,共享段的**乱序**同样是分叉。
- *
- * 返回 `null` = 无分叉(安全 append);返回非空数组 = 分叉的 entry id(dst 顺序):
- * 逐条单 entry 摘要不等的 id;若逐条全等而整段摘要不等(纯乱序),列出位置错开的 id。
- */
 export function fastForwardSharedContentDiverged(stagedShared, dst) {
     if (sessionLogDigest([...stagedShared]) === sessionLogDigest([...dst]))
         return null;
@@ -82,13 +21,6 @@ export function fastForwardSharedContentDiverged(stagedShared, dst) {
     }
     return diverged;
 }
-/**
- * 把 fast_forward 的内容级分叉铸成 §7 冲突载荷(SyncConflictError.relation,wire 上是 409 的
- * `{relation}` 详情)。用现有 `fork` 成员而不是扩词表:内容层它**就是** fork(双方各握着对方
- * 没有的东西),且 SDK/客户端的关系词表是闭集,扩成员=BREAKING。字段口径(内容级,与 id 级
- * 注释的措辞差异在此登记):`srcExclusive` = 源端要追加的新 id;`dstExclusive` = 目的端将被
- * 销毁的共享版本的 id;`commonAncestor` = null(未逐条定位分叉点 —— 定位成本与收益不配)。
- */
 export function contentForkRelation(divergedIds, newEntryIds) {
     return { relation: "fork", commonAncestor: null, srcExclusive: [...newEntryIds], dstExclusive: [...divergedIds] };
 }