@provenonce/sdk 0.9.0 → 0.10.0

package/README.md

@@ -169,4 +169,4 @@ Python examples use the REST API directly — no Python SDK needed. See [`exampl
 - [Live prototype](https://provenonce.io)
 - [npm package](https://www.npmjs.com/package/@provenonce/sdk)
 - [API docs](https://provenonce.dev)
-- [Whitepaper](https://provenonce.dev/whitepaper)
+- [Whitepaper](https://provenonce.dev/concepts/architecture)

package/dist/index.d.mts

@@ -28,6 +28,18 @@
  */
 /** SIGIL identity class — determines tier pricing and heartbeat volume caps */
 type IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator';
+/** SIGIL trust governance tier — orthogonal to identity_class (fee axis) */
+type SigilTier = 'sov' | 'org' | 'ind' | 'eph' | 'sbx';
+/** Substrate — what the agent runs on */
+type Substrate = 'frontier' | 'open' | 'local' | 'symbolic' | 'hybrid' | 'human';
+/** Substrate provider */
+type SubstrateProvider = 'anthropic' | 'openai' | 'google' | 'meta' | 'mistral' | 'xai' | 'cohere' | 'deepseek' | 'custom';
+/** Capability — what the agent primarily does */
+type Capability = 'analyst' | 'executor' | 'orchestrator' | 'guardian' | 'retriever' | 'renderer' | 'witness';
+/** Protocol — how to reach the agent */
+type SigilProtocol = 'http' | 'grpc' | 'websocket' | 'mcp' | 'a2a' | 'custom';
+/** Compliance regime */
+type ComplianceRegime = 'gdpr' | 'pdpa' | 'hipaa' | 'sox' | 'aisi' | 'none' | 'custom';
 /**
  * Ed25519-signed lineage proof — portable, offline-verifiable credential.
  * Also known as the agent's "passport" — a cryptographic proof of identity
@@ -47,10 +59,48 @@ interface LineageProof {
 }
 /** Passport = LineageProof. The agent's portable, offline-verifiable credential. */
 type Passport = LineageProof;
+/** Options for purchasing a SIGIL with full namespace */
+interface SigilPurchaseOptions {
+    identity_class: IdentityClass;
+    principal: string;
+    tier: SigilTier;
+    name?: string;
+    payment_tx: string;
+    substrate?: Substrate;
+    substrate_provider?: SubstrateProvider;
+    substrate_model?: string;
+    capability?: Capability;
+    capability_scope?: string;
+    tools?: string[];
+    modality_input?: string[];
+    modality_output?: string[];
+    protocol?: SigilProtocol;
+    endpoint?: string;
+    compliance_regime?: ComplianceRegime;
+}
+/** Mutable SIGIL metadata fields for PATCH updates */
+interface SigilMutableFields {
+    substrate?: Substrate;
+    substrate_provider?: SubstrateProvider;
+    substrate_model?: string;
+    capability?: Capability;
+    capability_scope?: string;
+    generation_trigger?: string;
+    tools?: string[];
+    modality_input?: string[];
+    modality_output?: string[];
+    protocol?: SigilProtocol;
+    endpoint?: string;
+    compliance_regime?: ComplianceRegime;
+}
 /** Result from purchasing a SIGIL (Structured Identity Governance and Intelligent Lookup) */
 interface SigilResult {
     ok: boolean;
     sigil?: {
+        sigil: string;
+        sigil_name: string;
+        principal: string;
+        tier: SigilTier;
         identity_class: IdentityClass;
         issued_at_beat: number;
         birth_tx: string | null;
@@ -64,6 +114,29 @@ interface SigilResult {
     };
     error?: string;
 }
+/** Result from updating mutable SIGIL metadata */
+interface MetadataUpdateResult {
+    ok: boolean;
+    sigil?: string;
+    generation?: number;
+    updated_fields?: string[];
+    error?: string;
+}
+/** Result from offline lineage proof verification */
+interface VerificationResult {
+    /** Overall validity: signature is valid AND not expired */
+    valid: boolean;
+    /** Ed25519 signature verification passed */
+    signatureValid: boolean;
+    /** Proof has passed its valid_until timestamp */
+    expired: boolean;
+    /** The beat index of the agent's last heartbeat */
+    lastHeartbeatBeat: number;
+    /** Beats elapsed since last heartbeat (null if currentBeat not provided) */
+    beatsSinceHeartbeat: number | null;
+    /** Human-readable warning if proof is expired or stale */
+    warning?: string;
+}
 /** Result from a paid heartbeat */
 interface HeartbeatResult {
     ok: boolean;
@@ -332,10 +405,20 @@ declare class BeatAgent {
      * SIGILs gate heartbeating, lineage proofs, and offline verification.
      * One-time purchase — cannot be re-purchased.
      *
-     * @param identityClass - 'narrow_task' (0.05 SOL), 'autonomous' (0.15 SOL), or 'orchestrator' (0.35 SOL)
-     * @param paymentTx - Solana transaction signature proving payment. Use 'devnet-skip' on devnet.
+     * @param options - SIGIL purchase options (identity_class, principal, tier, name, payment_tx, + optional metadata)
+     *
+     * Legacy signature (deprecated):
+     * @param identityClass - 'narrow_task' | 'autonomous' | 'orchestrator'
+     * @param paymentTx - Solana transaction signature or 'devnet-skip'
+     */
+    purchaseSigil(optionsOrClass: SigilPurchaseOptions | IdentityClass, paymentTx?: string): Promise<SigilResult>;
+    /**
+     * Update mutable SIGIL metadata fields.
+     * Requires a SIGIL. Cannot modify immutable fields.
+     *
+     * @param fields - Subset of mutable SIGIL fields to update
      */
-    purchaseSigil(identityClass: IdentityClass, paymentTx: string): Promise<SigilResult>;
+    updateMetadata(fields: Partial<SigilMutableFields>): Promise<MetadataUpdateResult>;
     /**
      * Send a paid heartbeat to the registry.
      * Requires a SIGIL. Returns a signed lineage proof.
@@ -371,10 +454,14 @@ declare class BeatAgent {
      * Verify a lineage proof 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.
+     *
      * @param proof - The LineageProof 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: LineageProof, authorityPubKeyHex: string): boolean;
+    static verifyProofLocally(proof: LineageProof, authorityPubKeyHex: string, currentBeat?: number): VerificationResult;
     /**
      * Get this agent's full beat status from the registry.
      */
@@ -486,4 +573,4 @@ declare class ServerError extends ProvenonceError {
     constructor(message: string, statusCode?: number);
 }
 
-export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegistrationResult, ServerError, type SigilResult, type SpawnResult, StateError, ValidationError, 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 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 };

package/dist/index.d.ts

@@ -28,6 +28,18 @@
  */
 /** SIGIL identity class — determines tier pricing and heartbeat volume caps */
 type IdentityClass = 'narrow_task' | 'autonomous' | 'orchestrator';
+/** SIGIL trust governance tier — orthogonal to identity_class (fee axis) */
+type SigilTier = 'sov' | 'org' | 'ind' | 'eph' | 'sbx';
+/** Substrate — what the agent runs on */
+type Substrate = 'frontier' | 'open' | 'local' | 'symbolic' | 'hybrid' | 'human';
+/** Substrate provider */
+type SubstrateProvider = 'anthropic' | 'openai' | 'google' | 'meta' | 'mistral' | 'xai' | 'cohere' | 'deepseek' | 'custom';
+/** Capability — what the agent primarily does */
+type Capability = 'analyst' | 'executor' | 'orchestrator' | 'guardian' | 'retriever' | 'renderer' | 'witness';
+/** Protocol — how to reach the agent */
+type SigilProtocol = 'http' | 'grpc' | 'websocket' | 'mcp' | 'a2a' | 'custom';
+/** Compliance regime */
+type ComplianceRegime = 'gdpr' | 'pdpa' | 'hipaa' | 'sox' | 'aisi' | 'none' | 'custom';
 /**
  * Ed25519-signed lineage proof — portable, offline-verifiable credential.
  * Also known as the agent's "passport" — a cryptographic proof of identity
@@ -47,10 +59,48 @@ interface LineageProof {
 }
 /** Passport = LineageProof. The agent's portable, offline-verifiable credential. */
 type Passport = LineageProof;
+/** Options for purchasing a SIGIL with full namespace */
+interface SigilPurchaseOptions {
+    identity_class: IdentityClass;
+    principal: string;
+    tier: SigilTier;
+    name?: string;
+    payment_tx: string;
+    substrate?: Substrate;
+    substrate_provider?: SubstrateProvider;
+    substrate_model?: string;
+    capability?: Capability;
+    capability_scope?: string;
+    tools?: string[];
+    modality_input?: string[];
+    modality_output?: string[];
+    protocol?: SigilProtocol;
+    endpoint?: string;
+    compliance_regime?: ComplianceRegime;
+}
+/** Mutable SIGIL metadata fields for PATCH updates */
+interface SigilMutableFields {
+    substrate?: Substrate;
+    substrate_provider?: SubstrateProvider;
+    substrate_model?: string;
+    capability?: Capability;
+    capability_scope?: string;
+    generation_trigger?: string;
+    tools?: string[];
+    modality_input?: string[];
+    modality_output?: string[];
+    protocol?: SigilProtocol;
+    endpoint?: string;
+    compliance_regime?: ComplianceRegime;
+}
 /** Result from purchasing a SIGIL (Structured Identity Governance and Intelligent Lookup) */
 interface SigilResult {
     ok: boolean;
     sigil?: {
+        sigil: string;
+        sigil_name: string;
+        principal: string;
+        tier: SigilTier;
         identity_class: IdentityClass;
         issued_at_beat: number;
         birth_tx: string | null;
@@ -64,6 +114,29 @@ interface SigilResult {
     };
     error?: string;
 }
+/** Result from updating mutable SIGIL metadata */
+interface MetadataUpdateResult {
+    ok: boolean;
+    sigil?: string;
+    generation?: number;
+    updated_fields?: string[];
+    error?: string;
+}
+/** Result from offline lineage proof verification */
+interface VerificationResult {
+    /** Overall validity: signature is valid AND not expired */
+    valid: boolean;
+    /** Ed25519 signature verification passed */
+    signatureValid: boolean;
+    /** Proof has passed its valid_until timestamp */
+    expired: boolean;
+    /** The beat index of the agent's last heartbeat */
+    lastHeartbeatBeat: number;
+    /** Beats elapsed since last heartbeat (null if currentBeat not provided) */
+    beatsSinceHeartbeat: number | null;
+    /** Human-readable warning if proof is expired or stale */
+    warning?: string;
+}
 /** Result from a paid heartbeat */
 interface HeartbeatResult {
     ok: boolean;
@@ -332,10 +405,20 @@ declare class BeatAgent {
      * SIGILs gate heartbeating, lineage proofs, and offline verification.
      * One-time purchase — cannot be re-purchased.
      *
-     * @param identityClass - 'narrow_task' (0.05 SOL), 'autonomous' (0.15 SOL), or 'orchestrator' (0.35 SOL)
-     * @param paymentTx - Solana transaction signature proving payment. Use 'devnet-skip' on devnet.
+     * @param options - SIGIL purchase options (identity_class, principal, tier, name, payment_tx, + optional metadata)
+     *
+     * Legacy signature (deprecated):
+     * @param identityClass - 'narrow_task' | 'autonomous' | 'orchestrator'
+     * @param paymentTx - Solana transaction signature or 'devnet-skip'
+     */
+    purchaseSigil(optionsOrClass: SigilPurchaseOptions | IdentityClass, paymentTx?: string): Promise<SigilResult>;
+    /**
+     * Update mutable SIGIL metadata fields.
+     * Requires a SIGIL. Cannot modify immutable fields.
+     *
+     * @param fields - Subset of mutable SIGIL fields to update
      */
-    purchaseSigil(identityClass: IdentityClass, paymentTx: string): Promise<SigilResult>;
+    updateMetadata(fields: Partial<SigilMutableFields>): Promise<MetadataUpdateResult>;
     /**
      * Send a paid heartbeat to the registry.
      * Requires a SIGIL. Returns a signed lineage proof.
@@ -371,10 +454,14 @@ declare class BeatAgent {
      * Verify a lineage proof 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.
+     *
      * @param proof - The LineageProof 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: LineageProof, authorityPubKeyHex: string): boolean;
+    static verifyProofLocally(proof: LineageProof, authorityPubKeyHex: string, currentBeat?: number): VerificationResult;
     /**
      * Get this agent's full beat status from the registry.
      */
@@ -486,4 +573,4 @@ declare class ServerError extends ProvenonceError {
     constructor(message: string, statusCode?: number);
 }
 
-export { type AgentStatus, AuthError, type Beat, BeatAgent, type BeatAgentConfig, type CheckinResult, ErrorCode, FrozenError, type HeartbeatResult, type IdentityClass, type LineageProof, NetworkError, NotFoundError, type Passport, ProvenonceError, RateLimitError, type RegistrationResult, ServerError, type SigilResult, type SpawnResult, StateError, ValidationError, 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 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 };

package/dist/index.js

@@ -723,26 +723,51 @@ var BeatAgent = class {
    * SIGILs gate heartbeating, lineage proofs, and offline verification.
    * One-time purchase — cannot be re-purchased.
    *
-   * @param identityClass - 'narrow_task' (0.05 SOL), 'autonomous' (0.15 SOL), or 'orchestrator' (0.35 SOL)
-   * @param paymentTx - Solana transaction signature proving payment. Use 'devnet-skip' on devnet.
+   * @param options - SIGIL purchase options (identity_class, principal, tier, name, payment_tx, + optional metadata)
+   *
+   * Legacy signature (deprecated):
+   * @param identityClass - 'narrow_task' | 'autonomous' | 'orchestrator'
+   * @param paymentTx - Solana transaction signature or 'devnet-skip'
    */
-  async purchaseSigil(identityClass, paymentTx) {
-    if (!identityClass || !["narrow_task", "autonomous", "orchestrator"].includes(identityClass)) {
-      throw new ValidationError("identityClass must be narrow_task, autonomous, or orchestrator");
-    }
-    if (!paymentTx || typeof paymentTx !== "string") {
-      throw new ValidationError('paymentTx is required (Solana transaction signature or "devnet-skip")');
+  async purchaseSigil(optionsOrClass, paymentTx) {
+    let body;
+    if (typeof optionsOrClass === "string") {
+      if (!optionsOrClass || !["narrow_task", "autonomous", "orchestrator"].includes(optionsOrClass)) {
+        throw new ValidationError("identityClass must be narrow_task, autonomous, or orchestrator");
+      }
+      if (!paymentTx || typeof paymentTx !== "string") {
+        throw new ValidationError('paymentTx is required (Solana transaction signature or "devnet-skip")');
+      }
+      body = {
+        identity_class: optionsOrClass,
+        payment_tx: paymentTx
+        // Legacy calls without principal/tier — server will require these now
+        // Callers must migrate to the options object form
+      };
+    } else {
+      const opts = optionsOrClass;
+      if (!opts.identity_class || !["narrow_task", "autonomous", "orchestrator"].includes(opts.identity_class)) {
+        throw new ValidationError("identity_class must be narrow_task, autonomous, or orchestrator");
+      }
+      if (!opts.principal || typeof opts.principal !== "string") {
+        throw new ValidationError("principal is required");
+      }
+      if (!opts.tier || !["sov", "org", "ind", "eph", "sbx"].includes(opts.tier)) {
+        throw new ValidationError("tier must be one of: sov, org, ind, eph, sbx");
+      }
+      if (!opts.payment_tx || typeof opts.payment_tx !== "string") {
+        throw new ValidationError("payment_tx is required");
+      }
+      body = { ...opts };
     }
     try {
-      const res = await this.api("POST", "/api/v1/sigil", {
-        identity_class: identityClass,
-        payment_tx: paymentTx
-      });
+      const res = await this.api("POST", "/api/v1/sigil", body);
       if (res.lineage_proof) {
         this.cachedProof = res.lineage_proof;
       }
-      this.log(`SIGIL purchased: ${identityClass}`);
-      this.config.onStatusChange("sigil_issued", { identity_class: identityClass });
+      const sigilStr = res.sigil?.sigil || res.sigil?.identity_class || "";
+      this.log(`SIGIL purchased: ${sigilStr}`);
+      this.config.onStatusChange("sigil_issued", { sigil: sigilStr });
       return {
         ok: true,
         sigil: res.sigil,
@@ -754,6 +779,30 @@ var BeatAgent = class {
       return { ok: false, error: err.message };
     }
   }
+  /**
+   * Update mutable SIGIL metadata fields.
+   * Requires a SIGIL. Cannot modify immutable fields.
+   *
+   * @param fields - Subset of mutable SIGIL fields to update
+   */
+  async updateMetadata(fields) {
+    if (!fields || Object.keys(fields).length === 0) {
+      throw new ValidationError("At least one metadata field is required");
+    }
+    try {
+      const res = await this.api("PATCH", "/api/v1/agent/metadata", fields);
+      this.log(`Metadata updated: ${res.updated_fields?.join(", ") || "unknown"}`);
+      return {
+        ok: true,
+        sigil: res.sigil,
+        generation: res.generation,
+        updated_fields: res.updated_fields
+      };
+    } catch (err) {
+      this.config.onError(err, "updateMetadata");
+      return { ok: false, error: err.message };
+    }
+  }
   /**
    * Send a paid heartbeat to the registry.
    * Requires a SIGIL. Returns a signed lineage proof.
@@ -829,14 +878,18 @@ var BeatAgent = class {
    * Verify a lineage proof 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.
+   *
    * @param proof - The LineageProof 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) {
+  static verifyProofLocally(proof, authorityPubKeyHex, currentBeat) {
+    const now = Date.now();
+    const expired = now > proof.valid_until;
+    let signatureValid = false;
     try {
-      if (Date.now() > proof.valid_until) {
-        return false;
-      }
       const canonical = JSON.stringify({
         agent_hash: proof.agent_hash,
         agent_public_key: proof.agent_public_key,
@@ -849,15 +902,25 @@ var BeatAgent = class {
         valid_until: proof.valid_until
       });
       const pubBytes = Buffer.from(authorityPubKeyHex, "hex");
-      if (pubBytes.length !== 32) return false;
-      const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
-      const pubKeyDer = Buffer.concat([ED25519_SPKI_PREFIX, pubBytes]);
-      const keyObject = (0, import_crypto.createPublicKey)({ key: pubKeyDer, format: "der", type: "spki" });
-      const sigBuffer = Buffer.from(proof.provenonce_signature, "hex");
-      return (0, import_crypto.verify)(null, Buffer.from(canonical), keyObject, sigBuffer);
+      if (pubBytes.length === 32) {
+        const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+        const pubKeyDer = Buffer.concat([ED25519_SPKI_PREFIX, pubBytes]);
+        const keyObject = (0, import_crypto.createPublicKey)({ key: pubKeyDer, format: "der", type: "spki" });
+        const sigBuffer = Buffer.from(proof.provenonce_signature, "hex");
+        signatureValid = (0, import_crypto.verify)(null, Buffer.from(canonical), keyObject, sigBuffer);
+      }
     } catch {
-      return false;
+      signatureValid = false;
+    }
+    const valid = signatureValid && !expired;
+    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.";
+    } 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 };
   }
   // ── STATUS ──
   /**