@sema-agent/server 7.79.0 → 7.79.2

package/dist/http/approval-sweeps.js

@@ -0,0 +1,138 @@
+import { redactHead } from "../observability/run-terminal-log.js";
+import { findParkOrigin } from "../parked-decide.js";
+import { decodeCheckpointScope } from "../security.js";
+import { personDecision } from "../host-decision.js";
+import { APPROVAL_GATE_KINDS } from "../tool-approval.js";
+import { createWallClockJumpGuard } from "../wall-clock-jump-guard.js";
+import { hasServiceAuth } from "./dispatch.js";
+import { gatedPrincipal } from "./principal-gate.js";
+export function createApprovalSweeps(ctx) {
+    const { deps, resumeCheckpoint, mayDiscloseRowError } = ctx;
+    const denySweepClockGuard = createWallClockJumpGuard({
+        slaMs: deps.config.approvalTimeoutSec > 0 ? deps.config.approvalTimeoutSec * 1000 : undefined,
+        onJump: ({ jumpMs, graceMs }) => deps.logger?.warn?.("deny_sweep_wall_clock_jump", {
+            jumpMs,
+            graceMs,
+            note: jumpMs > 0
+                ? "the wall clock stepped FORWARD relative to the monotonic clock; the approval SLA deny-sweep stands down for graceMs of MONOTONIC time so no pending gate is denied earlier than one full SLA of REAL time ([4232]①/[4235]). The checkpoint terminal_at_ms backstop is unaffected — nothing can hang forever."
+                : "the wall clock stepped BACKWARD relative to the monotonic clock; the deny-sweep needs no grace for this direction (a receding deadline only DELAYS a deny) but the step itself is an operational fact worth recording.",
+        }),
+        onSuppressed: ({ remainingMs }) => deps.logger?.info?.("deny_sweep_clock_grace", { remainingMs }),
+        onGraceCapped: ({ totalGraceMs }) => deps.logger?.warn?.("deny_sweep_clock_grace_capped", {
+            totalGraceMs,
+            note: "the wall clock kept stepping forward; the approval SLA deny-sweep has stood down for the maximum cumulative grace and now RESUMES on a demonstrably unstable clock — a fail-closed leg that never runs is worse than one running on a bad clock. Fix NTP on this host.",
+        }),
+    });
+    async function denyExpiredApprovals(now) {
+        const cs = deps.checkpointStore;
+        if (!cs)
+            return;
+        if (!denySweepClockGuard.admit(now))
+            return;
+        const expired = await cs.listExpiredApprovalGates(now).catch(() => []);
+        const isParkedOwned = async (sessionId) => {
+            if (deps.backgroundAgentStore === undefined && deps.workflowAgentSessionIndex === undefined)
+                return false;
+            try {
+                const token = await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS });
+                if (!token)
+                    return false;
+                const cp = await cs.get(token);
+                if (!cp)
+                    return false;
+                return (await findParkOrigin({
+                    ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
+                    ...(deps.workflowAgentSessionIndex !== undefined && deps.workflowRunStore !== undefined
+                        ? { workflowIndex: deps.workflowAgentSessionIndex, workflowRunStore: deps.workflowRunStore }
+                        : {}),
+                }, { token, scope: cp.scope, sessionId: cp.sessionId })) !== undefined;
+            }
+            catch {
+                return false;
+            }
+        };
+        let parkedSkipped = 0;
+        for (const { sessionId } of expired) {
+            if (await isParkedOwned(sessionId)) {
+                parkedSkipped += 1;
+                continue;
+            }
+            await resumeCheckpoint(sessionId, "deny", "approval SLA expired — auto-denied", { decidedBy: "sla_timeout" }).then((r) => { if (r.status >= 400)
+                deps.logger?.warn?.("deny_sweep_resume_blocked", { sessionId, status: r.status, errorCode: r.body?.errorCode }); }, (e) => deps.logger?.warn?.("deny_sweep_resume_failed", { sessionId, err: redactHead(e instanceof Error ? e.message : String(e), 2000) }));
+        }
+        if (parkedSkipped > 0)
+            deps.logger?.info?.("deny_sweep_parked_skipped", { count: parkedSkipped });
+    }
+    async function redeemParkedAsk(req) {
+        const cs = deps.checkpointStore;
+        if (!cs) {
+            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+        }
+        if (!hasServiceAuth(deps.config) && !deps.config.allowUnauthedWrites) {
+            return { status: 503, body: { error: "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions", errorCode: "auth.service_token_required" } };
+        }
+        if (deps.drainState?.draining) {
+            return {
+                status: 503,
+                body: {
+                    error: "draining",
+                    errorCode: "draining",
+                    message: "this instance is draining for shutdown/upgrade — retry against the replacement instance",
+                    ...(deps.drainState.reason ? { reason: deps.drainState.reason } : {}),
+                },
+            };
+        }
+        if (deps.modelReady && !deps.modelReady()) {
+            return {
+                status: 503,
+                body: {
+                    error: "model_roster_pending",
+                    errorCode: "state.model_roster_pending",
+                    message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly",
+                },
+            };
+        }
+        if (deps.costQuota && req.httpReq) {
+            const quotaPrincipal = gatedPrincipal(req.httpReq, deps.config);
+            if (quotaPrincipal !== undefined) {
+                const d = deps.costQuota.check(quotaPrincipal);
+                if (!d.allowed) {
+                    deps.metrics?.inc("cost_quota_rejected_total");
+                    return {
+                        status: 429,
+                        body: { error: "cost quota exceeded", errorCode: "limit.cost_quota_exceeded", usedMicroUsd: d.usedMicroUsd, limitMicroUsd: d.limitMicroUsd, retryAfterSec: d.retryAfterSec },
+                    };
+                }
+            }
+        }
+        let cp;
+        try {
+            cp = await cs.get(req.gateToken);
+        }
+        catch (e) {
+            if (!(await mayDiscloseRowError(cs, req.gateToken, { principal: req.principal, explicitOperator: false }))) {
+                deps.logger?.warn?.("parked_late_decision_unreadable_row_withheld", { askId: req.askId });
+                return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+            }
+            return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
+        }
+        if (!cp) {
+            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+        }
+        const cpPrincipal = decodeCheckpointScope(cp.scope);
+        if (cpPrincipal !== undefined && cpPrincipal !== req.principal) {
+            deps.logger?.warn?.("parked_late_decision_scope_mismatch", { askId: req.askId });
+            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+        }
+        const binding = {
+            checkpointToken: req.gateToken,
+            ...(req.gateBoundCallId !== null ? { boundCallId: req.gateBoundCallId } : {}),
+            ...(req.gateBoundInputHash !== null ? { boundInputHash: req.gateBoundInputHash } : {}),
+            ...(req.updatedInput !== undefined ? { updatedInput: req.updatedInput } : {}),
+        };
+        const out = await resumeCheckpoint(cp.sessionId, req.decision, req.note, personDecision(req.principal), req.httpReq, undefined, binding, undefined, true, { principal: req.principal, explicitOperator: false });
+        return { status: out.status, body: out.body };
+    }
+    return { denyExpiredApprovals, redeemParkedAsk };
+}
+//# sourceMappingURL=approval-sweeps.js.map

