@freedomofpress/sigstore-browser 0.1.0

package/src/trust/tuf.ts

@@ -0,0 +1,223 @@
+/*
+ * TUF (The Update Framework) integration for trusted root management
+ *
+ * Provides secure updates for Sigstore trusted root metadata using TUF.
+ * Uses tuf-browser for browser-compatible TUF client functionality.
+ *
+ * Reference: https://github.com/freedomofpress/tuf-browser
+ */
+
+import type { TrustedRoot } from "../interfaces.js";
+import { Uint8ArrayToString } from "../encoding.js";
+import type { TUFClient } from "tuf-browser/dist/tuf.js";
+
+/**
+ * Options for TrustedRootProvider configuration
+ */
+export interface TrustedRootProviderOptions {
+  /**
+   * TUF repository URL for metadata
+   * Default: Sigstore production TUF repository
+   */
+  metadataUrl?: string;
+
+  /**
+   * Target base URL for fetching target files
+   * If not specified, uses the same as metadataUrl
+   */
+  targetBaseUrl?: string;
+
+  /**
+   * Initial root metadata (1.root.json content)
+   * If not provided, will use embedded default
+   */
+  initialRoot?: string;
+
+  /**
+   * Namespace for TUF cache storage
+   * Default: 'sigstore-browser'
+   */
+  namespace?: string;
+
+  /**
+   * Name of the trusted root target file
+   * Default: 'trusted_root.json'
+   */
+  trustedRootTarget?: string;
+
+  /**
+   * Cache TTL in milliseconds
+   * Default: 1 hour (3600000 ms)
+   */
+  cacheTTL?: number;
+}
+
+/**
+ * Default configuration for Sigstore production TUF repository
+ */
+const DEFAULT_CONFIG = {
+  metadataUrl: 'https://tuf-repo-cdn.sigstore.dev/',
+  namespace: 'sigstore-browser',
+  trustedRootTarget: 'trusted_root.json',
+  cacheTTL: 3600000, // 1 hour
+};
+
+/**
+ * Provides Sigstore trusted root via TUF for secure updates
+ *
+ * This class manages fetching and caching of Sigstore trusted root metadata
+ * using The Update Framework (TUF) for secure, verified updates.
+ *
+ * Example usage:
+ * ```typescript
+ * const provider = new TrustedRootProvider();
+ * const trustedRoot = await provider.getTrustedRoot();
+ * ```
+ */
+export class TrustedRootProvider {
+  private metadataUrl: string;
+  private targetBaseUrl?: string;
+  private initialRoot?: string;
+  private namespace: string;
+  private trustedRootTarget: string;
+  private cacheTTL: number;
+
+  private tufClient?: TUFClient;
+  private cachedRoot?: TrustedRoot;
+  private cacheTimestamp?: number;
+
+  constructor(options: TrustedRootProviderOptions = {}) {
+    const metadataUrl = options.metadataUrl || DEFAULT_CONFIG.metadataUrl;
+    this.metadataUrl = metadataUrl.endsWith('/') ? metadataUrl : `${metadataUrl}/`;
+    this.targetBaseUrl = options.targetBaseUrl || this.metadataUrl;
+    this.initialRoot = options.initialRoot;
+    this.namespace = options.namespace || DEFAULT_CONFIG.namespace;
+    this.trustedRootTarget = options.trustedRootTarget || DEFAULT_CONFIG.trustedRootTarget;
+    this.cacheTTL = options.cacheTTL ?? DEFAULT_CONFIG.cacheTTL;
+  }
+
+  /**
+   * Initialize the TUF client
+   * Lazy initialization to avoid loading TUF client until needed
+   */
+  private async initTUFClient(): Promise<void> {
+    if (this.tufClient) {
+      return;
+    }
+
+    try {
+      const { TUFClient } = await import('tuf-browser/dist/tuf.js');
+
+      // Get initial root metadata
+      const rootMetadata = this.initialRoot || await this.getDefaultRoot();
+
+      this.tufClient = new TUFClient(
+        this.metadataUrl,
+        rootMetadata,
+        this.namespace,
+        this.targetBaseUrl
+      );
+    } catch (error) {
+      throw new Error(
+        `Failed to initialize TUF client: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Get the default embedded root metadata
+   * Returns the TUF root.json that bootstraps the TUF client
+   */
+  private async getDefaultRoot(): Promise<string> {
+    // Import the embedded TUF root metadata (base64-encoded 1.root.json as JSON string)
+    // This is the root of trust for TUF, not to be confused with the Sigstore trusted root
+    const tufRootModule = await import('./tuf-root.json', { with: { type: 'json' } });
+    const tufRootBase64 = tufRootModule.default as string;
+
+    // Decode from base64 to get the actual root.json content
+    const decoder = new TextDecoder();
+    const rootBytes = Uint8Array.from(atob(tufRootBase64), c => c.charCodeAt(0));
+    return decoder.decode(rootBytes);
+  }
+
+  /**
+   * Check if cached trusted root is still valid
+   */
+  private isCacheValid(): boolean {
+    if (!this.cachedRoot || !this.cacheTimestamp) {
+      return false;
+    }
+
+    const now = Date.now();
+    return (now - this.cacheTimestamp) < this.cacheTTL;
+  }
+
+  /**
+   * Get the Sigstore trusted root metadata
+   * Uses TUF to securely fetch and verify the trusted root
+   *
+   * @returns Promise<TrustedRoot> The verified trusted root metadata
+   * @throws Error if TUF verification fails or root cannot be fetched
+   */
+  async getTrustedRoot(): Promise<TrustedRoot> {
+    // Return cached root if still valid
+    if (this.isCacheValid() && this.cachedRoot) {
+      return this.cachedRoot;
+    }
+
+    // Initialize TUF client if needed
+    await this.initTUFClient();
+
+    if (!this.tufClient) {
+      throw new Error('TUF client not initialized');
+    }
+
+    try {
+      // Update TUF metadata (root, timestamp, snapshot, targets)
+      // This must be called before getTarget() to populate the metadata cache
+      await this.tufClient.updateTUF();
+
+      // Fetch the trusted root target via TUF
+      // TUF will handle all verification (signatures, rollback protection, etc.)
+      const trustedRootBytes = await this.tufClient.getTarget(this.trustedRootTarget);
+
+      // Parse the trusted root JSON
+      const trustedRootJson = Uint8ArrayToString(trustedRootBytes);
+      const trustedRoot = JSON.parse(trustedRootJson) as TrustedRoot;
+
+      // Cache the result
+      this.cachedRoot = trustedRoot;
+      this.cacheTimestamp = Date.now();
+
+      return trustedRoot;
+    } catch (error) {
+      throw new Error(
+        `Failed to fetch trusted root via TUF: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Manually refresh the trusted root from TUF
+   * Bypasses cache and forces a fresh fetch
+   *
+   * @returns Promise<TrustedRoot> The updated trusted root metadata
+   */
+  async refreshTrustedRoot(): Promise<TrustedRoot> {
+    // Clear cache
+    this.cachedRoot = undefined;
+    this.cacheTimestamp = undefined;
+
+    // Fetch fresh root
+    return await this.getTrustedRoot();
+  }
+
+  /**
+   * Clear the cached trusted root
+   * Next call to getTrustedRoot() will fetch fresh data
+   */
+  clearCache(): void {
+    this.cachedRoot = undefined;
+    this.cacheTimestamp = undefined;
+  }
+}

package/src/types/tuf-browser.d.ts

@@ -0,0 +1,13 @@
+declare module 'tuf-browser/dist/tuf.js' {
+  export class TUFClient {
+    constructor(
+      repositoryUrl: string,
+      startingRoot: string,
+      namespace: string,
+      targetBaseUrl?: string
+    );
+
+    updateTUF(): Promise<void>;
+    getTarget(targetPath: string): Promise<Uint8Array>;
+  }
+}

package/src/x509/cert.ts

@@ -0,0 +1,319 @@
+/*
+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.
+*/
+import { ASN1Obj } from "../asn1/index.js";
+import { bufferEqual, importKey, verifySignature } from "../crypto.js";
+import { Uint8ArrayToBase64 } from "../encoding.js";
+import { KeyTypes } from "../interfaces.js";
+import { ECDSA_CURVE_NAMES, ECDSA_SIGNATURE_ALGOS, RSA_SIGNATURE_ALGOS } from "../oid.js";
+import * as pem from "../pem.js";
+import {
+  X509AuthorityKeyIDExtension,
+  X509BasicConstraintsExtension,
+  X509Extension,
+  X509FulcioIssuerV1,
+  X509FulcioIssuerV2,
+  X509KeyUsageExtension,
+  X509SCTExtension,
+  X509SubjectAlternativeNameExtension,
+  X509SubjectKeyIDExtension,
+} from "./ext.js";
+
+// https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md
+const EXTENSION_OID_SUBJECT_KEY_ID = "2.5.29.14";
+const EXTENSION_OID_KEY_USAGE = "2.5.29.15";
+const EXTENSION_OID_SUBJECT_ALT_NAME = "2.5.29.17";
+const EXTENSION_OID_BASIC_CONSTRAINTS = "2.5.29.19";
+const EXTENSION_OID_AUTHORITY_KEY_ID = "2.5.29.35";
+const EXTENSION_OID_FULCIO_ISSUER_V1 = "1.3.6.1.4.1.57264.1.1";
+const EXTENSION_OID_FULCIO_ISSUER_V2 = "1.3.6.1.4.1.57264.1.8";
+
+export const EXTENSION_OID_SCT = "1.3.6.1.4.1.11129.2.4.2";
+
+export class X509Certificate {
+  public root: ASN1Obj;
+
+  constructor(asn1: ASN1Obj) {
+    this.root = asn1;
+  }
+
+  public static parse(cert: Uint8Array | string): X509Certificate {
+    const der = typeof cert === "string" ? pem.toDER(cert) : cert;
+    const asn1 = ASN1Obj.parseBuffer(der);
+    return new X509Certificate(asn1);
+  }
+
+  get tbsCertificate(): ASN1Obj {
+    return this.tbsCertificateObj;
+  }
+
+  get version(): string {
+    // version number is the first element of the version context specific tag
+    const ver = this.versionObj.subs[0].toInteger();
+    return `v${(ver + BigInt(1)).toString()}`;
+  }
+
+  get serialNumber(): Uint8Array {
+    return this.serialNumberObj.value;
+  }
+
+  get notBefore(): Date {
+    // notBefore is the first element of the validity sequence
+    return this.validityObj.subs[0].toDate();
+  }
+
+  get notAfter(): Date {
+    // notAfter is the second element of the validity sequence
+    return this.validityObj.subs[1].toDate();
+  }
+
+  get issuer(): Uint8Array {
+    return this.issuerObj.value;
+  }
+
+  get subject(): Uint8Array {
+    return this.subjectObj.value;
+  }
+
+  get publicKey(): Uint8Array {
+    return this.subjectPublicKeyInfoObj.toDER();
+  }
+
+  /**
+   * Import the public key with a specific hash algorithm for RSA keys
+   * For ECDSA keys, the hash parameter is ignored
+   */
+  public async getPublicKeyObj(hashAlg?: string): Promise<CryptoKey> {
+    const publicKey = this.subjectPublicKeyInfoObj.toDER();
+    const spki = ASN1Obj.parseBuffer(publicKey);
+    const algorithmOID = spki.subs[0].subs[0].toOID();
+
+    // Check if it's an RSA key (OID 1.2.840.113549.1.1.1)
+    if (algorithmOID === "1.2.840.113549.1.1.1") {
+      // RSA key - use provided hash or default to SHA-256
+      const hash = hashAlg || "sha256";
+      let scheme: string;
+      if (hash.includes("384")) {
+        scheme = "SHA384";
+      } else if (hash.includes("512")) {
+        scheme = "SHA512";
+      } else {
+        scheme = "SHA256";
+      }
+      return importKey("RSA", `RSA_PKCS1V5_${scheme}`, Uint8ArrayToBase64(publicKey));
+    } else {
+      // ECDSA key - the curve OID is in the second element
+      const curveOID = spki.subs[0].subs[1]?.toOID();
+      const curve = ECDSA_CURVE_NAMES[curveOID];
+      if (!curve) {
+        throw new Error(`Unknown ECDSA curve OID: ${curveOID}`);
+      }
+      return importKey(KeyTypes.Ecdsa, curve, Uint8ArrayToBase64(publicKey));
+    }
+  }
+
+  get publicKeyObj(): Promise<CryptoKey> {
+    return this.getPublicKeyObj();
+  }
+
+  get signatureAlgorithm(): string {
+    const oid: string = this.signatureAlgorithmObj.subs[0].toOID();
+    return ECDSA_SIGNATURE_ALGOS[oid];
+  }
+
+  get signatureValue(): Uint8Array {
+    // Signature value is a bit string, so we need to skip the first byte
+    return this.signatureValueObj.value.subarray(1);
+  }
+
+  get subjectAltName(): string | undefined {
+    const ext = this.extSubjectAltName;
+    return ext?.uri || ext?.rfc822Name;
+  }
+
+  get extensions(): ASN1Obj[] {
+    // The extension list is the first (and only) element of the extensions
+    // context specific tag
+    const extSeq = this.extensionsObj?.subs[0];
+    return extSeq?.subs || /* istanbul ignore next */ [];
+  }
+
+  get extKeyUsage(): X509KeyUsageExtension | undefined {
+    const ext = this.findExtension(EXTENSION_OID_KEY_USAGE);
+    return ext ? new X509KeyUsageExtension(ext) : undefined;
+  }
+
+  get extBasicConstraints(): X509BasicConstraintsExtension | undefined {
+    const ext = this.findExtension(EXTENSION_OID_BASIC_CONSTRAINTS);
+    return ext ? new X509BasicConstraintsExtension(ext) : undefined;
+  }
+
+  get extSubjectAltName(): X509SubjectAlternativeNameExtension | undefined {
+    const ext = this.findExtension(EXTENSION_OID_SUBJECT_ALT_NAME);
+    return ext ? new X509SubjectAlternativeNameExtension(ext) : undefined;
+  }
+
+  get extAuthorityKeyID(): X509AuthorityKeyIDExtension | undefined {
+    const ext = this.findExtension(EXTENSION_OID_AUTHORITY_KEY_ID);
+    return ext ? new X509AuthorityKeyIDExtension(ext) : undefined;
+  }
+
+  get extSubjectKeyID(): X509SubjectKeyIDExtension | undefined {
+    const ext = this.findExtension(EXTENSION_OID_SUBJECT_KEY_ID);
+    return ext
+      ? new X509SubjectKeyIDExtension(ext)
+      : /* istanbul ignore next */ undefined;
+  }
+
+  get extSCT(): X509SCTExtension | undefined {
+    const ext = this.findExtension(EXTENSION_OID_SCT);
+    return ext ? new X509SCTExtension(ext) : undefined;
+  }
+
+  get extFulcioIssuerV1(): X509FulcioIssuerV1 | undefined {
+    const ext = this.findExtension(EXTENSION_OID_FULCIO_ISSUER_V1);
+    return ext ? new X509FulcioIssuerV1(ext) : undefined;
+  }
+
+  get extFulcioIssuerV2(): X509FulcioIssuerV2 | undefined {
+    const ext = this.findExtension(EXTENSION_OID_FULCIO_ISSUER_V2);
+    return ext ? new X509FulcioIssuerV2(ext) : undefined;
+  }
+
+  get isCA(): boolean {
+    const ca = this.extBasicConstraints?.isCA || false;
+
+    // If the KeyUsage extension is present, keyCertSign must be set
+    if (this.extKeyUsage) {
+      return ca && this.extKeyUsage.keyCertSign;
+    }
+
+    return ca;
+  }
+
+  public extension(oid: string): X509Extension | undefined {
+    const ext = this.findExtension(oid);
+    return ext ? new X509Extension(ext) : undefined;
+  }
+
+  public async verify(issuerCertificate?: X509Certificate): Promise<boolean> {
+    // Extract the hash algorithm from this certificate's signature algorithm
+    // (not the issuer's own signature algorithm)
+    const sigAlgOID = this.signatureAlgorithmObj.subs[0].toOID();
+    const hashAlg = RSA_SIGNATURE_ALGOS[sigAlgOID] || ECDSA_SIGNATURE_ALGOS[sigAlgOID];
+
+    // Use the issuer's public key if provided, otherwise use the subject's (for self-signed certs)
+    // Import with the correct hash algorithm for this certificate's signature
+    const publicKeyObj = issuerCertificate
+      ? await issuerCertificate.getPublicKeyObj(hashAlg)
+      : await this.getPublicKeyObj(hashAlg);
+
+    return await verifySignature(
+      publicKeyObj,
+      this.tbsCertificate.toDER(),
+      this.signatureValue,
+      this.signatureAlgorithm,
+    );
+  }
+
+  public validForDate(date: Date): boolean {
+    return this.notBefore <= date && date <= this.notAfter;
+  }
+
+  public equals(other: X509Certificate): boolean {
+    return bufferEqual(this.root.toDER(), other.root.toDER());
+  }
+
+  // Creates a copy of the certificate with a new buffer
+  public clone(): X509Certificate {
+    const der = this.root.toDER();
+    const clone = new Uint8Array(der);
+    return X509Certificate.parse(clone);
+  }
+
+  private findExtension(oid: string): ASN1Obj | undefined {
+    // Find the extension with the given OID. The OID will always be the first
+    // element of the extension sequence
+    return this.extensions.find((ext) => ext.subs[0].toOID() === oid);
+  }
+
+  /////////////////////////////////////////////////////////////////////////////
+  // The following properties use the documented x509 structure to locate the
+  // desired ASN.1 object
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1
+
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1.1.1
+  private get tbsCertificateObj(): ASN1Obj {
+    // tbsCertificate is the first element of the certificate sequence
+    return this.root.subs[0];
+  }
+
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1.1.2
+  private get signatureAlgorithmObj(): ASN1Obj {
+    // signatureAlgorithm is the second element of the certificate sequence
+    return this.root.subs[1];
+  }
+
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1.1.3
+  private get signatureValueObj(): ASN1Obj {
+    // signatureValue is the third element of the certificate sequence
+    return this.root.subs[2];
+  }
+
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.1
+  private get versionObj(): ASN1Obj {
+    // version is the first element of the tbsCertificate sequence
+    return this.tbsCertificateObj.subs[0];
+  }
+
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.2
+  private get serialNumberObj(): ASN1Obj {
+    // serialNumber is the second element of the tbsCertificate sequence
+    return this.tbsCertificateObj.subs[1];
+  }
+
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.4
+  private get issuerObj(): ASN1Obj {
+    // issuer is the fourth element of the tbsCertificate sequence
+    return this.tbsCertificateObj.subs[3];
+  }
+
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.5
+  private get validityObj(): ASN1Obj {
+    // version is the fifth element of the tbsCertificate sequence
+    return this.tbsCertificateObj.subs[4];
+  }
+
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.6
+  private get subjectObj(): ASN1Obj {
+    // subject is the sixth element of the tbsCertificate sequence
+    return this.tbsCertificateObj.subs[5];
+  }
+
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.7
+  private get subjectPublicKeyInfoObj(): ASN1Obj {
+    // subjectPublicKeyInfo is the seventh element of the tbsCertificate sequence
+    return this.tbsCertificateObj.subs[6];
+  }
+
+  // Extensions can't be located by index because their position varies. Instead,
+  // we need to find the extensions context specific tag
+  // https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.9
+  private get extensionsObj(): ASN1Obj | undefined {
+    return this.tbsCertificateObj.subs.find((sub) =>
+      sub.tag.isContextSpecific(0x03),
+    );
+  }
+}