@zanii/certify 0.0.0-stage → 0.5.0

package/dist/live-evidence.js

@@ -0,0 +1,210 @@
+// spec/live-evidence.md: signed periodic production metrics for a certified agent, from the
+// deployer's Blackbox gateway identity, in Blackbox's signed form (`signed: {by, sig}`).
+import { signCertificateWith, verifyCertificate as verifyBlackboxSigned } from "@zanii/blackbox";
+import { verifySignedObject } from "@zanii/core";
+import { credentialHash } from "@zanii/credentials";
+import { MAX_SKEW_SECONDS } from "./beacon.js";
+import { isDid, isInt, isIso, isObj, isSha, ms, sortedUnique } from "./shared.js";
+import { signerDid, signWith } from "./signer.js";
+import { verifyAssuranceStatus } from "./assurance-status.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const COUNT_MAX = 1_000_000_000;
+const CONFIGURATION = /^[A-Za-z0-9_.:-]{1,128}$/;
+const count = (v) => isInt(v, 0, COUNT_MAX);
+const counts = (o, keys) => isObj(o) && Object.keys(o).length === keys.length && keys.every((k) => count(o[k]));
+/** Section 1's field rules; the first broken rule, or null. */
+function fieldError(e) {
+    const w = isObj(e.window) ? e.window : {};
+    if (!isSha(e.certificate))
+        return "certificate must be a certificate hash";
+    if (!isDid(e.agent))
+        return "agent must be a did:key";
+    if (!isObj(e.window) || Object.keys(w).length !== 2 || !isIso(w.from) || !isIso(w.to) || !(ms(w.from) < ms(w.to)))
+        return "window needs ISO UTC from and to, from before to";
+    if (!isIso(e.issued_at) || ms(e.issued_at) < ms(w.to))
+        return "issued_at must be an ISO UTC timestamp, not before window.to";
+    if (![e.sessions, e.guard_blocks, e.budget_breaches, e.near_misses].every(count))
+        return "counts must be integers 0-1000000000";
+    if (!counts(e.claims, ["satisfied", "failed", "unverified"]))
+        return "claims needs satisfied, failed and unverified counts";
+    if (!counts(e.findings, ["advisory", "caution", "warning"]))
+        return "findings needs advisory, caution and warning counts";
+    if (!counts(e.incidents, ["serious", "minor"]))
+        return "incidents needs serious and minor counts";
+    const c = e.configurations;
+    if (!Array.isArray(c) || c.length > 100 || !c.every((x) => typeof x === "string" && CONFIGURATION.test(x)) || sortedUnique(c).join("\n") !== c.join("\n"))
+        return "configurations must be at most 100 sorted, distinct configuration ids";
+    return null;
+}
+/** Sign live evidence as the deployer's Blackbox gateway (`signer` holds the gateway key). */
+export async function buildLiveEvidence(fields, signer) {
+    const unsigned = {
+        v: 1,
+        type: "certify.live-evidence",
+        certificate: fields.certificate,
+        agent: fields.agent,
+        window: fields.window,
+        sessions: fields.sessions,
+        guard_blocks: fields.guard_blocks,
+        claims: fields.claims,
+        budget_breaches: fields.budget_breaches,
+        findings: fields.findings,
+        incidents: fields.incidents,
+        near_misses: fields.near_misses,
+        configurations: Array.isArray(fields.configurations) ? sortedUnique(fields.configurations) : fields.configurations,
+        issued_at: fields.issuedAt,
+    };
+    const err = fieldError(unsigned);
+    if (err)
+        throw new Error(err);
+    return signCertificateWith(unsigned, signerDid(signer), signer.sign);
+}
+// ---------------------------------------------------------------- 4. gateway enrolment
+const PLATFORM = /^[a-z0-9][a-z0-9-]{0,31}$/;
+function enrolmentError(g) {
+    if (!isSha(g.certificate))
+        return "certificate must be a certificate hash";
+    if (!isDid(g.gateway))
+        return "gateway must be a did:key";
+    const a = g.attestation;
+    if (a !== null && (!isObj(a) || Object.keys(a).length !== 3 || typeof a.platform !== "string" || !PLATFORM.test(a.platform) || !isSha(a.document) || !isIso(a.verified_at)))
+        return "attestation is null or {platform, document: sha256, verified_at}";
+    if (!isIso(g.issued_at) || !isIso(g.valid_until) || !(ms(g.valid_until) > ms(g.issued_at)))
+        return "issued_at and valid_until must be ISO timestamps, valid_until after issued_at";
+    if (isObj(a) && ms(a.verified_at) > ms(g.issued_at))
+        return "the attestation is verified after the enrolment is issued";
+    return null;
+}
+/** Section 4: the lab enrols the deployer's gateway key for one certificate (`signer` is the lab key). */
+export async function buildGatewayEnrolment(f, signer) {
+    const a = f.attestation ?? null;
+    const unsigned = {
+        v: 1,
+        type: "certify.gateway-enrolment",
+        certificate: f.certificate,
+        gateway: f.gateway,
+        attestation: a === null ? null : { platform: a.platform, document: a.document, verified_at: a.verified_at },
+        issued_at: f.issuedAt,
+        valid_until: f.validUntil,
+    };
+    const err = enrolmentError(unsigned);
+    if (err)
+        throw new Error(err);
+    return signWith(unsigned, signer);
+}
+/** Section 4: signed by a trusted lab (`labs`), well formed and (with `at`) in force at that time. */
+export function verifyGatewayEnrolment(doc, opts = {}) {
+    const g = isObj(doc) ? doc : {};
+    if (g.v !== 1 || g.type !== "certify.gateway-enrolment" || Object.keys(g).length !== 9)
+        return { ok: false, reasons: ["not a gateway enrolment (v1)"] };
+    const reasons = [];
+    if (!verifySignedObject(g))
+        reasons.push("bad gateway enrolment signature");
+    const err = enrolmentError(g);
+    if (err)
+        reasons.push(`gateway enrolment is malformed: ${err}`);
+    if (!opts.labs)
+        reasons.push("no trusted labs supplied: the enrolment signer was NOT checked");
+    else if (!opts.labs.includes(g.signer))
+        reasons.push("gateway enrolment is not signed by a trusted lab");
+    if (opts.at !== undefined && !(ms(g.issued_at) <= ms(opts.at) && ms(opts.at) <= ms(g.valid_until)))
+        reasons.push("gateway enrolment is not in force at the evidence time");
+    return { ok: reasons.length === 0, reasons };
+}
+/** Pure acceptance gate; persist a new report watermark atomically with the accepted report. */
+export function liveEvidenceFreshnessReasons(evidence, opts) {
+    if (!isObj(opts) || !isIso(opts.now) || !isIso(opts.after) || !isInt(opts.maxEvidenceAgeSeconds, 1, 300) || ms(opts.after) > ms(opts.now))
+        return ["strict gateway evidence needs a retained report watermark and bounded freshness policy"];
+    if (!withinVerificationBudget(evidence, { maxBytes: 65_536, maxNodes: 1000, maxDepth: 8 }))
+        return ["strict gateway evidence exceeds its JSON budget or has an invalid status policy"];
+    const e = isObj(evidence) ? evidence : {}, now = ms(opts.now);
+    return !isIso(e.issued_at) || !isObj(e.window) || !isIso(e.window.to) || ms(e.issued_at) <= ms(opts.after) || now - ms(e.issued_at) >= opts.maxEvidenceAgeSeconds * 1000 || now - ms(e.window.to) >= opts.maxEvidenceAgeSeconds * 1000 || ms(e.issued_at) > now + 5_000
+        ? ["live evidence is stale, replayed or from the future"] : [];
+}
+/**
+ * Verify live evidence: Blackbox signed form by `gateway` (the deployer's registered gateway
+ * DID), well formed, not from the future, and (with `certificate`) for that certificate and holder.
+ * With `enrolment` or `requireEnrolment` (section 4), also an enrolment of the signing gateway for
+ * the evidence's certificate in force at its `issued_at`; `attested` says whether that gateway is.
+ */
+export function verifyLiveEvidence(evidence, opts = {}) {
+    const enrolled = opts.enrolment !== undefined || opts.requireEnrolment === true || opts.gatewayStatus !== undefined;
+    if (opts.gatewayStatus !== undefined && (!withinVerificationBudget({ evidence, opts }, { maxBytes: 4_194_304 }) || !isObj(opts.gatewayStatus)))
+        return { ok: false, reasons: ["strict gateway evidence exceeds its JSON budget or has an invalid status policy"], attested: false };
+    const e = isObj(evidence) ? evidence : {};
+    if (e.v !== 1 || e.type !== "certify.live-evidence" || Object.keys(e).length !== 15)
+        return { ok: false, reasons: ["not live evidence (v1)"], ...(enrolled ? { attested: false } : {}) };
+    const reasons = [];
+    const g = isObj(opts.enrolment) ? opts.enrolment : null;
+    const gateway = opts.gateway ?? (g && isDid(g.gateway) ? g.gateway : undefined);
+    const sig = verifyBlackboxSigned(e, gateway);
+    if (!sig.ok)
+        reasons.push(sig.reason === "wrong_signer" ? "live evidence is not signed by the expected gateway" : "bad live evidence signature");
+    if (!gateway)
+        reasons.push("no gateway identity supplied: the signer was NOT checked");
+    const err = fieldError(e);
+    if (err)
+        reasons.push(`live evidence is malformed: ${err}`);
+    const now = opts.now ? ms(opts.now) : Date.now();
+    const policy = opts.gatewayStatus;
+    if (policy !== undefined) {
+        reasons.push(...liveEvidenceFreshnessReasons(evidence, { after: policy.after, maxEvidenceAgeSeconds: policy.maxEvidenceAgeSeconds, now: opts.now ?? new Date(now).toISOString() }));
+        reasons.push(...verifyAssuranceStatus(policy.document, { ...policy, purpose: "gateway-enrolment", artifact: opts.enrolment, now: opts.now ?? new Date(now).toISOString() }).reasons);
+    }
+    if (ms(e.issued_at) > now + MAX_SKEW_SECONDS * 1000)
+        reasons.push("live evidence issued_at is in the future");
+    if (opts.certificate) {
+        if (e.certificate !== credentialHash(opts.certificate))
+            reasons.push("live evidence names a different certificate");
+        if (e.agent !== opts.certificate.holder)
+            reasons.push("live evidence agent is not the certificate holder");
+    }
+    if (!enrolled)
+        return { ok: reasons.length === 0, reasons };
+    if (opts.enrolment === undefined) {
+        reasons.push("no gateway enrolment supplied: live evidence is accepted only from an enrolled gateway");
+        return { ok: false, reasons, attested: false };
+    }
+    reasons.push(...verifyGatewayEnrolment(opts.enrolment, { ...(opts.labs ? { labs: opts.labs } : {}), at: String(e.issued_at) }).reasons);
+    if (g && isObj(e.signed) && g.gateway !== e.signed.by)
+        reasons.push("live evidence is not signed by the enrolled gateway");
+    if (g && g.certificate !== e.certificate)
+        reasons.push("the gateway enrolment is for a different certificate");
+    const ok = reasons.length === 0;
+    return { ok, reasons, attested: ok && g !== null && g.attestation !== null };
+}
+export const LIVE_TRIGGERS = [
+    "SERIOUS_INCIDENT",
+    "GUARD_BLOCKS",
+    "CONTRADICTED_CLAIMS",
+    "BUDGET_BREACHES",
+    "CONFIGURATION_CHANGED",
+];
+/** Section 3: used for every threshold a profile's `live_evidence` does not set. */
+export const LIVE_DEFAULTS = {
+    max_guard_block_ppm: 10_000,
+    max_contradicted_claim_ppm: 10_000,
+    max_budget_breaches: 0,
+};
+/**
+ * Section 3: the re-test reasons in verified live evidence, in LIVE_TRIGGERS order; empty when none.
+ * Integer comparisons only (`a * 1e6 > max * b` rather than a division).
+ */
+export function liveEvidenceTriggers(evidence, profile, certificate) {
+    const t = { ...LIVE_DEFAULTS, ...(isObj(profile?.live_evidence) ? profile.live_evidence : {}) };
+    const e = evidence;
+    const checked = e.claims.satisfied + e.claims.failed;
+    const out = [];
+    if (e.incidents.serious > 0)
+        out.push("SERIOUS_INCIDENT");
+    if (e.sessions > 0 && e.guard_blocks * 1_000_000 > t.max_guard_block_ppm * e.sessions)
+        out.push("GUARD_BLOCKS");
+    if (checked > 0 && e.claims.failed * 1_000_000 > t.max_contradicted_claim_ppm * checked)
+        out.push("CONTRADICTED_CLAIMS");
+    if (e.budget_breaches > t.max_budget_breaches)
+        out.push("BUDGET_BREACHES");
+    const configuration = isObj(certificate?.claim) ? certificate.claim.configuration : undefined;
+    if (certificate && e.configurations.some((c) => c !== configuration))
+        out.push("CONFIGURATION_CHANGED");
+    return out;
+}

