imbas-verify 0.0.0-stage → 0.1.0

package/read-file.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reads a text file, returning a named failure instead of throwing.
+ *
+ * The same reasoning as `readAttestationFile`: a path the operator typed wrong must
+ * produce "cannot read that file", not a stack trace from `node:fs`. Verify is usually
+ * the first thing anyone runs on a fresh machine, with paths they were given.
+ */
+export type TextRead = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    check: "key_unreadable";
+    message: string;
+};
+export declare function readTextFile(path: string): TextRead;
+/**
+ * Reads a file as raw bytes, for the patch.
+ *
+ * Separate from `readTextFile` because the patch digest is over bytes. Decoding to a
+ * string and re-encoding would go through UTF-8 a second time, and a patch is not
+ * guaranteed to be valid UTF-8 - the digest would then be of different bytes than the
+ * ones that were approved, and an honest file would report a mismatch.
+ */
+export type BinaryRead = {
+    ok: true;
+    bytes: Buffer;
+} | {
+    ok: false;
+    check: "patch_unreadable";
+    message: string;
+};
+export declare function readBinaryFile(path: string): BinaryRead;

package/read-file.js

@@ -0,0 +1,25 @@
+/**
+ * File reads that return a named failure instead of throwing.
+ *
+ * Split from `attest.ts` for the same reason as `verify.ts`: the verifier needs these and
+ * nothing else in that module needs the engine.
+ */
+import { readFileSync } from "node:fs";
+export function readTextFile(path) {
+    try {
+        return { ok: true, text: readFileSync(path, "utf8") };
+    }
+    catch (cause) {
+        const code = cause.code ?? "unknown";
+        return { ok: false, check: "key_unreadable", message: `Cannot read ${path} (${code}).` };
+    }
+}
+export function readBinaryFile(path) {
+    try {
+        return { ok: true, bytes: readFileSync(path) };
+    }
+    catch (cause) {
+        const code = cause.code ?? "unknown";
+        return { ok: false, check: "patch_unreadable", message: `Cannot read ${path} (${code}).` };
+    }
+}

