imbas-verify 0.0.0-stage → 0.1.0

package/attestation.js

@@ -0,0 +1,260 @@
+/**
+ * Making and verifying an attestation, end to end.
+ *
+ * This is the seam between "a record Imbas can build" and "a file someone else can
+ * check". The two halves are deliberately separate functions with no shared state:
+ * `attest` has the signing key and never verifies; `verify` has only public material
+ * and never signs. A verifier that could reach the signing key would not be a
+ * verifier, and a test that used the signing key to check its own output would prove
+ * only that the code is self-consistent.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { APPROVAL_PREDICATE_TYPE, DSSE_PAYLOAD_TYPE, IN_TOTO_STATEMENT_TYPE, counterSignEnvelope, verifyEnvelopeSignatures, } from "./dsse.js";
+import { tryKeyIdOfPem } from "./key.js";
+import { judgeRetirement } from "./retirement.js";
+import { readStatement } from "./statement.js";
+/*
+ * `attest` lives in `./attest-produce.js`, not here.
+ *
+ * It is the only function in this module that needs `predicate.ts`, and `predicate.ts`
+ * reaches the pipeline, the gate helpers and the provenance store. Keeping it here meant
+ * that importing the *verifier* pulled the engine's pipeline into its closure — 10
+ * modules against the 5 a verifier actually uses. The verifier is given away on the
+ * promise that checking a record needs nothing from Imbas, and this boundary is what keeps
+ * that true; `engine/test/verify-standalone.test.ts` asserts it.
+ */
+/** Writes an attestation as JSON. Two-space indent, so a human diff is readable. */
+export function writeAttestation(file, path) {
+    writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, "utf8");
+}
+/**
+ * Adds a counter-signature to an existing record.
+ *
+ * The order of operations is the security property, and it is not negotiable:
+ *
+ *   1. verify every existing signature over the payload, and refuse if any fails;
+ *   2. decode the payload those signatures actually cover;
+ *   3. sign *those bytes*, unchanged.
+ *
+ * A counter-signer who signed without step 1 would be endorsing a record they had not
+ * read, and their signature would add the appearance of a second opinion to a forged
+ * document. Step 2 rather than re-serialising the `statement` field is the same lesson as
+ * `attest`: the bytes that travel are the bytes that were signed, never a rebuild.
+ *
+ * Throws rather than returning a result. A caller who asked to counter-sign has already
+ * decided to vouch for a record, and a silent failure would leave them believing they had.
+ */
+export function counterSign(file, keys, counterKey) {
+    const verified = verifyEnvelopeSignatures(file.envelope, keys);
+    if (!verified.ok) {
+        throw new Error(`Refusing to counter-sign: the record does not verify first (${verified.check}). ${verified.message}`);
+    }
+    /*
+     * The readable copy must agree with the signed bytes.
+     *
+     * `statement` exists so a reader need not base64-decode; it is not the signed thing. But
+     * a file whose readable copy says one thing while the signature covers another is worse
+     * than no file at all — a reader who trusts the readable form has been lied to by a
+     * record that verifies. `attest` refuses to write such a file; a counter-signer must
+     * refuse to *endorse* one, because their signature would make the lie look vouched for.
+     */
+    const signed = readStatement(verified.payload);
+    if (!signed.ok || JSON.stringify(signed.statement) !== JSON.stringify(file.statement)) {
+        throw new Error("Refusing to counter-sign: the readable `statement` in this file does not match the bytes the signature covers. The file was edited after it was signed, so what a reader sees is not what was attested.");
+    }
+    // `verified.payload` is the decoded payload that every signature above was checked
+    // against, so signing it attests the same bytes rather than a re-serialisation.
+    const envelope = counterSignEnvelope(file.envelope, verified.payload, counterKey);
+    return {
+        ...file,
+        envelope,
+        counter_signature: {
+            signers: envelope.signatures.map((signature) => signature.keyid),
+            counter_signed_at: new Date().toISOString(),
+        },
+    };
+}
+function isEnvelope(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.payloadType === "string" &&
+        typeof candidate.payload === "string" &&
+        Array.isArray(candidate.signatures));
+}
+/**
+ * Verifies a signed record.
+ *
+ * The signature check comes before anything is read out of the payload, and that order
+ * is the whole security property: statement fields are parsed only after the bytes are
+ * known to be the bytes that were signed. Reading first would mean acting on
+ * unauthenticated input, which is how a "verify" function ends up trusting a tampered
+ * file for the length of one bug.
+ */
+export function verifyAttestation(inputs) {
+    const { file, publicPem, patch, requireKeyids } = inputs;
+    if (typeof file !== "object" || file === null) {
+        return { ok: false, check: "file_json", message: "The file is not a JSON object." };
+    }
+    const pems = typeof publicPem === "string" ? [publicPem] : [...publicPem];
+    if (pems.length === 0) {
+        return {
+            ok: false,
+            check: "key_not_public",
+            message: "No public key was supplied, so nothing can be checked.",
+        };
+    }
+    // Every key is checked before the envelope, so a bad key file says what is wrong with
+    // the key rather than reporting "signature does not verify" against nothing.
+    const keys = [];
+    for (const pem of pems) {
+        const keyid = tryKeyIdOfPem(pem);
+        if (keyid === null) {
+            return {
+                ok: false,
+                check: "key_not_public",
+                message: `One of the keys supplied is not a PEM public key (it does not begin with -----BEGIN PUBLIC KEY-----).`,
+            };
+        }
+        keys.push({ publicPem: pem, keyid });
+    }
+    const envelope = file.envelope;
+    if (!isEnvelope(envelope)) {
+        return {
+            ok: false,
+            check: "envelope_shape",
+            message: "The file has no DSSE envelope, or the envelope is malformed.",
+        };
+    }
+    /*
+     * Every signature, not the first one.
+     *
+     * A single-signature record takes the same path with a list of one, so there is no
+     * second implementation to keep in step. What it buys is the case this whole slice
+     * exists for: a counter-signed record whose second signature is wrong fails, rather
+     * than passing because the first one happened to verify.
+     */
+    const verification = verifyEnvelopeSignatures(envelope, keys, {
+        requireKeyids: requireKeyids ?? [],
+    });
+    if (!verification.ok) {
+        return { ok: false, check: verification.check, message: verification.message };
+    }
+    const payload = verification.payload;
+    if (payload === null) {
+        return { ok: false, check: "payload_encoding", message: "The payload could not be decoded." };
+    }
+    const read = readStatement(payload);
+    if (!read.ok) {
+        return { ok: false, check: read.check, message: read.message };
+    }
+    if (patch !== undefined) {
+        const subject = read.statement.subject[0];
+        const digest = subject?.digest.sha256 ?? "";
+        // The patch bytes exactly as they are in the file. A verifier checking a patch it
+        // normalised first (line endings, trailing newline) would report a false mismatch
+        // for an honest file, so the comparison is over the raw bytes and says so.
+        const actual = sha256Hex(patch);
+        if (actual !== digest) {
+            return {
+                ok: false,
+                check: "subject_digest",
+                message: `The patch file hashes to ${actual.slice(0, 16)}…, but the record names ${digest.slice(0, 16)}…. This is not the patch that was approved, byte for byte.`,
+            };
+        }
+    }
+    /**
+     * Every keyid whose signature verified, so a caller can ask about each of them.
+     *
+     * A retirement is per-key, and a counter-signed record has more than one signer. Asking
+     * only about the first would let a record whose *second* signature came from a disowned
+     * key report clean.
+     */
+    const retirement = judgeEverySigner(inputs.retirements ?? null, verification.satisfied, read.statement);
+    if (!retirement.ok) {
+        return retirement;
+    }
+    /*
+     * The keyid reported is the signer whose *record* signature this is, meaning the first
+     * key the verifier holds that signed. With one key that is that key; with two it is
+     * whichever came first in the supplied list, which is why the outcome also carries
+     * `signers` — a caller reporting "verified by X" needs the whole list, not a guess.
+     */
+    return {
+        ok: true,
+        statement: read.statement,
+        keyid: verification.satisfied[0] ?? keys[0].keyid,
+        signers: verification.satisfied,
+        retirements: retirement.verdicts,
+    };
+}
+/**
+ * Asks the retirement list about each verified signer.
+ *
+ * Returns the refusal when a signature was made *after* its key was retired, and the
+ * verdicts otherwise. `retired_after_signing` is reported, not refused: the record is
+ * genuinely signed and was genuine when it was made, so failing it would retroactively
+ * convict every honest approval a machine ever produced. A verifier who needs to refuse it
+ * asks for that with `requireLiveKeyids`.
+ */
+function judgeEverySigner(list, signers, statement) {
+    const completedAt = statement.predicate.completed_at ?? null;
+    if (list === null) {
+        // No list supplied. Every signer is unchecked, which is *not* "not listed": the caller
+        // must be able to tell "I checked and found nothing" from "I was given nothing to
+        // check against". Both are reported as `not_listed` only when a list was supplied.
+        return { ok: true, verdicts: signers.map((keyid) => ({ keyid, state: "unchecked" })) };
+    }
+    const verdicts = [];
+    for (const keyid of signers) {
+        const verdict = judgeRetirement(list, keyid, { completedAt });
+        if (verdict.state === "retired_before_signing") {
+            return {
+                ok: false,
+                check: "key_retired_before_signing",
+                message: `This record was sealed at ${completedAt ?? "(no completed_at)"}, but key ${keyid.slice(0, 16)}… was retired at ${verdict.retirement.retired_at} — ${verdict.retirement.reason}. A signature by a key its own operator had already disowned is not evidence that they approved anything.`,
+            };
+        }
+        verdicts.push({ keyid, ...verdict });
+    }
+    return { ok: true, verdicts };
+}
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+export function readAttestationFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (cause) {
+        // A missing path, a directory, a permissions problem. Distinct from "not JSON",
+        // because "I cannot read that file" and "that file is not a record" send the
+        // operator to different places.
+        const code = cause.code ?? "unknown";
+        return {
+            ok: false,
+            check: "file_unreadable",
+            message: `Cannot read ${path} (${code}).`,
+        };
+    }
+    if (text.trim().length === 0) {
+        return { ok: false, check: "file_json", message: `${path} is empty, so it holds no record.` };
+    }
+    try {
+        return { ok: true, file: JSON.parse(text) };
+    }
+    catch {
+        // The parser's own message is deliberately not passed on: it quotes the offending
+        // text, which for a large file is a wall of noise, and it says nothing the operator
+        // can act on that "this is not JSON" does not.
+        return {
+            ok: false,
+            check: "file_json",
+            message: `${path} is not JSON. A signed record is the .json file downloaded from Imbas.`,
+        };
+    }
+}
+/** Re-exported so a caller needs one import for the whole flow. */
+export { APPROVAL_PREDICATE_TYPE, DSSE_PAYLOAD_TYPE, IN_TOTO_STATEMENT_TYPE, };

