@sema-ai/core 1.275.1

package/dist/core/canonical-json.js

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+/**
+ * design/80 D-1 §2 (slice 1a.2) — the engine-only **vetted canonical serializer** used to mint a stable,
+ * opaque {@link boundInputHashOf | boundInputHash} over a pending tool call's arguments.
+ *
+ * ## Why a bespoke serializer (and why engine-ONLY)
+ * The package's only runtime deps are typebox + the MCP SDK — there is no canonical/stable JSON serializer,
+ * and `JSON.stringify` is **not** canonical (object key order is insertion order, `-0`/`NaN`/`Infinity` are
+ * mishandled, and it offers no type-tagging). The red-team r3 ruling (design/80 §7) is the load-bearing
+ * constraint: **never let two runtimes each compute a canonical form and compare** — a `JSON.stringify`
+ * divergence (or a serializer-version drift across a worker upgrade) would produce a false mismatch and
+ * fail-closed a *legitimate* approval. So the boundInputHash is **server-minted opaque**: the engine computes
+ * it ONCE at suspend-mint with THIS serializer, persists it on the checkpoint, and a resume verifies by
+ * **opaque string equality** against the persisted value (it never re-serializes the resume-side args). This
+ * serializer therefore only needs to be *internally deterministic* (same value → same bytes within one
+ * runtime); it is deliberately NOT exported from the package index, so no cross-wire consumer (the SDK /
+ * service) can be tempted to recompute it — they treat the hash as opaque and echo it verbatim.
+ *
+ * ## Canonical form
+ * A total function (never throws) that emits a **type-tagged, length-prefixed** string so distinct values of
+ * distinct types can never collide (`number 1` ≠ `string "1"` ≠ `boolean`, and `{"a":"b"}` ≠ `{"ab":""}`):
+ *  - `null` → `N`, `undefined` → `U` (encoded distinctly — `{a:undefined}` must not collide with `{}`)
+ *  - boolean → `b1` / `b0`
+ *  - number → `n:<canonical>`; finite via `String(x)` (shortest round-trippable, deterministic per value);
+ *    `-0` normalized to `0`; `NaN`/`±Infinity` get explicit distinct tokens (never collapsed to `null`)
+ *  - bigint → `i:<value>`
+ *  - string → `s<byteLen>:<raw>` — **length-prefixed, NOT normalized**: equal inputs map to equal output and
+ *    distinct inputs (e.g. a non-NFC string vs its NFC form) map to distinct output. The serializer never
+ *    silently Unicode-normalizes (that would let two different argument payloads share one hash).
+ *  - array → `a<len>:[<el>…]` — order preserved (semantic)
+ *  - object → `o<count>:{<keyLen>:<key>=<val>…}` — **own enumerable keys sorted** by UTF-16 code unit, so
+ *    `{a,b}` and `{b,a}` canonicalize identically. (Duplicate keys cannot exist on a live JS object —
+ *    last-wins already happened at parse/construction — so they need no special handling here.)
+ *  - function / symbol → tagged tokens (`fn` / `y:<desc>`) so the serializer stays total; these never appear
+ *    in design/37 post-hook tool args (which are JSON values), but encoding rather than throwing keeps a
+ *    weird arg from silently degrading a durable suspend to a non-durable fallback.
+ */
+export function canonicalize(value) {
+    // Total at the TOP level too (round-2 MAJOR): `encode`'s per-object try/catch keeps NESTED throws local, but
+    // a throw at the top-level primitive branch (e.g. building the result for a string near V8's max length, or
+    // the final concat overflowing it) would escape it. This backstop guarantees `boundInputHashOf` NEVER throws
+    // — the load-bearing post-suspendVM invariant (a throw there skips the unpause compensation → leaked VM).
+    try {
+        return encode(value);
+    }
+    catch {
+        return "<uncanonicalizable>";
+    }
+}
+/**
+ * design/80 D-1 §2 — the server-minted **opaque** boundInputHash: a SHA-256 (hex) over {@link canonicalize}.
+ * Bound at suspend-mint to the pending tool call's input (`pendingAction.args`) and persisted on the
+ * checkpoint; a resume verifies the echoed value by string equality (never re-hashing the resume-side args).
+ * The hex digest is fixed-length and opaque — exactly what the operator sees / the D-G signer signs.
+ */
+export function boundInputHashOf(value) {
+    return createHash("sha256").update(canonicalize(value), "utf8").digest("hex");
+}
+/**
+ * Recursion-depth ceiling. Makes {@link encode} TOTAL against the two ways a naive recursive walk throws:
+ * a CIRCULAR reference (infinite recursion → `Maximum call stack size`) and pathological DEEP nesting (a
+ * RangeError before the JS stack limit). At/below this depth a deterministic sentinel is emitted instead of
+ * recursing — so {@link boundInputHashOf} can never throw. This is load-bearing (MAJOR-4): the hash is minted
+ * AFTER `suspendVM()` paused the remote VM, where a throw would skip the unpause compensation and leak the VM.
+ * 256 is far below the engine's stack limit yet far deeper than any real tool-arg payload.
+ */
+const MAX_DEPTH = 256;
+function encode(value, depth = 0) {
+    if (value === null)
+        return "N";
+    if (value === undefined)
+        return "U";
+    switch (typeof value) {
+        case "boolean":
+            return value ? "b1" : "b0";
+        case "number":
+            return `n:${encodeNumber(value)}`;
+        case "bigint":
+            return `i:${value.toString()}`;
+        case "string":
+            // Byte-length prefix (UTF-8) disambiguates concatenation; the raw string is emitted UN-normalized.
+            return `s${Buffer.byteLength(value, "utf8")}:${value}`;
+        case "function":
+            return "fn";
+        case "symbol":
+            return `y:${value.description ?? ""}`;
+        case "object": {
+            // Depth cap → total: bounds circular refs (infinite recursion) AND deep nesting (RangeError) with a
+            // deterministic sentinel rather than throwing. Distinct pathological inputs may share the sentinel —
+            // acceptable: real tool args are shallow JSON, and a never-throwing hash is the load-bearing property.
+            if (depth >= MAX_DEPTH)
+                return "<max-depth>";
+            try {
+                if (Array.isArray(value)) {
+                    let out = `a${value.length}:[`;
+                    for (const el of value)
+                        out += encode(el, depth + 1);
+                    return `${out}]`;
+                }
+                // Plain object: own enumerable string keys, sorted for canonical order. (Exotic objects such as Date
+                // have no own enumerable keys → `{}` form; design/37 post-hook args are JSON values, so this is the
+                // full universe in practice. Symbol keys are intentionally excluded — JSON has none.) A throwing
+                // getter on `obj[k]` (or a Proxy `ownKeys`) is caught below so encode stays total.
+                const obj = value;
+                const keys = Object.keys(obj).sort();
+                let out = `o${keys.length}:{`;
+                for (const k of keys)
+                    out += `${Buffer.byteLength(k, "utf8")}:${k}=${encode(obj[k], depth + 1)}`;
+                return `${out}}`;
+            }
+            catch {
+                // A throwing getter / exotic Proxy trap — emit a deterministic sentinel rather than propagate.
+                return "<unserializable>";
+            }
+        }
+        default:
+            // Unreachable for the standard `typeof` set above; total fallback keeps determinism.
+            return "U";
+    }
+}
+function encodeNumber(n) {
+    if (Number.isNaN(n))
+        return "NaN";
+    if (n === Infinity)
+        return "Inf";
+    if (n === -Infinity)
+        return "-Inf";
+    if (n === 0)
+        return "0"; // normalize -0 → 0 (they are semantically equal as an argument value)
+    return String(n); // shortest round-trippable decimal — deterministic per IEEE-754 value
+}
+//# sourceMappingURL=canonical-json.js.map

package/dist/core/canonical-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.js","sourceRoot":"","sources":["../../src/core/canonical-json.ts"],"names":[],"mappings":"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"}