@zanii/certify 0.0.0-stage → 0.5.0

package/dist/runtime.d.ts

@@ -0,0 +1,226 @@
+import { type Signer } from "./signer.ts";
+export interface RuntimeCheck {
+    ok: boolean;
+    reasons: string[];
+}
+interface Signed {
+    v: 1;
+    signer: string;
+    sig: string;
+}
+export interface RuntimeRelease extends Signed {
+    type: "certify.runtime-release";
+    agent: string;
+    fingerprint: string;
+    image: string;
+    config: string;
+    tools: {
+        name: string;
+        digest: string;
+    }[];
+    knowledge: string | null;
+    retrieval: string | null;
+    model: {
+        id: string;
+        revision: string | null;
+        artifact: string | null;
+    };
+    permissions: string[];
+    egress: string[];
+    provenance: {
+        builder: string;
+        artifact: string;
+        workflow: string;
+    };
+    issued_at: string;
+}
+export interface RuntimePolicy {
+    v: 1;
+    type: "certify.runtime-policy";
+    platform: "nitro";
+    pcrs: Record<string, string>;
+    evidence_max_age_s: number;
+    challenge_ttl_s: number;
+    lease_ttl_s: number;
+    permissions: string[];
+    audiences: string[];
+    authorizers: string[];
+    max_uses: number;
+    require_model_artifact: boolean;
+}
+export interface RuntimeApproval extends Signed {
+    type: "certify.runtime-approval";
+    certificate: string;
+    release: string;
+    policy: string;
+    /** Human-reviewed artifact digest; not a cryptographic proof of a test/build relationship. */
+    qualification: string;
+    approved_by: string;
+    issued_at: string;
+    valid_until: string;
+    epoch: number;
+}
+export interface RuntimeProof extends Signed {
+    type: "certify.runtime-proof";
+    deployment: string;
+    certificate: string;
+    release: string;
+    challenge: string;
+    public_key: string;
+    attestation_sha256: string;
+    observed_at: string;
+}
+export interface RuntimeChallengeRequest extends Signed {
+    type: "certify.runtime-challenge-request";
+    deployment: string;
+    certificate: string;
+    release: string;
+    nonce: string;
+    issued_at: string;
+}
+export interface RuntimeLease extends Signed {
+    type: "certify.runtime-lease";
+    id: string;
+    certificate: string;
+    release: string;
+    policy: string;
+    deployment: string;
+    workload: string;
+    audience: string;
+    permission: string;
+    request: string;
+    epoch: number;
+    issued_at: string;
+    expires_at: string;
+    max_uses: number;
+}
+export interface RuntimeAction extends Signed {
+    type: "certify.runtime-action";
+    lease: string;
+    certificate: string;
+    deployment: string;
+    audience: string;
+    permission: string;
+    request: string;
+    nonce: string;
+    issued_at: string;
+}
+export interface RuntimeLeaseRequest extends Signed {
+    type: "certify.runtime-lease-request";
+    deployment: string;
+    certificate: string;
+    audience: string;
+    permission: string;
+    request: string;
+    nonce: string;
+    issued_at: string;
+}
+export interface RuntimeMandate extends Signed {
+    type: "certify.runtime-mandate";
+    deployment: string;
+    certificate: string;
+    workload: string;
+    audience: string;
+    permission: string;
+    request: string;
+    nonce: string;
+    issued_at: string;
+    expires_at: string;
+}
+export interface RuntimeTrustOptions {
+    signers: readonly string[];
+    now: string;
+    maxSkewSeconds?: number;
+}
+export interface RuntimeReleaseOptions extends RuntimeTrustOptions {
+    agent?: string;
+    fingerprint?: string;
+    hash?: string;
+}
+export interface RuntimeApprovalOptions extends RuntimeTrustOptions {
+    certificate: string;
+    release: string;
+    policy: string;
+    qualification?: string;
+    epoch?: number;
+}
+export interface RuntimeProofOptions extends RuntimeTrustOptions {
+    certificate: string;
+    release: string;
+    deployment: string;
+    challenge: string;
+    attestation_sha256: string;
+    maxAgeSeconds: number;
+}
+export interface RuntimeChallengeOptions extends RuntimeTrustOptions {
+    certificate: string;
+    release: string;
+    deployment: string;
+    maxAgeSeconds?: number;
+}
+export interface RuntimeLeaseOptions extends RuntimeTrustOptions {
+    certificate: string;
+    release: string;
+    policy: string;
+    deployment: string;
+    workload: string;
+    audience: string;
+    permission: string;
+    request: string;
+    epoch: number;
+    maxTtlSeconds?: number;
+}
+export interface RuntimeActionOptions extends RuntimeTrustOptions {
+    lease: string;
+    certificate: string;
+    deployment: string;
+    audience: string;
+    permission: string;
+    request: string;
+    maxAgeSeconds?: number;
+}
+export interface RuntimeLeaseRequestOptions extends RuntimeTrustOptions {
+    certificate: string;
+    deployment: string;
+    audience: string;
+    permission: string;
+    request: string;
+    maxAgeSeconds?: number;
+}
+export interface RuntimeMandateOptions extends RuntimeTrustOptions {
+    certificate: string;
+    deployment: string;
+    workload: string;
+    audience: string;
+    permission: string;
+    request: string;
+    maxTtlSeconds?: number;
+}
+type Input<T> = Omit<T, "v" | "type" | "signer" | "sig">;
+export declare const buildRuntimeRelease: (fields: Input<RuntimeRelease>, signer: Signer) => Promise<RuntimeRelease>;
+export declare const buildRuntimeApproval: (fields: Input<RuntimeApproval>, signer: Signer) => Promise<RuntimeApproval>;
+export declare const buildRuntimeProof: (fields: Input<RuntimeProof>, signer: Signer) => Promise<RuntimeProof>;
+export declare const buildRuntimeChallengeRequest: (fields: Input<RuntimeChallengeRequest>, signer: Signer) => Promise<RuntimeChallengeRequest>;
+export declare const buildRuntimeLease: (fields: Input<RuntimeLease>, signer: Signer) => Promise<RuntimeLease>;
+export declare const buildRuntimeAction: (fields: Input<RuntimeAction>, signer: Signer) => Promise<RuntimeAction>;
+export declare const buildRuntimeLeaseRequest: (fields: Input<RuntimeLeaseRequest>, signer: Signer) => Promise<RuntimeLeaseRequest>;
+export declare const buildRuntimeMandate: (fields: Input<RuntimeMandate>, signer: Signer) => Promise<RuntimeMandate>;
+export declare function buildRuntimePolicy(fields: Omit<RuntimePolicy, "v" | "type">): RuntimePolicy;
+export declare function verifyRuntimeRelease(doc: unknown, opts?: RuntimeReleaseOptions): RuntimeCheck;
+export declare const verifyRuntimePolicy: (doc: unknown) => RuntimeCheck;
+export declare function verifyRuntimeApproval(doc: unknown, opts?: RuntimeApprovalOptions): RuntimeCheck;
+export declare function verifyRuntimeProof(doc: unknown, opts?: RuntimeProofOptions): RuntimeCheck;
+export declare function verifyRuntimeChallengeRequest(doc: unknown, opts?: RuntimeChallengeOptions): RuntimeCheck;
+export declare function verifyRuntimeLease(doc: unknown, opts?: RuntimeLeaseOptions): RuntimeCheck;
+export declare function verifyRuntimeAction(doc: unknown, opts?: RuntimeActionOptions): RuntimeCheck;
+export declare function verifyRuntimeLeaseRequest(doc: unknown, opts?: RuntimeLeaseRequestOptions): RuntimeCheck;
+export declare function verifyRuntimeMandate(doc: unknown, opts?: RuntimeMandateOptions): RuntimeCheck;
+/** Hashes identify validated wire bytes; they do not establish signer trust or hardware state. */
+export declare function runtimeReleaseHash(doc: RuntimeRelease): string;
+export declare function runtimePolicyHash(doc: RuntimePolicy): string;
+export declare function runtimeRequestHash(request: {
+    method: string;
+    url: string;
+    body_sha256: string;
+}): string;
+export {};

