@zanii/certify 0.0.0-stage → 0.6.0

package/dist/nitro.js

@@ -0,0 +1,329 @@
+// spec/attestation-nitro.md: an AWS Nitro Enclaves attestation document verifier, injected as the
+// @zanii/attest platform verifier for platform `nitro`.
+import { createHash, verify, X509Certificate } from "node:crypto";
+import { nitroCertificatePathReasons } from "./nitro-x509.js";
+import { AWS_NITRO_GOV_ROOT_PEM } from "./nitro-roots.js";
+export { AWS_NITRO_GOV_ROOT_PEM, AWS_NITRO_GOV_ROOT_SHA256 } from "./nitro-roots.js";
+/**
+ * Section 2: the AWS Nitro Enclaves Root-G1 certificate, from
+ * https://aws-nitro-enclaves.amazonaws.com/AWS_NitroEnclaves_Root-G1.zip, whose SHA-256
+ * fingerprint AWS publishes at https://docs.aws.amazon.com/enclaves/latest/user/verify-root.html
+ * (CN=aws.nitro-enclaves, C=US, O=Amazon, OU=AWS, valid 2019-10-28 to 2049-10-28).
+ */
+export const AWS_NITRO_ROOT_PEM = `-----BEGIN CERTIFICATE-----
+MIICETCCAZagAwIBAgIRAPkxdWgbkK/hHUbMtOTn+FYwCgYIKoZIzj0EAwMwSTEL
+MAkGA1UEBhMCVVMxDzANBgNVBAoMBkFtYXpvbjEMMAoGA1UECwwDQVdTMRswGQYD
+VQQDDBJhd3Mubml0cm8tZW5jbGF2ZXMwHhcNMTkxMDI4MTMyODA1WhcNNDkxMDI4
+MTQyODA1WjBJMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGQW1hem9uMQwwCgYDVQQL
+DANBV1MxGzAZBgNVBAMMEmF3cy5uaXRyby1lbmNsYXZlczB2MBAGByqGSM49AgEG
+BSuBBAAiA2IABPwCVOumCMHzaHDimtqQvkY4MpJzbolL//Zy2YlES1BR5TSksfbb
+48C8WBoyt7F2Bw7eEtaaP+ohG2bnUs990d0JX28TcPQXCEPZ3BABIeTPYwEoCWZE
+h8l5YoQwTcU/9KNCMEAwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUkCW1DdkF
+R+eWw5b6cp3PmanfS5YwDgYDVR0PAQH/BAQDAgGGMAoGCCqGSM49BAMDA2kAMGYC
+MQCjfy+Rocm9Xue4YnwWmNJVA44fA0P5W2OpYow9OYCVRaEevL8uO1XYru5xtMPW
+rfMCMQCi85sWBbJwKKXdS6BptQFuZbT73o/gBh1qUxl/nNr12UO8Yfwr6wPLb+6N
+IwLz3/Y=
+-----END CERTIFICATE-----
+`;
+/** The fingerprint AWS publishes for the root (verify-root.html), as `X509Certificate.fingerprint256` writes it. */
+export const AWS_NITRO_ROOT_SHA256 = "64:1A:03:21:A3:E2:44:EF:E4:56:46:31:95:D6:06:31:7E:D7:CD:CC:3C:17:56:E0:98:93:F3:C6:8F:79:BB:5B";
+/** Explicit operator policy only. Never select a root from the quote's subject, bundle or request. */
+export function nitroRootForPartition(partition = "aws") {
+    if (partition === "aws")
+        return AWS_NITRO_ROOT_PEM;
+    if (partition === "aws-us-gov")
+        return AWS_NITRO_GOV_ROOT_PEM;
+    throw new Error("unsupported Nitro trust partition");
+}
+/** Section 5: default freshness window, and the allowed skew between the document and the attestation claim. */
+export const NITRO_MAX_AGE_SECONDS = 300;
+export const NITRO_MAX_SKEW_SECONDS = 300;
+const MAX_DEPTH = 8;
+function decodeCbor(b) {
+    let p = 0;
+    const need = (n) => {
+        if (n > b.length - p)
+            throw new Error("truncated CBOR");
+    };
+    const head = () => {
+        need(1);
+        const ib = b[p++];
+        const major = ib >> 5;
+        const ai = ib & 31;
+        if (ai < 24)
+            return [major, ai];
+        if (ai > 27)
+            throw new Error("unsupported CBOR length encoding");
+        const n = 1 << (ai - 24);
+        need(n);
+        let v = 0n;
+        for (let i = 0; i < n; i++)
+            v = (v << 8n) | BigInt(b[p++]);
+        if (v > BigInt(Number.MAX_SAFE_INTEGER))
+            throw new Error("CBOR integer too large");
+        return [major, Number(v)];
+    };
+    const item = (depth) => {
+        if (depth > MAX_DEPTH)
+            throw new Error("CBOR nested too deep");
+        const [major, v] = head();
+        switch (major) {
+            case 0:
+                return v;
+            case 1:
+                return -1 - v;
+            case 2:
+                need(v);
+                return b.subarray(p, (p += v));
+            case 3:
+                need(v);
+                return new TextDecoder("utf-8", { fatal: true }).decode(b.subarray(p, (p += v)));
+            case 4: {
+                need(v); // each item takes at least one byte
+                const out = [];
+                for (let i = 0; i < v; i++)
+                    out.push(item(depth + 1));
+                return out;
+            }
+            case 5: {
+                need(v * 2);
+                const out = new Map();
+                for (let i = 0; i < v; i++) {
+                    const k = item(depth + 1);
+                    if (typeof k !== "number" && typeof k !== "string")
+                        throw new Error("CBOR map key is not an integer or text");
+                    if (out.has(k))
+                        throw new Error("duplicate CBOR map key");
+                    out.set(k, item(depth + 1));
+                }
+                return out;
+            }
+            case 6:
+                if (depth !== 0 || v !== 18)
+                    throw new Error("unexpected CBOR tag");
+                return item(depth + 1);
+            default:
+                if (v === 20)
+                    return false;
+                if (v === 21)
+                    return true;
+                if (v === 22)
+                    return null;
+                throw new Error("unsupported CBOR simple value");
+        }
+    };
+    const out = item(0);
+    if (p !== b.length)
+        throw new Error("trailing bytes after CBOR");
+    return out;
+}
+const cborHead = (major, n) => {
+    if (n < 24)
+        return Uint8Array.of((major << 5) | n);
+    if (n < 0x100)
+        return Uint8Array.of((major << 5) | 24, n);
+    if (n < 0x10000)
+        return Uint8Array.of((major << 5) | 25, n >> 8, n & 255);
+    return Uint8Array.of((major << 5) | 26, n >>> 24, (n >> 16) & 255, (n >> 8) & 255, n & 255);
+};
+const cborBytes = (b) => Buffer.concat([cborHead(2, b.length), b]);
+/** RFC 9052 section 4.4: Sig_structure = ["Signature1", body_protected, external_aad (empty), payload]. */
+export function sigStructure(protectedBytes, payload) {
+    return Buffer.concat([cborHead(4, 4), cborHead(3, 10), Buffer.from("Signature1"), cborBytes(protectedBytes), cborBytes(new Uint8Array(0)), cborBytes(payload)]);
+}
+// ---- The attestation document (section 3).
+const isBytes = (v, min, max) => v instanceof Uint8Array && v.length >= min && v.length <= max;
+const hex = (b) => Buffer.from(b).toString("hex");
+function optionalBytes(m, key) {
+    const v = m.get(key);
+    if (v === undefined || v === null)
+        return null;
+    if (!isBytes(v, 0, 1024))
+        throw new Error(`${key} is not bytes of at most 1024`);
+    return v;
+}
+/** Sections 3 and 4: decode the COSE_Sign1 envelope and its attestation document; throws on any malformed part. */
+export function parseNitroDocument(bytes) {
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength < 1 || bytes.byteLength > 16384)
+        throw new Error("attestation document must contain 1 to 16384 bytes");
+    const cose = decodeCbor(bytes);
+    if (!Array.isArray(cose) || cose.length !== 4)
+        throw new Error("not a COSE_Sign1 array");
+    const [protectedBytes, unprotected, payload, signature] = cose;
+    if (!(protectedBytes instanceof Uint8Array) || !(unprotected instanceof Map) || !(payload instanceof Uint8Array) || !(signature instanceof Uint8Array))
+        throw new Error("COSE_Sign1 fields have the wrong types");
+    const header = decodeCbor(protectedBytes);
+    if (!(header instanceof Map) || header.get(1) !== -35)
+        throw new Error("protected header algorithm is not ES384 (-35)");
+    if (signature.length !== 96)
+        throw new Error("signature is not a 96-byte P-384 r||s");
+    const m = decodeCbor(payload);
+    if (!(m instanceof Map))
+        throw new Error("payload is not a CBOR map");
+    const moduleId = m.get("module_id");
+    if (typeof moduleId !== "string" || moduleId === "")
+        throw new Error("module_id missing");
+    if (m.get("digest") !== "SHA384")
+        throw new Error("digest is not SHA384");
+    const timestamp = m.get("timestamp");
+    if (typeof timestamp !== "number" || timestamp <= 0)
+        throw new Error("timestamp missing");
+    const rawPcrs = m.get("pcrs");
+    if (!(rawPcrs instanceof Map) || rawPcrs.size === 0)
+        throw new Error("pcrs missing");
+    const pcrs = {};
+    for (const [k, v] of rawPcrs) {
+        if (typeof k !== "number" || !Number.isInteger(k) || k < 0 || k > 31)
+            throw new Error("PCR index out of range");
+        if (!isBytes(v, 48, 48))
+            throw new Error(`PCR${k} is not a SHA-384 value`);
+        pcrs[k] = hex(v);
+    }
+    const certificate = m.get("certificate");
+    if (!isBytes(certificate, 1, 1024))
+        throw new Error("certificate missing");
+    const cabundle = m.get("cabundle");
+    if (!Array.isArray(cabundle) || cabundle.length === 0 || cabundle.length > 8 || !cabundle.every((c) => isBytes(c, 1, 1024)))
+        throw new Error("cabundle must contain 1 to 8 certificates of at most 1024 bytes");
+    return {
+        protectedBytes,
+        payload,
+        signature,
+        document: {
+            moduleId,
+            digest: "SHA384",
+            timestamp,
+            pcrs,
+            certificate,
+            cabundle: cabundle,
+            publicKey: optionalBytes(m, "public_key"),
+            userData: optionalBytes(m, "user_data"),
+            nonce: optionalBytes(m, "nonce"),
+        },
+    };
+}
+/** Section 4: cabundle[0] is the pinned root, each next certificate is issued by the one before, the leaf by the last. */
+function chainReasons(doc, root) {
+    let certs;
+    try {
+        certs = [...doc.cabundle, doc.certificate].map((bytes) => { const c = new X509Certificate(bytes); if (!c.raw.equals(Buffer.from(bytes)))
+            throw new Error("trailing certificate bytes"); return c; });
+    }
+    catch {
+        return ["a certificate in the chain does not parse"];
+    }
+    const reasons = [];
+    const at = doc.timestamp;
+    if (!certs[0].raw.equals(root.raw))
+        reasons.push("cabundle does not start with the trusted root");
+    certs.forEach((c, i) => {
+        if (!(c.validFromDate.getTime() <= at && at <= c.validToDate.getTime()))
+            reasons.push(`certificate ${i} is not valid at the document timestamp`);
+        if (i === 0)
+            return;
+        const issuer = certs[i - 1];
+        if (!issuer.ca)
+            reasons.push(`certificate ${i - 1} is not a CA`);
+        try {
+            if (!c.checkIssued(issuer))
+                reasons.push(`certificate ${i} is not issued by certificate ${i - 1}`);
+            else if (!c.verify(issuer.publicKey))
+                reasons.push(`certificate ${i} signature does not verify`);
+        }
+        catch {
+            reasons.push(`certificate ${i} signature does not verify`);
+        }
+    });
+    return [...reasons, ...nitroCertificatePathReasons(certs)];
+}
+/** Section 4 and 5: the document's envelope, signature, chain, freshness, nonce and PCRs. */
+export function verifyNitroDocument(bytes, opts = {}) {
+    let parsed;
+    try {
+        parsed = parseNitroDocument(bytes);
+    }
+    catch (error) {
+        return { ok: false, structural: false, quoteVerified: false, reasons: [`malformed attestation document: ${error.message}`], document: null };
+    }
+    const { document: doc } = parsed;
+    let root;
+    try {
+        if (opts.root !== undefined && !(opts.root instanceof X509Certificate) && (typeof opts.root !== "string" || Buffer.byteLength(opts.root) > 16384))
+            throw new Error();
+        root = opts.root instanceof X509Certificate ? opts.root : new X509Certificate(opts.root ?? AWS_NITRO_ROOT_PEM);
+    }
+    catch {
+        return { ok: false, structural: true, quoteVerified: false, reasons: ["trusted Nitro root certificate is invalid"], document: doc };
+    }
+    const reasons = chainReasons(doc, root);
+    let leafKey = null;
+    try {
+        leafKey = new X509Certificate(doc.certificate).publicKey;
+    }
+    catch {
+        // reported by chainReasons
+    }
+    const signed = leafKey !== null && leafKey.asymmetricKeyType === "ec" && leafKey.asymmetricKeyDetails?.namedCurve === "secp384r1" &&
+        verify("sha384", sigStructure(parsed.protectedBytes, parsed.payload), { key: leafKey, dsaEncoding: "ieee-p1363" }, parsed.signature);
+    if (!signed)
+        reasons.push("document signature does not verify with the leaf certificate's P-384 key");
+    const now = opts.now !== undefined ? Date.parse(opts.now) : Date.now();
+    // written as !(x <= limit) so an unparsable time (NaN) is refused, never passed
+    if (Number.isNaN(now))
+        reasons.push("now is not a timestamp");
+    else if (!(doc.timestamp <= now + NITRO_MAX_SKEW_SECONDS * 1000))
+        reasons.push("document timestamp is in the future");
+    else if (!(now - doc.timestamp <= (opts.maxAgeSeconds ?? NITRO_MAX_AGE_SECONDS) * 1000))
+        reasons.push("document is stale");
+    if (opts.nonce !== undefined) {
+        const want = typeof opts.nonce === "string" ? Buffer.from(opts.nonce, "utf8") : Buffer.from(opts.nonce);
+        if (doc.nonce === null || !want.equals(doc.nonce))
+            reasons.push("nonce does not match");
+    }
+    for (const [i, want] of Object.entries(opts.pcrs ?? {})) {
+        const got = doc.pcrs[Number(i)];
+        if (got === undefined)
+            reasons.push(`PCR${i} is missing`);
+        else if (got !== want.toLowerCase())
+            reasons.push(`PCR${i} does not match`);
+    }
+    const ok = reasons.length === 0;
+    return { ok, structural: true, quoteVerified: ok, reasons, document: doc };
+}
+/** The `measurement` a Nitro attestation claims: PCR0 (the enclave image), `sha384:<hex>`. */
+export const nitroMeasurement = (doc) => `sha384:${doc.pcrs[0] ?? ""}`;
+/**
+ * Section 6: a @zanii/attest QuoteVerifier for platform `nitro`. The Attestation carries only the
+ * quote's hash, so `quote` returns the raw document by `quoteHash` (from the deployer's upload or
+ * a store). It holds when the document hashes to `quoteHash`, verifies (section 5) with
+ * `nonce` = the attestation's nonce, its PCR0 is the claimed `measurement`, and its timestamp is
+ * within 300 seconds of `attestedAt`.
+ */
+export function nitroQuoteVerifier(opts) {
+    return async (a) => (await checkNitroAttestation(a, opts)).ok;
+}
+/** `nitroQuoteVerifier` with its reasons. */
+export async function checkNitroAttestation(a, opts) {
+    const fail = (reason) => ({ ok: false, structural: false, quoteVerified: false, reasons: [reason], document: null });
+    if (a.platform !== "nitro")
+        return fail("attestation platform is not nitro");
+    if (!a.quoteHash || !a.nonce)
+        return fail("attestation has no quote hash or nonce");
+    const bytes = await opts.quote(a.quoteHash);
+    if (!bytes)
+        return fail("no attestation document for this quote hash");
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength < 1 || bytes.byteLength > 16384)
+        return fail("attestation document must contain 1 to 16384 bytes");
+    if (`sha256:${createHash("sha256").update(bytes).digest("hex")}` !== a.quoteHash)
+        return fail("attestation document does not hash to quote_hash");
+    const { quote: _quote, now, ...rest } = opts;
+    const r = verifyNitroDocument(bytes, { ...rest, nonce: a.nonce, ...(now ? { now: now() } : {}) });
+    if (r.document) {
+        if (nitroMeasurement(r.document) !== a.measurement)
+            r.reasons.push("measurement is not the document's PCR0");
+        if (!(Math.abs(r.document.timestamp - Date.parse(a.attestedAt)) <= NITRO_MAX_SKEW_SECONDS * 1000))
+            r.reasons.push("attested_at is not the document timestamp");
+    }
+    const ok = r.reasons.length === 0;
+    return { ...r, ok, quoteVerified: ok };
+}