package/describe.d.ts

@@ -0,0 +1,8 @@
+/**
+ * How the verifier describes a retirement list's own signature.
+ *
+ * Split out so `verify.ts` can print this without importing `attest.ts`.
+ */
+import type { ListSignatureState } from "./retirement.js";
+/** One sentence per list-signature state, in the words the docs use. */
+export declare function describeListSignature(state: ListSignatureState): string;

package/describe.js

@@ -0,0 +1,15 @@
+/** One sentence per list-signature state, in the words the docs use. */
+export function describeListSignature(state) {
+    switch (state.state) {
+        case "signed":
+            return `signed by policy key ${state.keyid.slice(0, 16)}...`;
+        case "unsigned":
+            return "UNSIGNED - this list carries no signature, so nothing proves the policy key wrote it";
+        case "unverified_signature":
+            return "signed, but no policy key was supplied to check it - the signature was not verified";
+        case "unknown_signer":
+            return `signed by ${state.keyid.slice(0, 16)}..., which is not the policy key you supplied`;
+        case "signature_invalid":
+            return `SIGNATURE INVALID - ${state.message}`;
+    }
+}

package/dsse.d.ts

@@ -0,0 +1,146 @@
+/**
+ * DSSE: the envelope around a signed record.
+ *
+ * The format is not invented here. It is the Dead Simple Signing Envelope from the
+ * in-toto attestation spec, because a record whose signature can only be checked by
+ * the program that made it is a record nobody else can check. Choosing a published
+ * format is what lets a third party verify an Imbas approval with nothing but the
+ * public key and `openssl` — no Imbas code, no Imbas trust.
+ *
+ * The envelope carries a payload (here, an in-toto Statement), a payloadType, and a
+ * signature over the *serialised pair* rather than over the payload alone. That
+ * distinction is the whole point of PAE: if the signature covered only the payload,
+ * an attacker could relabel the payloadType and the same signature would still verify
+ * while the bytes meant something different.
+ */
+import type { InstallationKey } from "./key.js";
+/** What a DSSE envelope's payload is. in-toto statements are JSON. */
+export declare const DSSE_PAYLOAD_TYPE = "application/vnd.in-toto+json";
+/** The in-toto Statement type. */
+export declare const IN_TOTO_STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+/** Imbas's own predicate type: an approval. Nothing else claims this URI. */
+export declare const APPROVAL_PREDICATE_TYPE = "https://somernorth.co.uk/imbas/attestation/approval/v1";
+export interface DsseSignature {
+    /** The keyid of the signing key: sha256 of the DER SPKI, hex. */
+    keyid: string;
+    /** ECDSA P-256 / SHA-256 signature over the PAE bytes, DER-encoded, base64. */
+    sig: string;
+}
+export interface DsseEnvelope {
+    payloadType: string;
+    /** The statement, base64. */
+    payload: string;
+    signatures: DsseSignature[];
+}
+/**
+ * Pre-Authentication Encoding, exactly as the DSSE spec defines it:
+ *
+ *   PAE(type, body) = "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body
+ *
+ * where SP is one space and LEN is the length in *bytes*, written in ASCII decimal.
+ *
+ * The length prefixes are not decoration. Without them, ("ab", "c") and ("a", "bc")
+ * encode to the same string, so a signature that verified one would verify the other.
+ * Lengths in bytes rather than characters for the same reason one level down: a
+ * payload with non-ASCII text has more bytes than characters, and counting characters
+ * would both short-count and split a UTF-8 sequence.
+ *
+ * The spec's own test vector is asserted in the tests:
+ *   PAE("http://example.com/HelloWorld", "hello world")
+ *     = "DSSEv1 29 http://example.com/HelloWorld 11 hello world"
+ */
+export declare function pae(payloadType: string, payload: Buffer): Buffer;
+/**
+ * Strict base64 decoding.
+ *
+ * `Buffer.from(text, "base64")` is lenient: it skips characters it does not
+ * recognise and stops at the first invalid one. That is fine for reading a file and
+ * wrong for verifying a signature, because a tampered payload that decodes "well
+ * enough" would be checked against a signature over different bytes and the failure
+ * would look like bad crypto rather than bad encoding. This rejects it outright.
+ */
+export declare function decodeBase64(text: string): Buffer | null;
+/**
+ * Signs a payload, producing a one-signature envelope.
+ *
+ * `payloadType` defaults to the in-toto statement type because almost every envelope here
+ * carries one. The retirement list passes its own: the type is part of the PAE bytes the
+ * signature covers, so it must be chosen *before* signing. Relabelling an envelope
+ * afterwards would leave a signature over one document beside a file claiming to be
+ * another, and nothing would verify it.
+ */
+export declare function signEnvelope(payload: Buffer, key: InstallationKey, payloadType?: string): DsseEnvelope;
+/**
+ * Adds a second, independent signature to an envelope that is already signed.
+ *
+ * This is what makes one installation's word checkable by another. The payload is not
+ * touched — not re-serialised, not reformatted — because the whole value of the first
+ * signature is that it covers these exact bytes. A counter-signature over a
+ * re-serialised copy would be a signature over a different document that happened to
+ * mean the same thing, which is not the same claim.
+ *
+ * The payload arrives as bytes rather than as the envelope's base64 for one reason: the
+ * caller must have already verified the existing signature and decoded it. Adding a
+ * signature to bytes nobody has checked would let a counter-signer endorse a forged
+ * record, and the parameter shape makes that obligation visible at the call site rather
+ * than leaving it to a comment. See `verifyEnvelopeSignatures`, which is how a caller
+ * earns the right to call this.
+ *
+ * Refuses a key that already signed. Two signatures with one keyid make "signed by whom"
+ * ambiguous, and an ambiguous answer is worse than a refused request: a reader would
+ * count two signatures and conclude two parties.
+ */
+export declare function counterSignEnvelope(envelope: DsseEnvelope, payload: Buffer, key: InstallationKey): DsseEnvelope;
+/**
+ * Which check failed, so a verifier can say the first one rather than "invalid".
+ *
+ * An operator looking at a failed verification needs to know whether the record was
+ * altered, whether they were handed the wrong key, or whether they asked the wrong
+ * question. "Signature invalid" collapses all three.
+ */
+export type EnvelopeCheck = "payload_type" | "payload_encoding" | "signature_present" | "keyid" | "signature";
+/** One signature's fate, for the per-signature report a reader needs. */
+export interface SignatureCheck {
+    keyid: string;
+    ok: boolean;
+    check: EnvelopeCheck | null;
+    message: string | null;
+}
+export type MultiSignatureVerification = {
+    ok: true;
+    payload: Buffer;
+    signatures: SignatureCheck[];
+    satisfied: string[];
+} | {
+    ok: false;
+    payload: Buffer | null;
+    signatures: SignatureCheck[];
+    satisfied: string[];
+    check: EnvelopeCheck | "keyid_missing" | "counter_signature_required";
+    message: string;
+};
+/**
+ * Verifies every signature on an envelope against the keys supplied.
+ *
+ * The property that matters: **each signature must verify over the same payload.** DSSE
+ * signatures cover PAE(payloadType, payload), so an attacker cannot move a signature from
+ * one document to another — but a *reader* can still be misled by counting. This function
+ * therefore reports per-signature results rather than a single boolean, so "two
+ * signatures, one of which does not verify" is visible instead of rounding to "signed by
+ * two parties".
+ *
+ * `requireKeyids` is the counter-signature check. A reader who needs a second party to
+ * have seen the record passes the keyids they require, and a record missing one fails at
+ * `counter_signature_required` rather than passing because *a* key signed it.
+ *
+ * An unknown keyid is `keyid_missing`, not `signature`: "I have no key for this signer"
+ * and "this signature is wrong" are different findings, and a verifier holding one of two
+ * keys must not be told the record is forged.
+ */
+export declare function verifyEnvelopeSignatures(envelope: DsseEnvelope, keys: readonly {
+    publicPem: string;
+    keyid: string;
+}[], options?: {
+    requireKeyids?: readonly string[];
+    expectedPayloadType?: string;
+}): MultiSignatureVerification;