@provenonce/sdk 0.10.1 → 0.12.0

package/README.md

@@ -54,13 +54,13 @@ const agent = new BeatAgent({
 
 await agent.init();           // Birth in Beat time
 
-// Purchase a SIGIL (cryptographic identity)
-const sigil = await agent.purchaseSigil({
-  identity_class: 'autonomous',
-  principal: 'my-agent',
-  tier: 'ind',
-  payment_tx: 'solana-tx-signature...',
-});
+// Purchase a SIGIL (cryptographic identity)
+const sigil = await agent.purchaseSigil({
+  identity_class: 'autonomous',
+  principal: 'my-agent',
+  tier: 'ind',
+  payment_tx: 'solana-tx-signature...',
+});
 
 // Start heartbeating (paid liveness proofs)
 agent.startHeartbeat();
@@ -78,18 +78,18 @@ agent.stopHeartbeat();
 
 ## API
 
-### `BeatAgent`
-
-| Method | Description |
-|--------|-------------|
-| `init()` | Initialize the agent's Beat chain (birth in Logical Time) |
-| `purchaseSigil(opts)` | Purchase a SIGIL identity (required for heartbeating) |
-| `updateMetadata(fields)` | Update mutable SIGIL metadata fields |
-| `heartbeat(paymentTx?, globalAnchor?)` | Submit a paid heartbeat and receive a signed lineage proof |
-| `startHeartbeat()` | Start autonomous heartbeat loop |
-| `stopHeartbeat()` | Stop heartbeat |
-| `getPassport()` | Get latest lineage proof (Passport) |
-| `reissueProof(paymentTx?)` | Reissue proof without extending lineage |
+### `BeatAgent`
+
+| Method | Description |
+|--------|-------------|
+| `init()` | Initialize the agent's Beat chain (birth in Logical Time) |
+| `purchaseSigil(opts)` | Purchase a SIGIL identity (required for heartbeating) |
+| `updateMetadata(fields)` | Update mutable SIGIL metadata fields |
+| `heartbeat(paymentTx?, globalAnchor?)` | Submit a paid heartbeat and receive a signed lineage proof |
+| `startHeartbeat()` | Start autonomous heartbeat loop |
+| `stopHeartbeat()` | Stop heartbeat |
+| `getPassport()` | Get latest lineage proof (Passport) |
+| `reissueProof(paymentTx?)` | Reissue proof without extending lineage |
 | `requestSpawn(name?)` | Spawn a child agent (requires accumulated beats) |
 | `getStatus()` | Get full beat status from registry |
 | `getLocalState()` | Get local state (no network call) |
@@ -124,7 +124,7 @@ Returns `RegistrationResult` with `hash`, `api_key`, `secret`, `wallet?`.
 
 **Note:** Agent names should only contain `[a-zA-Z0-9_\-. ]`. Other characters are stripped by the server before signature verification.
 
-### Phase 2 Types
+### Phase 2 Types
 
 ```typescript
 import type { Passport, LineageProof, IdentityClass, SigilResult, HeartbeatResult } from '@provenonce/sdk';
@@ -133,20 +133,20 @@ import type { Passport, LineageProof, IdentityClass, SigilResult, HeartbeatResul
 // Contains: agent_hash, agent_public_key, identity_class, lineage_chain_hash,
 //           provenonce_signature, issued_at, valid_until, etc.
 
-// IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator'
-```
-
-### `purchaseSigil(opts)` required fields
-
-```typescript
-await agent.purchaseSigil({
-  identity_class: 'narrow_task' | 'autonomous' | 'orchestrator',
-  principal: 'my-agent',
-  tier: 'sov' | 'org' | 'ind' | 'eph' | 'sbx',
-  payment_tx: 'solana-tx-signature...', // or 'devnet-skip' on devnet
-  name: 'optional-display-name'
-});
-```
+// IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator'
+```
+
+### `purchaseSigil(opts)` required fields
+
+```typescript
+await agent.purchaseSigil({
+  identity_class: 'narrow_task' | 'autonomous' | 'orchestrator',
+  principal: 'my-agent',
+  tier: 'sov' | 'org' | 'ind' | 'eph' | 'sbx',
+  payment_tx: 'solana-tx-signature...', // or 'devnet-skip' on devnet
+  name: 'optional-display-name'
+});
+```
 
 ### Error Handling
 
@@ -181,7 +181,7 @@ Python examples use the REST API directly — no Python SDK needed. See [`exampl
 
 ## Links
 
-- [Live prototype](https://provenonce.io)
-- [npm package](https://www.npmjs.com/package/@provenonce/sdk)
-- [API docs](https://provenonce.dev)
-- [Whitepaper](https://provenonce.dev/whitepaper)
+- [Live prototype](https://provenonce.io)
+- [npm package](https://www.npmjs.com/package/@provenonce/sdk)
+- [API docs](https://provenonce.dev)
+- [Whitepaper](https://provenonce.dev/whitepaper)

package/dist/index.d.mts

@@ -161,6 +161,20 @@ interface Beat {
     anchor_hash?: string;
 }
 declare function computeBeat(prevHash: string, beatIndex: number, difficulty: number, nonce?: string, anchorHash?: string): Beat;
+/**
+ * Verify an anchor hash locally.
+ * V3 (solana_entropy present): binary-canonical single SHA-256.
+ * V1 legacy (no entropy): string-based hash with difficulty iteration.
+ */
+declare function verifyAnchorHash(anchor: {
+    prev_hash: string;
+    beat_index: number;
+    hash: string;
+    utc: number;
+    epoch: number;
+    difficulty: number;
+    solana_entropy?: string;
+}): boolean;
 /** Result from a check-in submission */
 interface CheckinResult {
     ok: boolean;
@@ -242,9 +256,42 @@ interface RegistrationResult {
         heartbeat?: string;
     };
 }
+/** Options for the register() function */
+interface RegisterOptions {
+    registryUrl?: string;
+    parentHash?: string;
+    parentApiKey?: string;
+    registrationSecret?: string;
+    /** Single-use registration token from POST /register/token or POST /register/email/verify */
+    registrationToken?: string;
+    /** Admin-minted invite token */
+    registrationInvite?: string;
+    /** Hex-encoded 32-byte Ed25519 secret seed (bring-your-own Solana key) */
+    walletSecretKey?: string;
+    /** Wallet model: 'self-custody' (Model A) or 'operator' (Model B). Must be set explicitly to opt in. */
+    walletModel?: 'self-custody' | 'operator';
+    /** Wallet chain: 'solana' (default when wallet is used) or 'ethereum' (D-63) */
+    walletChain?: 'solana' | 'ethereum';
+    /** Wallet address for Ethereum bring-your-own (0x + 40 hex chars) */
+    walletAddress?: string;
+    /** Async function to sign a message with an Ethereum wallet (EIP-191 personal_sign). Returns 0x-prefixed 65-byte hex sig. */
+    walletSignFn?: (message: string) => Promise<string>;
+    /** Operator's Solana wallet address (base58). Required when walletModel='operator'. */
+    operatorWalletAddress?: string;
+    /** Function to sign a message with the operator's Solana wallet. Required when walletModel='operator'. */
+    operatorSignFn?: (message: string) => Promise<string>;
+    /** Optional agent metadata (arbitrary JSON object, max 4KB). Returned in /verify and /status. */
+    metadata?: Record<string, unknown>;
+}
 /**
  * Register a new agent on the Provenonce registry.
  *
+ * With registration token (from /register/token or email verification):
+ *   const creds = await register('my-agent', {
+ *     registryUrl: '...',
+ *     registrationToken: '<token-from-email-verify>',
+ *   });
+ *
  * No wallet (default, single-phase):
  *   const creds = await register('my-agent', { registryUrl: '...' });
  *
@@ -285,28 +332,7 @@ interface RegistrationResult {
  *     parentApiKey: parentCreds.api_key,
  *   });
  */
-declare function register(name: string, options?: {
-    registryUrl?: string;
-    parentHash?: string;
-    parentApiKey?: string;
-    registrationSecret?: string;
-    /** Hex-encoded 32-byte Ed25519 secret seed (bring-your-own Solana key) */
-    walletSecretKey?: string;
-    /** Wallet model: 'self-custody' (Model A) or 'operator' (Model B). Must be set explicitly to opt in. */
-    walletModel?: 'self-custody' | 'operator';
-    /** Wallet chain: 'solana' (default when wallet is used) or 'ethereum' (D-63) */
-    walletChain?: 'solana' | 'ethereum';
-    /** Wallet address for Ethereum bring-your-own (0x + 40 hex chars) */
-    walletAddress?: string;
-    /** Async function to sign a message with an Ethereum wallet (EIP-191 personal_sign). Returns 0x-prefixed 65-byte hex sig. */
-    walletSignFn?: (message: string) => Promise<string>;
-    /** Operator's Solana wallet address (base58). Required when walletModel='operator'. */
-    operatorWalletAddress?: string;
-    /** Function to sign a message with the operator's Solana wallet. Required when walletModel='operator'. */
-    operatorSignFn?: (message: string) => Promise<string>;
-    /** Optional agent metadata (arbitrary JSON object, max 4KB). Returned in /verify and /status. */
-    metadata?: Record<string, unknown>;
-}): Promise<RegistrationResult>;
+declare function register(name: string, options?: RegisterOptions): Promise<RegistrationResult>;
 interface BeatAgentConfig {
     /** API key from registration (pvn_...) */
     apiKey: string;
@@ -330,6 +356,8 @@ interface BeatAgentConfig {
     onStatusChange?: (status: string, details: Record<string, unknown>) => void;
     /** Enable verbose logging */
     verbose?: boolean;
+    /** Verify anchor hash locally before trusting it (default: true). */
+    verifyAnchors?: boolean;
 }
 declare class BeatAgent {
     private config;
@@ -573,4 +601,4 @@ declare class ServerError extends ProvenonceError {
     constructor(message: string, statusCode?: number);
 }
 
-export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type Capability, type CheckinResult, type ComplianceRegime, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, type MetadataUpdateResult, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegistrationResult, ServerError, type SigilMutableFields, type SigilProtocol, type SigilPurchaseOptions, type SigilResult, type SigilTier, type SpawnResult, StateError, type Substrate, type SubstrateProvider, ValidationError, type VerificationResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };
+export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type Capability, type CheckinResult, type ComplianceRegime, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, type MetadataUpdateResult, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegisterOptions, type RegistrationResult, ServerError, type SigilMutableFields, type SigilProtocol, type SigilPurchaseOptions, type SigilResult, type SigilTier, type SpawnResult, StateError, type Substrate, type SubstrateProvider, ValidationError, type VerificationResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register, verifyAnchorHash };

package/dist/index.d.ts

@@ -161,6 +161,20 @@ interface Beat {
     anchor_hash?: string;
 }
 declare function computeBeat(prevHash: string, beatIndex: number, difficulty: number, nonce?: string, anchorHash?: string): Beat;
+/**
+ * Verify an anchor hash locally.
+ * V3 (solana_entropy present): binary-canonical single SHA-256.
+ * V1 legacy (no entropy): string-based hash with difficulty iteration.
+ */
+declare function verifyAnchorHash(anchor: {
+    prev_hash: string;
+    beat_index: number;
+    hash: string;
+    utc: number;
+    epoch: number;
+    difficulty: number;
+    solana_entropy?: string;
+}): boolean;
 /** Result from a check-in submission */
 interface CheckinResult {
     ok: boolean;
@@ -242,9 +256,42 @@ interface RegistrationResult {
         heartbeat?: string;
     };
 }
+/** Options for the register() function */
+interface RegisterOptions {
+    registryUrl?: string;
+    parentHash?: string;
+    parentApiKey?: string;
+    registrationSecret?: string;
+    /** Single-use registration token from POST /register/token or POST /register/email/verify */
+    registrationToken?: string;
+    /** Admin-minted invite token */
+    registrationInvite?: string;
+    /** Hex-encoded 32-byte Ed25519 secret seed (bring-your-own Solana key) */
+    walletSecretKey?: string;
+    /** Wallet model: 'self-custody' (Model A) or 'operator' (Model B). Must be set explicitly to opt in. */
+    walletModel?: 'self-custody' | 'operator';
+    /** Wallet chain: 'solana' (default when wallet is used) or 'ethereum' (D-63) */
+    walletChain?: 'solana' | 'ethereum';
+    /** Wallet address for Ethereum bring-your-own (0x + 40 hex chars) */
+    walletAddress?: string;
+    /** Async function to sign a message with an Ethereum wallet (EIP-191 personal_sign). Returns 0x-prefixed 65-byte hex sig. */
+    walletSignFn?: (message: string) => Promise<string>;
+    /** Operator's Solana wallet address (base58). Required when walletModel='operator'. */
+    operatorWalletAddress?: string;
+    /** Function to sign a message with the operator's Solana wallet. Required when walletModel='operator'. */
+    operatorSignFn?: (message: string) => Promise<string>;
+    /** Optional agent metadata (arbitrary JSON object, max 4KB). Returned in /verify and /status. */
+    metadata?: Record<string, unknown>;
+}
 /**
  * Register a new agent on the Provenonce registry.
  *
+ * With registration token (from /register/token or email verification):
+ *   const creds = await register('my-agent', {
+ *     registryUrl: '...',
+ *     registrationToken: '<token-from-email-verify>',
+ *   });
+ *
  * No wallet (default, single-phase):
  *   const creds = await register('my-agent', { registryUrl: '...' });
  *
@@ -285,28 +332,7 @@ interface RegistrationResult {
  *     parentApiKey: parentCreds.api_key,
  *   });
  */
-declare function register(name: string, options?: {
-    registryUrl?: string;
-    parentHash?: string;
-    parentApiKey?: string;
-    registrationSecret?: string;
-    /** Hex-encoded 32-byte Ed25519 secret seed (bring-your-own Solana key) */
-    walletSecretKey?: string;
-    /** Wallet model: 'self-custody' (Model A) or 'operator' (Model B). Must be set explicitly to opt in. */
-    walletModel?: 'self-custody' | 'operator';
-    /** Wallet chain: 'solana' (default when wallet is used) or 'ethereum' (D-63) */
-    walletChain?: 'solana' | 'ethereum';
-    /** Wallet address for Ethereum bring-your-own (0x + 40 hex chars) */
-    walletAddress?: string;
-    /** Async function to sign a message with an Ethereum wallet (EIP-191 personal_sign). Returns 0x-prefixed 65-byte hex sig. */
-    walletSignFn?: (message: string) => Promise<string>;
-    /** Operator's Solana wallet address (base58). Required when walletModel='operator'. */
-    operatorWalletAddress?: string;
-    /** Function to sign a message with the operator's Solana wallet. Required when walletModel='operator'. */
-    operatorSignFn?: (message: string) => Promise<string>;
-    /** Optional agent metadata (arbitrary JSON object, max 4KB). Returned in /verify and /status. */
-    metadata?: Record<string, unknown>;
-}): Promise<RegistrationResult>;
+declare function register(name: string, options?: RegisterOptions): Promise<RegistrationResult>;
 interface BeatAgentConfig {
     /** API key from registration (pvn_...) */
     apiKey: string;
@@ -330,6 +356,8 @@ interface BeatAgentConfig {
     onStatusChange?: (status: string, details: Record<string, unknown>) => void;
     /** Enable verbose logging */
     verbose?: boolean;
+    /** Verify anchor hash locally before trusting it (default: true). */
+    verifyAnchors?: boolean;
 }
 declare class BeatAgent {
     private config;
@@ -573,4 +601,4 @@ declare class ServerError extends ProvenonceError {
     constructor(message: string, statusCode?: number);
 }
 
-export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type Capability, type CheckinResult, type ComplianceRegime, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, type MetadataUpdateResult, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegistrationResult, ServerError, type SigilMutableFields, type SigilProtocol, type SigilPurchaseOptions, type SigilResult, type SigilTier, type SpawnResult, StateError, type Substrate, type SubstrateProvider, ValidationError, type VerificationResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register };
+export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type Capability, type CheckinResult, type ComplianceRegime, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, type MetadataUpdateResult, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegisterOptions, type RegistrationResult, ServerError, type SigilMutableFields, type SigilProtocol, type SigilPurchaseOptions, type SigilResult, type SigilTier, type SpawnResult, StateError, type Substrate, type SubstrateProvider, ValidationError, type VerificationResult, type WalletInfo, computeBeat, computeBeatsLite, generateWalletKeypair, register, verifyAnchorHash };

package/dist/index.js

@@ -34,7 +34,8 @@ __export(index_exports, {
   computeBeat: () => computeBeat,
   computeBeatsLite: () => computeBeatsLite,
   generateWalletKeypair: () => generateWalletKeypair,
-  register: () => register
+  register: () => register,
+  verifyAnchorHash: () => verifyAnchorHash
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -149,6 +150,54 @@ function computeBeat(prevHash, beatIndex, difficulty, nonce, anchorHash) {
   }
   return { index: beatIndex, hash: current, prev: prevHash, timestamp, nonce, anchor_hash: anchorHash };
 }
+var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function base58DecodeToBuffer(str) {
+  const map = {};
+  for (let i = 0; i < BASE58_ALPHABET.length; i++) map[BASE58_ALPHABET[i]] = i;
+  let bytes = [0];
+  for (let i = 0; i < str.length; i++) {
+    const val = map[str[i]];
+    if (val === void 0) throw new Error("invalid base58 character");
+    let carry = val;
+    for (let j = 0; j < bytes.length; j++) {
+      const x = bytes[j] * 58 + carry;
+      bytes[j] = x & 255;
+      carry = x >> 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 255);
+      carry >>= 8;
+    }
+  }
+  for (let i = 0; i < str.length && str[i] === "1"; i++) bytes.push(0);
+  return Buffer.from(bytes.reverse());
+}
+function u64be(n) {
+  const buf = Buffer.alloc(8);
+  buf.writeUInt32BE(Math.floor(n / 4294967296), 0);
+  buf.writeUInt32BE(n >>> 0, 4);
+  return buf;
+}
+var ANCHOR_DOMAIN_PREFIX = "PROVENONCE_BEATS_V1";
+function verifyAnchorHash(anchor) {
+  if (!anchor || !anchor.hash || !anchor.prev_hash) return false;
+  if (anchor.solana_entropy) {
+    const prefix = Buffer.from(ANCHOR_DOMAIN_PREFIX, "utf8");
+    const prev = Buffer.from(anchor.prev_hash, "hex");
+    const idx = u64be(anchor.beat_index);
+    const entropy = base58DecodeToBuffer(anchor.solana_entropy);
+    const preimage = Buffer.concat([prefix, prev, idx, entropy]);
+    const computed = (0, import_crypto.createHash)("sha256").update(preimage).digest("hex");
+    return computed === anchor.hash;
+  }
+  const nonce = `anchor:${anchor.utc}:${anchor.epoch}`;
+  const seed = `${anchor.prev_hash}:${anchor.beat_index}:${nonce}`;
+  let current = (0, import_crypto.createHash)("sha256").update(seed).digest("hex");
+  for (let i = 0; i < anchor.difficulty; i++) {
+    current = (0, import_crypto.createHash)("sha256").update(current).digest("hex");
+  }
+  return current === anchor.hash;
+}
 var ED25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
 function generateWalletKeypair() {
   const { publicKey, privateKey } = (0, import_crypto.generateKeyPairSync)("ed25519");
@@ -183,6 +232,12 @@ async function register(name, options) {
   if (options?.registrationSecret) {
     headers["x-registration-secret"] = options.registrationSecret;
   }
+  if (options?.registrationToken) {
+    headers["x-registration-token"] = options.registrationToken;
+  }
+  if (options?.registrationInvite) {
+    headers["x-registration-invite"] = options.registrationInvite;
+  }
   if (options?.parentHash) {
     if (options.parentApiKey) {
       headers["Authorization"] = `Bearer ${options.parentApiKey}`;
@@ -432,6 +487,7 @@ var BeatAgent = class {
       onStatusChange: () => {
       },
       verbose: false,
+      verifyAnchors: true,
       ...config
     };
   }
@@ -957,6 +1013,10 @@ var BeatAgent = class {
       clearTimeout(timeout);
       const data = await res.json();
       if (data.anchor) {
+        if (this.config.verifyAnchors && !verifyAnchorHash(data.anchor)) {
+          this.log("\u26A0 Anchor hash verification FAILED \u2014 rejecting untrusted anchor");
+          return;
+        }
         this.globalBeat = data.anchor.beat_index;
         this.globalAnchorHash = data.anchor.hash || "";
         if (data.anchor.difficulty) this.difficulty = data.anchor.difficulty;
@@ -1056,6 +1116,7 @@ function computeBeatsLite(startHash, startIndex, count, difficulty = 1e3, anchor
   computeBeat,
   computeBeatsLite,
   generateWalletKeypair,
-  register
+  register,
+  verifyAnchorHash
 });
 //# sourceMappingURL=index.js.map