burnledger 0.9.1 → 0.10.0

package/dist/cjs/audit-pack.d.ts

@@ -0,0 +1,201 @@
+/** Audit pack verification (docs/audit-pack.md).
+ *
+ * A port of core/auditpack.go and core/auditpack_footer.go, verdict for
+ * verdict and reason string for reason string. Every record inside a pack is
+ * verified exactly as `burnledger check --cert` verifies one, through the same
+ * verifyCertificateWithStatus and verifyTransparency. What this file adds is
+ * the framing — header, footer, digest, cursor chain — that lets a reader tell
+ * a whole page from a subset and a whole set of pages from a partial one, and
+ * the footer's signed statement, which is the issuer's word on the count and
+ * digest rather than the host's.
+ *
+ * The single-record verifier reports a refusal by THROWING a VerificationError
+ * whose message is prose, where Go returns a named verdict. A pack result is
+ * read beside the Go one — testdata/audit_pack/index.json pins the two to the
+ * same strings — so the throw is mapped back to Go's name here rather than
+ * leaking one SDK's wording into a cross-language contract.
+ */
+import type { CryptoOps } from "./crypto.js";
+import type { KeyEntry } from "./keys.js";
+import { type PublicKeyInfo } from "./verify.js";
+import { type RunRecord, type RunRecordResult } from "./run-record.js";
+export declare const AUDIT_PACK_FORMAT = "burnledger.audit_pack.v1";
+export type AuditPackVerdict = "VERIFIED" | "INCOMPLETE" | "INVALID" | "UNREADABLE";
+export type AuditPackLogHead = "VALID" | "ABSENT" | "INVALID_SIGNATURE" | "UNREADABLE";
+export interface AuditPackFilters {
+    status: string | null;
+    issuedAfter: string | null;
+    issuedBefore: string | null;
+    /** Limits the pack to one run (ADR-031). A pack filtered by a closed run
+     * carries the run record in its header. */
+    runId: string | null;
+}
+/** The log head as the header carries it: GET /v1/log/head's hex document. */
+export interface SignedTreeHeadDocument {
+    tree_size: number;
+    root_hash: string;
+    timestamp: string;
+    signature: string;
+    log_id?: string;
+}
+export interface AuditPackHeader {
+    format: string;
+    /** Whole-second UTC, as Go's time.Time prints it: the server stamps a
+     * nanosecond clock, and the three CLIs print one Generated line. */
+    generatedAt: string;
+    filters: AuditPackFilters;
+    /** The cursor this page resumed from; null on a first page. */
+    cursor: string | null;
+    issuerKeys: KeyEntry[];
+    /** Absent when the issuer had none to give. */
+    logHead?: SignedTreeHeadDocument;
+    /** The signed run record (ADR-031) when the pack is filtered by a CLOSED
+     * run: the document GET /v1/runs/{id} serves as `record`, proof included,
+     * as it arrived. Absent for an open or lost run, or no run filter. */
+    runRecord?: Record<string, unknown>;
+}
+/** The wire form of the footer's signed statement (core.AuditPackFooterSigned):
+ * the fields the header and footer do not already carry, as the file prints
+ * them. */
+export interface AuditPackFooterSigned {
+    statement_issued_at: string;
+    sth_tree_size: number;
+    sth_root_hash: string;
+    signature: string;
+    key_id: string;
+}
+export interface AuditPackFooter {
+    recordCount: number;
+    nextCursor: string | null;
+    recordsSha256: string;
+    /** Absent when the issuer could not sign; the count and digest are then the
+     * issuer's unsigned word, and the reader is told so. */
+    signed?: AuditPackFooterSigned;
+}
+export declare const PAYLOAD_TYPE_AUDIT_PACK_FOOTER = "burnledger.audit_pack_footer.v1";
+/** What a reader learns about a footer's signature (core.AuditPackFooterResult).
+ * Not a record verdict: it answers whether the issuer attested to the count
+ * and digest, never whether a record may be relied on. */
+export type AuditPackFooterResult = "VALID" | "UNSIGNED" | "UNKNOWN_KEY" | "KEY_UNUSABLE" | "INVALID_SIGNATURE";
+/** The enclave's signed word on one page (core.AuditPackFooterStatement): for
+ * THIS query, resumed from THIS cursor, the issuer wrote THIS many records with
+ * THIS digest, with THIS log head in front of it, at THIS instant. The filters
+ * and cursor are the header's, so the signature binds the footer to the query
+ * its header names. It says nothing about completeness: the enclave signs what
+ * the host tells it. */
+export interface AuditPackFooterStatement {
+    filters: AuditPackFilters;
+    cursor: string | null;
+    nextCursor: string | null;
+    recordCount: number;
+    /** 32 bytes. */
+    recordsSha256: Uint8Array;
+    /** The header's log head; zero when the header carries none. */
+    sthTreeSize: number;
+    /** 32 bytes. */
+    sthRootHash: Uint8Array;
+    /** RFC 3339. Signed in whole-second UTC, whatever offset it arrived with. */
+    statementIssuedAt: string;
+    /** 64 bytes. */
+    signature: Uint8Array;
+    keyId: string;
+}
+export interface AuditPackRecordFailure {
+    /** 1-based position in the file, for a record so broken it has no id. */
+    index: number;
+    certificateId: string;
+    /** Go's VerificationResult name; "" when the record never reached the verifier. */
+    offline: string;
+    /** Go's TransparencyResult name; "" when the record never reached the verifier. */
+    transparency: string;
+    reason: string;
+}
+/** Mirrors core.AuditPackResult. */
+export interface AuditPackResult {
+    verdict: AuditPackVerdict;
+    /** Empty on VERIFIED; every finding otherwise, joined with "; ". */
+    reason: string;
+    header: AuditPackHeader | null;
+    footer: AuditPackFooter | null;
+    /** Record lines the file carries, refused ones included. */
+    records: number;
+    /** Records whose envelope label is REVOKED. The label is unsigned. */
+    revoked: number;
+    /** Records with no transparency proof yet. Not a failure. */
+    notIncluded: number;
+    failed: AuditPackRecordFailure[];
+    logHead: AuditPackLogHead;
+    /** The key that verified the head, when one did. */
+    logHeadKeyId: string;
+    /** No key set was supplied, so the pack's own issuer_keys were used. */
+    keysFromPack: boolean;
+    digest: string;
+    /** Records a signed status statement was obtained for, and those whose
+     * statement said REVOKED. Neither refuses the pack. */
+    statusChecked: number;
+    statusRevoked: number;
+    revokedIds: string[];
+    /** What the footer's signature established, UNSIGNED when it carries none.
+     * Only VALID means the issuer attested to the count and digest; any other
+     * refusal is INVALID for the page. */
+    footerStatement: AuditPackFooterResult;
+    footerKeyId: string;
+    /** The parsed run record when the header carries one; runResult its
+     * signature verdict and runInclusion its own proof's, both "" without one.
+     * runSubjects and runRecordIds are what this page contributes to
+     * reproducing the record's roots — a reader holding every page of the run's
+     * chain checks them with checkRunAgainstRecords. runMislabelled counts
+     * records whose own signed run_id names another run; each is also refused. */
+    run: RunRecord | null;
+    runResult: RunRecordResult | "";
+    runInclusion: string;
+    runSubjects: Uint8Array[];
+    runRecordIds: string[];
+    runMislabelled: number;
+}
+export interface AuditPackOptions {
+    /** Step 8, per record. null means no statement could be had, which leaves
+     * the record at VALID_REVOCATION_UNKNOWN exactly as offline. */
+    status?: (certificateId: string) => Promise<Record<string, unknown> | null>;
+}
+/** The one definition of the footer's records_sha256: SHA-256 over every
+ * record line followed by a newline, in file order, with a trailing carriage
+ * return stripped. Mirrors core.AuditPackDigest. */
+export declare function auditPackDigest(crypto: CryptoOps, lines: Uint8Array[]): Promise<string>;
+/** Verify one page offline, exactly as core.VerifyAuditPackWith does.
+ *
+ * `keys` null means the pack's own issuer_keys are used and the result says so
+ * (trust on first use). A supplied map — even an empty one — outranks them.
+ * `now` is the reader's clock, used to read a status statement's window.
+ */
+export declare function verifyAuditPack(crypto: CryptoOps, source: string | Uint8Array, keys: Map<string, PublicKeyInfo> | null, now: Date, opts?: AuditPackOptions): Promise<AuditPackResult>;
+/** The canonical signing payload of a footer statement. Optional fields are
+ * omitted rather than encoded as null, as in every other statement: a page
+ * with no filter must sign the same bytes a verifier rebuilds from it. Mirrors
+ * core.BuildAuditPackFooterPayload. */
+export declare function buildAuditPackFooterPayload(s: AuditPackFooterStatement): Uint8Array;
+/** Checks a footer statement against the reader's keys, in the order every
+ * other verifier uses: the key's authority first, then the signature. Mirrors
+ * core.VerifyAuditPackFooter. A statement whose payload cannot be built is
+ * INVALID_SIGNATURE, as there. */
+export declare function verifyAuditPackFooter(crypto: CryptoOps, s: AuditPackFooterStatement, keys: Map<string, PublicKeyInfo>): Promise<AuditPackFooterResult>;
+/** Rebuilds the signed statement from a page's header and footer, as
+ * core.AuditPackFooter.Statement does. Throws for an unsigned footer, and for
+ * signed fields that do not parse, rather than returning a statement that
+ * would verify against nothing. */
+export declare function auditPackFooterStatement(header: AuditPackHeader, footer: AuditPackFooter): AuditPackFooterStatement;
+export interface AuditPackPage {
+    name: string;
+    cursor: string | null;
+    nextCursor: string | null;
+}
+/** Orders a set of pages by their cursors and says whether they are one
+ * complete answer: exactly one first page, each next_cursor met by a page that
+ * resumes from it, every file used, and a last page with no next cursor. The
+ * returned order is as far as the chain could be followed. */
+export declare function chainAuditPackPages(pages: AuditPackPage[]): {
+    order: AuditPackPage[];
+    complete: boolean;
+    reason: string;
+};
+//# sourceMappingURL=audit-pack.d.ts.map

package/dist/cjs/audit-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-pack.d.ts","sourceRoot":"","sources":["../../src/audit-pack.ts"],"names":[],"mappings":"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"}