@zanii/certify 0.0.0-stage → 0.5.0

package/dist/runtime-client.js

@@ -0,0 +1,185 @@
+// The attester must run inside approved measured code with a protected key; HTTP signatures alone do not establish that.
+import { randomBytes } from "node:crypto";
+import { publicKeyFromDid } from "@zanii/core";
+import { sha256Bytes } from "./fingerprint.js";
+import { RUNTIME_NITRO_MAX_BYTES, runtimeNitroBindingHash } from "./runtime-nitro.js";
+import { buildRuntimeChallengeRequest, buildRuntimeProof, runtimePolicyHash, verifyRuntimeApproval } from "./runtime.js";
+import { isDid, isIso, isObj } from "./shared.js";
+import { signerDid } from "./signer.js";
+const DEADLINE_MS = 10_000, MAX_RESPONSE_BYTES = 32 * 1024;
+const SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+/** One reporter has at most one underlying operation, including an uncancellable attester after timeout. */
+export function createRuntimeReporter(options) {
+    const authority = options.authority;
+    let url;
+    try {
+        url = new URL(authority);
+    }
+    catch {
+        throw new Error("runtime authority must be a canonical HTTPS origin");
+    }
+    if (typeof authority !== "string" || authority.length > 2048 || !/^[\x21-\x7e]+$/.test(authority) || url.protocol !== "https:"
+        || authority !== url.origin || url.username || url.password)
+        throw new Error("runtime authority must be a canonical HTTPS origin");
+    if (!Array.isArray(options.issuers) || !options.issuers.length || options.issuers.length > 100 || !options.issuers.every(isDid))
+        throw new Error("explicit runtime issuer DIDs are required");
+    const issuers = [...options.issuers], clock = options.clock ?? Date.now, call = options.fetch ?? fetch, attest = options.attest;
+    if (typeof attest !== "function" || !(options.signer?.publicKey instanceof Uint8Array) || options.signer.publicKey.length !== 32 || typeof options.signer.sign !== "function")
+        throw new Error("a workload signer and trusted attester are required");
+    const signer = { publicKey: new Uint8Array(options.signer.publicKey), sign: options.signer.sign.bind(options.signer) };
+    const workload = signerDid(signer), deployment = options.deployment;
+    const policyHash = runtimePolicyHash(options.policy);
+    const approve = (approval) => {
+        const check = verifyRuntimeApproval(approval, { signers: issuers, now: new Date(clock()).toISOString(), certificate: approval?.certificate,
+            release: approval?.release, policy: policyHash });
+        if (!check.ok)
+            throw new Error(`runtime approval refused: ${check.reasons.join("; ")}`);
+    };
+    approve(options.approval);
+    const approval = structuredClone(options.approval), policy = structuredClone(options.policy);
+    const context = { certificate: approval.certificate, release: approval.release, policy: policyHash, deployment, workload };
+    runtimeNitroBindingHash({ ...context, challenge: "0".repeat(32) });
+    const interval = options.intervalMs ?? Math.min(15_000, Math.floor(policy.evidence_max_age_s * 1000 / 3));
+    if (!Number.isSafeInteger(interval) || interval < 1_000 || interval >= policy.evidence_max_age_s * 1000)
+        throw new Error("runtime report interval must be at least 1000ms and below the evidence lifetime");
+    let running = null, controller = null, timer = null;
+    let started = false, stopped = false;
+    const abortCheck = (signal) => { if (signal.aborted)
+        throw signal.reason; };
+    async function post(path, body, signal) {
+        abortCheck(signal);
+        const response = await call(`${authority}/v1/runtime/deployments/${deployment}/${path}`, { method: "POST", redirect: "error",
+            credentials: "omit", headers: { "content-type": "application/json", accept: "application/json" }, body: JSON.stringify(body), signal });
+        abortCheck(signal);
+        if (response.redirected || (response.url && new URL(response.url).origin !== authority))
+            throw new Error("runtime authority redirected the request");
+        const length = response.headers.get("content-length");
+        if (length && (!/^\d+$/.test(length) || Number(length) > MAX_RESPONSE_BYTES)) {
+            void response.body?.cancel().catch(() => { });
+            throw new Error("runtime authority response exceeds 32KiB");
+        }
+        const reader = response.body?.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+            if (reader)
+                for (;;) {
+                    const part = await reader.read();
+                    abortCheck(signal);
+                    if (part.done)
+                        break;
+                    size += part.value.byteLength;
+                    if (size > MAX_RESPONSE_BYTES)
+                        throw new Error("runtime authority response exceeds 32KiB");
+                    chunks.push(part.value);
+                }
+        }
+        catch (error) {
+            void reader?.cancel().catch(() => { });
+            throw error;
+        }
+        finally {
+            reader?.releaseLock();
+        }
+        if (!response.ok)
+            throw new Error(`runtime authority refused ${path} (HTTP ${response.status})`);
+        let value;
+        try {
+            value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
+        }
+        catch {
+            throw new Error("runtime authority returned invalid JSON");
+        }
+        if (!isObj(value))
+            throw new Error("runtime authority returned an invalid response");
+        return value;
+    }
+    async function report(signal) {
+        approve(approval);
+        const request = await buildRuntimeChallengeRequest({ deployment, certificate: approval.certificate, release: approval.release,
+            nonce: randomBytes(32).toString("base64url"), issued_at: new Date(clock()).toISOString() }, signer);
+        const challenge = await post("challenge", request, signal);
+        if (Object.keys(challenge).length !== 7 || Object.entries(context).some(([key, value]) => challenge[key] !== value)
+            || typeof challenge.challenge !== "string" || !/^[A-Za-z0-9_-]{32,128}$/.test(challenge.challenge)
+            || !isIso(challenge.expires_at) || Date.parse(challenge.expires_at) <= clock()
+            || Date.parse(challenge.expires_at) > clock() + policy.challenge_ttl_s * 1000 + 5000)
+            throw new Error("runtime challenge does not match the approved deployment");
+        const binding = { ...context, challenge: challenge.challenge };
+        const document = await attest({ ...binding, nonce: binding.challenge, publicKey: Buffer.concat([SPKI_PREFIX, publicKeyFromDid(workload)]), userData: Buffer.from(runtimeNitroBindingHash(binding), "utf8") });
+        abortCheck(signal);
+        if (!(document instanceof Uint8Array) || document.byteLength < 1 || document.byteLength > RUNTIME_NITRO_MAX_BYTES)
+            throw new Error("runtime attestation must contain 1 to 16384 bytes");
+        const quote = new Uint8Array(document);
+        if (Date.parse(challenge.expires_at) <= clock())
+            throw new Error("runtime challenge expired during attestation");
+        const proof = await buildRuntimeProof({ deployment, certificate: approval.certificate, release: approval.release, challenge: binding.challenge,
+            public_key: workload, attestation_sha256: sha256Bytes(quote), observed_at: new Date(clock()).toISOString() }, signer);
+        const result = await post("evidence", { proof, attestation_document: Buffer.from(quote).toString("base64") }, signal);
+        if (result.accepted !== true || !isObj(result.deployment) || result.deployment.id !== deployment || result.deployment.state !== "fresh"
+            || !isIso(result.deployment.evidence_until) || Date.parse(result.deployment.evidence_until) <= clock())
+            throw new Error("runtime authority did not accept fresh deployment evidence");
+        return { accepted: true, deployment, evidence_until: result.deployment.evidence_until };
+    }
+    function schedule() {
+        if (started && !stopped && !running)
+            timer = setTimeout(() => { timer = null; void send().catch(() => { }); }, interval);
+    }
+    function send() {
+        if (stopped)
+            return Promise.reject(new Error("runtime reporter is stopped"));
+        if (running)
+            return Promise.reject(new Error("runtime reporter is busy"));
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        const control = new AbortController();
+        controller = control;
+        let finish, reject;
+        const result = new Promise((resolve, fail) => { finish = resolve; reject = fail; });
+        let settled = false;
+        const notify = (value) => {
+            try {
+                void Promise.resolve(options.onResult?.(value)).catch(() => { });
+            }
+            catch { /* Observers cannot break reporting or create retry queues. */ }
+        };
+        const fail = (error) => { if (!settled) {
+            settled = true;
+            reject(error);
+            notify({ accepted: false, error: error instanceof Error ? error : new Error("runtime report failed") });
+        } };
+        const abort = () => fail(control.signal.reason);
+        control.signal.addEventListener("abort", abort, { once: true });
+        const deadline = setTimeout(() => control.abort(new Error("runtime report exceeded its 10000ms deadline")), DEADLINE_MS);
+        const cleanup = () => {
+            clearTimeout(deadline);
+            control.signal.removeEventListener("abort", abort);
+            controller = null;
+            running = null;
+            schedule();
+        };
+        running = report(control.signal).then((value) => {
+            cleanup();
+            if (!settled) {
+                settled = true;
+                finish(value);
+                notify(value);
+            }
+        }, (error) => { cleanup(); fail(error); });
+        // Abort clears the deadline even if an uncancellable callback never settles.
+        control.signal.addEventListener("abort", () => clearTimeout(deadline), { once: true });
+        return result;
+    }
+    function start() { if (stopped)
+        throw new Error("runtime reporter is stopped"); if (!started) {
+        started = true;
+        if (!running)
+            void send().catch(() => { });
+    } }
+    async function stop() { stopped = true; started = false; if (timer) {
+        clearTimeout(timer);
+        timer = null;
+    } controller?.abort(new Error("runtime reporter stopped")); }
+    return { send, start, stop };
+}