package/dist/runtime.js

@@ -0,0 +1,254 @@
+// Runtime documents bind signed claims and request scope; hardware and live authorization are separate checks.
+import { jcsHash, publicKeyFromDid } from "@zanii/core";
+import { isDid as sharedDid, isInt, isIso as sharedIso, isObj, isSha as sharedSha, ms } from "./shared.js";
+import { signatureOk, signerDid, signWith } from "./signer.js";
+const keys = (v, names) => isObj(v) && Object.keys(v).length === names.split(" ").length && names.split(" ").every((key) => Object.hasOwn(v, key));
+const isDid = (v) => sharedDid(v) && v.trim() === v && publicKeyFromDid(v) !== null;
+const isSha = (v) => sharedSha(v) && v.trim() === v;
+const isIso = (v) => sharedIso(v) && v.trim() === v;
+const text = (v, max = 200) => typeof v === "string" && v.length > 0 && v.length <= max && v.isWellFormed() && !/[\u0000-\u001f\u007f]/.test(v);
+const identifier = (v) => text(v, 128) && /^[A-Za-z0-9._:-]{1,128}$/.test(v);
+const nonce = (v) => text(v, 128) && /^[A-Za-z0-9_-]{32,128}$/.test(v);
+const digestOrNull = (v) => v === null || isSha(v);
+const ordered = (v, max, valid) => Array.isArray(v) && v.length <= max && v.every((s, i) => valid(s) && (i === 0 || v[i - 1] < s));
+/** Canonical ASCII HTTPS origins only; neither credentials nor a default port are hidden by normalization. */
+const origin = (v) => {
+    if (typeof v !== "string" || v.length > 2048 || !/^[\x21-\x7e]+$/.test(v))
+        return false;
+    try {
+        const url = new URL(v);
+        return url.protocol === "https:" && v === url.origin && !url.username && !url.password
+            && (url.hostname.startsWith("[") || (url.hostname.length <= 253 && /^[a-z0-9_.-]+$/.test(url.hostname)));
+    }
+    catch {
+        return false;
+    }
+};
+const common = (d, purpose) => d.v === 1 && d.type === `certify.runtime-${purpose}` && isDid(d.signer) && typeof d.sig === "string" && d.sig.length === 136 && /^ed25519:[0-9a-f]{128}$/.test(d.sig);
+const tools = (v) => Array.isArray(v) && v.length <= 100 && v.every((tool, i) => keys(tool, "name digest") && identifier(tool.name) && isSha(tool.digest) && (i === 0 || v[i - 1].name < tool.name));
+function releaseShape(v) {
+    return keys(v, "v type agent fingerprint image config tools knowledge retrieval model permissions egress provenance issued_at signer sig") && common(v, "release")
+        && isDid(v.agent) && isSha(v.fingerprint) && isSha(v.image) && isSha(v.config) && digestOrNull(v.knowledge) && digestOrNull(v.retrieval)
+        && tools(v.tools)
+        && keys(v.model, "id revision artifact") && text(v.model.id) && (v.model.revision === null || text(v.model.revision)) && digestOrNull(v.model.artifact)
+        && ordered(v.permissions, 100, (s) => text(s, 128)) && ordered(v.egress, 32, origin)
+        && keys(v.provenance, "builder artifact workflow") && isDid(v.provenance.builder) && v.provenance.builder === v.signer && isSha(v.provenance.artifact) && v.provenance.artifact === v.image && text(v.provenance.workflow)
+        && isIso(v.issued_at);
+}
+function policyShape(v) {
+    return keys(v, "v type platform pcrs evidence_max_age_s challenge_ttl_s lease_ttl_s permissions audiences authorizers max_uses require_model_artifact") && v.v === 1 && v.type === "certify.runtime-policy" && v.platform === "nitro"
+        && isObj(v.pcrs) && Object.keys(v.pcrs).length >= 1 && Object.keys(v.pcrs).length <= 8 && typeof v.pcrs["0"] === "string" && /[1-9a-f]/.test(v.pcrs["0"])
+        && Object.entries(v.pcrs).every(([key, value]) => key.trim() === key && /^(?:[0-9]|[12][0-9]|3[01])$/.test(key) && typeof value === "string" && value.length === 96 && /^[0-9a-f]{96}$/.test(value))
+        && isInt(v.evidence_max_age_s, 15, 300) && isInt(v.challenge_ttl_s, 5, 120) && isInt(v.lease_ttl_s, 1, 60)
+        && ordered(v.permissions, 100, (s) => text(s, 128)) && ordered(v.audiences, 32, origin) && ordered(v.authorizers, 8, isDid) && v.authorizers.length > 0 && isInt(v.max_uses, 1, 1000) && typeof v.require_model_artifact === "boolean";
+}
+function approvalShape(v) {
+    return keys(v, "v type certificate release policy qualification approved_by issued_at valid_until epoch signer sig") && common(v, "approval")
+        && [v.certificate, v.release, v.policy, v.qualification].every(isSha) && isDid(v.approved_by) && isIso(v.issued_at) && isIso(v.valid_until) && ms(v.valid_until) > ms(v.issued_at) && isInt(v.epoch, 1, Number.MAX_SAFE_INTEGER);
+}
+function proofShape(v) {
+    return keys(v, "v type deployment certificate release challenge public_key attestation_sha256 observed_at signer sig") && common(v, "proof")
+        && identifier(v.deployment) && isSha(v.certificate) && isSha(v.release) && nonce(v.challenge) && isDid(v.public_key) && v.public_key === v.signer && isSha(v.attestation_sha256) && isIso(v.observed_at);
+}
+function challengeShape(v) {
+    return keys(v, "v type deployment certificate release nonce issued_at signer sig") && common(v, "challenge-request")
+        && identifier(v.deployment) && isSha(v.certificate) && isSha(v.release) && nonce(v.nonce) && isIso(v.issued_at);
+}
+function leaseShape(v) {
+    return keys(v, "v type id certificate release policy deployment workload audience permission request epoch issued_at expires_at max_uses signer sig") && common(v, "lease")
+        && identifier(v.id) && [v.certificate, v.release, v.policy, v.request].every(isSha) && identifier(v.deployment) && isDid(v.workload) && origin(v.audience) && text(v.permission, 128)
+        && isInt(v.epoch, 1, Number.MAX_SAFE_INTEGER) && isInt(v.max_uses, 1, 1000) && isIso(v.issued_at) && isIso(v.expires_at) && ms(v.expires_at) > ms(v.issued_at) && ms(v.expires_at) - ms(v.issued_at) <= 60_000;
+}
+function actionShape(v) {
+    return keys(v, "v type lease certificate deployment audience permission request nonce issued_at signer sig") && common(v, "action")
+        && identifier(v.lease) && isSha(v.certificate) && identifier(v.deployment) && origin(v.audience) && text(v.permission, 128) && isSha(v.request) && nonce(v.nonce) && isIso(v.issued_at);
+}
+function leaseRequestShape(v) {
+    return keys(v, "v type deployment certificate audience permission request nonce issued_at signer sig") && common(v, "lease-request")
+        && identifier(v.deployment) && isSha(v.certificate) && origin(v.audience) && text(v.permission, 128) && isSha(v.request) && nonce(v.nonce) && isIso(v.issued_at);
+}
+function mandateShape(v) {
+    return keys(v, "v type deployment certificate workload audience permission request nonce issued_at expires_at signer sig") && common(v, "mandate")
+        && identifier(v.deployment) && isSha(v.certificate) && isDid(v.workload) && v.workload !== v.signer && origin(v.audience) && text(v.permission, 128) && isSha(v.request) && nonce(v.nonce)
+        && isIso(v.issued_at) && isIso(v.expires_at) && ms(v.expires_at) > ms(v.issued_at) && ms(v.expires_at) - ms(v.issued_at) <= 60_000;
+}
+const signatures = { signer: "", sig: `ed25519:${"0".repeat(128)}` };
+const copy = (value) => JSON.parse(JSON.stringify(value));
+async function build(purpose, fields, signer, shape) {
+    if (!isObj(fields) || ["v", "type", "signer", "sig"].some((key) => Object.hasOwn(fields, key)))
+        throw new Error(`not a runtime ${purpose} input`);
+    const doc = { ...fields, v: 1, type: `certify.runtime-${purpose}`, ...signatures, signer: signerDid(signer) };
+    // Bound arrays before sorting or serializing attacker-supplied manifests.
+    for (const [key, limit] of [["tools", 100], ["permissions", 100], ["egress", 32]]) {
+        const value = doc[key];
+        if (Array.isArray(value) && value.length > limit)
+            throw new Error(`runtime ${key} exceeds ${limit} items`);
+    }
+    if (Array.isArray(doc.tools))
+        doc.tools = [...doc.tools].sort((a, b) => String(a?.name) < String(b?.name) ? -1 : String(a?.name) > String(b?.name) ? 1 : 0);
+    for (const key of ["permissions", "egress"])
+        if (key in doc && Array.isArray(doc[key]))
+            doc[key] = [...doc[key]].sort();
+    if (!shape(doc))
+        throw new Error(`not a runtime ${purpose} (v1)`);
+    const { sig: _, signer: __, ...unsigned } = copy(doc);
+    return await signWith(unsigned, signer);
+}
+export const buildRuntimeRelease = (fields, signer) => build("release", fields, signer, releaseShape);
+export const buildRuntimeApproval = (fields, signer) => build("approval", fields, signer, approvalShape);
+export const buildRuntimeProof = (fields, signer) => build("proof", fields, signer, proofShape);
+export const buildRuntimeChallengeRequest = (fields, signer) => build("challenge-request", fields, signer, challengeShape);
+export const buildRuntimeLease = (fields, signer) => build("lease", fields, signer, leaseShape);
+export const buildRuntimeAction = (fields, signer) => build("action", fields, signer, actionShape);
+export const buildRuntimeLeaseRequest = (fields, signer) => build("lease-request", fields, signer, leaseRequestShape);
+export const buildRuntimeMandate = (fields, signer) => build("mandate", fields, signer, mandateShape);
+export function buildRuntimePolicy(fields) {
+    if (!isObj(fields) || ["v", "type"].some((key) => Object.hasOwn(fields, key)))
+        throw new Error("not a runtime policy input");
+    const doc = { ...fields, v: 1, type: "certify.runtime-policy" };
+    for (const [key, limit] of [["permissions", 100], ["audiences", 32], ["authorizers", 8]]) {
+        if (Array.isArray(doc[key]) && doc[key].length <= limit)
+            doc[key] = [...doc[key]].sort();
+    }
+    if (!policyShape(doc))
+        throw new Error("not a runtime policy (v1)");
+    return copy(doc);
+}
+function trust(doc, opts) {
+    const reasons = [];
+    if (!Array.isArray(opts.signers) || opts.signers.length < 1 || opts.signers.length > 100 || !opts.signers.every(isDid))
+        reasons.push("no trusted runtime signers supplied");
+    else if (!opts.signers.includes(doc.signer))
+        reasons.push("runtime signer is not trusted");
+    if (!isIso(opts.now))
+        reasons.push("now must be an ISO UTC timestamp");
+    if (!isInt(opts.maxSkewSeconds ?? 5, 0, 5))
+        reasons.push("maxSkewSeconds must be from 0 to 5");
+    const { sig, ...unsigned } = doc;
+    if (!signatureOk(unsigned, sig, doc.signer))
+        reasons.push("bad runtime signature");
+    return reasons;
+}
+function expected(doc, opts, fields, optional = []) {
+    const reasons = [];
+    for (const [key, valid] of Object.entries(fields)) {
+        const value = opts[key];
+        if (value === undefined && optional.includes(key))
+            continue;
+        if (!valid(value))
+            reasons.push(`expected ${key} is required`);
+        else if (doc[key] !== value)
+            reasons.push(`runtime ${key} does not match`);
+    }
+    return reasons;
+}
+function time(at, opts, maxAge) {
+    if (ms(at) > ms(opts.now) + (opts.maxSkewSeconds ?? 5) * 1000)
+        return ["runtime timestamp is in the future"];
+    return maxAge !== undefined && ms(opts.now) - ms(at) >= maxAge * 1000 ? ["runtime evidence is stale"] : [];
+}
+const result = (reasons) => ({ ok: reasons.length === 0, reasons });
+const invalid = (purpose) => result([`not a runtime ${purpose} (v1)`]);
+const bindings = { certificate: isSha, release: isSha, deployment: identifier };
+export function verifyRuntimeRelease(doc, opts = {}) {
+    if (!releaseShape(doc))
+        return invalid("release");
+    const reasons = [...trust(doc, opts), ...time(doc.issued_at, opts), ...expected(doc, opts, { agent: isDid, fingerprint: isSha }, ["agent", "fingerprint"])];
+    if (opts.hash !== undefined && (!isSha(opts.hash) || jcsHash(doc) !== opts.hash))
+        reasons.push("runtime release hash does not match");
+    return result(reasons);
+}
+export const verifyRuntimePolicy = (doc) => policyShape(doc) ? result([]) : invalid("policy");
+export function verifyRuntimeApproval(doc, opts = {}) {
+    if (!approvalShape(doc))
+        return invalid("approval");
+    const reasons = [...trust(doc, opts), ...time(doc.issued_at, opts), ...expected(doc, opts, { certificate: isSha, release: isSha, policy: isSha, qualification: isSha, epoch: (v) => isInt(v, 1, Number.MAX_SAFE_INTEGER) }, ["qualification", "epoch"])];
+    if (ms(doc.valid_until) <= ms(opts.now))
+        reasons.push("runtime approval expired");
+    return result(reasons);
+}
+export function verifyRuntimeProof(doc, opts = {}) {
+    if (!proofShape(doc))
+        return invalid("proof");
+    const reasons = [...trust(doc, opts), ...expected(doc, opts, { ...bindings, challenge: nonce, attestation_sha256: isSha })];
+    if (!isInt(opts.maxAgeSeconds, 15, 300))
+        reasons.push("maxAgeSeconds must be from 15 to 300");
+    else
+        reasons.push(...time(doc.observed_at, opts, opts.maxAgeSeconds));
+    return result(reasons);
+}
+export function verifyRuntimeChallengeRequest(doc, opts = {}) {
+    if (!challengeShape(doc))
+        return invalid("challenge-request");
+    const reasons = [...trust(doc, opts), ...expected(doc, opts, bindings)];
+    if (!isInt(opts.maxAgeSeconds ?? 60, 1, 60))
+        reasons.push("maxAgeSeconds must be from 1 to 60");
+    else
+        reasons.push(...time(doc.issued_at, opts, opts.maxAgeSeconds ?? 60));
+    return result(reasons);
+}
+export function verifyRuntimeLease(doc, opts = {}) {
+    if (!leaseShape(doc))
+        return invalid("lease");
+    const reasons = [...trust(doc, opts), ...time(doc.issued_at, opts), ...expected(doc, opts, { ...bindings, policy: isSha, workload: isDid, audience: origin, permission: (v) => text(v, 128), request: isSha, epoch: (v) => isInt(v, 1, Number.MAX_SAFE_INTEGER) })];
+    if (!isInt(opts.maxTtlSeconds ?? 60, 1, 60) || ms(doc.expires_at) - ms(doc.issued_at) > (opts.maxTtlSeconds ?? 60) * 1000)
+        reasons.push("runtime lease exceeds the allowed lifetime");
+    if (ms(doc.expires_at) <= ms(opts.now))
+        reasons.push("runtime lease expired");
+    return result(reasons);
+}
+export function verifyRuntimeAction(doc, opts = {}) {
+    if (!actionShape(doc))
+        return invalid("action");
+    const reasons = [...trust(doc, opts), ...expected(doc, opts, { lease: identifier, certificate: isSha, deployment: identifier, audience: origin, permission: (v) => text(v, 128), request: isSha })];
+    if (!isInt(opts.maxAgeSeconds ?? 60, 1, 60))
+        reasons.push("maxAgeSeconds must be from 1 to 60");
+    else
+        reasons.push(...time(doc.issued_at, opts, opts.maxAgeSeconds ?? 60));
+    return result(reasons);
+}
+export function verifyRuntimeLeaseRequest(doc, opts = {}) {
+    if (!leaseRequestShape(doc))
+        return invalid("lease-request");
+    const reasons = [...trust(doc, opts), ...expected(doc, opts, { certificate: isSha, deployment: identifier, audience: origin, permission: (v) => text(v, 128), request: isSha })];
+    if (!isInt(opts.maxAgeSeconds ?? 60, 1, 60))
+        reasons.push("maxAgeSeconds must be from 1 to 60");
+    else
+        reasons.push(...time(doc.issued_at, opts, opts.maxAgeSeconds ?? 60));
+    return result(reasons);
+}
+export function verifyRuntimeMandate(doc, opts = {}) {
+    if (!mandateShape(doc))
+        return invalid("mandate");
+    const reasons = [...trust(doc, opts), ...time(doc.issued_at, opts), ...expected(doc, opts, { certificate: isSha, deployment: identifier, workload: isDid, audience: origin, permission: (v) => text(v, 128), request: isSha })];
+    if (!isInt(opts.maxTtlSeconds ?? 60, 1, 60) || ms(doc.expires_at) - ms(doc.issued_at) > (opts.maxTtlSeconds ?? 60) * 1000)
+        reasons.push("runtime mandate exceeds the allowed lifetime");
+    if (ms(doc.expires_at) <= ms(opts.now))
+        reasons.push("runtime mandate expired");
+    return result(reasons);
+}
+/** Hashes identify validated wire bytes; they do not establish signer trust or hardware state. */
+export function runtimeReleaseHash(doc) {
+    if (!releaseShape(doc))
+        throw new Error("not a runtime release (v1)");
+    return jcsHash(doc);
+}
+export function runtimePolicyHash(doc) {
+    if (!policyShape(doc))
+        throw new Error("not a runtime policy (v1)");
+    return jcsHash(doc);
+}
+export function runtimeRequestHash(request) {
+    if (!keys(request, "method url body_sha256") || !text(request.method, 16) || !/^[A-Z]{1,16}$/.test(request.method) || !isSha(request.body_sha256) || typeof request.url !== "string" || request.url.length > 2048 || !/^[\x21-\x7e]+$/.test(request.url))
+        throw new Error("not a canonical runtime request");
+    let url;
+    try {
+        url = new URL(request.url);
+    }
+    catch {
+        throw new Error("not a canonical runtime request");
+    }
+    if (!origin(url.origin) || request.url !== url.href || request.url.includes("#") || url.username || url.password)
+        throw new Error("not a canonical runtime request");
+    return jcsHash({ v: 1, type: "certify.runtime-request", ...request });
+}

