@neus/sdk 1.0.10 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+Release notes: [github.com/neus/network/blob/main/CHANGELOG.md](https://github.com/neus/network/blob/main/CHANGELOG.md)

package/README.md

@@ -1,22 +1,50 @@
 # @neus/sdk
 
-Create, check, and reuse NEUS trust receipts from apps.
+Create, check, and reuse NEUS trust receipts from apps and backends. The same package ships the **`neus`** CLI for hosted MCP setup and portable agent import.
 
-NEUS turns signed claims, ownership checks, account links, access rules, and verification results into portable receipts your app can store, display, and check later.
+NEUS makes trust portable across apps, agents, and ecosystems before access, payment, or action.
 
-## Install
+**Status:** [Live and Operational for Production Apps](https://docs.neus.network/platform/status).
+
+## Install (library)
 
 ```bash
 npm install @neus/sdk
 ```
 
-## What you can build
+## Bring Your Own Agent (BYOA) in 30 Seconds
+
+Already have an agent setup? Use the CLI to instantly scan and import your local agent setups—including instructions, memories, rules, skills, and MCP servers from **OpenClaw, Cursor, Claude Code, and Claude Desktop**—straight into the NEUS trust network:
+
+```bash
+npx -y -p @neus/sdk neus import
+```
+
+This automatically prepares your portable NEUS agent manifest, maps your credentials, and secures a reusable trust receipt for your workflows.
+
+*To check what will be imported without writing changes:*
+```bash
+npx -y -p @neus/sdk neus import --dry-run
+```
+
+## Connect editors and assistants
+
+| Topic                             | Link                                                                          |
+| --------------------------------- | ----------------------------------------------------------------------------- |
+| Setup, JSON snippets, and headers | [MCP setup](https://docs.neus.network/mcp/setup)                              |
+| Tools and session order           | [MCP overview](https://docs.neus.network/mcp/overview)                        |
+| Discovery URLs                    | [Discovery and endpoints](https://docs.neus.network/mcp/endpoints)            |
+| Claude Code skill bundle          | [NEUS for Claude Code](https://docs.neus.network/mcp/claude-code-marketplace) |
+
+Prefer `neus setup` over hand-editing config files so every host stays on **`https://mcp.neus.network/mcp`**.
 
-- Issue a proof that a user, wallet, org, app, file, release, profile, or result belongs to someone
-- Store the returned `qHash` as a durable trust receipt ID
-- Check receipts later for access, eligibility, provenance, or display
-- Add proof-gated UX with React widgets
-- Connect IDEs and agents through optional MCP
+## What you can ship
+
+- Hosted verification flows that return a reusable receipt
+- Server checks before access, rewards, payments, or actions
+- React gates with `VerifyGate`
+- Agent identity and scoped delegation
+- MCP setup for assistants and agent tools
 
 ## Fastest path: Hosted Verify
 
@@ -27,19 +55,17 @@ import { getHostedCheckoutUrl } from '@neus/sdk';
 
 const url = getHostedCheckoutUrl({
   verifiers: ['ownership-basic'],
-  returnUrl: 'https://yourapp.com/neus/callback'
+  returnUrl: 'https://yourapp.com/auth/callback'
 });
 
 window.location.assign(url);
 ```
 
-After completion, NEUS redirects back with a `qHash`.
-
-Store that `qHash` in your database next to your user, workspace, project, claim, listing, or record.
+After completion, NEUS redirects back with a receipt ID. Store it with your user or record.
 
-## Create a signed receipt directly
+## Create a receipt directly
 
-Use this when your app already controls the signing flow.
+Use this when your app handles signing. This example is EVM. For non-EVM wallets, pass the provider explicitly and include `chain` as a CAIP-2 value.
 
 ```js
 import { NeusClient } from '@neus/sdk';
@@ -64,7 +90,7 @@ const proof = await client.verify({
       title: 'Source record'
     }
   },
-  wallet: window.ethereum
+  wallet: window.ethereum // EVM provider
 });
 
 console.log(proof.qHash);
@@ -97,7 +123,7 @@ export function Page() {
           }
         }
       }}
-      onVerified={(result) => {
+      onVerified={result => {
         console.log(result.qHash || result.qHashes);
       }}
     />
@@ -126,7 +152,7 @@ if (!result.data?.eligible) {
 }
 ```
 
-Access keys are only for trusted server, IDE, or agent environments. Never ship access keys in browser code.
+Never ship access keys in browser code.
 
 ## Core methods
 
@@ -134,11 +160,11 @@ Access keys are only for trusted server, IDE, or agent environments. Never ship
 | ------------------------------- | ------------------------------------------- |
 | `getHostedCheckoutUrl()`        | Send a user to Hosted Verify                |
 | `client.verify()`               | Create a proof                              |
-| `client.getProof()`             | Fetch a proof by `qHash`                    |
+| `client.getProof()`             | Fetch a receipt by `qHash`                  |
 | `client.pollProofStatus()`      | Wait for async completion                   |
 | `client.gateCheck()`            | Server-side eligibility checks              |
 | `client.checkGate()`            | Local preview against already-loaded proofs |
-| `client.createWalletLinkData()` | Advanced wallet-link payloads               |
+| `client.createWalletLinkData()` | Wallet-link payloads                        |
 
 ## Configuration
 
@@ -153,20 +179,23 @@ const client = new NeusClient({
 `appId` is public attribution for your app.
 `apiKey` / `npk_*` is optional and server-side only.
 
-## Optional MCP setup
-
-Use MCP when you want IDEs, assistants, or agents to inspect receipts, check proof state, or work with NEUS tools.
+## MCP step-by-step
 
 ```bash
-npx -y -p @neus/sdk neus init
+npx -y -p @neus/sdk neus setup
+npx -y -p @neus/sdk neus auth
+npx -y -p @neus/sdk neus doctor --live
 ```
 
-Add account-aware/private access only when needed:
+Re-sign in or rotate credentials:
 
 ```bash
-npx -y -p @neus/sdk neus auth --access-key <npk_...>
+npx -y -p @neus/sdk neus auth
+npx -y -p @neus/sdk neus auth --access-key <npk_...>   # servers and CI only
 ```
 
+Claude Code users can add the optional **`neus-mcp@neus`** skill bundle, then run **`neus setup`** and **`neus auth`**. See [NEUS for Claude Code](https://docs.neus.network/mcp/claude-code-marketplace).
+
 ## Docs
 
 - Quickstart: https://docs.neus.network/quickstart

package/SECURITY.md

@@ -20,7 +20,7 @@ Treat **wallet signatures** and **API keys** as secrets. Do not log them, expose
 
 **`VerifyGate`** create mode also defaults to **private**.
 
-Use public visibility only when you intentionally need proof reuse without owner-authenticated access:
+Use public visibility only when you need proof reuse without owner-authenticated access:
 
 - unlisted public: `privacyLevel: 'public'`, `publicDisplay: false`
 - listed public: `privacyLevel: 'public'`, `publicDisplay: true`

package/cjs/client.cjs

@@ -421,6 +421,11 @@ function normalizeBrowserSignerString(raw) {
   }
   return null;
 }
+function isPlaceholderNeusSignature(signature) {
+  const s = typeof signature === "string" ? signature.trim() : "";
+  if (!s) return true;
+  return /^0x0+$/i.test(s);
+}
 var validateVerifierData = (verifierId, data) => {
   if (!data || typeof data !== "object") {
     return { valid: false, error: "Data object is required" };
@@ -594,6 +599,17 @@ var validateVerifierData = (verifierId, data) => {
       if (data.agentType && !["ai", "bot", "service", "automation", "agent"].includes(data.agentType)) {
         return { valid: false, error: "agentType must be one of: ai, bot, service, automation, agent" };
       }
+      if (data.defaultRuntime && typeof data.defaultRuntime === "object") {
+        if (data.defaultRuntime.provider && typeof data.defaultRuntime.provider === "string" && data.defaultRuntime.provider.length > 64) {
+          return { valid: false, error: "defaultRuntime.provider must be 64 chars or less" };
+        }
+        if (data.defaultRuntime.model && typeof data.defaultRuntime.model === "string" && data.defaultRuntime.model.length > 128) {
+          return { valid: false, error: "defaultRuntime.model must be 128 chars or less" };
+        }
+        if (data.defaultRuntime.mode && typeof data.defaultRuntime.mode === "string" && data.defaultRuntime.mode.length > 64) {
+          return { valid: false, error: "defaultRuntime.mode must be 64 chars or less" };
+        }
+      }
       break;
     case "agent-delegation":
       if (!data.controllerWallet || !validateWalletAddress(data.controllerWallet)) {
@@ -608,6 +624,18 @@ var validateVerifierData = (verifierId, data) => {
       if (data.expiresAt && (typeof data.expiresAt !== "number" || data.expiresAt < Date.now())) {
         return { valid: false, error: "expiresAt must be a future timestamp" };
       }
+      if (data.model && typeof data.model === "string" && data.model.length > 128) {
+        return { valid: false, error: "model must be 128 chars or less" };
+      }
+      if (data.provider && typeof data.provider === "string" && data.provider.length > 64) {
+        return { valid: false, error: "provider must be 64 chars or less" };
+      }
+      if (data.allowedActions && Array.isArray(data.allowedActions) && data.allowedActions.length > 32) {
+        return { valid: false, error: "allowedActions must have 32 items or less" };
+      }
+      if (data.deniedActions && Array.isArray(data.deniedActions) && data.deniedActions.length > 32) {
+        return { valid: false, error: "deniedActions must have 32 items or less" };
+      }
       break;
     case "ai-content-moderation":
       if (!data.content || typeof data.content !== "string") {
@@ -797,7 +825,7 @@ var NeusClient = class {
   }
   _getDefaultBrowserWallet() {
     if (typeof window === "undefined") return null;
-    return window.ethereum || window.solana || window.phantom && window.phantom.solana || null;
+    return window.ethereum || null;
   }
   async _buildPrivateGateAuth({ address, wallet, chain, signatureMethod } = {}) {
     const providerWallet = wallet || this._getDefaultBrowserWallet();
@@ -922,8 +950,57 @@ var NeusClient = class {
       ...label ? { label } : {}
     };
   }
+  async verifyFromApp(params) {
+    if (!params || typeof params !== "object") {
+      throw new ValidationError("verifyFromApp requires a params object");
+    }
+    const {
+      user,
+      verifier = "ownership-basic",
+      content,
+      data: explicitData = null,
+      options = {}
+    } = params;
+    if (!user || typeof user !== "object") {
+      throw new ValidationError("verifyFromApp requires user object");
+    }
+    const walletAddress = user.walletAddress || user.address || user.identity;
+    if (!walletAddress || typeof walletAddress !== "string") {
+      throw new ValidationError("verifyFromApp requires user.walletAddress");
+    }
+    const delegationQHash = this.config.appLinkQHash || typeof process !== "undefined" && process.env && process.env.NEUS_APP_LINK_QHASH || null;
+    let data;
+    if (explicitData && typeof explicitData === "object") {
+      data = { owner: walletAddress, ...explicitData };
+    } else if (content && typeof content === "object") {
+      data = {
+        owner: walletAddress,
+        content: JSON.stringify(content),
+        contentType: typeof content.contentType === "string" ? content.contentType : "application/json",
+        reference: content.reference || { type: "other" }
+      };
+    } else if (typeof content === "string") {
+      data = {
+        owner: walletAddress,
+        content,
+        reference: { type: "other" }
+      };
+    } else {
+      data = { owner: walletAddress, reference: { type: "other" } };
+    }
+    const signedTimestamp = Date.now();
+    const verifierIds = [verifier];
+    return this.verify({
+      verifierIds,
+      data,
+      walletAddress,
+      signedTimestamp,
+      ...delegationQHash ? { delegationQHash } : {},
+      options
+    });
+  }
   async verify(params) {
-    if ((!params?.signature || !params?.walletAddress) && (params?.verifier || params?.content || params?.data)) {
+    if ((isPlaceholderNeusSignature(params?.signature) || !params?.signature || !params?.walletAddress) && (params?.verifier || params?.content || params?.data)) {
       const { content, verifier = "ownership-basic", data: data2 = null, wallet = null, options: options2 = {} } = params;
       if (verifier === "ownership-basic" && !data2 && (!content || typeof content !== "string")) {
         throw new ValidationError("content is required and must be a string (or use data param with owner + reference)");
@@ -976,7 +1053,7 @@ var NeusClient = class {
         }
       } else {
         if (typeof window === "undefined" || !window.ethereum) {
-          throw new ConfigurationError("No Web3 wallet detected. Please install MetaMask or provide wallet parameter.");
+          throw new ConfigurationError("No EVM browser wallet detected. Provide wallet explicitly for non-EVM flows and include chain as a CAIP-2 value.");
         }
         await window.ethereum.request({ method: "eth_requestAccounts" });
         provider = window.ethereum;
@@ -1092,9 +1169,13 @@ var NeusClient = class {
         verificationData = {
           agentId: data2.agentId,
           agentWallet: data2?.agentWallet || walletAddress2,
+          ...data2?.agentChainRef && { agentChainRef: data2.agentChainRef },
+          ...data2?.agentAccountId && { agentAccountId: data2.agentAccountId },
           ...data2?.agentLabel && { agentLabel: data2.agentLabel },
           ...data2?.agentType && { agentType: data2.agentType },
+          ...data2?.avatar && { avatar: data2.avatar },
           ...data2?.description && { description: data2.description },
+          ...data2?.defaultRuntime && { defaultRuntime: data2.defaultRuntime },
           ...data2?.capabilities && { capabilities: data2.capabilities },
           ...data2?.instructions && { instructions: data2.instructions },
           ...data2?.skills && { skills: data2.skills },
@@ -1106,7 +1187,11 @@ var NeusClient = class {
         }
         verificationData = {
           controllerWallet: data2?.controllerWallet || walletAddress2,
+          ...data2?.controllerChainRef && { controllerChainRef: data2.controllerChainRef },
           agentWallet: data2.agentWallet,
+          ...data2?.agentChainRef && { agentChainRef: data2.agentChainRef },
+          ...data2?.controllerAccountId && { controllerAccountId: data2.controllerAccountId },
+          ...data2?.agentAccountId && { agentAccountId: data2.agentAccountId },
           ...data2?.agentId && { agentId: data2.agentId },
           ...data2?.scope && { scope: data2.scope },
           ...data2?.permissions && { permissions: data2.permissions },
@@ -1115,7 +1200,13 @@ var NeusClient = class {
           ...data2?.receiptDisclosure && { receiptDisclosure: data2.receiptDisclosure },
           ...data2?.expiresAt && { expiresAt: data2.expiresAt },
           ...data2?.instructions && { instructions: data2.instructions },
-          ...data2?.skills && { skills: data2.skills }
+          ...data2?.skills && { skills: data2.skills },
+          ...data2?.model && { model: data2.model },
+          ...data2?.provider && { provider: data2.provider },
+          ...data2?.runtimePolicy && { runtimePolicy: data2.runtimePolicy },
+          ...data2?.allowedActions && { allowedActions: data2.allowedActions },
+          ...data2?.deniedActions && { deniedActions: data2.deniedActions },
+          ...data2?.approvalPolicy && { approvalPolicy: data2.approvalPolicy }
         };
       } else if (verifier === "ai-content-moderation") {
         if (!data2?.content) {
@@ -1264,13 +1355,15 @@ ${bytes.length}`;
       verifierIds,
       data,
       walletAddress,
-      signature,
+      signature: rawSignature,
       signedTimestamp,
       chainId,
       chain,
       signatureMethod,
+      delegationQHash,
       options = {}
     } = params;
+    const signature = isPlaceholderNeusSignature(rawSignature) ? void 0 : rawSignature;
     const resolvedChainId = chainId || (chain ? null : NEUS_CONSTANTS.HUB_CHAIN_ID);
     const normalizeVerifierId = (id) => {
       if (typeof id !== "string") return id;
@@ -1287,8 +1380,11 @@ ${bytes.length}`;
     if (!walletAddress || typeof walletAddress !== "string") {
       throw new ValidationError("walletAddress is required");
     }
-    if (!signature) {
-      throw new ValidationError("signature is required");
+    const hasAppAttribution = typeof this.config.appId === "string" && this.config.appId.trim().length > 0;
+    if (!signature && !delegationQHash && !hasAppAttribution) {
+      throw new ValidationError(
+        "signature, delegationQHash, or NeusClient config appId (sent as X-Neus-App) is required"
+      );
     }
     if (!signedTimestamp || typeof signedTimestamp !== "number") {
       throw new ValidationError("signedTimestamp is required");
@@ -1314,11 +1410,12 @@ ${bytes.length}`;
       verifierIds: normalizedVerifierIds,
       data,
       walletAddress,
-      signature,
+      ...signature ? { signature } : {},
       signedTimestamp,
       ...resolvedChainId !== null && { chainId: resolvedChainId },
       ...chain && { chain },
       ...signatureMethod && { signatureMethod },
+      ...delegationQHash && { delegationQHash },
       options: optionsPayload
     };
     const response = await this._makeRequest("POST", "/api/v1/verification", requestData);
@@ -1328,19 +1425,17 @@ ${bytes.length}`;
     return this._formatResponse(response);
   }
   async getProof(qHash) {
-    const resolvedQHash = qHash;
-    if (!resolvedQHash || typeof resolvedQHash !== "string") {
+    if (!qHash || typeof qHash !== "string") {
       throw new ValidationError("qHash is required");
     }
-    const response = await this._makeRequest("GET", `/api/v1/proofs/${resolvedQHash}`);
+    const response = await this._makeRequest("GET", `/api/v1/proofs/${qHash}`);
     if (!response.success) {
       throw new ApiError(`Failed to get proof: ${response.error?.message || "Unknown error"}`, response.error);
     }
     return this._formatResponse(response);
   }
   async getPrivateProof(qHash, wallet = null) {
-    const resolvedQHash = qHash;
-    if (!resolvedQHash || typeof resolvedQHash !== "string") {
+    if (!qHash || typeof qHash !== "string") {
       throw new ValidationError("qHash is required");
     }
     const isPreSignedAuth = wallet && typeof wallet === "object" && typeof wallet.walletAddress === "string" && typeof wallet.signature === "string" && typeof wallet.signedTimestamp === "number";
@@ -1353,7 +1448,7 @@ ${bytes.length}`;
         ...typeof auth.chain === "string" && auth.chain.trim() ? { "x-chain": auth.chain.trim() } : {},
         ...typeof auth.signatureMethod === "string" && auth.signatureMethod.trim() ? { "x-signature-method": auth.signatureMethod.trim() } : {}
       };
-      const response2 = await this._makeRequest("GET", `/api/v1/proofs/${resolvedQHash}`, null, headers);
+      const response2 = await this._makeRequest("GET", `/api/v1/proofs/${qHash}`, null, headers);
       if (!response2.success) {
         throw new ApiError(
           `Failed to access private proof: ${response2.error?.message || "Unauthorized"}`,
@@ -1374,7 +1469,7 @@ ${bytes.length}`;
     const message = constructVerificationMessage({
       walletAddress,
       signedTimestamp,
-      data: { action: "access_private_proof", qHash: resolvedQHash },
+      data: { action: "access_private_proof", qHash },
       verifierIds: ["ownership-basic"],
       ...signerIsEvm ? { chainId: this._getHubChainId() } : { chain }
     });
@@ -1392,7 +1487,7 @@ ${bytes.length}`;
       }
       throw new ValidationError(`Failed to sign message: ${error.message}`);
     }
-    const response = await this._makeRequest("GET", `/api/v1/proofs/${resolvedQHash}`, null, {
+    const response = await this._makeRequest("GET", `/api/v1/proofs/${qHash}`, null, {
       "x-wallet-address": walletAddress,
       "x-signature": signature,
       "x-signed-timestamp": signedTimestamp.toString(),
@@ -1430,20 +1525,19 @@ ${bytes.length}`;
     };
   }
   async pollProofStatus(qHash, options = {}) {
-    const resolvedQHash = qHash;
     const {
       interval = 5e3,
       timeout = 12e4,
       onProgress
     } = options;
-    if (!resolvedQHash || typeof resolvedQHash !== "string") {
+    if (!qHash || typeof qHash !== "string") {
       throw new ValidationError("qHash is required");
     }
     const startTime = Date.now();
     let consecutiveRateLimits = 0;
     while (Date.now() - startTime < timeout) {
       try {
-        const status = await this.getProof(resolvedQHash);
+        const status = await this.getProof(qHash);
         consecutiveRateLimits = 0;
         if (onProgress && typeof onProgress === "function") {
           onProgress(status.data || status);
@@ -1486,8 +1580,7 @@ ${bytes.length}`;
     }
   }
   async revokeOwnProof(qHash, wallet) {
-    const resolvedQHash = qHash;
-    if (!resolvedQHash || typeof resolvedQHash !== "string") {
+    if (!qHash || typeof qHash !== "string") {
       throw new ValidationError("qHash is required");
     }
     const providerWallet = wallet || this._getDefaultBrowserWallet();
@@ -1502,7 +1595,7 @@ ${bytes.length}`;
     const message = constructVerificationMessage({
       walletAddress: address,
       signedTimestamp,
-      data: { action: "revoke_proof", qHash: resolvedQHash },
+      data: { action: "revoke_proof", qHash },
       verifierIds: ["ownership-basic"],
       ...signerIsEvm ? { chainId: this._getHubChainId() } : { chain }
     });
@@ -1520,7 +1613,7 @@ ${bytes.length}`;
       }
       throw new ValidationError(`Failed to sign revocation: ${error.message}`);
     }
-    const res = await this._makeRequest("POST", `/api/v1/proofs/revoke-self/${resolvedQHash}`, {
+    const res = await this._makeRequest("POST", `/api/v1/proofs/revoke-self/${qHash}`, {
       walletAddress: address,
       signature,
       signedTimestamp,
@@ -1927,10 +2020,7 @@ ${bytes.length}`;
     }
   }
   _formatResponse(response) {
-    const qHash = response?.data?.qHash || response?.qHash || response?.data?.resource?.qHash || response?.data?.proofId || // Legacy input compatibility only. Do not expose or store proofId.
-    response?.proofId || // Legacy input compatibility only. Do not expose or store proofId.
-    response?.data?.resource?.proofId || // Legacy input compatibility only. Do not expose or store proofId.
-    response?.data?.id;
+    const qHash = response?.data?.qHash || response?.qHash || response?.data?.resource?.qHash || response?.data?.id;
     const status = response?.data?.status || response?.status || response?.data?.resource?.status || (response?.success ? "completed" : "unknown");
     return {
       success: response.success,