imbas-verify 0.0.0-stage → 0.1.1

package/key.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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: the loader in `signing.ts` 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.
+ *
+ * This file is compiled into the published verifier, so it holds only what *checking* a
+ * signature needs. Key creation and signing live in `signing.ts`, which the verifier does
+ * not compile — the tool that checks the evidence must not be able to manufacture 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. */
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+/**
+ * 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;
+/** An in-memory key pair, for tests and the demo. Never written to disk. */
+/**
+ * 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;
+};

package/key.js

@@ -0,0 +1,142 @@
+/**
+ * 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: the loader in `signing.ts` 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.
+ *
+ * This file is compiled into the published verifier, so it holds only what *checking* a
+ * signature needs. Key creation and signing live in `signing.ts`, which the verifier does
+ * not compile — the tool that checks the evidence must not be able to manufacture it.
+ */
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { 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. */
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+/**
+ * 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");
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "imbas-verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "attestation",
+    "provenance",
+    "supply-chain",
+    "dsse",
+    "in-toto",
+    "verification"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/read-file.d.ts

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

package/read-file.js

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

package/record.d.ts

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

package/record.js

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