package/dist/runtime-gateway.d.ts

@@ -0,0 +1,24 @@
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+export interface RuntimeGatewayOptions {
+    authority: string;
+    issuers: readonly string[];
+    targets: Readonly<Record<string, {
+        url: string;
+        method: string;
+        headers?: Readonly<Record<string, string>>;
+        knowledgeRoot?: string;
+    }>>;
+    maxConcurrent?: number;
+    maxRequestBytes?: number;
+    maxResponseBytes?: number;
+    timeoutMs?: number;
+    clock?: () => number;
+    fetch?: typeof fetch;
+}
+export declare function createRuntimeGateway(options: RuntimeGatewayOptions): {
+    handle: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    server: Server;
+    stats: () => {
+        active: number;
+    };
+};

package/dist/runtime-gateway.js

@@ -0,0 +1,167 @@
+// Reference resource enforcement point. Run separately from the agent; protected backends must reject bypass paths.
+import { canonicalBytes, jcsHash, publicKeyFromDid } from "@zanii/core";
+import { createServer } from "node:http";
+import { runtimeRequestHash, verifyRuntimeAction, verifyRuntimeLease } from "./runtime.js";
+import { isDid, isIso, isObj } from "./shared.js";
+import { signatureOk } from "./signer.js";
+import { sha256Bytes } from "./fingerprint.js";
+import { verifyRuntimeKnowledgeChunk } from "./runtime-knowledge.js";
+class GatewayError extends Error {
+    status;
+    constructor(status, message) { super(message); this.status = status; }
+}
+const httpsUrl = (raw) => {
+    const url = new URL(raw);
+    if (url.protocol !== "https:" || url.username || url.password || url.hash || url.href !== raw)
+        throw new Error("gateway URLs must be canonical HTTPS without credentials or fragments");
+    return url;
+};
+const cap = (value, fallback, max) => {
+    const out = value ?? fallback;
+    if (!Number.isSafeInteger(out) || out < 1 || out > max)
+        throw new Error("invalid gateway resource limit");
+    return out;
+};
+export function createRuntimeGateway(options) {
+    const authority = new URL(options.authority);
+    if (authority.protocol !== "https:" || ![authority.origin, `${authority.origin}/`].includes(options.authority))
+        throw new Error("authority must be a canonical HTTPS origin");
+    if (!options.issuers.length || options.issuers.length > 16 || options.issuers.some((did) => !isDid(did) || !publicKeyFromDid(did)))
+        throw new Error("explicit trusted issuer DIDs are required");
+    const issuers = [...options.issuers];
+    const targets = Object.entries(options.targets).map(([permission, target]) => [permission,
+        { url: target.url, method: target.method, headers: { ...target.headers }, knowledgeRoot: target.knowledgeRoot }]);
+    if (!targets.length || targets.length > 100)
+        throw new Error("configure 1 to 100 fixed gateway targets");
+    for (const [permission, target] of targets) {
+        if (!/^[A-Za-z0-9._:-]{1,128}$/.test(permission) || permission.trim() !== permission || !["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"].includes(target.method))
+            throw new Error("invalid gateway target permission or method");
+        httpsUrl(target.url);
+        if (target.knowledgeRoot !== undefined && (typeof target.knowledgeRoot !== "string" || !/^sha256:[0-9a-f]{64}$/.test(target.knowledgeRoot) || target.knowledgeRoot.trim() !== target.knowledgeRoot))
+            throw new Error("knowledge root must be a pinned SHA-256 digest");
+        for (const [key, value] of Object.entries(target.headers ?? {})) {
+            if (!/^[A-Za-z0-9-]{1,64}$/.test(key) || key.trim() !== key || typeof value !== "string" || value.length > 8192 || /[\r\n]/.test(value) || ["host", "content-type", "content-length", "transfer-encoding", "connection", "idempotency-key"].includes(key.toLowerCase()))
+                throw new Error("invalid protected backend header");
+        }
+    }
+    const targetMap = new Map(targets);
+    const maxConcurrent = cap(options.maxConcurrent, 16, 64);
+    const maxRequest = cap(options.maxRequestBytes, 65536, 1048576);
+    const maxResponse = cap(options.maxResponseBytes, 1048576, 8388608);
+    const timeout = cap(options.timeoutMs, 10000, 30000);
+    const clock = options.clock ?? Date.now;
+    const call = options.fetch ?? fetch;
+    let active = 0;
+    const reply = (res, status, body) => {
+        if (!res.headersSent && !res.destroyed)
+            res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store", "x-content-type-options": "nosniff" }).end(JSON.stringify(body));
+    };
+    async function bounded(body, limit) {
+        const chunks = [];
+        let size = 0;
+        if (body)
+            for await (const chunk of body) {
+                size += chunk.length;
+                if (size > limit)
+                    throw new GatewayError(413, "gateway payload limit exceeded");
+                chunks.push(Buffer.from(chunk));
+            }
+        return Buffer.concat(chunks);
+    }
+    async function handle(req, res) {
+        if (active >= maxConcurrent) {
+            reply(res, 503, { error: "gateway is busy" });
+            req.resume();
+            return;
+        }
+        active++;
+        try {
+            const path = /^\/invoke\/([A-Za-z0-9._:-]{1,128})$/.exec((req.url ?? "").split("?")[0]);
+            const permission = path?.[1];
+            const target = permission ? targetMap.get(permission) : undefined;
+            if (req.method !== "POST" || !target)
+                throw new GatewayError(404, "no such gateway operation");
+            const raw = await bounded(req, maxRequest);
+            let body;
+            try {
+                body = JSON.parse(raw.toString("utf8"));
+            }
+            catch {
+                throw new GatewayError(400, "expected a JSON operation");
+            }
+            if (!isObj(body) || Object.keys(body).length !== 3 || !isObj(body.lease) || !isObj(body.action) || !isObj(body.payload))
+                throw new GatewayError(400, "expected lease, action and payload");
+            const lease = body.lease;
+            const action = body.action;
+            if (target.knowledgeRoot !== undefined) {
+                const documents = body.payload.documents;
+                if (!Array.isArray(documents) || documents.length < 1 || documents.length > 32)
+                    throw new GatewayError(403, "approved knowledge proofs are required");
+                const ids = new Set();
+                for (const doc of documents) {
+                    if (!isObj(doc) || Object.keys(doc).length !== 3 || typeof doc.content !== "string" || !doc.content.isWellFormed()
+                        || !isObj(doc.metadata) || !isObj(doc.proof) || typeof doc.metadata.id !== "string" || ids.has(doc.metadata.id)
+                        || !verifyRuntimeKnowledgeChunk({ metadata: doc.metadata, content: Buffer.from(doc.content), proof: doc.proof }, { root: target.knowledgeRoot }).ok)
+                        throw new GatewayError(403, "knowledge content does not match the pinned approved snapshot");
+                    ids.add(doc.metadata.id);
+                }
+            }
+            const noBody = target.method === "GET" || target.method === "HEAD";
+            if (noBody && Object.keys(body.payload).length)
+                throw new GatewayError(400, "GET and HEAD operations require an empty payload");
+            const data = noBody ? Buffer.alloc(0) : canonicalBytes(body.payload);
+            const request = runtimeRequestHash({ method: target.method, url: target.url, body_sha256: sha256Bytes(data) });
+            const audience = new URL(target.url).origin;
+            const at = new Date(clock()).toISOString();
+            const checkedLease = verifyRuntimeLease(lease, { signers: issuers, now: at, certificate: action.certificate,
+                release: lease.release, policy: lease.policy, deployment: action.deployment, workload: action.signer,
+                audience, permission: permission, request, epoch: lease.epoch, maxSkewSeconds: 0 });
+            const checkedAction = verifyRuntimeAction(action, { signers: [lease.workload], now: at, certificate: lease.certificate,
+                lease: lease.id, deployment: lease.deployment, audience, permission: permission, request, maxSkewSeconds: 0 });
+            if (!checkedLease.ok || !checkedAction.ok || lease.max_uses !== 1)
+                throw new GatewayError(403, "operation does not match its single-use runtime authority");
+            // No protected effect starts before the live authority service atomically consumes the grant.
+            const authorization = await call(new URL("/v1/runtime/consume", authority), { method: "POST", redirect: "error",
+                headers: { "content-type": "application/json" }, body: JSON.stringify({ lease, action }), signal: AbortSignal.timeout(timeout) });
+            const authorizationBytes = await bounded(authorization.body, 16384);
+            if (!authorization.ok)
+                throw new GatewayError(403, "live runtime authority refused the operation");
+            let result;
+            try {
+                result = JSON.parse(authorizationBytes.toString("utf8"));
+            }
+            catch {
+                throw new GatewayError(502, "invalid authority response");
+            }
+            const decision = isObj(result) && isObj(result.decision) ? result.decision : null;
+            if (!decision)
+                throw new GatewayError(502, "missing signed authority decision");
+            const { sig, ...unsigned } = decision;
+            if (Object.keys(decision).length !== 10 || decision.v !== 1 || decision.type !== "certify.runtime-decision" || decision.allowed !== true
+                || typeof decision.signer !== "string" || !issuers.includes(decision.signer) || !signatureOk(unsigned, sig, decision.signer)
+                || decision.lease !== lease.id || decision.action !== jcsHash(action) || decision.request !== request
+                || !isIso(decision.issued_at) || !isIso(decision.expires_at) || Date.parse(decision.issued_at) > clock()
+                || clock() - Date.parse(decision.issued_at) > timeout || Date.parse(decision.expires_at) <= clock() || Date.parse(lease.expires_at) <= clock())
+                throw new GatewayError(403, "authority decision is invalid, stale or for a different operation");
+            const response = await call(target.url, { method: target.method, redirect: "error",
+                headers: { ...target.headers, "content-type": "application/json", "idempotency-key": `${lease.id}:${action.nonce}` },
+                body: noBody ? undefined : Buffer.from(data), signal: AbortSignal.timeout(timeout) });
+            const bytes = await bounded(response.body, maxResponse);
+            if (!res.destroyed)
+                res.writeHead(response.status, { "content-type": response.headers.get("content-type") ?? "application/octet-stream",
+                    "cache-control": "no-store", "x-content-type-options": "nosniff" }).end(bytes);
+        }
+        catch (error) {
+            reply(res, error instanceof GatewayError ? error.status : 502, { error: error instanceof GatewayError ? error.message : "runtime gateway could not complete the operation" });
+        }
+        finally {
+            active--;
+        }
+    }
+    const server = createServer((req, res) => void handle(req, res));
+    server.maxConnections = maxConcurrent * 4;
+    server.maxRequestsPerSocket = 1000;
+    server.requestTimeout = 30000;
+    server.headersTimeout = 10000;
+    return { handle, server, stats: () => ({ active }) };
+}

