@ggui-ai/gadget-signing 0.6.2 → 0.7.0

package/dist/index.d.ts

@@ -110,8 +110,11 @@ export declare function isGadgetSignature(value: unknown): value is GadgetSignat
 export declare function canonicalJson(value: unknown): string;
 /**
  * Derive a stable public-key identifier from a 32-byte Ed25519 public key.
- * `base64(sha256(publicKey))[:16]`. Used as the registry's stable handle
- * for a stored author public key.
+ * `base64url(sha256(publicKey))[:16]` — RFC 4648 §5 URL-safe alphabet
+ * (`-`/`_`, no padding), because keyIds travel as URL path segments
+ * (`DELETE /author-keys/{keyId}`) and as storage row-key components;
+ * standard base64 would put `/` in ~22% of ids. Used as the registry's
+ * stable handle for a stored author public key.
  */
 export declare function derivePublicKeyId(publicKey: Uint8Array): string;
 /**
@@ -248,14 +251,41 @@ export interface VerifyBundleSigstoreInput {
         readonly issuer?: string;
     };
     /**
-     * Optional endpoint overrides — only meaningful when paired with a
-     * non-prod TUF mirror. Production gadgets verify against the prod
-     * Sigstore TUF root.
+     * TUF mirror serving the trust-root metadata + targets. When unset,
+     * the upstream verifier resolves against the Sigstore public-good
+     * mirror. Point this (together with {@link tufRootPath}) at an
+     * alternative TUF repository for private sigstore deployments and
+     * hermetic tests — verification never contacts Fulcio/Rekor
+     * directly, so the TUF trust root is THE knob that selects which
+     * signing infrastructure a verifier trusts.
      */
