@zanii/certify 0.0.0-stage → 0.6.0

package/dist/verification-bounds.js

@@ -0,0 +1,78 @@
+// 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;
+        // Most evidence strings need no JSON escapes; scan those in native code once.
+        if (/[\u0000-\u001f"\\]/.test(s))
+            for (let i = 0; i < s.length; i++) {
+                const c = s.charCodeAt(i);
+                if (c === 34 || c === 92 || c === 8 || c === 9 || c === 10 || c === 12 || c === 13)
+                    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;
+    }
+}

package/dist/verification-policy.d.ts

@@ -0,0 +1,32 @@
+import type { Credential } from "@zanii/credentials";
+import type { SchemeLogsInput } from "./scheme-log.ts";
+export interface IssuerPolicy {
+    v: 1;
+    type: "certify.issuer-policy";
+    domain: string;
+    dids: string[];
+    status_dids: string[];
+    require_pq: boolean;
+    require_pq_from: string | null;
+    pq_bindings: string[];
+}
+export interface ReleaseVerificationPolicy {
+    owner: string;
+    boards: readonly unknown[];
+    releases: readonly unknown[];
+    withdrawals?: readonly unknown[];
+    rejectWithdrawn?: boolean;
+    profileSha256?: string;
+    schemeSha256?: string;
+    schemeLog?: SchemeLogsInput;
+}
+export declare function isIssuerPolicy(value: unknown): value is IssuerPolicy;
+export declare function issuerPolicyCheck(cert: Credential, document: unknown, policy: unknown, opts?: {
+    allowNoPq?: boolean;
+    status?: unknown;
+    revocationList?: unknown;
+}): {
+    reasons: string[];
+    requirePq: boolean;
+};
+export declare function releasePolicyReasons(cert: Credential, policy: ReleaseVerificationPolicy): string[];

package/dist/verification-policy.js

@@ -0,0 +1,85 @@
+// Optional relying-party policies. Downloaded trust metadata cannot replace these local pins.
+import { publicKeyFromDid } from "@zanii/core";
+import { bindingHash } from "@zanii/pq";
+import { requireRelease } from "./board.js";
+import { pqCommitment, pqPolicyOf } from "./pq.js";
+import { isIso, isObj, isSha } from "./shared.js";
+import { signingIdentityReasons } from "./signing-identity.js";
+const did = (v) => typeof v === "string" && v.length <= 69 && publicKeyFromDid(v) !== null;
+const hash = (v) => isSha(v) && v.length === 71;
+const unique = (v, min, valid) => Array.isArray(v) && v.length >= min && v.length <= 64 && Array.from(v).every(valid) && new Set(v).size === v.length;
+const equalSet = (a, b, valid) => unique(a, 0, valid) && a.length === b.length && a.every((x) => b.includes(x));
+const boundedBinding = (b) => isObj(b) && Object.keys(b).length === 8 && b.v === 1 && b.type === "pq.binding" && b.alg === "ML-DSA-65"
+    && did(b.did) && isIso(b.ts) && ["pq_pub", "sig_ed", "sig_pq"].every((key) => typeof b[key] === "string" && b[key].length <= 7000);
+export function isIssuerPolicy(value) {
+    if (!isObj(value) || Object.keys(value).length !== 8 || !["v", "type", "domain", "dids", "status_dids", "require_pq", "require_pq_from", "pq_bindings"].every((k) => Object.hasOwn(value, k)))
+        return false;
+    return value.v === 1 && value.type === "certify.issuer-policy" && typeof value.domain === "string" && value.domain.length <= 253
+        && /^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(value.domain) && value.domain.trim() === value.domain
+        && unique(value.dids, 1, did) && unique(value.status_dids, 1, did) && value.status_dids.every((d) => value.dids.includes(d))
+        && typeof value.require_pq === "boolean" && (value.require_pq_from === null || isIso(value.require_pq_from))
+        && (value.require_pq || value.require_pq_from === null) && unique(value.pq_bindings, value.require_pq ? 1 : 0, hash);
+}
+export function issuerPolicyCheck(cert, document, policy, opts = {}) {
+    const reasons = [], fail = (s) => reasons.push(`issuer policy: ${s}`);
+    if (!isIssuerPolicy(policy))
+        return { reasons: ["issuer policy: invalid pinned policy (v1)"], requirePq: true };
+    const requirePq = pqPolicyOf(policy, false, String(cert?.issued_at)) === "required";
+    if (cert?.issuer_domain !== policy.domain || !policy.dids.includes(cert?.issuer))
+        fail("certificate issuer is not pinned");
+    if (!isObj(document))
+        fail("issuer document is required");
+    else {
+        if (document.owner !== undefined)
+            reasons.push(...signingIdentityReasons(document.owner, document.dids ?? [], document.status_dids ?? []));
+        if (document.v !== 1 || document.domain !== policy.domain)
+            fail("issuer document domain does not match the pin");
+        if (!equalSet(document.dids, policy.dids, did) || !equalSet(document.status_dids, policy.status_dids, did))
+            fail("issuer keys changed or are missing; review and update the local policy for a rotation");
+        if (document.require_pq !== policy.require_pq || (document.require_pq_from ?? null) !== policy.require_pq_from)
+            fail("post-quantum requirement or cutover is missing or changed");
+        const bindings = document.pq_bindings;
+        if (!Array.isArray(bindings) || bindings.length > 64 || !Array.from(bindings).every(boundedBinding))
+            fail("post-quantum binding metadata is required");
+        else
+            try {
+                if (!equalSet(bindings.map((b) => bindingHash(b)), policy.pq_bindings, hash))
+                    fail("post-quantum bindings do not match the local pins");
+            }
+            catch {
+                fail("post-quantum binding metadata is invalid");
+            }
+    }
+    if (opts.allowNoPq)
+        fail("post-quantum opt-out is incompatible with a pinned policy");
+    if (requirePq && !policy.pq_bindings.includes(pqCommitment(cert) ?? ""))
+        fail("certificate post-quantum key is not pinned");
+    if (requirePq && opts.status !== undefined && !policy.pq_bindings.includes(pqCommitment(opts.status) ?? ""))
+        fail("status post-quantum key is not pinned");
+    if (isObj(opts.status) && !policy.status_dids.includes(String(opts.status.issuer)))
+        fail("status signer is not pinned");
+    if (isObj(opts.revocationList) && !policy.status_dids.includes(String(opts.revocationList.issuer)))
+        fail("revocation list signer is not pinned");
+    return { reasons, requirePq };
+}
+export function releasePolicyReasons(cert, policy) {
+    if (!isObj(policy) || !did(policy.owner) || !Array.isArray(policy.boards) || policy.boards.length > 10_000
+        || !Array.isArray(policy.releases) || policy.releases.length > 10_000 || !isIso(cert?.issued_at)
+        || Object.keys(policy).some((k) => !["owner", "boards", "releases", "withdrawals", "rejectWithdrawn", "profileSha256", "schemeSha256", "schemeLog"].includes(k))
+        || (policy.rejectWithdrawn !== undefined && typeof policy.rejectWithdrawn !== "boolean")
+        || (policy.schemeLog !== undefined && !isObj(policy.schemeLog))
+        || (policy.withdrawals !== undefined && (!Array.isArray(policy.withdrawals) || policy.withdrawals.length > 10_000))
+        || (policy.rejectWithdrawn === true && policy.withdrawals === undefined)
+        || (policy.profileSha256 !== undefined && !hash(policy.profileSha256)) || (policy.schemeSha256 !== undefined && !hash(policy.schemeSha256)))
+        return ["release policy: invalid policy or missing trusted logs"];
+    const claim = isObj(cert.claim) ? cert.claim : {};
+    const reasons = [];
+    for (const [kind, ref, digest] of [["profile", claim.profile, policy.profileSha256], ["scheme", claim.scheme, policy.schemeSha256]]) {
+        const checked = requireRelease(policy.releases, policy.boards, { kind, ref: String(ref) }, cert.issued_at, {
+            owner: policy.owner, ...(digest ? { sha256: digest } : {}), ...(policy.rejectWithdrawn ? { withdrawals: policy.withdrawals } : {}),
+            ...(policy.schemeLog ? { schemeLog: policy.schemeLog } : {}),
+        });
+        reasons.push(...checked.reasons.map((r) => `release policy: ${r}`));
+    }
+    return [...new Set(reasons)];
+}

package/dist/witness.d.ts

@@ -0,0 +1,19 @@
+import { type SignedTreeHead } from "@zanii/core";
+import { type Signer } from "./signer.ts";
+import { type StatusDocument, type StatusWitness } from "./status.ts";
+/** Section 1: the documents form one log: each signed by one issuer, at its index, naming its predecessor. */
+export declare function verifyStatusLog(docs: readonly unknown[]): {
+    ok: boolean;
+    reasons: string[];
+};
+/** Section 2: the issuer's signed tree head over the whole log (leaf i = document i). */
+export declare function statusCheckpoint(docs: readonly StatusDocument[], ts: string, signer: Signer): Promise<SignedTreeHead>;
+/** Section 2: the inclusion proof of document `index` in the checkpoint over `docs`, hex. */
+export declare const statusInclusionProof: (docs: readonly StatusDocument[], index: number) => string[];
+/** Section 2: the proof that the log over `docs` extends its first `fromSize` documents, hex. */
+export declare const statusConsistencyProof: (docs: readonly StatusDocument[], fromSize: number) => string[];
+/** Section 3: the reasons a status document is not in a checkpoint co-signed by `k` trusted witnesses. */
+export declare function witnessReasons(doc: Record<string, unknown>, w: StatusWitness): {
+    reasons: string[];
+    witnesses: string[];
+};

package/dist/witness.js

@@ -0,0 +1,80 @@
+// spec/witness.md: the status log. Every status document names the previous one (`seq`, `prev`);
+// the issuer checkpoints the log as a Merkle tree head, and partner witnesses (@zanii/witness)
+// check it is append-only and co-sign it.
+import { canonicalBytes, consistencyProof, createSTHAsync, inclusionProof, jcsHash, leafHash, merkleRoot, verifyInclusion, verifySignedObject, verifySTH, } from "@zanii/core";
+import { verifyQuorum } from "@zanii/witness";
+import { isInt, isIso, isObj, isSha, ms } from "./shared.js";
+import { signerDid } from "./signer.js";
+import { verifyStatus } from "./status.js";
+const HEX32 = /^[0-9a-f]{64}$/;
+const hex = (b) => Buffer.from(b).toString("hex");
+const bytes = (h) => new Uint8Array(Buffer.from(h, "hex"));
+const leaves = (docs) => docs.map((d) => leafHash(canonicalBytes(d)));
+/** Section 1: the documents form one log: each signed by one issuer, at its index, naming its predecessor. */
+export function verifyStatusLog(docs) {
+    const reasons = [];
+    if (!Array.isArray(docs) || docs.length === 0)
+        return { ok: false, reasons: ["the status log is empty"] };
+    docs.forEach((d, i) => {
+        const prev = i > 0 ? docs[i - 1] : null;
+        if (!isObj(d) || (d.v !== 1 && d.v !== 2) || d.type !== "certify.status" || (d.v === 2 ? !verifyStatus(d, { issuer: String(d.issuer), now: String(d.issued_at) }).ok : !verifySignedObject(d)) || d.signer !== d.issuer) {
+            reasons.push(`document ${i} is not a signed status document`);
+            return;
+        }
+        if (i > 0 && (!isObj(prev) || prev.issuer !== d.issuer))
+            reasons.push(`document ${i} is from a different issuer`);
+        if (d.seq !== i)
+            reasons.push(`document ${i} is not at position ${i}`);
+        if (d.prev !== (i > 0 && isObj(prev) ? jcsHash(prev) : null))
+            reasons.push(`document ${i} does not name the previous document`);
+        if (i > 0 && isObj(prev) && !(ms(d.issued_at) >= ms(prev.issued_at)))
+            reasons.push(`document ${i} is older than the previous document`);
+    });
+    return { ok: reasons.length === 0, reasons };
+}
+/** Section 2: the issuer's signed tree head over the whole log (leaf i = document i). */
+export async function statusCheckpoint(docs, ts, signer) {
+    const check = verifyStatusLog(docs);
+    if (!check.ok)
+        throw new Error(check.reasons[0]);
+    if (docs[0].issuer !== signerDid(signer))
+        throw new Error("signer is not the status log issuer");
+    if (!isIso(ts) || ms(ts) < ms(docs.at(-1).issued_at))
+        throw new Error("ts must be an ISO UTC timestamp, not before the last document");
+    const root = `sha256:${hex(merkleRoot(leaves(docs)))}`;
+    return createSTHAsync({ logId: signerDid(signer), size: docs.length, root, ts }, signer.sign);
+}
+/** Section 2: the inclusion proof of document `index` in the checkpoint over `docs`, hex. */
+export const statusInclusionProof = (docs, index) => inclusionProof(index, leaves(docs)).map(hex);
+/** Section 2: the proof that the log over `docs` extends its first `fromSize` documents, hex. */
+export const statusConsistencyProof = (docs, fromSize) => consistencyProof(fromSize, leaves(docs)).map(hex);
+const cosigShape = (c) => isObj(c) && typeof c.witnessed_log_id === "string" && isObj(c.cosignature) && typeof c.cosignature.log_id === "string";
+/** Section 3: the reasons a status document is not in a checkpoint co-signed by `k` trusted witnesses. */
+export function witnessReasons(doc, w) {
+    const reasons = [];
+    const cp = isObj(w?.checkpoint) ? w.checkpoint : null;
+    if (!isInt(doc.seq, 0, Number.MAX_SAFE_INTEGER))
+        reasons.push("status document is not in a status log");
+    if (!cp || cp.log_id !== doc.issuer || !verifySTH(cp)) {
+        reasons.push("status checkpoint is not signed by the issuer");
+        return { reasons, witnesses: [] };
+    }
+    const proof = Array.isArray(w.proof) ? w.proof : [];
+    const included = isInt(doc.seq, 0, Number.MAX_SAFE_INTEGER) &&
+        doc.seq < cp.size &&
+        isSha(cp.root) &&
+        proof.every((h) => typeof h === "string" && HEX32.test(h)) &&
+        verifyInclusion(leafHash(canonicalBytes(doc)), doc.seq, cp.size, proof.map(bytes), bytes(cp.root.slice(7)));
+    if (!included)
+        reasons.push("status document is not in the checkpoint");
+    if (!isInt(w.k, 1, 1000)) {
+        reasons.push("witness policy k must be an integer from 1");
+        return { reasons, witnesses: [] };
+    }
+    const trusted = Array.isArray(w.trusted) ? w.trusted : [];
+    const cosigs = Array.isArray(w.cosignatures) ? w.cosignatures.filter(cosigShape) : [];
+    const q = verifyQuorum(cp, cosigs, { trusted, k: w.k });
+    if (!q.ok)
+        reasons.push(`status checkpoint has ${q.witnesses.length} of the ${w.k} trusted witness co-signatures required`);
+    return { reasons, witnesses: q.witnesses };
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@zanii/certify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0",
+  "description": "Build and verify Zanii Certify certificates for AI agents: fingerprints, signed certificates, status documents, test suites and the certify command.",
+  "license": "Apache-2.0",
+  "homepage": "https://zanii.agency",
+  "author": "Zanii <info@zanii.agency>",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "certify": "./src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "bin": {
+      "certify": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test \"src/**/*.test.ts\"",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@scure/base": "1.2.6",
+    "@zanii/attest": "0.1.3",
+    "@zanii/blackbox": "0.23.0",
+    "@zanii/core": "^0.5.6",
+    "@zanii/credentials": "^0.1.2",
+    "@zanii/insurance": "0.1.3",
+    "@zanii/kyb": "0.1.2",
+    "@zanii/pq": "0.2.2",
+    "@zanii/redact": "0.1.3",
+    "@zanii/succession": "0.1.2",
+    "@zanii/vc": "0.1.2",
+    "@zanii/witness": "0.1.5"
+  },
+  "devDependencies": {
+    "@zanii/swarm": "0.2.3"
+  },
+  "keywords": [
+    "ai-agents",
+    "certification",
+    "verifiable-credentials",
+    "ai-assurance",
+    "ed25519",
+    "post-quantum",
+    "arabic",
+    "zanii"
+  ]
+}