package/dist/runtime-knowledge.d.ts

@@ -0,0 +1,28 @@
+import type { RuntimeCheck } from "./runtime.ts";
+export interface RuntimeKnowledgeMetadata {
+    id: string;
+    source: string;
+    content_sha256: string;
+    acl_sha256: string;
+}
+export interface RuntimeKnowledgeSnapshot {
+    root: string;
+    size: number;
+    metadata: readonly RuntimeKnowledgeMetadata[];
+}
+export interface RuntimeKnowledgeProof {
+    index: number;
+    size: number;
+    path: string[];
+}
+export interface RuntimeKnowledgeOptions {
+    root: string;
+    maxContentBytes?: number;
+}
+/** Only metadata enters a snapshot; raw documents stay outside the manifest and tree builder. */
+export declare function buildRuntimeKnowledgeSnapshot(metadata: readonly RuntimeKnowledgeMetadata[]): RuntimeKnowledgeSnapshot;
+/** For multiple chunks prefer runtimeKnowledgeProofs, which builds the tree once per batch. */
+export declare function runtimeKnowledgeProof(snapshot: RuntimeKnowledgeSnapshot, index: number): RuntimeKnowledgeProof;
+/** O(n) preparation and O(log n) per proof, without any global snapshot cache. */
+export declare function runtimeKnowledgeProofs(snapshot: RuntimeKnowledgeSnapshot, indices: readonly number[]): RuntimeKnowledgeProof[];
+export declare function verifyRuntimeKnowledgeChunk(chunk: unknown, options: RuntimeKnowledgeOptions): RuntimeCheck;

