@sema-agent/server 7.147.0 → 7.149.0

package/dist/http/routes/rules.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendUnauthorized } from "../principal-gate.js";
+import { gatedPerson, explicitOperatorOk, sendOperatorPrincipalsRequired, sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
+import { principalShapeProblem } from "../../principal-shape.js";
 import * as facts from "../../capability-facts.js";
 import { createLogger } from "../../observability/logger.js";
 import { RULE_IMPORT_RETRY_AFTER_SEC, RULE_SCOPE_REFUSAL_SENTENCE, MAX_RULE_SCOPE_CHARS, buildCcImportLayerRootRefusal, parseRuleScope, serializeRuleScope } from "../../rules-consent.js";
@@ -75,7 +76,7 @@ const RuleIdentityBodySchema = z
     behavior: z.enum(RULE_BEHAVIORS),
     rule: z.string().min(1).max(1024),
     scope: z.string().min(1).max(MAX_RULE_SCOPE_CHARS),
-    principal: z.string().min(1).max(190).optional(),
+    principal: z.string().optional(),
 })
     .strict();
 const RULES_CURSOR_FORMAT = 2;
@@ -100,7 +101,7 @@ export async function handleRules(req, res, match, ctx) {
     const { readJson, rateLimited } = ctx.helpers;
     if (rateLimited(req, res))
         return;
-    const principal = gatedPrincipal(req, deps.config);
+    const principal = gatedPerson(req, deps.config);
     if (principal === undefined) {
         sendUnauthorized(res, "identity");
         return;
@@ -245,8 +246,13 @@ function resolveTargetPrincipal(requested, caller, config) {
         return { ok: false, why: "operator_principals_empty" };
     if (!explicitOperatorOk(caller, config))
         return { ok: false, why: "not_operator" };
+    if (principalShapeProblem(requested) !== undefined)
+        return { ok: false, why: "not_a_principal" };
     return { ok: true, principal: requested };
 }
+function sendTargetNotAPrincipal(res) {
+    sendError(res, 400, "request.field_invalid", "principal must name a principal a caller can authenticate as (a visible-character, well-formed name, not a reserved identifier, at most the principal byte length)", { field: "principal" });
+}
 async function handleRuleList(res, search, caller, lane, config) {
     const q = new URLSearchParams(search);
     const target = resolveTargetPrincipal(q.get("principal") ?? undefined, caller, config);
@@ -258,6 +264,9 @@ async function handleRuleList(res, search, caller, lane, config) {
             case "not_operator":
                 sendError(res, 403, "auth.operator_only", "reading another principal's rules is an operator-only action");
                 return;
+            case "not_a_principal":
+                sendTargetNotAPrincipal(res);
+                return;
             default:
                 return assertNever(target.why);
         }
@@ -378,6 +387,9 @@ async function handleRuleWrite(res, rawBody, caller, lane, config) {
             case "not_operator":
                 sendError(res, 403, "auth.operator_only", "writing another principal's rules is an operator-only action");
                 return;
+            case "not_a_principal":
+                sendTargetNotAPrincipal(res);
+                return;
             default:
                 return assertNever(target.why);
         }
@@ -392,9 +404,9 @@ async function handleRuleWrite(res, rawBody, caller, lane, config) {
             return;
         case "rejected":
             logger.info("rule write refused", { reason: written.reason, detail: written.detail });
-            sendError(res, 400, "request.field_invalid", "this rule was not written — `reason` names which check refused it and `detail` says why", {
+            sendError(res, 400, "request.field_invalid", `this rule was not written — \`reason\` names which check refused it: ${written.detail}`, {
                 reason: written.reason,
-                detail: written.detail,
+                ...(written.canonical !== undefined ? { canonical: written.canonical } : {}),
             });
             return;
         case "failed":
@@ -427,6 +439,9 @@ async function handleRuleRevoke(res, rawBody, caller, lane, config) {
             case "not_operator":
                 sendError(res, 403, "auth.operator_only", "revoking another principal's rules is an operator-only action");
                 return;
+            case "not_a_principal":
+                sendTargetNotAPrincipal(res);
+                return;
             default:
                 return assertNever(target.why);
         }

package/dist/http/routes/run-memory-capture.d.ts

@@ -10,7 +10,7 @@
  *
  * ── 权限法条(steer 车道逐字)────────────────────────────────────────────────────────────────────
  * core 不认证:持有活流句柄即能力。**本面拥有 verified-principal / 会话所有权判定**:裸 sessionId 中继会让任何人
- * 关掉任何人的记忆(可用性攻击)。所以:身份来自 `gatedPrincipal`(验证过的身份,不是可自造的头),run 属主不符
+ * 关掉任何人的记忆(可用性攻击)。所以:身份来自 `gatedSubject`(验证过的身份,不是可自造的头),run 属主不符
  * ⇒ 404 `not_found.run` **同串反枚举**(与 steer/interrupt 同判)。core 在翻转时刻**重新裁决** per-principal
  * entitlement(`RuntimeCaps.allowMemoryOptOut` under `memoryCapturePolicy`,fresh resolve)—— 被拒 ⇒ typed
  * `memory.capture_optout_denied` + 零记录残留;server 不复刻那条裁决。
@@ -28,7 +28,7 @@
  * `sessionBackgroundable` 同谓词):老 worker 键缺席 ⇒ 壳不渲入口(假 affordance 纪律)。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 export declare function handleRunMemoryCapture(req: IncomingMessage, res: ServerResponse, match: RouteMatch<RunMemoryCaptureRouteId>, ctx: RouteCtx): Promise<void>;
 export declare const RUN_MEMORY_CAPTURE_ROUTES: readonly [{
     readonly id: "run-memory-capture-optout";

package/dist/http/routes/run-memory-capture.js

@@ -1,8 +1,7 @@
 import { z } from "zod";
 import { isParkedRunStatus, isTerminalRunStatus, runProvenElsewhere } from "../../plugins/store-contracts.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
-import { RUN_NOT_FOUND_MESSAGE, runNotFoundMessage } from "../route-ctx.js";
+import { admitRunById, enter } from "../owner-access.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 const BodySchema = z.object({ reason: z.string().min(1).max(500).optional() }).strict();
@@ -18,24 +17,19 @@ export async function handleRunMemoryCapture(req, res, match, ctx) {
                 return;
             }
             const runStore = runs.runStore;
-            const principal = gatedPrincipal(req, deps.config);
-            if (deps.config.requirePrincipal && principal === undefined) {
-                sendPrincipalRefusal(res, req, deps.config);
+            const entry = enter(req, res, deps, match.decl.id);
+            if (entry === undefined)
                 return;
-            }
             const taskId = match.params.taskId;
             const parsed = BodySchema.safeParse((await ctx.helpers.readJson(req)) ?? {});
             if (!parsed.success) {
                 sendError(res, 400, "request.body_shape", "body must be {} or { reason: string (non-empty, at most 500 chars) } — the session memory-capture opt-out verb takes no other keys");
                 return;
             }
-            const run = await runStore.getRun(taskId);
-            if (!run) {
-                sendError(res, 404, "not_found.run", runNotFoundMessage(taskId));
-                return;
-            }
-            if (!ctx.helpers.runOwnerOk(req, res, run.owner))
+            const admitted = (await admitRunById(entry, res, runStore, taskId));
+            if (admitted === undefined)
                 return;
+            const run = admitted.row;
             const live = ctx.registry.steerableRuns.get(taskId);
             if (live) {
                 try {

package/dist/http/routes/run-permission-mode.d.ts

@@ -23,7 +23,7 @@
  * 一行运维 warn + fail-open 计数(`server.run-permission-mode.write-back-unpersisted`),壳据 `persisted` 判要不要在续跑后重切。
  *
  * ── 门(与 steer 同一组)──────────────────────────────────────────────────────────────────────────────
- * 零模型工作(不进 billable);mutating ⇒ `rateLimited`。属主门与 steer / interrupt 同一组放行臂(行经属主存取器 `readOwnedRun` 取,`owner_or_operator`):
+ * 零模型工作(不进 billable);mutating ⇒ `rateLimited`。属主门与 steer / interrupt 同一面(属主存取器的 `run.supervise`:属主资格 ∨ 显式运维):
  * 显式 operator 可切任一租户的 run(监督动作),普通调用方只切自己的(非属主 404 同串,不给存在性 oracle);`?session=` 的受理期断言同族。非 live 四臂一码 409 `steering.not_running`
  * (停驻 / 终局 / 他副本 / 本副本无活流);坏词 422 `steering.invalid_content`(引擎同码,受理前判)。能力位 `permissionModeWrite`
  * = 事实 `permissionModeWrite`(持久 run 账面 ∧ checkpoint 店),与两道 501 同一只。
@@ -31,7 +31,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { PermissionMode, PermissionModeReceipt } from "@sema-agent/core";
 import { type FencedRun } from "../../plugins/store-contracts.js";
-import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
+import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 import { type PermissionModeAdmissionFold } from "../../permission-mode-admission.js";
 /** 回写没落定的成因(闭集;wire `persistMiss`):`claim_released` 接下切档的那条腿这一刻已不持有这条 run(终局 / 停驻 / 已由续跑的新腿接手);
  *  `context_absent` 持有但会话没有存储体行;`store_failed` 店写抛(库抖 / 一行装不下 / 封签失败)。 */

package/dist/http/routes/run-permission-mode.js

@@ -1,14 +1,12 @@
 import { z } from "zod";
 import { isParkedRunStatus, isTerminalRunStatus, runProvenElsewhere } from "../../plugins/store-contracts.js";
 import { sendJson, sendError } from "../send.js";
-import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
-import { readOwnedRun } from "../owner-access.js";
-import { runNotFoundMessage } from "../route-ctx.js";
+import { admitRunById, enter } from "../owner-access.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { PERMISSION_MODE_WORDS, coercePermissionModeStrict, parseTaskSettings } from "../../task-settings.js";
 import { admitPermissionModeWord } from "../../permission-mode-admission.js";
-import { readResumeCtx, resumeCtxCorruptAnswer, resumeCtxUnsealableAnswer } from "../resume-ctx-read.js";
+import { readResumeCtx, resumeCtxCorruptAnswer, resumeCtxUnreadableAnswer, resumeCtxUnsealableAnswer } from "../resume-ctx-read.js";
 import { sealCheckpointCtx, withPermissionModeRewritten } from "../checkpoint-ctx.js";
 import { serviceVersion } from "../../service-version.js";
 import { recordFailOpen } from "../../observability/fail-open.js";
@@ -44,11 +42,9 @@ export async function handlePermissionMode(req, res, match, ctx) {
                 }
             }
             const { runStore, checkpointStore } = seat;
-            const principal = gatedPrincipal(req, deps.config);
-            if (deps.config.requirePrincipal && principal === undefined) {
-                sendPrincipalRefusal(res, req, deps.config);
+            const entry = enter(req, res, deps, match.decl.id);
+            if (entry === undefined)
                 return;
-            }
             const taskId = match.params.taskId;
             const parsed = BodySchema.safeParse((await ctx.helpers.readJson(req)) ?? {});
             if (!parsed.success) {
@@ -60,13 +56,10 @@ export async function handlePermissionMode(req, res, match, ctx) {
                 sendError(res, 422, "steering.invalid_content", `mode must be one of ${PERMISSION_MODE_WORDS} (got ${JSON.stringify(parsed.data.mode.slice(0, 64))})`);
                 return;
             }
-            const run = await readOwnedRun(deps.config, runStore, principal, taskId, "owner_or_operator");
-            if (!run) {
-                sendError(res, 404, "not_found.run", runNotFoundMessage(taskId));
-                return;
-            }
-            if (!ctx.helpers.runSessionAcceptOk(req, res, run, "run.permission_mode"))
+            const admitted = (await admitRunById(entry, res, runStore, taskId));
+            if (admitted === undefined)
                 return;
+            const run = admitted.row;
             const live = ctx.registry.steerableRuns.get(taskId);
             if (!live) {
                 if (isParkedRunStatus(run.status)) {
@@ -87,8 +80,8 @@ export async function handlePermissionMode(req, res, match, ctx) {
             const sessionId = run.sessionId;
             const out = await serialOnStream(live, async () => {
                 const read = await readResumeCtx(checkpointStore.getCtx(sessionId), { sessionId, opener: deps.checkpointCtxSealing });
-                if (read.kind === "corrupt" || read.kind === "unsealable") {
-                    const { status, body: { error, errorCode, ...facts } } = read.kind === "corrupt" ? resumeCtxCorruptAnswer(read.where) : resumeCtxUnsealableAnswer(read);
+                if (read.kind === "corrupt" || read.kind === "unsealable" || read.kind === "unreadable") {
+                    const { status, body: { error, errorCode, ...facts } } = read.kind === "corrupt" ? resumeCtxCorruptAnswer(read.where) : read.kind === "unsealable" ? resumeCtxUnsealableAnswer(read) : resumeCtxUnreadableAnswer();
                     sendError(res, status, errorCode, error, facts);
                     return { kind: "answered" };
                 }
@@ -122,7 +115,7 @@ export async function handlePermissionMode(req, res, match, ctx) {
                 let persistMiss;
                 try {
                     const next = sealCheckpointCtx({ ...withPermissionModeRewritten(stored, { ...stored.body, permissionMode: admitted }), writerVersion: serviceVersion() }, deps.checkpointCtxSealing, sessionId);
-                    const rewrite = await checkpointStore.rewriteCtxWhileClaimed(sessionId, taskId, next, (fenced) => switchLegHolds(fenced, deps.instanceId, ctx.registry.steerableRuns.get(taskId), live));
+                    const rewrite = await checkpointStore.rewriteCtxWhileClaimed(sessionId, next, { fence: runStore, taskId, legHolds: (fenced) => switchLegHolds(fenced, deps.instanceId, ctx.registry.steerableRuns.get(taskId), live) });
                     persistMiss = rewrite === "written" ? undefined : rewrite;
                 }
                 catch (e) {