@enactprotocol/trust 2.0.0

package/src/sigstore/verification.ts

@@ -0,0 +1,355 @@
+/**
+ * Sigstore verification module
+ *
+ * This module provides verification capabilities for Sigstore bundles and attestations.
+ * It verifies signatures, certificates, and transparency log entries.
+ *
+ * NOTE: This implementation bypasses TUF (The Update Framework) and uses bundled trusted
+ * roots directly. This is necessary for Bun compatibility because TUF verification fails
+ * with BoringSSL's stricter signature algorithm requirements.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { bundleFromJSON } from "@sigstore/bundle";
+import { TrustedRoot } from "@sigstore/protobuf-specs";
+import { Verifier, toSignedEntity, toTrustMaterial } from "@sigstore/verify";
+import { extractIdentityFromBundle } from "./signing";
+import type {
+  ExpectedIdentity,
+  OIDCIdentity,
+  SigstoreBundle,
+  VerificationDetails,
+  VerificationOptions,
+  VerificationResult,
+} from "./types";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Get the path to bundled TUF seeds
+ * We need to navigate from the @sigstore/tuf main entry point to find seeds.json
+ */
+function getTufSeedsPath(): string {
+  // The package.json main points to dist/index.js, but seeds.json is at package root
+  const tufPkgPath = require.resolve("@sigstore/tuf/package.json");
+  return path.join(path.dirname(tufPkgPath), "seeds.json");
+}
+
+// ============================================================================
+// Trusted Root Management
+// ============================================================================
+
+/**
+ * Load the trusted root from bundled TUF seeds
+ * This bypasses TUF's online verification which fails with BoringSSL
+ */
+async function loadTrustedRoot(): Promise<ReturnType<typeof TrustedRoot.fromJSON>> {
+  const seedsPath = getTufSeedsPath();
+  const seeds = JSON.parse(fs.readFileSync(seedsPath, "utf8"));
+  const seedData = seeds["https://tuf-repo-cdn.sigstore.dev"];
+  const trustedRootB64 = seedData.targets["trusted_root.json"];
+  const trustedRootJson = JSON.parse(Buffer.from(trustedRootB64, "base64").toString());
+  return TrustedRoot.fromJSON(trustedRootJson);
+}
+
+/**
+ * Create trust material from the bundled trusted root
+ */
+async function createTrustMaterial() {
+  const trustedRoot = await loadTrustedRoot();
+  return toTrustMaterial(trustedRoot);
+}
+
+// ============================================================================
+// Verification Functions
+// ============================================================================
+
+/**
+ * Verify a Sigstore bundle
+ *
+ * @param bundle - The Sigstore bundle to verify
+ * @param artifact - Optional artifact data (for message signature bundles)
+ * @param options - Verification options
+ * @returns Verification result with detailed checks
+ *
+ * @example
+ * ```ts
+ * const result = await verifyBundle(bundle, artifact, {
+ *   expectedIdentity: {
+ *     subjectAlternativeName: "user@example.com",
+ *     issuer: "https://accounts.google.com"
+ *   }
+ * });
+ * if (result.verified) {
+ *   console.log("Bundle verified successfully");
+ * }
+ * ```
+ */
+export async function verifyBundle(
+  bundle: SigstoreBundle,
+  artifact?: Buffer,
+  options: VerificationOptions = {}
+): Promise<VerificationResult> {
+  const details: VerificationDetails = {
+    signatureValid: false,
+    certificateValid: false,
+    certificateWithinValidity: false,
+    rekorEntryValid: false,
+    inclusionProofValid: false,
+    errors: [],
+  };
+
+  try {
+    // Create trust material from bundled roots
+    const trustMaterial = await createTrustMaterial();
+
+    // Create verifier
+    const verifier = new Verifier(trustMaterial);
+
+    // Convert bundle to proper format
+    const parsedBundle = bundleFromJSON(bundle);
+    const signedEntity = toSignedEntity(parsedBundle, artifact);
+
+    // Perform verification
+    verifier.verify(signedEntity);
+
+    // If we get here, verification passed
+    details.signatureValid = true;
+    details.certificateValid = true;
+    details.certificateWithinValidity = true;
+    details.rekorEntryValid = true;
+    details.inclusionProofValid = true;
+
+    // Extract identity from bundle
+    const identity = extractIdentityFromBundle(bundle);
+
+    // Check identity if expected identity is provided
+    if (options.expectedIdentity) {
+      details.identityMatches = matchesExpectedIdentity(identity, options.expectedIdentity);
+      if (!details.identityMatches) {
+        details.errors.push("Identity does not match expected values");
+        const result: VerificationResult = {
+          verified: false,
+          error: "Identity mismatch",
+          details,
+        };
+        if (identity) result.identity = identity;
+        const timestamp = extractTimestampFromBundle(bundle);
+        if (timestamp) result.timestamp = timestamp;
+        return result;
+      }
+    }
+
+    const result: VerificationResult = {
+      verified: true,
+      details,
+    };
+    if (identity) result.identity = identity;
+    const timestamp = extractTimestampFromBundle(bundle);
+    if (timestamp) result.timestamp = timestamp;
+    return result;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    details.errors.push(errorMessage);
+
+    // Try to determine which check failed based on error message
+    categorizeVerificationError(errorMessage, details);
+
+    return {
+      verified: false,
+      error: errorMessage,
+      details,
+    };
+  }
+}
+
+/**
+ * Create a reusable verifier for multiple verifications
+ *
+ * @param options - Verification options
+ * @returns A verifier object that can verify multiple bundles
+ *
+ * @example
+ * ```ts
+ * const verifier = await createBundleVerifier({
+ *   expectedIdentity: { issuer: "https://accounts.google.com" }
+ * });
+ *
+ * // Verify multiple bundles efficiently
+ * for (const bundle of bundles) {
+ *   verifier.verify(bundle);
+ * }
+ * ```
+ */
+export async function createBundleVerifier(options: VerificationOptions = {}) {
+  // Create trust material once and reuse
+  const trustMaterial = await createTrustMaterial();
+  const verifier = new Verifier(trustMaterial);
+
+  return {
+    /**
+     * Verify a bundle using the cached verifier
+     */
+    verify: async (bundle: SigstoreBundle, artifact?: Buffer): Promise<VerificationResult> => {
+      const details: VerificationDetails = {
+        signatureValid: false,
+        certificateValid: false,
+        certificateWithinValidity: false,
+        rekorEntryValid: false,
+        inclusionProofValid: false,
+        errors: [],
+      };
+
+      try {
+        // Convert bundle to proper format
+        const parsedBundle = bundleFromJSON(bundle);
+        const signedEntity = toSignedEntity(parsedBundle, artifact);
+
+        // Perform verification
+        verifier.verify(signedEntity);
+
+        details.signatureValid = true;
+        details.certificateValid = true;
+        details.certificateWithinValidity = true;
+        details.rekorEntryValid = true;
+        details.inclusionProofValid = true;
+
+        const identity = extractIdentityFromBundle(bundle);
+
+        if (options.expectedIdentity) {
+          details.identityMatches = matchesExpectedIdentity(identity, options.expectedIdentity);
+          if (!details.identityMatches) {
+            details.errors.push("Identity does not match expected values");
+            const result: VerificationResult = {
+              verified: false,
+              error: "Identity mismatch",
+              details,
+            };
+            if (identity) result.identity = identity;
+            const timestamp = extractTimestampFromBundle(bundle);
+            if (timestamp) result.timestamp = timestamp;
+            return result;
+          }
+        }
+
+        const result: VerificationResult = {
+          verified: true,
+          details,
+        };
+        if (identity) result.identity = identity;
+        const timestamp = extractTimestampFromBundle(bundle);
+        if (timestamp) result.timestamp = timestamp;
+        return result;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        details.errors.push(errorMessage);
+        categorizeVerificationError(errorMessage, details);
+
+        return {
+          verified: false,
+          error: errorMessage,
+          details,
+        };
+      }
+    },
+  };
+}
+
+/**
+ * Quick verification check - returns boolean only
+ *
+ * @param bundle - The Sigstore bundle to verify
+ * @param artifact - Optional artifact data
+ * @returns True if verification passes, false otherwise
+ */
+export async function isVerified(bundle: SigstoreBundle, artifact?: Buffer): Promise<boolean> {
+  try {
+    const trustMaterial = await createTrustMaterial();
+    const verifier = new Verifier(trustMaterial);
+    const parsedBundle = bundleFromJSON(bundle);
+    const signedEntity = toSignedEntity(parsedBundle, artifact);
+    verifier.verify(signedEntity);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Check if an identity matches expected values
+ */
+function matchesExpectedIdentity(
+  identity: OIDCIdentity | undefined,
+  expected: ExpectedIdentity
+): boolean {
+  if (!identity) {
+    return false;
+  }
+
+  // Check issuer
+  if (expected.issuer && identity.issuer !== expected.issuer) {
+    return false;
+  }
+
+  // Check subject alternative name (could be email or URI)
+  if (expected.subjectAlternativeName) {
+    const san = expected.subjectAlternativeName;
+    if (identity.email !== san && identity.subject !== san) {
+      return false;
+    }
+  }
+
+  // Check GitHub workflow repository
+  if (expected.workflowRepository && identity.workflowRepository !== expected.workflowRepository) {
+    return false;
+  }
+
+  // Check GitHub workflow ref
+  if (expected.workflowRef && identity.workflowRef !== expected.workflowRef) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Extract timestamp from a Sigstore bundle
+ */
+function extractTimestampFromBundle(bundle: SigstoreBundle): Date | undefined {
+  // Try to get timestamp from transparency log entry
+  const tlogEntry = bundle.verificationMaterial?.tlogEntries?.[0];
+  if (tlogEntry?.integratedTime) {
+    const timestamp = Number.parseInt(tlogEntry.integratedTime, 10);
+    if (!Number.isNaN(timestamp)) {
+      return new Date(timestamp * 1000);
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Categorize a verification error to update details
+ */
+function categorizeVerificationError(errorMessage: string, details: VerificationDetails): void {
+  const lowerError = errorMessage.toLowerCase();
+
+  if (lowerError.includes("signature")) {
+    details.signatureValid = false;
+  } else if (lowerError.includes("certificate") && lowerError.includes("expired")) {
+    details.certificateWithinValidity = false;
+  } else if (lowerError.includes("certificate")) {
+    details.certificateValid = false;
+  } else if (lowerError.includes("rekor") || lowerError.includes("transparency")) {
+    details.rekorEntryValid = false;
+  } else if (lowerError.includes("inclusion") || lowerError.includes("proof")) {
+    details.inclusionProofValid = false;
+  }
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Type definitions for security operations
+ */
+
+// ============================================================================
+// Hash Types
+// ============================================================================
+
+/**
+ * Supported hash algorithms
+ */
+export type HashAlgorithm = "sha256" | "sha512";
+
+/**
+ * Result of a hash operation
+ */
+export interface HashResult {
+  /** The hash algorithm used */
+  algorithm: HashAlgorithm;
+  /** The hash digest in hexadecimal format */
+  digest: string;
+}
+
+/**
+ * Options for file hashing operations
+ */
+export interface FileHashOptions {
+  /** Hash algorithm to use (default: sha256) */
+  algorithm?: HashAlgorithm;
+  /** Progress callback for large files */
+  onProgress?: (bytesRead: number, totalBytes: number) => void;
+}
+
+// ============================================================================
+// Key Management Types
+// ============================================================================
+
+/**
+ * Supported key types
+ */
+export type KeyType = "rsa" | "ed25519" | "ecdsa";
+
+/**
+ * Key format for storage
+ */
+export type KeyFormat = "pem" | "der" | "jwk";
+
+/**
+ * A cryptographic key pair
+ */
+export interface KeyPair {
+  /** Public key */
+  publicKey: string;
+  /** Private key (encrypted or plain) */
+  privateKey: string;
+  /** Key type */
+  type: KeyType;
+  /** Key format */
+  format: KeyFormat;
+}
+
+/**
+ * Options for key generation
+ */
+export interface KeyGenerationOptions {
+  /** Key type to generate */
+  type: KeyType;
+  /** Output format */
+  format?: KeyFormat;
+  /** RSA key size in bits (only for RSA keys) */
+  modulusLength?: number;
+  /** Passphrase for encrypting private key */
+  passphrase?: string;
+}
+
+// ============================================================================
+// Placeholder for other types
+// ============================================================================
+
+export type SecurityConfig = Record<string, unknown>;

package/tests/hash.test.ts

@@ -0,0 +1,180 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { hashBuffer, hashContent, hashFile } from "../src/hash";
+
+const TEST_DIR = join(import.meta.dir, "fixtures");
+const TEST_FILE = join(TEST_DIR, "test.txt");
+const LARGE_FILE = join(TEST_DIR, "large.txt");
+const BINARY_FILE = join(TEST_DIR, "binary.dat");
+
+describe("hash utilities", () => {
+  beforeAll(() => {
+    // Create test directory and files
+    mkdirSync(TEST_DIR, { recursive: true });
+    writeFileSync(TEST_FILE, "hello world");
+
+    // Create a larger file for streaming tests
+    writeFileSync(LARGE_FILE, "x".repeat(1024 * 1024)); // 1MB file
+
+    // Create a binary file
+    const binaryData = Buffer.from([0x00, 0x01, 0x02, 0xff, 0xfe, 0xfd]);
+    writeFileSync(BINARY_FILE, binaryData);
+  });
+
+  afterAll(() => {
+    // Clean up test files
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  });
+
+  describe("hashContent", () => {
+    test("hashes string content with sha256", () => {
+      const result = hashContent("hello world");
+
+      expect(result.algorithm).toBe("sha256");
+      expect(result.digest).toBe(
+        "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+      );
+    });
+
+    test("hashes string content with sha512", () => {
+      const result = hashContent("hello world", "sha512");
+
+      expect(result.algorithm).toBe("sha512");
+      expect(result.digest).toBe(
+        "309ecc489c12d6eb4cc40f50c902f2b4d0ed77ee511a7c7a9bcd3ca86d4cd86f989dd35bc5ff499670da34255b45b0cfd830e81f605dcf7dc5542e93ae9cd76f"
+      );
+    });
+
+    test("hashes buffer content", () => {
+      const buffer = Buffer.from("hello world");
+      const result = hashContent(buffer);
+
+      expect(result.digest).toBe(
+        "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+      );
+    });
+
+    test("produces consistent hashes for same content", () => {
+      const result1 = hashContent("test content");
+      const result2 = hashContent("test content");
+
+      expect(result1.digest).toBe(result2.digest);
+    });
+
+    test("produces different hashes for different content", () => {
+      const result1 = hashContent("content 1");
+      const result2 = hashContent("content 2");
+
+      expect(result1.digest).not.toBe(result2.digest);
+    });
+
+    test("handles empty string", () => {
+      const result = hashContent("");
+
+      expect(result.digest).toBe(
+        "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+      );
+    });
+
+    test("handles unicode content", () => {
+      const result = hashContent("Hello 世界 🌍");
+
+      expect(result.algorithm).toBe("sha256");
+      expect(result.digest).toHaveLength(64); // sha256 produces 64 hex chars
+    });
+  });
+
+  describe("hashBuffer", () => {
+    test("hashes buffer data", () => {
+      const buffer = Buffer.from("hello world");
+      const result = hashBuffer(buffer);
+
+      expect(result.digest).toBe(
+        "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+      );
+    });
+
+    test("hashes binary data", () => {
+      const buffer = Buffer.from([0x00, 0x01, 0x02, 0xff]);
+      const result = hashBuffer(buffer);
+
+      expect(result.algorithm).toBe("sha256");
+      expect(result.digest).toHaveLength(64);
+    });
+
+    test("supports sha512 algorithm", () => {
+      const buffer = Buffer.from("test");
+      const result = hashBuffer(buffer, "sha512");
+
+      expect(result.algorithm).toBe("sha512");
+      expect(result.digest).toHaveLength(128); // sha512 produces 128 hex chars
+    });
+  });
+
+  describe("hashFile", () => {
+    test("hashes file content", async () => {
+      const result = await hashFile(TEST_FILE);
+
+      expect(result.algorithm).toBe("sha256");
+      expect(result.digest).toBe(
+        "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+      );
+    });
+
+    test("hashes file with sha512", async () => {
+      const result = await hashFile(TEST_FILE, { algorithm: "sha512" });
+
+      expect(result.algorithm).toBe("sha512");
+      expect(result.digest).toHaveLength(128);
+    });
+
+    test("hashes large file with streaming", async () => {
+      const result = await hashFile(LARGE_FILE);
+
+      expect(result.algorithm).toBe("sha256");
+      expect(result.digest).toHaveLength(64);
+    });
+
+    test("hashes binary file", async () => {
+      const result = await hashFile(BINARY_FILE);
+
+      expect(result.algorithm).toBe("sha256");
+      expect(result.digest).toHaveLength(64);
+    });
+
+    test("calls progress callback during hashing", async () => {
+      const progressCalls: Array<{ read: number; total: number }> = [];
+
+      await hashFile(LARGE_FILE, {
+        onProgress: (bytesRead, totalBytes) => {
+          progressCalls.push({ read: bytesRead, total: totalBytes });
+        },
+      });
+
+      expect(progressCalls.length).toBeGreaterThan(0);
+
+      // Last call should have read all bytes
+      const lastCall = progressCalls[progressCalls.length - 1];
+      if (lastCall) {
+        expect(lastCall.read).toBe(lastCall.total);
+      }
+    });
+
+    test("throws error for non-existent file", async () => {
+      await expect(hashFile("/nonexistent/file.txt")).rejects.toThrow("Failed to access file");
+    });
+
+    test("throws error for directory path", async () => {
+      await expect(hashFile(TEST_DIR)).rejects.toThrow("Path is not a file");
+    });
+
+    test("produces same hash as hashContent for same data", async () => {
+      const content = "hello world";
+      const contentResult = hashContent(content);
+      const fileResult = await hashFile(TEST_FILE);
+
+      expect(fileResult.digest).toBe(contentResult.digest);
+    });
+  });
+});

package/tests/index.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, test } from "bun:test";
+import { version } from "../src/index";
+
+describe("@enactprotocol/security", () => {
+  test("exports version", () => {
+    expect(version).toBe("0.1.0");
+  });
+});