@neus/sdk 1.0.9 → 1.0.12

package/README.md

@@ -1,104 +1,208 @@
 # @neus/sdk
 
-[![npm](https://img.shields.io/npm/v/%40neus%2Fsdk?logo=npm&label=%40neus%2Fsdk&color=98C0EF)](https://www.npmjs.com/package/@neus/sdk)
+Create, check, and reuse NEUS trust receipts from apps and backends. The same package ships the **`neus`** CLI for wiring **hosted NEUS MCP** into editors and agents.
 
-**Portable trust, shipped as APIs and widgets.** For **Web2-style apps**, prefer **Hosted Verify** (`getHostedCheckoutUrl` or `VerifyGate`) so users never touch `window.ethereum` in your UI. Use **`npk_*` + `gateCheck`** on your server for allow/deny. Store **`qHash`**, then reuse it.
+NEUS makes trust portable across the internet so people, apps, and AI agents can prove what is real before access, payout, or execution.
 
-## Install
+## Install (library)
 
 ```bash
 npm install @neus/sdk
 ```
 
-## Minimal working example (hosted, no wallet in your page)
+## Connect editors and assistants (MCP)
 
-```javascript
-import { getHostedCheckoutUrl } from '@neus/sdk';
+Use one command to merge NEUS into Cursor, VS Code, and Claude Code when those tools are detected. No separate NEUS editor extension is required.
 
-window.location.href = getHostedCheckoutUrl({
-  verifiers: ['ownership-basic'],
-  returnUrl: 'https://myapp.com/neus/callback',
-});
+```bash
+npx -y -p @neus/sdk neus setup
 ```
 
-After Hosted Verify, NEUS redirects to `returnUrl` with **`qHash`** in the query string — persist it on your server next to your user id.
+Add your NEUS Profile access key in the same step (needed for account-aware tools such as `neus_me`):
 
-## Server check (use your access key, not in the browser)
+```bash
+npx -y -p @neus/sdk neus setup --access-key <npk_...>
+```
 
-```javascript
-import { NeusClient } from '@neus/sdk';
+Check configuration and connectivity:
 
-const client = new NeusClient({ appId: 'your-app-id' });
+```bash
+npx -y -p @neus/sdk neus doctor
+```
 
-const check = await client.gateCheck({
-  address: '0x...',
-  verifierIds: ['ownership-basic'],
+Create keys under **Profile → Account → Access keys** on [neus.network](https://neus.network/profile?tab=account). Never put access keys in browser bundles or public repos.
+
+| 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) |
+| Optional Claude Code plugin + skill | [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`**.
+
+## What you can build
+
+- 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
+
+## Fastest path: Hosted Verify
+
+Use Hosted Verify when you want NEUS to handle the signing/verification flow outside your app UI.
+
+```js
+import { getHostedCheckoutUrl } from '@neus/sdk';
+
+const url = getHostedCheckoutUrl({
+  verifiers: ['ownership-basic'],
+  returnUrl: 'https://yourapp.com/auth/callback'
 });
+
+window.location.assign(url);
 ```
 
-## Advanced: sign inside your app
+After completion, NEUS redirects back with a `qHash`.
+
+Store that `qHash` with your user record.
 
-Only when you intentionally need a browser wallet:
+## Create a signed receipt directly
 
-```javascript
+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; see the CAIP-380 standards page in the docs.
+
+```js
 import { NeusClient } from '@neus/sdk';
 
-const client = new NeusClient({ appId: 'your-app-id' });
+const client = new NeusClient({
+  appId: 'your-app-id'
+});
 
 const proof = await client.verify({
   verifier: 'ownership-basic',
-  content: 'Hello NEUS',
-  wallet: window.ethereum,
+  data: {
+    owner: '0x...',
+    contentType: 'application/json',
+    content: JSON.stringify({
+      title: 'Verified claim',
+      type: 'project-update',
+      summary: 'Public summary of what is being proven.'
+    }),
+    reference: {
+      type: 'url',
+      id: 'https://example.com/source',
+      title: 'Source record'
+    }
+  },
+  wallet: window.ethereum // EVM provider
 });
-const qHash = proof.qHash;
-```
-
-## Core methods
 
-| Method | Purpose |
-| --- | --- |
-| `client.verify()` | Create proof |
-| `client.getProof()` | Fetch by `qHash` |
-| `client.pollProofStatus()` | Wait for async completion |
-| `client.gateCheck()` | **Server eligibility** (use for real gates) |
-| `client.checkGate()` | Local preview only |
-| `getHostedCheckoutUrl()` | Hosted verify URL |
-| `client.createWalletLinkData()` | Build advanced direct wallet-link payload |
+console.log(proof.qHash);
+console.log(proof.proofUrl);
+```
 
-## VerifyGate (React)
+## React widget
 
-Defaults: private create (`privacyLevel: 'private'`, `publicDisplay: false`). Set `proofOptions` only when you intentionally need public visibility.
+Use `VerifyGate` when you want a drop-in verification flow in React.
 
 ```jsx
 import { VerifyGate } from '@neus/sdk/widgets';
 
-<VerifyGate appId="your-app-id" requiredVerifiers={['ownership-basic']}>
-  <ProtectedContent />
-</VerifyGate>
+export function Page() {
+  return (
+    <VerifyGate
+      appId="your-app-id"
+      requiredVerifiers={['ownership-basic']}
+      verifierData={{
+        'ownership-basic': {
+          owner: '0x...',
+          contentType: 'application/json',
+          content: JSON.stringify({
+            title: 'Verified claim',
+            summary: 'Public summary of what is being proven.'
+          }),
+          reference: {
+            type: 'url',
+            id: 'https://example.com/source'
+          }
+        }
+      }}
+      onVerified={(result) => {
+        console.log(result.qHash || result.qHashes);
+      }}
+    />
+  );
+}
+```
+
+## Check receipts
+
+Use `gateCheck` from trusted server code when you need allow/deny or eligibility checks.
+
+```js
+import { NeusClient } from '@neus/sdk';
+
+const client = new NeusClient({
+  appId: 'your-app-id'
+});
+
+const result = await client.gateCheck({
+  address: '0x...',
+  verifierIds: ['ownership-basic']
+});
+
+if (!result.data?.eligible) {
+  throw new Error('Access denied');
+}
 ```
 
-[Widgets README](./widgets/README.md)
+Never ship access keys in browser code.
+
+## Core methods
+
+| Method                          | Use it for                                  |
+| ------------------------------- | ------------------------------------------- |
+| `getHostedCheckoutUrl()`        | Send a user to Hosted Verify                |
+| `client.verify()`               | Create a proof                              |
+| `client.getProof()`             | Fetch a proof 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               |
 
-## Config
+## Configuration
 
-```javascript
+```js
 const client = new NeusClient({
   apiUrl: 'https://api.neus.network',
-  appId: 'my-app',
-  timeout: 30000,
+  appId: 'your-app-id',
+  timeout: 30000
 });
 ```
 
-## Docs
+`appId` is public attribution for your app.
+`apiKey` / `npk_*` is optional and server-side only.
+
+## MCP: step-by-step (alternative to `setup`)
+
+```bash
+npx -y -p @neus/sdk neus init
+```
 
-- [Quickstart](https://docs.neus.network/quickstart)
-- [Examples](https://docs.neus.network/examples) — start with the [trust receipts showcase](https://github.com/neus/network/tree/main/examples/trust-receipts-showcase) locally; [live demo](https://neus.network/demo) on the product site
-- [SDK](https://docs.neus.network/sdks/javascript)
-- [MCP](https://docs.neus.network/mcp/overview) for IDEs and assistants
-- [Widgets](https://docs.neus.network/widgets/overview)
-- [API](https://docs.neus.network/api/overview)
-- [Hosted Verify](https://docs.neus.network/cookbook/auth-hosted-verify)
+Add or rotate a Profile access key on an existing install:
 
-## Contributing
+```bash
+npx -y -p @neus/sdk neus auth --access-key <npk_...>
+```
+
+Claude Code (optional): add marketplace `https://github.com/neus/network`, install **`neus-mcp@neus`**, then run **`neus setup`** so your key matches every editor. See [NEUS for Claude Code](https://docs.neus.network/mcp/claude-code-marketplace).
+
+## Docs
 
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for how to propose documentation, SDK, and example changes.
+- Quickstart: https://docs.neus.network/quickstart
+- JavaScript SDK: https://docs.neus.network/sdks/javascript
+- Ownership Basic: https://docs.neus.network/verification/ownership-basic
+- Widgets: https://docs.neus.network/widgets/overview
+- MCP: https://docs.neus.network/mcp/overview
+- API: https://docs.neus.network/api/overview

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" };
@@ -797,7 +802,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 +927,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 +1030,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;
@@ -1264,13 +1318,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 +1343,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 +1373,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);

package/cjs/index.cjs

@@ -1081,6 +1081,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 FALLBACK_PUBLIC_VERIFIER_CATALOG, EVM_ADDRESS_RE, WALLET_LINK_RELATIONSHIP_TYPES, validateVerifierData, NeusClient;
 var init_client = __esm({
   "client.js"() {
@@ -1481,7 +1486,7 @@ var init_client = __esm({
       }
       _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();
@@ -1606,8 +1611,57 @@ var init_client = __esm({
           ...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)");
@@ -1660,7 +1714,7 @@ var init_client = __esm({
             }
           } 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;
@@ -1948,13 +2002,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;
@@ -1971,8 +2027,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");
@@ -1998,11 +2057,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);

package/cli/neus.mjs

@@ -203,16 +203,18 @@ function printUsage(exitCode = 0) {
     'Usage: neus <command> [options]',
     '',
     'Commands:',
+    '  setup         One-command: run init, then auth if --access-key is provided',
     '  init          Configure supported MCP clients automatically',
     '  auth          Add or update a personal access key for NEUS MCP',
     '  status        Show current NEUS MCP setup',
+    '  doctor        Deep check: config status, profile connection, agent verification',
     '  help          Show this message',
     '',
     'Options:',
     '  --client <name[,name]>   Limit setup to claude, cursor, or vscode',
     '  --project                Write shared project config instead of user config',
     '  --access-key <npk_...>   Configure Bearer auth for personal account tools',
-    '  --json                   Emit machine-readable output',
+    '  --json                   Print JSON output',
     '  --dry-run                Preview changes without writing files',
   ];
   const stream = exitCode === 0 ? process.stdout : process.stderr;
@@ -246,8 +248,8 @@ function ensureClientSelection(scope, clients) {
 }
 
 function ensureSafeAuth(command, scope, accessKey) {
-  if (command === 'auth' && scope !== 'user') {
-    throw new Error('`neus auth` only supports user scope so access keys never land in shared project config.');
+  if ((command === 'auth' || command === 'setup') && scope !== 'user') {
+    throw new Error('`neus ${command}` only supports user scope so access keys never land in shared project config.');
   }
   if (scope === 'project' && accessKey) {
     throw new Error('Access keys are only supported in user scope. Remove --project or omit --access-key.');
@@ -256,7 +258,7 @@ function ensureSafeAuth(command, scope, accessKey) {
 
 function buildCursorServer(accessKey) {
   return {
-    type: 'streamableHttp',
+    type: 'http',
     url: NEUS_MCP_URL,
     ...(accessKey ? { headers: { Authorization: `Bearer ${accessKey}` } } : {}),
   };
@@ -548,6 +550,14 @@ function printResultSummary(command, scope, results, accessKey) {
   if (command === 'init' && !accessKey) {
     lines.push(`Account tools stay optional. Add personal auth later with: neus auth --access-key <npk_...>`);
   }
+  if (command === 'init' || command === 'setup') {
+    lines.push(
+      'Claude Code (optional): plugin neus-mcp@neus + docs — https://docs.neus.network/mcp/claude-code-marketplace',
+    );
+    lines.push(
+      'Cursor / VS Code: same command when those apps are detected (local MCP config) — https://docs.neus.network/mcp/setup',
+    );
+  }
   if ((command === 'init' || command === 'auth') && accessKey) {
     lines.push('Personal account tools are enabled where the client supports user-scope auth setup.');
   }
@@ -659,6 +669,97 @@ function runStatus(options) {
   printResultSummary('status', scope, inspected, '');
 }
 
+function runSetup(options) {
+  const scope = resolveScope(options);
+  ensureSafeAuth('setup', scope, options.accessKey);
+  const cwd = process.cwd();
+  if (options.project && options.accessKey) {
+    throw new Error('Access keys are only supported in user scope. Remove --project or omit --access-key.');
+  }
+
+  const clients = resolveClients(scope, options.clients);
+  ensureClientSelection(scope, clients);
+
+  const initResults = runClientOperations(
+    clients,
+    scope,
+    cwd,
+    options.dryRun,
+    (client) => installClient(client, scope, options.accessKey, options.dryRun, cwd),
+  );
+
+  const payload = {
+    command: 'setup',
+    scope,
+    detectedClients: defaultUserClients(),
+    clients,
+    accessKeyConfigured: Boolean(options.accessKey),
+    results: initResults,
+    hasErrors: initResults.some((result) => result.error),
+  };
+
+  if (options.json) {
+    printJson(payload);
+  } else {
+    printResultSummary('setup', scope, initResults, options.accessKey);
+  }
+
+  if (payload.hasErrors) {
+    process.exitCode = 1;
+  }
+}
+
+function runDoctor(options) {
+  const scope = resolveScope(options);
+  const cwd = process.cwd();
+  const clients = resolveClients(scope, options.clients);
+  ensureClientSelection(scope, clients);
+
+  const inspected = runClientOperations(clients, scope, cwd, options.dryRun, (client) =>
+    inspectClient(client, scope, cwd),
+  );
+  const configuredClients = inspected.filter((r) => r.configured);
+  const payload = {
+    command: 'doctor',
+    scope,
+    clients: inspected,
+    configuredCount: configuredClients.length,
+    accessKeyPresent: Boolean(options.accessKey),
+    profileConnectable: false,
+    agentVerified: false,
+    summary: '',
+    hasErrors: inspected.some((result) => result.error),
+  };
+
+  if (options.json) {
+    printJson(payload);
+    return;
+  }
+
+  printResultSummary('doctor', scope, inspected, '');
+
+  const lines = [];
+  if (configuredClients.length > 0) {
+    lines.push(`MCP reachable: ${configuredClients.map((r) => r.client).join(', ')} ready at ${NEUS_MCP_URL}.`);
+  } else {
+    lines.push('MCP reachable: No clients configured. Run `neus setup` or `neus init` first.');
+    process.stdout.write(`\n${lines.join('\n')}\n`);
+    process.exit(1);
+  }
+
+  if (options.accessKey) {
+    lines.push('Profile connection: auth header present. Connect to the MCP endpoint and run `neus_me` to confirm.');
+  } else {
+    lines.push(`Profile connection: No access key found. Run \`neus auth --access-key <npk_...>\` (create one at ${NEUS_ACCESS_KEYS_URL}) and reconnect.`);
+  }
+
+  lines.push('Agent verification: Run `neus_agent_link` and `neus_proofs_check` inside the MCP-connected client to verify agent identity and delegation proofs.');
+  lines.push('');
+  lines.push('Next: Open your editor/IDE, connect to the NEUS MCP endpoint, and run `neus_context`.');
+
+  process.stdout.write(`\n${lines.join('\n')}\n`);
+}
+
 function main() {
   try {
     const { command, options } = parseArgs(process.argv.slice(2));
@@ -679,6 +780,14 @@ function main() {
       runStatus(options);
       return;
     }
+    if (command === 'setup') {
+      runSetup(options);
+      return;
+    }
+    if (command === 'doctor') {
+      runDoctor(options);
+      return;
+    }
 
     process.stderr.write(`Unknown subcommand: ${command}\n`);
     printUsage(1);

package/client.js

@@ -48,6 +48,13 @@ function normalizeBrowserSignerString(raw) {
   return null;
 }
 
+/** Treats SDK placeholder signatures as absent so the protocol can use session or app-link delegation. */
+function isPlaceholderNeusSignature(signature) {
+  const s = typeof signature === 'string' ? signature.trim() : '';
+  if (!s) return true;
+  return /^0x0+$/i.test(s);
+}
+
 const validateVerifierData = (verifierId, data) => {
   if (!data || typeof data !== 'object') {
     return { valid: false, error: 'Data object is required' };
@@ -450,10 +457,12 @@ export class NeusClient {
     throw new ConfigurationError('Invalid wallet provider');
   }
 
-  _getDefaultBrowserWallet() {
-    if (typeof window === 'undefined') return null;
-    return window.ethereum || window.solana || (window.phantom && window.phantom.solana) || null;
-  }
+  _getDefaultBrowserWallet() {
+    if (typeof window === 'undefined') return null;
+    // Legacy convenience fallback only. Non-EVM wallets must be passed explicitly
+    // with CAIP-2 chain context so the SDK does not route them through EVM RPC.
+    return window.ethereum || null;
+  }
 
   async _buildPrivateGateAuth({ address, wallet, chain, signatureMethod } = {}) {
     const providerWallet = wallet || this._getDefaultBrowserWallet();
@@ -595,8 +604,74 @@ export class NeusClient {
     };
   }
 
+  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 = null, wallet = null, options = {} } = params;
 
       if (verifier === 'ownership-basic' && !data && (!content || typeof content !== 'string')) {
@@ -657,10 +732,10 @@ export class NeusClient {
             walletAddress = Array.isArray(accounts) && accounts.length > 0 ? accounts[0] : null;
           }
         }
-      } else {
-        if (typeof window === 'undefined' || !window.ethereum) {
-          throw new ConfigurationError('No Web3 wallet detected. Please install MetaMask or provide wallet parameter.');
-        }
+      } else {
+        if (typeof window === 'undefined' || !window.ethereum) {
+          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;
         const accounts = await provider.request({ method: 'eth_accounts' });
@@ -962,14 +1037,17 @@ export class NeusClient {
       verifierIds,
       data,
       walletAddress,
-      signature,
+      signature: rawSignature,
       signedTimestamp,
       chainId,
       chain,
       signatureMethod,
+      delegationQHash,
       options = {}
     } = params;
 
+    const signature = isPlaceholderNeusSignature(rawSignature) ? undefined : rawSignature;
+
     const resolvedChainId = chainId || (chain ? null : NEUS_CONSTANTS.HUB_CHAIN_ID);
 
     const normalizeVerifierId = (id) => {
@@ -988,8 +1066,12 @@ export class NeusClient {
     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');
@@ -1019,11 +1101,12 @@ export class NeusClient {
       verifierIds: normalizedVerifierIds,
       data,
       walletAddress,
-      signature,
+      ...(signature ? { signature } : {}),
       signedTimestamp,
       ...(resolvedChainId !== null && { chainId: resolvedChainId }),
       ...(chain && { chain }),
       ...(signatureMethod && { signatureMethod }),
+      ...(delegationQHash && { delegationQHash }),
       options: optionsPayload
     };
 

package/errors.js

@@ -79,7 +79,7 @@ export class NetworkError extends SDKError {
     super(message, code);
     this.name = 'NetworkError';
     this.originalError = originalError;
-    this.isRetryable = true; // Network errors are typically retryable
+    this.isRetryable = true; // Network errors are retryable
   }
 
   static isNetworkError(error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@neus/sdk",
-  "version": "1.0.9",
-  "description": "Issue and check NEUS trust receipts across apps, agents, gates, payments, and workflows.",
+  "version": "1.0.12",
+  "description": "NEUS makes trust portable across the internet — so people, apps, and AI agents can prove what is real before access, payout, or execution.",
   "bin": {
     "neus": "cli/neus.mjs"
   },

package/types.d.ts

@@ -7,7 +7,9 @@ declare module '@neus/sdk' {
 
   export class NeusClient {
     constructor(config?: NeusClientConfig);
-    
+
+    verifyFromApp(params: VerifyFromAppParams): Promise<VerificationResult>;
+
     verify(params: VerifyParams): Promise<VerificationResult>;
     
     getProof(qHash: string): Promise<StatusResult>;
@@ -57,6 +59,8 @@ declare module '@neus/sdk' {
     apiUrl?: string;
     apiKey?: string;
     appId?: string;
+    /** Optional: only when using legacy `delegationQHash` on verify requests. App-linked servers rely on `appId` + Origin + stored delegation. */
+    appLinkQHash?: string;
     paymentSignature?: string;
     extraHeaders?: Record<string, string>;
     timeout?: number;
@@ -92,6 +96,18 @@ declare module '@neus/sdk' {
     meta?: Record<string, any>;
   }
   
+  export interface VerifyFromAppParams {
+    user: {
+      walletAddress?: string;
+      address?: string;
+      identity?: string;
+    };
+    verifier?: VerifierId;
+    content?: string | Record<string, any>;
+    data?: VerificationData;
+    options?: VerifyOptions;
+  }
+
   export interface VerifyParams {
     verifier?: VerifierId;
     content?: string;
@@ -105,6 +121,7 @@ declare module '@neus/sdk' {
     chainId?: number;
     chain?: string;
     signatureMethod?: string;
+    delegationQHash?: string;
     wallet?: WalletLike;
   }
     

package/widgets/README.md

@@ -10,7 +10,7 @@ npm install @neus/sdk react react-dom
 
 ## VerifyGate
 
-Create mode defaults to **private**. Override `proofOptions` only when you intentionally need public visibility for link-based or public checks.
+Create mode defaults to **private**. Override `proofOptions` only when you need public visibility for link-based or public checks.
 
 ```jsx
 import { VerifyGate } from '@neus/sdk/widgets';

package/widgets/verify-gate/dist/VerifyGate.js

@@ -307,7 +307,7 @@ function VerifyGate({
       return provider.address;
     }
     if (typeof provider.request !== "function") {
-      throw new Error("No wallet provider available");
+      throw new Error("Connect a wallet and try again.");
     }
     let accounts = await provider.request({ method: "eth_accounts" });
     if (!accounts || accounts.length === 0) {
@@ -315,7 +315,7 @@ function VerifyGate({
       accounts = await provider.request({ method: "eth_accounts" });
     }
     if (!accounts || accounts.length === 0) {
-      throw new Error("No wallet accounts available");
+      throw new Error("Connect a wallet and try again.");
     }
     return accounts[0];
   }, [wallet]);
@@ -388,7 +388,7 @@ function VerifyGate({
   }, [client, buildGateRequirements, wallet, inferChainFromAddress, signatureMethod]);
   const launchHostedCheckout = useCallback(async () => {
     if (typeof window === "undefined") {
-      throw new Error("Hosted checkout is only available in browser environments");
+      throw new Error("Open this in a browser to verify.");
     }
     const origin = window.location.origin;
     const returnUrl = window.location.href;
@@ -446,7 +446,7 @@ function VerifyGate({
         completed = true;
         cleanup();
         if (payload?.eligible === false) {
-          reject(new Error("Hosted checkout completed but eligibility was not satisfied."));
+          reject(new Error("Verification could not be completed."));
           return;
         }
         resolve(payload);
@@ -573,7 +573,7 @@ function VerifyGate({
         const buildDataForVerifier = (verifierId) => {
           if (!CREATABLE_VERIFIERS.has(verifierId)) {
             throw new Error(
-              `${verifierId} cannot be created via the wallet flow. It requires hosted checkout or a server integration.`
+              "This check requires the hosted verifier."
             );
           }
           const explicit = verifierData && verifierData[verifierId];
@@ -587,12 +587,12 @@ function VerifyGate({
           if (verifierId === "wallet-link") {
             if (!explicit?.secondaryWalletAddress || !explicit?.signature || !explicit?.chain || !explicit?.signatureMethod) {
               throw new Error(
-                "wallet-link direct mode requires verifierData: { secondaryWalletAddress, signature, chain, signatureMethod }. For user-facing flows, prefer hosted checkout."
+                "Missing required wallet details."
               );
             }
             return explicit;
           }
-          throw new Error(`${verifierId} requires explicit verifierData`);
+          throw new Error("Missing required verification details.");
         };
         const verifyOne = async (verifierId) => {
           const dataForVerifier = buildDataForVerifier(verifierId);
@@ -616,7 +616,7 @@ function VerifyGate({
           const verifiedVerifiers = final?.data?.verifiedVerifiers || [];
           const verifierResult = verifiedVerifiers.find((v) => v.verifierId === verifierId);
           if (!verifierResult || verifierResult.verified !== true) {
-            throw new Error(`Verification failed for ${verifierId}`);
+            throw new Error("Verification could not be completed.");
           }
           const hubTx = final?.data?.hubTransaction || {};
           const crosschain = final?.data?.crosschain || {};
@@ -849,7 +849,7 @@ function VerifyGate({
             textUnderlineOffset: "2px",
             opacity: disabled || isProcessing ? 0.6 : 0.9
           },
-          children: "Already verified? Sign to reuse existing proofs."
+          children: "Already verified? Reuse your proof."
         }
       ),
       error && /* @__PURE__ */ jsx("div", { style: {