package/dist/normalization.d.ts

@@ -0,0 +1,8 @@
+export interface NormalizationPolicy {
+    v: 1;
+    type: "certify.text-normalization-policy";
+    algorithm: "nfkc-arabic-v1";
+    unicode: "16.0" | "17.0";
+}
+export declare const runtimeNormalizationVersion: () => string;
+export declare function normalizationPolicyReasons(policy: unknown): string[];

package/dist/normalization.js

@@ -0,0 +1,10 @@
+// Strict grading pins the runtime tables; legacy callers retain their original unversioned normalization.
+import { isObj } from "./shared.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+export const runtimeNormalizationVersion = () => process.versions.unicode?.split(".").slice(0, 2).join(".") ?? "unknown";
+export function normalizationPolicyReasons(policy) {
+    if (!withinVerificationBudget(policy, { maxBytes: 1024, maxNodes: 20, maxDepth: 2 }) || !isObj(policy) || Object.keys(policy).length !== 4 || policy.v !== 1 || policy.type !== "certify.text-normalization-policy" || policy.algorithm !== "nfkc-arabic-v1" || (policy.unicode !== "16.0" && policy.unicode !== "17.0"))
+        return ["invalid text normalization policy (v1)"];
+    const actual = runtimeNormalizationVersion();
+    return actual === policy.unicode ? [] : [`text normalization requires Unicode ${policy.unicode}; runtime has ${actual}; align runtimes before grading`];
+}

