@sanning/proof 0.11.1 → 0.13.0

package/dist/cli.d.ts

@@ -1,8 +1,139 @@
 #!/usr/bin/env node
+import { type WitnessLine } from "./case.js";
 interface Cli {
     out: (s: string) => void;
     err: (s: string) => void;
     fetchImpl?: typeof fetch;
 }
-export declare function runCli(argv: string[], io: Cli): Promise<number>;
+/** Each control character in `text` as a visible escape: `\x1b` for ESC,
+ * `\u202e` for RIGHT-TO-LEFT OVERRIDE. Every other character is unchanged, a
+ * backslash included, so a line with none is printed as it was. */
+export declare function escapeControl(text: string): string;
+export declare function runCli(argv: string[], stream: Cli): Promise<number>;
+/** The error text for an input with no pack in it, word for word the page's. */
+export declare const NO_BUNDLE = "No bundle.json found. An evidence pack contains bundle.json plus logs/.";
+/** A directory nested deeper than this below an argument refuses the input. */
+export declare const MAX_WALK_DEPTH = 32;
+/** More names than this, across every argument, refuse the input. */
+export declare const MAX_WALK_ENTRIES = 50000;
+/**
+ * `bundle.json` nested deeper than this is refused before it is parsed, by
+ * `verify` and by `case` alike (see `readBundleBytes`).
+ */
+export declare const MAX_JSON_DEPTH = 512;
+/**
+ * The input could not be read as a case. The message is the whole report,
+ * identical in both kernels, and the command exits 2 on it. `hint` is an
+ * optional second line naming a way through.
+ */
+export declare class CaseInputError extends Error {
+    readonly hint: string | null;
+    constructor(message: string, hint?: string | null);
+}
+/**
+ * `bundle.json` bytes that `readBundleBytes` will not read. `tooDeep` separates
+ * the one refusal that is not a parse error; `detail` is the parser's own words,
+ * which differ by kernel and are printed by `verify` only.
+ */
+export declare class BundleReadError extends Error {
+    readonly tooDeep: boolean;
+    readonly detail: string;
+    constructor(tooDeep: boolean, detail: string);
+}
+/**
+ * How both `verify` and `case` turn `bundle.json` bytes into JSON, in both
+ * kernels (`read_bundle_bytes` in the Python twin). UTF-8 with each ill-formed
+ * sequence read as U+FFFD, and a byte-order mark kept; then nesting deeper than
+ * MAX_JSON_DEPTH is refused before any parser walks into it; then `JSON.parse`.
+ * Throws `BundleReadError`.
+ */
+export declare function readBundleBytes(bytes: Uint8Array): unknown;
+export interface SplitPack {
+    ref: string;
+    bundlePath: string;
+    bundleBytes: Uint8Array;
+    /**
+     * `logs/<event_id>.json` bytes by event id. A `Map` and not an object: an
+     * event id is written by the audited party, and `obj["__proto__"] = bytes`
+     * replaces the prototype instead of storing the disclosure.
+     */
+    content: Map<string, Uint8Array>;
+    unaccounted: string[];
+}
+export interface SplitCase {
+    packs: SplitPack[];
+    /** Paths that belong to no pack, sorted. Never opened. */
+    outside: string[];
+    /** The part of `outside` that is not a regular file. Never followed, never opened. */
+    notRegular: string[];
+}
+/** One name the walk found that is not a directory. */
+export interface TreeEntry {
+    /** Where it sits on disk. Empty for an entry read out of a case-file `.zip`. */
+    fsPath: string;
+    /**
+     * `true` for a regular file; `false` for a link or anything else, including a
+     * `.zip` entry the reader refused.
+     */
+    regular: boolean;
+    /** The bytes of an entry read out of a case-file `.zip`. */
+    data?: Uint8Array | null;
+}
+/**
+ * The page's `splitCase` followed by its `assemble` per pack, over the walk's
+ * tree. `read` opens a file; it is called for the files a pack owns and for
+ * nothing else.
+ */
+export declare function splitCase(tree: Map<string, TreeEntry>, read: (entry: TreeEntry, key: string) => Promise<Uint8Array>): Promise<SplitCase>;
+/** `verify`'s reader, with the refusal named by the pack's path. */
+export declare function loadBundle(pack: SplitPack): unknown;
+/**
+ * A regular file's bytes. Opened without following a link and without
+ * blocking, then checked again, so a file swapped for a link or a pipe after
+ * the walk listed it is refused rather than followed or waited on.
+ */
+export declare function readFileEntry(entry: TreeEntry, key: string): Promise<Uint8Array>;
+/**
+ * Every name under the directories named, keyed `<name>/<path inside>`. Each
+ * argument must be a directory, and not a link to one. A `.zip` is refused
+ * with the way through.
+ */
+export declare function treeFromArguments(paths: readonly string[]): Promise<Map<string, TreeEntry>>;
+export declare const CASE_USAGE: string;
+interface OnChainRow {
+    ref: string;
+    witnesses: number;
+    confirmed: number;
+    mismatched: number;
+    unreachable: number;
+    not_checked: number;
+}
+interface OnChainHalf {
+    /** Present only where a lookup ran: each gateway that answered, in the order given. */
+    answered?: string[];
+    checked: boolean;
+    gateways: string[];
+    packs: OnChainRow[];
+    verdict: "not_checked" | "confirmed" | "failed" | "undetermined";
+}
+/**
+ * The witness line (evidence-bundle 5.5.6 v1.20, A24, D7) from the on-chain
+ * half: `confirmed` is `confirmed`, `not_checked` and `undetermined` are
+ * `not_checked` with the reason, and `failed` is `differs`. It never moves the
+ * headline.
+ */
+export declare function witnessLine(onChain: OnChainHalf): WitnessLine;
+/**
+ * The case verdict's code, moved only by an on-chain half that was asked for:
+ * a witness that does not match is a failure whatever the reading said, and an
+ * on-chain half that could not be settled is never a clean 0.
+ */
+export declare function caseExitCode(verdict: string, onChainVerdict: string): number;
+/**
+ * `proof case <folder>... [--gateways <urls>] [--json]`. Every path out of the
+ * command is an exit code from the table: an exception nobody expected exits 2,
+ * never 1, because 1 would name the evidence failed over a defect in this
+ * command.
+ */
+export declare function runCase(argv: readonly string[], stream: Cli): Promise<number>;
 export {};