@zanii/certify 0.0.0-stage → 0.6.0

package/dist/bitstring-status.js

@@ -0,0 +1,135 @@
+// W3C Bitstring Status List v1.0, fixed 131072-slot publishing profile. Offline status remains a snapshot.
+import { gzipSync, gunzipSync } from "node:zlib";
+import { publicKeyFromDid } from "@zanii/core";
+import { credentialHash } from "@zanii/credentials";
+import { VC_CONTEXT, verifyVC } from "@zanii/vc";
+import { isInt, isIso, isObj, ms } from "./shared.js";
+import { signerDid } from "./signer.js";
+import { signVcWith } from "./vc.js";
+export const BITSTRING_STATUS_SLOTS = 131_072;
+const BYTES = BITSTRING_STATUS_SLOTS / 8;
+const purpose = (p) => p === "revocation" || p === "suspension";
+const web = (s) => {
+    if (typeof s !== "string" || s.length > 2048 || !/^[\x21-\x7e]+$/.test(s))
+        return false;
+    try {
+        const u = new URL(s);
+        return u.protocol === "https:" && !u.username && !u.password && !s.includes("#") && s === u.href;
+    }
+    catch {
+        return false;
+    }
+};
+const decode = (s) => {
+    if (typeof s !== "string" || s.length > 32768 || !/^u[A-Za-z0-9_-]+$/.test(s) || s.trim() !== s)
+        return null;
+    try {
+        const data = Buffer.from(s.slice(1), "base64url");
+        if (`u${data.toString("base64url")}` !== s)
+            return null;
+        const bits = gunzipSync(data, { maxOutputLength: BYTES });
+        return bits.length === BYTES ? bits : null;
+    }
+    catch {
+        return null;
+    }
+};
+const encode = (bits) => {
+    // shortcut: stored GZIP blocks fix bytes across zlib versions; use a canonical compressor if shard bandwidth requires it.
+    const gzip = gzipSync(bits, { level: 0 });
+    gzip[9] = 255; // Stable RFC1952 OS field across Node/Python; payload is ordinary GZIP.
+    return `u${gzip.toString("base64url")}`;
+};
+const entryShape = (s) => isObj(s) && Object.keys(s).length === 5 && s.type === "BitstringStatusListEntry" && purpose(s.statusPurpose)
+    && web(s.statusListCredential) && typeof s.statusListIndex === "string" && /^(?:0|[1-9][0-9]{0,5})$/.test(s.statusListIndex) && s.statusListIndex.trim() === s.statusListIndex
+    && Number(s.statusListIndex) < BITSTRING_STATUS_SLOTS && s.id === `${s.statusListCredential}#${s.statusListIndex}`;
+export { entryShape as isBitstringStatusEntry };
+const proofShape = (proof) => isObj(proof) && Object.keys(proof).length === 6 && proof.type === "DataIntegrityProof"
+    && proof.cryptosuite === "eddsa-jcs-2022" && proof.proofPurpose === "assertionMethod" && isIso(proof.created)
+    && typeof proof.verificationMethod === "string" && proof.verificationMethod.length <= 140
+    && typeof proof.proofValue === "string" && proof.proofValue.length <= 100;
+export function bitstringStatusEntry(input) {
+    if (!isInt(input.index, 0, BITSTRING_STATUS_SLOTS - 1) || !web(input.list) || !purpose(input.purpose))
+        throw new Error("invalid bitstring status entry");
+    return { id: `${input.list}#${input.index}`, type: "BitstringStatusListEntry", statusPurpose: input.purpose, statusListIndex: String(input.index), statusListCredential: input.list };
+}
+export async function buildBitstringStatusList(input, signer) {
+    if (!web(input.id) || !purpose(input.purpose) || !isIso(input.validFrom) || !isIso(input.validUntil) || !isIso(input.created)
+        || ms(input.validUntil) <= ms(input.validFrom) || ms(input.validUntil) - ms(input.validFrom) > 86_400_000
+        || !Array.isArray(input.entries) || input.entries.length > BITSTRING_STATUS_SLOTS)
+        throw new Error("invalid bitstring status list input");
+    const bits = new Uint8Array(BYTES), seen = new Set();
+    for (const e of input.entries) {
+        if (!isObj(e) || Object.keys(e).length !== 2 || !isInt(e.index, 0, BITSTRING_STATUS_SLOTS - 1) || typeof e.value !== "boolean" || seen.has(e.index))
+            throw new Error("invalid or duplicate bitstring status index");
+        seen.add(e.index);
+        if (e.value)
+            bits[Math.floor(e.index / 8)] |= 0x80 >> (e.index % 8);
+    }
+    if (input.previous !== undefined) {
+        const prior = input.previous, subject = isObj(prior?.credentialSubject) ? prior.credentialSubject : {};
+        const old = verifyBitstringStatusList(prior, { issuers: [signerDid(signer)], now: String(prior?.validFrom) }).bits;
+        if (prior?.id !== input.id || subject.statusPurpose !== input.purpose || !old
+            || !isIso(prior.validFrom) || ms(prior.validFrom) > ms(input.validFrom))
+            throw new Error("invalid previous bitstring status list");
+        if (input.purpose === "revocation" && old.some((byte, i) => (byte & bits[i]) !== byte))
+            throw new Error("revocation bits cannot be cleared");
+    }
+    return signVcWith({ "@context": [VC_CONTEXT], id: input.id, type: ["VerifiableCredential", "BitstringStatusListCredential"], issuer: signerDid(signer),
+        validFrom: input.validFrom, validUntil: input.validUntil,
+        credentialSubject: { id: `${input.id}#list`, type: "BitstringStatusList", statusPurpose: input.purpose, encodedList: encode(bits) } }, signer, input.created);
+}
+export function verifyBitstringStatusList(doc, opts) {
+    const denied = (reason) => ({ ok: false, reasons: [reason], bits: null });
+    if (!isObj(opts) || !Array.isArray(opts.issuers) || opts.issuers.length < 1 || opts.issuers.length > 64 || !Array.from(opts.issuers).every((d) => typeof d === "string" && d.length <= 69 && publicKeyFromDid(d)) || !isIso(opts.now))
+        return denied("explicit trusted bitstring issuers and reference time are required");
+    if (!isObj(doc) || Object.keys(doc).length !== 8 || !web(doc.id) || !opts.issuers.includes(String(doc.issuer)) || !isIso(doc.validFrom) || !isIso(doc.validUntil)
+        || ms(doc.validFrom) > ms(opts.now) || ms(doc.validUntil) <= ms(opts.now) || ms(doc.validUntil) - ms(doc.validFrom) > 86_400_000
+        || !Array.isArray(doc.type) || doc.type.length !== 2 || doc.type[0] !== "VerifiableCredential" || doc.type[1] !== "BitstringStatusListCredential"
+        || !Array.isArray(doc["@context"]) || doc["@context"].length !== 1 || doc["@context"][0] !== VC_CONTEXT || !proofShape(doc.proof))
+        return denied("invalid, untrusted or stale bitstring status list");
+    const subject = doc.credentialSubject;
+    if (!isObj(subject) || Object.keys(subject).length !== 4 || subject.id !== `${doc.id}#list` || subject.type !== "BitstringStatusList" || !purpose(subject.statusPurpose))
+        return denied("invalid bitstring status subject");
+    const bits = decode(subject.encodedList);
+    if (!bits)
+        return denied("invalid or oversized bitstring encoding");
+    const check = verifyVC(doc, { at: opts.now });
+    return check.ok ? { ok: true, reasons: [], bits } : { ok: false, reasons: check.reasons, bits: null };
+}
+export function verifyBitstringStatusEntry(entry, doc, opts) {
+    if (!entryShape(entry))
+        return { ok: false, reasons: ["invalid bitstring status entry"], value: null };
+    const checked = verifyBitstringStatusList(doc, opts);
+    if (!checked.ok || !checked.bits)
+        return { ok: false, reasons: checked.reasons, value: null };
+    const list = doc;
+    if (list.id !== entry.statusListCredential || list.credentialSubject.statusPurpose !== entry.statusPurpose)
+        return { ok: false, reasons: ["bitstring list URL or purpose does not match the entry"], value: null };
+    const index = Number(entry.statusListIndex);
+    return { ok: true, reasons: [], value: !!(checked.bits[Math.floor(index / 8)] & (0x80 >> (index % 8))) };
+}
+export async function certificateToBitstringVc(cert, signer, opts) {
+    if (cert?.v !== 1 || cert.type !== "credential" || cert.issuer !== signerDid(signer) || !isIso(opts.created) || opts.revocationList === opts.suspensionList)
+        throw new Error("invalid certificate or bitstring VC signer/options");
+    return signVcWith({ "@context": [VC_CONTEXT], type: ["VerifiableCredential", "ZaniiCertifyCertificateV2"], issuer: cert.issuer,
+        validFrom: cert.issued_at, validUntil: cert.exp,
+        credentialSubject: { id: cert.holder, scope: cert.scope, claim: cert.claim, issuerDomain: cert.issuer_domain, certificate: credentialHash(cert), sig: cert.sig },
+        credentialStatus: [bitstringStatusEntry({ index: opts.index, list: opts.revocationList, purpose: "revocation" }), bitstringStatusEntry({ index: opts.index, list: opts.suspensionList, purpose: "suspension" })] }, signer, opts.created);
+}
+export function verifyCertificateBitstringVc(vc, opts = {}) {
+    if (!isObj(vc) || !proofShape(vc.proof))
+        return { ok: false, reasons: ["not a certificate bitstring VC v2 proof"], certificate: null };
+    const checked = verifyVC(vc, opts.at === undefined ? {} : { at: opts.at });
+    if (!checked.ok)
+        return { ok: false, reasons: checked.reasons, certificate: null };
+    const doc = vc, s = doc.credentialSubject;
+    if (!doc.type.includes("ZaniiCertifyCertificateV2") || !isObj(s) || !["id", "scope", "claim", "issuerDomain", "sig", "certificate"].every((k) => Object.hasOwn(s, k)))
+        return { ok: false, reasons: ["not a complete certificate bitstring VC v2"], certificate: null };
+    const cert = { v: 1, type: "credential", issuer: doc.issuer, issuer_domain: s.issuerDomain, holder: s.id, scope: s.scope, claim: s.claim, issued_at: doc.validFrom, exp: doc.validUntil, sig: s.sig };
+    const statuses = doc.credentialStatus;
+    if (credentialHash(cert) !== s.certificate || !Array.isArray(statuses) || statuses.length !== 2 || !Array.from(statuses).every(entryShape)
+        || statuses[0].statusPurpose !== "revocation" || statuses[1].statusPurpose !== "suspension" || statuses[0].statusListIndex !== statuses[1].statusListIndex || statuses[0].statusListCredential === statuses[1].statusListCredential)
+        return { ok: false, reasons: ["bitstring VC certificate or status bindings are invalid"], certificate: null };
+    return { ok: true, reasons: [], certificate: cert };
+}

