zk-credits 0.2.7 → 0.2.8

package/README.md

@@ -9,7 +9,7 @@ receive $25 for a 30-minute session regardless of setup success. That payment
 is not product revenue or willingness-to-pay evidence.
 
 ```bash
-npm install --global zk-credits@0.2.7
+npm install --global zk-credits@0.2.8
 ```
 
 ## Pinned pilot versions
@@ -19,17 +19,18 @@ not mix versions between the sidecar, the adapter package, and the gateway:
 
 | Package | Version |
 | --- | --- |
-| `zk-credits` (this sidecar) | `0.2.7` |
+| `zk-credits` (this sidecar) | `0.2.8` |
 | `@zk-credits/x402-zk-prepaid` (adapter) | `0.1.0` |
 | `@zk-credits/shared` | `0.1.0` |
 
-The pinned Base Sepolia trial version is `0.2.7`. It uses the non-streaming
+The slot A Base Sepolia trial version is `0.2.8`. It uses the non-streaming
 `POST /v1/chat/completions` path below, includes the narrow loopback Responses
-bridge for supported Codex text and function-tool requests, and acquires the
-pinned private proving bundle through the local GitHub CLI session. It also
+bridge for supported Codex text and function-tool requests, and includes the
+pinned proving bundle in the package. It also
 synchronizes V2 Base events and checks the gateway known root before local
-setup completes. The proving artifacts are available only from the private
-immutable release pinned by `circuits/manifest.json`.
+setup completes. The packaged archive is checked against the immutable release
+digest pinned by `circuits/manifest.json`. Version 0.2.8 must be published by
+the owner before inviting a slot A participant.
 
 Verify the shipped artifacts before your first prove. The package's
 `circuits/manifest.json` fixes the SHA-256 of the frozen
@@ -60,16 +61,13 @@ still receives the class. A rejected request consumes no credit.
 ## First run
 
 1. Redeem the founder-prepared invite and download the encrypted V2 credential
-   export. The founder grants access to the private bundle repository
-   `mangekyou-labs/zk-credits-base-sepolia-v2-bundle` before the session.
+   export. Slot A needs no access to the proving-bundle repository.
 2. Give Codex the single setup instruction in the
    [first-use guide](../../docs/onboarding/base-zk-credits-codex-first-use.md).
-   Codex checks local GitHub CLI authentication and repository access, installs
-   this pinned release, downloads and verifies the bundle, and runs setup.
+   Codex installs this pinned release, verifies its packaged bundle, and runs setup.
    The human signs in if needed, enters the recovery password at the hidden
    prompt, gives consent, and chooses their own task. No product payment is
-   involved. The sidecar uses the local GitHub CLI session and never receives
-   or stores the GitHub token.
+   involved. The sidecar needs no GitHub token to install proving material.
 3. The setup command sets the credential, gateway, and Base Sepolia RPC
    endpoint:
 
