@agenthippo-ai/agenthippo 0.2.3-dataplane → 1.110.9

package/out/pack/signature.js

@@ -0,0 +1,839 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACK_FULL_REVERIFY_INTERVAL_MS = exports.PACK_PROBE_INTERVAL_MS = exports.LEASE_JWKS_PINS_ENV = exports.LEASE_JWKS_URL_ENV = exports.LEASE_SIGNING_KEYS_ENV = exports.ALLOW_INSECURE_TRUST_ROOT_ENV = exports.PACK_JWKS_PINS_ENV = exports.PACK_JWKS_URL_ENV_LEGACY = exports.PACK_JWKS_URL_ENV = exports.ALLOW_UNSIGNED_PACK_ENV = exports.DIGEST_EXCLUDED_SEGMENTS = exports.PACK_SIGNATURE_FILE = void 0;
+exports.isDigestExcluded = isDigestExcluded;
+exports.computePackDigestFromFiles = computePackDigestFromFiles;
+exports.computePackDigest = computePackDigest;
+exports.packTreeProbe = packTreeProbe;
+exports.signPack = signPack;
+exports.readPackSignature = readPackSignature;
+exports.verifyPack = verifyPack;
+exports.verifyPackFromFiles = verifyPackFromFiles;
+exports.requireSignedPack = requireSignedPack;
+exports.resolveRequireSignedPack = resolveRequireSignedPack;
+exports.allowUnsignedPackFromEnv = allowUnsignedPackFromEnv;
+exports.describePackRefusal = describePackRefusal;
+exports.publicKeyThumbprints = publicKeyThumbprints;
+exports.parseJwksPins = parseJwksPins;
+exports.assertSecureTrustUrl = assertSecureTrustUrl;
+exports.loadPackTrustRoot = loadPackTrustRoot;
+exports.loadLeaseTrustRoot = loadLeaseTrustRoot;
+exports.selectLeaseSigningKeys = selectLeaseSigningKeys;
+exports.loadPackSigningKeys = loadPackSigningKeys;
+exports.createPackVerifier = createPackVerifier;
+/**
+ * Pack signing — the gate that has to exist before a control plane may ever FETCH an artifact.
+ *
+ * A reconcile loop that pulls a pack and runs it is a remote-code-execution feature until a
+ * signature decides what it is allowed to run. So this lands first, on its own, and the pull
+ * comes after: verification with no fetch is merely unused; a fetch with no verification is a
+ * vulnerability.
+ *
+ * Shape, and why:
+ *
+ *   digest    — sha256 over the pack's files, path AND content, sorted, each length-prefixed.
+ *               Length prefixes matter: without them `a/b` + `c` and `a/bc` + `''` hash the same,
+ *               so a rename could be laundered into an identical digest.
+ *   signature — a compact JWS (ES256) whose payload names the pack, the version, and that digest.
+ *               Binding all three is what stops a valid signature being replayed onto a different
+ *               pack or a different version of the same one — a bare content signature would let
+ *               an attacker who can place files claim any name they like.
+ *   keys      — verified with PUBLIC halves only, distributed by the control plane's existing
+ *               JWKS endpoint (which refuses private material). Whoever verifies cannot sign,
+ *               which is the same asymmetry the inference warrants rely on.
+ *
+ * Deliberately NOT expiring: a warrant is turn-short because it authorises spend, but a pack
+ * signature attests to content that does not rot. An expiry here would ground a fleet on a
+ * calendar boundary for no security gain.
+ */
+const crypto = __importStar(require("node:crypto"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const warrant_1 = require("../authority/warrant");
+/** Written at the pack root. Excluded from the digest — it cannot cover itself. */
+exports.PACK_SIGNATURE_FILE = 'pack.sig';
+/**
+ * Path segments never hashed, at ANY depth: VCS metadata and installed dependencies.
+ *
+ * This list used to also carry `.claude`, `.codex`, `.agent-hippo` and `.DS_Store`, and the walk
+ * tested it on every directory entry rather than only at the top level — despite a comment
+ * claiming "top-level". The result was a hole big enough to drive a payload through:
+ * `.claude/settings.json` is where Claude Code reads its HOOKS from, i.e. arbitrary shell commands
+ * that run around every tool call. A pack with an injected `PreToolUse` hook verified clean, and
+ * `agenthippo pack verify` printed OK. The same was true of `.codex/` and `.agent-hippo/`.
+ *
+ * Executable content is now IN the digest. The cost is real and accepted: anything that writes
+ * into a pack directory after signing (including macOS writing `.DS_Store` when someone opens the
+ * folder in Finder) invalidates the signature, and the pack must be re-signed. That is the correct
+ * direction to fail — "the tree changed since it was signed" is exactly what the signature is for,
+ * and the failure says so.
+ *
+ * `.git` and `node_modules` remain excluded at every depth because they are not pack content: a
+ * checkout's git objects differ per clone, and dependencies are installed, not authored. Excluding
+ * them at every depth (rather than only the top level) is deliberate — a nested `node_modules`
+ * from a workspace install is the same non-content.
+ */
+exports.DIGEST_EXCLUDED_SEGMENTS = new Set(['.git', 'node_modules']);
+/**
+ * The ONE predicate both digest paths use.
+ *
+ * `computePackDigest` (directory walk) and `computePackDigestFromFiles` (fetched artifact) MUST
+ * agree for identical trees, or a locally-signed pack can never verify through the store path —
+ * which is precisely what happened when the walk excluded seven names and the file list excluded
+ * one. There is a test asserting the two agree on a tree containing every excluded and formerly
+ * excluded name.
+ *
+ * @param relPosixPath path RELATIVE to the pack root, `/`-separated.
+ */
+function isDigestExcluded(relPosixPath) {
+    if (relPosixPath === exports.PACK_SIGNATURE_FILE) {
+        return true;
+    }
+    return relPosixPath.split('/').some((seg) => exports.DIGEST_EXCLUDED_SEGMENTS.has(seg));
+}
+/**
+ * The single hashing routine. Sorted so two checkouts agree regardless of readdir order, and
+ * length-prefixed so no combination of names and contents can be rearranged into the same hash.
+ *
+ * Symlinks are hashed as their TARGET STRING rather than followed (following them would let a link
+ * resolving differently on another host produce the same digest for different bytes) and carry an
+ * `L:` domain tag so a symlink `a → b` cannot be swapped for a regular file `a` containing `b`.
+ * Regular-file framing is unchanged, so signatures over packs without symlinks still verify.
+ */
+function hashEntries(entries) {
+    const hash = crypto.createHash('sha256');
+    const sorted = [...entries].sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+    for (const entry of sorted) {
+        if (entry.link) {
+            hash.update('L:');
+        }
+        const rel = Buffer.from(entry.rel);
+        // length-prefix both halves — see the header note on rename laundering
+        hash.update(`${rel.length}:`);
+        hash.update(rel);
+        hash.update(`${entry.body.length}:`);
+        hash.update(entry.body);
+    }
+    return hash.digest('hex');
+}
+/**
+ * Hash an artifact file list (a store download, or a materialised tree read back).
+ *
+ * Uses `isDigestExcluded`, exactly like the directory walk. It previously excluded only `pack.sig`
+ * while the walk excluded seven names, so any pack containing `.claude/`, `.codex/` or
+ * `.agent-hippo/` produced two different digests and could never verify through the store path.
+ */
+function computePackDigestFromFiles(files) {
+    const entries = [];
+    for (const f of files) {
+        const rel = f.path.replace(/\\/g, '/');
+        if (isDigestExcluded(rel)) {
+            continue;
+        }
+        entries.push({ rel, body: f.content, link: f.link });
+    }
+    return hashEntries(entries);
+}
+/** Deterministic digest of a pack directory. */
+function computePackDigest(packDir) {
+    const entries = [];
+    const walk = (dir, prefix) => {
+        for (const name of fs.readdirSync(dir)) {
+            const rel = prefix ? `${prefix}/${name}` : name;
+            if (isDigestExcluded(rel)) {
+                continue;
+            }
+            const abs = path.join(dir, name);
+            const st = fs.lstatSync(abs);
+            if (st.isSymbolicLink()) {
+                entries.push({ rel, body: Buffer.from(fs.readlinkSync(abs)), link: true });
+            }
+            else if (st.isDirectory()) {
+                walk(abs, rel);
+            }
+            else if (st.isFile()) {
+                entries.push({ rel, body: fs.readFileSync(abs) });
+            }
+            // Sockets, fifos and devices are not pack content; ignoring them keeps the digest
+            // stable across environments that happen to leave one behind.
+        }
+    };
+    walk(packDir, '');
+    return hashEntries(entries);
+}
+/**
+ * A CHEAP probe of a pack tree, for deciding whether a full re-verify is needed.
+ *
+ * Not a security boundary on its own — see `createPackVerifier`, which pairs it with a periodic
+ * unconditional re-verify. This walks the tree with `lstat` only: no file is read and nothing is
+ * hashed, so the cost is O(entries) syscalls rather than O(bytes) of SHA-256. On a typical pack
+ * (tens to low hundreds of files) that is sub-millisecond, which is what makes it acceptable on
+ * the turn path where a full digest is not.
+ *
+ * Covers: content edits (mtime + size), whole-file replacement (inode), permission changes (mode),
+ * and any addition or removal (the entry list itself).
+ */
+function packTreeProbe(packDir) {
+    const parts = [];
+    const walk = (dir, prefix) => {
+        let names;
+        try {
+            names = fs.readdirSync(dir).sort();
+        }
+        catch {
+            parts.push(`${prefix}/?unreadable`);
+            return;
+        }
+        for (const name of names) {
+            const rel = prefix ? `${prefix}/${name}` : name;
+            if (isDigestExcluded(rel)) {
+                continue;
+            }
+            const abs = path.join(dir, name);
+            let st;
+            try {
+                st = fs.lstatSync(abs);
+            }
+            catch {
+                parts.push(`${rel}|gone`);
+                continue;
+            }
+            if (st.isDirectory()) {
+                walk(abs, rel);
+                continue;
+            }
+            parts.push(`${rel}|${st.size}|${st.mtimeMs}|${st.ino}|${st.mode}`);
+        }
+    };
+    try {
+        walk(packDir, '');
+    }
+    catch {
+        return 'unwalkable';
+    }
+    return crypto.createHash('sha256').update(parts.join('\n')).digest('hex');
+}
+/** Sign a pack in place: computes the digest and writes `pack.sig` at the pack root. */
+function signPack(input) {
+    const digest = computePackDigest(input.packDir);
+    const claims = {
+        pack: input.pack,
+        packVersion: input.packVersion,
+        digest,
+        iat: input.nowSeconds ?? Math.floor(Date.now() / 1000),
+    };
+    const signature = (0, warrant_1.signCompactJws)({ typ: 'JWT', kid: input.kid }, claims, input.privateKeyPem);
+    fs.writeFileSync(path.join(input.packDir, exports.PACK_SIGNATURE_FILE), `${signature}\n`);
+    return { signature, digest };
+}
+function readPackSignature(packDir) {
+    try {
+        const raw = fs.readFileSync(path.join(packDir, exports.PACK_SIGNATURE_FILE), 'utf8').trim();
+        return raw || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Verify a pack against public keys only.
+ *
+ * Every failure is a refusal with a stated reason rather than a thrown error, because the caller
+ * is an admission decision: it needs to log precisely why a pack was rejected, and "unknown kid"
+ * and "content changed after signing" are very different operational problems.
+ */
+function verifyPack(token, publicKeysByKid, input) {
+    return verifyPackAgainst(token, publicKeysByKid, input.pack, input.packVersion, () => computePackDigest(input.packDir));
+}
+/**
+ * Verify a downloaded artifact against its signature using the fetched file list, not a directory
+ * walk. Both paths hash through `isDigestExcluded`, so a tree and the file list it was built from
+ * produce the SAME digest — the property `pack-digest-parity.test.ts` pins.
+ */
+function verifyPackFromFiles(token, publicKeysByKid, pack, packVersion, files) {
+    return verifyPackAgainst(token, publicKeysByKid, pack, packVersion, () => computePackDigestFromFiles(files));
+}
+/** The shared body of both verify paths — identity binding, then digest. */
+function verifyPackAgainst(token, publicKeysByKid, pack, packVersion, actualDigest) {
+    if (Object.keys(publicKeysByKid).length === 0) {
+        // Distinct from every other refusal, and with a distinct remedy: nothing is wrong with the
+        // pack, this instance simply has nothing to check it against. Verifying against an empty
+        // keyring would otherwise report success for any signature at all.
+        return { ok: false, kind: 'no-trust-root', reason: 'no trusted pack-signing keys are configured on this instance' };
+    }
+    // alg pinning, kid-must-be-known and the raw R||S encoding all live in verifyCompactJws.
+    const jws = (0, warrant_1.verifyCompactJws)(token, publicKeysByKid);
+    if (!jws.ok) {
+        if (jws.reason === 'unknown kid') {
+            // Never trusted-on-first-use: accepting a key because it arrived with the artifact would
+            // let anyone who can write the pack also choose who vouches for it.
+            const kid = readUnverifiedKid(token);
+            return { ok: false, kind: 'unknown-key', reason: `unknown signing key ${kid ?? '(none named)'}` };
+        }
+        if (jws.reason === 'bad signature') {
+            return { ok: false, kind: 'bad-signature', reason: 'signature does not verify' };
+        }
+        if (jws.reason === 'malformed') {
+            return { ok: false, kind: 'malformed', reason: 'malformed signature' };
+        }
+        if (jws.reason === 'unparseable') {
+            return { ok: false, kind: 'malformed', reason: 'unreadable signature' };
+        }
+        return { ok: false, kind: 'malformed', reason: jws.reason };
+    }
+    const claims = jws.payload;
+    // Identity binding is checked BEFORE the digest: a signature that verifies cryptographically
+    // but names a different pack is an attempted replay, and saying so is more useful than
+    // reporting a digest mismatch.
+    if (claims.pack !== pack) {
+        return { ok: false, kind: 'identity-mismatch', reason: `signature is for pack ${claims.pack}, not ${pack}` };
+    }
+    if (claims.packVersion !== packVersion) {
+        return { ok: false, kind: 'identity-mismatch', reason: `signature is for ${claims.pack}@${claims.packVersion}, not @${packVersion}` };
+    }
+    if (typeof claims.digest !== 'string' || !claims.digest) {
+        return { ok: false, kind: 'malformed', reason: 'signature carries no digest' };
+    }
+    if (!(0, warrant_1.timingSafeEqualString)(actualDigest(), claims.digest)) {
+        return { ok: false, kind: 'digest-mismatch', reason: 'pack contents changed after signing' };
+    }
+    return { ok: true, claims };
+}
+/** The `kid` a token CLAIMS, for error messages only — never for a trust decision. */
+function readUnverifiedKid(token) {
+    try {
+        const header = JSON.parse(Buffer.from(token.split('.')[0], 'base64url').toString('utf8'));
+        return header.kid;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Signature requirement, merged tighten-only.
+ *
+ * Either side may demand signed packs; neither may waive the other's demand. Same rule as caps,
+ * and for the same reason: a requirement an instance can switch off by editing its own flags is
+ * decorative, and this one gates code execution.
+ */
+function requireSignedPack(leaseValue, localValue) {
+    return Boolean(leaseValue) || Boolean(localValue);
+}
+/** Escape hatch for local development. Loud on every boot; the lease can still override it. */
+exports.ALLOW_UNSIGNED_PACK_ENV = 'AGENTHIPPO_ALLOW_UNSIGNED_PACK';
+/**
+ * Is a verified signature REQUIRED for this pack to run?
+ *
+ * **Default: yes.** This flipped from opt-in. `requireSignedPack` used to be off unless an operator
+ * turned it on, so the shipped default was warn-and-run: serve logged
+ * `[Pack] unsigned or unverifiable — …` and then executed the pack anyway. A gate that logs and
+ * proceeds is not a gate, and the commit message "verify before run, fail closed" was not true of
+ * the default shape.
+ *
+ * Tighten-only is preserved exactly: the LEASE's demand is checked first and cannot be waived, so
+ * an instance can never opt out of a requirement the control plane made. The escape hatch only
+ * relaxes the instance's OWN default.
+ */
+function resolveRequireSignedPack(opts) {
+    if (requireSignedPack(opts.lease, opts.localRequire)) {
+        return true;
+    }
+    return !opts.localAllowUnsigned;
+}
+/** Reads the escape hatch from the environment. `1`/`true`/`yes` enable it; anything else does not. */
+function allowUnsignedPackFromEnv(env = process.env) {
+    const raw = env[exports.ALLOW_UNSIGNED_PACK_ENV]?.trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes';
+}
+/**
+ * The operator-facing refusal.
+ *
+ * Written out longhand on purpose. Flipping the default to refuse WILL stop deployments that ran
+ * unsigned packs, and the difference between a good and a terrible version of that change is
+ * entirely in this function: an operator must learn from the message alone what is wrong, how to
+ * fix it properly, and how to get moving again right now.
+ */
+function describePackRefusal(ctx) {
+    const id = ctx.packVersion ? `${ctx.pack}@${ctx.packVersion}` : ctx.pack;
+    const lines = [`refusing to run ${id}: ${ctx.detail}`];
+    switch (ctx.kind) {
+        case 'unsigned':
+            lines.push(`  The pack directory has no ${exports.PACK_SIGNATURE_FILE}${ctx.packDir ? ` at ${ctx.packDir}` : ''}.`, `  Sign it:  agenthippo pack sign ${ctx.pack} --key <private-key.pem> --kid <key-id>`, '  (generate a key with: agenthippo pack keygen -o key.pem, then publish its public half to JWKS)');
+            break;
+        case 'no-trust-root':
+            lines.push('  This is NOT a problem with the pack — this instance has no keys to check it against.', '  Configure ONE of:', '    AGENTHIPPO_PACK_SIGNING_KEYS   inline JSON {"<kid>":"<public PEM>"} (air-gapped installs)', `    ${exports.PACK_JWKS_URL_ENV}        https URL of the JWKS document publishing your signing keys`, `    ${exports.PACK_JWKS_PINS_ENV}       optional, comma-separated sha256 thumbprints to pin those keys to`);
+            break;
+        case 'trust-root-unavailable':
+            lines.push('  A trust root IS configured but could not be loaded, so no signature can be checked.', `  ${ctx.trustRootHint ?? ''}`.trimEnd(), '  This is deliberately an error and not an empty keyring: "cannot reach the trust root" and', '  "no trust root configured" have different causes and different fixes.');
+            break;
+        case 'unknown-key':
+            lines.push('  The pack IS signed, but by a key this fleet does not trust.', '  Either publish that key to your JWKS / AGENTHIPPO_PACK_SIGNING_KEYS, or re-sign the pack', '  with a key that is already trusted. A key is never trusted just because it arrived with the pack.');
+            break;
+        case 'digest-mismatch':
+            lines.push('  The signature is valid but the pack tree no longer matches it — something changed after signing.', '  Note that .claude/, .codex/ and .agent-hippo/ are now INSIDE the digest (they carry hooks and', '  other executable content), so edits there invalidate a signature that used to survive them.', `  Re-sign after reviewing the diff:  agenthippo pack sign ${ctx.pack} --key <private-key.pem> --kid <key-id>`);
+            break;
+        case 'identity-mismatch':
+            lines.push('  The signature is valid but names a different pack or version — a replayed signature, not this artifact.');
+            break;
+        case 'malformed':
+        case 'bad-signature':
+            lines.push(`  ${exports.PACK_SIGNATURE_FILE} is present but unusable. Re-sign the pack; do not hand-edit it.`);
+            break;
+        case 'no-pack':
+            break;
+    }
+    lines.push(`  To run unsigned packs anyway (LOCAL DEVELOPMENT ONLY), set ${exports.ALLOW_UNSIGNED_PACK_ENV}=1.`, '  A lease that sets requireSignedPack overrides that escape hatch — the control plane\'s demand cannot be waived locally.');
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------------------------
+// Trust root
+// ---------------------------------------------------------------------------------------------
+/** Dedicated JWKS URL. Pins the trust root INDEPENDENTLY of wherever the lease happens to live. */
+exports.PACK_JWKS_URL_ENV = 'AGENTHIPPO_PACK_JWKS_URL';
+/** Legacy name for the same thing; still honoured. */
+exports.PACK_JWKS_URL_ENV_LEGACY = 'AGENTHIPPO_PACK_SIGNING_JWKS_URL';
+/** Comma-separated sha256 thumbprints. Any key not matching one of these is refused. */
+exports.PACK_JWKS_PINS_ENV = 'AGENTHIPPO_PACK_JWKS_PINS';
+/** Local-dev escape hatch allowing a plaintext-http trust root / lease origin. Logs loudly. */
+exports.ALLOW_INSECURE_TRUST_ROOT_ENV = 'AGENTHIPPO_ALLOW_INSECURE_TRUST_ROOT';
+/**
+ * The LEASE trust root — the same three knobs, named the same way, one word different.
+ *
+ * Deliberately parallel to the pack names so an operator who has configured one can guess the
+ * other. They must be separate keyrings, not one: the control plane publishes the lease public key
+ * under purpose `lease-signing` and REFUSES to register a single kid under two purposes, so a
+ * correctly-configured plane and a serve that verified leases against the pack keyring could never
+ * agree on a key — and `requireSignedLease` is sticky with no plane-side undo, so that disagreement
+ * latches an instance into refusing turns. Separating the roots is also the right shape on its own:
+ * a lease-signing key that lives in the pack keyring is a key that can authorise code execution.
+ */
+exports.LEASE_SIGNING_KEYS_ENV = 'AGENTHIPPO_LEASE_SIGNING_KEYS';
+exports.LEASE_JWKS_URL_ENV = 'AGENTHIPPO_LEASE_JWKS_URL';
+exports.LEASE_JWKS_PINS_ENV = 'AGENTHIPPO_LEASE_JWKS_PINS';
+/**
+ * sha256 thumbprints of a public key, in both forms an operator is likely to have.
+ *
+ *   jwk  — RFC 7638 JWK thumbprint, base64url. What `openssl`-free tooling and most JWKS
+ *          publishers produce, and what a `kid` is conventionally derived from.
+ *   spki — sha256 over the DER SPKI, hex. What `openssl pkey -pubout -outform der | sha256sum`
+ *          gives, which is what an operator with a PEM in hand will reach for first.
+ *
+ * A pin matching EITHER is accepted, with or without a `sha256:` prefix, case-insensitively.
+ * Publishing both costs nothing and removes an entire class of "my pin doesn't match" tickets.
+ */
+function publicKeyThumbprints(publicKeyPem) {
+    const key = crypto.createPublicKey(publicKeyPem);
+    const jwk = key.export({ format: 'jwk' });
+    // RFC 7638: lexicographically ordered, whitespace-free JSON of the REQUIRED members only.
+    const required = jwk.kty === 'EC'
+        ? { crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y }
+        : jwk.kty === 'RSA'
+            ? { e: jwk.e, kty: jwk.kty, n: jwk.n }
+            : { kty: jwk.kty };
+    return {
+        jwk: crypto.createHash('sha256').update(JSON.stringify(required)).digest('base64url'),
+        spki: crypto.createHash('sha256').update(key.export({ type: 'spki', format: 'der' })).digest('hex'),
+    };
+}
+const normalisePin = (p) => p.trim().replace(/^sha256:/i, '').toLowerCase();
+/** Parse the pin list. Empty/blank ⇒ no pinning. */
+function parseJwksPins(raw) {
+    return (raw ?? '').split(',').map(normalisePin).filter((p) => p.length > 0);
+}
+/**
+ * Is this URL safe to fetch a TRUST ROOT from?
+ *
+ * The keyring that decides which code may run must not be fetched over a channel any on-path
+ * device can rewrite. https is required; the escape hatch exists because a local control plane on
+ * `http://localhost` is a real development shape, and it is deliberately loud.
+ */
+function assertSecureTrustUrl(url, what, env = process.env) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { ok: false, reason: `${what} is not a valid URL: ${url}` };
+    }
+    if (parsed.protocol === 'https:') {
+        return { ok: true, warnings: [] };
+    }
+    const allowed = (env[exports.ALLOW_INSECURE_TRUST_ROOT_ENV] ?? '').trim().toLowerCase();
+    if (allowed === '1' || allowed === 'true' || allowed === 'yes') {
+        return {
+            ok: true,
+            warnings: [
+                `INSECURE: ${what} is ${parsed.protocol}//${parsed.host} (not https) and ` +
+                    `${exports.ALLOW_INSECURE_TRUST_ROOT_ENV} is set. Anyone on the path between this instance and that ` +
+                    'host can choose which packs it will run and whether the kill switch is honoured. ' +
+                    'This must never be set outside local development.',
+            ],
+        };
+    }
+    return {
+        ok: false,
+        reason: `${what} must be https (got ${parsed.protocol}//${parsed.host}). ` +
+            `Set ${exports.ALLOW_INSECURE_TRUST_ROOT_ENV}=1 to allow plaintext for LOCAL DEVELOPMENT ONLY.`,
+    };
+}
+const PACK_TRUST_ROOT_SPEC = {
+    label: 'pack',
+    purpose: 'pack-signing',
+    inlineEnv: 'AGENTHIPPO_PACK_SIGNING_KEYS',
+    urlEnvs: [exports.PACK_JWKS_URL_ENV, exports.PACK_JWKS_URL_ENV_LEGACY],
+    pinsEnv: exports.PACK_JWKS_PINS_ENV,
+    derivedRisk: 'chooses which packs this instance will run',
+};
+const LEASE_TRUST_ROOT_SPEC = {
+    label: 'lease',
+    purpose: 'lease-signing',
+    inlineEnv: exports.LEASE_SIGNING_KEYS_ENV,
+    urlEnvs: [exports.LEASE_JWKS_URL_ENV],
+    pinsEnv: exports.LEASE_JWKS_PINS_ENV,
+    derivedRisk: "chooses whether this instance's kill switch is ever honoured",
+};
+/**
+ * Public halves used to verify one class of signature.
+ *
+ * Three sources, in precedence order:
+ *   1. `<…>_SIGNING_KEYS` — inline kid→PEM JSON. Air-gapped installs; no network at all.
+ *   2. `<…>_JWKS_URL` (plus, for packs, the legacy `…_SIGNING_JWKS_URL`) — an EXPLICIT trust root.
+ *   3. `/.well-known/jwks.json?purpose=<purpose>` on the lease origin — back-compat, reported weaker.
+ *
+ * (3) is why this function exists in this shape. The whole governance story — kill switch, deny
+ * rules, caps, version pin, pack signing — was rooted in an origin named by `AGENTHIPPO_LEASE_URL`
+ * and fetched with a bare `fetch()`: no scheme check, no pinning, and nothing signing the key
+ * document. Whoever could answer that URL could hand the fleet its trust root. Now: https is
+ * required unless explicitly opted out of, the trust root can be pinned independently of the lease,
+ * and thumbprint pins let an operator refuse any key the plane did not previously publish.
+ *
+ * And a load FAILURE is no longer an empty keyring (finding A4). "No trust root configured" and
+ * "trust root configured but unreachable" are different states with different remedies; collapsing
+ * them into `{}` meant a 503 during a rolling restart looked exactly like an unmanaged deployment.
+ *
+ * NOT re-fetched once `configured` — that is the caller's job (`serve` retries only while a root is
+ * missing), so key rotation still needs the documented restart and a compromised plane cannot swap
+ * a trust root under a running instance mid-flight. Both roots behave identically here.
+ */
+async function loadTrustRoot(spec, opts) {
+    const env = opts.env ?? process.env;
+    const warnings = [];
+    const pins = parseJwksPins(env[spec.pinsEnv]);
+    const inline = env[spec.inlineEnv]?.trim();
+    const explicit = spec.urlEnvs.map((name) => env[name]).find((v) => v !== undefined && v.trim() !== '')?.trim();
+    // Read BEFORE any early return: `unavailable` still has to say whether an operator asked for it.
+    const explicitlyConfigured = Boolean(inline) || Boolean(explicit);
+    const applyPins = (keys, source, url) => {
+        if (pins.length === 0) {
+            return Object.keys(keys).length === 0
+                ? { status: 'unavailable', keys: {}, source, url, warnings, explicitlyConfigured, reason: 'the trust root published no usable ES256 keys' }
+                : { status: 'configured', keys, source, url, warnings, explicitlyConfigured };
+        }
+        const kept = {};
+        for (const [kid, pem] of Object.entries(keys)) {
+            let tp;
+            try {
+                tp = publicKeyThumbprints(pem);
+            }
+            catch {
+                warnings.push(`${spec.label} trust root: key ${kid} is unreadable and was dropped`);
+                continue;
+            }
+            const matched = pins.some((p) => (0, warrant_1.timingSafeEqualString)(p, tp.jwk.toLowerCase()) || (0, warrant_1.timingSafeEqualString)(p, tp.spki));
+            if (matched) {
+                kept[kid] = pem;
+            }
+            else {
+                warnings.push(`${spec.label} trust root: key ${kid} does not match any pin in ${spec.pinsEnv} and was REFUSED ` +
+                    `(its thumbprints are jwk=${tp.jwk} spki=${tp.spki})`);
+            }
+        }
+        if (Object.keys(kept).length === 0) {
+            return {
+                status: 'unavailable', keys: {}, source, url, warnings, explicitlyConfigured,
+                reason: `every key offered by the trust root failed the ${spec.pinsEnv} pin check`,
+            };
+        }
+        return { status: 'configured', keys: kept, source, url, warnings, explicitlyConfigured };
+    };
+    if (inline) {
+        let parsed;
+        try {
+            parsed = JSON.parse(inline);
+        }
+        catch (err) {
+            // Previously `{}` — i.e. a typo in an env var silently became "unmanaged".
+            return {
+                status: 'unavailable', keys: {}, source: 'inline', warnings, explicitlyConfigured,
+                reason: `${spec.inlineEnv} is set but is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        return applyPins(parsed, 'inline');
+    }
+    let url = explicit;
+    let derivedFromLease = false;
+    if (!url && opts.leaseUrl) {
+        // `?purpose=…` because the bare path's meaning belongs to the plane: it used to return every
+        // key it held, and a control plane that separates keys by purpose may now default it to
+        // something else entirely. Asking for the purpose we actually need makes this fallback survive
+        // that change — an older plane ignores the query string and returns the same document it
+        // always did, so this is safe in both directions.
+        //
+        // The plane also publishes `/.well-known/lease-jwks.json` as an alias for
+        // `?purpose=lease-signing`. The query form is used for BOTH roots on purpose: one derivation
+        // rule, one thing to reason about, and it is the form that already survives a plane changing
+        // what the bare path defaults to.
+        try {
+            url = new URL(`/.well-known/jwks.json?purpose=${spec.purpose}`, opts.leaseUrl).toString();
+        }
+        catch {
+            return { status: 'unavailable', keys: {}, warnings, explicitlyConfigured, reason: `AGENTHIPPO_LEASE_URL is not a valid URL: ${opts.leaseUrl}` };
+        }
+        derivedFromLease = true;
+    }
+    if (!url) {
+        return { status: 'unconfigured', keys: {}, warnings, explicitlyConfigured };
+    }
+    const secure = assertSecureTrustUrl(url, `the ${spec.purpose} JWKS URL`, env);
+    if (!secure.ok) {
+        return { status: 'unavailable', keys: {}, source: 'jwks', url, warnings, reason: secure.reason, derivedFromLease, explicitlyConfigured };
+    }
+    warnings.push(...secure.warnings);
+    if (derivedFromLease && pins.length === 0) {
+        warnings.push(`${spec.label} trust root is derived from AGENTHIPPO_LEASE_URL (${url}) and is not pinned. Whoever can answer ` +
+            `that origin ${spec.derivedRisk}. Pin it with ${spec.urlEnvs[0]} and ` +
+            `${spec.pinsEnv}.`);
+    }
+    try {
+        const res = await (opts.fetchImpl ?? fetch)(url);
+        if (!res.ok) {
+            return { status: 'unavailable', keys: {}, source: 'jwks', url, warnings, reason: `JWKS fetch returned HTTP ${res.status}`, derivedFromLease, explicitlyConfigured };
+        }
+        const doc = (await res.json());
+        const keys = jwksToPems(doc);
+        if (!keys.ok) {
+            return { status: 'unavailable', keys: {}, source: 'jwks', url, warnings, reason: keys.reason, derivedFromLease, explicitlyConfigured };
+        }
+        const result = applyPins(keys.pems, 'jwks', url);
+        return { ...result, derivedFromLease };
+    }
+    catch (err) {
+        return {
+            status: 'unavailable', keys: {}, source: 'jwks', url, warnings, derivedFromLease, explicitlyConfigured,
+            reason: `JWKS fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/** Public halves used to verify PACKS — i.e. which code this fleet is allowed to execute. */
+async function loadPackTrustRoot(opts) {
+    return loadTrustRoot(PACK_TRUST_ROOT_SPEC, opts);
+}
+/**
+ * Public halves used to verify signed LEASE envelopes — i.e. which policy this instance obeys.
+ *
+ * Separate from the pack root because the control plane refuses to register one kid under two
+ * purposes, so there is no key that can serve both. See `LEASE_SIGNING_KEYS_ENV`.
+ *
+ * A caller with no lease root configured must fall back to the pack root and say so: that is what
+ * every deployment signing leases today is doing, and `requireSignedLease` is sticky with no
+ * plane-side undo, so a hard cutover here is unrecoverable from the plane. `explicitlyConfigured`
+ * is what makes that fallback decidable — a DERIVED lease root that comes back `unavailable`
+ * (a plane publishing no lease key) must not be read as "the operator has moved over".
+ */
+async function loadLeaseTrustRoot(opts) {
+    return loadTrustRoot(LEASE_TRUST_ROOT_SPEC, opts);
+}
+/**
+ * Which keyring verifies a signed lease — and whether that answer is the back-compat fallback.
+ *
+ * A lease root named OUTRIGHT (`AGENTHIPPO_LEASE_JWKS_URL` / `AGENTHIPPO_LEASE_SIGNING_KEYS`) is
+ * the whole answer: the pack keyring is not consulted, so a lease-signing key cannot be smuggled in
+ * through the root that decides which code runs, and an operator who has moved over gets the
+ * separation they asked for.
+ *
+ * With nothing named, the pack keyring stays in play. That is not laziness — it is every deployment
+ * that signs leases today, whose lease key necessarily sits in its PACK trust root because until
+ * now that was the only keyring serve consulted. `requireSignedLease` latches per instance and the
+ * control plane has no undo, so an instance that stopped recognising its own lease key would refuse
+ * turns and could not be talked out of it from the console. The derived lease keys are unioned in
+ * (and win a kid collision) so a rollover has both halves live at once.
+ *
+ * `packFallback` is returned rather than logged here: the caller owns the "warn exactly once, and
+ * only when a signed lease is actually being verified" part.
+ */
+function selectLeaseSigningKeys(leaseTrust, packTrust) {
+    if (leaseTrust.explicitlyConfigured) {
+        return { keys: leaseTrust.keys, packFallback: false };
+    }
+    return { keys: { ...packTrust.keys, ...leaseTrust.keys }, packFallback: true };
+}
+/**
+ * Accept both shapes: this codebase's `{pemsByKid}` and a standard JWKS `{keys:[…]}` — the latter
+ * is exactly what `authority/warrant.ts:jwks()` publishes, so the pack trust root and the warrant
+ * trust root can be the same document.
+ *
+ * ES256 only, matching the alg pinning in the verifier. An RSA or symmetric entry in a JWKS is not
+ * something to quietly skip past — it means the document is not what this verifier expects.
+ */
+function jwksToPems(doc) {
+    if (doc.pemsByKid && typeof doc.pemsByKid === 'object') {
+        return { ok: true, pems: doc.pemsByKid };
+    }
+    if (!Array.isArray(doc.keys)) {
+        return { ok: false, reason: 'JWKS document has neither `pemsByKid` nor a `keys` array' };
+    }
+    const pems = {};
+    for (const jwk of doc.keys) {
+        if (!jwk || typeof jwk !== 'object') {
+            continue;
+        }
+        if (jwk.kty !== 'EC' || jwk.crv !== 'P-256') {
+            continue;
+        }
+        if (jwk.alg !== undefined && jwk.alg !== 'ES256') {
+            continue;
+        }
+        if (typeof jwk.kid !== 'string' || !jwk.kid) {
+            continue;
+        }
+        try {
+            pems[jwk.kid] = crypto.createPublicKey({ key: jwk, format: 'jwk' })
+                .export({ type: 'spki', format: 'pem' }).toString();
+        }
+        catch { /* an unreadable entry is dropped; an empty result is reported as unavailable */ }
+    }
+    if (Object.keys(pems).length === 0) {
+        return { ok: false, reason: 'JWKS document published no usable ES256 (P-256) keys' };
+    }
+    return { ok: true, pems };
+}
+/**
+ * Back-compat shim. Returns just the keys, `{}` on any failure.
+ *
+ * Prefer `loadPackTrustRoot`: this signature cannot express "configured but unavailable", which is
+ * the distinction finding A4 is about.
+ *
+ * @deprecated
+ */
+async function loadPackSigningKeys(opts) {
+    return (await loadPackTrustRoot(opts)).keys;
+}
+// ---------------------------------------------------------------------------------------------
+// Re-verification on the turn path
+// ---------------------------------------------------------------------------------------------
+/** How long a verified result is reused without even probing the tree. */
+exports.PACK_PROBE_INTERVAL_MS = 1_000;
+/** How long a verified result is reused without a FULL digest, however clean the probe looks. */
+exports.PACK_FULL_REVERIFY_INTERVAL_MS = 30_000;
+/**
+ * Verify-per-turn with a cheap change probe.
+ *
+ * The signature used to be computed ONCE at boot and the boolean cached for the life of the
+ * process. In the DEFAULT deployment shape (no `--sandbox`) the engine runs IN THIS PROCESS with
+ * `fileAccess: full`, so an agent can edit its own pack directory — including, before the digest
+ * fix above, dropping a `PreToolUse` hook into `.claude/` — and every subsequent turn would still
+ * pass on the boot-time boolean. "Verified before run" has to mean before each run.
+ *
+ * Why this shape rather than a per-turn digest, or a plain interval:
+ *
+ *   - A full digest reads and hashes every byte of the pack. On the turn path that is a filesystem
+ *     walk plus O(bytes) of SHA-256 per turn, for a fact that is usually unchanged. Not measured,
+ *     therefore not put on a hot path — which is exactly what the original comment said and why it
+ *     cached, so replacing one unmeasured choice with another would be no better.
+ *   - `packTreeProbe` is `lstat` only: no reads, no hashing. It catches edits, replacements,
+ *     additions and removals, and it is what makes the common case (nothing changed) cheap.
+ *   - The probe alone is NOT sufficient: an attacker inside the process can restore mtime and size
+ *     after editing a file of identical length. So a full re-verify also runs unconditionally every
+ *     `PACK_FULL_REVERIFY_INTERVAL_MS`, which bounds that window rather than leaving it open for
+ *     the life of the process. Lowering that constant trades CPU for a shorter window.
+ *
+ * Residual, stated plainly: within one full-reverify interval, an in-process agent that edits its
+ * pack while preserving size and mtime is not detected. The structural fix for that is `--sandbox`
+ * (the engine cannot reach the pack directory at all); this bounds the exposure for the default
+ * shape rather than eliminating it.
+ */
+function createPackVerifier(opts = {}) {
+    const probeEvery = opts.probeIntervalMs ?? exports.PACK_PROBE_INTERVAL_MS;
+    const fullEvery = opts.fullReverifyIntervalMs ?? exports.PACK_FULL_REVERIFY_INTERVAL_MS;
+    let cached;
+    let cachedKey = '';
+    let cachedProbe = '';
+    let lastProbeAt = 0;
+    let lastFullAt = 0;
+    let fullCount = 0;
+    const identity = (i) => `${i.packDir}${i.pack}${i.packVersion}${Object.keys(i.keys).sort().join(',')}`;
+    const full = (input, nowMs) => {
+        fullCount += 1;
+        cachedKey = identity(input);
+        cachedProbe = packTreeProbe(input.packDir);
+        lastProbeAt = nowMs;
+        lastFullAt = nowMs;
+        const token = readPackSignature(input.packDir);
+        // "Unsigned" is reported ahead of "no trust root": the first step is the same either way
+        // (sign the pack), and an operator who is told about a missing keyring while their pack has
+        // no signature at all will configure the keyring and land right back here.
+        cached = token
+            ? verifyPack(token, input.keys, { packDir: input.packDir, pack: input.pack, packVersion: input.packVersion })
+            : { ok: false, kind: 'unsigned', reason: `${input.pack} is not signed (no ${exports.PACK_SIGNATURE_FILE} at the pack root)` };
+        return cached;
+    };
+    return {
+        fullVerifications: () => fullCount,
+        refresh(input, nowMs = Date.now()) { return full(input, nowMs); },
+        verify(input, nowMs = Date.now()) {
+            // Any change of pack, version or keyring invalidates outright — none of those are the
+            // kind of thing to reuse a cached verdict across.
+            if (!cached || cachedKey !== identity(input)) {
+                return full(input, nowMs);
+            }
+            if (nowMs - lastFullAt >= fullEvery) {
+                return full(input, nowMs);
+            }
+            if (nowMs - lastProbeAt < probeEvery) {
+                return cached;
+            }
+            lastProbeAt = nowMs;
+            const probe = packTreeProbe(input.packDir);
+            if (probe === cachedProbe) {
+                return cached;
+            }
+            return full(input, nowMs);
+        },
+    };
+}