package/dist/board.d.ts

@@ -0,0 +1,218 @@
+import { type Signer } from "./signer.ts";
+import type { SchemeLogsInput } from "./scheme-log.ts";
+/** Section 1: one signature over the canonical bytes of a document without `signatures`. */
+export interface BodySignature {
+    signer: string;
+    sig: string;
+}
+export declare function bodySignature(body: object, signer: Signer): Promise<BodySignature>;
+/** The document with its signatures sorted by signer; one signer signs once. */
+export declare function withSignatures<T extends object>(body: T, sigs: readonly BodySignature[]): T & {
+    signatures: BodySignature[];
+};
+/**
+ * Section 1: the signers of `doc` whose signature verifies, and whether `signatures` is well formed
+ * (1 to 64 `{signer, sig}`, strictly sorted by signer, each verifying, each in `allowed` when given).
+ */
+export declare function signersOf(doc: Record<string, unknown>, allowed?: readonly string[]): {
+    signers: string[];
+    wellFormed: boolean;
+};
+export interface BoardInput {
+    owner: string;
+    seq: number;
+    prev: string | null;
+    members: readonly string[];
+    threshold: number;
+    effectiveFrom: string;
+    /** scheme-log.md section 3: the scheme owner's ledger identity, the root of the delegation of its append receipts. */
+    ledger?: string;
+}
+export type BoardBody = {
+    v: 1;
+    type: "certify.board";
+    owner: string;
+    seq: number;
+    prev: string | null;
+    members: string[];
+    threshold: number;
+    effective_from: string;
+    ledger?: string;
+};
+export type Board = BoardBody & {
+    signatures: BodySignature[];
+};
+export interface BoardCheck {
+    ok: boolean;
+    reasons: string[];
+}
+declare function boardError(b: Record<string, unknown>): string | null;
+/** The unsigned board (each signer signs it with `bodySignature`). */
+export declare function boardBody(f: BoardInput): BoardBody;
+/** A board signed by `signers`: the owner for the first board, k of the previous board after. */
+export declare function buildBoard(f: BoardInput, signers: readonly Signer[]): Promise<Board>;
+export declare const isBoard: (b: unknown) => b is Record<string, unknown>;
+/**
+ * Section 2: the boards form one log: board i at seq i naming board i - 1, one owner, each taking
+ * effect after the previous one; board 0 signed by the owner, every later board by at least the
+ * previous board's threshold of its members, and no other signature.
+ */
+export declare function verifyBoardLog(boards: readonly unknown[], opts?: {
+    owner?: string;
+}): BoardCheck;
+export declare const RELEASE_KINDS: readonly ["scheme", "profile"];
+export type ReleaseKind = (typeof RELEASE_KINDS)[number];
+export interface ReleaseSubject {
+    kind: ReleaseKind;
+    /** `zanii-certify/<major>.<minor>` for a scheme, `<slug>/<version>` for a profile. */
+    ref: string;
+}
+export interface ReleaseInput {
+    seq: number;
+    prev: string | null;
+    subject: ReleaseSubject;
+    /** The released content: a scheme's published text, file hash; a profile, jcsHash of the profile. */
+    sha256: string;
+    effectiveFrom: string;
+    notes: {
+        en: string;
+        ar: string;
+    };
+    /** jcsHash of the board that signs the release (the board in force at effectiveFrom). */
+    board: string;
+}
+export type ReleaseBody = {
+    v: 1;
+    type: "certify.release";
+    seq: number;
+    prev: string | null;
+    subject: ReleaseSubject;
+    sha256: string;
+    effective_from: string;
+    notes: {
+        en: string;
+        ar: string;
+    };
+    board: string;
+};
+export type Release = ReleaseBody & {
+    signatures: BodySignature[];
+};
+export declare const isText: (t: unknown) => boolean;
+export declare function subjectOk(s: unknown): s is ReleaseSubject;
+declare function releaseError(r: Record<string, unknown>): string | null;
+export declare function releaseBody(f: ReleaseInput): ReleaseBody;
+/** A release signed by `signers` (members of the board it names). */
+export declare function buildRelease(f: ReleaseInput, signers: readonly Signer[]): Promise<Release>;
+export declare const isRelease: (r: unknown) => r is Record<string, unknown>;
+/**
+ * A board-signed document (release, withdrawal, body register) against a board log already checked:
+ * the board it names is in the log and in force at its effective_from, and k of its members signed it.
+ */
+export declare function boardSignedReasons(r: Record<string, unknown>, boards: readonly unknown[], noun: string): string[];
+/** Section 3: one release, with the board log it names (checked with `verifyBoardLog`). */
+export declare function verifyRelease(release: unknown, boards: readonly unknown[], opts?: {
+    owner?: string;
+}): BoardCheck;
+export declare const subjectKey: (s: unknown) => string;
+/** Section 4: the release log: every release valid, at seq i naming release i - 1, effective_from never going back, each subject released once. */
+export declare function verifyReleaseLog(releases: readonly unknown[], boards: readonly unknown[], opts?: {
+    owner?: string;
+    schemeLog?: SchemeLogsInput;
+}): BoardCheck;
+/**
+ * Section 5: may a lab use `subject` at `at`? The release log must verify, release the subject, take
+ * effect no later than `at` and (with `sha256`) for exactly that content. With `withdrawals`
+ * (section 6), a release withdrawn at or before `at` may not be used.
+ */
+export declare function requireRelease(releases: readonly unknown[], boards: readonly unknown[], subject: ReleaseSubject, at: string, opts?: {
+    owner?: string;
+    sha256?: string;
+    withdrawals?: readonly unknown[];
+    schemeLog?: SchemeLogsInput;
+}): BoardCheck & {
+    release: Release | null;
+    withdrawal?: ReleaseWithdrawal | null;
+};
+/**
+ * Section 4a: may `board` be appended to the board log now? The board log with it verifies, it takes
+ * effect after the effective_from of every release already in the release log, and the release log
+ * still verifies against the longer board log (a board change never breaks a release).
+ */
+export declare function verifyBoardAppend(boards: readonly unknown[], releases: readonly unknown[], board: unknown, opts?: {
+    owner?: string;
+}): BoardCheck;
+/**
+ * Section 4a: may `release` be appended to the release log now? The release log with it verifies,
+ * and it is signed by the newest board of the board log (a board that was replaced signs nothing more).
+ */
+export declare function verifyReleaseAppend(releases: readonly unknown[], boards: readonly unknown[], release: unknown, opts?: {
+    owner?: string;
+}): BoardCheck;
+export declare const WITHDRAWAL_REASONS: readonly ["DEFECT", "SECURITY", "LEGAL", "OTHER"];
+export type WithdrawalReason = (typeof WITHDRAWAL_REASONS)[number];
+export interface ReleaseWithdrawalInput {
+    seq: number;
+    prev: string | null;
+    subject: ReleaseSubject;
+    /** jcsHash of the release withdrawn. */
+    release: string;
+    reason: WithdrawalReason;
+    notes: {
+        en: string;
+        ar: string;
+    };
+    effectiveFrom: string;
+    /** jcsHash of the board that signs (the newest board when it is appended). */
+    board: string;
+}
+export type ReleaseWithdrawalBody = {
+    v: 1;
+    type: "certify.release-withdrawal";
+    seq: number;
+    prev: string | null;
+    subject: ReleaseSubject;
+    release: string;
+    reason: WithdrawalReason;
+    notes: {
+        en: string;
+        ar: string;
+    };
+    effective_from: string;
+    board: string;
+};
+export type ReleaseWithdrawal = ReleaseWithdrawalBody & {
+    signatures: BodySignature[];
+};
+declare function withdrawalError(w: Record<string, unknown>): string | null;
+export { boardError as boardFieldError, releaseError as releaseFieldError, withdrawalError as withdrawalFieldError };
+export declare function releaseWithdrawalBody(f: ReleaseWithdrawalInput): ReleaseWithdrawalBody;
+/** A release withdrawal signed by `signers` (k members of the board it names). */
+export declare function buildReleaseWithdrawal(f: ReleaseWithdrawalInput, signers: readonly Signer[]): Promise<ReleaseWithdrawal>;
+export declare const isWithdrawal: (w: unknown) => w is Record<string, unknown>;
+/**
+ * Section 6: the withdrawal log: the release log verifies, every withdrawal at seq i naming
+ * withdrawal i - 1, effective_from never going back, naming a release of the log with its subject,
+ * taking effect no earlier than it, each release withdrawn once, signed by k of the board in force.
+ */
+export declare function verifyWithdrawalLog(withdrawals: readonly unknown[], releases: readonly unknown[], boards: readonly unknown[], opts?: {
+    owner?: string;
+    schemeLog?: SchemeLogsInput;
+}): BoardCheck;
+/**
+ * Section 6: a certificate issued under a withdrawn scheme or profile version is flagged, never
+ * failed. `ok` is whether the withdrawal log verified; `flags` names each withdrawal that touches
+ * the certificate's scheme or profile.
+ */
+export declare function withdrawalFlags(cert: {
+    issued_at?: unknown;
+    claim?: unknown;
+}, logs: {
+    withdrawals: readonly unknown[];
+    releases: readonly unknown[];
+    boards: readonly unknown[];
+    owner?: string;
+    schemeLog?: SchemeLogsInput;
+}): BoardCheck & {
+    flags: string[];
+};