@@ -80,10 +78,10 @@ still receives the class. A rejected request consumes no credit.
    ```
 
    `zk-credits setup codex` searches the standard local folders first. If it
-   finds no valid bundle, it downloads the pinned release, verifies the
-   release id, tag, immutability, archive digest, and all three file digests,
+   finds no valid bundle, it reads the packaged archive, verifies its pinned
+   archive digest and all three file digests,
    then atomically installs the bundle under `~/.zk-credits/artifacts` with
-   owner-only permissions. Missing GitHub access or any mismatch stops setup.
+   owner-only permissions. Any mismatch stops setup.
    It syncs public Base events from the pinned V2 bond and deployment block,
    validates that the resulting witness resolves the activated credential,
    and asks the gateway's public `POST /v1/root-known` endpoint whether the

package/dist/artifact-release.d.ts

@@ -5,6 +5,7 @@ export interface AcquirePinnedBundleOptions {
     manifest: CircuitManifest;
     targetDirectory: string;
     runGithubCommand?: GithubCommand;
+    bundledArchivePath?: string;
 }
-/** Fetches a pinned private GitHub release and atomically installs its safe USTAR bundle. */
+/** Installs the pinned package archive, or fetches the release for legacy/test callers. */
 export declare function acquirePinnedArtifactBundle(options: AcquirePinnedBundleOptions): Promise<string>;

package/dist/artifact-release.js

@@ -5,7 +5,8 @@ import { gunzipSync } from 'node:zlib';
 import { promisify } from 'node:util';
 import { chmod, lstat, mkdir, open, readFile, rename, rm, } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { resolvePinnedArtifactBundle } from './artifact-bundle.js';
+import { fileURLToPath } from 'node:url';
+import { ArtifactBundleError, resolvePinnedArtifactBundle } from './artifact-bundle.js';
 const execFile = promisify(nodeExecFile);
 const MAX_COMPRESSED_BYTES = 20 * 1024 * 1024;
 const MAX_EXPANDED_BYTES = 32 * 1024 * 1024;
@@ -126,14 +127,15 @@ function pinnedAsset(release, raw) {
     }
     const record = value;
     const assets = Array.isArray(record.assets) ? record.assets : [];
-    const asset = assets.find((entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+    const matchingAssets = assets.filter((entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
         && entry.name === release.assetName);
+    const asset = matchingAssets[0];
     if (record.id !== release.releaseId
         || record.tag_name !== release.tag
         || record.draft !== false
         || record.immutable !== true
-        || !asset
-        || (typeof asset.digest === 'string' && asset.digest !== 'sha256:' + release.sha256)) {
+        || matchingAssets.length !== 1
+        || asset.digest !== 'sha256:' + release.sha256) {
         throw new Error('Pinned proving release identity or immutability check failed');
     }
 }
@@ -185,13 +187,15 @@ async function replaceDirectoryAtomically(stage, target) {
         await rm(stage, { recursive: true, force: true });
     }
 }
-/** Fetches a pinned private GitHub release and atomically installs its safe USTAR bundle. */
+/** Installs the pinned package archive, or fetches the release for legacy/test callers. */
 export async function acquirePinnedArtifactBundle(options) {
     const release = options.manifest.release;
     if (!release)
         throw new Error('This sidecar manifest has no pinned artifact release');
     const names = new Set(options.manifest.artifacts.map((artifact) => artifact.file));
     const command = options.runGithubCommand ?? defaultGithubCommand;
+    const bundledArchivePath = options.bundledArchivePath
+        ?? (!options.runGithubCommand ? fileURLToPath(new URL('../circuits/base-sepolia-v2.tar.gz', import.meta.url)) : undefined);
     const parent = dirname(resolve(options.targetDirectory));
     const tempDirectory = join(parent, '.base-sepolia-download-' + randomUUID());
     const stage = join(parent, '.base-sepolia-stage-' + randomUUID());
@@ -199,16 +203,49 @@ export async function acquirePinnedArtifactBundle(options) {
         await mkdir(parent, { recursive: true, mode: 0o700 });
         await mkdir(tempDirectory, { recursive: false, mode: 0o700 });
         await mkdir(stage, { recursive: false, mode: 0o700 });
-        const releaseJson = await command(['api', `repos/${release.repository}/releases/${release.releaseId}`]);
-        pinnedAsset(release, releaseJson);
-        await command([
-            'release', 'download', release.tag,
-            '--repo', release.repository,
-            '--dir', tempDirectory,
-            '--pattern', release.assetName,
-        ]);
-        const archivePath = join(tempDirectory, release.assetName);
-        const archiveInfo = await lstat(archivePath);
+        if (!bundledArchivePath) {
+            try {
+                await command(['auth', 'status']);
+            }
+            catch {
+                throw new Error('GitHub CLI authentication is required; run gh auth login locally before downloading the pinned proving bundle.');
+            }
+            try {
+                const repositoryJson = await command(['api', `repos/${release.repository}`]);
+                const repository = JSON.parse(repositoryJson);
+                if (repository.full_name !== release.repository)
+                    throw new Error('Repository identity mismatch');
+            }
+            catch {
+                throw new Error(`Pinned proving bundle requires read access to ${release.repository}; ask the founder to grant access to your signed-in GitHub account.`);
+            }
+            let releaseJson;
+            try {
+                releaseJson = await command(['api', `repos/${release.repository}/releases/${release.releaseId}`]);
+            }
+            catch {
+                throw new Error('Pinned proving release metadata could not be read; ask the founder to verify the published release with an authorized account. A 404 does not distinguish a missing release from insufficient access.');
+            }
+            pinnedAsset(release, releaseJson);
+            try {
+                await command([
+                    'release', 'download', release.tag,
+                    '--repo', release.repository,
+                    '--dir', tempDirectory,
+                    '--pattern', release.assetName,
+                ]);
+            }
+            catch {
+                throw new Error('Pinned proving bundle download failed; verify gh access and the published release asset.');
+            }
+        }
+        const archivePath = bundledArchivePath ?? join(tempDirectory, release.assetName);
+        const archiveInfo = await lstat(archivePath).catch((error) => {
+            if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+                throw new Error('Pinned proving bundle archive is missing or too large');
+            }
+            throw error;
+        });
         if (archiveInfo.isSymbolicLink() || !archiveInfo.isFile() || archiveInfo.size > MAX_COMPRESSED_BYTES) {
             throw new Error('Pinned proving bundle archive is missing or too large');
         }
@@ -226,15 +263,23 @@ export async function acquirePinnedArtifactBundle(options) {
         for (const [name, bytes] of files)
             await writeBundleFile(stage, name, bytes);
         await chmod(stage, 0o700);
-        await resolvePinnedArtifactBundle({ artifactDirectory: stage, manifest: options.manifest });
+        try {
+            await resolvePinnedArtifactBundle({ artifactDirectory: stage, manifest: options.manifest });
+        }
+        catch (error) {
+            if (error instanceof ArtifactBundleError && error.category === 'artifact_hash_mismatch') {
+                throw new Error(`Pinned proving bundle file SHA-256 check failed: ${error.message}`, { cause: error });
+            }
+            throw error;
+        }
         await replaceDirectoryAtomically(stage, resolve(options.targetDirectory));
         await resolvePinnedArtifactBundle({ artifactDirectory: resolve(options.targetDirectory), manifest: options.manifest });
         return resolve(options.targetDirectory);
     }
     catch (error) {
-        if (error instanceof Error && /^(Pinned proving|This sidecar manifest|Local proving bundle)/u.test(error.message))
+        if (error instanceof Error && /^(Pinned proving|This sidecar manifest|Local proving bundle|GitHub CLI authentication)/u.test(error.message))
             throw error;
-        throw new Error('Pinned proving bundle acquisition failed; verify gh access and the published release pin.');
+        throw new Error('Pinned proving bundle acquisition failed; verify the packaged archive and manifest pins.');
     }
     finally {
         await rm(tempDirectory, { recursive: true, force: true });

package/dist/setup-config.d.ts

@@ -24,7 +24,7 @@ export interface ResolveSetupInputsOptions {
     validateWitness(source: SetupWitnessSource): Promise<void>;
     /** Called only when more than one valid local candidate exists. */
     chooseCandidate?(kind: 'proving bundle' | 'witness file', candidates: readonly string[]): Promise<string>;
-    /** Test seam for clean-install acquisition; production uses gh-authenticated release download. */
+    /** Test seam for clean-install acquisition; production reads the packaged pinned archive. */
     acquireArtifactBundle?(targetDirectory: string, manifest: CircuitManifest): Promise<void>;
     workingDirectory?: string;
 }

package/dist/zk-credits.js

@@ -82027,6 +82027,7 @@ import { gunzipSync } from "node:zlib";
 import { promisify as promisify2 } from "node:util";
 import { chmod as chmod3, lstat, mkdir as mkdir5, open, readFile as readFile4, rename as rename3, rm } from "node:fs/promises";
 import { dirname as dirname4, join as join4, resolve as resolve2 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 var execFile = promisify2(nodeExecFile);
 var MAX_COMPRESSED_BYTES = 20 * 1024 * 1024;
 var MAX_EXPANDED_BYTES = 32 * 1024 * 1024;
@@ -82145,8 +82146,9 @@ function pinnedAsset(release, raw) {
   }
   const record = value;
   const assets = Array.isArray(record.assets) ? record.assets : [];
-  const asset = assets.find((entry) => entry && typeof entry === "object" && !Array.isArray(entry) && entry.name === release.assetName);
-  if (record.id !== release.releaseId || record.tag_name !== release.tag || record.draft !== false || record.immutable !== true || !asset || typeof asset.digest === "string" && asset.digest !== "sha256:" + release.sha256) {
+  const matchingAssets = assets.filter((entry) => entry && typeof entry === "object" && !Array.isArray(entry) && entry.name === release.assetName);
+  const asset = matchingAssets[0];
+  if (record.id !== release.releaseId || record.tag_name !== release.tag || record.draft !== false || record.immutable !== true || matchingAssets.length !== 1 || asset.digest !== "sha256:" + release.sha256) {
     throw new Error("Pinned proving release identity or immutability check failed");
   }
 }
@@ -82198,6 +82200,7 @@ async function acquirePinnedArtifactBundle(options) {
     throw new Error("This sidecar manifest has no pinned artifact release");
   const names = new Set(options.manifest.artifacts.map((artifact) => artifact.file));
   const command = options.runGithubCommand ?? defaultGithubCommand;
+  const bundledArchivePath = options.bundledArchivePath ?? (!options.runGithubCommand ? fileURLToPath2(new URL("../circuits/base-sepolia-v2.tar.gz", import.meta.url)) : void 0);
   const parent = dirname4(resolve2(options.targetDirectory));
   const tempDirectory = join4(parent, ".base-sepolia-download-" + randomUUID());
   const stage = join4(parent, ".base-sepolia-stage-" + randomUUID());
@@ -82205,21 +82208,50 @@ async function acquirePinnedArtifactBundle(options) {
     await mkdir5(parent, { recursive: true, mode: 448 });
     await mkdir5(tempDirectory, { recursive: false, mode: 448 });
     await mkdir5(stage, { recursive: false, mode: 448 });
-    const releaseJson = await command(["api", `repos/${release.repository}/releases/${release.releaseId}`]);
-    pinnedAsset(release, releaseJson);
-    await command([
-      "release",
-      "download",
-      release.tag,
-      "--repo",
-      release.repository,
-      "--dir",
-      tempDirectory,
-      "--pattern",
-      release.assetName
-    ]);
-    const archivePath = join4(tempDirectory, release.assetName);
-    const archiveInfo = await lstat(archivePath);
+    if (!bundledArchivePath) {
+      try {
+        await command(["auth", "status"]);
+      } catch {
+        throw new Error("GitHub CLI authentication is required; run gh auth login locally before downloading the pinned proving bundle.");
+      }
+      try {
+        const repositoryJson = await command(["api", `repos/${release.repository}`]);
+        const repository = JSON.parse(repositoryJson);
+        if (repository.full_name !== release.repository)
+          throw new Error("Repository identity mismatch");
+      } catch {
+        throw new Error(`Pinned proving bundle requires read access to ${release.repository}; ask the founder to grant access to your signed-in GitHub account.`);
+      }
+      let releaseJson;
+      try {
+        releaseJson = await command(["api", `repos/${release.repository}/releases/${release.releaseId}`]);
+      } catch {
+        throw new Error("Pinned proving release metadata could not be read; ask the founder to verify the published release with an authorized account. A 404 does not distinguish a missing release from insufficient access.");
+      }
+      pinnedAsset(release, releaseJson);
+      try {
+        await command([
+          "release",
+          "download",
+          release.tag,
+          "--repo",
+          release.repository,
+          "--dir",
+          tempDirectory,
+          "--pattern",
+          release.assetName
+        ]);
+      } catch {
+        throw new Error("Pinned proving bundle download failed; verify gh access and the published release asset.");
+      }
+    }
+    const archivePath = bundledArchivePath ?? join4(tempDirectory, release.assetName);
+    const archiveInfo = await lstat(archivePath).catch((error) => {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        throw new Error("Pinned proving bundle archive is missing or too large");
+      }
+      throw error;
+    });
     if (archiveInfo.isSymbolicLink() || !archiveInfo.isFile() || archiveInfo.size > MAX_COMPRESSED_BYTES) {
       throw new Error("Pinned proving bundle archive is missing or too large");
     }
@@ -82236,14 +82268,21 @@ async function acquirePinnedArtifactBundle(options) {
     for (const [name, bytes] of files)
       await writeBundleFile(stage, name, bytes);
     await chmod3(stage, 448);
-    await resolvePinnedArtifactBundle({ artifactDirectory: stage, manifest: options.manifest });
+    try {
+      await resolvePinnedArtifactBundle({ artifactDirectory: stage, manifest: options.manifest });
+    } catch (error) {
+      if (error instanceof ArtifactBundleError && error.category === "artifact_hash_mismatch") {
+        throw new Error(`Pinned proving bundle file SHA-256 check failed: ${error.message}`, { cause: error });
+      }
+      throw error;
+    }
     await replaceDirectoryAtomically(stage, resolve2(options.targetDirectory));
     await resolvePinnedArtifactBundle({ artifactDirectory: resolve2(options.targetDirectory), manifest: options.manifest });
     return resolve2(options.targetDirectory);
   } catch (error) {
-    if (error instanceof Error && /^(Pinned proving|This sidecar manifest|Local proving bundle)/u.test(error.message))
+    if (error instanceof Error && /^(Pinned proving|This sidecar manifest|Local proving bundle|GitHub CLI authentication)/u.test(error.message))
       throw error;
-    throw new Error("Pinned proving bundle acquisition failed; verify gh access and the published release pin.");
+    throw new Error("Pinned proving bundle acquisition failed; verify the packaged archive and manifest pins.");
   } finally {
     await rm(tempDirectory, { recursive: true, force: true });
     await rm(stage, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zk-credits",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Loopback x402 zk-prepaid transport for private Base API credits.",
   "homepage": "https://feature-zk-api-credits-gadillacers-projects.vercel.app",
   "repository": {