@freedomofpress/sigstore-browser 0.1.0

package/src/cli.ts

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+import { createHash, webcrypto } from "node:crypto";
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { SigstoreBundle } from "./bundle.js";
+import { base64ToUint8Array, hexToUint8Array, Uint8ArrayToHex, Uint8ArrayToString } from "./encoding.js";
+import { TrustedRoot } from "./interfaces.js";
+import { SigstoreVerifier } from "./sigstore.js";
+import { TrustedRootProvider } from "./trust/tuf.js";
+
+// Ensure the global Web Crypto implementation is available when running under Node.js
+if (typeof globalThis.crypto === "undefined") {
+  globalThis.crypto = webcrypto as unknown as Crypto;
+}
+
+interface CLIOptions {
+  bundlePath: string;
+  certificateIdentity: string;
+  certificateOidcIssuer: string;
+  trustedRootPath: string | undefined;
+  artifactInput: string;
+}
+
+type ArtifactInput =
+  | { type: "file"; path: string; data: Uint8Array; digestHex: string }
+  | { type: "digest"; digestHex: string };
+
+const USAGE = `Usage: sigstore-browser verify-bundle [--staging] --bundle FILE --certificate-identity IDENTITY --certificate-oidc-issuer URL [--trusted-root FILE] FILE_OR_DIGEST`;
+
+function printUsage(): void {
+  console.error(USAGE);
+}
+
+function parseArgs(argv: string[]): CLIOptions {
+  const options: Partial<CLIOptions> = {};
+  let command: string | undefined;
+  let artifactInput: string | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const current = argv[i];
+
+    if (current === "--help" || current === "-h") {
+      printUsage();
+      process.exit(0);
+    }
+
+    if (current.startsWith("--")) {
+      const [name, providedValue] = current.split("=", 2);
+
+      switch (name) {
+        case "--bundle": {
+          const value = providedValue ?? argv[++i];
+          if (!value) {
+            throw new Error("Missing value for --bundle");
+          }
+          options.bundlePath = value;
+          break;
+        }
+        case "--certificate-identity": {
+          const value = providedValue ?? argv[++i];
+          if (!value) {
+            throw new Error("Missing value for --certificate-identity");
+          }
+          options.certificateIdentity = value;
+          break;
+        }
+        case "--certificate-oidc-issuer": {
+          const value = providedValue ?? argv[++i];
+          if (!value) {
+            throw new Error("Missing value for --certificate-oidc-issuer");
+          }
+          options.certificateOidcIssuer = value;
+          break;
+        }
+        case "--trusted-root": {
+          const value = providedValue ?? argv[++i];
+          if (!value) {
+            throw new Error("Missing value for --trusted-root");
+          }
+          options.trustedRootPath = value;
+          break;
+        }
+        default:
+          throw new Error(`Unknown option: ${name}`);
+      }
+
+      continue;
+    }
+
+    if (!command) {
+      command = current;
+      continue;
+    }
+
+    if (!artifactInput) {
+      artifactInput = current;
+      continue;
+    }
+
+    throw new Error(`Unexpected argument: ${current}`);
+  }
+
+  if (command !== "verify-bundle") {
+    throw new Error("No command provided. Expected 'verify-bundle'.");
+  }
+
+  if (!artifactInput) {
+    throw new Error("Missing FILE_OR_DIGEST argument.");
+  }
+
+  if (!options.bundlePath) {
+    throw new Error("Missing required option --bundle");
+  }
+
+  if (!options.certificateIdentity) {
+    throw new Error("Missing required option --certificate-identity");
+  }
+
+  if (!options.certificateOidcIssuer) {
+    throw new Error("Missing required option --certificate-oidc-issuer");
+  }
+
+  return {
+    bundlePath: options.bundlePath,
+    certificateIdentity: options.certificateIdentity,
+    certificateOidcIssuer: options.certificateOidcIssuer,
+    trustedRootPath: options.trustedRootPath,
+    artifactInput,
+  };
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveArtifact(input: string): Promise<ArtifactInput> {
+  const digestPrefix = "sha256:";
+
+  if (
+    input.startsWith(digestPrefix) &&
+    input.length === digestPrefix.length + 64 &&
+    /^[0-9a-fA-F]+$/.test(input.slice(digestPrefix.length)) &&
+    !(await fileExists(input))
+  ) {
+    return {
+      type: "digest",
+      digestHex: input.slice(digestPrefix.length).toLowerCase(),
+    };
+  }
+
+  const resolvedPath = path.resolve(input);
+  const artifactBuffer = await readFile(resolvedPath);
+  const digestHex = createHash("sha256").update(artifactBuffer).digest("hex");
+
+  return {
+    type: "file",
+    path: resolvedPath,
+    data: new Uint8Array(artifactBuffer),
+    digestHex,
+  };
+}
+
+async function loadTrustedRoot(
+  pathInput: string | undefined,
+): Promise<TrustedRoot> {
+  if (!pathInput) {
+    // Use TUF to fetch the latest trusted root (matches sigstore-js behavior)
+    const tufProvider = new TrustedRootProvider({
+      metadataUrl: "https://tuf-repo-cdn.sigstore.dev/",
+      targetBaseUrl: "https://tuf-repo-cdn.sigstore.dev/targets/",
+    });
+    return await tufProvider.getTrustedRoot();
+  }
+  const resolvedPath = path.resolve(pathInput);
+  const raw = await readFile(resolvedPath, "utf8");
+  return JSON.parse(raw) as TrustedRoot;
+}
+
+async function loadBundle(bundlePath: string): Promise<SigstoreBundle> {
+  const resolved = path.resolve(bundlePath);
+  const raw = await readFile(resolved, "utf8");
+  return JSON.parse(raw) as SigstoreBundle;
+}
+
+async function verifyBundle(options: CLIOptions): Promise<void> {
+  const [trustedRoot, bundle, artifact] = await Promise.all([
+    loadTrustedRoot(options.trustedRootPath),
+    loadBundle(options.bundlePath),
+    resolveArtifact(options.artifactInput),
+  ]);
+
+  const verifier = new SigstoreVerifier();
+  await verifier.loadSigstoreRoot(trustedRoot);
+
+  // Extract and verify the artifact digest from the bundle
+  let bundleDigestHex: string;
+  let bundleDigestBytes: Uint8Array;
+
+  if (bundle.messageSignature) {
+    // Regular bundle: digest is in messageSignature
+    if (bundle.messageSignature.messageDigest.algorithm !== "SHA2_256") {
+      throw new Error(
+        `Unsupported message digest algorithm: ${bundle.messageSignature.messageDigest.algorithm}`,
+      );
+    }
+
+    bundleDigestBytes = base64ToUint8Array(
+      bundle.messageSignature.messageDigest.digest,
+    );
+    bundleDigestHex = Uint8ArrayToHex(bundleDigestBytes).toLowerCase();
+  } else if (bundle.dsseEnvelope) {
+    // DSSE bundle: digest is in the in-toto statement payload
+    const payloadBytes = base64ToUint8Array(bundle.dsseEnvelope.payload);
+    const payload = JSON.parse(Uint8ArrayToString(payloadBytes));
+
+    if (!payload.subject || payload.subject.length === 0) {
+      throw new Error("DSSE payload has no subject");
+    }
+
+    // Find matching subject by comparing artifact digest with all subjects
+    let matchedSubject = null;
+    for (const subject of payload.subject) {
+      const subjectDigest = subject.digest?.["sha256"];
+      if (subjectDigest && artifact.digestHex === subjectDigest.toLowerCase()) {
+        matchedSubject = subject;
+        break;
+      }
+    }
+
+    if (!matchedSubject) {
+      throw new Error(
+        `Artifact digest ${artifact.digestHex} does not match any subject in DSSE payload`
+      );
+    }
+
+    bundleDigestHex = matchedSubject.digest["sha256"].toLowerCase();
+
+    // Convert hex digest to bytes for verification target
+    bundleDigestBytes = hexToUint8Array(bundleDigestHex);
+  } else {
+    throw new Error("Bundle does not contain a message signature or DSSE envelope");
+  }
+
+  // For non-DSSE bundles, verify the digest matches
+  if (bundle.messageSignature && artifact.digestHex !== bundleDigestHex) {
+    throw new Error(
+      "Artifact digest does not match the digest embedded in the bundle.",
+    );
+  }
+
+  const verificationTarget =
+    artifact.type === "file" ? artifact.data : bundleDigestBytes;
+  const isDigestOnly = artifact.type === "digest";
+
+  await verifier.verifyArtifact(
+    options.certificateIdentity,
+    options.certificateOidcIssuer,
+    bundle,
+    verificationTarget,
+    isDigestOnly,
+  );
+}
+
+async function main(): Promise<void> {
+  try {
+    const options = parseArgs(process.argv.slice(2));
+    await verifyBundle(options);
+    console.log("Bundle verification succeeded.");
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(error.message);
+    } else {
+      console.error(error);
+    }
+    process.exitCode = 1;
+  }
+}
+
+await main();