package/dist/pq.d.ts

@@ -0,0 +1,32 @@
+import { type PqBinding } from "@zanii/pq";
+export interface PqCosignature {
+    v: 1;
+    type: "certify.pq-signature";
+    /** The issuer's @zanii/pq binding of its ML-DSA-65 key to its did:key. */
+    binding: PqBinding;
+    /** `mldsa65:<hex>` over the canonical bytes of the object without `sig`. */
+    sig_pq: string;
+}
+/** The binding hash a certificate (`claim.pq_binding`) or status document (`pq_binding`) commits to. */
+export declare function pqCommitment(signed: unknown): string | null;
+/** A binding usable by `issuer`: both its signatures verify and it is for that DID. */
+export declare function checkPqBinding(binding: PqBinding, issuer: string): void;
+/**
+ * Co-sign a signed certificate or status document that commits to `binding`. The ML-DSA signature
+ * covers the bytes the Ed25519 `sig` already covers, so classical verifiers see no change.
+ */
+export declare function pqCosign(signed: {
+    issuer: string;
+    sig: string;
+}, binding: PqBinding, pqSecretKey: Uint8Array): Promise<PqCosignature>;
+/**
+ * certificate.md section 7a: what an issuer document's `require_pq` asks of a verifier:
+ * `required`, or `opted_out` when the caller explicitly allows no co-signature, else `not_required`.
+ * Given `issuedAt`, a certificate issued before the document's `require_pq_from` is `not_required`.
+ */
+export declare function pqPolicyOf(issuerDoc: unknown, allowNoPq?: boolean, issuedAt?: string): "required" | "opted_out" | "not_required";
+/** Both signatures verify over the same bytes, with the key of the binding the object commits to. */
+export declare function verifyPqCosignature(signed: unknown, cosig: unknown): {
+    ok: boolean;
+    reasons: string[];
+};

