@cejel/cejel 0.4.10 → 0.4.11

package/dist/index.js

@@ -21,19 +21,452 @@ import {
   runCejelScan,
   serializeWitanReport,
   verifyWitanAttestationBinding
-} from "./chunk-TUUNJP27.js";
-import "./chunk-IHT7B6L7.js";
-import "./chunk-GKYTLWQK.js";
+} from "./chunk-UBCIGOIP.js";
+import "./chunk-63XQDYQ5.js";
+import {
+  external_exports
+} from "./chunk-FSMZV3Y6.js";
 import {
   init_esm_shims
-} from "./chunk-PTZU6G4E.js";
+} from "./chunk-O3MHSK25.js";
 
 // src/index.ts
 init_esm_shims();
-import { createHash } from "crypto";
-import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
-import { join, resolve } from "path";
-import { pathToFileURL } from "url";
+import { createHash as createHash2 } from "crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+
+// src/issuance/index.ts
+init_esm_shims();
+
+// src/issuance/schemas.ts
+init_esm_shims();
+var WITAN_ISSUANCE_STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+var WITAN_ISSUANCE_PREDICATE_TYPE = "https://cejel.dev/attestations/issuance/v1";
+var WITAN_ISSUANCE_FORMAT_VERSION = "1.0";
+var WITAN_ISSUANCE_SIGNATURE_NAMESPACE = "cejel-issuance";
+var WITAN_ISSUANCE_PRINCIPAL = "issuance@barglabs.ai";
+var WITAN_ISSUER_NAME = "Barg Labs Inc.";
+var WitanIssuanceSubjectArtifactSchema = external_exports.enum(["report.json", "attestation.json"]);
+var WitanIssuanceStatementSchema = external_exports.object({
+  _type: external_exports.literal(WITAN_ISSUANCE_STATEMENT_TYPE),
+  subject: external_exports.array(
+    external_exports.object({
+      name: external_exports.string().min(1).max(300),
+      artifact: WitanIssuanceSubjectArtifactSchema,
+      digest: external_exports.object({ sha256: external_exports.string().regex(/^[a-f0-9]{64}$/) }).strict()
+    }).strict()
+  ).length(2),
+  predicateType: external_exports.literal(WITAN_ISSUANCE_PREDICATE_TYPE),
+  predicate: external_exports.object({
+    issuanceFormatVersion: external_exports.string().regex(/^1\.\d+$/),
+    issuer: external_exports.object({
+      name: external_exports.literal(WITAN_ISSUER_NAME),
+      // OpenSSH public-key fingerprint of the signing key, as printed by `ssh-keygen -lf`.
+      keyFingerprint: external_exports.string().regex(/^SHA256:[A-Za-z0-9+/]{43}$/)
+    }).strict(),
+    reproduction: external_exports.object({
+      sourceRevision: external_exports.string().min(7).max(64),
+      toolPackage: external_exports.literal("@cejel/cejel"),
+      toolVersion: external_exports.string().min(1).max(80),
+      rubricVersion: external_exports.string().min(1).max(120),
+      rubricBehaviourFingerprint: external_exports.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
+      reportByteIdentical: external_exports.literal(true)
+    }).strict(),
+    issuedAt: external_exports.string().datetime({ offset: true }),
+    // An opaque identifier the issuer chooses. The charset is enforced here; that the value
+    // is genuinely opaque and names no counterparty is a policy rule this schema cannot
+    // check — see docs/issuance.md.
+    engagementRef: external_exports.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{3,63}$/),
+    limitations: external_exports.array(external_exports.string().min(1).max(500)).min(1).max(8)
+  }).strict()
+}).strict();
+
+// src/issuance/issuance.ts
+init_esm_shims();
+import { createHash, createPublicKey, verify as cryptoVerify } from "crypto";
+var WITAN_ISSUANCE_LIMITATIONS = [
+  "Barg Labs Inc. attests only that it re-ran the named @cejel/cejel version at the named source revision and obtained byte-identical report.json content. It does not attest that the measurement itself is correct.",
+  "This is not a statement about the safety, security, correctness, or fitness for purpose of the software, and it carries no warranty or guarantee of any kind.",
+  "Nothing outside the pinned source tree was examined. Evidence absent from that tree was neither seen nor found to be absent.",
+  "Reproduction is not coverage. Cejel measures observable repository signals; a criterion it cannot measure is reported as unmeasured rather than scored, and this statement does not convert that into a pass."
+];
+var WITAN_ISSUANCE_SUPPORTED_KEY_TYPES = ["ssh-ed25519"];
+var SSHSIG_MAGIC = "SSHSIG";
+var SSHSIG_VERSION = 1;
+var SSHSIG_BEGIN = "-----BEGIN SSH SIGNATURE-----";
+var SSHSIG_END = "-----END SSH SIGNATURE-----";
+var SSHSIG_MAX_ARMORED_BYTES = 64 * 1024;
+var SSHSIG_HASH_ALGORITHMS = /* @__PURE__ */ new Set(["sha256", "sha512"]);
+var ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+var ED25519_PUBLIC_KEY_BYTES = 32;
+var ED25519_SIGNATURE_BYTES = 64;
+function serializeWitanIssuance(statement) {
+  return JSON.stringify(statement, null, 2);
+}
+function createWitanIssuanceStatement(report, options) {
+  const sourceRevision = report.repo.headSha;
+  if (!sourceRevision) {
+    throw new Error(
+      "Cejel: report.json records no repository revision (repo.headSha), so an issuance could not name what was reproduced."
+    );
+  }
+  return WitanIssuanceStatementSchema.parse({
+    _type: WITAN_ISSUANCE_STATEMENT_TYPE,
+    subject: [
+      {
+        name: `${report.productSlug}/report.json`,
+        artifact: "report.json",
+        digest: { sha256: options.reportSha256 }
+      },
+      {
+        name: `${report.productSlug}/attestation.json`,
+        artifact: "attestation.json",
+        digest: { sha256: options.attestationSha256 }
+      }
+    ],
+    predicateType: WITAN_ISSUANCE_PREDICATE_TYPE,
+    predicate: {
+      issuanceFormatVersion: WITAN_ISSUANCE_FORMAT_VERSION,
+      issuer: { name: WITAN_ISSUER_NAME, keyFingerprint: options.issuerKeyFingerprint },
+      reproduction: {
+        sourceRevision,
+        toolPackage: "@cejel/cejel",
+        toolVersion: options.toolVersion,
+        rubricVersion: report.rubricVersion,
+        ...report.rubricBehaviourFingerprint ? { rubricBehaviourFingerprint: report.rubricBehaviourFingerprint } : {},
+        reportByteIdentical: true
+      },
+      issuedAt: options.issuedAt,
+      engagementRef: options.engagementRef,
+      limitations: [...WITAN_ISSUANCE_LIMITATIONS]
+    }
+  });
+}
+function verifyWitanIssuanceBinding(statement, options) {
+  const parsed = WitanIssuanceStatementSchema.safeParse(statement);
+  if (!parsed.success) {
+    return {
+      valid: false,
+      errors: parsed.error.issues.map(
+        (issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`
+      )
+    };
+  }
+  const errors = [];
+  const reportSubject = parsed.data.subject.find((entry) => entry.artifact === "report.json");
+  const attestationSubject = parsed.data.subject.find(
+    (entry) => entry.artifact === "attestation.json"
+  );
+  if (!reportSubject) {
+    errors.push("issuance names no report.json subject");
+  } else {
+    if (reportSubject.digest.sha256 !== options.reportSha256) {
+      errors.push("issuance report.json subject digest does not match the supplied report.json");
+    }
+    if (reportSubject.name !== `${options.productSlug}/report.json`) {
+      errors.push("issuance report.json subject name does not match the report repository identity");
+    }
+  }
+  if (!attestationSubject) {
+    errors.push("issuance names no attestation.json subject");
+  } else {
+    if (attestationSubject.digest.sha256 !== options.attestationSha256) {
+      errors.push(
+        "issuance attestation.json subject digest does not match the supplied attestation.json"
+      );
+    }
+    if (attestationSubject.name !== `${options.productSlug}/attestation.json`) {
+      errors.push(
+        "issuance attestation.json subject name does not match the report repository identity"
+      );
+    }
+  }
+  if (parsed.data.predicate.reproduction.reportByteIdentical !== true) {
+    errors.push("issuance does not assert reportByteIdentical: true");
+  }
+  return { valid: errors.length === 0, errors };
+}
+var KEY_TYPE_PATTERN = /^(?:ssh-[a-z0-9]+|ecdsa-sha2-[a-z0-9-]+|sk-[a-z0-9-]+@openssh\.com|[a-z0-9-]+@openssh\.com)$/;
+function splitRespectingQuotes(line) {
+  const tokens = [];
+  let current = "";
+  let quoted = false;
+  for (const character of line) {
+    if (character === '"') {
+      quoted = !quoted;
+      current += character;
+      continue;
+    }
+    if (!quoted && /\s/.test(character)) {
+      if (current.length > 0) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += character;
+  }
+  if (quoted) throw new Error("unterminated quoted field");
+  if (current.length > 0) tokens.push(current);
+  return tokens;
+}
+function parseAllowedSigners(text) {
+  const entries = [];
+  const lines = text.split("\n");
+  for (const [index, rawLine] of lines.entries()) {
+    const line = rawLine.replace(/\r$/, "").trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    let tokens;
+    try {
+      tokens = splitRespectingQuotes(line);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`allowed-signers line ${index + 1}: ${message}`);
+    }
+    const [principalsToken, ...rest] = tokens;
+    if (!principalsToken) continue;
+    const keyTypeIndex = rest.findIndex((token) => KEY_TYPE_PATTERN.test(token));
+    if (keyTypeIndex === -1) {
+      throw new Error(`allowed-signers line ${index + 1}: no recognised key type`);
+    }
+    const keyType = rest[keyTypeIndex];
+    const keyBase64 = rest[keyTypeIndex + 1];
+    if (!keyType || !keyBase64) {
+      throw new Error(`allowed-signers line ${index + 1}: key type is not followed by a key`);
+    }
+    const optionText = rest.slice(0, keyTypeIndex).join(" ");
+    const entry = {
+      principals: principalsToken.split(",").map((principal) => principal.replace(/^"|"$/g, "").trim()).filter((principal) => principal.length > 0),
+      keyType,
+      keyBase64
+    };
+    if (optionText.length > 0) {
+      const namespacesMatch = /^namespaces="([^"]*)"$/.exec(optionText);
+      if (namespacesMatch?.[1] !== void 0) {
+        entry.namespaces = namespacesMatch[1].split(",").map((namespace) => namespace.trim()).filter((namespace) => namespace.length > 0);
+      } else {
+        entry.uninterpretedOptions = optionText;
+      }
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+function sshPublicKeyFingerprint(keyBlob) {
+  return `SHA256:${createHash("sha256").update(keyBlob).digest("base64").replace(/=+$/, "")}`;
+}
+var SshWireReader = class {
+  constructor(buffer) {
+    this.buffer = buffer;
+  }
+  buffer;
+  offset = 0;
+  readBytes(length) {
+    if (length < 0 || this.offset + length > this.buffer.length) {
+      throw new Error("truncated SSH wire encoding");
+    }
+    const slice = this.buffer.subarray(this.offset, this.offset + length);
+    this.offset += length;
+    return slice;
+  }
+  readUint32() {
+    return this.readBytes(4).readUInt32BE(0);
+  }
+  readString() {
+    return this.readBytes(this.readUint32());
+  }
+  get remaining() {
+    return this.buffer.length - this.offset;
+  }
+};
+function sshString(value) {
+  const payload = typeof value === "string" ? Buffer.from(value, "utf8") : value;
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(payload.length, 0);
+  return Buffer.concat([header, payload]);
+}
+function parseSshSignature(armored) {
+  if (armored.length > SSHSIG_MAX_ARMORED_BYTES) {
+    throw new Error("signature file is implausibly large for an SSH signature");
+  }
+  const lines = armored.split("\n").map((line) => line.replace(/\r$/, "").trim());
+  const begin = lines.indexOf(SSHSIG_BEGIN);
+  const end = lines.indexOf(SSHSIG_END);
+  if (begin === -1 || end === -1 || end <= begin) {
+    throw new Error("not an armored SSH signature (missing BEGIN/END SSH SIGNATURE lines)");
+  }
+  const body = lines.slice(begin + 1, end).join("");
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(body)) {
+    throw new Error("armored SSH signature body is not base64");
+  }
+  const blob = Buffer.from(body, "base64");
+  const reader = new SshWireReader(blob);
+  const magic = reader.readBytes(SSHSIG_MAGIC.length).toString("utf8");
+  if (magic !== SSHSIG_MAGIC) throw new Error("signature is missing the SSHSIG preamble");
+  const version = reader.readUint32();
+  if (version !== SSHSIG_VERSION) {
+    throw new Error(`unsupported SSHSIG version ${version}`);
+  }
+  const publicKeyBlob = reader.readString();
+  const namespace = reader.readString().toString("utf8");
+  const reserved = reader.readString();
+  if (reserved.length !== 0) throw new Error("SSHSIG reserved field is not empty");
+  const hashAlgorithm = reader.readString().toString("utf8");
+  const signatureBlob = reader.readString();
+  if (reader.remaining !== 0) throw new Error("trailing bytes after the SSHSIG structure");
+  const keyType = new SshWireReader(publicKeyBlob).readString().toString("utf8");
+  return { publicKeyBlob, keyType, namespace, hashAlgorithm, signatureBlob };
+}
+function ed25519PublicKeyFromBlob(publicKeyBlob) {
+  const reader = new SshWireReader(publicKeyBlob);
+  const keyType = reader.readString().toString("utf8");
+  if (keyType !== "ssh-ed25519") throw new Error(`expected ssh-ed25519, found ${keyType}`);
+  const rawKey = reader.readString();
+  if (rawKey.length !== ED25519_PUBLIC_KEY_BYTES) {
+    throw new Error("ssh-ed25519 public key is not 32 bytes");
+  }
+  if (reader.remaining !== 0) throw new Error("trailing bytes after the ssh-ed25519 public key");
+  return createPublicKey({
+    key: Buffer.concat([ED25519_SPKI_PREFIX, rawKey]),
+    format: "der",
+    type: "spki"
+  });
+}
+function sshsigSignedData(namespace, hashAlgorithm, messageHash) {
+  return Buffer.concat([
+    Buffer.from(SSHSIG_MAGIC, "utf8"),
+    sshString(namespace),
+    sshString(""),
+    sshString(hashAlgorithm),
+    sshString(messageHash)
+  ]);
+}
+function verifyWitanIssuanceSignature(options) {
+  const expectedNamespace = options.namespace ?? WITAN_ISSUANCE_SIGNATURE_NAMESPACE;
+  const expectedPrincipal = options.principal ?? WITAN_ISSUANCE_PRINCIPAL;
+  let parsed;
+  try {
+    parsed = parseSshSignature(options.armoredSignature);
+  } catch (error) {
+    return { status: "invalid", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (parsed.namespace !== expectedNamespace) {
+    return {
+      status: "invalid",
+      reason: `signature namespace is ${JSON.stringify(parsed.namespace)}, expected ${JSON.stringify(expectedNamespace)}`
+    };
+  }
+  if (!SSHSIG_HASH_ALGORITHMS.has(parsed.hashAlgorithm)) {
+    return {
+      status: "unsupported",
+      reason: `signature hash algorithm ${JSON.stringify(parsed.hashAlgorithm)} is not one this build verifies`
+    };
+  }
+  if (!WITAN_ISSUANCE_SUPPORTED_KEY_TYPES.includes(parsed.keyType)) {
+    return {
+      status: "unsupported",
+      reason: `key type ${JSON.stringify(parsed.keyType)} is not one this build verifies (supported: ${WITAN_ISSUANCE_SUPPORTED_KEY_TYPES.join(", ")}); verify with OpenSSH instead \u2014 see docs/issuance.md`
+    };
+  }
+  const fingerprint = sshPublicKeyFingerprint(parsed.publicKeyBlob);
+  let signatureVerified;
+  try {
+    const publicKey = ed25519PublicKeyFromBlob(parsed.publicKeyBlob);
+    const signatureReader = new SshWireReader(parsed.signatureBlob);
+    const signatureType = signatureReader.readString().toString("utf8");
+    if (signatureType !== parsed.keyType) {
+      return {
+        status: "invalid",
+        reason: `inner signature type ${JSON.stringify(signatureType)} does not match the signing key type ${JSON.stringify(parsed.keyType)}`
+      };
+    }
+    const rawSignature = signatureReader.readString();
+    if (rawSignature.length !== ED25519_SIGNATURE_BYTES) {
+      return { status: "invalid", reason: "ssh-ed25519 signature is not 64 bytes" };
+    }
+    if (signatureReader.remaining !== 0) {
+      return { status: "invalid", reason: "trailing bytes after the ssh-ed25519 signature" };
+    }
+    const messageHash = createHash(parsed.hashAlgorithm).update(options.message).digest();
+    const signedData = sshsigSignedData(parsed.namespace, parsed.hashAlgorithm, messageHash);
+    signatureVerified = cryptoVerify(null, signedData, publicKey, rawSignature);
+  } catch (error) {
+    return { status: "invalid", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (!signatureVerified) {
+    return { status: "invalid", reason: "the signature does not verify over these issuance bytes" };
+  }
+  let signers;
+  try {
+    signers = parseAllowedSigners(options.allowedSignersText);
+  } catch (error) {
+    return { status: "invalid", reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (signers.length === 0) {
+    return { status: "unlisted_key", keyType: parsed.keyType, fingerprint };
+  }
+  const signedKeyBase64 = parsed.publicKeyBlob.toString("base64");
+  const listed = signers.some(
+    (entry) => entry.uninterpretedOptions === void 0 && entry.keyType === parsed.keyType && normalizeBase64(entry.keyBase64) === signedKeyBase64 && entry.principals.includes(expectedPrincipal) && (entry.namespaces === void 0 || entry.namespaces.includes(expectedNamespace))
+  );
+  if (!listed) {
+    return { status: "unlisted_key", keyType: parsed.keyType, fingerprint };
+  }
+  return { status: "valid", principal: expectedPrincipal, keyType: parsed.keyType, fingerprint };
+}
+function normalizeBase64(value) {
+  return Buffer.from(value, "base64").toString("base64");
+}
+var REVOCATION_LINE_PATTERN = /^([a-f0-9]{64})\s+(\d{4}-\d{2}-\d{2})\s+(\S.*)$/;
+function parseIssuerRevocations(text) {
+  const revocations = [];
+  for (const [index, rawLine] of text.split("\n").entries()) {
+    const line = rawLine.replace(/\r$/, "").trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const match = REVOCATION_LINE_PATTERN.exec(line);
+    if (!match?.[1] || !match[2] || !match[3]) {
+      throw new Error(
+        `issuer-revocations line ${index + 1} is not "<report-sha256> <YYYY-MM-DD> <reason>"`
+      );
+    }
+    revocations.push({ reportSha256: match[1], date: match[2], reason: match[3].trim() });
+  }
+  return revocations;
+}
+function findIssuerRevocation(revocations, reportSha256) {
+  return revocations.find((revocation) => revocation.reportSha256 === reportSha256);
+}
+var PRIVATE_KEY_MARKER = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/;
+function parseIssuerPublicKey(contents) {
+  if (PRIVATE_KEY_MARKER.test(contents)) {
+    throw new Error(
+      "Cejel: --key names a file containing PRIVATE key material. Cejel never reads a private key and never signs: the issuer key is generated on a hardware token, exists as no file, and signs through ssh-agent. Pass the PUBLIC key (the .pub file) instead."
+    );
+  }
+  const line = contents.split("\n").map((entry) => entry.trim()).find((entry) => entry.length > 0 && !entry.startsWith("#"));
+  if (!line) throw new Error("Cejel: --key file contains no public key line.");
+  const tokens = line.split(/\s+/);
+  const [keyType, keyBase64] = tokens;
+  if (!keyType || !keyBase64 || !KEY_TYPE_PATTERN.test(keyType)) {
+    throw new Error(
+      'Cejel: --key file is not an OpenSSH public key ("<keytype> <base64> [comment]").'
+    );
+  }
+  let blob;
+  try {
+    blob = Buffer.from(keyBase64, "base64");
+    const declaredType = new SshWireReader(blob).readString().toString("utf8");
+    if (declaredType !== keyType) {
+      throw new Error(`key blob declares ${declaredType} but the line says ${keyType}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Cejel: --key file does not hold a decodable OpenSSH public key: ${message}`);
+  }
+  return { keyType, keyBase64, fingerprint: sshPublicKeyFingerprint(blob) };
+}
 
 // src/terminal.ts
 init_esm_shims();
@@ -178,6 +611,21 @@ function formatScore(score) {
 
 // src/index.ts
 var DEFAULT_OUT_DIR = ".cejel";
+var ISSUER_SIGNERS_FILE = "issuer-signers";
+var ISSUER_REVOCATIONS_FILE = "issuer-revocations";
+var SECURITY_FILE_CANDIDATES = ["../docs/security/", "../../docs/security/"];
+function resolveBundledSecurityFile(name) {
+  for (const prefix of SECURITY_FILE_CANDIDATES) {
+    let candidate;
+    try {
+      candidate = fileURLToPath(new URL(`${prefix}${name}`, import.meta.url));
+    } catch {
+      continue;
+    }
+    if (existsSync(candidate)) return candidate;
+  }
+  return void 0;
+}
 var CLI_FLAG_SPECS = [
   {
     tokens: ["--out", "--out-dir"],
@@ -281,15 +729,36 @@ var USAGE = `cejel \u2014 a trust certificate for your codebase
 Usage:
   npx ${NPX_PACKAGE_NAME} [path] [options]
   npx ${NPX_PACKAGE_NAME} scan [path] [options]
-  npx ${NPX_PACKAGE_NAME} verify <report.json> <attestation.json>
+  npx ${NPX_PACKAGE_NAME} verify <report.json> <attestation.json> [issuance.json issuance.json.sig]
+  npx ${NPX_PACKAGE_NAME} issue [path] --report <report.json> --attestation <attestation.json> --key <key.pub> --engagement-ref <ref>
 
 Commands:
   scan    score a repository (default when the command is omitted)
-  verify  verify report/attestation binding only; no signature or signer identity check
+  verify  verify the report/attestation binding; with an issuance pair, also check the issuer
+          signature against docs/security/${ISSUER_SIGNERS_FILE} and docs/security/${ISSUER_REVOCATIONS_FILE}
+  issue   re-run this version at the certificate's revision and, only if report.json reproduces
+          byte for byte, write an unsigned issuance.json for the issuer to sign through ssh-agent
 
 Scan options:
 ${usageOptions}
 
+Verify options:
+  --signers <file>       use this allowed-signers file instead of the published one
+  --revocations <file>   use this revocations file instead of the published one
+
+Issue options:
+  --report <file>        the report.json being countersigned (required)
+  --attestation <file>   the attestation.json beside it (required)
+  --key <file>           the issuer PUBLIC key (.pub); a private key file is refused (required)
+  --engagement-ref <id>  opaque issuer-chosen identifier; never a counterparty name (required)
+  --out <dir>            where issuance.json is written (default: the report.json directory)
+  --product-name <name>  pass exactly what the original scan used, or the bytes will not reproduce
+  --name <display>       pass exactly what the original scan used, or the bytes will not reproduce
+  --rubric-pin <version> pass exactly what the original scan used, or the bytes will not reproduce
+  --ingest <file>        pass exactly what the original scan used, or the bytes will not reproduce
+
+cejel never signs and never reads private key material.
+
 Runs entirely offline. No code leaves your machine.
 Docs: https://cejel.dev
 `;
@@ -306,7 +775,10 @@ async function runWitanV22CalibrationCli(args) {
 async function runWitanCli(args, rubricVersion) {
   const invocation = parseCliInvocation(args);
   if (invocation.command === "verify") {
-    return runVerifyBinding(invocation.reportPath, invocation.attestationPath);
+    return runVerifyBinding(invocation);
+  }
+  if (invocation.command === "issue") {
+    return runIssue(invocation.options);
   }
   const options = invocation.options;
   if (options.showVersion) {
@@ -402,23 +874,148 @@ function parseCliInvocation(args) {
     if (verifyArgs.some((arg) => arg === "-v" || arg === "--version")) {
       return { command: "scan", options: parseArgs(["--version"]) };
     }
-    if (verifyArgs.length !== 2) {
-      throw new Error(`Usage: npx ${NPX_PACKAGE_NAME} verify <report.json> <attestation.json>`);
+    return parseVerifyArgs(verifyArgs);
+  }
+  if (command === "issue") {
+    const issueArgs = args.slice(1);
+    if (issueArgs.some((arg) => arg === "-h" || arg === "--help")) {
+      return { command: "scan", options: parseArgs(["--help"]) };
     }
-    const [reportPath, attestationPath] = verifyArgs;
-    if (!reportPath || !attestationPath) {
-      throw new Error(`Usage: npx ${NPX_PACKAGE_NAME} verify <report.json> <attestation.json>`);
+    if (issueArgs.some((arg) => arg === "-v" || arg === "--version")) {
+      return { command: "scan", options: parseArgs(["--version"]) };
     }
-    return {
-      command: "verify",
-      reportPath: resolve(reportPath),
-      attestationPath: resolve(attestationPath)
-    };
+    return { command: "issue", options: parseIssueArgs(issueArgs) };
   }
   return { command: "scan", options: parseArgs(args) };
 }
-function runVerifyBinding(reportPath, attestationPath) {
-  const reportArtifact = readJsonArtifact(reportPath, "report");
+var VERIFY_USAGE = () => `Usage: npx ${NPX_PACKAGE_NAME} verify <report.json> <attestation.json> [issuance.json issuance.json.sig] [--signers <file>] [--revocations <file>]`;
+function parseVerifyArgs(args) {
+  const positionals = [];
+  let signersPath;
+  let revocationsPath;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === void 0) continue;
+    if (arg === "--signers" || arg === "--revocations") {
+      const value = args[index + 1];
+      if (!value) throw new Error(`Missing value for ${arg}`);
+      if (arg === "--signers") signersPath = resolve(value);
+      else revocationsPath = resolve(value);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("-")) throw new Error(`Unknown Cejel verify flag: ${arg}`);
+    positionals.push(arg);
+  }
+  if (positionals.length !== 2 && positionals.length !== 4) throw new Error(VERIFY_USAGE());
+  const [reportPath, attestationPath, issuancePath, issuanceSignaturePath] = positionals;
+  if (!reportPath || !attestationPath) throw new Error(VERIFY_USAGE());
+  return {
+    command: "verify",
+    reportPath: resolve(reportPath),
+    attestationPath: resolve(attestationPath),
+    ...issuancePath ? { issuancePath: resolve(issuancePath) } : {},
+    ...issuanceSignaturePath ? { issuanceSignaturePath: resolve(issuanceSignaturePath) } : {},
+    ...signersPath ? { signersPath } : {},
+    ...revocationsPath ? { revocationsPath } : {}
+  };
+}
+function parseIssueArgs(args) {
+  let repoPath;
+  let reportPath;
+  let attestationPath;
+  let keyPath;
+  let engagementRef;
+  let outDir;
+  let productName;
+  let productDisplayName;
+  let rubricPin;
+  const ingestPatterns = [];
+  function takeValue(arg, index) {
+    const value = args[index];
+    if (!value) throw new Error(`Missing value for ${arg}`);
+    return value;
+  }
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === void 0) continue;
+    switch (arg) {
+      case "--report":
+        reportPath = resolve(takeValue(arg, index + 1));
+        index += 1;
+        continue;
+      case "--attestation":
+        attestationPath = resolve(takeValue(arg, index + 1));
+        index += 1;
+        continue;
+      case "--key":
+        keyPath = resolve(takeValue(arg, index + 1));
+        index += 1;
+        continue;
+      case "--engagement-ref":
+        engagementRef = takeValue(arg, index + 1).trim();
+        index += 1;
+        continue;
+      case "--out":
+      case "--out-dir":
+        outDir = resolve(takeValue(arg, index + 1));
+        index += 1;
+        continue;
+      case "--product-name":
+        productName = takeValue(arg, index + 1).trim();
+        index += 1;
+        continue;
+      case "--name":
+        productDisplayName = takeValue(arg, index + 1).trim();
+        index += 1;
+        continue;
+      case "--rubric-pin": {
+        const value = takeValue(arg, index + 1);
+        assertSelectableRubricVersion(value);
+        rubricPin = value;
+        index += 1;
+        continue;
+      }
+      case "--ingest":
+        ingestPatterns.push(takeValue(arg, index + 1));
+        index += 1;
+        continue;
+      default:
+        break;
+    }
+    if (arg.startsWith("-")) throw new Error(`Unknown Cejel issue flag: ${arg}`);
+    if (repoPath !== void 0) throw new Error(`Unexpected positional argument: ${arg}`);
+    repoPath = arg;
+  }
+  const missing = [
+    reportPath ? null : "--report",
+    attestationPath ? null : "--attestation",
+    keyPath ? null : "--key",
+    engagementRef ? null : "--engagement-ref"
+  ].filter((entry) => entry !== null);
+  if (missing.length > 0 || !reportPath || !attestationPath || !keyPath || !engagementRef) {
+    throw new Error(
+      `Cejel issue requires ${missing.join(", ")}. Usage: npx ${NPX_PACKAGE_NAME} issue [path] --report <report.json> --attestation <attestation.json> --key <key.pub> --engagement-ref <ref>`
+    );
+  }
+  if (productName && productDisplayName) {
+    throw new Error("--product-name and --name cannot be used together");
+  }
+  return {
+    repoPath: resolve(repoPath ?? "."),
+    reportPath,
+    attestationPath,
+    keyPath,
+    engagementRef,
+    outDir: outDir ?? dirname(reportPath),
+    ...productName ? { productName } : {},
+    ...productDisplayName ? { productDisplayName } : {},
+    ...rubricPin ? { rubricPin } : {},
+    ingestPatterns
+  };
+}
+function runVerifyBinding(invocation) {
+  const reportArtifact = readJsonArtifact(invocation.reportPath, "report");
   const reportResult = WitanReportSchema.safeParse(reportArtifact.value);
   if (!reportResult.success) {
     const members = reportResult.error.issues.map(
@@ -431,8 +1028,8 @@ ${members.map((member) => `  - ${member}`).join("\n")}
     );
     return 1;
   }
-  const statement = readJsonArtifact(attestationPath, "attestation");
-  const reportSha256 = createHash("sha256").update(reportArtifact.contents).digest("hex");
+  const statement = readJsonArtifact(invocation.attestationPath, "attestation");
+  const reportSha256 = createHash2("sha256").update(reportArtifact.contents).digest("hex");
   const result = verifyWitanAttestationBinding(statement.value, reportResult.data, {
     reportSha256
   });
@@ -445,7 +1042,190 @@ ${result.errors.map((error) => `  - ${error}`).join("\n")}
     return 1;
   }
   process.stdout.write("Cejel: report/attestation binding verified.\n");
-  process.stdout.write("Cejel: signature and signer identity were not verified.\n");
+  if (!invocation.issuancePath || !invocation.issuanceSignaturePath) {
+    process.stdout.write("Cejel: signature and signer identity were not verified.\n");
+    return 0;
+  }
+  const attestationSha256 = createHash2("sha256").update(statement.contents).digest("hex");
+  return runVerifyIssuance(invocation, {
+    reportSha256,
+    attestationSha256,
+    productSlug: reportResult.data.productSlug,
+    issuancePath: invocation.issuancePath,
+    issuanceSignaturePath: invocation.issuanceSignaturePath
+  });
+}
+function runVerifyIssuance(invocation, context) {
+  const issuance = readJsonArtifact(context.issuancePath, "issuance");
+  let armoredSignature;
+  try {
+    armoredSignature = readFileSync(context.issuanceSignaturePath, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Cejel: could not read issuance signature file ${context.issuanceSignaturePath}: ${message}`
+    );
+  }
+  const signersPath = invocation.signersPath ?? resolveBundledSecurityFile(ISSUER_SIGNERS_FILE);
+  const revocationsPath = invocation.revocationsPath ?? resolveBundledSecurityFile(ISSUER_REVOCATIONS_FILE);
+  let signatureLine;
+  let signatureOk = false;
+  if (!signersPath) {
+    signatureLine = `signature:  NOT VERIFIED \u2014 no ${ISSUER_SIGNERS_FILE} file was found beside this build; pass --signers <file>`;
+  } else {
+    const verdict = verifyWitanIssuanceSignature({
+      message: issuance.contents,
+      armoredSignature,
+      allowedSignersText: readFileSync(signersPath, "utf8")
+    });
+    switch (verdict.status) {
+      case "valid":
+        signatureOk = true;
+        signatureLine = `signature:  valid \u2014 signed by ${verdict.principal} (${verdict.keyType}, ${verdict.fingerprint}) under namespace ${WITAN_ISSUANCE_SIGNATURE_NAMESPACE}`;
+        break;
+      case "unlisted_key":
+        signatureLine = `signature:  SIGNED BY AN UNLISTED KEY \u2014 ${verdict.keyType} ${verdict.fingerprint} is not listed for ${WITAN_ISSUANCE_PRINCIPAL} in ${signersPath}`;
+        break;
+      case "unsupported":
+        signatureLine = `signature:  NOT VERIFIED \u2014 ${verdict.reason}`;
+        break;
+      default:
+        signatureLine = `signature:  INVALID \u2014 ${verdict.reason}`;
+        break;
+    }
+  }
+  const binding = verifyWitanIssuanceBinding(issuance.value, {
+    reportSha256: context.reportSha256,
+    attestationSha256: context.attestationSha256,
+    productSlug: context.productSlug
+  });
+  const bindingLine = binding.valid ? "binding:    valid \u2014 the issuance names the exact report.json and attestation.json supplied, and asserts reportByteIdentical: true" : `binding:    INVALID \u2014 ${binding.errors.join("; ")}`;
+  let revocationLine;
+  let revocationOk = false;
+  if (!revocationsPath) {
+    revocationLine = `revocation: NOT CHECKED \u2014 no ${ISSUER_REVOCATIONS_FILE} file was found beside this build; pass --revocations <file>`;
+  } else {
+    let revocation;
+    try {
+      revocation = findIssuerRevocation(
+        parseIssuerRevocations(readFileSync(revocationsPath, "utf8")),
+        context.reportSha256
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stdout.write(`${signatureLine}
+${bindingLine}
+`);
+      process.stdout.write(`revocation: NOT CHECKED \u2014 ${message}
+`);
+      return 1;
+    }
+    if (revocation) {
+      revocationLine = `revocation: REVOKED \u2014 withdrawn ${revocation.date}: ${revocation.reason}`;
+    } else {
+      revocationOk = true;
+      revocationLine = `revocation: not revoked \u2014 this report digest is absent from ${revocationsPath}`;
+    }
+  }
+  process.stdout.write(`${signatureLine}
+${bindingLine}
+${revocationLine}
+`);
+  return signatureOk && binding.valid && revocationOk ? 0 : 1;
+}
+function runIssue(options) {
+  const reportArtifact = readJsonArtifact(options.reportPath, "report");
+  const reportResult = WitanReportSchema.safeParse(reportArtifact.value);
+  if (!reportResult.success) {
+    const members = reportResult.error.issues.map(
+      (issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`
+    );
+    process.stderr.write(
+      `Cejel: report validation failed:
+${members.map((member) => `  - ${member}`).join("\n")}
+`
+    );
+    return 1;
+  }
+  const suppliedReport = reportResult.data;
+  const attestationArtifact = readJsonArtifact(options.attestationPath, "attestation");
+  const reportSha256 = createHash2("sha256").update(reportArtifact.contents).digest("hex");
+  const attestationSha256 = createHash2("sha256").update(attestationArtifact.contents).digest("hex");
+  const attestationBinding = verifyWitanAttestationBinding(
+    attestationArtifact.value,
+    suppliedReport,
+    { reportSha256 }
+  );
+  if (!attestationBinding.valid) {
+    process.stderr.write(
+      `Cejel: refusing to issue \u2014 the supplied report and attestation are not bound to each other:
+${attestationBinding.errors.map((error) => `  - ${error}`).join("\n")}
+`
+    );
+    return 1;
+  }
+  let keyContents;
+  try {
+    keyContents = readFileSync(options.keyPath, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Cejel: could not read --key file ${options.keyPath}: ${message}`);
+  }
+  const issuerKey = parseIssuerPublicKey(keyContents);
+  const reproduction = runCejelScan({
+    repoPath: options.repoPath,
+    ...options.productName ? { productName: options.productName } : {},
+    ...options.productDisplayName ? { productDisplayName: options.productDisplayName } : {},
+    ...options.rubricPin ? { rubricVersion: options.rubricPin } : {},
+    ingestPatterns: options.ingestPatterns,
+    warnOnEmptyIngestMatch: true,
+    toolVersion: cliVersion()
+  });
+  const reproducedBytes = serializeWitanReport(reproduction.report);
+  const reproducedSha256 = createHash2("sha256").update(reproducedBytes, "utf8").digest("hex");
+  if (reproducedSha256 !== reportSha256) {
+    process.stderr.write(
+      [
+        "Cejel: refusing to issue \u2014 report.json did not reproduce byte for byte.",
+        `  supplied report.json:   sha256:${reportSha256}`,
+        `  re-run at ${options.repoPath}: sha256:${reproducedSha256}`,
+        `  this build:             @cejel/cejel ${cliVersion()}`,
+        "  Check that the checkout is at the certificate revision, that the @cejel/cejel version matches",
+        "  report.json's toolVersion, and that --product-name/--name/--rubric-pin/--ingest match the",
+        "  original invocation. An issuance that cannot reproduce is not issued.",
+        ""
+      ].join("\n")
+    );
+    return 1;
+  }
+  const statement = createWitanIssuanceStatement(suppliedReport, {
+    reportSha256,
+    attestationSha256,
+    issuerKeyFingerprint: issuerKey.fingerprint,
+    toolVersion: cliVersion(),
+    issuedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    engagementRef: options.engagementRef
+  });
+  mkdirSync(options.outDir, { recursive: true });
+  const issuancePath = join(options.outDir, "issuance.json");
+  writeFileSync(issuancePath, serializeWitanIssuance(statement), "utf8");
+  process.stdout.write(
+    [
+      `Cejel: reproduced report.json byte for byte (sha256:${reportSha256}).`,
+      `Wrote:
+  ${issuancePath}`,
+      "",
+      "report.json and attestation.json were not modified. Cejel does not sign and never reads a",
+      "private key. Sign through ssh-agent, with the issuer key on its token:",
+      "",
+      `  ssh-keygen -Y sign -n ${WITAN_ISSUANCE_SIGNATURE_NAMESPACE} -f ${options.keyPath} -U ${issuancePath}`,
+      "",
+      "Then verify before delivery:",
+      "",
+      `  npx ${NPX_PACKAGE_NAME} verify ${options.reportPath} ${options.attestationPath} ${issuancePath} ${issuancePath}.sig`,
+      ""
+    ].join("\n")
+  );
   return 0;
 }
 function readJsonArtifact(path, label) {
@@ -623,6 +1403,8 @@ export {
   WitanReportSchema,
   parseArgs,
   parseCliInvocation,
+  parseIssueArgs,
+  parseVerifyArgs,
   runWitanFreeCli,
   runWitanV22CalibrationCli,
   verifyWitanAttestationBinding