@provenonce/sdk 0.14.0 → 0.17.1

package/dist/index.js

@@ -29,6 +29,7 @@ __export(index_exports, {
   ProvenonceError: () => ProvenonceError,
   RateLimitError: () => RateLimitError,
   ServerError: () => ServerError,
+  SigilRequiredError: () => SigilRequiredError,
   StateError: () => StateError,
   ValidationError: () => ValidationError,
   computeBeat: () => computeBeat,
@@ -46,6 +47,7 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["VALIDATION"] = "VALIDATION";
   ErrorCode2["AUTH_INVALID"] = "AUTH_INVALID";
   ErrorCode2["AUTH_MISSING"] = "AUTH_MISSING";
+  ErrorCode2["SIGIL_REQUIRED"] = "SIGIL_REQUIRED";
   ErrorCode2["RATE_LIMITED"] = "RATE_LIMITED";
   ErrorCode2["AGENT_FROZEN"] = "AGENT_FROZEN";
   ErrorCode2["AGENT_NOT_INITIALIZED"] = "AGENT_NOT_INITIALIZED";
@@ -78,6 +80,13 @@ var AuthError = class extends ProvenonceError {
     this.name = "AuthError";
   }
 };
+var SigilRequiredError = class extends ProvenonceError {
+  constructor(message = "SIGIL required: purchase a SIGIL before sending heartbeats.") {
+    super(message, "SIGIL_REQUIRED" /* SIGIL_REQUIRED */, 403);
+    this.name = "SigilRequiredError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
 var RateLimitError = class extends ProvenonceError {
   constructor(message, statusCode = 429, retryAfterMs) {
     super(message, "RATE_LIMITED" /* RATE_LIMITED */, statusCode);
@@ -118,7 +127,42 @@ var ServerError = class extends ProvenonceError {
 };
 function mapApiError(statusCode, body, path) {
   const msg = typeof body.error === "string" ? body.error : `API error ${statusCode}`;
+  const apiCode = typeof body.code === "string" ? body.code : void 0;
+  if (apiCode) {
+    switch (apiCode) {
+      case "SIGIL_REQUIRED":
+        return new SigilRequiredError(msg);
+      case "AGENT_FROZEN":
+        return new FrozenError(msg);
+      case "AUTH_MISSING":
+        return new AuthError(msg, "AUTH_MISSING" /* AUTH_MISSING */, statusCode);
+      case "AUTH_INVALID":
+      case "AUTH_FORBIDDEN":
+        return new AuthError(msg, "AUTH_INVALID" /* AUTH_INVALID */, statusCode);
+      case "RATE_LIMITED":
+      case "HEARTBEAT_TOO_SOON":
+      case "VOLUME_CAP_REACHED":
+      case "SPAWN_LIMIT_REACHED": {
+        const retryAfter = typeof body.retry_after_ms === "number" ? body.retry_after_ms : void 0;
+        return new RateLimitError(msg, statusCode, retryAfter);
+      }
+      case "AGENT_NOT_FOUND":
+        return new NotFoundError(msg, statusCode);
+      case "AGENT_NOT_INITIALIZED":
+        return new StateError(msg, "not_initialized", "AGENT_NOT_INITIALIZED" /* AGENT_NOT_INITIALIZED */);
+      case "AGENT_WRONG_STATE":
+      case "SPAWN_CONFLICT":
+        return new StateError(msg, "conflict", "AGENT_WRONG_STATE" /* AGENT_WRONG_STATE */);
+      case "SERVER_ERROR":
+      case "DB_ERROR":
+      case "DB_NOT_CONFIGURED":
+        return new ServerError(msg, statusCode);
+    }
+  }
   if (statusCode === 401 || statusCode === 403) {
+    if (statusCode === 403 && body.sigil_required === true) {
+      return new SigilRequiredError(msg);
+    }
     const code = statusCode === 401 ? "AUTH_MISSING" /* AUTH_MISSING */ : "AUTH_INVALID" /* AUTH_INVALID */;
     return new AuthError(msg, code, statusCode);
   }
@@ -349,7 +393,7 @@ async function register(name, options) {
   if (!res.ok) throw mapApiError(res.status, data, "/api/v1/register");
   return data;
 }
-var BeatAgent = class {
+var BeatAgent = class _BeatAgent {
   constructor(config) {
     this.chain = [];
     this.difficulty = 1e3;
@@ -361,9 +405,10 @@ var BeatAgent = class {
     this.heartbeatInterval = null;
     this.globalBeat = 0;
     this.globalAnchorHash = "";
+    this.cachedIdentityClass = "";
     // ── PHASE 2: SIGIL + HEARTBEAT + PROOF ──
-    /** Cached lineage proof from the most recent heartbeat or SIGIL purchase */
-    this.cachedProof = null;
+    /** Cached passport from the most recent heartbeat or SIGIL purchase */
+    this.cachedPassport = null;
     if (!config.apiKey || typeof config.apiKey !== "string") {
       throw new ValidationError("BeatAgentConfig.apiKey is required (must be a non-empty string)");
     }
@@ -474,10 +519,12 @@ var BeatAgent = class {
    * Start the autonomous heartbeat loop.
    * Phase 2: Sends paid heartbeats at regular intervals.
    *
-   * @param paymentTxFn - Optional function that returns a payment tx for each heartbeat.
-   *                      If not provided, uses 'devnet-skip' (devnet only).
+   * @param paymentTxFn - Function that returns a Solana payment tx signature for each heartbeat (required).
    */
   startHeartbeat(paymentTxFn) {
+    if (!paymentTxFn) {
+      throw new ValidationError("paymentTxFn is required. Provide a function that returns a Solana transaction signature.");
+    }
     if (this.heartbeatInterval) {
       this.log("Heartbeat already running.");
       return;
@@ -495,7 +542,7 @@ var BeatAgent = class {
         return;
       }
       try {
-        const paymentTx = paymentTxFn ? await paymentTxFn() : "devnet-skip";
+        const paymentTx = await paymentTxFn();
         await this.heartbeat(paymentTx);
         consecutiveErrors = 0;
       } catch (err) {
@@ -641,13 +688,16 @@ var BeatAgent = class {
     const genesisHash = (0, import_crypto.createHash)("sha256").update(`provenonce:work-proof-genesis:${this.config.apiKey.slice(0, 16)}:${Date.now()}`).digest("hex");
     const beats = Math.max(beatsNeeded, 1);
     let prevHash = genesisHash;
-    const spotCheckCount = Math.min(5, Math.max(1, Math.floor(beats / 100)));
+    const spotCheckCount = Math.max(
+      Math.min(beats, 3),
+      Math.min(Math.ceil(beats / 1e3), 25)
+    );
     const spotInterval = Math.max(1, Math.floor(beats / (spotCheckCount + 1)));
     const spotChecks = [];
     for (let i = 1; i <= beats; i++) {
       const beat = computeBeat(prevHash, i, difficulty, void 0, anchorHash);
       prevHash = beat.hash;
-      if (i % spotInterval === 0 && spotChecks.length < spotCheckCount) {
+      if (i === 1 || i === beats || i % spotInterval === 0 && spotChecks.length < spotCheckCount) {
         spotChecks.push({ index: beat.index, hash: beat.hash, prev: beat.prev });
       }
     }
@@ -790,16 +840,19 @@ var BeatAgent = class {
     }
     try {
       const res = await this.api("POST", "/api/v1/sigil", body);
-      if (res.lineage_proof) {
-        this.cachedProof = res.lineage_proof;
+      const resPassport = res.passport || res.lineage_proof;
+      if (resPassport) {
+        this.cachedPassport = resPassport;
       }
       const sigilStr = res.sigil?.sigil || res.sigil?.identity_class || "";
+      this.cachedIdentityClass = res.sigil?.identity_class || "";
       this.log(`SIGIL purchased: ${sigilStr}`);
       this.config.onStatusChange("sigil_issued", { sigil: sigilStr });
       return {
         ok: true,
         sigil: res.sigil,
-        lineage_proof: res.lineage_proof,
+        passport: resPassport,
+        lineage_proof: resPassport,
         fee: res.fee
       };
     } catch (err) {
@@ -807,6 +860,35 @@ var BeatAgent = class {
       return { ok: false, error: err.message };
     }
   }
+  /**
+   * Get a SIGIL attribution token from a partner skill's ref_token (RFC-018).
+   *
+   * Call this after receiving a skill's ref_token in its response.
+   * Returns a pvr_ attribution token to include as `at` in purchaseSigil().
+   *
+   * This is the agent-side half of the two-sided witnessed proof:
+   * the skill's server already called /sigil/check for this agent hash.
+   * This call completes the proof — our server witnesses both sides.
+   *
+   * @param partnerRef - The skill's 16-char ref_token
+   */
+  async getSigilAttribution(partnerRef) {
+    if (!partnerRef || typeof partnerRef !== "string" || partnerRef.length !== 16) {
+      return { ok: false, error: "partnerRef must be a 16-character ref_token from the skill" };
+    }
+    try {
+      const res = await this.api("POST", "/api/v1/sigil/check", { partner_ref: partnerRef });
+      return {
+        ok: true,
+        attribution_token: res.attribution_token,
+        signup_url: res.signup_url ?? null,
+        already_has_sigil: res.already_has_sigil ?? false
+      };
+    } catch (err) {
+      this.config.onError(err, "getSigilAttribution");
+      return { ok: false, error: err.message };
+    }
+  }
   /**
    * Update mutable SIGIL metadata fields.
    * Requires a SIGIL. Cannot modify immutable fields.
@@ -836,17 +918,25 @@ var BeatAgent = class {
    * Requires a SIGIL. Returns a signed lineage proof.
    * This is the Phase 2 replacement for pulse() + checkin().
    *
-   * @param paymentTx - Solana transaction signature. Omit or 'devnet-skip' on devnet.
+   * @param paymentTx - Solana transaction signature (required).
    * @param globalAnchor - Optional: the global anchor index to reference.
    */
-  async heartbeat(paymentTx, globalAnchor) {
+  async heartbeat(paymentTx, globalAnchor, opts) {
+    if (!paymentTx) {
+      throw new ValidationError("paymentTx is required. Provide a Solana transaction signature.");
+    }
     try {
-      const res = await this.api("POST", "/api/v1/agent/heartbeat", {
-        payment_tx: paymentTx || "devnet-skip",
+      const body = {
+        payment_tx: paymentTx,
         global_anchor: globalAnchor
-      });
-      if (res.lineage_proof) {
-        this.cachedProof = res.lineage_proof;
+      };
+      if (opts?.sponsoredBy) {
+        body.sponsored_by = opts.sponsoredBy;
+      }
+      const res = await this.api("POST", "/api/v1/agent/heartbeat", body);
+      const hbPassport = res.passport || res.lineage_proof;
+      if (hbPassport) {
+        this.cachedPassport = hbPassport;
       }
       if (res.ok) {
         this.status = "active";
@@ -856,69 +946,216 @@ var BeatAgent = class {
       }
       return {
         ok: res.ok,
-        lineage_proof: res.lineage_proof,
+        passport: hbPassport,
+        lineage_proof: hbPassport,
         heartbeat_count_epoch: res.heartbeat_count_epoch,
         billing_epoch: res.billing_epoch,
         current_beat: res.current_beat,
-        fee: res.fee
+        fee: res.fee,
+        sponsor: res.sponsor
       };
     } catch (err) {
+      if (err instanceof SigilRequiredError) {
+        return { ok: false, sigil_required: true, error: err.message };
+      }
       this.config.onError(err, "heartbeat");
       return { ok: false, error: err.message };
     }
   }
   /**
-   * Reissue a lineage proof. "Reprint, not a renewal."
+   * Reissue a passport. "Reprint, not a renewal."
    * Does NOT create a new lineage event.
    *
-   * @param paymentTx - Solana transaction signature. Omit or 'devnet-skip' on devnet.
+   * @param paymentTx - Solana transaction signature (required).
    */
-  async reissueProof(paymentTx) {
+  async reissuePassport(paymentTx) {
+    if (!paymentTx) {
+      throw new ValidationError("paymentTx is required. Provide a Solana transaction signature.");
+    }
     try {
       const res = await this.api("POST", "/api/v1/agent/reissue-proof", {
-        payment_tx: paymentTx || "devnet-skip"
+        payment_tx: paymentTx
       });
-      if (res.lineage_proof) {
-        this.cachedProof = res.lineage_proof;
+      const rePassport = res.passport || res.lineage_proof;
+      if (rePassport) {
+        this.cachedPassport = rePassport;
       }
-      return { ok: true, lineage_proof: res.lineage_proof };
+      return { ok: true, passport: rePassport, lineage_proof: rePassport };
+    } catch (err) {
+      this.config.onError(err, "reissuePassport");
+      return { ok: false, error: err.message };
+    }
+  }
+  /** @deprecated Use `reissuePassport()` instead. Sunset 2026-09-01. */
+  async reissueProof(paymentTx) {
+    return this.reissuePassport(paymentTx);
+  }
+  // ============ SPONSORSHIP (RFC-021) ============
+  /**
+   * Sponsor a child agent's heartbeats.
+   * The authenticated agent (this instance) becomes the sponsor, paying heartbeat
+   * fees on behalf of the specified child from this agent's operator wallet.
+   *
+   * @param childHash - Hash of the child agent to sponsor
+   * @param opts.maxHeartbeatsEpoch - Max heartbeats per billing epoch (default: 100, max: 10,000)
+   * @param opts.expiresInHours - Optional TTL for the sponsorship
+   */
+  async sponsorChild(childHash, opts) {
+    try {
+      const res = await this.api("POST", "/api/v1/agent/sponsor", {
+        child_hash: childHash,
+        max_heartbeats_epoch: opts?.maxHeartbeatsEpoch,
+        expires_in_hours: opts?.expiresInHours
+      });
+      return { ok: true, sponsorship: res.sponsorship };
+    } catch (err) {
+      this.config.onError(err, "sponsorChild");
+      return { ok: false, error: err.message };
+    }
+  }
+  /**
+   * Revoke a sponsorship for a child agent.
+   * The child will no longer be able to use this agent's wallet for heartbeat payments.
+   */
+  async revokeSponsor(childHash) {
+    try {
+      await this.api("DELETE", "/api/v1/agent/sponsor", {
+        child_hash: childHash
+      });
+      return { ok: true };
+    } catch (err) {
+      this.config.onError(err, "revokeSponsor");
+      return { ok: false, error: err.message };
+    }
+  }
+  /**
+   * List all active sponsorships for this agent (as parent).
+   */
+  async listSponsorships() {
+    try {
+      const res = await this.api("GET", "/api/v1/agent/sponsor");
+      return { ok: true, sponsorships: res.sponsorships };
     } catch (err) {
-      this.config.onError(err, "reissueProof");
+      this.config.onError(err, "listSponsorships");
       return { ok: false, error: err.message };
     }
   }
   /**
-   * Get the latest cached lineage proof (no network call).
-   * Returns null if no proof has been obtained yet.
+   * Get the latest cached passport (no network call).
+   * Returns null if no passport has been obtained yet.
    */
+  getLatestPassport() {
+    return this.cachedPassport;
+  }
+  /** @deprecated Use `getLatestPassport()` instead. Sunset 2026-09-01. */
   getLatestProof() {
-    return this.cachedProof;
+    return this.getLatestPassport();
   }
   /**
-   * Get the agent's passport (alias for getLatestProof).
+   * Get the agent's passport (alias for getLatestPassport).
    * The passport is the agent's portable, offline-verifiable credential.
    * Returns null if no passport has been issued yet (requires SIGIL + heartbeat).
    */
   getPassport() {
-    return this.cachedProof;
+    return this.cachedPassport;
+  }
+  /**
+   * Export this agent's passport in both flat (Passport) and W3C VC envelope formats.
+   * Fetches a freshly signed passport from the server. Free endpoint, rate-limited 10/hr.
+   * Returns null if the request fails.
+   */
+  async exportPassport() {
+    try {
+      const res = await this.api("GET", "/api/v1/agent/passport");
+      const expPassport = res.passport || res.lineage_proof;
+      if (expPassport) {
+        this.cachedPassport = expPassport;
+      }
+      return { passport: expPassport, passport_vc: res.passport_vc, lineage_proof: expPassport };
+    } catch (err) {
+      this.config.onError(err, "exportPassport");
+      return null;
+    }
+  }
+  /**
+   * Wrap a Passport in a W3C Verifiable Credential envelope (client-side).
+   * Does not make any network call. Requires the passport to have authority_key_id.
+   */
+  static proofToPassportVC(proof, authorityKeyId) {
+    const keyId = proof.authority_key_id || authorityKeyId || "unknown";
+    return {
+      "@context": [
+        "https://www.w3.org/2018/credentials/v1",
+        "https://provenonce.io/.well-known/provenonce-passport-v1.jsonld"
+      ],
+      type: ["VerifiableCredential", "ProvenoncePassport"],
+      issuer: {
+        id: "https://provenonce.io",
+        authority_key_id: keyId
+      },
+      issuanceDate: new Date(proof.issued_at).toISOString(),
+      expirationDate: new Date(proof.valid_until).toISOString(),
+      credentialSubject: {
+        id: `provenonce:agent:${proof.agent_hash}`,
+        agent_hash: proof.agent_hash,
+        agent_public_key: proof.agent_public_key,
+        identity_class: proof.identity_class,
+        registered_at_beat: proof.registered_at_beat,
+        sigil_issued_at_beat: proof.sigil_issued_at_beat,
+        last_heartbeat_beat: proof.last_heartbeat_beat,
+        lineage_chain_hash: proof.lineage_chain_hash
+      },
+      proof: {
+        type: "Ed25519Signature2020",
+        created: new Date(proof.issued_at).toISOString(),
+        verificationMethod: `https://provenonce.io/.well-known/provenonce-authority.json#${keyId}`,
+        proofPurpose: "assertionMethod",
+        cryptosuite: "eddsa-provenonce-2026",
+        proofValue: proof.provenonce_signature
+      },
+      format_version: proof.format_version || 1
+    };
   }
   /**
-   * Verify a lineage proof locally using the authority public key.
+   * Verify a passport locally using the authority public key.
    * Offline verification — no API call, no SOL cost.
    *
    * Returns a VerificationResult object. The object is truthy when valid,
-   * so `if (BeatAgent.verifyProofLocally(proof, key))` still works.
+   * so `if (BeatAgent.verifyPassportLocally(proof, key))` still works.
    *
-   * @param proof - The LineageProof to verify
+   * @param proof - The Passport to verify
    * @param authorityPubKeyHex - 32-byte hex-encoded Ed25519 public key from /.well-known/provenonce-authority.json
    * @param currentBeat - Optional current global beat index (for beatsSinceHeartbeat calculation)
    */
-  static verifyProofLocally(proof, authorityPubKeyHex, currentBeat) {
+  static verifyPassportLocally(proof, authorityPubKeyHex, currentBeat) {
     const now = Date.now();
     const expired = now > proof.valid_until;
     let signatureValid = false;
     try {
-      const canonical = JSON.stringify({
+      const canonical = proof.format_version ? JSON.stringify({
+        format_version: proof.format_version,
+        agent_hash: proof.agent_hash,
+        agent_public_key: proof.agent_public_key,
+        authority_key_id: proof.authority_key_id,
+        identity_class: proof.identity_class,
+        registered_at_beat: proof.registered_at_beat,
+        sigil_issued_at_beat: proof.sigil_issued_at_beat,
+        last_heartbeat_beat: proof.last_heartbeat_beat,
+        lineage_chain_hash: proof.lineage_chain_hash,
+        issued_at: proof.issued_at,
+        valid_until: proof.valid_until
+      }) : proof.authority_key_id ? JSON.stringify({
+        agent_hash: proof.agent_hash,
+        agent_public_key: proof.agent_public_key,
+        authority_key_id: proof.authority_key_id,
+        identity_class: proof.identity_class,
+        registered_at_beat: proof.registered_at_beat,
+        sigil_issued_at_beat: proof.sigil_issued_at_beat,
+        last_heartbeat_beat: proof.last_heartbeat_beat,
+        lineage_chain_hash: proof.lineage_chain_hash,
+        issued_at: proof.issued_at,
+        valid_until: proof.valid_until
+      }) : JSON.stringify({
         agent_hash: proof.agent_hash,
         agent_public_key: proof.agent_public_key,
         identity_class: proof.identity_class,
@@ -944,12 +1181,16 @@ var BeatAgent = class {
     const beatsSinceHeartbeat = currentBeat != null ? currentBeat - proof.last_heartbeat_beat : null;
     let warning;
     if (expired) {
-      warning = "Proof has expired. Reissue with reissueProof() or send a heartbeat.";
+      warning = "Passport has expired. Reissue with reissuePassport() or send a heartbeat.";
     } else if (beatsSinceHeartbeat != null && beatsSinceHeartbeat > 60) {
       warning = `Agent is ${beatsSinceHeartbeat} beats behind. Heartbeat may be stale.`;
     }
     return { valid, signatureValid, expired, lastHeartbeatBeat: proof.last_heartbeat_beat, beatsSinceHeartbeat, warning };
   }
+  /** @deprecated Use `verifyPassportLocally()` instead. Sunset 2026-09-01. */
+  static verifyProofLocally(proof, authorityPubKeyHex, currentBeat) {
+    return _BeatAgent.verifyPassportLocally(proof, authorityPubKeyHex, currentBeat);
+  }
   // ── STATUS ──
   /**
    * Get this agent's full beat status from the registry.
@@ -976,6 +1217,14 @@ var BeatAgent = class {
       chainLength: this.chain.length
     };
   }
+  /**
+   * Returns true if this agent has purchased a SIGIL in this session,
+   * or if a cached passport contains an identity_class.
+   * For an authoritative check, use GET /api/v1/agent/me.
+   */
+  hasSigil() {
+    return !!(this.cachedIdentityClass || this.cachedPassport?.identity_class);
+  }
   // ── INTERNALS ──
   async syncGlobal() {
     try {
@@ -991,7 +1240,6 @@ var BeatAgent = class {
         }
         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})`);
       }
     } catch {
@@ -1083,6 +1331,7 @@ function computeBeatsLite(startHash, startIndex, count, difficulty = 1e3, anchor
   ProvenonceError,
   RateLimitError,
   ServerError,
+  SigilRequiredError,
   StateError,
   ValidationError,
   computeBeat,