package/dist/sandbox-delegation.d.ts

@@ -0,0 +1,38 @@
+import { type Signer } from "./signer.ts";
+import type { Delegation } from "./suite.ts";
+export interface SandboxDelegationPolicy {
+    v: 1;
+    type: "certify.sandbox-delegation";
+    run: string;
+    case_id: string;
+    agent: string;
+    issued_at: string;
+    expires_at: string;
+    chain_hash: string;
+    tools_hash: string;
+    certs_hash: string;
+    spend_limit: {
+        amount_minor: number;
+        currency: string;
+    };
+    signer: string;
+    sig: string;
+}
+export interface SandboxDelegationContext {
+    root: string;
+    run: string;
+    case_id: string;
+    agent: string;
+    now: string;
+}
+export declare function buildSandboxDelegationPolicy(d: Delegation, context: {
+    run: string;
+    case_id: string;
+    agent: string;
+    issued_at: string;
+    expires_at: string;
+}, signer: Signer): Promise<SandboxDelegationPolicy>;
+export declare function verifySandboxDelegationPolicy(value: unknown, d: Delegation, context: SandboxDelegationContext): {
+    ok: boolean;
+    reasons: string[];
+};

package/dist/sandbox-delegation.js

@@ -0,0 +1,61 @@
+// Lab test authority only: this envelope never grants production resource access.
+import { jcsHash } from "@zanii/core";
+import { isDid, isInt, isIso, isObj, isSha, ms } from "./shared.js";
+import { signWith, signatureOk, signerDid } from "./signer.js";
+const id = (v) => typeof v === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(v);
+const scope = (v) => typeof v === "string" && v.length <= 128 && /^(\*|[a-z0-9_-]+(\.[a-z0-9_-]+)*(\.\*)?)$/.test(v);
+const keys = (v, required, optional = []) => isObj(v) && required.every((key) => Object.hasOwn(v, key)) && Object.keys(v).every((key) => required.includes(key) || optional.includes(key));
+const amount = (v) => keys(v, ["amount_minor", "currency"]) && isInt(v.amount_minor, 0, Number.MAX_SAFE_INTEGER) && typeof v.currency === "string" && /^[A-Z]{3}$/.test(v.currency);
+function hashes(d) {
+    if (!isObj(d) || !Array.isArray(d.chain) || d.chain.length < 1 || d.chain.length > 8 || !Array.isArray(d.tools) || d.tools.length > 64
+        || !Array.isArray(d.certs) || d.certs.length !== d.chain.length)
+        throw new Error("sandbox delegation needs a bounded signed chain");
+    for (const link of d.chain)
+        if (!keys(link, ["agent", "scopes", "spend_limit"]) || !id(link.agent) || !Array.isArray(link.scopes) || !link.scopes.length || link.scopes.length > 64 || !link.scopes.every(scope) || !amount(link.spend_limit))
+            throw new Error("invalid sandbox delegation link");
+    if (new Set(d.chain.map((link) => link.spend_limit.currency)).size !== 1)
+        throw new Error("sandbox delegation currency must be consistent");
+    for (const tool of d.tools)
+        if (!keys(tool, ["name", "scope"], ["amount", "currency"]) || typeof tool.name !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(tool.name) || !scope(tool.scope)
+            || [tool.amount, tool.currency].some((v) => v !== undefined && (typeof v !== "string" || !/^[A-Za-z0-9_]{1,64}$/.test(v))))
+            throw new Error("invalid sandbox delegation tool");
+    for (const cert of d.certs)
+        if (!keys(cert, ["v", "issuer", "subject", "scopes", "exp", "sig"]) || cert.v !== 1 || !isDid(cert.issuer) || !isDid(cert.subject) || !isIso(cert.exp)
+            || !Array.isArray(cert.scopes) || !cert.scopes.length || cert.scopes.length > 64 || !cert.scopes.every(scope) || typeof cert.sig !== "string" || !/^ed25519:[0-9a-f]{128}$/.test(cert.sig))
+            throw new Error("invalid sandbox delegation certificate");
+    return { chain_hash: jcsHash(d.chain), tools_hash: jcsHash(d.tools), certs_hash: jcsHash(d.certs), spend_limit: {
+            amount_minor: Math.min(...d.chain.map((link) => link.spend_limit.amount_minor)), currency: d.chain[0].spend_limit.currency
+        } };
+}
+function shape(value) {
+    return keys(value, ["v", "type", "run", "case_id", "agent", "issued_at", "expires_at", "chain_hash", "tools_hash", "certs_hash", "spend_limit", "signer", "sig"])
+        && value.v === 1 && value.type === "certify.sandbox-delegation" && id(value.run) && id(value.case_id) && isDid(value.agent) && isDid(value.signer)
+        && isIso(value.issued_at) && isIso(value.expires_at) && ms(value.expires_at) > ms(value.issued_at) && ms(value.expires_at) - ms(value.issued_at) <= 3600000
+        && [value.chain_hash, value.tools_hash, value.certs_hash].every(isSha) && amount(value.spend_limit) && typeof value.sig === "string" && /^ed25519:[0-9a-f]{128}$/.test(value.sig);
+}
+export async function buildSandboxDelegationPolicy(d, context, signer) {
+    const fields = { v: 1, type: "certify.sandbox-delegation", ...context, ...hashes(d) };
+    const candidate = { ...fields, signer: signerDid(signer), sig: `ed25519:${"0".repeat(128)}` };
+    if (!shape(candidate) || d.certs[0].issuer !== candidate.signer || d.certs.at(-1).subject !== context.agent)
+        throw new Error("sandbox policy signer or context does not match its chain");
+    return await signWith(fields, signer);
+}
+export function verifySandboxDelegationPolicy(value, d, context) {
+    try {
+        if (!shape(value) || !isDid(context.root) || !id(context.run) || !id(context.case_id) || !isDid(context.agent) || !isIso(context.now))
+            return { ok: false, reasons: ["invalid sandbox delegation or expected context"] };
+        const reasons = [], expected = hashes(d), { sig, ...unsigned } = value;
+        if (value.signer !== context.root || d.certs[0].issuer !== context.root || !signatureOk(unsigned, sig, context.root))
+            reasons.push("sandbox policy is not signed by the expected run root");
+        if (value.run !== context.run || value.case_id !== context.case_id || value.agent !== context.agent || d.certs.at(-1).subject !== context.agent)
+            reasons.push("sandbox run, case or tested agent does not match");
+        if (ms(value.issued_at) > ms(context.now) || ms(value.expires_at) <= ms(context.now))
+            reasons.push("sandbox policy is not current");
+        if (value.chain_hash !== expected.chain_hash || value.tools_hash !== expected.tools_hash || value.certs_hash !== expected.certs_hash || jcsHash(value.spend_limit) !== jcsHash(expected.spend_limit))
+            reasons.push("sandbox signed budget or delegation changed");
+        return { ok: reasons.length === 0, reasons };
+    }
+    catch {
+        return { ok: false, reasons: ["invalid sandbox delegation or expected context"] };
+    }
+}

package/dist/schema-dialect.d.ts

@@ -0,0 +1 @@
+export declare function schemaDialectErrors(schema: unknown): string[];