@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/write-behind-counter.js

@@ -1,11 +1,5 @@
-const SEP = "\u0000"; // NUL — can't appear in a principal / scope / IP key
-/** S9 deeper fix: default per-query timeout for the counter family's statements. Always ON (unlike the
- *  opt-in pool-wide DB_QUERY_TIMEOUT_MS): every statement here is a tiny single-row/single-bucket op, so
- *  30s is ~1000× headroom — a query that slow IS the S9 pathology (a DB-side hang would otherwise pin the
- *  flush round forever; the stalled watchdog can then only report, not recover). The rejection lands in
- *  the existing flush/refresh catch → the S9 streak telemetry counts it; the round ENDS and retries. */
+const SEP = "\u0000";
 export const DEFAULT_COUNTER_QUERY_TIMEOUT_MS = 30_000;
-/** Dual-dialect write-behind aggregating counter. See the file header for the dialect-delta ledger. */
 export class SqlWriteBehindCounter {
     dialect;
     pool;
@@ -14,20 +8,13 @@ export class SqlWriteBehindCounter {
     now;
     onDegraded;
     queryTimeoutMs;
-    pendingDelta = new Map(); // unflushed local, by rowKey (key + window bucket)
-    fleetTotal = new Map(); // peers' current-window view, refreshed periodically
+    pendingDelta = new Map();
+    fleetTotal = new Map();
     timer;
     flushing = false;
-    flushStartedAt = 0; // S9 review MED-1: hang-watchdog anchor // reentrancy guard: a flush slower than the timer interval must not overlap
-    failStreak = new Map(); // S9: consecutive-failure runs, per kind
-    constructor(dialect, pool, t, 
-    /** 🔴 不再 `readonly`(#322):`costQuotaWindowSec` 热更新经 {@link setWindowMs} 换代,语义见那里。 */
-    windowMs, now = () => Date.now(), onDegraded, // S9: observability tap — never affects counting
-    // S9 deeper fix: per-query inactivity timeout. mysql2's is the client-side `{sql, timeout}` form (the
-    // connection is held until the hung command really ends, so a poisoned connection is never reused
-    // mid-query); node-pg's is `query_timeout` on the QueryConfig. Overridable via DB_QUERY_TIMEOUT_MS
-    // (threaded by store-backend.ts); the default keeps the counter face always bounded.
-    queryTimeoutMs = DEFAULT_COUNTER_QUERY_TIMEOUT_MS) {
+    flushStartedAt = 0;
+    failStreak = new Map();
+    constructor(dialect, pool, t, windowMs, now = () => Date.now(), onDegraded, queryTimeoutMs = DEFAULT_COUNTER_QUERY_TIMEOUT_MS) {
         this.dialect = dialect;
         this.pool = pool;
         this.t = t;
@@ -36,7 +23,6 @@ export class SqlWriteBehindCounter {
         this.onDegraded = onDegraded;
         this.queryTimeoutMs = queryTimeoutMs;
     }
-    /** The ONLY place the two drivers' query shapes diverge. Returns {rows, affected}. */
     async exec(sql, params) {
         if (this.dialect === "tidb") {
             const [r] = (await this.pool.query({ sql, timeout: this.queryTimeoutMs }, params));
@@ -48,8 +34,6 @@ export class SqlWriteBehindCounter {
         const res = await this.pool.query(q);
         return { rows: (res.rows ?? []), affected: res.rowCount ?? 0 };
     }
-    /** S9: track the consecutive-failure streak per kind and notify on every failure + on the recovery edge
-     *  (streak>0 → 0). Steady healthy state stays silent. The hook must never break the counter. */
     bump(kind, failed, error) {
         if (!this.onDegraded)
             return;
@@ -62,7 +46,6 @@ export class SqlWriteBehindCounter {
             this.onDegraded({ table: this.t.table, kind, streak: next, prevStreak: prev, ...(failed && error !== undefined ? { error: error instanceof Error ? error.message : String(error) } : {}) });
         }
         catch {
-            /* observability must never break the counter */
         }
     }
     bucket() {
@@ -71,7 +54,6 @@ export class SqlWriteBehindCounter {
     rk(key) {
         return `${key}${SEP}${this.bucket()}`;
     }
-    /** Cached fleet total (peers, from the last refresh) + this replica's unflushed delta, current window. */
     used(key) {
         const rk = this.rk(key);
         return (this.fleetTotal.get(rk) ?? 0) + (this.pendingDelta.get(rk) ?? 0);
@@ -82,20 +64,11 @@ export class SqlWriteBehindCounter {
         const rk = this.rk(key);
         this.pendingDelta.set(rk, (this.pendingDelta.get(rk) ?? 0) + n);
     }
-    /** Seconds until the current aligned window rolls over. */
     retryAfterSec() {
         return Math.ceil(((this.bucket() + 1) * this.windowMs - this.now()) / 1000);
     }
-    /** Atomically push pending deltas, then refresh the current window's fleet totals + reap old buckets.
-     *  Reentrancy-guarded: two overlapping flushes would each apply `+delta` from the same snapshot and
-     *  double-count into the shared table (inflating fleet totals → spurious rate-limit/quota rejection). */
     async flush() {
         if (this.flushing) {
-            // S9 review MED-1: a hung query holds this guard: every later tick returns HERE and bump() is never
-            // reached, so the reject-path telemetry goes silent exactly when the fleet is degraded. Surface the
-            // stall itself — >60s inside one flush round = a "stalled" failure signal per tick; its streak clears
-            // when the round finally settles. (The per-query timeout above is the deeper fix — a round now self-
-            // terminates at queryTimeoutMs; this watchdog stays as the backstop for anything it doesn't cover.)
             if (this.now() - this.flushStartedAt > 60_000)
                 this.bump("stalled", true, "flush round stalled >60s (hung query?)");
             return;
@@ -107,18 +80,17 @@ export class SqlWriteBehindCounter {
         }
         finally {
             this.flushing = false;
-            this.bump("stalled", false); // watchdog recovery edge (no-op if it never fired)
+            this.bump("stalled", false);
         }
     }
     async flushOnce() {
         const { table, keyCol, valCol } = this.t;
-        // The atomic-increment upsert — the ONE statement whose dialect delta actually matters here.
         const sql = this.dialect === "tidb"
             ? `INSERT INTO ${table} (${keyCol}, window_bucket, ${valCol}, updated_at) VALUES (?,?,?,?) ` +
                 `ON DUPLICATE KEY UPDATE ${valCol} = ${valCol} + VALUES(${valCol}), updated_at = VALUES(updated_at)`
             : `INSERT INTO ${table} (${keyCol}, window_bucket, ${valCol}, updated_at) VALUES ($1,$2,$3,$4) ` +
                 `ON CONFLICT (${keyCol}, window_bucket) DO UPDATE SET ${valCol} = ${table}.${valCol} + EXCLUDED.${valCol}, updated_at = EXCLUDED.updated_at`;
-        let attempted = false; // S9: only score a flush round that actually tried a write
+        let attempted = false;
         let failure;
         let hadFailure = false;
         for (const [rk, delta] of [...this.pendingDelta]) {
@@ -129,8 +101,7 @@ export class SqlWriteBehindCounter {
             const windowBucket = Number(rk.slice(sep + 1));
             attempted = true;
             try {
-                await this.exec(sql, [key, windowBucket, delta, new Date()]); // S9 deeper fix: a hung INSERT rejects into the catch below (streak counts it)
-                // subtract what we flushed (not delete — a concurrent addLocal may have grown it meanwhile)
+                await this.exec(sql, [key, windowBucket, delta, new Date()]);
                 const remaining = (this.pendingDelta.get(rk) ?? 0) - delta;
                 if (remaining > 0)
                     this.pendingDelta.set(rk, remaining);
@@ -138,22 +109,15 @@ export class SqlWriteBehindCounter {
                     this.pendingDelta.delete(rk);
             }
             catch (err) {
-                hadFailure = true; // S9: surfaced via bump() below — the retry/soft-limit semantics are unchanged
+                hadFailure = true;
                 failure = err;
-                // keep the delta; retry next flush (advisory — never throw into the caller).
-                // KNOWN/ACCEPTED (audit B): an ambiguous failure (INSERT applied but the ack was lost) re-adds
-                // the delta next flush = double-count; conversely a reader between our INSERT and a peer's sees
-                // a momentary under-count. Both are bounded by one flush window and this counter backs SOFT
-                // limits only (quota/rate-limit, design: eventual consistency; hard caps use per-task budgets).
-                // Exactly-once would need a flush ledger/CAS — not worth it at this tier.
             }
         }
         if (attempted)
-            this.bump("flush", hadFailure, failure); // S9: empty rounds carry no health signal
+            this.bump("flush", hadFailure, failure);
         await this.refresh();
         await this.reap();
     }
-    /** Load the current window's fleet totals into the cache (pendingDelta is separate → never clobbered). */
     async refresh() {
         const { table, keyCol, valCol } = this.t;
         const b = this.bucket();
@@ -163,36 +127,26 @@ export class SqlWriteBehindCounter {
                 : `SELECT ${keyCol}, ${valCol} FROM ${table} WHERE window_bucket = $1`, [b]);
             const next = new Map();
             for (const row of rows) {
-                next.set(`${String(row[keyCol])}${SEP}${b}`, Number(row[valCol])); // node-pg returns BIGINT/INT as STRING
+                next.set(`${String(row[keyCol])}${SEP}${b}`, Number(row[valCol]));
             }
             this.fleetTotal = next;
-            this.bump("refresh", false); // S9: recovery edge (no-op while healthy)
+            this.bump("refresh", false);
         }
         catch (err) {
-            // keep last-known cache on a transient read failure
-            this.bump("refresh", true, err); // S9
+            this.bump("refresh", true, err);
         }
     }
-    /**
-     * Delete expired window buckets to bound the table.
-     *
-     * 🔴 失败**必须留痕**(#192 codex 复审 round2 修):这里原先是裸 `catch { return 0 }` —— 一个只影响
-     * DELETE 的故障(权限被收回、引擎单独拒 DELETE)会被吞成"删了 0 行",而 flush/refresh 两条腿照常成功
-     * ⇒ 健康遥测全绿,同时 rate_limit / cost_quota 的历史桶无界增长。那正是本仓禁止的静默 fail-open。
-     * 处置是**留痕不改失败方向**:清理是 best-effort,失败仍返回 0(把一次运维层面的清理失败升级成业务
-     * 失败是错的方向),但走与 flush/refresh 同一套 `bump()` ⇒ 有连败计数、有降级钩子、有恢复边沿。
-     */
     async reap() {
         try {
             const { affected } = await this.exec(this.dialect === "tidb"
                 ? `DELETE FROM ${this.t.table} WHERE window_bucket < ?`
                 : `DELETE FROM ${this.t.table} WHERE window_bucket < $1`, [this.bucket()]);
-            this.bump("reap", false); // 恢复边沿(健康时是 no-op)
+            this.bump("reap", false);
             return affected;
         }
         catch (err) {
             this.bump("reap", true, err);
-            return 0; // best-effort:留痕之后照旧不抛
+            return 0;
         }
     }
     startRefresh(intervalMs = 5_000) {
@@ -205,31 +159,18 @@ export class SqlWriteBehindCounter {
             clearInterval(this.timer);
         this.timer = undefined;
     }
-    /** #322:刷新环是否在跑(关断哨兵的判据:off 态必须**零 SQL**,含这条后台环)。 */
     refreshRunning() {
         return this.timer !== undefined;
     }
-    /**
-     * #322 批1:窗长换代(`costQuotaWindowSec` 热更新)。
-     *
-     * 🔴 如实语义:窗长是**桶键的一部分**(`floor(now/windowMs)`),不是行里的一个可改字段。换窗长 ⇒ 当代
-     * 桶重算 ⇒ 本副本对「当前窗已用多少」的读数从新桶起算(旧桶的行还在库里,按它自己的窗长归属)。
-     * 未 flush 的本地增量仍带着**它自己的**桶键(rowKey 里已含),所以它们仍落回原来那个桶,不会被搬家。
-     * 这与限额值的换代不同(那个是纯比较参数,窗内计数一个不动),因此单独成注:运营改窗长要知道自己在
-     * 换的是**记账周期**,不是一个阈值。
-     */
     setWindowMs(windowMs) {
         this.windowMs = windowMs;
     }
 }
-/** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */
 export class WriteBehindCounter extends SqlWriteBehindCounter {
     constructor(pool, t, windowMs, now, onDegraded, queryTimeoutMs) {
         super("tidb", pool, t, windowMs, now, onDegraded, queryTimeoutMs);
     }
 }
-/** PostgreSQL binding — the class pg-rate-limiter.ts used to define inline (and pg-cost-quota.ts duplicated
- *  privately, hardwired to the cost_quota columns). Same ctor shape as the mysql2 twin. */
 export class PgWriteBehindCounter extends SqlWriteBehindCounter {
     constructor(pool, t, windowMs, now, onDegraded, queryTimeoutMs) {
         super("pg", pool, t, windowMs, now, onDegraded, queryTimeoutMs);

package/dist/principal-jwt.js

@@ -1,29 +1,8 @@
-/**
- * design/80 D-G: principal crypto-binding (the direct-door IDENTITY gate) + the combined direct-door proof
- * verifier. Split out of `security.ts` (design/158 A13; consumers import from HERE — [2354] cleared the security.ts compat re-exports;
- * `verifyDirectDoorProof` imports {@link verifyApprovalHmac} from `./approval-hmac.js` for the
- * integrity half of the combined proof; `security.ts`'s own `verifiedPrincipal` imports {@link verifyPrincipalJwt}
- * from here for the direct-door identity branch).
- *
- * ✅ WIRED (was "🔴 SCAFFOLD — NOT YET WIRED" — STALE, corrected by the 2026-07-25 doc-rot sweep). Two live call
- * sites, both traced: `verifiedPrincipal` (security.ts) takes the direct-door branch when `directDoorActive` and
- * derives the principal from {@link verifyPrincipalJwt} instead of the header, and {@link verifyDirectDoorProof}
- * verifies the same JWT for the decide routes. Still true, and the part worth keeping: `directDoorActive` is
- * computed from the anchors (config.ts) and is OFF by default, so the direct branch never runs in a stock
- * deployment — activation = provisioning the issuer JWKS + iss/aud, a deployment task, not a coding one.
- * The direct-connect /decide door must NEVER trust a client-supplied principal header
- * (invariant #1). Instead the client presents a SIGNED JWT (sub = principal), and the worker verifies the SIGNATURE
- * against the issuer's PUBLIC key — so identity is crypto-DERIVED, not header-asserted. PUBLIC keys ⇒ non-secret
- * (ride the config projection like OPERATOR_PRINCIPALS, not the HMAC secret path). The issuer's PRIVATE key lives
- * ONLY with the trusted minter (the BFF/identity service), never on a worker. HMAC stays integrity; this is identity.
- */
 import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
 import { verifyApprovalHmac } from "./approval-hmac.js";
 function b64urlToBuf(s) {
     return Buffer.from(s, "base64url");
 }
-/** Map a PINNED JWS alg → the node:crypto verify call. EdDSA(Ed25519): algorithm=null. RS256: RSA-PKCS1+sha256.
- *  ES256: ECDSA P-256 with the JWS raw r||s encoding (dsaEncoding ieee-p1363, NOT DER). Returns false on mismatch. */
 function verifyJwsSignature(alg, signingInput, sig, pub) {
     try {
         if (alg === "EdDSA")
@@ -38,12 +17,6 @@ function verifyJwsSignature(alg, signingInput, sig, pub) {
         return false;
     }
 }
-/**
- * design/80 D-G: verify a compact JWS principal token. Returns the crypto-verified principal (`sub`) + the
- * channel-binding (`bnd`) on success, or `null` on ANY failure (caller fail-closes — NEVER falls back to a header).
- * 🔴 Hardening: the JWS header `alg` MUST equal the kid's PINNED alg (rejects `alg:none`, symmetric, downgrade);
- * the kid MUST resolve to a configured key; iss/aud/exp/nbf (with a small skew) are enforced; `sub` MUST be present.
- */
 export function verifyPrincipalJwt(token, keys, expect) {
     if (keys.length === 0)
         return null;
@@ -62,15 +35,13 @@ export function verifyPrincipalJwt(token, keys, expect) {
     catch {
         return null;
     }
-    // A payload of the JSON literal `null` (or any non-object) parses WITHOUT throwing — guard before any deref so a
-    // crafted `base64url("null").<payload>.<sig>` token fail-closes to a typed reject, not an uncaught TypeError → 500.
     if (typeof header !== "object" || header === null || typeof payload !== "object" || payload === null)
         return null;
     if (typeof header.alg !== "string" || typeof header.kid !== "string" || sig.length === 0)
         return null;
     const key = keys.find((k) => k.kid === header.kid);
     if (!key || key.alg !== header.alg)
-        return null; // 🔴 alg PINNED to the kid's key — no confusion/downgrade
+        return null;
     let pub;
     try {
         pub = createPublicKey(key.key);
@@ -81,7 +52,6 @@ export function verifyPrincipalJwt(token, keys, expect) {
     const signingInput = Buffer.from(`${h}.${p}`, "utf8");
     if (!verifyJwsSignature(key.alg, signingInput, sig, pub))
         return null;
-    // claims — signature verified, now enforce the envelope
     if (payload.iss !== expect.iss)
         return null;
     const aud = payload.aud;
@@ -92,57 +62,32 @@ export function verifyPrincipalJwt(token, keys, expect) {
         return null;
     const now = expect.nowSec ?? Math.floor(Date.now() / 1000);
     const skew = expect.skewSec ?? 30;
-    // 🔴 exp is MANDATORY (the design mandates a short-lived token, ≤120s) — a missing/non-numeric exp must FAIL, else a
-    // token minted without exp would never expire (anti-replay = single-use checkpointToken ONLY, with no time bound).
     if (typeof payload.exp !== "number" || payload.exp + skew < now)
-        return null; // missing / non-numeric / expired
+        return null;
     if (payload.nbf !== undefined && (typeof payload.nbf !== "number" || payload.nbf - skew > now))
-        return null; // nbf, if present, must be numeric + reached
-    // Cap the TTL so a sloppy/over-permissive minter can't widen the replay window past the short-lived mandate.
+        return null;
     if (expect.maxTtlSec && payload.exp - now > expect.maxTtlSec + skew)
         return null;
     const bnd = typeof payload.cnf?.bnd === "string" ? payload.cnf.bnd : undefined;
     return { sub: payload.sub, bnd };
 }
-/** The channel-binding value a direct client's principal JWT must carry in `cnf.bnd`: the hex SHA-256 of the
- *  CLIENT-VISIBLE action identity (sessionId + boundCallId + boundInputHash — NOT the unexposed checkpointToken).
- *  Binds the identity assertion to THIS specific suspended action so a captured JWT cannot be lifted onto another. */
 export function approvalBnd(env) {
     return createHash("sha256").update(JSON.stringify([env.sessionId, env.boundCallId ?? null, env.boundInputHash ?? null])).digest("hex");
 }
-/**
- * design/80 D-G: verify the WHOLE direct-door proof for one /decide — the signed principal JWT (identity) + its
- * cnf.bnd channel-binding + the HMAC envelope (integrity) — and return the CRYPTO-VERIFIED principal, or a typed
- * reject. 🔴 Fail-closed: every failure rejects (the caller must NOT fall back to the trusted header). Order:
- * verify principal → bind → mac-present → mac-valid (so a non-operator never gets a MAC oracle, an unverified
- * caller never reaches the operator list).
- *
- * 🔴 `opts.actionBinding`: the boundCallId/boundInputHash action-binding is `policy_ask`-
- * SPECIFIC (a pending TOOL call). A NON-ACTION gate — `plan_review` (and any review-pause) — `binds NO action`
- * (core checkpoint-store.ts: pendingAction `{kind:"plan_review"}`, editedPlan is a typed sibling that binds no
- * action), so the proof correctly DEGRADES to "verify WHO": JWT identity + cnf.bnd channel-binding + the HMAC over
- * {sessionId, decision} (bound fields null) — WITHOUT requiring a boundInputHash. Pass `actionBinding:false` for a
- * non-action gate; the default (true) keeps the /decide tool-approval contract byte-identical. Binding the decision
- * to a plan HASH was REJECTED (the plan artifact lives in a profile ref store; the worker has no TOCTOU original).
- */
 export function verifyDirectDoorProof(proof, envelope, config, opts) {
-    const actionBinding = opts?.actionBinding ?? true; // default = the policy_ask tool-approval action-binding (unchanged)
+    const actionBinding = opts?.actionBinding ?? true;
     if (!proof.jwt)
         return { ok: false, status: 401, errorCode: "principal_unverified", error: "direct door requires a signed principal token (X-Approval-Principal-Token)" };
     const verified = verifyPrincipalJwt(proof.jwt, config.principalJwtPubkeys, { iss: config.principalJwtIss ?? "\0", aud: config.principalJwtAud ?? "\0", maxTtlSec: config.principalJwtMaxTtlSec });
     if (!verified)
         return { ok: false, status: 401, errorCode: "principal_unverified", error: "principal token failed verification" };
-    // action-binding gates (policy_ask) MUST carry the bound action; a non-action gate (plan_review) skips this — the
-    // cnf.bnd + HMAC below still bind {sessionId, decision} (with null bound fields), so WHO + decision-integrity hold.
     if (actionBinding && !envelope.boundInputHash)
         return { ok: false, status: 400, errorCode: "approval_mac_required", error: "direct door requires boundInputHash (the bound action) in the body" };
     if (verified.bnd !== approvalBnd(envelope))
         return { ok: false, status: 401, errorCode: "principal_unbound", error: "principal token is not bound to this decision (cnf.bnd mismatch)" };
     if (!proof.mac)
         return { ok: false, status: 401, errorCode: "approval_mac_required", error: "direct door requires an approval MAC (X-Approval-Mac)" };
-    const ok = verifyApprovalHmac(
-    // reason 与两个绑定位同样归一到 null(缺席=null),使"服务端算的"与"签名器签的"在缺席形上逐字节一致。
-    { sessionId: envelope.sessionId, boundCallId: envelope.boundCallId ?? null, boundInputHash: envelope.boundInputHash ?? null, decision: envelope.decision, reason: envelope.reason ?? null }, proof.mac, proof.kid, config.approvalHmacKeys);
+    const ok = verifyApprovalHmac({ sessionId: envelope.sessionId, boundCallId: envelope.boundCallId ?? null, boundInputHash: envelope.boundInputHash ?? null, decision: envelope.decision, reason: envelope.reason ?? null }, proof.mac, proof.kid, config.approvalHmacKeys);
     if (!ok)
         return { ok: false, status: 401, errorCode: "approval_mac_invalid", error: "approval envelope MAC invalid" };
     return { ok: true, principal: verified.sub };