package/dist/nitro-roots.d.ts

@@ -0,0 +1,3 @@
+export declare const AWS_NITRO_GOV_ROOT_PEM = "-----BEGIN CERTIFICATE-----\nMIICIDCCAaWgAwIBAgIQP+wUYfyWFFRko9PR00zhZzAKBggqhkjOPQQDAzBQMQsw\nCQYDVQQGEwJVUzEPMA0GA1UECgwGQW1hem9uMQwwCgYDVQQLDANBV1MxIjAgBgNV\nBAMMGWF3cy11cy1nb3Yubml0cm8tZW5jbGF2ZXMwIBcNMjAwOTEwMTIwMzQ2WhgP\nMjA1MDA5MTAxMzAzNDZaMFAxCzAJBgNVBAYTAlVTMQ8wDQYDVQQKDAZBbWF6b24x\nDDAKBgNVBAsMA0FXUzEiMCAGA1UEAwwZYXdzLXVzLWdvdi5uaXRyby1lbmNsYXZl\nczB2MBAGByqGSM49AgEGBSuBBAAiA2IABCzkRJcZVx7Sg2yXXkl0Nqj9o1ECZNAh\n0L8/90ATZXAaS1rxA1ti1F3wE86PGsh2UiQIYXiMu81l5kO7775gPuLsgYcGMO/J\n0t08BHI8s3+JmjxTlA+/UyAqEmj7fD5CbKNCMEAwDwYDVR0TAQH/BAUwAwEB/zAd\nBgNVHQ4EFgQUUKIzFk2FAlhihuQexsqOxZ5ZjF0wDgYDVR0PAQH/BAQDAgGGMAoG\nCCqGSM49BAMDA2kAMGYCMQD9bO9epcf5kMSdsHcyNJXs4bo07wvTIOwnxN41t5eE\nSDyXtUei++RebAbI9Viap2gCMQC7PVZ6Kpg0+N9k+DDpksoJv7gx6YwCqKsmTfU/\nWigyQlpyJUrWapqk0afDA4lef14=\n-----END CERTIFICATE-----\n";
+/** SHA-256 of the exact DER bytes independently copied from the official GovCloud page above. */
+export declare const AWS_NITRO_GOV_ROOT_SHA256 = "20:BC:D3:0A:3E:16:8E:A0:37:89:E1:C4:59:12:BC:12:3C:4D:E3:C9:77:B8:A6:E1:C1:25:C7:92:9D:66:8B:3B";

