@aimarket/warden 0.0.1 → 0.4.0

package/dist/jcs.js

@@ -0,0 +1,296 @@
+/**
+ * RFC 8785 (JSON Canonicalization Scheme) as profiled by AWR/2 (`awr/SPEC.md` §4).
+ *
+ * Two places in WARDEN turn a JSON value into bytes that a *different*
+ * implementation has to reproduce exactly: the signed threat feed (a publisher
+ * signs, ARGUS verifies) and the tool-def pin (a sha256 quoted in receipts and
+ * re-checked by `argus verify`). `JSON.stringify` cannot do that job — its output
+ * depends on the key order the wire happened to use, so one logical document
+ * serialises to different bytes on the two sides and the signature fails for no
+ * security reason at all.
+ *
+ * The profile implemented here, rule by rule:
+ *
+ * 1. **Property names sort as arrays of UTF-16 code units** (RFC 8785 §3.2.3).
+ *    JavaScript's default `Array.prototype.sort()` on strings compares exactly
+ *    that, so this is the one rule the platform gives away for free.
+ *    `String.prototype.localeCompare` does *not*: it depends on the host locale
+ *    and ICU version, which makes it unusable as a digest input.
+ * 2. **No Unicode normalization, ever** (SPEC §4.1 item 2). NFC would collide two
+ *    property names that RFC 8785 keeps distinct.
+ * 3. **Two-character escapes plus lowercase `\uXXXX` for the remaining C0
+ *    controls** (§3.2.2.2) — which is precisely what `JSON.stringify` emits for a
+ *    string, so string bodies are delegated to it rather than re-implemented.
+ * 4. **Lone surrogates terminate with an error** instead of being substituted
+ *    (§4.1 item 4). `JSON.stringify` would quietly escape them into
+ *    valid-looking bytes, so they are rejected before it is called.
+ * 5. **Integers only, within ±(2^53−1)**; every non-integer number is refused
+ *    rather than arbitrated (§4.3), because whether `1` parses as an integer or
+ *    as a double is a language accident that silently changes the signed bytes.
+ *
+ * Scope: this module is *only* the byte-level canonicalization. It knows nothing
+ * about AWR documents, Data Integrity proofs, `did:key` or profiles.
+ */
+/**
+ * A value could not be canonicalized (or parsed) under the AWR profile.
+ *
+ * Callers are expected to *handle* this rather than let it escape: refusing to
+ * produce bytes is the honest outcome, but it must not crash a connection check.
+ */
+export class CanonicalizationError extends Error {
+    code;
+    constructor(code, detail) {
+        super(`${code}: ${detail}`);
+        this.code = code;
+        this.name = "CanonicalizationError";
+    }
+}
+/** Largest magnitude of a JSON integer permitted in canonical bytes (2^53−1). */
+export const MAX_SAFE_JSON_INTEGER = 9007199254740991;
+/**
+ * Nesting bound. Canonicalization runs over attacker-influenced input (a remote
+ * feed, a third-party tool schema), and an unbounded recursive walk is a
+ * denial-of-service (SPEC §13.4).
+ */
+const MAX_DEPTH = 64;
+/**
+ * Return the RFC 8785 canonical serialization of `value` as a UTF-8-ready string.
+ *
+ * Throws {@link CanonicalizationError} rather than emitting bytes it cannot
+ * defend: a non-integer number, an integer beyond 2^53−1, a lone surrogate, an
+ * `undefined` property (which `JSON.stringify` would silently drop), a
+ * non-plain object, or a cycle.
+ */
+export function canonicalize(value) {
+    const out = [];
+    serialize(value, out, "$", 0, new Set());
+    return out.join("");
+}
+function serialize(value, out, path, depth, seen) {
+    if (depth > MAX_DEPTH) {
+        throw new CanonicalizationError("AWR-CANON-005", `nesting deeper than ${MAX_DEPTH} at ${path}`);
+    }
+    if (value === null) {
+        out.push("null");
+        return;
+    }
+    switch (typeof value) {
+        case "boolean":
+            out.push(value ? "true" : "false");
+            return;
+        case "number":
+            out.push(serializeNumber(value, path));
+            return;
+        case "string":
+            out.push(serializeString(value, path));
+            return;
+        case "object":
+            break;
+        default:
+            // undefined, function, symbol, bigint: JSON has no representation, and
+            // guessing one (JSON.stringify drops or throws depending on position) is
+            // exactly the silent divergence this module exists to prevent.
+            throw new CanonicalizationError("AWR-CANON-005", `${typeof value} at ${path} is not representable in JSON`);
+    }
+    const obj = value;
+    if (seen.has(obj))
+        throw new CanonicalizationError("AWR-CANON-005", `circular reference at ${path}`);
+    seen.add(obj);
+    try {
+        if (Array.isArray(obj)) {
+            out.push("[");
+            for (let i = 0; i < obj.length; i++) {
+                if (i > 0)
+                    out.push(",");
+                serialize(obj[i], out, `${path}[${i}]`, depth + 1, seen);
+            }
+            out.push("]");
+            return;
+        }
+        // Only plain records canonicalize. A Date, Map, RegExp or class instance has
+        // no JSON form of its own; `JSON.stringify` would call `toJSON()` or emit
+        // `{}`, inventing bytes the other implementation cannot reproduce.
+        const proto = Object.getPrototypeOf(obj);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new CanonicalizationError("AWR-CANON-005", `${obj.constructor?.name ?? "object"} at ${path} is not a plain JSON object`);
+        }
+        const record = obj;
+        out.push("{");
+        let first = true;
+        // §3.2.3: sort as arrays of UTF-16 code units — the default string sort.
+        for (const key of Object.keys(record).sort()) {
+            const member = record[key];
+            if (member === undefined) {
+                throw new CanonicalizationError("AWR-CANON-005", `property "${key}" at ${path} is undefined — JSON has no such value ` +
+                    `(JSON.stringify would drop it silently, changing the signed bytes)`);
+            }
+            if (!first)
+                out.push(",");
+            first = false;
+            out.push(serializeString(key, `property name "${key}" at ${path}`), ":");
+            serialize(member, out, `${path}.${key}`, depth + 1, seen);
+        }
+        out.push("}");
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
+/** §4.3: integers only, `[-(2^53-1), 2^53-1]`. Everything else is refused. */
+function serializeNumber(n, path) {
+    if (!Number.isFinite(n)) {
+        throw new CanonicalizationError("AWR-CANON-001", `${String(n)} at ${path} is not a JSON number`);
+    }
+    if (!Number.isInteger(n)) {
+        throw new CanonicalizationError("AWR-CANON-001", `non-integer JSON number ${n} at ${path}`);
+    }
+    if (!Number.isSafeInteger(n)) {
+        throw new CanonicalizationError("AWR-CANON-002", `integer ${n} at ${path} is outside ±(2^53−1)`);
+    }
+    // Safe integers never render in exponential form, and `String(-0)` is "0".
+    return String(n);
+}
+/**
+ * §3.2.2.2 string serialization, delegated to `JSON.stringify` — which emits the
+ * same two-character escapes and the same lowercase `\u00xx` for the remaining C0
+ * controls, and leaves every other character literal. The one divergence is lone
+ * surrogates, which it escapes and RFC 8785 forbids, so those are rejected first.
+ */
+function serializeString(text, path) {
+    assertWellFormed(text, path);
+    return JSON.stringify(text);
+}
+/** §4.1 item 4 / `AWR-CANON-003`: unpaired surrogates are an error, not a substitution. */
+function assertWellFormed(text, path) {
+    for (let i = 0; i < text.length; i++) {
+        const unit = text.charCodeAt(i);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const low = text.charCodeAt(i + 1);
+            if (!(low >= 0xdc00 && low <= 0xdfff)) {
+                throw new CanonicalizationError("AWR-CANON-003", `lone high surrogate U+${unit.toString(16).toUpperCase()} at index ${i} in ${path}`);
+            }
+            i++;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff) {
+            throw new CanonicalizationError("AWR-CANON-003", `lone low surrogate U+${unit.toString(16).toUpperCase()} at index ${i} in ${path}`);
+        }
+    }
+}
+/**
+ * Parse JSON with the profile's parser requirements, for input whose bytes were
+ * signed by someone else.
+ *
+ * `JSON.parse` alone is not enough on a verification path:
+ *
+ * - **Duplicate property names** (§4.1 item 5, `AWR-CANON-004`) are resolved
+ *   last-wins and silently, which would let the parser — not the signer — decide
+ *   which of two records was the signed one.
+ * - **Non-integer number literals** (§4.3, `AWR-CANON-001`) are rejected
+ *   *lexically*, not by value: `2340.0` and `2340` parse to the same JavaScript
+ *   number, and a publisher written in a language that distinguishes them would
+ *   have signed different bytes.
+ *
+ * Both checks run over the received text after `JSON.parse` has confirmed it is
+ * well-formed, so the scanner below only has to find tokens, never validate
+ * grammar.
+ */
+export function parseJsonStrict(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (err) {
+        throw new CanonicalizationError("AWR-CANON-005", `not well-formed JSON: ${err.message}`);
+    }
+    auditTokens(text);
+    return value;
+}
+function auditTokens(text) {
+    const tokens = tokenize(text);
+    for (const token of tokens) {
+        if (token.kind === "number")
+            assertIntegerLiteral(token.literal);
+    }
+    // A string immediately followed by `:` inside an object is a property name;
+    // in well-formed JSON nothing else can occupy that position.
+    const stack = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.kind === "{")
+            stack.push(new Set());
+        else if (token.kind === "[")
+            stack.push(null);
+        else if (token.kind === "}" || token.kind === "]")
+            stack.pop();
+        else if (token.kind === "string") {
+            const names = stack[stack.length - 1];
+            if (names && tokens[i + 1]?.kind === ":") {
+                if (names.has(token.value)) {
+                    throw new CanonicalizationError("AWR-CANON-004", `duplicate object property name "${token.value}"`);
+                }
+                names.add(token.value);
+            }
+        }
+    }
+}
+function tokenize(text) {
+    const tokens = [];
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '"') {
+            const start = i;
+            i++;
+            while (i < text.length) {
+                const c = text[i];
+                if (c === "\\") {
+                    i += 2;
+                    continue;
+                }
+                i++;
+                if (c === '"')
+                    break;
+            }
+            // The slice is a valid JSON string literal (JSON.parse already accepted the
+            // whole document), so decoding it cannot fail — and decoding is required:
+            // "a" and "a" are the same property name.
+            tokens.push({ kind: "string", value: JSON.parse(text.slice(start, i)) });
+            continue;
+        }
+        if (ch === "{" || ch === "}" || ch === "[" || ch === "]" || ch === ":" || ch === ",") {
+            tokens.push({ kind: ch });
+            i++;
+            continue;
+        }
+        if (ch === "-" || (ch >= "0" && ch <= "9")) {
+            const start = i;
+            i++;
+            while (i < text.length && /[0-9eE+.\-]/.test(text[i]))
+                i++;
+            tokens.push({ kind: "number", literal: text.slice(start, i) });
+            continue;
+        }
+        // Whitespace and the letters of true/false/null carry nothing we check.
+        i++;
+    }
+    return tokens;
+}
+function assertIntegerLiteral(literal) {
+    if (/[.eE]/.test(literal)) {
+        throw new CanonicalizationError("AWR-CANON-001", `non-integer JSON number literal ${literal}`);
+    }
+    // BigInt, not Number: a 20-digit literal loses precision before it can be
+    // compared, and would slip through as a "safe" integer.
+    let asInt;
+    try {
+        asInt = BigInt(literal);
+    }
+    catch {
+        throw new CanonicalizationError("AWR-CANON-005", `malformed number literal ${literal}`);
+    }
+    const limit = BigInt(MAX_SAFE_JSON_INTEGER);
+    if (asInt > limit || asInt < -limit) {
+        throw new CanonicalizationError("AWR-CANON-002", `integer literal ${literal} is outside ±(2^53−1)`);
+    }
+}
+//# sourceMappingURL=jcs.js.map

