@sema-agent/server 7.146.0 → 7.148.0

package/dist/orchestration/workflow-completion-inbox.js

@@ -1,12 +1,16 @@
-import { mkdirSync, openSync, writeSync, fsyncSync, closeSync, renameSync } from "node:fs";
+import { openSync, writeSync, fsyncSync, closeSync } from "node:fs";
+import { OWNER_ONLY_FILE_MODE, atomicWriteFileSync } from "../plugins/owner-only-file-mode.js";
 import { join } from "node:path";
 import { redactSecrets } from "../trace/redact.js";
 import { seatText } from "../trace/exit-seat.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { INBOX_PAYLOAD_MAX_BYTES } from "../plugins/inbox-payload-column.js";
 import { injectionTierOrAbsent } from "../trace/injection-tier.js";
-import { semaProvenanceOrAbsent } from "../trace/sema-provenance.js";
-import { resupplyFields, terminalFrameFacetFields } from "../trace/task-notification-facets.js";
-import { taskNotificationDedupKey } from "@sema-agent/core";
+import { semaProvenanceFields } from "../trace/sema-provenance.js";
+import { resupplyFields, sessionBoxCarrierFields, terminalFrameFacetFields } from "../trace/task-notification-facets.js";
+import { ensureDir, taskNotificationDedupKey } from "@sema-agent/core";
+import { keyAdmits, ownerCellOf, recoveredSubject } from "../owner-faces.js";
 export const MAX_PENDING_PER_SESSION = 100;
 export const COMPACT_EVERY = 512;
 export const PURGE_FENCE_MS = 10 * 60 * 1000;
@@ -155,7 +159,7 @@ export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox
         super(onWarn);
         this.fsyncEnabled = fsyncEnabled;
         this.dir = join(root, "workflow-completion-inbox");
-        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        ensureDir(this.dir);
         this.ledgerPath = join(this.dir, "inbox.jsonl");
         this.replay();
         this.compact();
@@ -187,7 +191,7 @@ export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox
     }
     commit(rec) {
         if (this.fd === undefined)
-            this.fd = openSync(this.ledgerPath, "a", 0o600);
+            this.fd = openSync(this.ledgerPath, "a", OWNER_ONLY_FILE_MODE);
         writeSync(this.fd, `${JSON.stringify(rec)}\n`);
         if (this.fsyncEnabled)
             fsyncSync(this.fd);
@@ -202,35 +206,11 @@ export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox
             closeSync(this.fd);
             this.fd = undefined;
         }
-        const tmp = `${this.ledgerPath}.tmp.${process.pid}`;
         const lines = [];
         for (const q of this.bySession.values())
             for (const entry of q.values())
                 lines.push(JSON.stringify({ op: "enqueue", entry }));
-        const tfd = openSync(tmp, "w", 0o600);
-        try {
-            if (lines.length)
-                writeSync(tfd, `${lines.join("\n")}\n`);
-            if (this.fsyncEnabled)
-                fsyncSync(tfd);
-        }
-        finally {
-            closeSync(tfd);
-        }
-        renameSync(tmp, this.ledgerPath);
-        if (this.fsyncEnabled) {
-            try {
-                const dfd = openSync(this.dir, "r");
-                try {
-                    fsyncSync(dfd);
-                }
-                finally {
-                    closeSync(dfd);
-                }
-            }
-            catch {
-            }
-        }
+        atomicWriteFileSync(this.ledgerPath, lines.length ? `${lines.join("\n")}\n` : "", { durability: "best-effort" });
         this.appendsSinceCompact = 0;
     }
     async enqueue(entry) {
@@ -274,18 +254,60 @@ function readEntryExtras(payload) {
     }
     return typeof extras === "object" && extras !== null && !Array.isArray(extras) ? extras : {};
 }