package/dist/http/dispatch.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 请求流水线(S-147 切片:`http/server.ts` 的 `handle()` 与它的模块级词表搬家;S-146 再把「这是什么路由」
+ * 整件事交给 `./route-table.ts`)。
+ *
+ * 住在这里的是**一条请求从进门到落地**的全过程,一件事一遍:admission 计数 / 附着登记 / CORS / /health /
+ * /metrics / 鉴权桥 / 全局服务凭据门 / 无凭据写门 / drain 与 roster-pending 两道 503 / 破坏性会话写门 /
+ * 两段分派 / 全局 404。
+ *
+ * 🔴 S-146 之后本文件**不再持有任何一份路由名单**:分派序、门侧、标签、三只门的判据全部读
+ * `ROUTES` / `ROUTE_DECLARATIONS`(见 route-table.ts 头注)。三道门也不再「按行号插在 37 只 if 中间」——
+ * 它们在门前段与门后段之间**恒定一处**执行,三段代码逐字未动,只是不再被域调用夹着。
+ *
+ * ctx 字段 4 只(`deps` / `counters` / `noteActivity` / `routeCtxBase`),机器算(closure-free-vars)与手抄一致。
+ * `openResponses` / `lastAttachEndedAt` 是 handle 自己写的外层 `let`/`Set`,随它一起进工厂 —— 这样那两行赋值
+ * 正文一个字都不用改(装盒改写会把 `lastAttachEndedAt = …` 改成 `box.x = …`,那就不是 move 了)。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { ServiceConfig } from "../config-types.js";
+import type { RouteCtxBase, RunRegistry } from "./route-ctx.js";
+import type { FlatServiceDeps } from "./server.js";
+/** 「这台部署配了任何一把 service 凭证吗」—— fail-closed 写门族的真值源。**单一属主**:`handle()` 的
+ *  凭证门、[ref] 的 parked 赎回席、以及 [ref] 的 consolidation 阀门启动期告警读同一句(手抄迟早
+ *  只改一处,而这条判据决定的是「无凭证部署上写口开不开」)。导出仅为最后一个消费点(main.ts)。 */
+export declare function hasServiceAuth(config: ServiceConfig): boolean;
+export declare function createDispatch(ctx: {
+    deps: FlatServiceDeps;
+    noteActivity: (url: string) => void;
+    routeCtxBase: RouteCtxBase;
+} & Pick<RunRegistry, "counters">): {
+    handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+};
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/http/dispatch.js

