@zanii/certify 0.0.0-stage → 0.5.0

package/dist/bundle.d.ts

@@ -0,0 +1,92 @@
+import { type Staff } from "./impartiality.ts";
+import { type CategoryScore } from "./scoring.ts";
+import { type ApplianceExecution, type ApplianceExportIdentity } from "./appliance-execution.ts";
+export type { ApplianceExecution, ApplianceExportIdentity } from "./appliance-execution.ts";
+export interface CategoryCount {
+    category: string;
+    trials: number;
+    passes: number;
+    threshold_ppm: number;
+    findings: readonly string[];
+}
+export interface CategoryResult extends CategoryScore {
+    category: string;
+    trials: number;
+    passes: number;
+    threshold_ppm: number;
+    findings: string[];
+}
+export interface Evidence {
+    case_id: string;
+    /** The hash-chain head of the case's recorded transcript. */
+    chain_head: string;
+    blackbox_session?: string;
+}
+export interface BundleInput {
+    execution?: ApplianceExecution | null;
+    profile: string;
+    level: number;
+    fingerprint: string;
+    plan: {
+        categories: readonly string[];
+        trials: number;
+    };
+    results: readonly CategoryCount[];
+    evidence: readonly Evidence[];
+    suite_snapshot: string;
+    staff: Staff;
+    started_at: string;
+    ended_at: string;
+    /** Default: pickScheme (0.1 for Levels 1 and 2, 0.2 for Level 3); the profile's scheme. */
+    scheme?: string;
+    /** Section 4: a partial re-test, and the bundle of the earlier passing run that covers the rest. */
+    partial?: {
+        covered_by: string;
+    } | null;
+}
+export interface ResultBundle {
+    execution?: ApplianceExecution;
+    v: 1;
+    type: "certify.result-bundle";
+    scheme: string;
+    profile: string;
+    level: number;
+    fingerprint: string;
+    plan: {
+        categories: string[];
+        trials: number;
+    };
+    results: CategoryResult[];
+    evidence: Evidence[];
+    suite_snapshot: string;
+    staff: {
+        testers: string[];
+        reviewer: string | null;
+        decider: string;
+    };
+    started_at: string;
+    ended_at: string;
+    partial?: {
+        covered_by: string;
+    };
+}
+export interface ApplianceExportBundle extends Omit<ResultBundle, "v" | "staff" | "execution" | "partial"> {
+    v: 2;
+    phase: "undecided";
+    staff: {
+        testers: string[];
+        reviewer: null;
+        decider: null;
+    };
+    execution: ApplianceExportIdentity;
+}
+export type ApplianceExportBundleInput = Omit<BundleInput, "staff" | "partial" | "execution"> & {
+    testers: readonly string[];
+    execution: ApplianceExportIdentity;
+};
+/** Existing v1 output is unchanged unless explicit verified appliance provenance is supplied. */
+export declare function buildBundle(input: BundleInput): ResultBundle;
+/** An appliance supplies execution evidence; it never occupies a human reviewer or decider role. */
+export declare function buildApplianceExportBundle(input: ApplianceExportBundleInput): ApplianceExportBundle;
+/** The bundle's identity: what the certificate's `claim.bundle` names. */
+export declare const bundleHash: (bundle: ResultBundle | ApplianceExportBundle) => string;

package/dist/bundle.js

