@orbinum/sdk 1.3.1 → 1.4.0

package/dist/index.d.mts

@@ -240,8 +240,27 @@ declare function reserveSelfEphIndex(storage: NoteStorage): Promise<number>;
  * viewing public key. Registering the counterparty is a side effect worth
  * having: it makes the REVERSE direction cheap too, since their future payments
  * to this wallet become hash lookups instead of one trial ECDH per note.
+ *
+ * Returns `null` when this vault holds no history for that counterparty, and
+ * the caller must then use a random ephemeral. The reason is that "no history"
+ * has two causes this function cannot tell apart:
+ *
+ *   - a genuine first payment, where index 0 is correct;
+ *   - a counter that was LOST — a restored seed, a cleared IndexedDB, a wipe
+ *     and rescan — where index 0 was already published and re-deriving it
+ *     republishes that ephPk, linking the two notes in public.
+ *
+ * Unlike `selfEphCounter`, this one cannot be recovered: the index was
+ * published on a note encrypted toward someone else, so it never appears in
+ * this wallet's own scan, and asking a server whether a given ephPk exists
+ * would reveal which notes are ours. So the ambiguity is resolved the safe way
+ * — the caller degrades to random, costing the recipient one trial scan, and
+ * every later payment to the same counterparty takes the fast path again.
+ *
+ * The entry is still created: the NEXT payment has a counter, and registering
+ * the counterparty is what makes the reverse direction cheap.
  */
-declare function reservePairwiseIndex(storage: NoteStorage, ivkHex: string): Promise<number>;
+declare function reservePairwiseIndex(storage: NoteStorage, ivkHex: string): Promise<number | null>;
 
 /**
  * Turning a note into a stored record and back.
@@ -4495,7 +4514,13 @@ declare function resolveSelfEphCeiling(params: {
 /**
  * Discovery window size for the next scan, given the persisted counter: at least
  * the default, rounded up so every index the wallet may already have used (plus
- * the gap margin) falls inside the fast path.
+ * the gap margin) falls inside the fast path, and never past `MAX_EPH_WINDOW`.
+ *
+ * The counter is read from a config that survives restores and hand-editing, so
+ * a non-finite value is treated as "no history" rather than propagated: `NaN`
+ * would make the builder's `i < from + count` false immediately and return an
+ * EMPTY window, silently disabling the fast path, while `Infinity` would make
+ * that same loop never terminate.
  */
 declare function windowSizeForCounter(counter: number): number;
 

package/dist/index.d.ts

@@ -240,8 +240,27 @@ declare function reserveSelfEphIndex(storage: NoteStorage): Promise<number>;
  * viewing public key. Registering the counterparty is a side effect worth
  * having: it makes the REVERSE direction cheap too, since their future payments
  * to this wallet become hash lookups instead of one trial ECDH per note.
+ *
+ * Returns `null` when this vault holds no history for that counterparty, and
+ * the caller must then use a random ephemeral. The reason is that "no history"
+ * has two causes this function cannot tell apart:
+ *
+ *   - a genuine first payment, where index 0 is correct;
+ *   - a counter that was LOST — a restored seed, a cleared IndexedDB, a wipe
+ *     and rescan — where index 0 was already published and re-deriving it
+ *     republishes that ephPk, linking the two notes in public.
+ *
+ * Unlike `selfEphCounter`, this one cannot be recovered: the index was
+ * published on a note encrypted toward someone else, so it never appears in
+ * this wallet's own scan, and asking a server whether a given ephPk exists
+ * would reveal which notes are ours. So the ambiguity is resolved the safe way
+ * — the caller degrades to random, costing the recipient one trial scan, and
+ * every later payment to the same counterparty takes the fast path again.
+ *
+ * The entry is still created: the NEXT payment has a counter, and registering
+ * the counterparty is what makes the reverse direction cheap.
  */