package/dist/nitro-roots.js

@@ -0,0 +1,20 @@
+// Official AWS GovCloud HTML certificate (not PDF OCR), retrieved 2026-10-24:
+// https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-ec2.html
+// Root selection is trusted configuration; an attestation document never chooses its trust anchor.
+export const AWS_NITRO_GOV_ROOT_PEM = `-----BEGIN CERTIFICATE-----
+MIICIDCCAaWgAwIBAgIQP+wUYfyWFFRko9PR00zhZzAKBggqhkjOPQQDAzBQMQsw
+CQYDVQQGEwJVUzEPMA0GA1UECgwGQW1hem9uMQwwCgYDVQQLDANBV1MxIjAgBgNV
+BAMMGWF3cy11cy1nb3Yubml0cm8tZW5jbGF2ZXMwIBcNMjAwOTEwMTIwMzQ2WhgP
+MjA1MDA5MTAxMzAzNDZaMFAxCzAJBgNVBAYTAlVTMQ8wDQYDVQQKDAZBbWF6b24x
+DDAKBgNVBAsMA0FXUzEiMCAGA1UEAwwZYXdzLXVzLWdvdi5uaXRyby1lbmNsYXZl
+czB2MBAGByqGSM49AgEGBSuBBAAiA2IABCzkRJcZVx7Sg2yXXkl0Nqj9o1ECZNAh
+0L8/90ATZXAaS1rxA1ti1F3wE86PGsh2UiQIYXiMu81l5kO7775gPuLsgYcGMO/J
+0t08BHI8s3+JmjxTlA+/UyAqEmj7fD5CbKNCMEAwDwYDVR0TAQH/BAUwAwEB/zAd
+BgNVHQ4EFgQUUKIzFk2FAlhihuQexsqOxZ5ZjF0wDgYDVR0PAQH/BAQDAgGGMAoG
+CCqGSM49BAMDA2kAMGYCMQD9bO9epcf5kMSdsHcyNJXs4bo07wvTIOwnxN41t5eE
+SDyXtUei++RebAbI9Viap2gCMQC7PVZ6Kpg0+N9k+DDpksoJv7gx6YwCqKsmTfU/
+WigyQlpyJUrWapqk0afDA4lef14=
+-----END CERTIFICATE-----
+`;
+/** SHA-256 of the exact DER bytes independently copied from the official GovCloud page above. */
+export const AWS_NITRO_GOV_ROOT_SHA256 = "20:BC:D3:0A:3E:16:8E:A0:37:89:E1:C4:59:12:BC:12:3C:4D:E3:C9:77:B8:A6:E1:C1:25:C7:92:9D:66:8B:3B";

