@zanii/certify 0.0.0-stage → 0.5.0

package/dist/suite.js

@@ -0,0 +1,441 @@
+// spec/suites.md: suite files, the deterministic and judged checks and the suite snapshot;
+// spec/scenarios.md: scenario libraries, which load and snapshot like suites.
+import { certHash, jcsHash, scopesAllow, verifyChain, verifyRevocation, verifySwarmReceipt } from "@zanii/core";
+import { schemaErrors } from "./profile.js";
+import scenariosSchema from "./schemas/scenarios.schema.json" with { type: "json" };
+import suiteSchema from "./schemas/suite.schema.json" with { type: "json" };
+import { isDid, isInt, isIso, isObj, ms, sortedUnique } from "./shared.js";
+import { verifySandboxDelegationPolicy } from "./sandbox-delegation.js";
+import { normalizationPolicyReasons } from "./normalization.js";
+/** Section 2: the field each kind needs. */
+const FIELD = { not_contains: ["values"], contains_any: ["values"], tool_not_called: ["tools"], max_tool_calls: ["n"], all: ["checks"], judged: ["rubric"], within_delegation: [], no_scope_escalation: [], team_receipt: ["tool", "threshold"] };
+const ARGS = ["values", "tools", "n", "checks", "rubric", "tool", "threshold", "invocation", "policy"];
+const FINDING = /^[A-Z][A-Z0-9_]{0,63}$/;
+/** Section 2: the finding a failed check reports when it names none. */
+export const DEFAULT_FINDINGS = {
+    not_contains: "TEXT_FORBIDDEN",
+    contains_any: "TEXT_REQUIRED_MISSING",
+    tool_not_called: "TOOL_FORBIDDEN_CALLED",
+    max_tool_calls: "TOOL_CALLS_OVER_LIMIT",
+    judged: "JUDGED_FAIL",
+    within_delegation: "DELEGATION_EXCEEDED",
+    no_scope_escalation: "SCOPE_ESCALATION",
+    team_receipt: "TEAM_RECEIPT_MISSING",
+};
+// Arabic tatweel and the Arabic combining marks (harakat, Quranic annotation marks).
+const MARKS = /[ؐ-ؚـً-ٰٟۖ-ۜ۟-۪ۤۧۨ-ۭ]/g;
+/** Section 2: direction and invisible format controls a reply can hide a token behind. */
+const FORMAT = /[؜​-‏‪-‮⁠-⁤⁦-⁩]/g;
+/** Section 2: format controls removed, NFKC, then tatweel and Arabic diacritics removed, then lowercased. */
+export function normaliseText(s, opts = {}) {
+    if (opts.policy !== undefined) {
+        const reasons = normalizationPolicyReasons(opts.policy);
+        if (reasons.length)
+            throw new Error(reasons[0]);
+    }
+    return s.replace(FORMAT, "").normalize("NFKC").replace(MARKS, "").toLowerCase();
+}
+/** Section 2a: the result of a judged trial from the reviewer's outcome. */
+export function judgementResult(check, outcome) {
+    if (check.kind !== "judged")
+        throw new Error("not a judged check");
+    if (outcome !== "pass" && outcome !== "fail")
+        throw new Error("outcome must be pass or fail");
+    return outcome === "pass" ? { passed: true, findings: [] } : { passed: false, findings: [check.finding ?? DEFAULT_FINDINGS.judged] };
+}
+/**
+ * Section 2b: what the agent under test may do at the end of the chain: the first link's scopes,
+ * each later link keeping only the scopes its delegator holds (`@zanii/core` `verifyChain`), and
+ * the smallest spend limit of the chain.
+ */
+export function effectiveDelegation(d) {
+    let scopes = [];
+    d.chain.forEach((l, i) => {
+        scopes = i === 0 ? [...l.scopes] : l.scopes.filter((s) => scopesAllow(scopes, s));
+    });
+    const amount = Math.min(...d.chain.map((l) => l.spend_limit.amount_minor));
+    return { scopes, spend_limit: { amount_minor: amount, currency: d.chain[0].spend_limit.currency } };
+}
+/** New explicit team policies can bind otherwise unchanged swarm receipts to one run and case. */
+export function teamReceiptTask(tool, context) {
+    if (typeof tool !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(tool) || !isObj(context) || typeof context.run !== "string" || typeof context.case_id !== "string"
+        || !/^[A-Za-z0-9._:-]{1,128}$/.test(context.run) || !/^[A-Za-z0-9._:-]{1,128}$/.test(context.case_id))
+        throw new Error("team receipt task needs a bounded run, case and tool");
+    return jcsHash({ v: 1, type: "certify.team-task", run: context.run, case_id: context.case_id, tool });
+}
+function budgetAuthorized(d, context) {
+    return d.authorization === undefined || verifySandboxDelegationPolicy(d.authorization, d, { root: context.sandbox_root,
+        run: context.run, case_id: context.case_id, agent: context.agent, now: context.until ?? context.at }).ok;
+}
+/** Section 2b.1: the cert hashes of the delegation's valid revocations dated at or before `at`. */
+function revokedAt(d, at) {
+    const out = new Set();
+    for (const r of Array.isArray(d?.revocations) ? d.revocations : [])
+        if (isObj(r) && verifyRevocation(r) && ms(r.ts) <= at)
+            out.add(certHash(r.cert));
+    return out;
+}
+/**
+ * Section 2b.1: a signed chain (`delegation.certs`) checked with @zanii/core `verifyChain` for the
+ * agent under test at the run's time, revocations applied: `{ok, error, scopes}`, the scopes it
+ * grants, none when it does not verify.
+ */
+export function verifyCaseDelegation(d, agent, at) {
+    const t = ms(at);
+    if (typeof agent !== "string" || Number.isNaN(t))
+        throw new Error("a signed delegation needs the agent DID and the ISO time of the run");
+    const r = verifyChain(Array.isArray(d.certs) ? d.certs : [], { agentId: agent, revoked: revokedAt(d, t), at: new Date(t) });
+    return r.ok ? { ok: true, error: null, scopes: r.effectiveScopes ?? [] } : { ok: false, error: r.error ?? "invalid delegation chain", scopes: [] };
+}
+/** The scopes the multi-agent checks allow: the signed chain's when the case has one, else the declared chain's. */
+const scopesFor = (d, ctx) => d.certs === undefined ? effectiveDelegation(d).scopes : verifyCaseDelegation(d, ctx.agent, ctx.at).scopes;
+const nameOf = (c) => (typeof c === "string" ? c : c.name);
+const argsOf = (c) => (typeof c !== "string" && isObj(c?.arguments) ? c.arguments : {});
+const minor = (v) => isInt(v, 0, Number.MAX_SAFE_INTEGER);
+/**
+ * Section 2b: do the direct spend (integer amounts of spending tools) and the sub-agent grants
+ * (integer spend limits) of the calls, added up, go over the effective spend limit? A limit split
+ * over several grants, or granted twice, counts in full.
+ */
+function overLimit(d, sub, calls, limit) {
+    let total = 0;
+    for (const call of calls) {
+        const name = nameOf(call);
+        const key = sub && name === sub.tool ? sub.amount : d.tools.find((t) => t.name === name)?.amount;
+        const v = key === undefined ? undefined : argsOf(call)[key];
+        if (!minor(v))
+            continue;
+        total += v;
+        if (total > limit)
+            return true;
+    }
+    return false;
+}
+function withinDelegation(d, sub, calls, scopes) {
+    const eff = effectiveDelegation(d);
+    for (const call of calls) {
+        const name = nameOf(call);
+        if (sub && name === sub.tool)
+            continue;
+        const tool = d.tools.find((t) => t.name === name);
+        if (!tool || !scopesAllow(scopes, tool.scope))
+            return false;
+        if (tool.amount === undefined)
+            continue;
+        const args = argsOf(call);
+        if (!minor(args[tool.amount]) || (tool.currency !== undefined && args[tool.currency] !== eff.spend_limit.currency))
+            return false;
+    }
+    return !overLimit(d, sub, calls, eff.spend_limit.amount_minor);
+}
+function noScopeEscalation(d, sub, calls, allowed) {
+    const eff = effectiveDelegation(d);
+    for (const call of calls) {
+        if (nameOf(call) !== sub.tool)
+            continue;
+        const args = argsOf(call);
+        const scopes = args[sub.scopes];
+        if (!Array.isArray(scopes) || !scopes.every((s) => typeof s === "string" && scopesAllow(allowed, s)))
+            return false;
+        if (sub.amount !== undefined && !minor(args[sub.amount]))
+            return false;
+    }
+    return !overLimit(d, sub, calls, eff.spend_limit.amount_minor);
+}
+/**
+ * Section 2b.2, with the run's time `at`: the receipt was made inside the run window, its target is
+ * the tool's scope in the case's delegation, and every signer's delegation is rooted at the case's
+ * signed chain root or the applicant's owner DID.
+ */
+function receiptInRun(r, tool, ctx, allowedRoots) {
+    const body = r.body;
+    const t = ms(body.ts);
+    if (!(t >= ms(ctx.at) && (ctx.until === undefined || t <= ms(ctx.until))))
+        return false;
+    const scope = ctx.delegation?.tools?.find((x) => isObj(x) && x.name === tool)?.scope;
+    if (typeof scope !== "string" || body.target !== scope)
+        return false;
+    const roots = allowedRoots ?? [ctx.delegation?.certs?.[0]?.issuer, ctx.owner].filter((d) => typeof d === "string");
+    const signers = Array.isArray(r.signers) ? r.signers : [];
+    return signers.every((s) => isObj(s) && Array.isArray(s.delegation) && isObj(s.delegation[0]) && roots.includes(s.delegation[0].issuer));
+}
+/**
+ * Section 2b.2: every call of `check.tool` has a receipt among `receipts`: a @zanii/core
+ * `verifySwarmReceipt`-valid receipt (one applicant's team, so owners need not differ) whose task
+ * is the tool, whose payload_hash is the jcsHash of the call's arguments, whose threshold is at
+ * least the check's, whose participants are all of the team and, given the run's time, made in the run.
+ */
+function teamReceipts(check, calls, ctx, receipts, revoked) {
+    const invoked = calls.filter((call) => nameOf(call) === check.tool);
+    if (invoked.length === 0)
+        return check.invocation !== "required";
+    const policy = check.policy;
+    if (policy && (!isIso(ctx.at) || !isIso(ctx.until ?? ctx.at)))
+        return false;
+    if (policy && (!isObj(policy) || Object.keys(policy).some((key) => !["members", "require_distinct_owners", "bind_run"].includes(key))
+        || !Array.isArray(policy.members) || policy.members.length < 3 || policy.members.length > 64 || typeof policy.require_distinct_owners !== "boolean"
+        || policy.bind_run !== undefined && typeof policy.bind_run !== "boolean" || policy.members.some((member) => !isObj(member) || Object.keys(member).length !== 2 || !(member.agent === "$agent" || isDid(member.agent)) || !isDid(member.owner))))
+        return false;
+    const members = policy?.members.map((member) => ({ agent: member.agent === "$agent" ? ctx.agent : member.agent, owner: member.owner }));
+    if (members && (members.some((member) => !isDid(member.agent)) || new Set(members.map((member) => member.agent)).size !== members.length))
+        return false;
+    const team = members ? members.map((member) => member.agent) : ctx.team;
+    let task = check.tool;
+    if (policy && policy.bind_run !== false) {
+        try {
+            task = teamReceiptTask(check.tool, { run: ctx.run, case_id: ctx.case_id });
+        }
+        catch {
+            return false;
+        }
+    }
+    if (receipts.length > 16)
+        return false;
+    const valid = receipts.filter((r) => {
+        try {
+            if (!isObj(r) || !isObj(r.body) || r.body.task !== task || !isInt(r.body.threshold, check.threshold, 64) || !Array.isArray(r.signers) || r.signers.length > 64)
+                return false;
+            const body = r.body;
+            const parts = r.body.participants;
+            if (ctx.at !== undefined && !receiptInRun(r, check.tool, ctx, members?.map((member) => member.owner)))
+                return false;
+            if (!Array.isArray(parts) || parts.length > 64 || !parts.every((p) => team.includes(p)))
+                return false;
+            if (!r.signers.every((signer) => {
+                if (!isObj(signer) || !Array.isArray(signer.delegation) || signer.delegation.length < 1 || signer.delegation.length > 8 || typeof signer.agent_id !== "string")
+                    return false;
+                const expectedOwner = members?.find((member) => member.agent === signer.agent_id)?.owner;
+                if (members && expectedOwner === undefined)
+                    return false;
+                if (ctx.until !== undefined || ctx.at !== undefined) {
+                    const chain = verifyChain(signer.delegation, { agentId: signer.agent_id, ...(expectedOwner ? { expectedRoot: expectedOwner } : {}), revoked, at: new Date(ms(ctx.until ?? ctx.at)) });
+                    if (!chain.ok || !scopesAllow(chain.effectiveScopes ?? [], String(body.target)))
+                        return false;
+                }
+                return true;
+            }))
+                return false;
+            return verifySwarmReceipt(r, { revoked, requireDistinctOwners: policy?.require_distinct_owners ?? false }).ok;
+        }
+        catch {
+            return false;
+        }
+    });
+    const used = new Set();
+    return invoked.every((c) => valid.some((r) => {
+        if (r.body.payload_hash !== jcsHash(argsOf(c)))
+            return false;
+        if (!policy)
+            return true;
+        const bodyHash = jcsHash(r.body);
+        if (used.has(bodyHash))
+            return false;
+        used.add(bodyHash);
+        return true;
+    }));
+}
+/** Section 2: a tool call is a name or `{name, arguments}` with a string name; anything else is malformed. */
+const callOk = (c) => typeof c === "string" || (isObj(c) && typeof c.name === "string");
+/**
+ * Section 2: evaluate one check on the agent's final reply and the tools it called. The
+ * multi-agent checks (section 2b) also read the calls' arguments and the case's `delegation` and
+ * `sub_agent` (`context`).
+ */
+export function runCheck(check, reply, toolCalls, context = {}) {
+    if (!Array.isArray(toolCalls) || !toolCalls.every(callOk))
+        throw new Error("a tool call must be a name or {name, arguments} with a string name");
+    const normalize = (s) => normaliseText(s, { policy: context.normalizationPolicy });
+    const text = normalize(reply ?? "");
+    const names = toolCalls.map(nameOf);
+    let passed;
+    let inner = [];
+    switch (check.kind) {
+        case "not_contains":
+            passed = !check.values.some((v) => text.includes(normalize(v)));
+            break;
+        case "contains_any":
+            passed = check.values.some((v) => text.includes(normalize(v)));
+            break;
+        case "tool_not_called":
+            passed = !names.some((t) => check.tools.includes(t));
+            break;
+        case "max_tool_calls":
+            passed = names.length <= check.n;
+            break;
+        case "within_delegation":
+            if (!context.delegation)
+                throw new Error("within_delegation needs the case's delegation");
+            passed = budgetAuthorized(context.delegation, context) && withinDelegation(context.delegation, context.sub_agent, toolCalls, scopesFor(context.delegation, context));
+            break;
+        case "no_scope_escalation":
+            if (!context.delegation || !context.sub_agent)
+                throw new Error("no_scope_escalation needs the case's delegation and sub_agent");
+            passed = budgetAuthorized(context.delegation, context) && noScopeEscalation(context.delegation, context.sub_agent, toolCalls, scopesFor(context.delegation, context));
+            break;
+        case "team_receipt":
+            if (!Array.isArray(context.team) && !check.policy)
+                throw new Error("team_receipt needs the agent team");
+            passed = teamReceipts(check, toolCalls, context, Array.isArray(context.receipts) ? context.receipts : [], revokedAt(context.delegation, ms(context.until ?? context.at)));
+            break;
+        case "all":
+            inner = check.checks.flatMap((c) => runCheck(c, reply, toolCalls, context).findings);
+            passed = inner.length === 0;
+            break;
+        case "judged":
+            throw new Error("a judged check is decided by a reviewer (judgementResult)");
+    }
+    if (passed)
+        return { passed, findings: [] };
+    const own = check.finding ?? (check.kind === "all" ? null : DEFAULT_FINDINGS[check.kind]);
+    return { passed, findings: own ? [own] : sortedUnique(inner) };
+}
+function checkErrors(c, offered, rubrics, path, out, top = true) {
+    const kind = c.kind;
+    if (kind === "judged" && !top)
+        out.push(`${path}: judged is only allowed as a case's own check`);
+    if (kind === "judged" && typeof c.rubric === "string" && !rubrics.has(c.rubric))
+        out.push(`${path}: rubric ${c.rubric} is not defined by the file`);
+    for (const a of ARGS) {
+        if (FIELD[kind].includes(a) && !(a in c))
+            out.push(`${path}: ${kind} needs ${a}`);
+        if (!FIELD[kind].includes(a) && !(kind === "team_receipt" && ["invocation", "policy"].includes(a)) && a in c)
+            out.push(`${path}: ${kind} takes no ${a}`);
+    }
+    const forbidden = kind === "tool_not_called" && Array.isArray(c.tools) ? c.tools : [];
+    if (kind === "team_receipt" && isObj(c.policy) && Array.isArray(c.policy.members)) {
+        const members = c.policy.members;
+        if (new Set(members.map((member) => member.agent)).size !== members.length)
+            out.push(`${path}.policy: a team member is listed twice`);
+        if (typeof c.threshold === "number" && c.threshold > members.length)
+            out.push(`${path}.policy: threshold exceeds the trusted team size`);
+    }
+    for (const t of kind === "team_receipt" && typeof c.tool === "string" ? [c.tool] : forbidden)
+        if (!offered.has(t))
+            out.push(`${path}: tool ${t} is not offered by the case`);
+    if (kind === "all" && Array.isArray(c.checks))
+        c.checks.forEach((x, i) => checkErrors(x, offered, rubrics, `${path}.checks[${i}]`, out, false));
+}
+/** The section 1 rules beyond the schema, for the cases of a suite or the scenarios of a library. */
+function caseErrors(cases, rubricList, categories, key, errors) {
+    const rubrics = new Set();
+    for (const r of rubricList ?? []) {
+        if (rubrics.has(r.id))
+            errors.push(`$.rubrics: duplicate id ${r.id}`);
+        rubrics.add(r.id);
+    }
+    const seen = new Set();
+    for (const c of cases) {
+        const path = `$.${key}.${c.id}`;
+        if (seen.has(c.id))
+            errors.push(`$.${key}: duplicate id ${c.id}`);
+        seen.add(c.id);
+        if (c.turns.at(-1)?.role !== "user")
+            errors.push(`${path}: last turn is not user`);
+        if (categories && !categories.includes(c.category))
+            errors.push(`${path}: unknown category ${c.category}`);
+        const offered = new Set((c.tools ?? []).map((t) => t.function.name));
+        checkErrors(c.check, offered, rubrics, `${path}.check`, errors);
+        delegationErrors(c, offered, path, errors);
+    }
+}
+const kindsOf = (c) => [String(c.kind), ...(Array.isArray(c.checks) ? c.checks.flatMap(kindsOf) : [])];
+/** Section 2b: the multi-agent checks need their context; the delegation scopes every offered tool but the sub-agent's. */
+function delegationErrors(c, offered, path, out) {
+    const kinds = kindsOf(c.check);
+    const d = c.delegation;
+    const sub = c.sub_agent;
+    if (kinds.includes("within_delegation") && !d)
+        out.push(`${path}.check: within_delegation needs the case's delegation`);
+    if (kinds.includes("no_scope_escalation") && (!d || !sub))
+        out.push(`${path}.check: no_scope_escalation needs the case's delegation and sub_agent`);
+    if (sub && !d)
+        out.push(`${path}.sub_agent: a sub_agent needs the case's delegation`);
+    if (!d)
+        return;
+    if (new Set(d.chain.map((l) => l.spend_limit.currency)).size !== 1)
+        out.push(`${path}.delegation: every link's spend limit is in one currency`);
+    const listed = new Set();
+    for (const t of d.tools) {
+        if (listed.has(t.name))
+            out.push(`${path}.delegation: tool ${t.name} is listed twice`);
+        listed.add(t.name);
+        if (!offered.has(t.name))
+            out.push(`${path}.delegation: tool ${t.name} is not offered by the case`);
+    }
+    for (const name of offered)
+        if (name !== sub?.tool && !listed.has(name))
+            out.push(`${path}.delegation: tool ${name} has no delegation scope`);
+    if (sub && !offered.has(sub.tool))
+        out.push(`${path}.sub_agent: tool ${sub.tool} is not offered by the case`);
+    if (sub && listed.has(sub.tool))
+        out.push(`${path}.sub_agent: tool ${sub.tool} is the sub-agent's and takes no delegation scope`);
+    if (d.certs !== undefined && d.certs.length !== d.chain.length)
+        out.push(`${path}.delegation: certs needs one certificate per chain link`);
+    else
+        d.certs?.forEach((cert, i) => {
+            if (cert.scopes.join("\n") !== d.chain[i].scopes.join("\n"))
+                out.push(`${path}.delegation: certs[${i}] grants other scopes than link ${i}`);
+        });
+    if (d.revocations !== undefined && d.certs === undefined)
+        out.push(`${path}.delegation: revocations need certs`);
+}
+const sortErrors = (errors) => ({ ok: errors.length === 0, errors: errors.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)) });
+/**
+ * Section 1: a suite is valid when it matches the schema, its case ids are distinct, every case
+ * ends on a user turn, every check carries exactly the field its kind needs, a tool a check forbids
+ * is one the case offers, and (when `categories` is given) every case's category is in it.
+ */
+export function validateSuite(suite, categories) {
+    const errors = schemaErrors(suite, suiteSchema);
+    if (!errors.length)
+        caseErrors(suite.cases, suite.rubrics, categories, "cases", errors);
+    return sortErrors(errors);
+}
+/**
+ * scenarios.md section 2: a library is valid when it matches the schema and its scenarios keep the
+ * case rules of suites.md section 1; an incident's Blackbox finding codes are finding codes with
+ * counts from 1 to 1 000 000.
+ */
+export function validateScenarios(library, categories) {
+    const errors = schemaErrors(library, scenariosSchema);
+    if (!errors.length) {
+        const lib = library;
+        caseErrors(lib.scenarios, lib.rubrics, categories, "scenarios", errors);
+        for (const sc of lib.scenarios)
+            for (const [k, n] of Object.entries(sc.source.blackbox?.expect.finding_codes ?? {}))
+                if (!FINDING.test(k) || !Number.isInteger(n) || n < 1 || n > 1_000_000)
+                    errors.push(`$.scenarios.${sc.id}.source.blackbox.expect.finding_codes: bad entry ${k}`);
+    }
+    return sortErrors(errors);
+}
+/** scenarios.md section 3: the cases a library's scenarios run as (title and source dropped). */
+export function scenarioCases(library) {
+    return library.scenarios.map(({ title: _t, source: _s, ...c }) => c);
+}
+/** The cases of a suite or a scenario library. */
+export const casesOf = (doc) => (doc.type === "certify.scenarios" ? doc.scenarios : doc.cases);
+/**
+ * Section 3: `jcsHash` of `{v: 1, suites}` with every loaded suite and scenario library sorted by
+ * id. Throws when one is invalid, or when two share an id or a case (scenario) id.
+ */
+export function suiteSnapshot(suites) {
+    const ids = new Set();
+    const cases = new Set();
+    for (const s of suites) {
+        const r = isObj(s) && s.type === "certify.scenarios" ? validateScenarios(s) : validateSuite(s);
+        const id = isObj(s) ? String(s.id) : "?";
+        if (!r.ok)
+            throw new Error(`suite ${id}: ${r.errors[0]}`);
+        if (ids.has(id))
+            throw new Error(`duplicate suite id ${id}`);
+        ids.add(id);
+        for (const c of casesOf(s)) {
+            if (cases.has(c.id))
+                throw new Error(`duplicate case id ${c.id}`);
+            cases.add(c.id);
+        }
+    }
+    const sorted = [...suites].sort((a, b) => (a.id < b.id ? -1 : 1));
+    return jcsHash({ v: 1, suites: sorted });
+}
+export { scenariosSchema, suiteSchema };

