imbas-verify 0.0.0-stage → 0.1.1

package/attestation.js

@@ -0,0 +1,199 @@
+/**
+ * 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 } from "node:fs";
+import { APPROVAL_PREDICATE_TYPE, DSSE_PAYLOAD_TYPE, IN_TOTO_STATEMENT_TYPE, verifyEnvelopeSignatures, } from "./dsse.js";
+import { tryKeyIdOfPem } from "./key.js";
+import { judgeRetirement } from "./retirement.js";
+import { readStatement } from "./statement.js";
+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,130 @@
+/** 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.
+ */
+/** The base64 signature over the PAE bytes for a payload. Shared by both signers. */
+/** The base64 signature over the PAE bytes of an in-toto statement. */
+/**
+ * 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.
+ */
+/**
+ * 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;

package/dsse.js

@@ -0,0 +1,211 @@
+/**
+ * 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 { verifyBytes } from "./key.js";
+/** What a DSSE envelope's payload is. in-toto statements are JSON. */
+export const DSSE_PAYLOAD_TYPE = "application/vnd.in-toto+json";
+/** The in-toto Statement type. */
+export const IN_TOTO_STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+/** Imbas's own predicate type: an approval. Nothing else claims this URI. */
+export const APPROVAL_PREDICATE_TYPE = "https://somernorth.co.uk/imbas/attestation/approval/v1";
+/**
+ * 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 function pae(payloadType, payload) {
+    const typeBytes = Buffer.from(payloadType, "utf8");
+    return Buffer.concat([
+        Buffer.from(`DSSEv1 ${typeBytes.length} `, "ascii"),
+        typeBytes,
+        Buffer.from(` ${payload.length} `, "ascii"),
+        payload,
+    ]);
+}
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+/**
+ * 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 function decodeBase64(text) {
+    if (text.length % 4 !== 0 || !BASE64.test(text))
+        return null;
+    return Buffer.from(text, "base64");
+}
+/**
+ * Checks one signature over the given payload, returning the failure or null.
+ *
+ * Extracted so single- and multi-signature verification cannot drift: a second copy of
+ * base64 decoding and PAE construction is a second place to get the length prefixes
+ * wrong, and the failure would look like bad crypto rather than a typo.
+ */
+function checkOneSignature(payloadType, payload, signature, publicPem) {
+    const sigBytes = decodeBase64(signature.sig);
+    if (!sigBytes) {
+        return { check: "payload_encoding", message: "The signature is not valid base64." };
+    }
+    if (!verifyBytes(publicPem, pae(payloadType, payload), sigBytes)) {
+        return {
+            check: "signature",
+            message: "The signature does not verify against this key, so the record has changed since it was signed.",
+        };
+    }
+    return null;
+}
+/**
+ * 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 function verifyEnvelopeSignatures(envelope, keys, options = {}) {
+    /*
+     * The expected type defaults to the in-toto statement type, and that default is
+     * load-bearing: a verifier checking a signed record must refuse an envelope that carries
+     * something else, or a retirement list could be passed off as an approval. Callers that
+     * sign a different kind of document pass their own type — and because the type is part of
+     * the PAE bytes, choosing it wrongly fails the signature as well as the shape check.
+     */
+    const expectedPayloadType = options.expectedPayloadType ?? DSSE_PAYLOAD_TYPE;
+    if (envelope.payloadType !== expectedPayloadType) {
+        return {
+            ok: false,
+            payload: null,
+            signatures: [],
+            satisfied: [],
+            check: "payload_type",
+            message: `payloadType is "${envelope.payloadType}", expected "${expectedPayloadType}".`,
+        };
+    }
+    const payload = decodeBase64(envelope.payload);
+    if (!payload) {
+        return {
+            ok: false,
+            payload: null,
+            signatures: [],
+            satisfied: [],
+            check: "payload_encoding",
+            message: "The payload is not valid base64, so it cannot be the bytes that were signed.",
+        };
+    }
+    const byKeyid = new Map(keys.map((key) => [key.keyid, key.publicPem]));
+    // An envelope with no signatures must never verify. Without this, every check below is
+    // vacuously satisfied — no signature fails, no required keyid is missing because there is
+    // nothing to check it against — and the record would pass. The single-signature path had
+    // this check and the rewrite lost it, which is exactly the kind of hole a "verify" function
+    // must not have.
+    if (envelope.signatures.length === 0) {
+        return {
+            ok: false,
+            payload,
+            signatures: [],
+            satisfied: [],
+            check: "signature_present",
+            message: "The envelope carries no signature, so there is nothing to verify and nothing has been attested.",
+        };
+    }
+    const checks = envelope.signatures.map((signature) => {
+        const publicPem = byKeyid.get(signature.keyid);
+        if (publicPem === undefined) {
+            return {
+                keyid: signature.keyid,
+                ok: false,
+                check: "keyid",
+                message: `No key was supplied for signer ${signature.keyid.slice(0, 16)}…, so this signature was not checked.`,
+            };
+        }
+        const failure = checkOneSignature(envelope.payloadType, payload, signature, publicPem);
+        return {
+            keyid: signature.keyid,
+            ok: failure === null,
+            check: failure?.check ?? null,
+            message: failure?.message ?? null,
+        };
+    });
+    const satisfied = checks.filter((check) => check.ok).map((check) => check.keyid);
+    /*
+     * A record the verifier holds no key for is `keyid`, not `signature`.
+     *
+     * This was the second thing the rewrite lost. Without it, a record signed by another
+     * installation reports "the signature does not verify" — which is a different and much
+     * more alarming finding than "you were handed the wrong key". The order matters as much
+     * as the check: a genuine bad signature must still be called forged even when some
+     * signer is unknown, so a forged `signature` is reported before an unknown `keyid`.
+     */
+    const broken = checks.find((check) => !check.ok && check.check === "signature");
+    if (broken) {
+        return {
+            ok: false,
+            payload,
+            signatures: checks,
+            satisfied,
+            check: "signature",
+            message: `The signature from ${broken.keyid.slice(0, 16)}… does not verify. A record carrying a signature nobody can verify is not a record with fewer signatures; it is one somebody has altered.`,
+        };
+    }
+    if (satisfied.length === 0) {
+        const unknown = checks[0];
+        return {
+            ok: false,
+            payload,
+            signatures: checks,
+            satisfied,
+            check: "keyid",
+            message: `Signed by key ${unknown.keyid.slice(0, 16)}…, and no key you supplied matches it. Supply the public key of the installation that signed this record.`,
+        };
+    }
+    for (const required of options.requireKeyids ?? []) {
+        if (!satisfied.includes(required)) {
+            return {
+                ok: false,
+                payload,
+                signatures: checks,
+                satisfied,
+                check: "counter_signature_required",
+                message: `This record needs a counter-signature from ${required.slice(0, 16)}…, and it does not carry a valid one. One installation's word is not a second opinion.`,
+            };
+        }
+    }
+    return { ok: true, payload, signatures: checks, satisfied };
+}