package/dist/runtime-knowledge.js

@@ -0,0 +1,75 @@
+// Inclusion proves approved snapshot membership and bytes, not truth or permission to read them.
+import { canonicalBytes, leafHash, merkleRoot, verifyInclusion } from "@zanii/core";
+import { sha256Bytes } from "./fingerprint.js";
+import { isInt, isObj, isSha } from "./shared.js";
+const MAX_ITEMS = 50_000, MAX_CONTENT = 1_048_576;
+const keys = (v, names) => isObj(v) && Object.keys(v).length === names.split(" ").length && names.split(" ").every((key) => Object.hasOwn(v, key));
+const digest = (v) => isSha(v) && v.length === 71;
+const metadataShape = (v) => keys(v, "id source content_sha256 acl_sha256")
+    && typeof v.id === "string" && v.id.length <= 128 && /^[A-Za-z0-9._:-]+$/.test(v.id) && v.id.trim() === v.id
+    && typeof v.source === "string" && v.source.length <= 2048 && /^[A-Za-z][A-Za-z0-9+.-]*:[\x21-\x7e]+$/.test(v.source) && v.source.trim() === v.source
+    && digest(v.content_sha256) && digest(v.acl_sha256);
+const leaf = (metadata) => leafHash(canonicalBytes({ v: 1, type: "certify.runtime-knowledge-chunk", ...metadata }));
+function tree(metadata) {
+    const levels = [metadata.map(leaf)];
+    while (levels.at(-1).length > 1) {
+        const level = levels.at(-1);
+        const next = [];
+        for (let i = 0; i < level.length; i += 2)
+            next.push(i + 1 < level.length ? merkleRoot([level[i], level[i + 1]]) : level[i]);
+        levels.push(next);
+    }
+    return { levels, root: `sha256:${Buffer.from(levels.at(-1)[0] ?? merkleRoot([])).toString("hex")}` };
+}
+/** Only metadata enters a snapshot; raw documents stay outside the manifest and tree builder. */
+export function buildRuntimeKnowledgeSnapshot(metadata) {
+    if (!Array.isArray(metadata) || metadata.length > MAX_ITEMS || !Array.from(metadata).every(metadataShape))
+        throw new Error("invalid runtime knowledge metadata");
+    const ordered = metadata.map((m) => Object.freeze({ ...m })).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    if (ordered.some((m, i) => i > 0 && ordered[i - 1].id === m.id))
+        throw new Error("duplicate runtime knowledge chunk id");
+    return Object.freeze({ root: tree(ordered).root, size: ordered.length, metadata: Object.freeze(ordered) });
+}
+/** For multiple chunks prefer runtimeKnowledgeProofs, which builds the tree once per batch. */
+export function runtimeKnowledgeProof(snapshot, index) {
+    return runtimeKnowledgeProofs(snapshot, [index])[0];
+}
+/** O(n) preparation and O(log n) per proof, without any global snapshot cache. */
+export function runtimeKnowledgeProofs(snapshot, indices) {
+    if (!keys(snapshot, "root size metadata") || !digest(snapshot.root) || !isInt(snapshot.size, 0, MAX_ITEMS)
+        || !Array.isArray(snapshot.metadata) || snapshot.metadata.length !== snapshot.size
+        || !Array.isArray(indices) || indices.length < 1 || indices.length > 100 || !Array.from(indices).every((i) => isInt(i, 0, snapshot.size - 1))
+        || !Array.from(snapshot.metadata).every((m, i) => metadataShape(m) && (i === 0 || snapshot.metadata[i - 1].id < m.id)))
+        throw new Error("invalid runtime knowledge snapshot or index");
+    const built = tree(snapshot.metadata);
+    if (built.root !== snapshot.root)
+        throw new Error("runtime knowledge snapshot root does not match metadata");
+    return indices.map((index) => {
+        const path = [];
+        let at = index;
+        for (const level of built.levels.slice(0, -1)) {
+            const sibling = at % 2 ? at - 1 : at + 1;
+            if (sibling < level.length)
+                path.push(Buffer.from(level[sibling]).toString("hex"));
+            at = Math.floor(at / 2);
+        }
+        return { index, size: snapshot.size, path };
+    });
+}
+export function verifyRuntimeKnowledgeChunk(chunk, options) {
+    const denied = (reason) => ({ ok: false, reasons: [reason] });
+    if (!isObj(options) || !Object.hasOwn(options, "root") || Object.keys(options).some((k) => k !== "root" && k !== "maxContentBytes") || !digest(options.root)
+        || !isInt(options.maxContentBytes ?? MAX_CONTENT, 1, MAX_CONTENT))
+        return denied("an independently pinned knowledge root and bounded content limit are required");
+    if (!keys(chunk, "metadata content proof") || !metadataShape(chunk.metadata) || !(chunk.content instanceof Uint8Array)
+        || chunk.content.byteLength > (options.maxContentBytes ?? MAX_CONTENT))
+        return denied("invalid or oversized runtime knowledge chunk");
+    const proof = chunk.proof;
+    if (!keys(proof, "index size path") || !isInt(proof.size, 1, MAX_ITEMS) || !isInt(proof.index, 0, proof.size - 1)
+        || !Array.isArray(proof.path) || proof.path.length > 32 || !Array.from(proof.path).every((p) => typeof p === "string" && p.length === 64 && /^[0-9a-f]{64}$/.test(p)))
+        return denied("invalid runtime knowledge inclusion proof");
+    if (sha256Bytes(chunk.content) !== chunk.metadata.content_sha256)
+        return denied("runtime knowledge content hash does not match");
+    return verifyInclusion(leaf(chunk.metadata), proof.index, proof.size, proof.path.map((p) => Buffer.from(p, "hex")), Buffer.from(options.root.slice(7), "hex"))
+        ? { ok: true, reasons: [] } : denied("runtime knowledge chunk is not in the pinned snapshot");
+}