package/dist/jcs.js.map

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

package/dist/logger.d.ts

@@ -0,0 +1,10 @@
+import type { WardenLogger } from "./types.js";
+/**
+ * A logger that writes nothing — the default when a host supplies none.
+ *
+ * WARDEN reports every decision through the logger, so a host that drops it
+ * loses the audit trail but never the enforcement: verdicts are returned as
+ * data from `vet()`, not inferred from log output.
+ */
+export declare function silentLogger(): WardenLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAU3C"}

package/dist/logger.js

@@ -0,0 +1,19 @@
+/**
+ * A logger that writes nothing — the default when a host supplies none.
+ *
+ * WARDEN reports every decision through the logger, so a host that drops it
+ * loses the audit trail but never the enforcement: verdicts are returned as
+ * data from `vet()`, not inferred from log output.
+ */
+export function silentLogger() {
+    const noop = () => { };
+    const self = {
+        debug: noop,
+        info: noop,
+        warn: noop,
+        error: noop,
+        child: () => self,
+    };
+    return self;
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,IAAI,GAAG,GAAS,EAAE,GAAE,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAiB;QACzB,KAAK,EAAE,IAAI;QACX,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI;KAClB,CAAC;IACF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/origin.d.ts

@@ -0,0 +1,25 @@
+import type { WardenGate, WardenGateInput, WardenGateResult } from "./types.js";
+/**
+ * Origin gate — enforces `policy.allowUnknownServers` against where a server
+ * declaration came from.
+ *
+ * Every server ARGUS connects to is one of two things: declared by the operator
+ * under `mcp.servers`, or discovered from a remote catalog listed under
+ * `mcp.catalogs` — in which case `McpServerRef.catalog` names that catalog
+ * (see CatalogConnector.normalize). Only the second kind is "unknown": nothing
+ * local ever vouched for it.
+ *
+ * This gate replaces the reputation gate that used to occupy this slot in the
+ * chain. That gate asked LUMEN for a PageRank score without ever supplying trust
+ * edges, so the oracle returned its neutral default without any request being
+ * made: the scored branch was unreachable in production, the composite score was
+ * permanently multiplied by a constant, and the user was told the oracle was
+ * unreachable when nothing had been tried. Catalog provenance needs no network,
+ * is always available, and cannot deadlock — an operator's own servers are known
+ * by definition, so fail-closed still leaves a way to connect.
+ */
+export declare class OriginGate implements WardenGate {
+    readonly name = "origin";
+    evaluate(input: WardenGateInput): Promise<WardenGateResult>;
+}
+//# sourceMappingURL=origin.d.ts.map

package/dist/origin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin.d.ts","sourceRoot":"","sources":["../src/origin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,UAAU,EACV,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,UAAW,YAAW,UAAU;IAC3C,QAAQ,CAAC,IAAI,YAAY;IAGnB,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAyBlE"}

package/dist/origin.js

@@ -0,0 +1,49 @@
+import { displaySafe } from "./sanitize.js";
+/**
+ * Origin gate — enforces `policy.allowUnknownServers` against where a server
+ * declaration came from.
+ *
+ * Every server ARGUS connects to is one of two things: declared by the operator
+ * under `mcp.servers`, or discovered from a remote catalog listed under
+ * `mcp.catalogs` — in which case `McpServerRef.catalog` names that catalog
+ * (see CatalogConnector.normalize). Only the second kind is "unknown": nothing
+ * local ever vouched for it.
+ *
+ * This gate replaces the reputation gate that used to occupy this slot in the
+ * chain. That gate asked LUMEN for a PageRank score without ever supplying trust
+ * edges, so the oracle returned its neutral default without any request being
+ * made: the scored branch was unreachable in production, the composite score was
+ * permanently multiplied by a constant, and the user was told the oracle was
+ * unreachable when nothing had been tried. Catalog provenance needs no network,
+ * is always available, and cannot deadlock — an operator's own servers are known
+ * by definition, so fail-closed still leaves a way to connect.
+ */
+export class OriginGate {
+    name = "origin";
+    // eslint-disable-next-line @typescript-eslint/require-await -- gate interface is async
+    async evaluate(input) {
+        const catalog = input.server.catalog;
+        if (!catalog) {
+            // Operator-declared under mcp.servers: known, nothing to report.
+            return { findings: [], score: 1 };
+        }
+        const strict = input.policy.allowUnknownServers !== true;
+        // Both the id and the catalog name can come from a remote catalog entry, and
+        // this message is printed to the operator's terminal.
+        const id = displaySafe(input.server.id);
+        const from = displaySafe(catalog);
+        const finding = {
+            gate: this.name,
+            severity: strict ? "high" : "info",
+            code: "SERVER_UNDECLARED",
+            message: strict
+                ? `Server "${id}" was discovered from catalog "${from}" and is not declared under mcp.servers; ` +
+                    `policy forbids undeclared servers (allowUnknownServers=false) — blocking. Add it to mcp.servers to allow it.`
+                : `Server "${id}" was discovered from catalog "${from}", not declared under mcp.servers.`,
+        };
+        // Catalog provenance on its own is not a defect, so the permissive path does
+        // not tax the composite score; it only says where the server came from.
+        return { findings: [finding], score: strict ? 0 : 1, fatal: strict };
+    }
+}
+//# sourceMappingURL=origin.js.map

package/dist/origin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin.js","sourceRoot":"","sources":["../src/origin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAQ5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,UAAU;IACZ,IAAI,GAAG,QAAQ,CAAC;IAEzB,uFAAuF;IACvF,KAAK,CAAC,QAAQ,CAAC,KAAsB;QACnC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,iEAAiE;YACjE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACpC,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,mBAAmB,KAAK,IAAI,CAAC;QACzD,6EAA6E;QAC7E,sDAAsD;QACtD,MAAM,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,OAAO,GAAkB;YAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;YAClC,IAAI,EAAE,mBAAmB;YACzB,OAAO,EAAE,MAAM;gBACb,CAAC,CAAC,WAAW,EAAE,kCAAkC,IAAI,2CAA2C;oBAC9F,8GAA8G;gBAChH,CAAC,CAAC,WAAW,EAAE,kCAAkC,IAAI,oCAAoC;SAC5F,CAAC;QACF,6EAA6E;QAC7E,wEAAwE;QACxE,OAAO,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACvE,CAAC;CACF"}

package/dist/pinning.d.ts

@@ -0,0 +1,91 @@
+import type { McpServerRef, PinStore, ToolDef, WardenGate, WardenGateInput, WardenGateResult } from "./types.js";
+/**
+ * Tool-definition pinning + drift detection ("rug-pull" defence).
+ *
+ * A server can advertise benign tools at approval time and silently swap in a
+ * poisoned definition later. We hash the canonical tool-def set on approval and
+ * compare on every subsequent connection: a changed hash means the contract the
+ * user approved no longer holds, so (under policy.pinToolDefs) we block and force
+ * re-approval. First-contact servers are flagged UNPINNED so the chain knows the
+ * pin is established only when the user approves.
+ */
+export declare class PinningGate implements WardenGate {
+    private readonly store;
+    readonly name = "pinning";
+    constructor(store: PinStore);
+    evaluate(input: WardenGateInput): Promise<WardenGateResult>;
+    /**
+     * Has the program behind this server changed since approval?
+     *
+     * Silent when the pin predates {@link PinnedServer.identityHash}: an absent
+     * value is "not recorded", never "changed". The next `approve()` records it.
+     */
+    private identityDrift;
+    /**
+     * The tool-def set has no canonical form (see {@link canonicalToolsHash}), so no
+     * hash can be produced for it. What that means depends on whether a pin exists:
+     *
+     * - **No pin yet** — nothing is being contradicted; the pin simply cannot be
+     *   established, which is a `medium` warning and not evidence of an attack.
+     * - **Pin exists** — the snapshot the user approved can no longer be re-verified,
+     *   which is indistinguishable from drift and is treated as drift. Otherwise a
+     *   server could disarm the rug-pull defence at will by adding one fractional
+     *   number to a schema.
+     */
+    private uncanonical;
+    /**
+     * Persist the current tool-def set as the trusted snapshot for this server.
+     * Called by Warden.approve() once a user has accepted the connection.
+     *
+     * Throws {@link CanonicalizationError} when the set has no canonical form; the
+     * caller (`McpHost.connect`) already reports a pin failure as a degraded
+     * rug-pull defence rather than failing the connection.
+     */
+    pin(server: McpServerRef, tools: ToolDef[]): Promise<void>;
+}
+/**
+ * Marker used where a tool-def hash is *recorded* rather than compared, and the set
+ * turned out to have no canonical form. It can never collide with a sha256 hex
+ * digest, so anything that later compares it simply reports a mismatch.
+ */
+export declare const UNCANONICAL_TOOLS_HASH = "uncanonical:non-canonical-tool-defs";
+/**
+ * sha256 over the canonical tool-def set: tools sorted by name, each reduced to
+ * the security-relevant fields (name, description, schema), serialised with
+ * {@link canonicalize} — RFC 8785 (JCS) as profiled in `awr/SPEC.md` §4.
+ *
+ * This digest is quoted in receipts and re-checked elsewhere (`argus verify`, the
+ * sealed mandate), so it has to be reproducible by an implementation that is not
+ * this one. Two consequences:
+ *
+ * - **Ordering is by UTF-16 code unit, never `localeCompare`.** `localeCompare`
+ *   depends on the host locale and ICU version — `["a", "B"]` sorts one way under
+ *   `en-US` and another under the C locale — so a digest built on it is not even
+ *   stable across two machines running this same code, let alone across languages.
+ *   JavaScript's `<`/`>` on strings compare UTF-16 code units, which is exactly
+ *   RFC 8785 §3.2.3's rule.
+ * - **Non-integer numbers are refused** (`AWR-CANON-001`, SPEC §4.3) rather than
+ *   serialised. Whether `1` is an integer or a double is a language accident that
+ *   silently changes the bytes, so a schema carrying e.g. `"multipleOf": 0.01` has
+ *   no canonical form here and this function throws
+ *   {@link CanonicalizationError}. Callers must handle that — refusing to emit a
+ *   digest is honest; emitting one nobody else can reproduce is not.
+ */
+export declare function canonicalToolsHash(tools: ToolDef[]): string;
+/**
+ * Like {@link canonicalToolsHash} but total: returns `undefined` instead of
+ * throwing, for call sites that record a hash rather than enforce one.
+ */
+export declare function tryCanonicalToolsHash(tools: ToolDef[]): string | undefined;
+/**
+ * sha256 over the server's launch identity: transport, command, args, url, name.
+ *
+ * Deliberately NOT the whole `McpServerRef`: `catalog` is provenance rather than
+ * identity (the origin gate is what has an opinion about it), and `env` holds
+ * secrets that must not be hashed into a value stored on disk next to the pin.
+ *
+ * Missing fields serialize as empty rather than being omitted, so a server that
+ * gains a `url` reads as a change instead of hashing the same as before.
+ */
+export declare function serverIdentityHash(server: McpServerRef): string;
+//# sourceMappingURL=pinning.d.ts.map

package/dist/pinning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinning.d.ts","sourceRoot":"","sources":["../src/pinning.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,YAAY,EACZ,QAAQ,EAER,OAAO,EAEP,UAAU,EACV,eAAe,EACf,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;GASG;AACH,qBAAa,WAAY,YAAW,UAAU;IAGhC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAFlC,QAAQ,CAAC,IAAI,aAAa;gBAEG,KAAK,EAAE,QAAQ;IAEtC,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqDjE;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAerB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,WAAW;IAgCnB;;;;;;;OAOG;IACG,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAUjE;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,wCAAwC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAS3D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,GAAG,SAAS,CAO1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAS/D"}