package/dist/pq.js

@@ -0,0 +1,69 @@
+// spec/certificate.md section 7, spec/status.md section 5: an optional ML-DSA-65 co-signature
+// (@zanii/pq) over the same bytes the Ed25519 signature covers, carried beside the object.
+import { bindingHash, dualSignAsync, verifyDual, verifyPqBinding } from "@zanii/pq";
+import { isIso, isObj, isSha, ms } from "./shared.js";
+/** The binding hash a certificate (`claim.pq_binding`) or status document (`pq_binding`) commits to. */
+export function pqCommitment(signed) {
+    if (!isObj(signed))
+        return null;
+    const v = signed.type === "credential" ? (isObj(signed.claim) ? signed.claim.pq_binding : null) : signed.pq_binding;
+    return isSha(v) ? v : null;
+}
+const unsignedOf = (signed) => {
+    const { sig: _omit, ...unsigned } = signed;
+    return unsigned;
+};
+/** A binding usable by `issuer`: both its signatures verify and it is for that DID. */
+export function checkPqBinding(binding, issuer) {
+    if (!verifyPqBinding(binding).ok)
+        throw new Error("pq binding does not verify");
+    if (binding.did !== issuer)
+        throw new Error("pq binding is not for the issuer");
+}
+/**
+ * Co-sign a signed certificate or status document that commits to `binding`. The ML-DSA signature
+ * covers the bytes the Ed25519 `sig` already covers, so classical verifiers see no change.
+ */
+export async function pqCosign(signed, binding, pqSecretKey) {
+    checkPqBinding(binding, signed.issuer);
+    if (pqCommitment(signed) !== bindingHash(binding))
+        throw new Error("the object does not commit to this pq binding");
+    if (!/^ed25519:[0-9a-f]{128}$/.test(String(signed.sig)))
+        throw new Error("the object is not signed");
+    // ponytail: dualSignAsync with the Ed25519 signature already made; the check below verifies both.
+    const ed = Buffer.from(signed.sig.slice(8), "hex");
+    const { sig_pq } = await dualSignAsync(unsignedOf(signed), async () => new Uint8Array(ed), pqSecretKey);
+    const out = { v: 1, type: "certify.pq-signature", binding, sig_pq };
+    if (!verifyPqCosignature(signed, out).ok)
+        throw new Error("pq co-signature does not verify");
+    return out;
+}
+/**
+ * certificate.md section 7a: what an issuer document's `require_pq` asks of a verifier:
+ * `required`, or `opted_out` when the caller explicitly allows no co-signature, else `not_required`.
+ * Given `issuedAt`, a certificate issued before the document's `require_pq_from` is `not_required`.
+ */
+export function pqPolicyOf(issuerDoc, allowNoPq = false, issuedAt) {
+    if (!isObj(issuerDoc) || issuerDoc.require_pq !== true)
+        return "not_required";
+    if (issuedAt !== undefined && isIso(issuerDoc.require_pq_from) && ms(issuedAt) < ms(issuerDoc.require_pq_from))
+        return "not_required";
+    return allowNoPq === true ? "opted_out" : "required";
+}
+/** Both signatures verify over the same bytes, with the key of the binding the object commits to. */
+export function verifyPqCosignature(signed, cosig) {
+    const no = (r) => ({ ok: false, reasons: [r] });
+    const committed = pqCommitment(signed);
+    if (!committed || !isObj(signed))
+        return no("the object does not commit to a post-quantum key");
+    if (!isObj(cosig) || cosig.v !== 1 || cosig.type !== "certify.pq-signature" || !isObj(cosig.binding))
+        return no("not a post-quantum co-signature (v1)");
+    const binding = cosig.binding;
+    if (bindingHash(binding) !== committed)
+        return no("post-quantum binding is not the one the object commits to");
+    const dual = verifyDual(unsignedOf(signed), String(signed.issuer), binding, {
+        sig_ed: String(signed.sig),
+        sig_pq: String(cosig.sig_pq),
+    });
+    return dual.ok ? { ok: true, reasons: [] } : no("post-quantum co-signature does not verify");
+}

