@entpoind/verify 0.0.0-stage → 0.2.0

package/dist/witness.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @entpoind/verify — the receipt ledger's public witness: a batch root's entry in the Sigstore Rekor log.
+ *
+ * What the ledger logs (runtime/shared/rekor-witness.ts, by the hourly cron job):
+ *
+ *   rootMessage   the canonical JSON the batch's `rootSignature` is over (ledgerRootMessage)
+ *   A             SHA-512(UTF-8 rootMessage)            `witness.artifactSha512`
+ *   data.hash     SHA-512(A)                            `witness.rekorSha512`, the hash in the `hashedrekord` entry
+ *   signature     Ed25519ph by the region's receipt key, the SAME key (`kid`) as the root's, with A as the message,
+ *                 so its prehash is SHA-512(A) = data.hash
+ *
+ * Offline (always): the witness's hashes are recomputed from the root message, the witness is by the root's key, its
+ * Ed25519ph signature verifies over the recomputed hash with that key, and the copy of the log's answer the proof carries
+ * (`body`, `entryUuid`, `inclusionProof`) is that entry and hangs together. That copy came from Entpoind, so it shows the
+ * witness is consistent, not that the log holds it.
+ *
+ * Online (opt-in): the entry is fetched from the log itself and checked again, with the log's own inclusion proof,
+ * signed checkpoint and signed entry timestamp verified against the log's public key (ECDSA P-256, as rekor.sigstore.dev
+ * uses). The key is pinned by the caller, or fetched from the log, which is then trust on first use; the result says which.
+ *
+ * Nothing here can fail the receipt or the ledger proof: a witness that is absent, off, pending, inconsistent or
+ * unreachable is reported as exactly that, next to a ledger proof that verified on its own. `off` means the receipt's
+ * workspace had turned the public witness off before the receipt was batched: the batch's root was never submitted, by
+ * the workspace's choice. It is not a failure.
+ */
+export declare const WITNESS_KIND = "rekor.hashedrekord.v0.0.1";
+export declare const DEFAULT_REKOR_URL = "https://rekor.sigstore.dev";
+export declare const WITNESS_LOG_TIMEOUT_MS = 10000;
+/** `witness` in the ledger proof, as the Tools Worker serves it. */
+export type LedgerWitness = 
+/** The workspace had turned the public witness off when the batch was built; its root is never submitted. */
+{
+    status: "off";
+} | {
+    status: "pending";
+    since: string;
+    attempts: number;
+    lastError: string | null;
+    nextAttemptAt: string | null;
+} | {
+    status: "logged";
+    kind: string;
+    log: string;
+    logIndex: number;
+    entryUuid: string;
+    integratedTime: number;
+    integratedAt: string;
+    searchUrl: string;
+    entryUrl: string;
+    artifactSha512: string;
+    rekorSha512: string;
+    signature: string;
+    signatureKeyId: string;
+    logId: string;
+    body: string;
+    inclusionProof: {
+        logIndex: number;
+        rootHash: string;
+        treeSize: number;
+        hashes: string[];
+        checkpoint: string;
+    } | null;
+    signedEntryTimestamp: string;
+};
+/** Why a logged witness is not consistent with the ledger proof. Each is exact: several can be reported at once. */
+export type WitnessProblem = 
+/** A field the check needs is missing or of the wrong type. */
+"malformed_witness" | "unknown_witness_kind"
+/** `artifactSha512` is not SHA-512 of the root message. */
+ | "artifact_hash_mismatch"
+/** `rekorSha512` is not SHA-512 of the artifact: not the hash the root message gives. */
+ | "rekor_hash_mismatch"
+/** `signatureKeyId` is not the key that signed the root. */
+ | "not_the_root_key"
+/** The Ed25519ph signature does not verify over the recomputed hash with the root's key. */
+ | "bad_witness_signature"
+/** The log entry (`body`) is not a decodable `hashedrekord`. */
+ | "entry_body_malformed"
+/** The entry's `data.hash` is not `{ sha512, <the recomputed hash> }`. */
+ | "entry_hash_mismatch"
+/** The entry's public key is not the root's key. */
+ | "entry_key_mismatch"
+/** The entry's signature is not the witness signature. */
+ | "entry_signature_mismatch"
+/** `entryUuid` does not end in the RFC 6962 leaf hash of the entry. */
+ | "entry_uuid_mismatch"
+/** The copied inclusion proof does not fold the entry to the root hash it names. */
+ | "inclusion_proof_invalid"
+/** `integratedAt` is not the instant `integratedTime` names. */
+ | "integrated_at_mismatch";
+/** What the log itself said, when it was asked (`witnessLog`). */
+export type WitnessLogProblem = 
+/** The log has no entry with that UUID (404). */
+"entry_not_in_log" | "bad_log_response" | "entry_uuid_mismatch" | "entry_body_malformed" | "entry_hash_mismatch" | "entry_key_mismatch" | "bad_witness_signature"
+/** The log's `logIndex` / `integratedTime` are not the ones the proof states. */
+ | "log_index_mismatch" | "integrated_time_mismatch"
+/** The log's public key could not be fetched, is not ECDSA P-256, or does not hash to the entry's `logID`. */
+ | "log_key_unavailable" | "log_key_unsupported" | "log_key_not_log_id" | "bad_signed_entry_timestamp" | "no_inclusion_proof" | "inclusion_proof_invalid" | "checkpoint_malformed"
+/** The checkpoint names another tree size or root hash than the inclusion proof. */
+ | "checkpoint_mismatch" | "bad_checkpoint_signature";
+export type WitnessPart = "verified" | "failed" | "not_checked";
+export type WitnessLogCheck = 
+/** The log was not asked, or did not answer: nothing about the witness was judged. */
+{
+    checked: false;
+    logUrl: string;
+    reason: "log_url_not_https" | "no_entry_uuid" | "log_unreachable" | "log_error";
+    status?: number;
+} | {
+    checked: true;
+    logUrl: string;
+    /** True only when every part below is `verified` and there is no problem. */
+    ok: boolean;
+    problems: WitnessLogProblem[];
+    /** `pinned`: the caller's `logPublicKey`. `fetched`: from the log's own /api/v1/log/publicKey, trust on first use. */
+    logKey: "pinned" | "fetched" | "unavailable";
+    /** The log's time for the entry (Unix seconds), as the log answered. */
+    integratedTime: number | null;
+    inclusionProof: WitnessPart;
+    checkpoint: WitnessPart;
+    signedEntryTimestamp: WitnessPart;
+};
+export type WitnessReport = 
+/** The proof carries no witness: the batch has not been submitted yet, or the witness is not switched on. */
+{
+    status: "absent";
+}
+/**
+ * Not witnessed, by the workspace's choice: its owner or admin had turned the public witness off before this receipt was
+ * batched, so the batch's root was never submitted to the log. Not a failure, and nothing to retry.
+ */
+ | {
+    status: "off";
+}
+/** Tried, not in the log yet. The batch itself is complete. */
+ | {
+    status: "pending";
+    since: string | null;
+    attempts: number | null;
+    lastError: string | null;
+    nextAttemptAt: string | null;
+}
+/** A `witness` whose status is none of the three the API defines (`off`, `pending`, `logged`). */
+ | {
+    status: "malformed";
+} | {
+    status: "logged";
+    /** The witness is the root's: its hashes, key and signature, and the copy of the log's answer, all check out. */
+    consistent: boolean;
+    problems: WitnessProblem[];
+    log: string | null;
+    logIndex: number | null;
+    entryUuid: string | null;
+    integratedAt: string | null;
+    searchUrl: string | null;
+    /** Present only when the log was asked (`witnessLog`). */
+    logCheck?: WitnessLogCheck;
+};
+export type WitnessLogOptions = {
+    /** Overrides the proof's `witness.log`. Must be https. Default: the proof's, else https://rekor.sigstore.dev. */
+    logUrl?: string;
+    /** The log's public key (SubjectPublicKeyInfo PEM) to verify its signatures with. Without it, the key is fetched from the log. */
+    logPublicKey?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+};
+export type WitnessContext = {
+    /** The message the root signature is over, rebuilt from the proof. */
+    rootMessage: string;
+    /** The root's key id, and its key from the published set (already used to verify the root). */
+    signatureKeyId: string;
+    publicKeyX: string;
+};
+/** Never throws: anything the witness holds that cannot be checked is a problem, reported. */
+export declare function checkLedgerWitness(witness: unknown, ctx: WitnessContext, log?: WitnessLogOptions): Promise<WitnessReport>;