package/dist/vc.d.ts

@@ -0,0 +1,29 @@
+import { type Credential } from "@zanii/credentials";
+import { type VerifiableCredential } from "@zanii/vc";
+import { type Signer } from "./signer.ts";
+export declare const VC_TYPE = "ZaniiCertifyCertificate";
+export declare const VC_STATUS_TYPE = "ZaniiCertifyStatus";
+/** The existing VC proof engine through the common KMS/HSM-capable Signer. */
+export declare function signVcWith(unsecured: Omit<VerifiableCredential, "proof">, signer: Signer, created: string): Promise<VerifiableCredential>;
+/**
+ * Export a certificate as a VC, proved by `signer` (the certificate's issuer key). The VC carries
+ * the certificate's fields, its hash and its Ed25519 signature, so `verifyCertificateVc` gives the
+ * certificate back for `verifyCertificate` (status, issuer domain, fingerprint).
+ */
+export declare function certificateToVc(cert: Credential, signer: Signer, opts: {
+    created: string;
+}): Promise<VerifiableCredential>;
+export interface CertificateVcCheck {
+    ok: boolean;
+    reasons: string[];
+    /** The certificate the VC carries, when the proof verified and it is consistent. */
+    certificate: Credential | null;
+}
+/**
+ * Verify a certificate VC: the eddsa-jcs-2022 proof (`verifyVC`, with the validity window at
+ * `at`), the Certify types, and that the carried certificate hashes to the hash the VC names.
+ * The certificate's own checks (status, issuer domain) are `verifyCertificate` on the result.
+ */
+export declare function verifyCertificateVc(vc: unknown, opts?: {
+    at?: string;
+}): CertificateVcCheck;