@@ -0,0 +1,109 @@
+// spec/result-bundle.md: what a test run produced, hashed into the certificate. Never item text.
+import { jcsHash } from "@zanii/core";
+import { LEVELS, pickScheme } from "./certificate.js";
+import { staffRefusals } from "./impartiality.js";
+import { scoreCategory } from "./scoring.js";
+import { isDid, isInt, isIso, isSha, ms, SLUG, sortedUnique } from "./shared.js";
+import { applianceExecution, applianceExportIdentity } from "./appliance-execution.js";
+const CATEGORY = /^[a-z][a-z0-9_]{0,63}$/;
+const FINDING = /^[A-Z][A-Z0-9_]{0,63}$/;
+const CASE_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const PROFILE_REF = new RegExp(`^${SLUG.source.slice(1, -1)}/[1-9][0-9]*$`);
+const byKey = (k) => (a, b) => k(a) < k(b) ? -1 : k(a) > k(b) ? 1 : 0;
+function normalizedBundle(input, source) {
+    if (!PROFILE_REF.test(input.profile))
+        throw new Error("profile must be <slug>/<version>");
+    if (!LEVELS.includes(input.level))
+        throw new Error("level must be 1, 2 or 3");
+    const scheme = pickScheme(input.scheme, input.level);
+    if (!isSha(input.fingerprint))
+        throw new Error("fingerprint must be a fingerprint id");
+    if (!isSha(input.suite_snapshot))
+        throw new Error("suite_snapshot must be a sha256");
+    if (!isIso(input.started_at) || !isIso(input.ended_at) || ms(input.ended_at) < ms(input.started_at))
+        throw new Error("started_at and ended_at must be ISO UTC timestamps, in order");
+    const categories = sortedUnique(input.plan.categories);
+    if (!categories.length || categories.length !== input.plan.categories.length)
+        throw new Error("plan.categories must be distinct and not empty");
+    if (!categories.every((c) => CATEGORY.test(c)))
+        throw new Error("bad category id");
+    if (!isInt(input.plan.trials, 1, 1000))
+        throw new Error("plan.trials must be 1-1000");
+    const results = input.results.map((r) => {
+        const findings = sortedUnique(r.findings);
+        if (!findings.every((f) => FINDING.test(f)))
+            throw new Error(`bad finding code in ${r.category}`);
+        return {
+            category: r.category,
+            trials: r.trials,
+            passes: r.passes,
+            ...scoreCategory(r.passes, r.trials, r.threshold_ppm),
+            threshold_ppm: r.threshold_ppm,
+            findings,
+        };
+    });
+    results.sort(byKey((r) => r.category));
+    if (results.map((r) => r.category).join() !== categories.join())
+        throw new Error("results must have exactly one entry per planned category");
+    const evidence = input.evidence.map((e) => {
+        if (!CASE_ID.test(e.case_id) || !isSha(e.chain_head))
+            throw new Error("bad evidence entry");
+        const out = { case_id: e.case_id, chain_head: e.chain_head };
+        if (e.blackbox_session != null) {
+            if (!CASE_ID.test(e.blackbox_session))
+                throw new Error("bad blackbox_session");
+            out.blackbox_session = e.blackbox_session;
+        }
+        return out;
+    });
+    evidence.sort(byKey((e) => e.case_id));
+    if (new Set(evidence.map((e) => e.case_id)).size !== evidence.length)
+        throw new Error("evidence case_id values must be distinct");
+    const { testers, reviewer, decider } = input.staff;
+    if (!testers.length || !testers.every(isDid) || !source && !isDid(decider))
+        throw new Error("staff needs tester and decider DIDs");
+    if (!source && (reviewer === null ? input.level !== 1 : !isDid(reviewer)))
+        throw new Error("a reviewer DID is required above Level 1");
+    const refusals = source ? [] : staffRefusals({ testers: [...testers], reviewer, decider: decider }, []);
+    if (refusals.length)
+        throw new Error(`staffing refused: ${refusals.join(", ")}`);
+    const partial = input.partial ?? null;
+    if (partial !== null && (Object.keys(partial).length !== 1 || !isSha(partial.covered_by)))
+        throw new Error("partial must be {covered_by: <bundle hash>}");
+    const execution = input.execution == null ? undefined : applianceExecution(input.execution), machine = source?.appliance ?? execution?.appliance;
+    if (machine && [...testers, reviewer, decider].includes(machine))
+        throw new Error("an appliance cannot be recorded as human staff");
+    const bundle = {
+        v: 1,
+        type: "certify.result-bundle",
+        scheme,
+        profile: input.profile,
+        level: input.level,
+        fingerprint: input.fingerprint,
+        plan: { categories, trials: input.plan.trials },
+        results,
+        evidence,
+        suite_snapshot: input.suite_snapshot,
+        staff: { testers: sortedUnique(testers), reviewer, decider: decider },
+        started_at: input.started_at,
+        ended_at: input.ended_at,
+        ...(partial ? { partial: { covered_by: partial.covered_by } } : {}),
+        ...(execution ? { execution } : {}),
+    };
+    if (source) {
+        const { partial: ignored, ...base } = bundle;
+        return { ...base, v: 2, phase: "undecided", staff: { testers: sortedUnique(testers), reviewer: null, decider: null }, execution: source };
+    }
+    return bundle;
+}
+/** Existing v1 output is unchanged unless explicit verified appliance provenance is supplied. */
+export function buildBundle(input) { return normalizedBundle(input); }
+/** An appliance supplies execution evidence; it never occupies a human reviewer or decider role. */
+export function buildApplianceExportBundle(input) {
+    if (!Array.isArray(input.testers) || input.testers.length > 64 || !Array.isArray(input.results) || input.results.length > 10000 || !Array.isArray(input.evidence) || input.evidence.length > 10000 || !Array.isArray(input.plan?.categories) || input.plan.categories.length > 10000)
+        throw new Error("appliance bundle exceeds its staff or result bounds");
+    const source = applianceExportIdentity(input.execution);
+    return normalizedBundle({ ...input, execution: null, partial: null, staff: { testers: input.testers, reviewer: null, decider: null } }, source);
+}
+/** The bundle's identity: what the certificate's `claim.bundle` names. */
+export const bundleHash = (bundle) => jcsHash(bundle);