package/dist/nitro-x509.d.ts

@@ -0,0 +1,16 @@
+import type { X509Certificate } from "node:crypto";
+type Constraints = {
+    ca: boolean;
+    pathLen?: number;
+    critical: boolean;
+};
+type Usage = {
+    signature: boolean;
+    certificates: boolean;
+};
+export declare function nitroCertificateConstraints(cert: X509Certificate): {
+    basic: Constraints | null;
+    usage: Usage | null;
+};
+export declare function nitroCertificatePathReasons(certs: X509Certificate[]): string[];
+export {};

package/dist/nitro-x509.js

@@ -0,0 +1,141 @@
+export function nitroCertificateConstraints(cert) {
+    const bytes = cert.raw;
+    if (bytes.length < 1 || bytes.length > 1024)
+        throw new Error("certificate exceeds its 1024-byte bound");
+    let nodes = 0;
+    function parts(start, end, depth) {
+        if (depth > 8 || start < 0 || end > bytes.length || start > end)
+            throw new Error("invalid DER bounds");
+        const out = [];
+        let cursor = start;
+        while (cursor < end) {
+            if (++nodes > 256 || end - cursor < 2)
+                throw new Error("invalid DER node budget");
+            const tag = bytes[cursor++], first = bytes[cursor++];
+            if ((tag & 31) === 31)
+                throw new Error("unsupported DER tag");
+            let size = first;
+            if (first & 128) {
+                const n = first & 127;
+                if (!n || n > 2 || n > end - cursor || bytes[cursor] === 0)
+                    throw new Error("invalid DER length");
+                size = 0;
+                for (let i = 0; i < n; i++)
+                    size = size * 256 + bytes[cursor++];
+                if (size < 128)
+                    throw new Error("non-minimal DER length");
+            }
+            if (size > end - cursor)
+                throw new Error("truncated DER value");
+            out.push({ tag, start: cursor, end: cursor + size });
+            cursor += size;
+        }
+        return out;
+    }
+    function children(part, tag, depth) {
+        if (part.tag !== tag)
+            throw new Error("invalid DER structure");
+        return parts(part.start, part.end, depth);
+    }
+    function content(part, tag) { if (part.tag !== tag)
+        throw new Error("invalid DER field"); return bytes.subarray(part.start, part.end); }
+    function boolean(part) { const b = content(part, 1); if (b.length !== 1 || b[0] !== 0 && b[0] !== 255)
+        throw new Error("invalid DER boolean"); return b[0] === 255; }
+    const outer = parts(0, bytes.length, 0);
+    if (outer.length !== 1)
+        throw new Error("invalid DER certificate");
+    const certificate = children(outer[0], 48, 1);
+    if (certificate.length !== 3)
+        throw new Error("invalid DER certificate");
+    const tbs = children(certificate[0], 48, 2), containers = tbs.filter(p => p.tag === 163);
+    if (containers.length > 1)
+        throw new Error("duplicate certificate extensions");
+    if (!containers.length)
+        return { basic: null, usage: null };
+    const container = children(containers[0], 163, 3);
+    if (container.length !== 1)
+        throw new Error("invalid certificate extensions");
+    const extensions = children(container[0], 48, 4);
+    if (extensions.length > 32)
+        throw new Error("certificate exceeds its 32-extension bound");
+    const seen = new Set();
+    let basic = null, usage = null;
+    for (const extension of extensions) {
+        const fields = children(extension, 48, 5);
+        if (fields.length < 2 || fields.length > 3)
+            throw new Error("invalid certificate extension");
+        const oidBytes = content(fields[0], 6);
+        if (!oidBytes.length || oidBytes.length > 32 || oidBytes.at(-1) & 128 || oidBytes.some((b, i) => b === 128 && (i === 0 || !(oidBytes[i - 1] & 128))))
+            throw new Error("invalid DER extension identifier");
+        const oid = oidBytes.toString("hex");
+        if (seen.has(oid))
+            throw new Error("duplicate certificate extension");
+        seen.add(oid);
+        const critical = fields.length === 3 ? boolean(fields[1]) : false, value = fields.at(-1);
+        content(value, 4);
+        if (oid === "551d13") {
+            const sequence = parts(value.start, value.end, 6);
+            if (sequence.length !== 1)
+                throw new Error("invalid basic constraints");
+            const values = children(sequence[0], 48, 7);
+            let index = 0;
+            const ca = values[0]?.tag === 1 ? boolean(values[index++]) : false;
+            let pathLen;
+            if (values[index]) {
+                const n = content(values[index++], 2);
+                if (!ca || !n.length || n.length > 4 || n[0] & 128 || n.length > 1 && n[0] === 0 && !(n[1] & 128))
+                    throw new Error("invalid CA path length");
+                pathLen = 0;
+                for (const b of n)
+                    pathLen = pathLen * 256 + b;
+            }
+            if (index !== values.length)
+                throw new Error("invalid basic constraints");
+            basic = { ca, critical, ...(pathLen !== undefined ? { pathLen } : {}) };
+        }
+        else if (oid === "551d0f") {
+            const bitString = parts(value.start, value.end, 6);
+            if (bitString.length !== 1)
+                throw new Error("invalid key usage");
+            const bits = content(bitString[0], 3), unused = bits[0];
+            if (bits.length < 2 || bits.length > 3 || unused === undefined || unused > 7 || bits.at(-1) & ((1 << unused) - 1) || bits.length === 3 && (bits[2] & 127 || unused !== 7) || !bits.subarray(1).some(b => b !== 0))
+                throw new Error("invalid key usage bits");
+            usage = { signature: !!(bits[1] & 128), certificates: !!(bits[1] & 4) };
+        }
+        else if (critical || ["551d1e", "551d20", "551d21", "551d24", "551d25", "551d36"].includes(oid)) {
+            throw new Error("unsupported certificate constraint or critical extension");
+        }
+    }
+    return { basic, usage };
+}
+export function nitroCertificatePathReasons(certs) {
+    const reasons = [];
+    for (let i = 0; i < certs.length; i++) {
+        const certificate = certs[i];
+        let parsed;
+        try {
+            parsed = nitroCertificateConstraints(certificate);
+        }
+        catch {
+            reasons.push(`certificate ${i} has malformed or unsupported constraints`);
+            continue;
+        }
+        const { basic, usage } = parsed, leaf = i === certs.length - 1;
+        if (leaf) {
+            if (certificate.ca || basic?.ca || basic?.pathLen !== undefined)
+                reasons.push(`certificate ${i} is not an end-entity signing certificate`);
+            if (!usage || !usage.signature || usage.certificates)
+                reasons.push(`certificate ${i} key usage does not permit attestation signing`);
+        }
+        else {
+            if (!basic?.ca || !basic.critical)
+                reasons.push(`certificate ${i} lacks critical CA basic constraints`);
+            if (!usage || !usage.certificates)
+                reasons.push(`certificate ${i} key usage does not permit certificate signing`);
+            const below = certs.slice(i + 1, -1).filter(c => c.subject !== c.issuer).length;
+            if (basic?.pathLen !== undefined && below > basic.pathLen)
+                reasons.push(`certificate ${i} path length constraint is exceeded`);
+        }
+    }
+    return reasons;
+}