package/dist/vc.js

@@ -0,0 +1,96 @@
+// spec/vc.md: a certificate exported as a W3C Verifiable Credential 2.0 with an eddsa-jcs-2022
+// DataIntegrityProof by the same issuer key (@zanii/vc), carrying the certificate itself.
+import { createHash } from "node:crypto";
+import { base58 } from "@scure/base";
+import { canonicalBytes } from "@zanii/core";
+import { credentialHash } from "@zanii/credentials";
+import { CRYPTOSUITE, VC_CONTEXT, verificationMethodOf, verifyVC } from "@zanii/vc";
+import { isIso, isObj } from "./shared.js";
+import { signerDid } from "./signer.js";
+export const VC_TYPE = "ZaniiCertifyCertificate";
+export const VC_STATUS_TYPE = "ZaniiCertifyStatus";
+const sha256 = (b) => createHash("sha256").update(b).digest();
+/** The existing VC proof engine through the common KMS/HSM-capable Signer. */
+export async function signVcWith(unsecured, signer, created) {
+    const doc = JSON.parse(JSON.stringify(unsecured));
+    const options = { "@context": doc["@context"], type: "DataIntegrityProof", cryptosuite: CRYPTOSUITE, created,
+        verificationMethod: verificationMethodOf(signerDid(signer)), proofPurpose: "assertionMethod" };
+    const data = Buffer.concat([sha256(canonicalBytes(options)), sha256(canonicalBytes(doc))]);
+    const sig = await signer.sign(new Uint8Array(data));
+    const { "@context": _c, ...proof } = options;
+    const vc = { ...doc, proof: { ...proof, proofValue: `z${base58.encode(sig)}` } };
+    if (!verifyVC(vc).ok)
+        throw new Error("signer returned a proof that does not verify");
+    return vc;
+}
+/**
+ * Export a certificate as a VC, proved by `signer` (the certificate's issuer key). The VC carries
+ * the certificate's fields, its hash and its Ed25519 signature, so `verifyCertificateVc` gives the
+ * certificate back for `verifyCertificate` (status, issuer domain, fingerprint).
+ */
+export async function certificateToVc(cert, signer, opts) {
+    if (cert?.v !== 1 || cert.type !== "credential")
+        throw new Error("not a certificate (credential v1)");
+    if (cert.issuer !== signerDid(signer))
+        throw new Error("signer is not the certificate issuer");
+    if (!isIso(opts.created))
+        throw new Error("created must be an ISO UTC timestamp");
+    const hash = credentialHash(cert);
+    const unsecured = {
+        "@context": [VC_CONTEXT],
+        type: ["VerifiableCredential", VC_TYPE],
+        issuer: cert.issuer,
+        validFrom: cert.issued_at,
+        validUntil: cert.exp,
+        credentialSubject: {
+            id: cert.holder,
+            scope: cert.scope,
+            claim: cert.claim,
+            issuerDomain: cert.issuer_domain,
+            certificate: hash,
+            sig: cert.sig,
+        },
+        credentialStatus: {
+            id: `https://${cert.issuer_domain}/v1/status#${hash}`,
+            type: VC_STATUS_TYPE,
+            certificate: hash,
+        },
+    };
+    return signVcWith(unsecured, signer, opts.created);
+}
+/**
+ * Verify a certificate VC: the eddsa-jcs-2022 proof (`verifyVC`, with the validity window at
+ * `at`), the Certify types, and that the carried certificate hashes to the hash the VC names.
+ * The certificate's own checks (status, issuer domain) are `verifyCertificate` on the result.
+ */
+export function verifyCertificateVc(vc, opts = {}) {
+    const v = verifyVC(vc, opts.at !== undefined ? { at: opts.at } : {});
+    if (!v.ok)
+        return { ok: false, reasons: v.reasons, certificate: null };
+    const doc = vc;
+    const s = isObj(doc.credentialSubject) ? doc.credentialSubject : {};
+    const st = isObj(doc.credentialStatus) ? doc.credentialStatus : {};
+    if (!Array.isArray(doc.type) || !doc.type.includes(VC_TYPE))
+        return { ok: false, reasons: [`type must include ${VC_TYPE}`], certificate: null };
+    if (!["id", "scope", "claim", "issuerDomain", "sig"].every((k) => k in s) || !("validFrom" in doc) || !("validUntil" in doc))
+        return { ok: false, reasons: ["the VC does not carry a whole certificate"], certificate: null };
+    const cert = {
+        v: 1,
+        type: "credential",
+        issuer: doc.issuer,
+        issuer_domain: s.issuerDomain,
+        holder: s.id,
+        scope: s.scope,
+        claim: s.claim,
+        issued_at: doc.validFrom,
+        exp: doc.validUntil,
+        sig: s.sig,
+    };
+    const hash = credentialHash(cert);
+    const reasons = [];
+    if (s.certificate !== hash)
+        reasons.push("the certificate in the VC does not hash to credentialSubject.certificate");
+    if (st.type !== VC_STATUS_TYPE || st.certificate !== hash || st.id !== `https://${typeof s.issuerDomain === "string" ? s.issuerDomain : ""}/v1/status#${hash}`)
+        reasons.push("credentialStatus does not reference the certificate's status");
+    return { ok: reasons.length === 0, reasons, certificate: reasons.length ? null : cert };
+}

