@zbase-protocol/core 0.1.1 → 0.1.2

package/dist/experimental.d.ts

@@ -1,15 +1,23 @@
 /**
  * @zbase-protocol/core/experimental — UNFINISHED UTXO surface. NOT PRODUCTION.
  *
- * ⚠️ These variable-amount UTXO primitives are a PRE-DEPLOYMENT scaffold. The UTXO
- * pool is not deployed (routes return 501) and the trusted-setup ceremony has not
- * run. The 2026-07-09 SDK audit found integrator fund-lock footguns here:
- *   - the note wire format is inconsistent (packCiphertext is length-prefixed but
- *     the scanner decodes a fixed bytes32[4]) → a recipient may be unable to
- *     decrypt their own note;
+ * ⚠️⚠️ DO NOT USE WITH REAL FUNDS. These variable-amount UTXO primitives are a
+ * PRE-DEPLOYMENT scaffold. The UTXO pool is not deployed (routes return 501) and
+ * the trusted-setup ceremony has not run. The 2026-07-09 SDK + black-hat audits
+ * confirmed integrator FUND-LOSS footguns here, still present by design until the
+ * post-ceremony rewrite:
+ *   - WIRE-FORMAT BREAK (HIGH): encryptNoteForTransfer produces a ~330-byte
+ *     length-prefixed envelope (packCiphertext), but the scanner's
+ *     decodeTransferredLog reassembles a FIXED 128-byte bytes32[4] blob →
+ *     decryption returns null → a recipient CANNOT see or spend their own inbound
+ *     note. Building a wallet on createScanner today will LOSE received funds.
  *   - createNote defaults NPK material to 0 → a note addressable to nobody;
- *   - deriveViewingKeyFromSeed diverges from the mnemonic path for non-64-byte
- *     seeds → recovery can silently fail.
+ *   - deserializeNote now range-validates (fixed), but malformed notes throw;
+ *   - deriveViewingKeyFromSeed now requires the exact 64-byte BIP39 seed (fixed).
+ *
+ * The wire-format break is NOT fixed here (it needs the frozen post-ceremony
+ * schema); it is quarantined behind this subpath so no main-entry integrator hits
+ * it. If you import this, you accept these are unfinished and fund-unsafe.
  *
  * This surface lives on a SEPARATE subpath (not the main entry) so no integrator
  * reaches it by accident: you must explicitly `import ... from

package/dist/experimental.js

@@ -1,15 +1,23 @@
 /**
  * @zbase-protocol/core/experimental — UNFINISHED UTXO surface. NOT PRODUCTION.
  *
- * ⚠️ These variable-amount UTXO primitives are a PRE-DEPLOYMENT scaffold. The UTXO
- * pool is not deployed (routes return 501) and the trusted-setup ceremony has not
- * run. The 2026-07-09 SDK audit found integrator fund-lock footguns here:
- *   - the note wire format is inconsistent (packCiphertext is length-prefixed but
- *     the scanner decodes a fixed bytes32[4]) → a recipient may be unable to
- *     decrypt their own note;
+ * ⚠️⚠️ DO NOT USE WITH REAL FUNDS. These variable-amount UTXO primitives are a
+ * PRE-DEPLOYMENT scaffold. The UTXO pool is not deployed (routes return 501) and
+ * the trusted-setup ceremony has not run. The 2026-07-09 SDK + black-hat audits
+ * confirmed integrator FUND-LOSS footguns here, still present by design until the
+ * post-ceremony rewrite:
+ *   - WIRE-FORMAT BREAK (HIGH): encryptNoteForTransfer produces a ~330-byte
+ *     length-prefixed envelope (packCiphertext), but the scanner's
+ *     decodeTransferredLog reassembles a FIXED 128-byte bytes32[4] blob →
+ *     decryption returns null → a recipient CANNOT see or spend their own inbound
+ *     note. Building a wallet on createScanner today will LOSE received funds.
  *   - createNote defaults NPK material to 0 → a note addressable to nobody;
- *   - deriveViewingKeyFromSeed diverges from the mnemonic path for non-64-byte
- *     seeds → recovery can silently fail.
+ *   - deserializeNote now range-validates (fixed), but malformed notes throw;
+ *   - deriveViewingKeyFromSeed now requires the exact 64-byte BIP39 seed (fixed).
+ *
+ * The wire-format break is NOT fixed here (it needs the frozen post-ceremony
+ * schema); it is quarantined behind this subpath so no main-entry integrator hits
+ * it. If you import this, you accept these are unfinished and fund-unsafe.
  *
  * This surface lives on a SEPARATE subpath (not the main entry) so no integrator
  * reaches it by accident: you must explicitly `import ... from

package/dist/facilitatorClient.d.ts

@@ -19,13 +19,38 @@
  */
 export type FacilitatorNetwork = "eip155:84532" | "eip155:8453";
 export interface FacilitatorClientConfig {
-    /** Base URL of the zBase deployment, e.g. "https://zbase.app" or "http://localhost:3009". */
+    /**
+     * Base URL of the zBase deployment, e.g. "https://zbase.app".
+     *
+     * ⚠️ SECURITY (CRITICAL, 2026-07-09): `baseUrl` is FULLY TRUSTED WITH YOUR SPEND
+     * SECRETS. In the current server-side-proving model, `settlePrivately` sends the
+     * deposit's `{nullifier, secret}` — the COMPLETE spend authority for the pool
+     * note — to this URL. A malicious or man-in-the-middle'd `baseUrl` can withdraw
+     * your funds. Therefore:
+     *   - `https:` is REQUIRED (an on-path attacker cannot read an HTTPS body).
+     *   - `http://localhost` / `http://127.0.0.1` is allowed for local dev only.
+     *   - any other `http:` URL is REJECTED unless you explicitly set
+     *     `allowInsecureHttp: true` (do this ONLY on a trusted private network).
+     *   - Always PIN this URL to a deployment you control/trust; never take it from
+     *     an untrusted discovery response or user input.
+     */
     baseUrl: string;
     /** CAIP-2 network. Defaults to Base Sepolia. */
     network?: FacilitatorNetwork;
     /** Optional fetch override (for tests / non-browser runtimes). */
     fetchImpl?: typeof fetch;
+    /**
+     * Explicitly allow a non-localhost `http://` baseUrl. Only for trusted private
+     * networks — this transmits spend secrets in cleartext. Default false.
+     */
+    allowInsecureHttp?: boolean;
 }