-    readonly endpoints?: {
-        readonly fulcioURL?: string;
-        readonly rekorURL?: string;
-    };
+    readonly tufMirrorURL?: string;
+    /**
+     * Path to the initial TUF `root.json` that anchors trust in
+     * {@link tufMirrorURL}. Required for any non-public-good mirror
+     * (the upstream client only ships seeds for the public-good
+     * repository); ignored once a cached root exists under
+     * {@link tufCachePath}.
+     */
+    readonly tufRootPath?: string;
+    /**
+     * Writable cache directory for the sigstore TUF trust root. The
+     * upstream verifier refreshes TUF metadata into this directory
+     * before verifying; when unset it falls back to the platform
+     * app-data directory (derived from `$XDG_DATA_HOME` / `$HOME`),
+     * which read-only filesystems reject at `mkdir` time — serverless
+     * runtimes typically only allow writes under `/tmp`, so point this
+     * at e.g. `/tmp/sigstore-js` there.
+     */
+    readonly tufCachePath?: string;
+    /**
+     * Reuse cached TUF metadata without a remote refresh while the
+     * cached copy is still valid. Keeps the trust-root network
+     * round-trip off warm verification paths; a missing, expired, or
+     * corrupt cache falls back to a normal remote refresh, so this is
+     * a latency knob — never a correctness one.
+     */
+    readonly tufForceCache?: boolean;
 }
 /**
  * Verify a sigstore-signed gadget bundle.
@@ -282,10 +312,19 @@ export interface VerifyBundleSigstoreInput {
 export declare function verifyBundleSigstore(input: VerifyBundleSigstoreInput): Promise<VerifyResult>;
 /**
  * Extract the Fulcio leaf cert's base64 raw bytes from a
- * {@link SigstoreSignature}'s serialized cosign bundle (per
- * `@sigstore/bundle` v0.3, `verificationMaterial.x509CertificateChain
- * .certificates[0].rawBytes`). Returns `undefined` if the bundle is
- * malformed or missing the cert chain.
+ * {@link SigstoreSignature}'s serialized cosign bundle. Two
+ * `verificationMaterial` shapes exist on the wire:
+ *
+ *   - `certificate.rawBytes` — the single-leaf shape bundle v0.3
+ *     emits. What real `sigstore.sign()` produces today (surfaced by
+ *     this path's first real signing run, 2026-08-10 — the extractor
+ *     previously only knew the chain shape and returned `undefined`
+ *     for every genuinely-signed bundle).
+ *   - `x509CertificateChain.certificates[0].rawBytes` — the v0.1/v0.2
+ *     chain shape, still valid on the wire for externally-produced
+ *     bundles.
+ *
+ * Returns `undefined` if the bundle is malformed or carries neither.
  *
  * Lives here — next to {@link verifyBundleSigstore} — so cosign
  * bundle-format knowledge has ONE home. Registries persist the

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAeH,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,mDAAmD;AACnD,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAWnE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAc5E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAS9E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AA4BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAqBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAQ/D;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,UAAU,CAAC,CAOrB;AAMD;;;;;GAKG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC;IACtD,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAQD;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE;IAC7C,WAAW,EAAE,UAAU,CAAC;IACxB,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgB5B;AAED,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GACpB;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACf;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,WAAW,EAAE,UAAU,CAAC;IACxB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,SAAS,EAAE,UAAU,CAAC;CACvB,GAAG,OAAO,CAAC,YAAY,CAAC,CAmDxB;AAiBD,sEAAsE;AACtE,MAAM,MAAM,wBAAwB,GAChC,cAAc,GACd,cAAc,GACd,aAAa,GACb,SAAS,CAAC;AAEd;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAM7E;AAED,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAwB5B;AAkDD,6CAA6C;AAC7C,MAAM,WAAW,yBAAyB;IACxC,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE;QAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;QAClC,4EAA4E;QAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,YAAY,CAAC,CAkFvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,iBAAiB,GAC3B,MAAM,GAAG,SAAS,CAuBpB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -31,6 +31,7 @@
 import { signAsync, verifyAsync, getPublicKeyAsync, utils } from "@noble/ed25519";
 import { sha384, sha256 } from "@noble/hashes/sha2";
 import { bundleFromJSON, bundleToJSON, } from "@sigstore/bundle";
+import { X509Certificate } from "@sigstore/core";
 import * as sigstoreClient from "sigstore";
 // ---------------------------------------------------------------------------
 // Canonical type guards.
@@ -91,6 +92,18 @@ function bytesToBase64(bytes) {
     // `btoa` exists in browsers and modern Node (>=16) globals.
     return btoa(binary);
 }
+/**
+ * base64url (RFC 4648 §5, unpadded) — the URL- and filename-safe
+ * alphabet. Used for identifiers that travel as URL path segments or
+ * become row-key/filename components ({@link derivePublicKeyId});
+ * signatures and digests stay standard base64 (JSON-body-only).
+ */
+function bytesToBase64Url(bytes) {
+    return bytesToBase64(bytes)
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/, "");
+}
 function base64ToBytes(b64) {
     const binary = atob(b64);
     const out = new Uint8Array(binary.length);
@@ -141,15 +154,18 @@ function canonicalSort(value) {
 // ---------------------------------------------------------------------------
 /**
  * Derive a stable public-key identifier from a 32-byte Ed25519 public key.
- * `base64(sha256(publicKey))[:16]`. Used as the registry's stable handle
- * for a stored author public key.
+ * `base64url(sha256(publicKey))[:16]` — RFC 4648 §5 URL-safe alphabet
+ * (`-`/`_`, no padding), because keyIds travel as URL path segments
+ * (`DELETE /author-keys/{keyId}`) and as storage row-key components;
+ * standard base64 would put `/` in ~22% of ids. Used as the registry's
+ * stable handle for a stored author public key.
  */
 export function derivePublicKeyId(publicKey) {
     if (publicKey.length !== 32) {
         throw new Error(`derivePublicKeyId: expected 32-byte Ed25519 public key, got ${publicKey.length}`);
     }
     const digest = sha256(publicKey);
-    return bytesToBase64(digest).slice(0, 16);
+    return bytesToBase64Url(digest).slice(0, 16);
 }
 /**
  * Derive the Ed25519 public key from a 32-byte private key. Deterministic
@@ -372,7 +388,7 @@ function classifySigstoreSigningError(err) {
  * `signature.bundle` JSON).
  */
 export async function verifyBundleSigstore(input) {
-    const { bundleBytes, signature, expectedIdentity } = input;
+    const { bundleBytes, signature, expectedIdentity, tufMirrorURL, tufRootPath, tufCachePath, tufForceCache, } = input;
     // 1. Fast tamper check.
     const recomputed = sha384(bundleBytes);
     const recomputedB64 = bytesToBase64(recomputed);
@@ -425,6 +441,18 @@ export async function verifyBundleSigstore(input) {
     // 4. Run the full upstream verify.
     try {
         const verifyOpts = {};
+        if (tufMirrorURL !== undefined) {
+            verifyOpts.tufMirrorURL = tufMirrorURL;
+        }
+        if (tufRootPath !== undefined) {
+            verifyOpts.tufRootPath = tufRootPath;
+        }
+        if (tufCachePath !== undefined) {
+            verifyOpts.tufCachePath = tufCachePath;
+        }
+        if (tufForceCache !== undefined) {
+            verifyOpts.tufForceCache = tufForceCache;
+        }
         if (expectedIdentity) {
             if (typeof expectedIdentity.subject === "string") {
                 // Use email-shaped vs URI-shaped routing per upstream's two
@@ -455,10 +483,19 @@ export async function verifyBundleSigstore(input) {
 }
 /**
  * Extract the Fulcio leaf cert's base64 raw bytes from a
- * {@link SigstoreSignature}'s serialized cosign bundle (per
- * `@sigstore/bundle` v0.3, `verificationMaterial.x509CertificateChain
- * .certificates[0].rawBytes`). Returns `undefined` if the bundle is
- * malformed or missing the cert chain.
+ * {@link SigstoreSignature}'s serialized cosign bundle. Two
+ * `verificationMaterial` shapes exist on the wire:
+ *
+ *   - `certificate.rawBytes` — the single-leaf shape bundle v0.3
+ *     emits. What real `sigstore.sign()` produces today (surfaced by
+ *     this path's first real signing run, 2026-08-10 — the extractor
+ *     previously only knew the chain shape and returned `undefined`
+ *     for every genuinely-signed bundle).
+ *   - `x509CertificateChain.certificates[0].rawBytes` — the v0.1/v0.2
+ *     chain shape, still valid on the wire for externally-produced
+ *     bundles.
+ *
+ * Returns `undefined` if the bundle is malformed or carries neither.
  *
  * Lives here — next to {@link verifyBundleSigstore} — so cosign
  * bundle-format knowledge has ONE home. Registries persist the
@@ -486,6 +523,14 @@ export function extractSigstoreLeafCertPem(signature) {
     if (verificationMaterial === null || typeof verificationMaterial !== "object") {
         return undefined;
     }
+    // Bundle v0.3 single-leaf shape first — what real signing emits.
+    const certificate = verificationMaterial.certificate;
+    if (certificate !== null && typeof certificate === "object") {
+        const rawBytes = certificate.rawBytes;
+        if (typeof rawBytes === "string" && rawBytes.length > 0)
+            return rawBytes;
+    }
+    // v0.1/v0.2 chain shape — leaf first.
     const chain = verificationMaterial
         .x509CertificateChain;
     if (chain === null || typeof chain !== "object")
@@ -507,9 +552,15 @@ export function extractSigstoreLeafCertPem(signature) {
  * by the RegExp-identity pre-check; production verification still goes
  * through the upstream verifier for the actual cryptographic check.
  *
+ * Parsing delegates to `@sigstore/core`'s `X509Certificate` — the
+ * SAME parser the upstream verifier uses — so the SAN this pre-check
+ * sees can never drift from the SAN verification enforces. (A prior
+ * hand-rolled DER scan over-captured on real certificates —
+ * discovered on the first genuinely Fulcio-issued cert it ever saw,
+ * 2026-08-10 — and was replaced wholesale rather than patched.)
+ *
  * Returns `undefined` if the bundle has no cert (e.g. publicKey-only
- * bundle) or no extractable SAN. Uses lightweight base64-DER scanning —
- * defers to the upstream verifier for the trust-chain semantics.
+ * bundle), the cert fails to parse, or it carries no URI/email SAN.
  */
 function extractSANFromBundle(bundle) {
     const material = bundle.verificationMaterial;
@@ -526,59 +577,14 @@ function extractSANFromBundle(bundle) {
     }
     if (!certB64)
         return undefined;
-    // Very lightweight SAN extraction: decode DER, locate the SAN
-    // extension OID (2.5.29.17), and pull the first URI/email-shaped
-    // ASCII run. This is intentionally tolerant — exact parsing happens
-    // in `@sigstore/verify` downstream.
-    let der;
     try {
-        der = base64ToBytes(certB64);
+        const cert = X509Certificate.parse(Buffer.from(certB64, "base64"));
+        // `subjectAltName` is the URI GeneralName when present, else the
+        // rfc822Name — the exact preference order the verifier's identity
+        // policy uses.
+        return cert.subjectAltName;
     }
     catch {
         return undefined;
     }
-    // OID 2.5.29.17 (subjectAltName) DER prefix: 06 03 55 1d 11.
-    const sanOid = [0x06, 0x03, 0x55, 0x1d, 0x11];
-    let idx = -1;
-    for (let i = 0; i < der.length - sanOid.length; i++) {
-        let match = true;
-        for (let j = 0; j < sanOid.length; j++) {
-            if (der[i + j] !== sanOid[j]) {
-                match = false;
-                break;
-            }
-        }
-        if (match) {
-            idx = i;
-            break;
-        }
-    }
-    if (idx === -1)
-        return undefined;
-    // After the OID DER there's a BOOLEAN (critical, optional) then an
-    // OCTET STRING wrapping a SEQUENCE of GeneralName. Scan forward for
-    // the first printable ASCII run containing a URI or email shape.
-    const tail = der.subarray(idx + sanOid.length);
-    let buf = "";
-    const uriPattern = /[a-zA-Z][a-zA-Z0-9+.-]*:[^\s]+|[\w.+-]+@[\w.-]+/;
-    for (let i = 0; i < tail.length; i++) {
-        const b = tail[i];
-        if (b >= 0x20 && b <= 0x7e) {
-            buf += String.fromCharCode(b);
-        }
-        else {
-            if (buf.length >= 3) {
-                const m = buf.match(uriPattern);
-                if (m)
-                    return m[0];
-            }
-            buf = "";
-        }
-    }
-    if (buf.length >= 3) {
-        const m = buf.match(uriPattern);
-        if (m)
-            return m[0];
-    }
-    return undefined;
 }

package/dist/testing/index.d.ts

@@ -0,0 +1,92 @@
+import { initializeCA, initializeCTLog, initializeTLog } from '@sigstore/mock';
+type CA = Awaited<ReturnType<typeof initializeCA>>;
+type CTLog = Awaited<ReturnType<typeof initializeCTLog>>;
+type TLog = Awaited<ReturnType<typeof initializeTLog>>;
+/** Options for {@link startSigstoreMockStack}. */
+export interface SigstoreMockStackOptions {
+    /**
+     * Mount the Fulcio signing-cert endpoint. Default `true`. Pass
+     * `false` to exercise CA-unreachable signing failure paths.
+     */
+    readonly fulcio?: boolean;
+    /**
+     * Mount the Rekor create-entry endpoint. Default `true`. Pass
+     * `false` to exercise transparency-log failure paths.
+     */
+    readonly rekor?: boolean;
+}
+/** Claims for {@link SigstoreMockStack.identityToken}. */
+export interface MockIdentityClaims {
+    /**
+     * OIDC subject — becomes the issued certificate's SAN (as a URI
+     * GeneralName; see the module docstring's mock-fidelity note).
+     */
+    readonly sub?: string;
+    /** OIDC issuer claim — lands in the cert's issuer extension. */
+    readonly iss?: string;
+    /** Additional claims (email, GitHub Actions workflow claims, …). */
+    readonly [claim: string]: unknown;
+}
+/** Handle returned by {@link startSigstoreMockStack}. */
+export interface SigstoreMockStack {
+    /** Base URL of the mock Fulcio instance. */
+    readonly fulcioURL: string;
+    /** Base URL of the mock Rekor instance. */
+    readonly rekorURL: string;
+    /**
+     * Endpoint overrides for `signBundleSigstore` — spread into its
+     * `endpoints` input.
+     */
+    readonly signEndpoints: {
+        readonly fulcioURL: string;
+        readonly rekorURL: string;
+    };
+    /**
+     * TUF trust-root overrides for `verifyBundleSigstore` — spread into
+     * its input (or a registry publish op's `sigstoreTuf` deps slot) so
+     * verification resolves the MOCK trust root instead of the
+     * public-good one.
+     *
+     * Includes `tufForceCache: true`, and load-bearingly so: the mock
+     * TUF mirror's nock interceptors are single-use, so exactly ONE
+     * remote metadata refresh succeeds per stack (discovered on this
+     * fixture's first multi-verify run — the second refresh died with
+     * `error refreshing TUF metadata`). The first verify populates the
+     * cache over the mock network; every later verify reuses it — which
+     * is also precisely the warm-start path serverless verifiers run in
+     * production, so the cache-reuse semantics get real coverage for
+     * free.
+     */
+    readonly tuf: {
+        readonly tufMirrorURL: string;
+        readonly tufRootPath: string;
+        readonly tufCachePath: string;
+        readonly tufForceCache: true;
+    };
+    /**
+     * Subject the zero-argument {@link identityToken} carries — handy
+     * for identity-policy assertions.
+     */
+    readonly defaultSubject: string;
+    /** Issuer the zero-argument {@link identityToken} carries. */
+    readonly defaultIssuer: string;
+    /**
+     * Mint an unsigned JWT-shaped OIDC token the mock Fulcio accepts.
+     * The mock decodes claims without verifying a signature.
+     */
+    identityToken(claims?: MockIdentityClaims): string;
+    /**
+     * Remove ALL nock interceptors registered in this process (including
+     * other live stacks — one stack per suite), restore real network
+     * access, and delete the TUF repo's cache directory.
+     */
+    teardown(): void;
+}
+/**
+ * Boot a full in-process sigstore mock stack: Fulcio + Rekor
+ * interceptors plus a TUF repository serving a trusted root built from
+ * the same keys. See the module docstring for the trust wiring.
+ */
+export declare function startSigstoreMockStack(options?: SigstoreMockStackOptions): Promise<SigstoreMockStack>;
+export type { CA as MockCA, CTLog as MockCTLog, TLog as MockTLog };
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AA2DA,OAAO,EAEL,YAAY,EACZ,eAAe,EACf,cAAc,EAEf,MAAM,gBAAgB,CAAC;AAkBxB,KAAK,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC;AACnD,KAAK,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC;AACzD,KAAK,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC;AAGvD,kDAAkD;AAClD,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE;QACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,GAAG,EAAE;QACZ,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAC;KAC9B,CAAC;IACF;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,aAAa,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC;IACnD;;;;OAIG;IACH,QAAQ,IAAI,IAAI,CAAC;CAClB;AAaD;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CA6H5B;AAgDD,YAAY,EAAE,EAAE,IAAI,MAAM,EAAE,KAAK,IAAI,SAAS,EAAE,IAAI,IAAI,QAAQ,EAAE,CAAC"}

package/dist/testing/index.js

@@ -0,0 +1,237 @@
+/**
+ * Hermetic sigstore test infrastructure for `@ggui-ai/gadget-signing`
+ * consumers.
+ *
+ * `startSigstoreMockStack()` boots in-process mock Fulcio + Rekor HTTP
+ * endpoints (nock interceptors over `@sigstore/mock`'s CA / CTLog /
+ * TLog primitives) **plus** a mock TUF repository (via
+ * `@tufjs/repo-mock`) that serves a `trusted_root.json` built from the
+ * SAME key material the mock services sign with. The result: the real
+ * `signBundleSigstore` and `verifyBundleSigstore` code paths execute
+ * end-to-end — real ephemeral key generation, real cert issuance, real
+ * transparency-log entries, real bundle serialization, real TUF
+ * trust-root resolution, real cryptographic verification — with only
+ * the network endpoints and the root of trust substituted, all through
+ * the upstream `sigstore` package's public option surface
+ * (`fulcioURL` / `rekorURL` on sign; `tufMirrorURL` / `tufRootPath` /
+ * `tufCachePath` on verify). Nothing in the sign/verify pipeline is
+ * stubbed.
+ *
+ * Subpath export — consumers
+ * `import { startSigstoreMockStack } from '@ggui-ai/gadget-signing/testing'`.
+ * Requires `@sigstore/mock`, `@tufjs/repo-mock`, `nock`, and
+ * `@sigstore/protobuf-specs` at test-runtime (declared as optional
+ * peerDeps; add them to devDependencies alongside this package).
+ * `@tufjs/repo-mock` is pinned to exactly 4.0.1 on purpose: 4.0.2
+ * moves its nock dependency to v14, which would load a second,
+ * differently-patched `http` interceptor next to `@sigstore/mock`'s
+ * nock v13 in the same process. At 4.0.1 both resolve one shared nock.
+ *
+ * Known mock-fidelity limits (upstream `@sigstore/mock` behavior —
+ * document divergence from the public-good instance, don't paper over
+ * it):
+ *
+ *   - The mock CA writes the certificate SAN as a **URI** GeneralName
+ *     regardless of the subject's shape, so email-based identity
+ *     policies (`certificateIdentityEmail`) can never match a
+ *     mock-issued cert. Use URI-shaped subjects in identity-policy
+ *     tests; the email routing itself is covered by the
+ *     option-threading seam tests.
+ *   - The mock Fulcio decodes (but does not cryptographically verify)
+ *     the OIDC token, so {@link SigstoreMockStack.identityToken}
+ *     mints unsigned JWT-shaped tokens.
+ *
+ * Interceptors are process-global (nock patches `http`), so run ONE
+ * stack per suite and call {@link SigstoreMockStack.teardown} in
+ * `afterAll`. While a stack is live the stack is HERMETIC: real
+ * network egress over `http.ClientRequest` is disabled (loopback
+ * excepted), so a request to any unmocked host fails fast and
+ * deterministically instead of silently escaping to live DNS — a
+ * `rekor: false` stack answers in milliseconds with nock's
+ * disallowed-net-connect error rather than waiting on a real
+ * NXDOMAIN. Undici-based `fetch` traffic is NOT intercepted (nor
+ * blocked) — only the `http.ClientRequest` path the sigstore/TUF
+ * clients use — so an in-process HTTP server under test keeps
+ * working alongside a live stack. `teardown()` restores real network
+ * access.
+ */
+import { createHash, generateKeyPairSync } from 'node:crypto';
+import { join } from 'node:path';
+import { fulcioHandler, initializeCA, initializeCTLog, initializeTLog, rekorHandler, } from '@sigstore/mock';
+import { TrustedRoot } from '@sigstore/protobuf-specs';
+import { createRequire } from 'node:module';
+import nock from 'nock';
+// `@tufjs/repo-mock` ships CJS with a transpiled `exports.default`.
+// Under native Node ESM a default-import binds the whole `exports`
+// object (Node does not unwrap transpiled `.default`), so
+// `mocktuf(...)` throws `TypeError: mocktuf is not a function` in the
+// shipped artifact even though vitest's interop keeps in-repo tests
+// green. `createRequire` reads the CJS shape identically in every
+// runtime — pinned by `dist-esm-interop.integration.test.ts`, which
+// imports the BUILT artifact under plain `node`.
+const cjsRequire = createRequire(import.meta.url);
+const repoMock = cjsRequire('@tufjs/repo-mock');
+const mocktuf = repoMock.default;
+/**
+ * Default SAN subject for minted identity tokens. URI-shaped on
+ * purpose — the mock CA writes URI SANs (module docstring).
+ */
+const DEFAULT_SUBJECT = 'https://gadgets.ggui.test/e2e-signer';
+/** Mirrors the mock Fulcio's default issuer claim. */
+const DEFAULT_ISSUER = 'https://fake.oidcissuer.com';
+/** Per-process counter so parallel suites get distinct mock hosts. */
+let stackCounter = 0;
+/**
+ * Boot a full in-process sigstore mock stack: Fulcio + Rekor
+ * interceptors plus a TUF repository serving a trusted root built from
+ * the same keys. See the module docstring for the trust wiring.
+ */
+export async function startSigstoreMockStack(options = {}) {
+    const id = (stackCounter += 1);
+    const fulcioURL = `https://fulcio.mock-${id}.ggui.test`;
+    const rekorURL = `https://rekor.mock-${id}.ggui.test`;
+    const tufMirrorURL = `https://tuf.mock-${id}.ggui.test`;
+    // One P-256 keypair roots the whole stack (CA + CTLog + TLog) —
+    // mirrors `@sigstore/mock`'s own top-level `mockFulcio` /
+    // `mockRekor` composition, which shares a keypair between the CA
+    // and its CTLog.
+    const keyPair = generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+    const ctlog = await initializeCTLog(keyPair);
+    const ca = await initializeCA(keyPair, ctlog);
+    const tlog = await initializeTLog(rekorURL, keyPair);
+    // Hermetic: while the stack is live, requests to any host without a
+    // registered interceptor fail fast with nock's NetConnectNotAllowed
+    // error instead of escaping to real DNS/network (empirically: an
+    // unmocked `.test` host cost ~3s of live NXDOMAIN lookups per
+    // attempt before this). Loopback stays open for in-process HTTP
+    // servers under test.
+    nock.disableNetConnect();
+    nock.enableNetConnect((host) => host.startsWith('127.0.0.1') || host.startsWith('localhost'));
+    if (options.fulcio !== false) {
+        mount(fulcioURL, fulcioHandler(ca, { strict: true }));
+    }
+    if (options.rekor !== false) {
+        mount(rekorURL, rekorHandler(tlog, { strict: true }));
+    }
+    // Trust material for verification — the SAME roots the mock services
+    // sign with, projected onto the `trusted_root.json` shape the TUF
+    // client resolves. Built in the protobuf-specs JSON encoding (base64
+    // bytes, enum names, ISO timestamps) and round-tripped through the
+    // `TrustedRoot` codec so a field drift fails loudly here rather than
+    // deep inside the verifier. (The installed protobuf-specs build
+    // exposes only `fromJSON`/`toJSON` — no `fromPartial` — discovered
+    // on this fixture's first run.)
+    //
+    // Validity windows are backdated one minute so cert-chain checks sit
+    // comfortably inside the window even under clock skew between this
+    // init and the moment a test signs.
+    const validityStart = new Date(Date.now() - 60_000).toISOString();
+    const trustedRootJSON = JSON.stringify(TrustedRoot.toJSON(TrustedRoot.fromJSON({
+        mediaType: 'application/vnd.dev.sigstore.trustedroot+json;version=0.1',
+        certificateAuthorities: [
+            {
+                subject: { commonName: 'sigstore', organization: 'sigstore.mock' },
+                uri: fulcioURL,
+                certChain: {
+                    certificates: [{ rawBytes: toBase64(ca.rootCertificate) }],
+                },
+                validFor: { start: validityStart },
+            },
+        ],
+        tlogs: [
+            {
+                baseUrl: rekorURL,
+                logId: {
+                    keyId: createHash('sha256').update(tlog.publicKey).digest('base64'),
+                },
+                hashAlgorithm: 'SHA2_256',
+                publicKey: {
+                    rawBytes: tlog.publicKey.toString('base64'),
+                    keyDetails: 'PKIX_ECDSA_P256_SHA_256',
+                    validFor: { start: validityStart },
+                },
+            },
+        ],
+        ctlogs: [
+            {
+                baseUrl: `${fulcioURL}/ctlog`,
+                logId: { keyId: toBase64(ctlog.logID) },
+                hashAlgorithm: 'SHA2_256',
+                publicKey: {
+                    rawBytes: ctlog.publicKey.toString('base64'),
+                    keyDetails: 'PKIX_ECDSA_P256_SHA_256',
+                    validFor: { start: validityStart },
+                },
+            },
+        ],
+        timestampAuthorities: [],
+    })));
+    const target = {
+        name: 'trusted_root.json',
+        content: Buffer.from(trustedRootJSON),
+    };
+    // `metadataPathPrefix: ''` matches `@sigstore/tuf`'s mirror layout
+    // (metadata at the mirror root, targets under /targets).
+    const tufRepo = mocktuf(target, { baseURL: tufMirrorURL, metadataPathPrefix: '' });
+    return {
+        fulcioURL,
+        rekorURL,
+        signEndpoints: { fulcioURL, rekorURL },
+        tuf: {
+            tufMirrorURL: tufRepo.baseURL,
+            tufCachePath: tufRepo.cachePath,
+            tufRootPath: join(tufRepo.cachePath, 'root.json'),
+            tufForceCache: true,
+        },
+        defaultSubject: DEFAULT_SUBJECT,
+        defaultIssuer: DEFAULT_ISSUER,
+        identityToken(claims = {}) {
+            return mintUnsignedJwt({
+                sub: DEFAULT_SUBJECT,
+                iss: DEFAULT_ISSUER,
+                ...claims,
+            });
+        },
+        teardown() {
+            nock.cleanAll();
+            nock.enableNetConnect();
+            tufRepo.teardown();
+        },
+    };
+}
+/**
+ * Register a persistent nock interceptor for a `@sigstore/mock`
+ * service handler. Persistence matters: a suite signs more than once
+ * per stack, and nock interceptors are single-use by default.
+ */
+function mount(baseURL, handler) {
+    nock(baseURL)
+        .persist()
+        .post(handler.path)
+        .reply(async (_uri, requestBody) => {
+        const raw = typeof requestBody === 'string' ? requestBody : JSON.stringify(requestBody);
+        const { statusCode, response, contentType } = await handler.fn(raw);
+        return [statusCode, response, { 'Content-Type': contentType ?? 'text/plain' }];
+    });
+}
+/**
+ * Mint an unsigned JWT-shaped token (`<b64url-header>.<b64url-payload>.`)
+ * that JWT decoders parse without signature verification — all the
+ * mock Fulcio does with it.
+ */
+function mintUnsignedJwt(payload) {
+    const header = base64Url(JSON.stringify({ alg: 'none', typ: 'JWT' }));
+    const body = base64Url(JSON.stringify(payload));
+    return `${header}.${body}.`;
+}
+function base64Url(value) {
+    return Buffer.from(value)
+        .toString('base64')
+        .replace(/=+$/u, '')
+        .replace(/\+/gu, '-')
+        .replace(/\//gu, '_');
+}
+/** Base64-encode an ArrayBufferView's exact byte range. */
+function toBase64(view) {
+    return Buffer.from(view.buffer, view.byteOffset, view.byteLength).toString('base64');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/gadget-signing",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Gadget bundle signing + verification for the ggui gadget marketplace. Ed25519 author-key path + sigstore/cosign keyless path. Pure-TS @noble crypto for Ed25519 — browser-safe.",
   "license": "Apache-2.0",
   "keywords": [
@@ -25,16 +25,47 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
     }
   },
   "dependencies": {
     "@noble/ed25519": "^2.2.0",
     "@noble/hashes": "^1.6.0",
     "@sigstore/bundle": "^4.0.0",
+    "@sigstore/core": "^3.2.1",
     "sigstore": "^4.0.0"
   },
+  "peerDependencies": {
+    "@sigstore/mock": "~0.12.1",
+    "@sigstore/protobuf-specs": "^0.5.1",
+    "@tufjs/repo-mock": "4.0.1",
+    "nock": "^13.5.6"
+  },
+  "peerDependenciesMeta": {
+    "@sigstore/mock": {
+      "optional": true
+    },
+    "@sigstore/protobuf-specs": {
+      "optional": true
+    },
+    "@tufjs/repo-mock": {
+      "optional": true
+    },
+    "nock": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@sigstore/mock": "~0.12.1",
+    "@sigstore/protobuf-specs": "^0.5.1",
+    "@sigstore/verify": "^3.1.1",
+    "@tufjs/repo-mock": "4.0.1",
     "@types/node": "^24.0.0",
+    "nock": "^13.5.6",
     "typescript": "^5.0.0",
     "vitest": "^3.2.6"
   },