-function encodeWorkflowCompleteExtras(extras) {
+const STREAM_KEY_FIELDS = { task_type: true, task_id: true, status: true, seq: true, attempt: true };
+const ATTRIBUTION_MEMBERS = ["_sema_provenance", "agentMessage", "crossSessionMessage"];
+export const INBOX_SUMMARY_WITHHELD = "[payload over budget: summary withheld; see payloadTruncated]";
+function encodeInboxBody(summary, body, at) {
+    const full = JSON.stringify(body);
+    const bytes = Buffer.byteLength(full, "utf8");
+    const out = bytes <= INBOX_PAYLOAD_MAX_BYTES ? { summary, payload: full } : trimToBudget(summary, body, bytes, at);
+    return { summary: out.summary, payload: out.payload };
+}
+function trimToBudget(summary, body, bytes, at) {
+    const present = Object.entries(body).filter(([, v]) => v !== undefined);
+    const attributed = present.some(([k]) => ATTRIBUTION_MEMBERS.includes(k));
+    const minimal = (keepProvenance) => {
+        const kept = {};
+        const droppedKeys = [];
+        for (const [k, v] of present) {
+            if (Object.hasOwn(STREAM_KEY_FIELDS, k) || (keepProvenance && k === "_sema_provenance"))
+                kept[k] = v;
+            else
+                droppedKeys.push(k);
+        }
+        const withhold = attributed && !Object.hasOwn(kept, "_sema_provenance");
+        if (withhold)
+            droppedKeys.push("summary");
+        const payloadTruncated = { droppedKeys, bytes };
+        return { summary: withhold ? INBOX_SUMMARY_WITHHELD : summary, payload: JSON.stringify({ ...kept, payloadTruncated }), droppedKeys };
+    };
+    const withProvenance = minimal(true);
+    const out = Buffer.byteLength(withProvenance.payload, "utf8") <= INBOX_PAYLOAD_MAX_BYTES ? withProvenance : minimal(false);
+    recordFailOpen("server.workflow-completion-inbox.payload-over-budget", `sessionId=${at.sessionId} key=${at.key} bytes=${String(bytes)} budget=${String(INBOX_PAYLOAD_MAX_BYTES)} dropped=${out.droppedKeys.join(",")}`);
+    return out;
+}
+function readPayloadTruncated(v) {
+    if (typeof v !== "object" || v === null)
+        return undefined;
+    const { droppedKeys, bytes } = v;
+    return Array.isArray(droppedKeys) && droppedKeys.every((k) => typeof k === "string") && Number.isSafeInteger(bytes) && bytes >= 0
+        ? { droppedKeys: droppedKeys, bytes: bytes }
+        : undefined;
+}
+function encodeWorkflowCompleteExtras(summary, extras, at) {
     const body = {
         ...(extras.completionId ? { completionId: extras.completionId } : {}),
         ...(extras.diagnostics ? { diagnostics: extras.diagnostics } : {}),
     };
-    return Object.keys(body).length > 0 ? { payload: JSON.stringify(body) } : {};
+    return Object.keys(body).length > 0 ? encodeInboxBody(summary, body, at) : { summary };
 }
 function workflowCompleteFrameExtras(payload) {
-    const { completionId, diagnostics } = readEntryExtras(payload);
+    const { completionId, diagnostics, payloadTruncated } = readEntryExtras(payload);
+    const truncated = readPayloadTruncated(payloadTruncated);
     return {
         ...(typeof completionId === "string" && completionId !== "" ? { completionId } : {}),
         ...(typeof diagnostics === "string" && diagnostics !== "" ? { diagnostics } : {}),
+        ...(truncated !== undefined ? { payloadTruncated: truncated } : {}),
     };
 }
 export function buildWorkflowCompleteInboxEntry(route, p, enqueuedAt) {
@@ -294,9 +316,8 @@ export function buildWorkflowCompleteInboxEntry(route, p, enqueuedAt) {
         owner: route.owner,
         runId: p.runId,
         status: p.status,
-        summary: p.summary,
         enqueuedAt,
-        ...encodeWorkflowCompleteExtras({ completionId: p.completionId, diagnostics: p.diagnostics ? seatText("inbox-diagnostics-text", p.diagnostics) : undefined }),
+        ...encodeWorkflowCompleteExtras(p.summary, { completionId: p.completionId, diagnostics: p.diagnostics ? seatText("completion-diagnostics-text", p.diagnostics) : undefined }, { sessionId: route.sessionId, key: p.runId }),
     };
 }
 export async function emitPendingWorkflowCompletions(inbox, sessionId, callerPrincipal, emit, diag) {
@@ -318,7 +339,7 @@ export async function emitPendingWorkflowCompletions(inbox, sessionId, callerPri
     }
     for (const e of entries) {
         try {
-            if (e.owner !== null && e.owner !== callerPrincipal) {
+            if (!keyAdmits("inbox.drain", { subject: recoveredSubject(callerPrincipal), operator: false }, ownerCellOf(e.owner))) {
                 await inbox.ack(sessionId, e.runId);
                 dlog("workflow_complete_dropped_owner_mismatch", { route: diag?.route, sessionId, runId: e.runId });
                 continue;
@@ -384,24 +405,22 @@ export function taskNotificationInboxEntry(sessionId, owner, n, enqueuedAt, pare
         ...(n.result ? { result: cap(redactSecrets(n.result), 4000) } : {}),
         ...(n.output_file ? { output_file: cap(redactSecrets(n.output_file), 1024) } : {}),
         ...(n.agentMessage !== undefined ? { agentMessage: { from: n.agentMessage.from, body: cap(redactSecrets(n.agentMessage.body), 4000) } } : {}),
-        ...(() => {
-            if (n._sema_provenance === undefined)
-                return {};
-            const p = semaProvenanceOrAbsent(n._sema_provenance);
-            return p !== undefined ? { _sema_provenance: p } : {};
-        })(),
+        ...semaProvenanceFields(n, "inbox-frame-text"),
         ...terminalFrameFacetFields(n),
         ...resupplyFields(n),
+        ...sessionBoxCarrierFields(n, "inbox-frame-text"),
     };
+    const runId = taskNotificationFoldKey(n);
+    const out = encodeInboxBody(cap(redactSecrets(n.summary ?? ""), 4000), { ...extras, task_id: n.task_id }, { sessionId, key: runId });
     return {
         sessionId,
         owner,
-        runId: taskNotificationFoldKey(n),
+        runId,
         status: n.status === "completed" ? "completed" : "failed",
-        summary: cap(redactSecrets(n.summary ?? ""), 4000),
+        summary: out.summary,
         enqueuedAt,
         kind: "task_notification",
-        payload: JSON.stringify({ ...extras, task_id: n.task_id }),
+        payload: out.payload,
     };
 }
 export async function resolveCompletionRoute(p, getRun, requirePrincipal) {

package/dist/org-delivery-gate.d.ts

@@ -24,9 +24,10 @@
  *     收件人串交给组织目录去查,而目录的每主体状态按属主裁定不淘汰、它的量级只在「查的都是验过的主体」时有界(`org-memory-admission.ts`
  *     的 `PrincipalState` 注);这一界让「一个成员拿任意串去刷目录」的速率与总量随时间线性有界(设计稿收件人查询面第四条:查询限流)。
  *     与收件人无关 ⇒ 它的 `rate_limited` 不泄露收件人存不存在。
- *  1. **成员判**(纯读):不同 org / 查无此人 / 目录不可用 / 收件人串过不了主体形判 / 收件人当不了收件箱的身份键(良构 Unicode ∧ 无控制字符 ∧
- *     UTF-8 字节不超过键列宽 —— 两方言收件箱写面与读面同读的唯一判官 `mailbox-store-sql.ts` 的 `mailboxKeyProblem`)⇒ 同一句 `not_member`,逐字节同 ——
- *     门永远不是一只存在性探针(core 契约原句),也不说「是长度」。收件人那一判必须在配额之前:第 5 步的追加按同一只判官拒,拒在扣了投递额度之后就是「吃了额度没投到」。
+ *  1. **成员判**(纯读):不同 org / 查无此人 / 目录不可用 / 收件人串过不了主体形判 ⇒ 同一句 `not_member`,逐字节同 ——
+ *     门永远不是一只存在性探针(core 契约原句),也不说「是长度」。主体形判(名字 ∧ 良构 Unicode ∧ 无控制字符 ∧ ≤ `PRINCIPAL_MAX_BYTES` UTF-8 字节)**蕴含**收件箱键判官
+ *     (`mailbox-store-sql.ts` 的 `mailboxKeyProblem`:非空 ∧ 良构 ∧ 无 C0 / DEL ∧ ≤ 同一只常量字节;收件人 scope 就是这只键)⇒ 收件人过了这一判,第 5 步的追加不会再按键判拒,
+ *     「吃了额度没投到」只剩追加失败这一种 —— 门里不另问键判官(零双判;蕴含性质钉在 `test/principal-one-byte-ruler.test.ts`)。收件人那一判必须在配额之前。
  *  2. **铸信**(纯函数):放在任何有副作用的步骤之前。发件人的 scope 拼不进信封的发件人位(引擎按百分号编码后 1..190 字节判,抛闭集码
  *     `cross_session.invalid_from_scope`,`CrossSessionCodecError` 由引擎包根导出)⇒ 同一句 `not_member`、一个配额名额都没吃 —— 发件人这一侧的判官只有引擎这一只,
  *     本仓不另抄宽度公式。部署没声明收件箱消费方(`no_consumer`)或别的铸信失败 ⇒ 门抛(core:「the gate maps that to its own failure」),HTTP 面答 500,同样没吃额度。
@@ -57,7 +58,7 @@ export declare const PRINCIPAL_INBOX_BOUND = 50;
 /**
  * 四只拒绝词各自的那**一句**(wire 上的 `error` 就是它,`routes/principal-inbox.ts` 原样中继、不手抄)。
  * 键集 = core 闭集:core 加词 ⇒ 这张表编译红。
- * `not_member` 一句同时服务「不同 org / 查无此人 / 目录答不上来 / 收件人串不成形 / 收件人当不了收件箱的键 / 发件人主体拼不进信封的发件人位」—— 改它要保持各臂同字节。
+ * `not_member` 一句同时服务「不同 org / 查无此人 / 目录答不上来 / 收件人串不成形 / 发件人主体拼不进信封的发件人位」—— 改它要保持各臂同字节。
  */
 export declare const ORG_DELIVERY_REFUSAL_MESSAGES: Readonly<Record<OrgDeliveryRefusalCode, string>>;
 export interface OrgDeliveryGateDeps {

package/dist/org-delivery-gate.js

@@ -1,6 +1,7 @@
 import { CrossSessionCodecError, MAILBOX_TOMBSTONED_RECIPIENT_CODE, PRINCIPAL_INBOX_HANDLE, peerSessionBoxHandle, mintCrossPrincipalRecord, uuidv7, } from "@sema-agent/core";
-import { principalShapeProblem } from "./security.js";
-import { mailboxKeyProblem } from "./stores-sql/mailbox-store-sql.js";
+import { principalShapeProblem } from "./principal-shape.js";
+import { personOf } from "./owner-brands.js";
+import { recoveredSubject } from "./owner-faces.js";
 export const ORG_DELIVERY_QUOTA = Object.freeze({ windowMs: 3_600_000, attemptsPerSender: 60, perPair: 10, perRecipient: 30 });
 export const PRINCIPAL_INBOX_BOUND = 50;
 export const ORG_DELIVERY_REFUSAL_MESSAGES = Object.freeze({
@@ -17,15 +18,15 @@ async function shareAnOrg(directory, a, b) {
     return Object.keys(la.scopes).some((org) => Object.hasOwn(lb.scopes, org));
 }
 const principalShaped = (s) => principalShapeProblem(s) === undefined;
-const fitsInboxKey = (recipient) => mailboxKeyProblem("scope", recipient) === undefined;
 export function createOrgDeliveryGate(deps) {
     const nowMs = deps.nowMs ?? Date.now;
     const mintReceiptId = deps.mintReceiptId ?? uuidv7;
     return {
         async deliverCrossPrincipal(authedFrom, toPrincipal, body) {
-            if (!(await deps.quota.admitAttempt(authedFrom.scope, ORG_DELIVERY_QUOTA)))
+            const senderPerson = personOf(recoveredSubject(authedFrom.scope));
+            if (!(await deps.quota.admitAttempt(senderPerson, ORG_DELIVERY_QUOTA)))
                 return refuse("org_delivery.rate_limited");
-            if (!principalShaped(toPrincipal) || !fitsInboxKey(toPrincipal) || !(await shareAnOrg(deps.directory, authedFrom.scope, toPrincipal))) {
+            if (!principalShaped(toPrincipal) || !(await shareAnOrg(deps.directory, senderPerson, toPrincipal))) {
                 return refuse("org_delivery.not_member");
             }
             const toScope = toPrincipal;
@@ -41,7 +42,7 @@ export function createOrgDeliveryGate(deps) {
             }
             if ((await deps.mailbox.peekCount(toScope, PRINCIPAL_INBOX_HANDLE)) >= PRINCIPAL_INBOX_BOUND)
                 return refuse("org_delivery.inbox_full");
-            if (!(await deps.quota.take(authedFrom.scope, toScope, ORG_DELIVERY_QUOTA)))
+            if (!(await deps.quota.take(senderPerson, toScope, ORG_DELIVERY_QUOTA)))
                 return refuse("org_delivery.rate_limited");
             let seq;
             try {

package/dist/org-memory-admission.d.ts

@@ -16,12 +16,13 @@
  * (请求来源的 scope 没有调用方 ⇒ 引擎在自己的门上先拒,不问本解析器)—— 本模块按这一判别式分支,不另判一次缺席;
  * 引擎型不可达的那一组合(无调用方 ∧ 请求来源 scope)若仍到了这里 ⇒ 抛,不放行。
  */
-import type { MemoryScopeAdmission } from "@sema-agent/core";
+import { type MemoryScopeAdmission } from "@sema-agent/core";
+import type { Logger } from "./observability/logger.js";
 /**
  * 单机腿:装载 `MEMORY_ORG_DIRECTORY_JSON`(`Record<principal, Record<orgScope, {write?}>>`)。启动期调用,
  * **fail-loud**——任何非法直接 throw 且消息点名坏在哪个键(响亮拒是正确方向:一张半坏的授权表比拒绝
  * 启动更危险)。principal 键复用 {@link assertPrincipalShape}(拒不是名字的串 / 保留哨兵 / 超长租户名,与所有其它
- * principal 入口同一道闸;拒句按键在 JSON 文本里的出现序点名,不回显不是名字的键 —— 对象的枚举序会把整数形的键排到最前,不能拿它编号);scope 键必须是 `org:` 前缀、值必须是仅含可选 `write: boolean` 的 plain object。
+ * principal 入口同一道闸;拒句按键在 JSON 文本里的出现序点名,不回显不是名字的键 —— 对象的枚举序会把整数形的键排到最前,不能拿它编号);scope 键必须过 core 的 org scope 键判官(`isOrgScopeKey`:`org:` 加一段 v2 编码的名;判官只有 core 这一只,本仓不另存文法)、值必须是仅含可选 `write: boolean` 的 plain object。
  */
 export declare function parseOrgDirectoryStatic(json: string): Map<string, Record<string, {
     write?: boolean;
@@ -62,6 +63,8 @@ export interface OrgMemoryDirectoryOptions {
     unavailableBackoffMs: number;
     /** 时间注入(测试用);默认 `Date.now`。 */
     now?: () => number;
+    /** 远程腿一代目录被按坏形拒时的留声口(只用 `warn`;缺席 = 不留声)。 */
+    logger?: Pick<Logger, "warn">;
 }
 type OrgDirectoryUnavailableReason = "fetch_failed" | "section_absent" | "malformed" | "stale_generation";
 /**

package/dist/org-memory-admission.js

@@ -1,7 +1,15 @@
+import { isOrgScopeKey } from "@sema-agent/core";
 import { PrincipalOrgMemoryWire } from "@sema-agent/settings-schema";
+import { echoCallerText } from "./caller-text-echo.js";
 import { assertPrincipalShape } from "./security.js";
+function observe(hook) {
+    try {
+        hook();
+    }
+    catch {
+    }
+}
 const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
-const ORG_SCOPE_RE = /^org:\S+$/;
 function topLevelKeysInTextOrder(json) {
     const keys = [];
     let depth = 0;
@@ -58,8 +66,8 @@ export function parseOrgDirectoryStatic(json) {
         }
         const scopes = {};
         for (const [scope, entryRaw] of Object.entries(scopesRaw)) {
-            if (!ORG_SCOPE_RE.test(scope)) {
-                throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}] has an invalid org scope key ${JSON.stringify(scope)} (must match /^org:\\S+$/)`);
+            if (!isOrgScopeKey(scope)) {
+                throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}] has an invalid org scope key ${JSON.stringify(scope)} (core's org scope key rule refuses it — spell the org with core's formatOrgScope: "org:" plus the name's percent-encoded segment)`);
             }
             if (!isPlainObject(entryRaw)) {
                 throw new Error(`MEMORY_ORG_DIRECTORY_JSON[${JSON.stringify(principal)}][${JSON.stringify(scope)}] must be an object`);
@@ -78,6 +86,8 @@ export function parseOrgDirectoryStatic(json) {
     }
     return table;
 }
+const REFUSED_GENERATION_KEYS_NAMED = 5;
+const REFUSED_GENERATION_KEY_ECHO_CHARS = 80;
 export function createOrgMemoryDirectory(opts) {
     if ((opts.fetchSection !== undefined) === (opts.staticTable !== undefined)) {
         throw new Error("createOrgMemoryDirectory requires exactly one of fetchSection or staticTable (both given or both missing)");
@@ -117,6 +127,17 @@ export function createOrgMemoryDirectory(opts) {
         if (!parsed.success) {
             return markUnavailable(state, "malformed");
         }
+        const badKeys = Object.keys(parsed.data.scopes).filter((key) => !isOrgScopeKey(key));
+        if (badKeys.length > 0) {
+            const refused = markUnavailable(state, "malformed");
+            observe(() => opts.logger?.warn("org_directory_generation_refused", {
+                gen: parsed.data.gen,
+                badKeyCount: badKeys.length,
+                badKeys: badKeys.slice(0, REFUSED_GENERATION_KEYS_NAMED).map((key) => echoCallerText(key, { maxChars: REFUSED_GENERATION_KEY_ECHO_CHARS })),
+                kept: "this generation is not adopted (the whole generation, not just the keys core refuses); the lookup answers unavailable(malformed) and is retried after the backoff window",
+            }));
+            return refused;
+        }
         if (state.highWaterGen !== undefined && parsed.data.gen < state.highWaterGen) {
             return markUnavailable(state, "stale_generation");
         }
@@ -157,13 +178,7 @@ export class OrgMemoryAdmissionRetryError extends Error {
     }
 }
 export function createMemoryScopeAdmission(directory, opts) {
-    const emit = (outcome, details) => {
-        try {
-            opts.onOutcome?.(outcome, details);
-        }
-        catch {
-        }
-    };
+    const emit = (outcome, details) => observe(() => opts.onOutcome?.(outcome, details));
     return async (input) => {
         const { requested, requestedWriteScope } = input;
         const attributed = (details) => input.principal === undefined ? details : { principal: input.principal, ...details };

package/dist/outbound-dispatcher.d.ts

@@ -125,7 +125,7 @@ export declare function buildOutboundProxyPosture(env?: NodeJS.ProcessEnv): Outb
  * (按远端处置 = 交给代理那一半,与修前方向一致)。认哪几形(与 sema-cli 1.0.136 `isLoopbackHost` 同集):
  *  · `localhost`(含 FQDN 尾点 `localhost.`);刻意**不**认 `*.localhost` 子域(能否落到本机取决于系统解析器,不是地址本身的事实);
  *  · IPv4 `127.0.0.0/8` 整段(WHATWG URL 先把 `127.1` / `0x7f.1` 这类写法规范成点分四段);
- *  · IPv6 `::1`、IPv4 映射段 `::ffff:127.x.x.x`(URL 规范成 `::ffff:7fxx:xxxx` 形);
+ *  · IPv6 `::1`、IPv4 映射段 `::ffff:127.x.x.x`(URL 规范成 `::ffff:7fxx:xxxx` 形,经 `canonicalAddress` 折回点分 IPv4 再判);
  *  · 未指定地址 `0.0.0.0` / `::`(及映射形):作为目的地址它在本机就是「本机」,送进代理只会让代理去连它自己。
  */
 export declare function isLoopbackOrigin(origin: string | URL | undefined): boolean;

package/dist/outbound-dispatcher.js

@@ -1,6 +1,7 @@
 import { Agent, Client, Dispatcher, EnvHttpProxyAgent, getGlobalDispatcher, Pool, setGlobalDispatcher } from "undici";
 import { PROXY_TUNNEL_REFUSED } from "@sema-agent/core";
 import { isIP } from "node:net";
+import { canonicalAddress } from "./net-address.js";
 import diagnosticsChannel from "node:diagnostics_channel";
 import { buildDisplaySafeUrl, DISPLAY_SAFE_URL_TOKEN, redactSecrets } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
@@ -41,19 +42,12 @@ export function isLoopbackOrigin(origin) {
     host = host.replace(/\.+$/, "");
     if (host === "localhost")
         return true;
-    const family = isIP(host);
-    if (family === 4)
-        return host.startsWith("127.") || host === "0.0.0.0";
-    if (family !== 6)
+    const address = canonicalAddress(host);
+    if (address === undefined)
         return false;
-    if (host === "::1" || host === "::")
-        return true;
-    const mapped = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
-    if (mapped === null)
-        return false;
-    const hi = Number.parseInt(mapped[1], 16);
-    const lo = Number.parseInt(mapped[2], 16);
-    return hi >> 8 === 127 || (hi === 0 && lo === 0);
+    if (isIP(address) === 4)
+        return address.startsWith("127.") || address === "0.0.0.0";
+    return address === "::1" || address === "::";
 }
 class OutboundDispatcher extends Dispatcher {
     direct;

package/dist/owner-brands.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 🔴 **身份的三根轴与行上的属主**(属主律 + 场景子命名空间的类型事实;叶子:零 import)。
+ *
+ * ## 律(四句)
+ *  1. **轴在汇点上,不在串里。** {@link Person} = 外部验过的那个人(谁付钱 / 谁有权 / 谁被治理:成本、租约、用量窗、运维名册、中心场景裁定、持久规则、组织成员);
+ *     {@link Scenario} = 请求自报的场景(人之内的自选收窄,不是权限主张);{@link Subject} = 分区键(行属主 / 存储键 / 列表过滤 / 检查点 scope / 记忆 scope / 幂等身份)。
+ *     读身份的每只汇点形参带品牌:人面收 `Person`,分区面收 `Subject`(行上读出的是它的持久形 {@link DurableOwnerKey})—— 收错 = 编译红。
+ *  2. **两只铸点、一只解码器。** 外部管线 {@link subjectOf}(没带场景 ⇒ 主体与人**逐字节相同**;带了 ⇒ `_scn:<场景>:<人>`);内部恢复管线 {@link partsOf}
+ *     (行属主 / 检查点 scope / 引擎回传的 scope 恢复成 `{ subject, person, scenario? }`,存量串**一律先过它**)。保留前缀 / 在册 / 宽度三判只在外部管线
+ *     (`security.ts` 的形判与宽度判、`http/principal-gate.ts` 的请求身份判决);恢复的不是外部输入,不判。
+ *  3. **载体只带一格。** 调用方 / 幂等身份 / 列表视域 / 执行上下文只带 `Subject`;人只经 {@link personOf} 从它读 —— 不存在「人与主体不一致」的态。
+ *  4. **存储零改形。** 主体按字节落进既有的属主 / scope 列;没带场景的请求写下的行与今天逐字节同。
+ *
+ * ## 铸点闭集(普查门 ⑤ 逐文件钉)
+ *  · `Person` —— `security.ts` 的 `verifiedPerson`(验请求身份的那一只)、`principal-jwt.ts` 的 `verifyDirectDoorProof`(直连门上这一次决定的证明推出的人)、
+ *    本文件的 {@link partsOf}(恢复管线);
+ *  · `Scenario` —— 本文件的 {@link scenarioNamed}(文法是它的唯一入口)与 {@link partsOf};
+ *  · `Subject` —— 本文件的 {@link subjectOf} 与 {@link partsOf};
+ *  · `DurableOwnerKey` —— `owner-faces.ts` 的 `ownerKeyOf`(属主列读数)、`security.ts` 的 `decodeCheckpointScope`(停驻行 scope 列)与 `http/owner-access.ts` 判行处的
+ *    {@link mintOwnedRow}(门放过的那一行:同一个行对象原样交出,只在型上带品牌)。
+ * 四只品牌两两不可赋、裸 `string` 都不可赋;「调用方 vs 行属主」只经 `owner-faces.ts` 的 `sameParty`(有主行)/ `sameKey`(存储键)两座桥 —— 桥的调用方一侧是 `Subject`。
+ * 本文件是 src 里这四只品牌**唯一**出现断言的地方。
+ */
+declare const personBrand: unique symbol;
+declare const scenarioBrand: unique symbol;
+declare const subjectBrand: unique symbol;
+declare const durableOwnerKeyBrand: unique symbol;
+export type Person = string & {
+    readonly [personBrand]: true;
+};
+export type Scenario = string & {
+    readonly [scenarioBrand]: true;
+};
+export type Subject = string & {
+    readonly [subjectBrand]: true;
+};
+export type DurableOwnerKey = string & {
+    readonly [durableOwnerKeyBrand]: true;
+};
+/** 场景名文法(唯一一份):内建场景表与中心声明的场景、请求的场景头同读。不含冒号 ⇒ 主体里前缀后的第一个冒号唯一切分(编码单射、可解)。 */
+export declare const SCENARIO_NAME_RE: RegExp;
+/** 带场景的主体的保留前缀。身份边界拒以它开头的人(`security.ts` 的保留前缀表登记它),否则一个人可以自称别人的分区。 */
+export declare const SCENARIO_SUBJECT_PREFIX = "_scn:";
+/** {@link Person} 的铸造口(只在铸点闭集里调,见上)。 */
+export declare function mintPerson(verified: string): Person;
+/** {@link DurableOwnerKey} 的铸造口(只在铸点闭集里调,见上)。 */
+export declare function mintDurableOwnerKey(persisted: string): DurableOwnerKey;
+/** {@link Scenario} 的唯一入口:合文法 ⇒ 场景;不合 ⇒ `undefined`(调用方按自己的面答拒;不合文法的名字不可能在册)。 */
+export declare function scenarioNamed(raw: string): Scenario | undefined;
+/** 外部管线的主体铸点:没带场景 ⇒ 与人逐字节相同;带了 ⇒ `_scn:<场景>:<人>`。 */
+export declare function subjectOf(person: Person, scenario?: Scenario): Subject;
+/** 一只主体的三格(恢复管线的产物)。 */
+export interface SubjectParts {
+    readonly subject: Subject;
+    readonly person: Person;
+    readonly scenario: Scenario | undefined;
+}
+/** 一只以保留前缀开头、却拆不出「合文法的场景 + 非空的人」的串 —— 存量里不该有(起服的切换检查拒启它的来源),出现即是数据坏,不猜。 */
+export declare class MalformedSubjectError extends Error {
+    readonly code = "owner.malformed_subject";
+    constructor();
+}
+/**
+ * 🔴 **内部恢复管线的唯一解码器**:行属主 / 检查点 scope / 引擎回传的 scope 恢复成三格。不以保留前缀开头 ⇒ 无场景(主体 = 人,逐字节);
+ * 以它开头 ⇒ 前缀后第一个冒号切成场景与人 —— 场景不合文法或人段为空 ⇒ 抛 {@link MalformedSubjectError}(响亮,不把坏形读成人)。
+ * 不判保留前缀 / 在册 / 宽度:恢复的不是外部输入。
+ */
+export declare function partsOf(key: Subject | DurableOwnerKey): SubjectParts;
+/** 一只主体(或它的持久形)背后的人 —— 人面汇点从分区键读人的唯一读法(= {@link partsOf} 的 `person` 格)。 */
+export declare function personOf(key: Subject | DurableOwnerKey): Person;
+/**
+ * 门放过的那一行的铸造口(只在属主存取器判行处调):**行对象原样交回** —— 运行期是同一个对象、属主是同一串,只在型上把属主那一格带 {@link DurableOwnerKey}。
+ * 不展开、不拷贝:行上可能有惰性读的格(头读的叶子 `leafId` 在会话内容读不出时是一只抛故障的读取器 —— 只判归属的口不读内容),展开一次就把内容读了。
+ */
+export declare function mintOwnedRow<R extends {
+    readonly owner: string | null;
+}>(row: R): R & {
+    readonly owner: DurableOwnerKey | null;
+};
+export {};
+//# sourceMappingURL=owner-brands.d.ts.map

package/dist/owner-brands.js

@@ -0,0 +1,42 @@
+export const SCENARIO_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
+export const SCENARIO_SUBJECT_PREFIX = "_scn:";
+export function mintPerson(verified) {
+    return verified;
+}
+export function mintDurableOwnerKey(persisted) {
+    return persisted;
+}
+export function scenarioNamed(raw) {
+    return SCENARIO_NAME_RE.test(raw) ? raw : undefined;
+}
+export function subjectOf(person, scenario) {
+    return (scenario === undefined ? person : `${SCENARIO_SUBJECT_PREFIX}${scenario}:${person}`);
+}
+export class MalformedSubjectError extends Error {
+    code = "owner.malformed_subject";
+    constructor() {
+        super(`a stored owner key starts with the reserved scenario prefix "${SCENARIO_SUBJECT_PREFIX}" but does not split into a scenario name and a person`);
+        this.name = "MalformedSubjectError";
+    }
+}
+export function partsOf(key) {
+    const raw = key;
+    if (!raw.startsWith(SCENARIO_SUBJECT_PREFIX))
+        return { subject: raw, person: raw, scenario: undefined };
+    const rest = raw.slice(SCENARIO_SUBJECT_PREFIX.length);
+    const cut = rest.indexOf(":");
+    if (cut < 0)
+        throw new MalformedSubjectError();
+    const scenario = scenarioNamed(rest.slice(0, cut));
+    const person = rest.slice(cut + 1);
+    if (scenario === undefined || person.length === 0)
+        throw new MalformedSubjectError();
+    return { subject: raw, person: person, scenario };
+}
+export function personOf(key) {
+    return partsOf(key).person;
+}
+export function mintOwnedRow(row) {
+    return row;
+}
+//# sourceMappingURL=owner-brands.js.map