package/dist/runtime-nitro.d.ts

@@ -0,0 +1,30 @@
+import { type NitroOptions } from "./nitro.ts";
+export interface RuntimeNitroBinding {
+    certificate: string;
+    release: string;
+    policy: string;
+    deployment: string;
+    workload: string;
+    challenge: string;
+}
+export interface RuntimeNitroOptions extends RuntimeNitroBinding {
+    /** This certified release's accepted PCRs. PCR0 is required and debug measurements are refused. */
+    pcrs: Readonly<Record<number, string>>;
+    maxAgeSeconds: number;
+    now?: string;
+    /** Trusted application configuration only; the pinned commercial AWS root is the default. */
+    root?: NitroOptions["root"];
+}
+export interface RuntimeNitroCheck {
+    ok: boolean;
+    reasons: string[];
+    /** Populated only after every quote and binding check succeeds. */
+    measurement: string | null;
+    observed_at?: string;
+}
+export declare const RUNTIME_NITRO_MAX_BYTES: number;
+export declare const RUNTIME_NITRO_MAX_SKEW_SECONDS = 5;
+/** The quote's USER DATA is this hash as UTF-8 bytes, not the unhashed context or raw hash bytes. */
+export declare function runtimeNitroBindingHash(context: RuntimeNitroBinding): string;
+/** Verify the raw signed quote against one release's policy and the verifier's expected challenge and workload. */
+export declare function verifyRuntimeNitroDocument(bytes: Uint8Array, opts: RuntimeNitroOptions): RuntimeNitroCheck;