package/dist/nitro.d.ts

@@ -0,0 +1,74 @@
+import { X509Certificate } from "node:crypto";
+import type { Attestation, AttestCheck, QuoteVerifier } from "@zanii/attest";
+export { AWS_NITRO_GOV_ROOT_PEM, AWS_NITRO_GOV_ROOT_SHA256 } from "./nitro-roots.ts";
+/**
+ * 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 declare const AWS_NITRO_ROOT_PEM = "-----BEGIN CERTIFICATE-----\nMIICETCCAZagAwIBAgIRAPkxdWgbkK/hHUbMtOTn+FYwCgYIKoZIzj0EAwMwSTEL\nMAkGA1UEBhMCVVMxDzANBgNVBAoMBkFtYXpvbjEMMAoGA1UECwwDQVdTMRswGQYD\nVQQDDBJhd3Mubml0cm8tZW5jbGF2ZXMwHhcNMTkxMDI4MTMyODA1WhcNNDkxMDI4\nMTQyODA1WjBJMQswCQYDVQQGEwJVUzEPMA0GA1UECgwGQW1hem9uMQwwCgYDVQQL\nDANBV1MxGzAZBgNVBAMMEmF3cy5uaXRyby1lbmNsYXZlczB2MBAGByqGSM49AgEG\nBSuBBAAiA2IABPwCVOumCMHzaHDimtqQvkY4MpJzbolL//Zy2YlES1BR5TSksfbb\n48C8WBoyt7F2Bw7eEtaaP+ohG2bnUs990d0JX28TcPQXCEPZ3BABIeTPYwEoCWZE\nh8l5YoQwTcU/9KNCMEAwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUkCW1DdkF\nR+eWw5b6cp3PmanfS5YwDgYDVR0PAQH/BAQDAgGGMAoGCCqGSM49BAMDA2kAMGYC\nMQCjfy+Rocm9Xue4YnwWmNJVA44fA0P5W2OpYow9OYCVRaEevL8uO1XYru5xtMPW\nrfMCMQCi85sWBbJwKKXdS6BptQFuZbT73o/gBh1qUxl/nNr12UO8Yfwr6wPLb+6N\nIwLz3/Y=\n-----END CERTIFICATE-----\n";
+/** The fingerprint AWS publishes for the root (verify-root.html), as `X509Certificate.fingerprint256` writes it. */
+export declare 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";
+export type NitroPartition = "aws" | "aws-us-gov";
+/** Explicit operator policy only. Never select a root from the quote's subject, bundle or request. */
+export declare function nitroRootForPartition(partition?: NitroPartition): string;
+/** Section 5: default freshness window, and the allowed skew between the document and the attestation claim. */
+export declare const NITRO_MAX_AGE_SECONDS = 300;
+export declare const NITRO_MAX_SKEW_SECONDS = 300;
+export interface NitroDocument {
+    moduleId: string;
+    digest: "SHA384";
+    /** Milliseconds since the UNIX epoch (UTC). */
+    timestamp: number;
+    /** PCR index to lowercase hex. */
+    pcrs: Record<number, string>;
+    certificate: Uint8Array;
+    cabundle: Uint8Array[];
+    publicKey: Uint8Array | null;
+    userData: Uint8Array | null;
+    nonce: Uint8Array | null;
+}
+export interface NitroCheck extends AttestCheck {
+    document: NitroDocument | null;
+}
+export interface NitroOptions {
+    /** The trust anchor (PEM or certificate); the pinned AWS root by default. Tests pass their own. */
+    root?: string | X509Certificate;
+    /** The verifier's clock, ISO UTC; `Date.now()` by default. */
+    now?: string;
+    /** Oldest acceptable document, in seconds before `now`; `Infinity` turns the check off. */
+    maxAgeSeconds?: number;
+    /** The expected nonce: bytes, or a string compared as its UTF-8 bytes. */
+    nonce?: Uint8Array | string;
+    /** Expected PCR values by index (PCR0, PCR1, PCR2, PCR8, ...), hex. */
+    pcrs?: Readonly<Record<number, string>>;
+}
+/** RFC 9052 section 4.4: Sig_structure = ["Signature1", body_protected, external_aad (empty), payload]. */
+export declare function sigStructure(protectedBytes: Uint8Array, payload: Uint8Array): Uint8Array;
+/** Sections 3 and 4: decode the COSE_Sign1 envelope and its attestation document; throws on any malformed part. */
+export declare function parseNitroDocument(bytes: Uint8Array): {
+    protectedBytes: Uint8Array;
+    payload: Uint8Array;
+    signature: Uint8Array;
+    document: NitroDocument;
+};
+/** Section 4 and 5: the document's envelope, signature, chain, freshness, nonce and PCRs. */
+export declare function verifyNitroDocument(bytes: Uint8Array, opts?: NitroOptions): NitroCheck;
+/** The `measurement` a Nitro attestation claims: PCR0 (the enclave image), `sha384:<hex>`. */
+export declare const nitroMeasurement: (doc: NitroDocument) => string;
+export type NitroQuoteOptions = Omit<NitroOptions, "nonce" | "now"> & {
+    /** The raw attestation document whose SHA-256 is `quoteHash`, or nothing. */
+    quote: (quoteHash: string) => Uint8Array | null | undefined | Promise<Uint8Array | null | undefined>;
+    now?: () => string;
+};
+/**
+ * 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 declare function nitroQuoteVerifier(opts: NitroQuoteOptions): QuoteVerifier;
+/** `nitroQuoteVerifier` with its reasons. */
+export declare function checkNitroAttestation(a: Attestation, opts: NitroQuoteOptions): Promise<NitroCheck>;