package/record.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The shape of the signed approval predicate, declared once.
+ *
+ * These interfaces lived in `predicate.ts`, beside the code that *builds* them. That was
+ * wrong for one reason: `attestation.ts` (the verifier) needs to name the type, and a type
+ * import still makes the compiler load the module it names. `predicate.ts` imports the
+ * gates, the pipeline state and the provenance store, so verifying a record dragged the
+ * whole engine into the program — and, in the published verifier, into the closure.
+ *
+ * Declaring them here means the verifier names nothing outside the package at all — not
+ * even in a type import. That matters twice over: a type import still makes the compiler
+ * load the named module while building, and it writes the name into the emitted `.d.ts`,
+ * where a consumer who installed only this package would see `any` or a typecheck error.
+ *
+ * `StageId` and `GateKind` therefore carry local declarations rather than imports, and
+ * `engine/test/verify-standalone.test.ts` asserts they still agree with the contract.
+ *
+ * `predicate.ts` re-exports everything in this file, so existing imports are unchanged.
+ * There is still exactly one declaration of the predicate: this one.
+ */
+export type StageId = "intake" | "research" | "plan" | "build" | "review" | "demo" | "notify" | "handoff";
+export type GateKind = "operator" | "engineer";
+/** What the record says about one gate. */
+export interface PredicateGate {
+    stage: StageId;
+    kind: GateKind;
+    /** The decision, or null if the gate was never decided. */
+    decision: "approve" | "reject" | null;
+    gate_id: string;
+    /**
+     * The artifact this gate decided, or null at a decision-only stage.
+     *
+     * HANDOFF produces nothing, so there is nothing to point at. Null says that
+     * plainly; a placeholder id would claim an artifact that never existed.
+     */
+    artifact_id: string | null;
+    requested_at: string;
+    decided_at: string | null;
+    principal_id: string | null;
+    principal_role: string | null;
+    authenticated_via: string | null;
+    /** Which explainer the approver acknowledged. Invariant 5, recorded. */
+    acknowledged_explainer_id: string | null;
+    explainer_view: string | null;
+}
+/** One stage in the pipeline that did not run. */
+export interface PredicateNotRun {
+    stage: StageId;
+    /**
+     * Why, in the words that were shown when the stage was stepped over. Copied from
+     * the `stage_unavailable` record's explainer, never rewritten for the signature: a
+     * reason that reads differently in the record than in the log is a reason a reader
+     * cannot check.
+     */
+    reason: string;
+}
+/** One override, with the per-finding reasons exactly as they were recorded. */
+export interface PredicateOverride {
+    override_id: string;
+    stage: StageId;
+    overridden_verdict: "changes_requested";
+    reviewer_artifact_id: string;
+    reviewer_principal_id: string;
+    reason: string;
+    finding_reasons: Array<{
+        finding_id: string;
+        reason: string;
+    }>;
+    /** Who set the verdict aside, and when. */
+    principal_id: string | null;
+    decided_at: string | null;
+    /** The provenance record carrying it, so a reader can find it in the chain. */
+    record_id: string;
+}
+/** A model that took part, and what it was, exactly as provenance recorded it. */
+export interface PredicateModel {
+    stage: StageId;
+    adapter: string;
+    provider: string;
+    model: string;
+    mocked: boolean;
+    prompt_version: string | null;
+}
+export interface ApprovalPredicate {
+    /** The name and version of this predicate, so a reader can find the definition. */
+    predicate_name: "imbas.approval";
+    predicate_version: "1";
+    schema_version: string;
+    job_id: string;
+    job_title: string;
+    sample: boolean;
+    created_at: string;
+    completed_at: string;
+    /** Every gate in the job, in pipeline order. */
+    gates: PredicateGate[];
+    /** Every override, in the order they were recorded. */
+    overrides: PredicateOverride[];
+    /**
+     * Every stage in the pipeline that did not run, and why, copied from its
+     * `stage_unavailable` record.
+     *
+     * Signed rather than only logged, because the claim this record makes is "production
+     * was authorised for what was actually checked". A job that reached the engineer gate
+     * with DEMO and NOTIFY unexecuted is still a legitimate job — but a reader of the
+     * record must be able to see the gap without also being trusted to have read the
+     * chain. Empty means every stage ran; it is never derived by subtracting from the
+     * list of stages that happened to produce an artifact.
+     */
+    stages_not_run: PredicateNotRun[];
+    /** Every adapter that produced an artifact, in the order they ran. */
+    models: PredicateModel[];
+    /** The head of the provenance chain. Verifying the chain verifies this many records. */
+    provenance: {
+        head_hash: string;
+        record_count: number;
+        chain_valid: boolean;
+    };
+    /** The versions the record was produced under, so a reader can place it in time. */
+    versions: {
+        contracts: string;
+        glossary: string;
+    };
+    /** The installation whose key signed this. */
+    installation_keyid: string;
+    proves: string[];
+    does_not_prove: string[];
+}

package/record.js

@@ -0,0 +1 @@
+export {};

package/retirement.d.ts