+/**
+ * Validate the facilitator baseUrl before we ever send spend secrets to it.
+ * Throws on a URL that would leak secrets to an on-path attacker. Exported for
+ * testing the guard.
+ */
+export declare function assertSafeFacilitatorBaseUrl(baseUrl: string, allowInsecureHttp?: boolean): URL;
 /** Deposit secrets the payer keeps locally; the input to every later settle. */
 export interface DepositSecrets {
     nullifier: string;

package/dist/facilitatorClient.js

@@ -18,11 +18,39 @@
  * mainnet). Zero new dependencies — fetch only.
  */
 import { generateDepositSecrets, computePrecommitment } from "./account.js";
+/**
+ * Validate the facilitator baseUrl before we ever send spend secrets to it.
+ * Throws on a URL that would leak secrets to an on-path attacker. Exported for
+ * testing the guard.
+ */
+export function assertSafeFacilitatorBaseUrl(baseUrl, allowInsecureHttp = false) {
+    let u;
+    try {
+        u = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`FacilitatorClient: baseUrl is not a valid URL: ${baseUrl}`);
+    }
+    if (u.protocol === "https:")
+        return u;
+    if (u.protocol === "http:") {
+        const host = u.hostname.toLowerCase();
+        const isLocal = host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+        if (isLocal || allowInsecureHttp)
+            return u;
+        throw new Error(`FacilitatorClient: refusing an insecure http:// baseUrl (${baseUrl}). settlePrivately sends your spend secrets to this host — use https, or set allowInsecureHttp:true only on a trusted private network.`);
+    }
+    throw new Error(`FacilitatorClient: unsupported baseUrl protocol '${u.protocol}' — use https.`);
+}
 export class FacilitatorClient {
     base;
     network;
     doFetch;
     constructor(cfg) {
+        // CRITICAL C3 fix (2026-07-09): validate baseUrl BEFORE any secret is sent to
+        // it. settlePrivately transmits the deposit spend secrets; an http:// or
+        // malformed baseUrl would leak them to an on-path attacker → fund theft.
+        assertSafeFacilitatorBaseUrl(cfg.baseUrl, cfg.allowInsecureHttp ?? false);
         this.base = cfg.baseUrl.replace(/\/$/, "");
         this.network = cfg.network ?? "eip155:84532";
         const f = cfg.fetchImpl ?? globalThis.fetch;

package/dist/index.d.ts

@@ -18,7 +18,7 @@ export type { ProofInput, Groth16Proof, ProofResult } from "./proofs.js";
 export { generateWithdrawalProof, verifyProofLocally } from "./proofs.js";
 export { buildMerkleTree, generateMerkleProof, getTreeDepth } from "./merkle.js";
 export type { FacilitatorClientConfig, FacilitatorNetwork, DepositSecrets, PreparedDeposit, VerifyResult, SettleResult, } from "./facilitatorClient.js";
-export { FacilitatorClient, createFacilitatorClient } from "./facilitatorClient.js";
+export { FacilitatorClient, createFacilitatorClient, assertSafeFacilitatorBaseUrl } from "./facilitatorClient.js";
 export type { BuildSwapCallPlanOpts } from "./swapPlan.js";
 export { buildSwapCallPlan, EXACT_INPUT_SINGLE_SELECTOR, } from "./swapPlan.js";
 export type { ForwardingNoteSecrets } from "./forwardingNotes.js";

package/dist/index.js

@@ -17,7 +17,7 @@ export { generateDepositSecrets, computeCommitment, computePrecommitment, comput
 export { generateWithdrawalProof, verifyProofLocally } from "./proofs.js";
 // Merkle tree
 export { buildMerkleTree, generateMerkleProof, getTreeDepth } from "./merkle.js";
-export { FacilitatorClient, createFacilitatorClient } from "./facilitatorClient.js";
+export { FacilitatorClient, createFacilitatorClient, assertSafeFacilitatorBaseUrl } from "./facilitatorClient.js";
 export { buildSwapCallPlan, EXACT_INPUT_SINGLE_SELECTOR, } from "./swapPlan.js";
 export { deriveForwardingNote, precommitmentForRelayer, recoverForwardingNotes, ZBASE_FORWARDING_PATH_PREFIX, } from "./forwardingNotes.js";
 export { STEALTH_SCHEME_ID, DEFAULT_CHAIN_TAG, generateMetaAddress, parseMetaAddress, isStealthMetaAddress, deriveStealthAddress, scanForPayments, computeStealthPrivateKey, } from "./stealth.js";

package/dist/notes.js

@@ -29,7 +29,7 @@ import { xchacha20poly1305 } from "@noble/ciphers/chacha";
 import { keccak_256 } from "@noble/hashes/sha3";
 import { randomBytes } from "@noble/hashes/utils";
 // Shared, unbiased (rejection-sampling) field sampler — see account.ts (audit F7).
-import { randomFieldElement } from "./account.js";
+import { randomFieldElement, SNARK_SCALAR_FIELD } from "./account.js";
 // -----------------------------------------------------------------------------
 // Note creation
 // -----------------------------------------------------------------------------
@@ -290,7 +290,7 @@ export function serializeNote(n) {
 }
 export function deserializeNote(s) {
     const o = JSON.parse(s);
-    return {
+    const note = {
         amount: BigInt(o.amount),
         label: BigInt(o.label),
         // Tolerate pre-v1 serialized notes (no NPK fields) by defaulting to 0 —
@@ -300,6 +300,26 @@ export function deserializeNote(s) {
         nullifier: BigInt(o.nullifier),
         secret: BigInt(o.secret),
     };
+    // HIGH fix (SDK audit 2026-07-09): RANGE-VALIDATE on deserialize. A corrupted /
+    // malicious serialized note with an out-of-range amount (>= 2^64) or an
+    // out-of-field element silently produces a commitment the circuit can never
+    // accept → funds locked (or, unchecked, value-confusion). Reject early with a
+    // clear error instead of failing opaquely at proof time.
+    if (note.amount < 0n || note.amount >= MAX_NOTE_AMOUNT) {
+        throw new NoteValueError(`deserializeNote: amount out of range [0, 2^64): ${note.amount}`);
+    }
+    for (const [name, v] of [
+        ["label", note.label],
+        ["nullifier", note.nullifier],
+        ["secret", note.secret],
+        ["spendingPK", note.spendingPK],
+        ["viewingPKBlind", note.viewingPKBlind],
+    ]) {
+        if (v < 0n || v >= SNARK_SCALAR_FIELD) {
+            throw new NoteValueError(`deserializeNote: ${name} is not a valid field element (>= SNARK field): ${v}`);
+        }
+    }
+    return note;
 }
 // -----------------------------------------------------------------------------
 // Viewing-key cryptography

package/dist/viewingKeyHD.js

@@ -135,8 +135,17 @@ export function deriveViewingKeyFromMnemonic(mnemonic, index = 0) {
  * The mnemonic field on the returned ViewingKey will be `undefined`.
  */
 export function deriveViewingKeyFromSeed(seed, index = 0) {
-    if (seed.length < 32) {
-        throw new Error(`deriveViewingKeyFromSeed: seed must be ≥ 32 bytes, got ${seed.length}`);
+    // HIGH fix (SDK audit 2026-07-09): require EXACTLY the 64-byte BIP39 seed
+    // (`mnemonicToSeedSync(mnemonic)`). The prior `>= 32` check let a caller pass
+    // 32-byte entropy (or any 32+ bytes) that derives a DIFFERENT viewing key than
+    // the mnemonic path — so a wallet "recovering" from the wrong-length seed scans
+    // the chain, finds none of its own notes, and concludes funds are lost. Only
+    // the 64-byte BIP39 seed matches deriveViewingKeyFromMnemonic. Enforce it.
+    if (seed.length !== 64) {
+        throw new Error(`deriveViewingKeyFromSeed: seed must be the 64-byte BIP39 seed (output of ` +
+            `mnemonicToSeedSync), got ${seed.length} bytes. Passing raw entropy or a ` +
+            `different length derives a DIFFERENT key than the mnemonic path and ` +
+            `breaks note recovery. Use deriveViewingKeyFromMnemonic if you have the phrase.`);
     }
     const derivationPath = pathFor(index);
     const node = HDKey.fromMasterSeed(seed).derive(derivationPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zbase-protocol/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Chain-agnostic ZK privacy core for x402 AI agent payments. Poseidon hashing, Merkle trees, Groth16 proof generation, account/secrets management. Used by @zbase-protocol/svm and @zbase-protocol/mcp.",
   "type": "module",
   "main": "./dist/index.js",