package/dist/certificate.d.ts

@@ -0,0 +1,161 @@
+import { type Credential, type CredentialCheck, type IssuerResolver, type RevocationList } from "@zanii/credentials";
+import { type PqBinding } from "@zanii/pq";
+import { type AuditAttestation } from "./audit.ts";
+import { type Fingerprint } from "./fingerprint.ts";
+import { type Licence, type LicenceOptions } from "./licence.ts";
+import { type PqCosignature } from "./pq.ts";
+import { type BodyRegisterOptions } from "./register.ts";
+import { type Signer } from "./signer.ts";
+import { type StatusDocument, type StatusEntry, type StatusWitness } from "./status.ts";
+import { type IssuerPolicy, type ReleaseVerificationPolicy } from "./verification-policy.ts";
+import { type AuditRenewalPolicy } from "./audit-renewal.ts";
+/** scheme.md section 8: every scheme version a certificate or bundle may name. */
+export declare const SCHEMES: readonly ["zanii-certify/0.1", "zanii-certify/0.2", "zanii-certify/0.3"];
+export type Scheme = (typeof SCHEMES)[number];
+/** The current scheme. */
+export declare const SCHEME: Scheme;
+export declare const LEVELS: readonly [1, 2, 3];
+export type Level = (typeof LEVELS)[number];
+/** scheme.md section 2: the levels each scheme version issues. */
+export declare const SCHEME_LEVELS: Record<Scheme, readonly Level[]>;
+/**
+ * scheme.md section 8: the scheme a certificate or bundle is issued under. Given, it must issue
+ * `level` (and allow 0.2 features when `needs02`, 0.3 features when `needs03`); absent, 0.3 with a
+ * 0.3 feature (a licence), else 0.1 for Levels 1 and 2 without 0.2 features, else 0.2.
+ */
+export declare function pickScheme(scheme: string | undefined, level: number, needs02?: boolean, needs03?: boolean): Scheme;
+export declare const CONFLICTS: readonly ["blackbox_customer", "ledger_customer", "investor", "staff_link", "other"];
+export type Conflict = (typeof CONFLICTS)[number];
+/** scheme.md section 5: the default re-test interval per level. */
+export declare const SURVEILLANCE: Record<Level, string>;
+/** scheme.md section 4: validity is 365 days from issue. */
+export declare const VALIDITY_DAYS = 365;
+export declare const DOMAIN: RegExp;
+export interface CertifyClaim {
+    scheme: Scheme;
+    profile: string;
+    level: Level;
+    fingerprint: string;
+    configuration: string;
+    bundle: string;
+    surveillance: string;
+    conflicts: Conflict[];
+    applicant: {
+        name: string;
+        country: string;
+    };
+    /** Level 3 only: jcsHash of the audit attestation (spec/audit.md). */
+    audit?: string;
+    /** When co-signed: bindingHash of the issuer's @zanii/pq binding (section 7). */
+    pq_binding?: string;
+    /** Scheme 0.3, issued by a licensee: jcsHash of its scheme licence (spec/licensing.md). */
+    licence?: string;
+}
+export interface CertificateInput {
+    issuerDomain: string;
+    /** The agent's did:key. */
+    holder: string;
+    profile: {
+        slug: string;
+        version: number;
+    };
+    level: Level;
+    fingerprint: Fingerprint;
+    /** The result bundle hash (spec/result-bundle.md). */
+    bundle: string;
+    conflicts: readonly Conflict[];
+    applicant: {
+        name: string;
+        country: string;
+    };
+    issuedAt: string;
+    /** Default: issuedAt plus 365 days. */
+    exp?: string;
+    /** Default: SURVEILLANCE[level]. */
+    surveillance?: string;
+    /** Default: pickScheme (0.1, or 0.2 for Level 3 or a pq binding). */
+    scheme?: string;
+    /** Level 3: the certification body's audit attestation (spec/audit.md). */
+    audit?: AuditAttestation;
+    /** The issuer's @zanii/pq binding, committed in the claim so the certificate can be co-signed. */
+    pqBinding?: PqBinding;
+    /** Scheme 0.3: the scheme licence the issuer certifies under (spec/licensing.md). */
+    licence?: Licence;
+    /** Scheme 0.3: the issuer's key lineage, oldest first: a licence naming an earlier key of it covers the signer. */
+    lineage?: readonly string[];
+}
+/** `certify.<profile slug>.l<level>` */
+export declare const certificateScope: (slug: string, level: number) => string;
+/** Issue a certificate, signed by `signer` (the lab issuer key, in a KMS or HSM). */
+export declare function issueCertificate(input: CertificateInput, signer: Signer): Promise<Credential>;
+export interface CertificateCheck {
+    ok: boolean;
+    reasons: string[];
+    /** This certificate's entry in the status document, when one was checked. */
+    status: StatusEntry | null;
+    /** Whether the supplied current fingerprint matches; null when none was supplied. */
+    fingerprint: "match" | "mismatch" | null;
+    credential: CredentialCheck;
+    /** Whether the certificate's post-quantum co-signature verified; null when not checked. */
+    pq: boolean | null;
+    /** The trusted witnesses that co-signed the status checkpoint, when a witness policy was given. */
+    witnesses: string[] | null;
+    /**
+     * With `issuerDoc` (section 7a): `required` when it says `require_pq` and the co-signatures were
+     * required, `opted_out` when the caller set `allowNoPq`, `not_required` otherwise.
+     */
+    pqPolicy?: PqPolicy;
+    /** Level 3 with `bodyRegister` or `trustedBodies`: which list of trusted bodies was used. */
+    bodies?: "register" | "local";
+}
+export type PqPolicy = "required" | "opted_out" | "not_required";
+export interface CertificateVerifyOptions {
+    /** Independently known scheme owner; its key cannot sign issuer or status histories. */
+    schemeOwner?: string;
+    status?: StatusDocument;
+    revocationList?: RevocationList;
+    resolver?: IssuerResolver;
+    /** The agent's current fingerprint (from a beacon or the applicant). */
+    fingerprint?: Fingerprint;
+    now?: string;
+    /** The certificate's post-quantum co-signature (section 7). */
+    pq?: PqCosignature;
+    /** The status document's post-quantum co-signature (status.md section 5). */
+    statusPq?: PqCosignature;
+    /** Require both signatures on the certificate and (when supplied) on the status document. */
+    requirePq?: boolean;
+    /** Level 3: the audit attestation the claim references (spec/audit.md). */
+    audit?: AuditAttestation;
+    /** Versioned issuer endorsement of a replacement audit; the original certificate stays immutable. */
+    auditRenewal?: AuditRenewalPolicy;
+    /** Level 3: the did:keys of the certification bodies this verifier trusts. */
+    trustedBodies?: readonly string[];
+    /** Require the status document to be in a witnessed checkpoint (spec/witness.md). */
+    statusWitness?: StatusWitness;
+    /**
+     * The issuer document's `status_dids` (section 5): the DIDs that may sign status now. Given, the
+     * status document and revocation list must be signed by one of them; a DID other than the
+     * certificate's issuer is accepted only when it is listed here and the resolver resolves it.
+     */
+    statusDids?: readonly string[];
+    /** spec/licensing.md section 3: check the certificate was issued under a licence that covered it. */
+    licences?: LicenceOptions;
+    /** Section 7a: the issuer document; `require_pq: true` in it makes `requirePq` the default. */
+    issuerDoc?: unknown;
+    /** Section 7a: explicitly verify without the post-quantum co-signatures the issuer document requires (reported as `opted_out`). */
+    allowNoPq?: boolean;
+    /** Level 3 (spec/body-register.md): the board-signed register of trusted bodies, used instead of `trustedBodies`. */
+    bodyRegister?: BodyRegisterOptions;
+    /** Independently pinned identity/PQ policy; absent metadata or changed keys fails closed. */
+    issuerPolicy?: IssuerPolicy;
+    /** Require trusted profile/scheme releases at issuance; optional strict post-withdrawal refusal. */
+    releases?: ReleaseVerificationPolicy;
+}
+/** The certify claim's own rules (certificate.md section 2); empty when the claim is well formed. */
+export declare function claimReasons(cert: Credential): string[];
+/**
+ * Verify a certificate: the four @zanii/credentials checks, the certify claim, its live status in
+ * the signed status document, and (when supplied) that the agent's current fingerprint matches.
+ * Anything not checked is reported, never assumed.
+ */
+export declare function verifyCertificate(cert: Credential, opts?: CertificateVerifyOptions): Promise<CertificateCheck>;