package/dist/runtime-nitro.js

@@ -0,0 +1,57 @@
+// Runtime appraisal over the raw Nitro quote. Challenge consumption and channel authentication belong to the relying service.
+import { jcsHash, publicKeyFromDid } from "@zanii/core";
+import { nitroMeasurement, verifyNitroDocument } from "./nitro.js";
+import { isDid, isIso, isObj, isSha } from "./shared.js";
+export const RUNTIME_NITRO_MAX_BYTES = 16 * 1024;
+export const RUNTIME_NITRO_MAX_SKEW_SECONDS = 5;
+const ED25519_SPKI = Buffer.from("302a300506032b6570032100", "hex");
+/** The quote's USER DATA is this hash as UTF-8 bytes, not the unhashed context or raw hash bytes. */
+export function runtimeNitroBindingHash(context) {
+    if (!isObj(context) || !isSha(context.certificate) || !isSha(context.release) || !isSha(context.policy)
+        || typeof context.deployment !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(context.deployment)
+        || typeof context.challenge !== "string" || !/^[A-Za-z0-9_-]{32,128}$/.test(context.challenge)
+        || !isDid(context.workload) || !publicKeyFromDid(context.workload))
+        throw new Error("invalid runtime Nitro binding context");
+    return jcsHash({ v: 1, type: "certify.runtime-binding", certificate: context.certificate, release: context.release,
+        policy: context.policy, deployment: context.deployment, workload: context.workload, challenge: context.challenge });
+}
+/** Verify the raw signed quote against one release's policy and the verifier's expected challenge and workload. */
+export function verifyRuntimeNitroDocument(bytes, opts) {
+    const fail = (...reasons) => ({ ok: false, reasons, measurement: null });
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength < 1 || bytes.byteLength > RUNTIME_NITRO_MAX_BYTES)
+        return fail("runtime Nitro quote must contain 1 to 16384 bytes");
+    try {
+        const binding = runtimeNitroBindingHash(opts);
+        if (!Number.isFinite(opts.maxAgeSeconds) || opts.maxAgeSeconds < 1 || opts.maxAgeSeconds > 300)
+            return fail("runtime Nitro maxAgeSeconds must be finite and between 1 and 300");
+        if (!isObj(opts.pcrs))
+            return fail("runtime Nitro PCR policy must contain PCR0 and at most 8 PCRs");
+        const pcrs = Object.entries(opts.pcrs);
+        if (pcrs.length < 1 || pcrs.length > 8 || !pcrs.some(([index]) => index === "0")
+            || pcrs.some(([index, value]) => !/^(?:[0-9]|[12][0-9]|3[01])$/.test(index) || typeof value !== "string" || !/^[0-9a-fA-F]{96}$/.test(value)))
+            return fail("runtime Nitro PCR policy must map at most 8 indexes from 0 to 31 to SHA-384 hex values, including PCR0");
+        if (/^0{96}$/.test(opts.pcrs[0]))
+            return fail("runtime Nitro PCR0 must not be a debug measurement");
+        const now = opts.now !== undefined ? opts.now : new Date().toISOString();
+        if (!isIso(now))
+            return fail("runtime Nitro now must be an ISO UTC timestamp");
+        const checked = verifyNitroDocument(bytes, { root: opts.root, now, nonce: opts.challenge, pcrs: Object.fromEntries(pcrs), maxAgeSeconds: opts.maxAgeSeconds });
+        if (!checked.ok || !checked.document)
+            return fail(...checked.reasons);
+        const doc = checked.document;
+        const reasons = [];
+        if (doc.timestamp > Date.parse(now) + RUNTIME_NITRO_MAX_SKEW_SECONDS * 1000)
+            reasons.push("runtime Nitro document timestamp exceeds the 5-second clock skew");
+        const expectedKey = Buffer.concat([ED25519_SPKI, publicKeyFromDid(opts.workload)]);
+        if (doc.publicKey === null || !expectedKey.equals(doc.publicKey))
+            reasons.push("runtime Nitro public_key does not match the workload Ed25519 SPKI key");
+        if (doc.userData === null || !Buffer.from(binding, "utf8").equals(doc.userData))
+            reasons.push("runtime Nitro user_data does not match the expected binding hash");
+        if (reasons.length)
+            return fail(...reasons);
+        return { ok: true, reasons: [], measurement: nitroMeasurement(doc), observed_at: new Date(doc.timestamp).toISOString() };
+    }
+    catch {
+        return fail("runtime Nitro quote or trusted verification context is invalid");
+    }
+}