JuliusBrussee/caveman · error

unsupported unsigned verification coverage ${String(bundle.v

Error message

unsupported unsigned verification coverage ${String(bundle.verification_coverage)}

What it means

The optional bundle field verification_coverage may only be "included_receipts_only". The verifier can only check receipts physically present in the bundle, so any broader coverage claim carried in unsigned export metadata is an unverifiable promise and is rejected.

Source

Thrown at packages/cli/src/index.ts:17412

  if (typeof info.key !== "string" || !info.key.trim()) throw new Error(`${label} key is required`);
  const raw = Buffer.from(info.key, "base64");
  if (raw.length !== 32 || raw.toString("base64") !== info.key) throw new Error(`${label} must be a canonical base64 Ed25519 public key`);
  return { info, raw, key: ed25519PublicKey(raw) };
}

function decodeUniqueKeyring(infos: ReceiptPublicKey[], label: string): Map<string, DecodedReceiptKey> {
  const keys = new Map<string, DecodedReceiptKey>();
  for (const [index, info] of infos.entries()) {
    const decoded = decodeReceiptKey(info, `${label}[${index}]`);
    if (keys.has(decoded.info.key_id)) throw new Error(`${label} contains duplicate key_id ${decoded.info.key_id}`);
    keys.set(decoded.info.key_id, decoded);
  }
  return keys;
}

function embeddedReceiptKeys(bundle: ReceiptBundle): { current: DecodedReceiptKey; keys: Map<string, DecodedReceiptKey> } {
  if (bundle.schema !== RECEIPT_BUNDLE_V1 && bundle.schema !== RECEIPT_BUNDLE_V2) throw new Error(`unsupported bundle schema ${String(bundle.schema)}`);
  if (bundle.verification_coverage !== undefined && bundle.verification_coverage !== INCLUDED_RECEIPTS_ONLY) throw new Error(`unsupported unsigned verification coverage ${String(bundle.verification_coverage)}`);
  if (bundle.completeness_attested === true) throw new Error("bundle completeness cannot be attested by unsigned export metadata");
  const current = decodeReceiptKey(bundle.public_key, "public_key");
  if (bundle.public_keys !== undefined && !Array.isArray(bundle.public_keys)) throw new Error("public_keys must be an array");
  if (bundle.schema === RECEIPT_BUNDLE_V2 && (!Array.isArray(bundle.public_keys) || bundle.public_keys.length === 0)) throw new Error("v2 bundle requires public_keys");
  const keys = decodeUniqueKeyring(bundle.public_keys ?? [], "public_keys");
  const currentInRing = keys.get(current.info.key_id);
  if (currentInRing && !currentInRing.raw.equals(current.raw)) throw new Error(`public_key conflicts with public_keys entry ${current.info.key_id}`);
  if (bundle.schema === RECEIPT_BUNDLE_V2 && !currentInRing) throw new Error("v2 public_keys must include public_key");
  if (!currentInRing) keys.set(current.info.key_id, current);
  return { current, keys };
}

async function pinnedReceiptKeys(file: string, current: DecodedReceiptKey): Promise<{ keys: Map<string, DecodedReceiptKey>; trust: string }> {
  const source = (await readFile(file, "utf8")).trim();
  if (!source.startsWith("{")) {
    const pinned = decodeReceiptKey({ ...current.info, key: source }, "--pubkey");
    if (!pinned.raw.equals(current.raw)) throw new Error("bundle public key does not match the published --pubkey");
    return { keys: new Map([[current.info.key_id, pinned]]), trust: "pinned_public_key" };

View on GitHub (pinned to 5184b3d11a)

Solutions

1. Re-export the bundle with verification_coverage omitted or set exactly to "included_receipts_only"
2. Upgrade the verifying CLI if the newer coverage value is legitimately defined by a newer schema
3. Do not hand-set this field on exported bundles

Example fix

// before
{ "verification_coverage": "all_receipts" }

// after
{ "verification_coverage": "included_receipts_only" }

if (bundle.verification_coverage !== undefined && bundle.verification_coverage !== "included_receipts_only") {
  throw new Error(`refusing bundle with coverage claim ${String(bundle.verification_coverage)}`);
}

function hasValidCoverage(v: unknown): boolean {
  return v === undefined || v === "included_receipts_only";
}

try { execSync(`caveman receipts verify ${bundle}`); }
catch (e) {
  if (/unsupported unsigned verification coverage/.test(String((e as Error).message))) {
    fail("re-export the bundle; only included_receipts_only coverage is verifiable");
  }
  throw e;
}

When it happens

Trigger: A bundle exported with verification_coverage set to something other than "included_receipts_only" (e.g. "all_receipts", "complete", or a new enum value from a newer producer).

Common situations: A newer producer adds a coverage mode the local CLI does not know; someone hand-sets the field trying to claim full coverage; copy-paste from internal docs.

Related errors

• ${label} key_id is required
• ${label} key is required
• ${label} contains duplicate key_id ${decoded.info.key_id}
• unsupported bundle schema ${String(bundle.schema)}
• bundle completeness cannot be attested by unsigned export me

AI-assisted analysis of JuliusBrussee/caveman@5184b3d11a (2026-08-18). Data as JSON: /api/errors/825cf3b62b030a43. Report an issue: GitHub.