-declare function reservePairwiseIndex(storage: NoteStorage, ivkHex: string): Promise<number>;
+declare function reservePairwiseIndex(storage: NoteStorage, ivkHex: string): Promise<number | null>;
 
 /**
  * Turning a note into a stored record and back.
@@ -4495,7 +4514,13 @@ declare function resolveSelfEphCeiling(params: {
 /**
  * Discovery window size for the next scan, given the persisted counter: at least
  * the default, rounded up so every index the wallet may already have used (plus
- * the gap margin) falls inside the fast path.
+ * the gap margin) falls inside the fast path, and never past `MAX_EPH_WINDOW`.
+ *
+ * The counter is read from a config that survives restores and hand-editing, so
+ * a non-finite value is treated as "no history" rather than propagated: `NaN`
+ * would make the builder's `i < from + count` false immediately and return an
+ * EMPTY window, silently disabling the fast path, while `Infinity` would make
+ * that same loop never terminate.
  */
 declare function windowSizeForCounter(counter: number): number;
 

package/dist/index.js

@@ -5414,13 +5414,29 @@ function mergeCounters(current, fallback) {
     ...parties !== void 0 ? { pairwiseCounterparties: parties } : {}
   };
 }
-var higher = (a, b) => a === void 0 ? b : b === void 0 ? a : Math.max(a, b);
+var counterOrNone = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+var higher = (a, b) => {
+  const x = counterOrNone(a);
+  const y = counterOrNone(b);
+  return x === void 0 ? y : y === void 0 ? x : Math.max(x, y);
+};
+function usableEntry(entry) {
+  if (typeof entry !== "object" || entry === null) return void 0;
+  const { nextIndex, addedAt } = entry;
+  const index = counterOrNone(nextIndex);
+  if (index === void 0) return void 0;
+  return { nextIndex: index, addedAt: counterOrNone(addedAt) ?? Date.now() };
+}
 function mergePairwise(current, fallback) {
   if (!current && !fallback) return void 0;
-  const merged = {
-    ...fallback ?? {}
-  };
-  for (const [key, entry] of Object.entries(current ?? {})) {
+  const merged = {};
+  for (const [key, entry] of Object.entries(fallback ?? {})) {
+    const usable = usableEntry(entry);
+    if (usable) merged[key] = usable;
+  }
+  for (const [key, raw] of Object.entries(current ?? {})) {
+    const entry = usableEntry(raw);
+    if (!entry) continue;
     const prev = merged[key];
     merged[key] = prev ? {
       nextIndex: Math.max(prev.nextIndex, entry.nextIndex),
@@ -5431,33 +5447,42 @@ function mergePairwise(current, fallback) {
 }
 
 // src/wallet/vault/storage/ephemeralIndex.ts
+var MAX_EPH_INDEX = 4294967294;
+function usableCounter(value) {
+  if (typeof value !== "number" || !Number.isInteger(value)) return null;
+  if (value < 0 || value > MAX_EPH_INDEX) return null;
+  return value;
+}
 async function reserveSelfEphIndex(storage) {
   const updated = await storage.updateConfig((config) => ({
     ...config,
-    selfEphCounter: (config.selfEphCounter ?? 0) + 1,
+    selfEphCounter: (usableCounter(config.selfEphCounter) ?? 0) + 1,
     updatedAt: Date.now()
   }));
   if (!updated) throw new Error("vault not initialized");
-  return (updated.selfEphCounter ?? 1) - 1;
+  return (usableCounter(updated.selfEphCounter) ?? 1) - 1;
 }
 async function reservePairwiseIndex(storage, ivkHex) {
   const key = ivkHex.toLowerCase();
   const updated = await storage.updateConfig((config) => {
-    const current = config.pairwiseCounterparties?.[key];
+    const stored = usableCounter(config.pairwiseCounterparties?.[key]?.nextIndex);
+    const addedAt = config.pairwiseCounterparties?.[key]?.addedAt;
     return {
       ...config,
       pairwiseCounterparties: {
         ...config.pairwiseCounterparties,
         [key]: {
-          nextIndex: (current?.nextIndex ?? 0) + 1,
-          addedAt: current?.addedAt ?? Date.now()
+          nextIndex: (stored ?? 0) + 1,
+          addedAt: typeof addedAt === "number" ? addedAt : Date.now()
         }
       },
       updatedAt: Date.now()
     };
   });
   if (!updated) throw new Error("vault not initialized");
-  return (updated.pairwiseCounterparties?.[key]?.nextIndex ?? 1) - 1;
+  const nextIndex = usableCounter(updated.pairwiseCounterparties?.[key]?.nextIndex);
+  if (nextIndex === null || nextIndex <= 1) return null;
+  return nextIndex - 1;
 }
 
 // src/wallet/vault/notes/record.ts
@@ -6235,7 +6260,7 @@ function gapMargin(windowSize) {
 }
 function resolveSelfEphCeiling(params) {
   const { notes, spendingKey, viewingKey, scanMaxIndex } = params;
-  const windowSize = params.windowSize ?? SELF_EPH_WINDOW;
+  const windowSize = params.windowSize !== void 0 && params.windowSize > 0 ? params.windowSize : SELF_EPH_WINDOW;
   if (scanMaxIndex === null) return null;
   if (scanMaxIndex < windowSize - gapMargin(windowSize)) return scanMaxIndex;
   const ownEphPks = /* @__PURE__ */ new Set();
@@ -6260,9 +6285,12 @@ function resolveSelfEphCeiling(params) {
   }
   return max;
 }
+var MAX_EPH_WINDOW = SELF_EPH_WINDOW * 64;
 function windowSizeForCounter(counter) {
-  const needed = counter + gapMargin(SELF_EPH_WINDOW);
-  return Math.max(SELF_EPH_WINDOW, Math.ceil(needed / SELF_EPH_WINDOW) * SELF_EPH_WINDOW);
+  const used = Number.isFinite(counter) ? counter : 0;
+  const needed = used + gapMargin(SELF_EPH_WINDOW);
+  const rounded = Math.ceil(needed / SELF_EPH_WINDOW) * SELF_EPH_WINDOW;
+  return Math.min(MAX_EPH_WINDOW, Math.max(SELF_EPH_WINDOW, rounded));
 }
 
 // src/wallet/scanner/phases/spentStatus.ts
@@ -6520,11 +6548,13 @@ async function buildZkNote(params, deps) {
   } else if (params.viewingPublicKey && storage && keys.viewingSecretKey) {
     try {
       const index = await reservePairwiseIndex(storage, toHex(params.viewingPublicKey));
-      const pairSecret = derivePairwiseSharedSecret(
-        keys.viewingSecretKey,
-        params.viewingPublicKey
-      );
-      ephSkOverride = derivePairwiseEphSk(pairSecret, index);
+      if (index !== null) {
+        const pairSecret = derivePairwiseSharedSecret(
+          keys.viewingSecretKey,
+          params.viewingPublicKey
+        );
+        ephSkOverride = derivePairwiseEphSk(pairSecret, index);
+      }
     } catch {
     }
   }

package/dist/index.mjs

@@ -4188,13 +4188,29 @@ function mergeCounters(current, fallback) {
     ...parties !== void 0 ? { pairwiseCounterparties: parties } : {}
   };
 }
-var higher = (a, b) => a === void 0 ? b : b === void 0 ? a : Math.max(a, b);
+var counterOrNone = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+var higher = (a, b) => {
+  const x = counterOrNone(a);
+  const y = counterOrNone(b);
+  return x === void 0 ? y : y === void 0 ? x : Math.max(x, y);
+};
+function usableEntry(entry) {
+  if (typeof entry !== "object" || entry === null) return void 0;
+  const { nextIndex, addedAt } = entry;
+  const index = counterOrNone(nextIndex);
+  if (index === void 0) return void 0;
+  return { nextIndex: index, addedAt: counterOrNone(addedAt) ?? Date.now() };
+}
 function mergePairwise(current, fallback) {
   if (!current && !fallback) return void 0;
-  const merged = {
-    ...fallback ?? {}
-  };
-  for (const [key, entry] of Object.entries(current ?? {})) {
+  const merged = {};
+  for (const [key, entry] of Object.entries(fallback ?? {})) {
+    const usable = usableEntry(entry);
+    if (usable) merged[key] = usable;
+  }
+  for (const [key, raw] of Object.entries(current ?? {})) {
+    const entry = usableEntry(raw);
+    if (!entry) continue;
     const prev = merged[key];
     merged[key] = prev ? {
       nextIndex: Math.max(prev.nextIndex, entry.nextIndex),
@@ -4205,33 +4221,42 @@ function mergePairwise(current, fallback) {
 }
 
 // src/wallet/vault/storage/ephemeralIndex.ts
+var MAX_EPH_INDEX = 4294967294;
+function usableCounter(value) {
+  if (typeof value !== "number" || !Number.isInteger(value)) return null;
+  if (value < 0 || value > MAX_EPH_INDEX) return null;
+  return value;
+}
 async function reserveSelfEphIndex(storage) {
   const updated = await storage.updateConfig((config) => ({
     ...config,
-    selfEphCounter: (config.selfEphCounter ?? 0) + 1,
+    selfEphCounter: (usableCounter(config.selfEphCounter) ?? 0) + 1,
     updatedAt: Date.now()
   }));
   if (!updated) throw new Error("vault not initialized");
-  return (updated.selfEphCounter ?? 1) - 1;
+  return (usableCounter(updated.selfEphCounter) ?? 1) - 1;
 }
 async function reservePairwiseIndex(storage, ivkHex) {
   const key = ivkHex.toLowerCase();
   const updated = await storage.updateConfig((config) => {
-    const current = config.pairwiseCounterparties?.[key];
+    const stored = usableCounter(config.pairwiseCounterparties?.[key]?.nextIndex);
+    const addedAt = config.pairwiseCounterparties?.[key]?.addedAt;
     return {
       ...config,
       pairwiseCounterparties: {
         ...config.pairwiseCounterparties,
         [key]: {
-          nextIndex: (current?.nextIndex ?? 0) + 1,
-          addedAt: current?.addedAt ?? Date.now()
+          nextIndex: (stored ?? 0) + 1,
+          addedAt: typeof addedAt === "number" ? addedAt : Date.now()
         }
       },
       updatedAt: Date.now()
     };
   });
   if (!updated) throw new Error("vault not initialized");
-  return (updated.pairwiseCounterparties?.[key]?.nextIndex ?? 1) - 1;
+  const nextIndex = usableCounter(updated.pairwiseCounterparties?.[key]?.nextIndex);
+  if (nextIndex === null || nextIndex <= 1) return null;
+  return nextIndex - 1;
 }
 
 // src/wallet/vault/notes/record.ts
@@ -4998,7 +5023,7 @@ function gapMargin(windowSize) {
 }
 function resolveSelfEphCeiling(params) {
   const { notes, spendingKey, viewingKey, scanMaxIndex } = params;
-  const windowSize = params.windowSize ?? SELF_EPH_WINDOW;
+  const windowSize = params.windowSize !== void 0 && params.windowSize > 0 ? params.windowSize : SELF_EPH_WINDOW;
   if (scanMaxIndex === null) return null;
   if (scanMaxIndex < windowSize - gapMargin(windowSize)) return scanMaxIndex;
   const ownEphPks = /* @__PURE__ */ new Set();
@@ -5023,9 +5048,12 @@ function resolveSelfEphCeiling(params) {
   }
   return max;
 }
+var MAX_EPH_WINDOW = SELF_EPH_WINDOW * 64;
 function windowSizeForCounter(counter) {
-  const needed = counter + gapMargin(SELF_EPH_WINDOW);
-  return Math.max(SELF_EPH_WINDOW, Math.ceil(needed / SELF_EPH_WINDOW) * SELF_EPH_WINDOW);
+  const used = Number.isFinite(counter) ? counter : 0;
+  const needed = used + gapMargin(SELF_EPH_WINDOW);
+  const rounded = Math.ceil(needed / SELF_EPH_WINDOW) * SELF_EPH_WINDOW;
+  return Math.min(MAX_EPH_WINDOW, Math.max(SELF_EPH_WINDOW, rounded));
 }
 
 // src/wallet/scanner/phases/spentStatus.ts
@@ -5283,11 +5311,13 @@ async function buildZkNote(params, deps) {
   } else if (params.viewingPublicKey && storage && keys.viewingSecretKey) {
     try {
       const index = await reservePairwiseIndex(storage, toHex(params.viewingPublicKey));
-      const pairSecret = derivePairwiseSharedSecret(
-        keys.viewingSecretKey,
-        params.viewingPublicKey
-      );
-      ephSkOverride = derivePairwiseEphSk(pairSecret, index);
+      if (index !== null) {
+        const pairSecret = derivePairwiseSharedSecret(
+          keys.viewingSecretKey,
+          params.viewingPublicKey
+        );
+        ephSkOverride = derivePairwiseEphSk(pairSecret, index);
+      }
     } catch {
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbinum/sdk",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Official TypeScript SDK for Orbinum.",
   "author": "Orbinum",
   "license": "MIT",