package/src/crypto.ts

@@ -0,0 +1,310 @@
+import { ASN1Obj } from "./asn1/index.js";
+import {
+  base64ToUint8Array,
+  base64UrlToUint8Array,
+  hexToUint8Array,
+  toArrayBuffer,
+  Uint8ArrayToHex,
+} from "./encoding.js";
+import { EcdsaTypes, HashAlgorithms, KeyTypes } from "./interfaces.js";
+import { toDER } from "./pem.js";
+import { p256, p384, p521 } from "@noble/curves/nist.js";
+
+function pkcs1ToSpki(pkcs1Bytes: Uint8Array): Uint8Array {
+  const algorithmIdentifier = new Uint8Array([
+    0x30, 0x0d,
+    0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01,
+    0x05, 0x00
+  ]);
+
+  const bitStringLength = pkcs1Bytes.length + 1;
+  const totalContentLength = algorithmIdentifier.length + 1 + lengthBytes(bitStringLength).length + bitStringLength;
+
+  const result = new Uint8Array(1 + lengthBytes(totalContentLength).length + totalContentLength);
+  let offset = 0;
+
+  result[offset++] = 0x30;
+  const totalLengthBytes = lengthBytes(totalContentLength);
+  result.set(totalLengthBytes, offset);
+  offset += totalLengthBytes.length;
+
+  result.set(algorithmIdentifier, offset);
+  offset += algorithmIdentifier.length;
+
+  result[offset++] = 0x03;
+  const bitStringLengthBytes = lengthBytes(bitStringLength);
+  result.set(bitStringLengthBytes, offset);
+  offset += bitStringLengthBytes.length;
+  result[offset++] = 0x00;
+  result.set(pkcs1Bytes, offset);
+
+  return result;
+}
+
+// Encodes a length value in DER (Distinguished Encoding Rules) format.
+// DER length encoding rules:
+// - Lengths 0-127: single byte containing the length
+// - Lengths 128-255: 0x81 followed by one byte containing the length
+// - Lengths 256-65535: 0x82 followed by two bytes containing the length (big-endian)
+// Used by pkcs1ToSpki() to construct valid ASN.1/DER structures.
+function lengthBytes(length: number): Uint8Array {
+  if (length < 128) {
+    return new Uint8Array([length]);
+  } else if (length < 256) {
+    return new Uint8Array([0x81, length]);
+  } else {
+    return new Uint8Array([0x82, (length >> 8) & 0xff, length & 0xff]);
+  }
+}
+
+// Imports cryptographic public keys into the Web Crypto API format (CryptoKey).
+// This function is specific to the browser implementation and doesn't exist in sigstore-js.
+//
+// Why needed for browser:
+// - sigstore-js uses Node.js crypto.createPublicKey() which handles many key formats automatically
+// - Browsers only have Web Crypto API (crypto.subtle.importKey) which requires explicit format/algorithm
+// - This function bridges the gap by:
+//   1. Detecting key format (PEM, hex, base64, PKCS#1, SPKI)
+//   2. Converting PKCS#1 RSA keys to SPKI (Web Crypto only supports SPKI for RSA)
+//   3. Mapping Sigstore key types/schemes to Web Crypto algorithm parameters
+//
+// Supports:
+// - ECDSA (P-256, P-384, P-521) - Used by Fulcio, CT logs
+// - Ed25519 - Used by Rekor checkpoints, some CT logs
+// - RSA (PKCS#1, PSS) - Used by older CT logs and some Rekor instances
+//
+// Key format detection:
+// - PEM format (contains "BEGIN"): Parse with toDER()
+// - Hex string (all hex chars): Import as raw
+// - Base64 PKCS#1 (starts with 0x30 0x82...): Convert to SPKI
+// - Base64 SPKI: Import directly
+export async function importKey(
+  keytype: string,
+  scheme: string,
+  key: string,
+): Promise<CryptoKey> {
+  class importParams {
+    format: "raw" | "spki" = "spki";
+    keyData: ArrayBuffer = new ArrayBuffer(0);
+    algorithm: RsaHashedImportParams | EcKeyImportParams | Algorithm = { name: "ECDSA" };
+    extractable: boolean = true;
+    usage: Array<KeyUsage> = ["verify"];
+  }
+
+  const params = new importParams();
+  if (key.includes("BEGIN")) {
+    params.format = "spki";
+    params.keyData = toArrayBuffer(toDER(key));
+  } else if (/^[0-9A-Fa-f]+$/.test(key)) {
+    params.format = "raw";
+    params.keyData = toArrayBuffer(hexToUint8Array(key));
+  } else {
+    params.format = "spki";
+    const keyBytes = base64ToUint8Array(key);
+
+    if (keytype.toLowerCase().includes("pkcs1") &&
+        keyBytes[0] === 0x30 && keyBytes[1] === 0x82 &&
+        keyBytes[4] === 0x02 && keyBytes[5] === 0x82) {
+      params.keyData = toArrayBuffer(pkcs1ToSpki(keyBytes));
+    } else {
+      params.keyData = toArrayBuffer(keyBytes);
+    }
+  }
+
+  if (keytype.toLowerCase().includes("ecdsa")) {
+    if (scheme.includes("256")) {
+      params.algorithm = { name: "ECDSA", namedCurve: EcdsaTypes.P256 };
+    } else if (scheme.includes("384")) {
+      params.algorithm = { name: "ECDSA", namedCurve: EcdsaTypes.P384 };
+    } else if (scheme.includes("521")) {
+      params.algorithm = { name: "ECDSA", namedCurve: EcdsaTypes.P521 };
+    } else {
+      throw new Error("Cannot determine ECDSA key size.");
+    }
+  } else if (keytype.toLowerCase().includes("ed25519")) {
+    params.algorithm = { name: "Ed25519" };
+  } else if (keytype.toLowerCase().includes("rsa") || keytype.toLowerCase().includes("pkcs1")) {
+    let hashName = HashAlgorithms.SHA256;
+    // Normalize scheme to handle various formats: SHA256, SHA_256, SHA-256, etc.
+    const normalizedScheme = scheme.toUpperCase().replace(/[-_]/g, "");
+    if (normalizedScheme.includes("SHA256") || normalizedScheme.includes("256")) {
+      hashName = HashAlgorithms.SHA256;
+    } else if (normalizedScheme.includes("SHA384") || normalizedScheme.includes("384")) {
+      hashName = HashAlgorithms.SHA384;
+    } else if (normalizedScheme.includes("SHA512") || normalizedScheme.includes("512")) {
+      hashName = HashAlgorithms.SHA512;
+    }
+
+    if (scheme.includes("PKCS1") || scheme.includes("RSA_PKCS1")) {
+      params.algorithm = {
+        name: "RSASSA-PKCS1-v1_5",
+        hash: { name: hashName },
+      };
+    } else {
+      params.algorithm = {
+        name: "RSA-PSS",
+        hash: { name: hashName },
+      };
+    }
+  } else {
+    throw new Error(`Unsupported ${keytype}`);
+  }
+
+  return await crypto.subtle.importKey(
+    params.format,
+    params.keyData,
+    params.algorithm,
+    params.extractable,
+    params.usage,
+  );
+}
+
+export async function verifySignature(
+  key: CryptoKey,
+  signed: Uint8Array,
+  sig: Uint8Array,
+  hash: string = "sha256",
+): Promise<boolean> {
+  const options: {
+    name: string;
+    hash?: {
+      name: string;
+    };
+  } = {
+    name: key.algorithm.name,
+  };
+
+  if (key.algorithm.name === KeyTypes.Ecdsa) {
+    const namedCurve = (key.algorithm as EcKeyAlgorithm).namedCurve;
+    let sig_size = 32;
+
+    if (namedCurve === EcdsaTypes.P256) {
+      sig_size = 32;
+    } else if (namedCurve === EcdsaTypes.P384) {
+      sig_size = 48;
+    } else if (namedCurve === EcdsaTypes.P521) {
+      sig_size = 66;
+    }
+
+    options.hash = { name: "" };
+    if (hash.includes("256")) {
+      options.hash.name = HashAlgorithms.SHA256;
+    } else if (hash.includes("384")) {
+      options.hash.name = HashAlgorithms.SHA384;
+    } else if (hash.includes("512")) {
+      options.hash.name = HashAlgorithms.SHA512;
+    } else {
+      throw new Error("Cannot determine hashing algorithm;");
+    }
+
+    let raw_signature: Uint8Array;
+    try {
+      const asn1_sig = ASN1Obj.parseBuffer(sig);
+      const r = asn1_sig.subs[0].toInteger();
+      const s = asn1_sig.subs[1].toInteger();
+      const binr = hexToUint8Array(r.toString(16).padStart(sig_size * 2, "0"));
+      const bins = hexToUint8Array(s.toString(16).padStart(sig_size * 2, "0"));
+      raw_signature = new Uint8Array(binr.length + bins.length);
+      raw_signature.set(binr, 0);
+      raw_signature.set(bins, binr.length);
+    } catch {
+      return false;
+    }
+
+    return await crypto.subtle.verify(
+      options,
+      key,
+      toArrayBuffer(raw_signature),
+      toArrayBuffer(signed),
+    );
+  } else if (key.algorithm.name === KeyTypes.Ed25519) {
+    // Ed25519 uses raw signatures (not DER-encoded like ECDSA)
+    // Fulcio supports Ed25519, ECDSA, and RSA_PSS for signing certificates
+    // Ed25519 is also used for checkpoint signatures in TLog configurations
+    return await crypto.subtle.verify(
+      key.algorithm.name,
+      key,
+      toArrayBuffer(sig),
+      toArrayBuffer(signed),
+    );
+  } else if (key.algorithm.name === "RSA-PSS") {
+    // Salt length must match the hash output size
+    const hashAlg = (key.algorithm as RsaHashedKeyAlgorithm).hash.name;
+    const saltLength = hashAlg === HashAlgorithms.SHA256 ? 32 :
+                       hashAlg === HashAlgorithms.SHA384 ? 48 :
+                       hashAlg === HashAlgorithms.SHA512 ? 64 : 32;
+    return await crypto.subtle.verify(
+      {
+        name: "RSA-PSS",
+        saltLength: saltLength,
+      },
+      key,
+      toArrayBuffer(sig),
+      toArrayBuffer(signed),
+    );
+  } else if (key.algorithm.name === "RSASSA-PKCS1-v1_5") {
+    return await crypto.subtle.verify(
+      key.algorithm.name,
+      key,
+      toArrayBuffer(sig),
+      toArrayBuffer(signed),
+    );
+  } else {
+    throw new Error("Unsupported key type!");
+  }
+}
+
+// Verifies an ECDSA signature over a pre-computed digest.
+// WebCrypto's verify() always hashes the input first, so passing a digest would
+// result in double-hashing. We use @noble/curves for low-level ECDSA verification,
+// adapted from the same workaround used in sigstore-js's conformance CLI.
+// See: https://github.com/sigstore/sigstore-js/blob/main/packages/conformance/src/commands/verify-bundle.ts#L111
+export async function verifySignatureOverDigest(
+  key: CryptoKey,
+  digest: Uint8Array,
+  sig: Uint8Array,
+): Promise<boolean> {
+  if (key.algorithm.name !== KeyTypes.Ecdsa) {
+    throw new Error("verifySignatureOverDigest only supports ECDSA keys");
+  }
+
+  const namedCurve = (key.algorithm as EcKeyAlgorithm).namedCurve;
+  let curve: typeof p256 | typeof p384 | typeof p521;
+
+  if (namedCurve === EcdsaTypes.P256) {
+    curve = p256;
+  } else if (namedCurve === EcdsaTypes.P384) {
+    curve = p384;
+  } else if (namedCurve === EcdsaTypes.P521) {
+    curve = p521;
+  } else {
+    throw new Error(`Unsupported curve: ${namedCurve}`);
+  }
+
+  // Export the public key to get x and y coordinates
+  const jwk = await crypto.subtle.exportKey("jwk", key);
+  if (!jwk.x || !jwk.y) {
+    throw new Error("Invalid ECDSA public key: missing x or y coordinates");
+  }
+
+  // Convert base64url JWK coordinates to bytes
+  const x = base64UrlToUint8Array(jwk.x);
+  const y = base64UrlToUint8Array(jwk.y);
+
+  // Combine x and y into uncompressed public key format (0x04 || x || y)
+  const publicKey = new Uint8Array(1 + x.length + y.length);
+  publicKey[0] = 0x04;
+  publicKey.set(x, 1);
+  publicKey.set(y, 1 + x.length);
+
+  // Verify the DER-encoded signature over the digest
+  // @noble/curves can parse DER signatures directly with format: 'der'
+  // Options:
+  // - format: 'der' to parse DER-encoded signatures
+  // - prehash: false because we're passing a pre-computed digest, not the original message
+  // - lowS: false to accept both high-S and low-S signatures (matches elliptic.js behavior)
+  //   elliptic.js accepts malleable signatures by default, while @noble/curves rejects them by default
+  return curve.verify(sig, digest, publicKey, { format: 'der', prehash: false, lowS: false });
+}
+
+export { uint8ArrayEqual as bufferEqual } from "./encoding.js";