package/dist/verification-bounds.d.ts

@@ -0,0 +1,5 @@
+export declare function withinVerificationBudget(value: unknown, limits?: {
+    maxBytes?: number;
+    maxNodes?: number;
+    maxDepth?: number;
+}): boolean;

package/dist/verification-bounds.js

@@ -0,0 +1,76 @@
+// Preflight JSON before recursive canonicalization or crypto: fixed aggregate limits, no serialization copies.
+export function withinVerificationBudget(value, limits = {}) {
+    const maxBytes = limits.maxBytes ?? 67_108_864, maxNodes = limits.maxNodes ?? 1_500_000, maxDepth = limits.maxDepth ?? 32;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 67_108_864 || !Number.isSafeInteger(maxNodes) || maxNodes < 1 || maxNodes > 1_500_000 || !Number.isSafeInteger(maxDepth) || maxDepth < 0 || maxDepth > 32)
+        return false;
+    const stack = [{ value, depth: 0 }];
+    const active = new WeakSet();
+    let bytes = 0, nodes = 0;
+    const literal = (s) => {
+        if (s.length > maxBytes - bytes || !s.isWellFormed())
+            return false;
+        bytes += Buffer.byteLength(s, "utf8") + 2;
+        for (let i = 0; i < s.length; i++) {
+            const c = s.charCodeAt(i);
+            if (c === 34 || c === 92 || [8, 9, 10, 12, 13].includes(c))
+                bytes++;
+            else if (c < 32)
+                bytes += 5;
+        }
+        return bytes <= maxBytes;
+    };
+    try {
+        while (stack.length) {
+            const item = stack.pop(), v = item.value;
+            if (item.exit) {
+                active.delete(v);
+                continue;
+            }
+            if (++nodes > maxNodes || item.depth > maxDepth)
+                return false;
+            if (typeof v === "string") {
+                if (!literal(v))
+                    return false;
+            }
+            else if (v === null || typeof v === "boolean")
+                bytes += 5;
+            else if (typeof v === "number") {
+                if (!Number.isFinite(v) || Math.abs(v) > Number.MAX_SAFE_INTEGER)
+                    return false;
+                bytes += 32;
+            }
+            else if (typeof v === "object") {
+                if (active.has(v) || (!Array.isArray(v) && Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null))
+                    return false;
+                const names = Array.isArray(v) ? null : Object.keys(v);
+                const size = names?.length ?? v.length;
+                if (size + nodes + stack.length > maxNodes)
+                    return false;
+                bytes += 2 + size;
+                active.add(v);
+                stack.push({ value: v, depth: item.depth, exit: true });
+                if (names)
+                    for (const name of names) {
+                        if (!literal(name))
+                            return false;
+                        const descriptor = Object.getOwnPropertyDescriptor(v, name);
+                        if (!("value" in descriptor))
+                            return false;
+                        bytes++;
+                        stack.push({ value: descriptor.value, depth: item.depth + 1 });
+                    }
+                else
+                    for (let i = 0; i < size; i++)
+                        stack.push({ value: v[i], depth: item.depth + 1 });
+            }
+            else
+                return false;
+            if (bytes > maxBytes)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}