package/dist/profile.d.ts

@@ -0,0 +1,15 @@
+import clauseMapSchema from "./schemas/clause-map.schema.json";
+import profileSchema from "./schemas/profile.schema.json";
+type Schema = {
+    [k: string]: unknown;
+};
+/** Section 4: the errors of `value` against `schema` (keywords in the section 4 list), sorted. */
+export declare function schemaErrors(value: unknown, schema: Schema): string[];
+export interface ProfileCheck {
+    ok: boolean;
+    errors: string[];
+}
+export declare function validateProfile(profile: unknown, clauseMaps?: readonly unknown[]): ProfileCheck;
+/** Section 3: a clause map is valid when it matches the schema and its clause ids are distinct. */
+export declare function validateClauseMap(map: unknown): ProfileCheck;
+export { clauseMapSchema, profileSchema };

package/dist/profile.js

@@ -0,0 +1,165 @@
+// spec/profiles.md: sector profiles and clause maps, checked against spec/schemas with a small
+// validator for the JSON Schema keywords those two schemas use (no dependency).
+import { canonicalBytes } from "@zanii/core";
+import clauseMapSchema from "./schemas/clause-map.schema.json" with { type: "json" };
+import profileSchema from "./schemas/profile.schema.json" with { type: "json" };
+import { isObj } from "./shared.js";
+import { schemaDialectErrors } from "./schema-dialect.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const typeOk = {
+    object: isObj,
+    array: Array.isArray,
+    string: (v) => typeof v === "string",
+    integer: (v) => Number.isInteger(v),
+    boolean: (v) => typeof v === "boolean",
+};
+/** Section 4: the errors of `value` against `schema` (keywords in the section 4 list), sorted. */
+export function schemaErrors(value, schema) {
+    const invalid = schemaDialectErrors(schema);
+    if (invalid.length)
+        return invalid;
+    if (!withinVerificationBudget(value))
+        return ["$: value exceeds the validation JSON budget"];
+    const root = schema;
+    const out = [];
+    let remaining = 1_000_000;
+    let tooManyErrors = false;
+    let tooDeep = false;
+    const error = (message) => { if (out.length < 1000)
+        out.push(message);
+    else
+        tooManyErrors = true; };
+    const walk = (v, s, path, depth = 0) => {
+        if (tooManyErrors || --remaining < 0)
+            return;
+        if (depth > 128) {
+            tooDeep = true;
+            return;
+        }
+        if (typeof s.$ref === "string") {
+            const name = s.$ref.replace("#/$defs/", "");
+            walk(v, root.$defs[name], path, depth + 1);
+            return;
+        }
+        if (Array.isArray(s.anyOf)) {
+            let matched = false;
+            for (const branch of s.anyOf) {
+                const start = out.length;
+                walk(v, branch, path, depth + 1);
+                if (out.length === start)
+                    matched = true;
+                out.length = start;
+                if (matched)
+                    break;
+            }
+            if (!matched)
+                error(`${path}: must match anyOf`);
+        }
+        const encoded = "const" in s || Array.isArray(s.enum) ? Buffer.from(canonicalBytes(v)) : null;
+        const equal = (expected) => encoded?.equals(Buffer.from(canonicalBytes(expected)));
+        if ("const" in s && !equal(s.const))
+            error(`${path}: must be ${JSON.stringify(s.const)}`);
+        if (Array.isArray(s.enum) && !s.enum.some(equal))
+            error(`${path}: must be one of ${JSON.stringify(s.enum)}`);
+        if (typeof s.type === "string" && !typeOk[s.type]?.(v)) {
+            error(`${path}: must be ${s.type}`);
+            return;
+        }
+        if (typeof v === "string") {
+            if (typeof s.minLength === "number" && v.length < s.minLength)
+                error(`${path}: shorter than ${s.minLength}`);
+            if (typeof s.maxLength === "number" && v.length > s.maxLength)
+                error(`${path}: longer than ${s.maxLength}`);
+            if (typeof s.pattern === "string" && !new RegExp(s.pattern).test(v))
+                error(`${path}: does not match ${s.pattern}`);
+        }
+        if (typeof v === "number") {
+            if (typeof s.minimum === "number" && v < s.minimum)
+                error(`${path}: below ${s.minimum}`);
+            if (typeof s.maximum === "number" && v > s.maximum)
+                error(`${path}: above ${s.maximum}`);
+        }
+        if (Array.isArray(v)) {
+            if (typeof s.minItems === "number" && v.length < s.minItems)
+                error(`${path}: fewer than ${s.minItems} items`);
+            if (typeof s.maxItems === "number" && v.length > s.maxItems)
+                error(`${path}: more than ${s.maxItems} items`);
+            if (s.uniqueItems === true && new Set(v.map((x) => Buffer.from(canonicalBytes(x)).toString())).size !== v.length)
+                error(`${path}: items are not unique`);
+            if (isObj(s.items))
+                v.forEach((x, i) => walk(x, s.items, `${path}[${i}]`, depth + 1));
+        }
+        if (isObj(v)) {
+            const props = isObj(s.properties) ? s.properties : {};
+            for (const k of Array.isArray(s.required) ? s.required : [])
+                if (!Object.hasOwn(v, k))
+                    error(`${path}: missing ${k}`);
+            for (const [k, x] of Object.entries(v)) {
+                if (Object.hasOwn(props, k) && isObj(props[k]))
+                    walk(x, props[k], `${path}.${k}`, depth + 1);
+                else if (s.additionalProperties === false)
+                    error(`${path}: unknown property ${k}`);
+            }
+        }
+    };
+    walk(value, schema, "$");
+    if (tooDeep)
+        return ["$: validation depth budget exceeded"];
+    if (remaining < 0)
+        return ["$: validation work budget exceeded"];
+    if (tooManyErrors)
+        return ["$: validation error budget exceeded"];
+    return out.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/**
+ * Section 2: a profile is valid when it matches the schema, its category ids are distinct, every
+ * category's required levels are levels the profile offers, and (when `clauseMaps` are given)
+ * every clause it cites exists in a clause map the profile lists.
+ */
+/** scheme.md section 2a: the scheme versions whose profiles may assess categories as multi-step workflows. */
+const TRAJECTORY_SCHEMES = ["zanii-certify/0.4"];
+export function validateProfile(profile, clauseMaps = []) {
+    const errors = schemaErrors(profile, profileSchema);
+    if (!errors.length) {
+        const p = profile;
+        if (p.levels.includes(3) && p.scheme === "zanii-certify/0.1")
+            errors.push("$.levels: level 3 needs scheme zanii-certify/0.2");
+        const seen = new Set();
+        for (const c of p.categories) {
+            if (seen.has(c.id))
+                errors.push(`$.categories: duplicate id ${c.id}`);
+            seen.add(c.id);
+            if (c.execution === "trajectory" && !TRAJECTORY_SCHEMES.includes(p.scheme))
+                errors.push(`$.categories.${c.id}: trajectory execution needs scheme zanii-certify/0.4`);
+            for (const l of c.required_levels)
+                if (!p.levels.includes(l))
+                    errors.push(`$.categories.${c.id}: level ${l} not in levels`);
+        }
+        if (clauseMaps.length) {
+            const known = new Set();
+            for (const m of clauseMaps) {
+                const map = m;
+                if (!p.clause_maps.includes(`${map.slug}/${map.version}`))
+                    continue;
+                for (const cl of map.clauses)
+                    known.add(`${map.slug}:${cl.id}`);
+            }
+            for (const c of p.categories)
+                for (const ref of c.clauses)
+                    if (!known.has(ref))
+                        errors.push(`$.categories.${c.id}: unknown clause ${ref}`);
+        }
+    }
+    return { ok: errors.length === 0, errors: errors.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)) };
+}
+/** Section 3: a clause map is valid when it matches the schema and its clause ids are distinct. */
+export function validateClauseMap(map) {
+    const errors = schemaErrors(map, clauseMapSchema);
+    if (!errors.length) {
+        const ids = map.clauses.map((c) => c.id);
+        if (new Set(ids).size !== ids.length)
+            errors.push("$.clauses: duplicate id");
+    }
+    return { ok: errors.length === 0, errors };
+}
+export { clauseMapSchema, profileSchema };