@@ -0,0 +1,230 @@
+import { createHash } from "node:crypto";
+import { setSsoPrincipal, ssoVerifiedPrincipal, setSsoScope, isDestructiveSessionWrite, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../security.js";
+import { publicStoreProbeError } from "../store-live-probe.js";
+import { looksLikeJwt } from "@sema-agent/settings-schema/api/auth-bridge";
+import { PRE_CREDENTIAL_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath } from "./route-table.js";
+import { sendJson, sendError, isSseResponse } from "./send.js";
+import { authorized, systemFor } from "./principal-gate.js";
+const PROCESS_STARTED_AT_MS = Date.now() - Math.round(process.uptime() * 1000);
+export function hasServiceAuth(config) {
+    return Boolean(config.authToken) || Object.keys(config.authTokens ?? {}).length > 0;
+}
+function cors(res, req, origins, principalHeader) {
+    if (!origins || origins.length === 0)
+        return;
+    let allow;
+    if (origins.length === 1) {
+        allow = origins[0];
+    }
+    else {
+        res.setHeader("vary", "Origin");
+        const reqOrigin = typeof req.headers.origin === "string" ? req.headers.origin : undefined;
+        allow = reqOrigin !== undefined && origins.includes(reqOrigin) ? reqOrigin : undefined;
+    }
+    if (allow === undefined)
+        return;
+    res.setHeader("access-control-allow-origin", allow);
+    res.setHeader("access-control-allow-methods", "GET, POST, PUT, DELETE, OPTIONS");
+    res.setHeader("access-control-allow-headers", `content-type, authorization, last-event-id, ${principalHeader}, idempotency-key, x-detach-on-disconnect, ${PRINCIPAL_TOKEN_HEADER}, ${APPROVAL_MAC_HEADER}, ${APPROVAL_MAC_KID_HEADER}, if-none-match`);
+    res.setHeader("access-control-expose-headers", "x-task-id, retry-after");
+}
+export function createDispatch(ctx) {
+    const { deps, noteActivity, routeCtxBase, counters } = ctx;
+    const openResponses = new Set();
+    let lastAttachEndedAt = 0;
+    if (deps.drainState) {
+        deps.drainState.attachedStreams = () => {
+            let n = 0;
+            for (const r of openResponses)
+                if (isSseResponse(r))
+                    n++;
+            return n;
+        };
+        deps.drainState.lastAttachEndedAt = () => lastAttachEndedAt;
+    }
+    async function dispatchSegment(rows, req, res, url, ctx) {
+        for (const row of rows) {
+            if (row.enabled !== undefined && !row.enabled(deps))
+                continue;
+            if (await row.handler(req, res, url, ctx))
+                return true;
+        }
+        return false;
+    }
+    async function handle(req, res) {
+        const startedAt = Date.now();
+        const method = req.method ?? "GET";
+        const url = (req.url ?? "/").split("?")[0];
+        noteActivity(url);
+        const admitted = method !== "OPTIONS" && url !== "/health" && !url.startsWith("/metrics");
+        if (admitted)
+            counters.admittedInflight++;
+        if (admitted)
+            openResponses.add(res);
+        let logged = false;
+        const reqState = { streamTaskId: undefined, streamDetached: false, source: null };
+        const ctx = { deps: routeCtxBase.deps, registry: routeCtxBase.registry, helpers: routeCtxBase.helpers, local: routeCtxBase.local, legs: routeCtxBase.legs, req: reqState };
+        const record = (viaClose) => {
+            if (logged)
+                return;
+            logged = true;
+            if (admitted)
+                counters.admittedInflight--;
+            if (openResponses.delete(res) && isSseResponse(res))
+                lastAttachEndedAt = performance.now();
+            const route = routeLabel(method, url);
+            const seconds = (Date.now() - startedAt) / 1000;
+            const aborted = viaClose && !res.writableEnded;
+            const status = aborted ? "499" : String(res.statusCode);
+            deps.metrics?.inc("http_requests_total", { route, method, status });
+            deps.metrics?.observe("http_request_duration_seconds", seconds, { route });
+            const log = route === "/health" || route === "/metrics" ? deps.logger?.debug : deps.logger?.info;
+            log?.call(deps.logger, "request", { method, route, status, ms: Date.now() - startedAt, ...(reqState.runStatus !== undefined ? { runStatus: reqState.runStatus } : {}), ...(reqState.runErrorCode !== undefined ? { errorCode: reqState.runErrorCode } : {}), ...(aborted ? { aborted: true, ...(reqState.streamTaskId ? { taskId: reqState.streamTaskId } : {}), ...(reqState.streamDetached ? { detached: true } : {}) } : {}) });
+        };
+        res.on("finish", () => record(false));
+        res.on("close", () => record(true));
+        cors(res, req, deps.config.corsOrigins, deps.config.principalHeader);
+        if (req.method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (req.method === "GET" && url === "/health") {
+            const restart = deps.restartState?.();
+            const configHash = createHash("sha256")
+                .update(JSON.stringify({ model: deps.config.model.id, sessionBackend: deps.config.sessionBackend, dbBackend: deps.config.dbBackend, dataRoot: deps.config.localDataRoot, configProvider: deps.config.configProvider, remoteExec: deps.config.remoteExec?.provider, port: deps.config.port }))
+                .digest("hex")
+                .slice(0, 16);
+            sendJson(res, 200, {
+                status: "ok",
+                ...(typeof deps.capabilities?.version === "string" ? { version: deps.capabilities.version } : {}),
+                ...(deps.drainState?.draining ? { draining: true, ...(deps.drainState.since ? { drainingSince: deps.drainState.since } : {}), ...(deps.drainState.reason ? { drainReason: deps.drainState.reason } : {}) } : {}),
+                ...(deps.drainState?.inflight ? { inflight: deps.drainState.inflight() } : {}),
+                ...(deps.storeDegraded ? { durable: false, storeDegraded: true } : {}),
+                ...(deps.modelReady && !deps.modelReady() ? { ready: false, readyReason: "model roster pending (first effective-config pull)" } : {}),
+                model: deps.config.model.id,
+                sessionBackend: deps.sessionStoreLabel ?? deps.config.sessionBackend,
+                sessions: deps.runner.sessions.size,
+                ...(deps.instanceId ? { instanceId: deps.instanceId } : {}),
+                ...(deps.config.localDataRoot ? { dataRoot: deps.config.localDataRoot } : {}),
+                configHash,
+                pid: process.pid,
+                startedAt: PROCESS_STARTED_AT_MS,
+                port: deps.config.port,
+                ...(deps.config.directDoorActive ? { directDoorActive: true } : {}),
+                ...(restart ? { restartRequired: true, restart: { reasons: restart.reasons, version: restart.version, since: restart.since } } : {}),
+                ...(() => {
+                    const stuck = deps.planeDeferredState?.();
+                    return stuck ? { modelPlaneDeferred: { version: stuck.version, since: stuck.since, noHandoff: true, ...(stuck.blocked ? { blockedReasons: stuck.blocked } : {}) } } : {};
+                })(),
+                ...(() => {
+                    const gen = deps.configApplyState?.();
+                    if (!gen)
+                        return {};
+                    return {
+                        configTargetVersion: gen.configTargetVersion,
+                        configAppliedVersion: gen.configAppliedVersion,
+                        configTargetOrdinal: gen.configTargetOrdinal,
+                        configAppliedOrdinal: gen.configAppliedOrdinal,
+                        ...(gen.configApplyStaleMs !== undefined ? { configApplyStaleMs: gen.configApplyStaleMs } : {}),
+                    };
+                })(),
+                ...(() => {
+                    const probe = deps.storeLiveState?.();
+                    if (!probe)
+                        return {};
+                    return {
+                        ...(probe.live ? {} : { storeLive: false }),
+                        storeProbe: { live: probe.live, ageMs: probe.ageMs, ...(probe.error !== undefined ? { error: publicStoreProbeError(probe.error) } : {}) },
+                    };
+                })(),
+            });
+            return;
+        }
+        if (req.method === "GET" && (url === "/metrics" || url === "/metrics/summary" || url === "/metrics/plan-cache")) {
+            if (!deps.metrics) {
+                sendError(res, 404, "feature.metrics_disabled", "metrics disabled");
+                return;
+            }
+            const { authToken: t, metricsToken: mt } = deps.config;
+            const anyT = Boolean(t) || Object.keys(deps.config.authTokens ?? {}).length > 0;
+            const devOpen = !anyT && !mt && !deps.config.requirePrincipal;
+            const ok = devOpen || (anyT && systemFor(req, deps.config) !== undefined) || (!!mt && authorized(req, mt));
+            if (!ok) {
+                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                return;
+            }
+            if (url === "/metrics/summary") {
+                sendJson(res, 200, { model: deps.config.model.id, ...deps.metrics.summarize() });
+                return;
+            }
+            if (url === "/metrics/plan-cache") {
+                sendJson(res, 200, { scopes: deps.planCacheProbe?.dump() ?? {} });
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/plain; version=0.0.4" });
+            res.end(deps.metrics.render());
+            return;
+        }
+        if (deps.registryJwtVerifier) {
+            const authz = req.headers.authorization ?? "";
+            const rawBearer = /^Bearer\s/i.test(authz) ? authz.replace(/^Bearer\s+/i, "") : "";
+            if (rawBearer && looksLikeJwt(rawBearer)) {
+                const v = await deps.registryJwtVerifier.verify(rawBearer);
+                if (v.ok) {
+                    setSsoPrincipal(req, v.identity.principal);
+                    req.headers[deps.config.principalHeader.toLowerCase()] = v.identity.principal;
+                    if (v.identity.scope)
+                        setSsoScope(req, v.identity.scope);
+                    deps.logger?.info?.("auth_bridge_principal_accepted", { principal: v.identity.principal, ...(v.identity.scope ? { scope: v.identity.scope } : {}) });
+                }
+            }
+        }
+        if (await dispatchSegment(PRE_CREDENTIAL_ROUTES, req, res, url, ctx))
+            return;
+        let source = null;
+        const anyServiceAuth = hasServiceAuth(deps.config);
+        if (anyServiceAuth) {
+            const sys = systemFor(req, deps.config);
+            if (sys === undefined) {
+                if (ssoVerifiedPrincipal(req)) {
+                    source = "sso";
+                }
+                else {
+                    sendError(res, 401, "auth.unauthorized", "unauthorized");
+                    return;
+                }
+            }
+            else {
+                source = sys;
+            }
+        }
+        reqState.source = source;
+        if (!anyServiceAuth &&
+            !deps.config.allowUnauthedWrites &&
+            ((req.method === "POST" && (isBillableSubmitPath(url) || url.startsWith("/v1/images/bakes"))) ||
+                isCredentialGatedRewrite(req.method ?? "", url))) {
+            sendError(res, 503, "auth.service_token_required", "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting task submissions");
+            return;
+        }
+        if (deps.drainState?.draining && req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
+            res.setHeader("retry-after", "15");
+            sendError(res, 503, "draining", "draining", { message: "this instance is draining for shutdown/upgrade — retry against the replacement instance", ...(deps.drainState.reason ? { reason: deps.drainState.reason } : {}) });
+            return;
+        }
+        if (deps.modelReady && !deps.modelReady() && req.method === "POST" && isBillableSubmitPath(url) && !isMethodDispatchedSubmitPath(url)) {
+            res.setHeader("retry-after", "5");
+            sendError(res, 503, "state.model_roster_pending", "model_roster_pending", { message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" });
+            return;
+        }
+        if (isDestructiveSessionWrite(req.method ?? "", url) && !anyServiceAuth && !deps.config.allowUnauthedWrites) {
+            sendError(res, 503, "auth.service_token_required", "this worker requires a service auth token (set SERVICE_AUTH_TOKEN) before accepting destructive session writes (policy / sync-import / fork / delete)");
+            return;
+        }
+        if (await dispatchSegment(POST_CREDENTIAL_ROUTES, req, res, url, ctx))
+            return;
+        sendError(res, 404, "not_found.route", "not found");
+    }
+    return { handle };
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/http/request-guards.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 请求守门族(S-147 切片:`http/server.ts` 4837–5195 + `MAX_BODY` 逐字搬家,正文一字未改)。
+ * 配额 / 租约 / 用量窗 / 限流 / owner-scope / 体读取 —— 每只守门的判据与它自己的头注原位随行。
+ * ctx 字段 1 只(`deps`):本族对外围的耦合就这一格,它也是这一族的可测性读数。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { FlatServiceDeps } from "./server.js";
+export declare function createRequestGuards(ctx: {
+    deps: FlatServiceDeps;
+}): {
+    quotaExceeded: (req: IncomingMessage, res: ServerResponse) => boolean;
+    ownerCostQuotaDenied: (principal: string | undefined) => {
+        status: number;
+        body: object;
+    } | undefined;
+    ownerFleetLeaseDenied: (owner: string | undefined) => Promise<{
+        status: number;
+        body: object;
+    } | undefined>;
+    ownerLeaseDenied: (res: ServerResponse, owner: string | undefined) => Promise<boolean>;
+    ownerQuotaDenied: (res: ServerResponse, owner: string | undefined) => boolean;
+    leaseDenied: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+    usageWindowDenialFor: (key: string) => Promise<{
+        status: number;
+        body: {
+            error: string;
+            errorCode: string;
+            retryAfterSec: number;
+        };
+        retryAfterSec: number;
+    } | undefined>;
+    usageWindowDenied: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+    rateLimited: (req: IncomingMessage, res: ServerResponse) => boolean;
+    safeDecode: (seg: string) => string | null;
+    isFleetWide: (req: IncomingMessage) => boolean;
+    sessionOwnerScope: (req: IncomingMessage) => {
+        fleetWide: boolean;
+        gateOwner: string | null;
+    };
+    sessionOwnerScopeForWrite: (req: IncomingMessage) => {
+        fleetWide: boolean;
+        gateOwner: string | null;
+    };
+    runOwnerOk: (req: IncomingMessage, res: ServerResponse, owner: string | null, notFoundForm?: "run" | "session") => boolean;
+    runSessionAcceptOk: (req: IncomingMessage, res: ServerResponse, run: {
+        sessionId: string | null;
+    }, face: string, notFoundError?: string) => boolean;
+    readJson: (req: IncomingMessage) => Promise<unknown>;
+    readRawBody: (req: IncomingMessage, max: number) => Promise<Buffer>;
+};
+//# sourceMappingURL=request-guards.d.ts.map

package/dist/http/request-guards.js

@@ -0,0 +1,205 @@
+import { GLOBAL_USAGE_KEY, usageRetryAfterMs } from "@sema-agent/core";
+import { HttpError, principalFrom } from "../security.js";
+import { RUN_NOT_FOUND_MESSAGE } from "./route-ctx.js";
+import { sendError } from "./send.js";
+import { authorized, systemFor, gatedPrincipal, explicitOperatorOk, runOwnerReadable, sendPrincipalRefusal } from "./principal-gate.js";
+const MAX_BODY = 8 * 1024 * 1024;
+export function createRequestGuards(ctx) {
+    const { deps } = ctx;
+    function quotaExceeded(req, res) {
+        if (!deps.costQuota)
+            return false;
+        const principal = gatedPrincipal(req, deps.config);
+        if (!principal)
+            return false;
+        const d = deps.costQuota.check(principal);
+        if (d.allowed)
+            return false;
+        deps.metrics?.inc("cost_quota_rejected_total");
+        res.setHeader("retry-after", String(d.retryAfterSec));
+        sendError(res, 429, "limit.cost_quota_exceeded", "cost quota exceeded", { usedMicroUsd: d.usedMicroUsd, limitMicroUsd: d.limitMicroUsd, retryAfterSec: d.retryAfterSec });
+        return true;
+    }
+    function ownerCostQuotaDenied(principal) {
+        if (!deps.costQuota || !principal)
+            return undefined;
+        const d = deps.costQuota.check(principal);
+        if (d.allowed)
+            return undefined;
+        deps.metrics?.inc("cost_quota_rejected_total");
+        return { status: 429, body: { error: "cost quota exceeded", errorCode: "limit.cost_quota_exceeded", usedMicroUsd: d.usedMicroUsd, limitMicroUsd: d.limitMicroUsd, retryAfterSec: d.retryAfterSec } };
+    }
+    async function ownerFleetLeaseDenied(owner) {
+        if (!deps.fleetLease || !owner)
+            return undefined;
+        const adm = await deps.fleetLease.admit(owner);
+        if (adm.ok)
+            return undefined;
+        deps.metrics?.inc("fleet_lease_rejected_total");
+        return { status: 429, body: { error: "budget exhausted (quota lease)", errorCode: "quota_exhausted", retryAfterSec: adm.retryAfterSec } };
+    }
+    async function ownerLeaseDenied(res, owner) {
+        if (!deps.fleetLease || !owner)
+            return false;
+        const adm = await deps.fleetLease.admit(owner);
+        if (adm.ok)
+            return false;
+        deps.metrics?.inc("fleet_lease_rejected_total");
+        res.setHeader("retry-after", String(adm.retryAfterSec));
+        sendError(res, 429, "quota_exhausted", "budget exhausted (quota lease)", { retryAfterSec: adm.retryAfterSec, ...(adm.detail ?? {}) });
+        return true;
+    }
+    function ownerQuotaDenied(res, owner) {
+        const denial = ownerCostQuotaDenied(owner);
+        if (!denial)
+            return false;
+        const { errorCode, error, ...extras } = denial.body;
+        res.setHeader("retry-after", String(extras.retryAfterSec));
+        sendError(res, denial.status, errorCode, error, extras);
+        return true;
+    }
+    async function leaseDenied(req, res) {
+        if (!deps.fleetLease)
+            return false;
+        const principal = gatedPrincipal(req, deps.config);
+        if (!principal)
+            return false;
+        const adm = await deps.fleetLease.admit(principal);
+        if (adm.ok)
+            return false;
+        deps.metrics?.inc("fleet_lease_rejected_total");
+        res.setHeader("retry-after", String(adm.retryAfterSec));
+        sendError(res, 429, "quota_exhausted", "budget exhausted (quota lease)", { retryAfterSec: adm.retryAfterSec, ...(adm.detail ?? {}) });
+        return true;
+    }
+    async function usageWindowDenialFor(key) {
+        const store = deps.usageWindowStore;
+        const windows = deps.config.usageWindows;
+        if (!store || !windows || windows.length === 0)
+            return undefined;
+        let retryAfterMs;
+        try {
+            retryAfterMs = usageRetryAfterMs(await store.read(key, windows, Date.now()));
+        }
+        catch (e) {
+            deps.logger?.warn?.("usage_window_admission_read_failed", { error: e instanceof Error ? e.message : String(e) });
+            return undefined;
+        }
+        if (retryAfterMs === undefined)
+            return undefined;
+        deps.metrics?.inc("usage_window_rejected_total");
+        deps.logger?.info?.("usage_window_exhausted", { hasPrincipal: key !== GLOBAL_USAGE_KEY, retryAfterMs });
+        const retryAfterSec = Math.max(1, Math.ceil(retryAfterMs / 1000));
+        return { status: 429, body: { error: "usage window exhausted (deployment token governance)", errorCode: "usage.window_exhausted", retryAfterSec }, retryAfterSec };
+    }
+    async function usageWindowDenied(req, res) {
+        const denial = await usageWindowDenialFor(gatedPrincipal(req, deps.config) || GLOBAL_USAGE_KEY);
+        if (!denial)
+            return false;
+        res.setHeader("retry-after", String(denial.retryAfterSec));
+        sendError(res, denial.status, denial.body.errorCode, denial.body.error, { retryAfterSec: denial.retryAfterSec });
+        return true;
+    }
+    function rateLimited(req, res) {
+        if (!deps.rateLimiter)
+            return false;
+        const key = (deps.config.directDoorActive ? undefined : principalFrom(req, deps.config)) ?? req.socket.remoteAddress ?? "anon";
+        const d = deps.rateLimiter.check(key);
+        if (d.allowed)
+            return false;
+        deps.metrics?.inc("rate_limited_total");
+        res.setHeader("retry-after", String(d.retryAfterSec));
+        sendError(res, 429, "limit.rate_exceeded", "rate limit exceeded", { retryAfterSec: d.retryAfterSec });
+        return true;
+    }
+    function safeDecode(seg) {
+        try {
+            return decodeURIComponent(seg);
+        }
+        catch {
+            return null;
+        }
+    }
+    function isFleetWide(req) {
+        const { authToken: at, traceToken: tt } = deps.config;
+        const anyAt = Boolean(at) || Object.keys(deps.config.authTokens ?? {}).length > 0;
+        return (!anyAt && !tt && !deps.config.requirePrincipal) || (anyAt && systemFor(req, deps.config) !== undefined) || (!!tt && authorized(req, tt));
+    }
+    function sessionOwnerScope(req) {
+        const fleetWide = isFleetWide(req);
+        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
+        return { fleetWide, gateOwner };
+    }
+    function sessionOwnerScopeForWrite(req) {
+        const { authToken: at, traceToken: tt } = deps.config;
+        const anyAt = Boolean(at) || Object.keys(deps.config.authTokens ?? {}).length > 0;
+        const fleetWide = (!anyAt && !tt && !deps.config.requirePrincipal) || (anyAt && systemFor(req, deps.config) !== undefined);
+        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
+        return { fleetWide, gateOwner };
+    }
+    function runOwnerOk(req, res, owner, notFoundForm = "run") {
+        const principal = gatedPrincipal(req, deps.config);
+        if (deps.config.requirePrincipal && !principal) {
+            sendPrincipalRefusal(res, req, deps.config);
+            return false;
+        }
+        if (!runOwnerReadable(principal, owner, deps.config)) {
+            if (notFoundForm === "session")
+                sendError(res, 404, "not_found.session", "session not found");
+            else
+                sendError(res, 404, "not_found.run", RUN_NOT_FOUND_MESSAGE);
+            return false;
+        }
+        return true;
+    }
+    const sessionAssertAbsentWarned = new Set();
+    function runSessionAcceptOk(req, res, run, face, notFoundError = RUN_NOT_FOUND_MESSAGE) {
+        if (!run.sessionId)
+            return true;
+        const asserted = new URL(req.url ?? "", "http://x").searchParams.get("session");
+        if (asserted === null) {
+            if (!sessionAssertAbsentWarned.has(face)) {
+                sessionAssertAbsentWarned.add(face);
+                console.warn(JSON.stringify({ ts: new Date().toISOString(), level: "warn", msg: "run_face_session_assert_absent", face, note: "caller sent no ?session= on a session-bound run — allowed in the accept phase; the enforcement train will 404 this ([1498]⑥/[1499])" }));
+            }
+            return true;
+        }
+        if (asserted === run.sessionId)
+            return true;
+        if (explicitOperatorOk(gatedPrincipal(req, deps.config), deps.config.operatorPrincipals))
+            return true;
+        sendError(res, 404, "not_found.run", notFoundError);
+        return false;
+    }
+    async function readJson(req) {
+        const chunks = [];
+        let size = 0;
+        for await (const c of req) {
+            size += c.length;
+            if (size > MAX_BODY)
+                throw new HttpError(413, "request body too large");
+            chunks.push(c);
+        }
+        if (chunks.length === 0)
+            return {};
+        try {
+            return JSON.parse(Buffer.concat(chunks).toString("utf8")) ?? {};
+        }
+        catch {
+            throw new HttpError(400, "invalid JSON body");
+        }
+    }
+    async function readRawBody(req, max) {
+        const chunks = [];
+        let size = 0;
+        for await (const c of req) {
+            size += c.length;
+            if (size > max)
+                throw new HttpError(413, "blob too large");
+            chunks.push(c);
+        }
+        return Buffer.concat(chunks);
+    }
+    return { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, isFleetWide, sessionOwnerScope, sessionOwnerScopeForWrite, runOwnerOk, runSessionAcceptOk, readJson, readRawBody };
+}
+//# sourceMappingURL=request-guards.js.map