package/src/dsse.ts

@@ -0,0 +1,49 @@
+/*
+Copyright 2023 The Sigstore Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+const PAE_PREFIX = "DSSEv1";
+
+// DSSE Pre-Authentication Encoding
+export function preAuthEncoding(
+  payloadType: string,
+  payload: Uint8Array,
+): Uint8Array {
+  const prefix = [
+    PAE_PREFIX,
+    payloadType.length,
+    payloadType,
+    payload.length,
+    "",
+  ].join(" ");
+
+  // DSSE spec requires ASCII encoding for the prefix
+  // TextEncoder will throw if the string contains non-ASCII characters
+  const encoder = new TextEncoder();
+  const prefixBuffer = encoder.encode(prefix);
+
+  // Verify all characters are ASCII (< 128)
+  for (let i = 0; i < prefixBuffer.length; i++) {
+    if (prefixBuffer[i] > 127) {
+      throw new Error(`Invalid non-ASCII character in PAE prefix at position ${i}`);
+    }
+  }
+
+  // Concatenate prefix and payload
+  const combinedArray = new Uint8Array(prefixBuffer.length + payload.length);
+
+  combinedArray.set(prefixBuffer, 0);
+  combinedArray.set(payload, prefixBuffer.length);
+  return combinedArray;
+}