@@ -0,0 +1,353 @@
+import { type DsseEnvelope } from "./dsse.js";
+import { type InstallationKey } from "./key.js";
+/** One retirement, as it appears in the list. */
+export interface KeyRetirement {
+    keyid: string;
+    /** ISO 8601. Records signed at or after this moment are the alarming ones. */
+    retired_at: string;
+    /** Why. Free text: "laptop stolen", "machine decommissioned". */
+    reason: string;
+    /** When the entry was written. Equal to `retired_at` for a timely retirement. */
+    recorded_at: string;
+    /**
+     * The keyid that replaces this one, when there is one.
+     *
+     * A **note**, not a proof. It says the operator intends that key to be used from here on;
+     * it says nothing about whether that key is trustworthy, whether the holder is the same
+     * person, or whether it was ever used. The only thing that makes the note worth reading is
+     * the policy key's signature over the whole list.
+     *
+     * Optional on purpose. A laptop that was stolen has no successor, and making the field
+     * required would turn "the key is gone" into a malformed entry. `undefined` and
+     * "superseded by B" are different facts and both are legitimate.
+     */
+    supersedes?: string;
+}
+export interface RetirementList {
+    schema_version: string;
+    retirements: KeyRetirement[];
+}
+/**
+ * A retirement list and the signature over it.
+ *
+ * The signature covers `entries` — the object holding `retirements` — and **not** the
+ * envelope that carries it, exactly as an attestation's signature covers the statement
+ * rather than the file. What a verifier must be able to establish is "these are the entries
+ * the policy key signed", and nothing about how the file was laid out.
+ *
+ * The payload is serialised once by `sealList` and those bytes are what travel. A verifier
+ * re-serialising the entries to check the signature would be checking a document that
+ * happened to mean the same thing, which is the failure the counter-signature slice spent
+ * its whole length avoiding.
+ */
+export interface SignedRetirementList {
+    /** The entries, exactly as signed. */
+    entries: {
+        retirements: KeyRetirement[];
+        schema_version: string;
+    };
+    /** The DSSE envelope over the canonical bytes of `entries`; null when unsigned. */
+    envelope: DsseEnvelope | null;
+}
+/** What a verifier concluded about the list's own integrity. */
+export type ListSignatureState = 
+/** The list carries an envelope and it verifies against the policy key supplied. */
+{
+    state: "signed";
+    keyid: string;
+}
+/** The list is a bare list of entries with no envelope at all. */
+ | {
+    state: "unsigned";
+}
+/** An envelope is present but does not verify — the entries are not the signed ones. */
+ | {
+    state: "signature_invalid";
+    message: string;
+}
+/** The envelope verifies against a keyid the verifier supplied no key for. */
+ | {
+    state: "unknown_signer";
+    keyid: string;
+}
+/** An envelope is present, but the verifier supplied no policy key to check it with. */
+ | {
+    state: "unverified_signature";
+};
+/**
+ * The version this code writes.
+ *
+ * 2.0.0 added `supersedes`. It is a major bump rather than a minor one because the entries
+ * are **signed**: a list written at 1.0.0 and a list written at 2.0.0 are different
+ * documents, and a verifier re-serialising one to check the other would produce bytes that
+ * never existed. Calling that a minor change would invite exactly that mistake.
+ */
+export declare const RETIREMENT_SCHEMA_VERSION = "2.0.0";
+/** The payload type for a retirement list. Distinct from an attestation's, so a list can
+ *  never be presented as a record or the other way round. */
+export declare const RETIREMENT_PAYLOAD_TYPE = "application/vnd.imbas.retirements+json";
+export declare class RetirementError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Where the retirement list lives inside a data dir. */
+export declare function retirementsPath(dataDir: string): string;
+/**
+ * Reads a retirement list, or returns an empty one when the file does not exist.
+ *
+ * **A missing file is an empty list, and that is not the same as "nothing is retired".**
+ * The caller must be able to tell those apart, so this returns `found` alongside the list
+ * and `lookupRetirement` reports `unknown` rather than `live` when the keyid is absent.
+ * Collapsing the two would make every verifier who was never handed a list report a
+ * confident "key not retired", which is the exact overclaim this whole module exists to
+ * avoid.
+ */
+export type RetirementRead = {
+    ok: true;
+    list: RetirementList;
+    found: boolean;
+    /**
+     * The signature state, when the file carried an envelope. `null` means the file was a
+     * bare list with nothing to check — which `verifyListSignature` reports as `unsigned`.
+     *
+     * Carried here rather than checked here: this function's job is to read a file, and
+     * checking a signature needs a policy key the reader may not have. It reports what it
+     * saw so the caller can decide.
+     */
+    envelope: DsseEnvelope | null;
+} | {
+    ok: false;
+    code: "retirements_json" | "retirements_unreadable";
+    message: string;
+};
+export declare function readRetirementList(path: string): RetirementRead;
+/**
+ * Validates a parsed retirement list.
+ *
+ * Strict about shape and lenient about nothing, because the failure mode of a
+ * half-understood retirement list is a verifier that silently checks fewer entries than
+ * its author wrote. An entry missing `retired_at` would otherwise become `undefined`, and
+ * `new Date(undefined)` is an Invalid Date that compares false against everything — so a
+ * malformed entry would read as "retired after all records", or as "retired never",
+ * depending on which way the comparison fell. Refusing the file is the only safe answer.
+ */
+export declare function parseRetirementList(value: unknown): {
+    ok: true;
+    list: RetirementList;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * True when the text is an ISO 8601 timestamp that names a real instant.
+ *
+ * `new Date("nonsense")` produces an Invalid Date rather than throwing, and every
+ * comparison against an Invalid Date is `false` — including `>=` and `<=`. A timestamp
+ * that cannot be compared is worse than a missing one, because it silently answers "no"
+ * to every question asked of it.
+ */
+export declare function isIsoDate(text: string): boolean;
+/**
+ * Appends a retirement.
+ *
+ * Refuses a duplicate keyid. Retiring the same key twice would produce a list where an
+ * earlier moment and a later one both claim to be the retirement, and a comparison that
+ * read the wrong one would call a post-retirement record genuine. The refusal is by name
+ * so an operator who runs the command twice learns what happened.
+ *
+ * Refuses to move a retirement *earlier* as well, for the same reason in the other
+ * direction: shortening the trusted period after records have been signed would
+ * retroactively disown approvals the operator made in good faith. A later retirement is
+ * a widening of trust, and this refuses that too — a list whose entries can be revised is
+ * a list a verifier cannot reason about.
+ */
+export declare function appendRetirement(input: {
+    path: string;
+    keyid: string;
+    retiredAt: string;
+    reason: string;
+    now?: string;
+    /** The keyid that replaces this one, when the operator is rotating rather than losing it. */
+    supersedes?: string;
+    /** The policy key. Required for a signed list; absent writes a bare, unsigned one. */
+    policyKey?: InstallationKey;
+}): KeyRetirement;
+/**
+ * Serialises the entries once and signs those bytes.
+ *
+ * `JSON.stringify` without indentation, not the two-space form the file is written with.
+ * The signature must cover a canonical byte string so that a verifier can reproduce it from
+ * `entries` alone without knowing how the writer chose to format the file. Key order is
+ * insertion order, which is deterministic for a given object, and the entries are built in
+ * one place — so a re-serialisation by `verifyListSignature` produces the same bytes.
+ */
+export declare function sealList(entries: {
+    schema_version: string;
+    retirements: KeyRetirement[];
+}, key: InstallationKey): SignedRetirementList;
+/**
+ * Checks the signature over a list, before any entry is read.
+ *
+ * Returns one of five states rather than a boolean, because "there is no signature", "the
+ * signature is wrong" and "I was given no key to check it with" are three different facts
+ * and only one of them says somebody tampered.
+ *
+ * `policyPem` is optional. When it is absent a signed list reports
+ * `unverified_signature` — a list that *has* a signature nobody checked, which is again
+ * different from a list with none. Collapsing those would let an operator hand a verifier
+ * an unsigned list and have it read as "unsigned is normal here".
+ */
+export declare function verifyListSignature(list: unknown, policyPem: string | null): {
+    ok: true;
+    state: ListSignatureState;
+    list: RetirementList;
+} | {
+    ok: false;
+    state: ListSignatureState;
+    message: string;
+};
+/** What a verifier can conclude about one keyid. */
+export type RetirementVerdict = 
+/** The keyid is in the list, and the record was signed at or after the retirement. */
+{
+    state: "retired_before_signing";
+    retirement: KeyRetirement;
+}
+/** The keyid is in the list, and the record was signed before the retirement. */
+ | {
+    state: "retired_after_signing";
+    retirement: KeyRetirement;
+}
+/** The keyid is not in the list the verifier holds. Says nothing about trust. */
+ | {
+    state: "not_listed";
+}
+/**
+ * The record names no signing moment this can be compared against, so the question
+ * cannot be answered. Distinct from both other answers: `not_listed` means "I looked
+ * and it is absent", this means "I could not look".
+ */
+ | {
+    state: "no_signing_time";
+    retirement: KeyRetirement;
+};
+/**
+ * What following the successors from one keyid produced.
+ *
+ * The two states that must never be confused are **"retired, and nothing replaced it"** and
+ * **"never retired at all"** — opposite facts about a key, and collapsing them would let a
+ * dead key read as live or a live one as dead.
+ *
+ * `path` is the walk itself, from the key asked about to the last retirement reached, so a
+ * reader can see A → B → C rather than being told a flat answer. Every path ends at a
+ * retirement; `state` says *why* the walk stopped there.
+ *
+ * Nothing here invents trust. A successor is a note the operator wrote; the only thing that
+ * makes it worth reading is the policy key's signature over the list it lives in.
+ */
+export type SuccessionChain = 
+/** The key asked about is not in the list. This says nothing about whether it is trusted. */
+{
+    state: "not_retired";
+    keyid: string;
+}
+/**
+ * The walk reached a retirement that names no successor — a stolen or decommissioned
+ * machine. A `path` of length one is the simple case: this key was retired and nothing
+ * replaced it.
+ */
+ | {
+    state: "retired_without_successor";
+    keyid: string;
+    path: SuccessionHop[];
+}
+/**
+ * The walk stopped because a retirement names a successor that is **not in this list**, so
+ * whether that key was itself retired cannot be said. Not an error: a successor is a note,
+ * not a proof, and a note may point outside the document that carries it.
+ */
+ | {
+    state: "successor_not_listed";
+    keyid: string;
+    path: SuccessionHop[];
+    successor: string;
+}
+/**
+ * The notes lead back to a key already walked. Only reachable from a hand-edited list,
+ * since both write paths refuse a self-successor. Reported rather than looped on, because
+ * a verifier that hangs on a malformed file is a denial of service of its own.
+ */
+ | {
+    state: "cycle";
+    keyid: string;
+    path: SuccessionHop[];
+    repeated: string;
+};
+/** One step of a succession walk: a keyid and the retirement record that ended its turn. */
+export type SuccessionHop = {
+    keyid: string;
+    retirement: KeyRetirement;
+};
+/**
+ * Follows the successors from a keyid, to the end of the chain.
+ *
+ * Read-only: it walks the signed list and invents nothing, signs nothing, and changes no
+ * trust. The walk terminates on the first key that is not retired, on a successor the list
+ * does not mention, or on a repeat — and reports *which* it was, because they mean
+ * different things to a reader deciding whether a signature is still worth anything.
+ *
+ * It checks no signature. Call `verifyListSignature` first: following an unverified list is
+ * following an unsigned claim, which this whole module exists to avoid.
+ */
+export declare function followSuccessors(list: RetirementList, keyid: string): SuccessionChain;
+/**
+ * The walk in one sentence.
+ *
+ * Deliberately talks about *notes* rather than trust. A chain ending at "key C" says the
+ * operator wrote down that C replaced B; it does not say C is trusted, or even that it
+ * exists. Nothing here is revocation, expiry, or a statement about time.
+ */
+export declare function describeSuccession(chain: SuccessionChain): string;
+/**
+ * One sentence per retirement state, in the words the docs use.
+ *
+ * Shared by the CLI and the API on purpose. Two copies would drift, and the drift would be
+ * invisible: an operator reading the terminal and a verifier reading the panel would be
+ * told subtly different things about the same record.
+ */
+export declare function describeVerdict(verdict: {
+    keyid: string;
+    state: "unchecked";
+} | {
+    keyid: string;
+    state: "not_listed";
+} | {
+    keyid: string;
+    state: "retired_after_signing";
+    retirement: KeyRetirement;
+} | {
+    keyid: string;
+    state: "no_signing_time";
+    retirement: KeyRetirement;
+} | undefined): string;
+/**
+ * Decides what the list says about a record signed by this keyid.
+ *
+ * **The signing moment is the whole record's, not one signature's.** An envelope does not
+ * carry a per-signature timestamp, and inventing one would be a claim the format does not
+ * make. So the question is asked of the record's *envelope* — the interval from the signed
+ * `created_at` to the signed `completed_at` — and the later end is what decides:
+ *
+ * - A record whose `completed_at` is at or after the retirement is `retired_before_signing`.
+ *   The key had been disowned by the time the record was sealed, so the signature claims
+ *   something its own operator had withdrawn.
+ * - A record whose `completed_at` is before the retirement is `retired_after_signing`: the
+ *   key was trusted throughout the job it describes.
+ *
+ * Using `completed_at` rather than `created_at` is deliberate. A long job that *started*
+ * before the retirement and finished after it was signed after the key was disowned. The
+ * earlier timestamp would launder exactly the case this feature exists to catch.
+ */
+export declare function judgeRetirement(list: RetirementList, keyid: string, signing: {
+    completedAt: string | null;
+}): RetirementVerdict;