imbas-verify 0.0.0-stage → 0.1.1

package/retirement.d.ts

@@ -0,0 +1,337 @@
+import { type DsseEnvelope } from "./dsse.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.
+ */
+/**
+ * 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.
+ */
+/**
+ * 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;