@provenonce/sdk 0.5.0 → 0.8.0

package/dist/index.js

@@ -22,19 +22,256 @@ var index_exports = {};
 __export(index_exports, {
   BeatAgent: () => BeatAgent,
   computeBeat: () => computeBeat,
-  computeBeatsLite: () => computeBeatsLite
+  computeBeatsLite: () => computeBeatsLite,
+  generateWalletKeypair: () => generateWalletKeypair,
+  register: () => register
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/beat-sdk.ts
 var import_crypto = require("crypto");
-function computeBeat(prevHash, beatIndex, difficulty, nonce) {
+function computeBeat(prevHash, beatIndex, difficulty, nonce, anchorHash) {
   const timestamp = Date.now();
-  let current = (0, import_crypto.createHash)("sha256").update(`${prevHash}:${beatIndex}:${nonce || ""}`).digest("hex");
+  const seed = anchorHash ? `${prevHash}:${beatIndex}:${nonce || ""}:${anchorHash}` : `${prevHash}:${beatIndex}:${nonce || ""}`;
+  let current = (0, import_crypto.createHash)("sha256").update(seed).digest("hex");
   for (let i = 0; i < difficulty; i++) {
     current = (0, import_crypto.createHash)("sha256").update(current).digest("hex");
   }
-  return { index: beatIndex, hash: current, prev: prevHash, timestamp, nonce };
+  return { index: beatIndex, hash: current, prev: prevHash, timestamp, nonce, anchor_hash: anchorHash };
+}
+var ED25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+function generateWalletKeypair() {
+  const { publicKey, privateKey } = (0, import_crypto.generateKeyPairSync)("ed25519");
+  const pubRaw = publicKey.export({ type: "spki", format: "der" }).subarray(12);
+  const privRaw = privateKey.export({ type: "pkcs8", format: "der" }).subarray(16);
+  return {
+    publicKey: Buffer.from(pubRaw).toString("hex"),
+    secretKey: Buffer.from(privRaw).toString("hex")
+  };
+}
+function signMessage(secretKeyHex, message) {
+  const privRaw = Buffer.from(secretKeyHex, "hex");
+  const privKeyDer = Buffer.concat([ED25519_PKCS8_PREFIX, privRaw]);
+  const keyObject = (0, import_crypto.createPrivateKey)({ key: privKeyDer, format: "der", type: "pkcs8" });
+  const sig = (0, import_crypto.sign)(null, Buffer.from(message), keyObject);
+  return Buffer.from(sig).toString("hex");
+}
+async function register(name, options) {
+  if (!name || typeof name !== "string" || name.trim().length === 0) {
+    throw new Error("name is required (must be a non-empty string)");
+  }
+  if (name.length > 64) {
+    throw new Error("name must be 64 characters or fewer");
+  }
+  const url = options?.registryUrl || "https://provenonce.io";
+  try {
+    new URL(url);
+  } catch {
+    throw new Error("registryUrl is not a valid URL");
+  }
+  const headers = { "Content-Type": "application/json" };
+  if (options?.registrationSecret) {
+    headers["x-registration-secret"] = options.registrationSecret;
+  }
+  if (options?.parentHash) {
+    if (options.parentApiKey) {
+      headers["Authorization"] = `Bearer ${options.parentApiKey}`;
+    }
+    const res2 = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ name, parent: options.parentHash, ...options.metadata && { metadata: options.metadata } })
+    });
+    let data2;
+    try {
+      data2 = await res2.json();
+    } catch {
+      throw new Error(`Registration failed: ${res2.status} ${res2.statusText} (non-JSON response)`);
+    }
+    if (!res2.ok) throw new Error(data2.error || "Registration failed");
+    return data2;
+  }
+  if (options?.walletChain === "ethereum") {
+    if (!options.walletAddress || !options.walletSignFn) {
+      throw new Error("Ethereum registration requires walletAddress and walletSignFn");
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(options.walletAddress)) {
+      throw new Error("walletAddress must be a valid Ethereum address (0x + 40 hex chars)");
+    }
+    const challengeRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ name, action: "challenge", wallet_chain: "ethereum" })
+    });
+    let challengeData;
+    try {
+      challengeData = await challengeRes.json();
+    } catch {
+      throw new Error(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
+    }
+    if (!challengeRes.ok || !challengeData.nonce) {
+      throw new Error(challengeData.error || "Failed to get registration challenge");
+    }
+    const nonce = challengeData.nonce;
+    const message = `provenonce-register-ethereum:${nonce}:${options.walletAddress}:${name}`;
+    const walletSignature = await options.walletSignFn(message);
+    const registerRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        name,
+        wallet_chain: "ethereum",
+        wallet_address: options.walletAddress,
+        wallet_signature: walletSignature,
+        wallet_nonce: nonce,
+        ...options.metadata && { metadata: options.metadata }
+      })
+    });
+    let data2;
+    try {
+      data2 = await registerRes.json();
+    } catch {
+      throw new Error(`Ethereum registration failed: ${registerRes.status} (non-JSON response)`);
+    }
+    if (!registerRes.ok) throw new Error(data2.error || "Registration failed");
+    data2.wallet = {
+      public_key: "",
+      secret_key: "",
+      address: data2.wallet?.address || options.walletAddress,
+      chain: "ethereum"
+    };
+    return data2;
+  }
+  if (options?.walletModel === "operator") {
+    if (!options.operatorWalletAddress || !options.operatorSignFn) {
+      throw new Error("Operator registration requires operatorWalletAddress and operatorSignFn");
+    }
+    const challengeRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ name, action: "challenge", wallet_model: "operator" })
+    });
+    let challengeData;
+    try {
+      challengeData = await challengeRes.json();
+    } catch {
+      throw new Error(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
+    }
+    if (!challengeRes.ok || !challengeData.nonce) {
+      throw new Error(challengeData.error || "Failed to get registration challenge");
+    }
+    const nonce = challengeData.nonce;
+    const message = `provenonce-register-operator:${nonce}:${options.operatorWalletAddress}:${name}`;
+    const walletSignature = await options.operatorSignFn(message);
+    const registerRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        name,
+        wallet_model: "operator",
+        operator_wallet_address: options.operatorWalletAddress,
+        wallet_signature: walletSignature,
+        wallet_nonce: nonce,
+        ...options.metadata && { metadata: options.metadata }
+      })
+    });
+    let data2;
+    try {
+      data2 = await registerRes.json();
+    } catch {
+      throw new Error(`Operator registration failed: ${registerRes.status} (non-JSON response)`);
+    }
+    if (!registerRes.ok) throw new Error(data2.error || "Registration failed");
+    const addr = data2.wallet?.address || data2.wallet?.solana_address || options.operatorWalletAddress;
+    data2.wallet = {
+      public_key: "",
+      secret_key: "",
+      solana_address: addr,
+      address: addr,
+      chain: "solana"
+    };
+    return data2;
+  }
+  if (options?.walletModel === "self-custody" || options?.walletSecretKey) {
+    let walletKeys;
+    if (options?.walletSecretKey) {
+      const privRaw = Buffer.from(options.walletSecretKey, "hex");
+      const privKeyDer = Buffer.concat([ED25519_PKCS8_PREFIX, privRaw]);
+      const keyObject = (0, import_crypto.createPrivateKey)({ key: privKeyDer, format: "der", type: "pkcs8" });
+      const pubRaw = keyObject.export({ type: "spki", format: "der" }).subarray(12);
+      walletKeys = {
+        publicKey: Buffer.from(pubRaw).toString("hex"),
+        secretKey: options.walletSecretKey
+      };
+    } else {
+      walletKeys = generateWalletKeypair();
+    }
+    const challengeRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ name, action: "challenge" })
+    });
+    let challengeData;
+    try {
+      challengeData = await challengeRes.json();
+    } catch {
+      throw new Error(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
+    }
+    if (!challengeRes.ok || !challengeData.nonce) {
+      const err = new Error(challengeData.error || "Failed to get registration challenge");
+      err.walletKeys = { publicKey: walletKeys.publicKey, secretKey: walletKeys.secretKey };
+      throw err;
+    }
+    const nonce = challengeData.nonce;
+    const message = `provenonce-register:${nonce}:${walletKeys.publicKey}:${name}`;
+    const walletSignature = signMessage(walletKeys.secretKey, message);
+    const registerRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        name,
+        wallet_public_key: walletKeys.publicKey,
+        wallet_signature: walletSignature,
+        wallet_nonce: nonce,
+        ...options?.metadata && { metadata: options.metadata }
+      })
+    });
+    let data2;
+    try {
+      data2 = await registerRes.json();
+    } catch {
+      const err = new Error(`Registration failed: ${registerRes.status} (non-JSON response)`);
+      err.walletKeys = { publicKey: walletKeys.publicKey, secretKey: walletKeys.secretKey };
+      throw err;
+    }
+    if (!registerRes.ok) {
+      const err = new Error(data2.error || "Registration failed");
+      err.walletKeys = { publicKey: walletKeys.publicKey, secretKey: walletKeys.secretKey };
+      throw err;
+    }
+    const addr = data2.wallet?.address || data2.wallet?.solana_address || "";
+    data2.wallet = {
+      public_key: walletKeys.publicKey,
+      secret_key: walletKeys.secretKey,
+      solana_address: addr,
+      address: addr,
+      chain: "solana"
+    };
+    return data2;
+  }
+  const res = await fetch(`${url}/api/v1/register`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ name, ...options?.metadata && { metadata: options.metadata } })
+  });
+  let data;
+  try {
+    data = await res.json();
+  } catch {
+    throw new Error(`Registration failed: ${res.status} ${res.statusText} (non-JSON response)`);
+  }
+  if (!res.ok) throw new Error(data.error || "Registration failed");
+  return data;
 }
 var BeatAgent = class {
   constructor(config) {
@@ -47,6 +284,24 @@ var BeatAgent = class {
     this.status = "uninitialized";
     this.heartbeatInterval = null;
     this.globalBeat = 0;
+    this.globalAnchorHash = "";
+    if (!config.apiKey || typeof config.apiKey !== "string") {
+      throw new Error("BeatAgentConfig.apiKey is required (must be a non-empty string)");
+    }
+    if (!config.registryUrl || typeof config.registryUrl !== "string") {
+      throw new Error("BeatAgentConfig.registryUrl is required (must be a non-empty string)");
+    }
+    try {
+      new URL(config.registryUrl);
+    } catch {
+      throw new Error("BeatAgentConfig.registryUrl is not a valid URL");
+    }
+    if (config.beatsPerPulse !== void 0 && (!Number.isInteger(config.beatsPerPulse) || config.beatsPerPulse < 1 || config.beatsPerPulse > 1e4)) {
+      throw new Error("BeatAgentConfig.beatsPerPulse must be an integer between 1 and 10000");
+    }
+    if (config.checkinIntervalSec !== void 0 && (!Number.isFinite(config.checkinIntervalSec) || config.checkinIntervalSec < 10 || config.checkinIntervalSec > 86400)) {
+      throw new Error("BeatAgentConfig.checkinIntervalSec must be between 10 and 86400");
+    }
     this.config = {
       beatsPerPulse: 10,
       checkinIntervalSec: 300,
@@ -107,21 +362,32 @@ var BeatAgent = class {
    * through a specific window of computational time.
    */
   pulse(count) {
+    if (this.status !== "active") {
+      throw new Error(`Cannot pulse: agent is ${this.status}. Use resync() if frozen.`);
+    }
+    if (count !== void 0 && (!Number.isInteger(count) || count < 1 || count > 1e4)) {
+      throw new Error("pulse count must be an integer between 1 and 10000");
+    }
+    return this.computeBeats(count);
+  }
+  /** Internal beat computation — no status check. Used by both pulse() and resync(). */
+  computeBeats(count, onProgress) {
     const n = count || this.config.beatsPerPulse;
     if (!this.latestBeat) {
       throw new Error("Beat chain not initialized. Call init() first.");
     }
-    if (this.status !== "active") {
-      throw new Error(`Cannot pulse in status '${this.status}'. Use resync() if frozen.`);
-    }
     const newBeats = [];
     let prevHash = this.latestBeat.hash;
     let startIndex = this.latestBeat.index + 1;
     const t0 = Date.now();
+    const progressInterval = Math.max(1, Math.floor(n / 10));
     for (let i = 0; i < n; i++) {
-      const beat = computeBeat(prevHash, startIndex + i, this.difficulty);
+      const beat = computeBeat(prevHash, startIndex + i, this.difficulty, void 0, this.globalAnchorHash || void 0);
       newBeats.push(beat);
       prevHash = beat.hash;
+      if (onProgress && (i + 1) % progressInterval === 0) {
+        onProgress(i + 1, n);
+      }
     }
     const elapsed = Date.now() - t0;
     this.chain.push(...newBeats);
@@ -142,21 +408,26 @@ var BeatAgent = class {
    *  submit a proof of its Local Beats to the Registry."
    */
   async checkin() {
-    if (!this.latestBeat || this.totalBeats === this.lastCheckinBeat) {
+    if (!this.latestBeat || this.latestBeat.index <= this.lastCheckinBeat) {
+      this.log("No new beats since last check-in. Call pulse() first.");
       return { ok: true, total_beats: this.totalBeats };
     }
     try {
+      const fromBeat = this.lastCheckinBeat;
+      const toBeat = this.latestBeat.index;
       const spotChecks = [];
-      const available = this.chain.filter((b) => b.index > this.lastCheckinBeat);
-      const sampleCount = Math.min(5, available.length);
+      const toBeatEntry = this.chain.find((b) => b.index === toBeat);
+      if (toBeatEntry) {
+        spotChecks.push({ index: toBeatEntry.index, hash: toBeatEntry.hash, prev: toBeatEntry.prev, nonce: toBeatEntry.nonce });
+      }
+      const available = this.chain.filter((b) => b.index > this.lastCheckinBeat && b.index !== toBeat);
+      const sampleCount = Math.min(4, available.length);
       for (let i = 0; i < sampleCount; i++) {
         const idx = Math.floor(Math.random() * available.length);
         const beat = available[idx];
         spotChecks.push({ index: beat.index, hash: beat.hash, prev: beat.prev, nonce: beat.nonce });
         available.splice(idx, 1);
       }
-      const fromBeat = this.lastCheckinBeat;
-      const toBeat = this.latestBeat.index;
       const fromHash = this.chain.find((b) => b.index === fromBeat)?.hash || this.genesisHash;
       const toHash = this.latestBeat.hash;
       const res = await this.api("POST", "/api/v1/agent/checkin", {
@@ -167,6 +438,7 @@ var BeatAgent = class {
           to_hash: toHash,
           beats_computed: toBeat - fromBeat,
           global_anchor: this.globalBeat,
+          anchor_hash: this.globalAnchorHash || void 0,
           spot_checks: spotChecks
         }
       });
@@ -201,7 +473,13 @@ var BeatAgent = class {
       throw new Error(`Cannot start heartbeat in status '${this.status}'.`);
     }
     this.log("\u2661 Starting heartbeat...");
+    let consecutiveErrors = 0;
+    let skipCount = 0;
     this.heartbeatInterval = setInterval(async () => {
+      if (skipCount > 0) {
+        skipCount--;
+        return;
+      }
       try {
         this.pulse();
         const beatsSinceCheckin = this.latestBeat.index - this.lastCheckinBeat;
@@ -210,8 +488,12 @@ var BeatAgent = class {
           await this.checkin();
           await this.syncGlobal();
         }
+        consecutiveErrors = 0;
       } catch (err) {
+        consecutiveErrors++;
         this.config.onError(err, "heartbeat");
+        skipCount = Math.min(32, Math.pow(2, consecutiveErrors - 1));
+        this.log(`Heartbeat error #${consecutiveErrors}, backing off ${skipCount} ticks`);
       }
     }, this.config.checkinIntervalSec * 1e3 / 10);
   }
@@ -246,16 +528,18 @@ var BeatAgent = class {
       const required = challenge.challenge.required_beats;
       this.difficulty = challenge.challenge.difficulty;
       this.log(`Re-sync challenge: compute ${required} beats at D=${this.difficulty}`);
+      await this.syncGlobal();
       const startHash = challenge.challenge.start_from_hash;
       const startBeat = challenge.challenge.start_from_beat;
       this.latestBeat = { index: startBeat, hash: startHash, prev: "", timestamp: Date.now() };
       this.chain = [this.latestBeat];
       const t0 = Date.now();
-      this.pulse(required);
+      this.computeBeats(required);
       const elapsed = Date.now() - t0;
       this.log(`Re-sync beats computed in ${elapsed}ms`);
       const proof = await this.api("POST", "/api/v1/agent/resync", {
         action: "prove",
+        challenge_nonce: challenge.challenge.nonce,
         proof: {
           from_beat: startBeat,
           to_beat: this.latestBeat.index,
@@ -263,7 +547,15 @@ var BeatAgent = class {
           to_hash: this.latestBeat.hash,
           beats_computed: required,
           global_anchor: challenge.challenge.sync_to_global,
-          spot_checks: this.chain.filter((_, i) => i % Math.ceil(required / 5) === 0).slice(0, 5).map((b) => ({ index: b.index, hash: b.hash, prev: b.prev, nonce: b.nonce }))
+          anchor_hash: this.globalAnchorHash || void 0,
+          spot_checks: (() => {
+            const toBeatEntry = this.chain.find((b) => b.index === this.latestBeat.index);
+            const available = this.chain.filter((b) => b.index !== this.latestBeat.index && b.index > startBeat);
+            const step = Math.max(1, Math.ceil(available.length / 5));
+            const others = available.filter((_, i) => i % step === 0).slice(0, 4);
+            const checks = toBeatEntry ? [toBeatEntry, ...others] : others;
+            return checks.map((b) => ({ index: b.index, hash: b.hash, prev: b.prev, nonce: b.nonce }));
+          })()
         }
       });
       if (proof.ok) {
@@ -286,6 +578,14 @@ var BeatAgent = class {
    */
   async requestSpawn(childName, childHash) {
     try {
+      if (childName !== void 0) {
+        if (typeof childName !== "string" || childName.trim().length === 0) {
+          throw new Error("childName must be a non-empty string");
+        }
+        if (childName.length > 64) {
+          throw new Error("childName must be 64 characters or fewer");
+        }
+      }
       const res = await this.api("POST", "/api/v1/agent/spawn", {
         child_name: childName,
         child_hash: childHash
@@ -330,10 +630,14 @@ var BeatAgent = class {
   // ── INTERNALS ──
   async syncGlobal() {
     try {
-      const res = await fetch(`${this.config.registryUrl}/api/v1/beat/anchor`);
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 15e3);
+      const res = await fetch(`${this.config.registryUrl}/api/v1/beat/anchor`, { signal: controller.signal });
+      clearTimeout(timeout);
       const data = await res.json();
       if (data.anchor) {
         this.globalBeat = data.anchor.beat_index;
+        this.globalAnchorHash = data.anchor.hash || "";
         if (data.anchor.difficulty) this.difficulty = data.anchor.difficulty;
         this.log(`Synced to global beat ${this.globalBeat} (D=${this.difficulty})`);
       }
@@ -347,23 +651,52 @@ var BeatAgent = class {
       this.totalBeats = res.total_beats;
       this.genesisHash = res.genesis_hash;
       this.status = res.status;
+      this.difficulty = res.difficulty || this.difficulty;
+      this.lastCheckinBeat = res.last_checkin_beat || 0;
+      if (!this.latestBeat && this.genesisHash) {
+        this.latestBeat = {
+          index: res.latest_beat || this.totalBeats,
+          hash: res.latest_hash || this.genesisHash,
+          prev: "0".repeat(64),
+          timestamp: Date.now()
+        };
+        this.chain = [this.latestBeat];
+      }
     }
     return res;
   }
   async api(method, path, body) {
-    const res = await fetch(`${this.config.registryUrl}${path}`, {
-      method,
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.config.apiKey}`
-      },
-      body: body ? JSON.stringify(body) : void 0
-    });
-    const data = await res.json();
-    if (!res.ok && !data.ok && !data.already_initialized && !data.eligible) {
-      throw new Error(data.error || `API ${res.status}: ${res.statusText}`);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3e4);
+    try {
+      const res = await fetch(`${this.config.registryUrl}${path}`, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.config.apiKey}`
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      let data;
+      try {
+        data = await res.json();
+      } catch {
+        throw new Error(`API error: ${res.status} non-JSON response from ${path}`);
+      }
+      if (!res.ok && !data.ok && !data.already_initialized && !data.eligible) {
+        const serverMsg = typeof data.error === "string" ? data.error : `API error ${res.status}`;
+        throw new Error(serverMsg);
+      }
+      return data;
+    } catch (err) {
+      if (err.name === "AbortError") {
+        throw new Error(`Request timeout: ${method} ${path}`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeout);
     }
-    return data;
   }
   log(msg) {
     if (this.config.verbose) {
@@ -371,12 +704,18 @@ var BeatAgent = class {
     }
   }
 };
-function computeBeatsLite(startHash, startIndex, count, difficulty = 1e3) {
+function computeBeatsLite(startHash, startIndex, count, difficulty = 1e3, anchorHash) {
+  if (!startHash || typeof startHash !== "string") {
+    throw new Error("computeBeatsLite: startHash must be a non-empty string");
+  }
+  if (!Number.isInteger(count) || count < 1) {
+    throw new Error("computeBeatsLite: count must be a positive integer");
+  }
   const t0 = Date.now();
   let prev = startHash;
   let lastBeat = null;
   for (let i = 0; i < count; i++) {
-    lastBeat = computeBeat(prev, startIndex + i, difficulty);
+    lastBeat = computeBeat(prev, startIndex + i, difficulty, void 0, anchorHash);
     prev = lastBeat.hash;
   }
   return { lastBeat, elapsed: Date.now() - t0 };
@@ -385,6 +724,8 @@ function computeBeatsLite(startHash, startIndex, count, difficulty = 1e3) {
 0 && (module.exports = {
   BeatAgent,
   computeBeat,
-  computeBeatsLite
+  computeBeatsLite,
+  generateWalletKeypair,
+  register
 });
 //# sourceMappingURL=index.js.map