imbas-verify 0.0.0-stage → 0.1.0

package/dsse.js

@@ -0,0 +1,258 @@
+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");
+}
+/**
+ * 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 function signEnvelope(payload, key, payloadType = DSSE_PAYLOAD_TYPE) {
+    return {
+        payloadType,
+        payload: payload.toString("base64"),
+        // ECDSA signatures are DER-encoded here, not IEEE-P1363. Both are legitimate for
+        // ECDSA and they are not interchangeable: DER is a tagged ASN.1 SEQUENCE of r and
+        // s, P1363 is raw r||s. DER is chosen because it is what `openssl dgst -verify`
+        // reads without extra flags, and an independent check that needs Imbas-specific
+        // instructions is not independent. `signBytes` pins `dsaEncoding: "der"` to match.
+        signatures: [{ keyid: key.keyid, sig: signatureOver(payloadType, payload, key) }],
+    };
+}
+/** The base64 signature over the PAE bytes for a payload. Shared by both signers. */
+function signatureOver(payloadType, payload, key) {
+    return key.signBytes(pae(payloadType, payload)).toString("base64");
+}
+/** The base64 signature over the PAE bytes of an in-toto statement. */
+function attestationSignature(payload, key) {
+    return signatureOver(DSSE_PAYLOAD_TYPE, payload, key);
+}
+/**
+ * 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 function counterSignEnvelope(envelope, payload, key) {
+    if (envelope.signatures.some((signature) => signature.keyid === key.keyid)) {
+        throw new Error(`This envelope is already signed by ${key.keyid.slice(0, 16)}…. A counter-signature has to come from a second key, or it proves nothing.`);
+    }
+    if (envelope.payload !== payload.toString("base64")) {
+        throw new Error("The payload does not match the one the envelope carries, so a signature over it would attest different bytes than the existing signatures cover.");
+    }
+    return {
+        payloadType: envelope.payloadType,
+        payload: envelope.payload,
+        signatures: [...envelope.signatures, { keyid: key.keyid, sig: attestationSignature(payload, key) }],
+    };
+}
+/**
+ * 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 };
+}

package/key.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The installation key.
+ *
+ * Every signed record Imbas produces is signed by one key pair that belongs to this
+ * installation and nowhere else. That is a deliberate limit, not a shortcoming:
+ * Sigstore's keyless flow publishes the signer's identity to a public transparency
+ * log, and an operator running Imbas on their own machine should not have to announce
+ * to the world that they approved a change. So the key is local, the public half is
+ * the only thing that ever leaves, and what a signature proves is bounded by that —
+ * see `proves` / `does_not_prove` in the predicate.
+ *
+ * The private key is written once, with the tightest permission the OS offers, and is
+ * never read into a response, a log line, a provenance record or an export. Nothing
+ * in this module hands it out: `loadOrCreateKey` returns a handle whose only outward
+ * key material is `publicPem()`. The private PEM lives in a closure, so a caller
+ * cannot find it by spreading the object or serialising it.
+ */
+import { type KeyObject } from "node:crypto";
+/** Where the installation key lives inside a data dir. */
+export declare function keyDir(dataDir: string): string;
+export declare function privateKeyPath(dataDir: string): string;
+export declare function publicKeyPath(dataDir: string): string;
+/** sha256 of arbitrary bytes, hex. The DER export is bytes, so this is not `ids.sha256`. */
+export declare function sha256Bytes(bytes: Buffer): string;
+/**
+ * The keyid: sha256 of the DER SubjectPublicKeyInfo, hex.
+ *
+ * Over the DER rather than the PEM on purpose. PEM is base64 of the DER with line
+ * breaks and a header, so two encoders can produce different PEM text for the same
+ * key — and a keyid that changed with the formatting would be useless as an
+ * identifier of the key. The DER is the key; the PEM is a way of writing it down.
+ */
+export declare function keyIdOf(publicKey: KeyObject): string;
+/** Reads a keyid from a PEM public key without creating anything. */
+export declare function keyIdOfPem(publicPem: string): string;
+/**
+ * Reads a keyid, or null when the text is not a public key at all.
+ *
+ * Verifying is often the first thing anyone runs on a fresh machine, with a key file
+ * they were handed and did not inspect. A DER file, a private key, an HTML error page
+ * saved by mistake — all of these should produce "that is not a public key" and not a
+ * stack trace from node:crypto. The distinction matters: an unhandled exception tells
+ * the operator the tool is broken, when the truth is that their input is wrong.
+ */
+export declare function tryKeyIdOfPem(text: string): string | null;
+export declare class KeyError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * The installation key, as the rest of the engine sees it.
+ *
+ * There is no `privatePem` field, and that is the point: the private key exists only
+ * inside the closure these methods share, so no caller can log it, serialise the
+ * handle and find it, or return it from an endpoint by spreading the object.
+ */
+export interface InstallationKey {
+    /** sha256 of the DER SPKI, hex. The `keyid` in every envelope. */
+    readonly keyid: string;
+    /** The public key as PEM. The only key material that may leave the process. */
+    publicPem(): string;
+    /** ECDSA P-256 / SHA-256 over these bytes. DER-encoded, as `sign` returns. */
+    signBytes(bytes: Buffer): Buffer;
+}
+/**
+ * Verifies a signature against a PEM public key.
+ *
+ * `dsaEncoding: "der"` is the default and is stated because it is load-bearing:
+ * ECDSA signatures have two encodings, DER and IEEE-P1363 ("raw"), and a verifier that
+ * guesses wrong reports a valid signature as forged. DER is what `openssl dgst
+ * -verify` expects, which is what makes an independent check possible at all.
+ */
+export declare function verifyBytes(publicPem: string, bytes: Buffer, signature: Buffer): boolean;
+/** Builds a handle around a private key already in memory. */
+export declare function handleFor(privateKey: KeyObject, publicPem: string, keyid: string): InstallationKey;
+/**
+ * Loads the installation key, generating it on first use.
+ *
+ * Creating it lazily rather than at install time keeps the promise simple: the key
+ * exists when it is first needed, in the data dir, with no separate setup step that
+ * can be skipped and leave signing broken later.
+ */
+export declare function loadOrCreateKey(dataDir: string): InstallationKey;
+/**
+ * Loads or creates a key pair at explicit paths.
+ *
+ * Extracted so the policy key — which signs retirement lists and must be a *different*
+ * key from the one that signs records — shares one implementation with the installation
+ * key rather than a copy. A second copy of the permission dance is a second place for it to
+ * drift, and the drift would be invisible on Windows where the mode bits are advisory.
+ */
+export declare function loadOrCreateNamedKey(privatePath: string, publicPath: string): InstallationKey;
+/**
+ * The policy key: what signs a retirement list, and nothing else.
+ *
+ * A second key for one reason, and it is the whole reason this exists. The attack key
+ * retirement defends against is a **stolen installation key**. If the retirement list were
+ * signed by that same key, the thief could hand out a confident "no keys were ever
+ * retired" and clear themselves — the list would prove nothing against exactly the threat
+ * it was built for. A policy key that can be kept somewhere else is what makes the list
+ * worth signing at all.
+ *
+ * It is created on first use like the installation key, so an operator who never retires
+ * anything never gets one. `docs/EVIDENCE.md` is explicit about the limit this does *not*
+ * remove: on a single machine both private keys sit in the same directory, and whoever
+ * holds the policy key can sign a false list.
+ */
+export declare function policyKeyDir(dataDir: string): string;
+export declare function policyPrivateKeyPath(dataDir: string): string;
+export declare function policyPublicKeyPath(dataDir: string): string;
+export declare function loadOrCreatePolicyKey(dataDir: string): InstallationKey;
+/** An in-memory key pair, for tests and the demo. Never written to disk. */
+export declare function ephemeralKey(): InstallationKey;
+/**
+ * Builds a signing handle from a private key PEM already in memory.
+ *
+ * The counter-signing path needs this: a second party signs a record with a key that is
+ * not this installation's, and `loadOrCreateKey` would be wrong in two ways — it reads the
+ * data dir, and it *creates* a key when there is none. A counter-signer who silently
+ * generated a fresh key would sign with something nobody has the public half of, and the
+ * record would carry a signature no verifier could ever check.
+ *
+ * Refuses anything that is not a private key, by name, rather than throwing an OpenSSL
+ * error. The keyid is derived from the public half of the same key, so a handle can never
+ * disagree with itself about which key it is.
+ */
+export type PrivateKeyRead = {
+    ok: true;
+    key: InstallationKey;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function handleFromPrivatePem(text: string): PrivateKeyRead;

package/key.js

@@ -0,0 +1,208 @@
+/**
+ * The installation key.
+ *
+ * Every signed record Imbas produces is signed by one key pair that belongs to this
+ * installation and nowhere else. That is a deliberate limit, not a shortcoming:
+ * Sigstore's keyless flow publishes the signer's identity to a public transparency
+ * log, and an operator running Imbas on their own machine should not have to announce
+ * to the world that they approved a change. So the key is local, the public half is
+ * the only thing that ever leaves, and what a signature proves is bounded by that —
+ * see `proves` / `does_not_prove` in the predicate.
+ *
+ * The private key is written once, with the tightest permission the OS offers, and is
+ * never read into a response, a log line, a provenance record or an export. Nothing
+ * in this module hands it out: `loadOrCreateKey` returns a handle whose only outward
+ * key material is `publicPem()`. The private PEM lives in a closure, so a caller
+ * cannot find it by spreading the object or serialising it.
+ */
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** Where the installation key lives inside a data dir. */
+export function keyDir(dataDir) {
+    return join(resolve(dataDir), "keys");
+}
+export function privateKeyPath(dataDir) {
+    return join(keyDir(dataDir), "installation-key.pem");
+}
+export function publicKeyPath(dataDir) {
+    return join(keyDir(dataDir), "installation-key.pub.pem");
+}
+/** sha256 of arbitrary bytes, hex. The DER export is bytes, so this is not `ids.sha256`. */
+export function sha256Bytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * The keyid: sha256 of the DER SubjectPublicKeyInfo, hex.
+ *
+ * Over the DER rather than the PEM on purpose. PEM is base64 of the DER with line
+ * breaks and a header, so two encoders can produce different PEM text for the same
+ * key — and a keyid that changed with the formatting would be useless as an
+ * identifier of the key. The DER is the key; the PEM is a way of writing it down.
+ */
+export function keyIdOf(publicKey) {
+    return sha256Bytes(publicKey.export({ type: "spki", format: "der" }));
+}
+/** Reads a keyid from a PEM public key without creating anything. */
+export function keyIdOfPem(publicPem) {
+    return keyIdOf(createPublicKey(publicPem));
+}
+/**
+ * Reads a keyid, or null when the text is not a public key at all.
+ *
+ * Verifying is often the first thing anyone runs on a fresh machine, with a key file
+ * they were handed and did not inspect. A DER file, a private key, an HTML error page
+ * saved by mistake — all of these should produce "that is not a public key" and not a
+ * stack trace from node:crypto. The distinction matters: an unhandled exception tells
+ * the operator the tool is broken, when the truth is that their input is wrong.
+ */
+export function tryKeyIdOfPem(text) {
+    try {
+        return keyIdOfPem(text);
+    }
+    catch {
+        return null;
+    }
+}
+export class KeyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "KeyError";
+    }
+}
+/**
+ * Verifies a signature against a PEM public key.
+ *
+ * `dsaEncoding: "der"` is the default and is stated because it is load-bearing:
+ * ECDSA signatures have two encodings, DER and IEEE-P1363 ("raw"), and a verifier that
+ * guesses wrong reports a valid signature as forged. DER is what `openssl dgst
+ * -verify` expects, which is what makes an independent check possible at all.
+ */
+export function verifyBytes(publicPem, bytes, signature) {
+    let key;
+    try {
+        key = createPublicKey(publicPem);
+    }
+    catch {
+        return false;
+    }
+    try {
+        return verify("sha256", bytes, { key, dsaEncoding: "der" }, signature);
+    }
+    catch {
+        // A malformed signature (wrong length, garbage) makes `verify` throw rather than
+        // return false. Both mean "not verified", and only one of them is an exception.
+        return false;
+    }
+}
+/** Builds a handle around a private key already in memory. */
+export function handleFor(privateKey, publicPem, keyid) {
+    return {
+        keyid,
+        publicPem: () => publicPem,
+        signBytes: (bytes) => sign("sha256", bytes, { key: privateKey, dsaEncoding: "der" }),
+    };
+}
+/**
+ * Loads the installation key, generating it on first use.
+ *
+ * Creating it lazily rather than at install time keeps the promise simple: the key
+ * exists when it is first needed, in the data dir, with no separate setup step that
+ * can be skipped and leave signing broken later.
+ */
+export function loadOrCreateKey(dataDir) {
+    return loadOrCreateNamedKey(privateKeyPath(dataDir), publicKeyPath(dataDir));
+}
+/**
+ * Loads or creates a key pair at explicit paths.
+ *
+ * Extracted so the policy key — which signs retirement lists and must be a *different*
+ * key from the one that signs records — shares one implementation with the installation
+ * key rather than a copy. A second copy of the permission dance is a second place for it to
+ * drift, and the drift would be invisible on Windows where the mode bits are advisory.
+ */
+export function loadOrCreateNamedKey(privatePath, publicPath) {
+    if (!existsSync(privatePath)) {
+        mkdirSync(dirname(privatePath), { recursive: true });
+        const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+        const privatePem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+        const publicPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+        // Written with 0600 and then chmodded, which is belt and braces on POSIX and
+        // mostly a statement of intent on Windows: Windows does not map `chmod` onto a
+        // DACL, so `mode` and `chmodSync` are largely ignored there. On Windows the
+        // private key's protection comes from the ACL of the containing directory — the
+        // user's profile — not from this bit. Saying that plainly is better than implying
+        // a guarantee the platform does not give. On a shared Windows machine, securing
+        // the data dir is the operator's job and `docs/EVIDENCE.md` says so.
+        writeFileSync(privatePath, privatePem, { encoding: "utf8", mode: 0o600 });
+        writeFileSync(publicPath, publicPem, { encoding: "utf8", mode: 0o644 });
+        try {
+            chmodSync(privatePath, 0o600);
+        }
+        catch {
+            // A filesystem that cannot express modes (FAT32, some network shares) must not
+            // stop signing from working. The trade-off is documented in docs/EVIDENCE.md.
+        }
+    }
+    const privateKey = createPrivateKey(readFileSync(privatePath, "utf8"));
+    const publicKey = createPublicKey(privateKey);
+    const publicPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+    return handleFor(privateKey, publicPem, keyIdOf(publicKey));
+}
+/**
+ * The policy key: what signs a retirement list, and nothing else.
+ *
+ * A second key for one reason, and it is the whole reason this exists. The attack key
+ * retirement defends against is a **stolen installation key**. If the retirement list were
+ * signed by that same key, the thief could hand out a confident "no keys were ever
+ * retired" and clear themselves — the list would prove nothing against exactly the threat
+ * it was built for. A policy key that can be kept somewhere else is what makes the list
+ * worth signing at all.
+ *
+ * It is created on first use like the installation key, so an operator who never retires
+ * anything never gets one. `docs/EVIDENCE.md` is explicit about the limit this does *not*
+ * remove: on a single machine both private keys sit in the same directory, and whoever
+ * holds the policy key can sign a false list.
+ */
+export function policyKeyDir(dataDir) {
+    return join(resolve(dataDir), "keys");
+}
+export function policyPrivateKeyPath(dataDir) {
+    return join(policyKeyDir(dataDir), "policy-key.pem");
+}
+export function policyPublicKeyPath(dataDir) {
+    return join(policyKeyDir(dataDir), "policy-key.pub.pem");
+}
+export function loadOrCreatePolicyKey(dataDir) {
+    return loadOrCreateNamedKey(policyPrivateKeyPath(dataDir), policyPublicKeyPath(dataDir));
+}
+/** An in-memory key pair, for tests and the demo. Never written to disk. */
+export function ephemeralKey() {
+    const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+    return handleFor(privateKey, publicKey.export({ type: "spki", format: "pem" }).toString(), keyIdOf(publicKey));
+}
+export function handleFromPrivatePem(text) {
+    let privateKey;
+    try {
+        privateKey = createPrivateKey(text);
+    }
+    catch {
+        return {
+            ok: false,
+            message: "The signing key is not a PEM private key (it does not begin with -----BEGIN PRIVATE KEY----- or -----BEGIN EC PRIVATE KEY-----).",
+        };
+    }
+    // `createPrivateKey` also accepts a *public* key PEM in some builds, and signing with
+    // one fails deep inside OpenSSL. Asking for the private half first turns that into a
+    // sentence at the boundary.
+    if (privateKey.type !== "private") {
+        return {
+            ok: false,
+            message: `The signing key is a ${privateKey.type} key. Counter-signing needs the private half.`,
+        };
+    }
+    const publicPem = createPublicKey(privateKey).export({ type: "spki", format: "pem" }).toString();
+    return { ok: true, key: handleFor(privateKey, publicPem, tryKeyIdOfPem(publicPem) ?? keyIdOfPem(publicPem)) };
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "imbas-verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Check a signed Imbas approval record without the engine. Verifies signatures, the patch digest and the provenance chain head; reads only the files you name.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "imbas-verify": "./verify-cli.js"
+  },
+  "main": "./verify.js",
+  "types": "./verify.d.ts",
+  "exports": {
+    ".": {
+      "types": "./verify.d.ts",
+      "default": "./verify.js"
+    },
+    "./args": {
+      "types": "./args.d.ts",
+      "default": "./args.js"
+    }
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md",
+    "FORMAT.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "attestation",
+    "provenance",
+    "supply-chain",
+    "dsse",
+    "in-toto",
+    "verification"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}