@neus/sdk 1.0.4 → 1.0.5

package/README.md

@@ -16,7 +16,22 @@ npm install @neus/sdk
 npx -y -p @neus/sdk neus init
 ```
 
-Prints the hosted MCP URL and documentation links in your terminal - fast setup in IDEs and agent clients.
+Configures supported MCP clients automatically. By default the command installs NEUS into user-level Claude Code, Cursor, and VS Code MCP config when those clients are detected.
+
+## CLI
+
+```bash
+# Autopilot setup for detected clients
+npx -y -p @neus/sdk neus init
+
+# Enable personal account tools such as neus_me and private reads
+npx -y -p @neus/sdk neus auth --access-key <npk_...>
+
+# Inspect current NEUS MCP setup
+npx -y -p @neus/sdk neus status --json
+```
+
+Use `neus init --project` when you want shared repo config instead of personal user-scope setup. Access keys stay user-scope only so secrets do not land in checked-in config.
 
 ## Minimal working example
 
@@ -51,6 +66,7 @@ const check = await client.gateCheck({
 | `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 |
 
 ## VerifyGate (React)
 
@@ -76,6 +92,27 @@ const client = new NeusClient({
 });
 ```
 
+## Wallet-link
+
+For user-facing browser flows, prefer Hosted Verify so the user can select a secondary wallet, sign once, see the linked state, and only then continue to proof creation.
+
+Use `client.createWalletLinkData()` only for advanced direct/API flows where your app already controls the secondary-wallet provider:
+
+```javascript
+const walletLinkData = await client.createWalletLinkData({
+  primaryWalletAddress: '0xprimary...',
+  secondaryWalletAddress: '0xsecondary...',
+  wallet: window.ethereum,
+  relationshipType: 'linked',
+  label: 'ops-wallet'
+});
+
+await client.verify({
+  verifier: 'wallet-link',
+  data: walletLinkData
+});
+```
+
 ## Docs
 
 - [Quickstart](https://docs.neus.network/quickstart)

package/cjs/client.cjs

@@ -411,6 +411,11 @@ var FALLBACK_PUBLIC_VERIFIER_CATALOG = {
   "ai-content-moderation": { supportsDirectApi: true }
 };
 var EVM_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+var WALLET_LINK_RELATIONSHIP_TYPES = /* @__PURE__ */ new Set(["primary", "personal", "org", "affiliate", "agent", "linked"]);
+function normalizeWalletLinkRelationshipType(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return WALLET_LINK_RELATIONSHIP_TYPES.has(normalized) ? normalized : "linked";
+}
 var validateVerifierData = (verifierId, data) => {
   if (!data || typeof data !== "object") {
     return { valid: false, error: "Data object is required" };
@@ -821,6 +826,74 @@ var NeusClient = class {
       signatureMethod: params.signatureMethod
     });
   }
+  async createWalletLinkData(params = {}) {
+    const normalizedPrimary = this._normalizeIdentity(params.primaryWalletAddress);
+    const normalizedSecondary = this._normalizeIdentity(params.secondaryWalletAddress);
+    if (!EVM_ADDRESS_RE.test(normalizedPrimary)) {
+      throw new ValidationError("wallet-link requires a valid primaryWalletAddress");
+    }
+    if (!EVM_ADDRESS_RE.test(normalizedSecondary)) {
+      throw new ValidationError("wallet-link requires a valid secondaryWalletAddress");
+    }
+    if (normalizedPrimary === normalizedSecondary) {
+      throw new ValidationError("wallet-link secondaryWalletAddress must differ from primaryWalletAddress");
+    }
+    const providerWallet = params.wallet || this._getDefaultBrowserWallet();
+    const { signerWalletAddress, provider } = await this._resolveWalletSigner(providerWallet);
+    const normalizedSigner = this._normalizeIdentity(signerWalletAddress);
+    if (!EVM_ADDRESS_RE.test(normalizedSigner)) {
+      throw new ValidationError("wallet-link requires an EVM wallet/provider for the secondary wallet");
+    }
+    if (normalizedSigner !== normalizedSecondary) {
+      throw new ValidationError("wallet-link wallet/provider must be connected to secondaryWalletAddress");
+    }
+    const resolvedChain = (() => {
+      const raw = String(params.chain || "").trim();
+      if (!raw) return `eip155:${this._getHubChainId()}`;
+      if (!/^eip155:\d+$/.test(raw)) {
+        throw new ValidationError("wallet-link requires chain in the form eip155:<chainId>");
+      }
+      return raw;
+    })();
+    const signedTimestamp = Number.isFinite(Number(params.signedTimestamp)) && Number(params.signedTimestamp) > 0 ? Number(params.signedTimestamp) : Date.now();
+    const linkData = {
+      primaryAccountId: `${resolvedChain}:${normalizedPrimary}`,
+      secondaryAccountId: `${resolvedChain}:${normalizedSecondary}`,
+      primaryWalletAddress: normalizedPrimary,
+      secondaryWalletAddress: normalizedSecondary
+    };
+    const message = constructVerificationMessage({
+      walletAddress: normalizedSecondary,
+      signedTimestamp,
+      data: linkData,
+      verifierIds: ["wallet-link"],
+      chain: resolvedChain
+    });
+    let signature;
+    try {
+      signature = await signMessage({
+        provider,
+        message,
+        walletAddress: signerWalletAddress
+      });
+    } catch (error) {
+      if (error?.code === 4001) {
+        throw new ValidationError("User rejected wallet-link signature request");
+      }
+      throw new ValidationError(`Failed to sign wallet-link message: ${error?.message || String(error)}`);
+    }
+    const label = String(params.label || "").trim().slice(0, 64);
+    return {
+      primaryWalletAddress: normalizedPrimary,
+      secondaryWalletAddress: normalizedSecondary,
+      signature,
+      chain: resolvedChain,
+      signatureMethod: "eip191",
+      signedTimestamp,
+      relationshipType: normalizeWalletLinkRelationshipType(params.relationshipType),
+      ...label ? { label } : {}
+    };
+  }
   /**
    * Create a verification proof.
    *

package/cjs/index.cjs

@@ -1073,7 +1073,11 @@ __export(client_exports, {
   PORTABLE_PROOF_SIGNER_HEADER: () => PORTABLE_PROOF_SIGNER_HEADER,
   constructVerificationMessage: () => constructVerificationMessage
 });
-var FALLBACK_PUBLIC_VERIFIER_CATALOG, EVM_ADDRESS_RE, validateVerifierData, NeusClient;
+function normalizeWalletLinkRelationshipType(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return WALLET_LINK_RELATIONSHIP_TYPES.has(normalized) ? normalized : "linked";
+}
+var FALLBACK_PUBLIC_VERIFIER_CATALOG, EVM_ADDRESS_RE, WALLET_LINK_RELATIONSHIP_TYPES, validateVerifierData, NeusClient;
 var init_client = __esm({
   "client.js"() {
     "use strict";
@@ -1096,6 +1100,7 @@ var init_client = __esm({
       "ai-content-moderation": { supportsDirectApi: true }
     };
     EVM_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+    WALLET_LINK_RELATIONSHIP_TYPES = /* @__PURE__ */ new Set(["primary", "personal", "org", "affiliate", "agent", "linked"]);
     validateVerifierData = (verifierId, data) => {
       if (!data || typeof data !== "object") {
         return { valid: false, error: "Data object is required" };
@@ -1506,6 +1511,74 @@ var init_client = __esm({
           signatureMethod: params.signatureMethod
         });
       }
+      async createWalletLinkData(params = {}) {
+        const normalizedPrimary = this._normalizeIdentity(params.primaryWalletAddress);
+        const normalizedSecondary = this._normalizeIdentity(params.secondaryWalletAddress);
+        if (!EVM_ADDRESS_RE.test(normalizedPrimary)) {
+          throw new ValidationError("wallet-link requires a valid primaryWalletAddress");
+        }
+        if (!EVM_ADDRESS_RE.test(normalizedSecondary)) {
+          throw new ValidationError("wallet-link requires a valid secondaryWalletAddress");
+        }
+        if (normalizedPrimary === normalizedSecondary) {
+          throw new ValidationError("wallet-link secondaryWalletAddress must differ from primaryWalletAddress");
+        }
+        const providerWallet = params.wallet || this._getDefaultBrowserWallet();
+        const { signerWalletAddress, provider } = await this._resolveWalletSigner(providerWallet);
+        const normalizedSigner = this._normalizeIdentity(signerWalletAddress);
+        if (!EVM_ADDRESS_RE.test(normalizedSigner)) {
+          throw new ValidationError("wallet-link requires an EVM wallet/provider for the secondary wallet");
+        }
+        if (normalizedSigner !== normalizedSecondary) {
+          throw new ValidationError("wallet-link wallet/provider must be connected to secondaryWalletAddress");
+        }
+        const resolvedChain = (() => {
+          const raw = String(params.chain || "").trim();
+          if (!raw) return `eip155:${this._getHubChainId()}`;
+          if (!/^eip155:\d+$/.test(raw)) {
+            throw new ValidationError("wallet-link requires chain in the form eip155:<chainId>");
+          }
+          return raw;
+        })();
+        const signedTimestamp = Number.isFinite(Number(params.signedTimestamp)) && Number(params.signedTimestamp) > 0 ? Number(params.signedTimestamp) : Date.now();
+        const linkData = {
+          primaryAccountId: `${resolvedChain}:${normalizedPrimary}`,
+          secondaryAccountId: `${resolvedChain}:${normalizedSecondary}`,
+          primaryWalletAddress: normalizedPrimary,
+          secondaryWalletAddress: normalizedSecondary
+        };
+        const message = constructVerificationMessage({
+          walletAddress: normalizedSecondary,
+          signedTimestamp,
+          data: linkData,
+          verifierIds: ["wallet-link"],
+          chain: resolvedChain
+        });
+        let signature;
+        try {
+          signature = await signMessage({
+            provider,
+            message,
+            walletAddress: signerWalletAddress
+          });
+        } catch (error) {
+          if (error?.code === 4001) {
+            throw new ValidationError("User rejected wallet-link signature request");
+          }
+          throw new ValidationError(`Failed to sign wallet-link message: ${error?.message || String(error)}`);
+        }
+        const label = String(params.label || "").trim().slice(0, 64);
+        return {
+          primaryWalletAddress: normalizedPrimary,
+          secondaryWalletAddress: normalizedSecondary,
+          signature,
+          chain: resolvedChain,
+          signatureMethod: "eip191",
+          signedTimestamp,
+          relationshipType: normalizeWalletLinkRelationshipType(params.relationshipType),
+          ...label ? { label } : {}
+        };
+      }
       /**
        * Create a verification proof.
        *

package/cli/neus.mjs

@@ -1,58 +1,606 @@
 #!/usr/bin/env node
-const argv = process.argv.slice(2);
-const sub = argv[0];
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 
-function usage() {
-  process.stderr.write("Usage: neus init\n");
-  process.stderr.write("Prints hosted MCP config and doc URLs. Does not write files.\n");
-  process.exit(sub && sub !== "help" && sub !== "--help" && sub !== "-h" ? 1 : 0);
+const NEUS_SERVER_NAME = 'neus';
+const NEUS_MCP_URL = 'https://mcp.neus.network/mcp';
+const NEUS_ACCESS_KEYS_URL = 'https://neus.network/profile?tab=account';
+const SUPPORTED_CLIENTS = ['claude', 'cursor', 'vscode'];
+
+function fileExists(targetPath) {
+  try {
+    fs.accessSync(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
-function printInit() {
-  const mcpBlock = {
-    mcpServers: {
-      neus: {
-        type: "streamableHttp",
-        url: "https://mcp.neus.network/mcp",
+function jsonStringify(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function readJsonFile(targetPath, fallback) {
+  if (!fileExists(targetPath)) return fallback;
+  const raw = fs.readFileSync(targetPath, 'utf8');
+  const parsed = JSON.parse(raw);
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : fallback;
+}
+
+function writeJsonFile(targetPath, nextValue, dryRun) {
+  const serialized = jsonStringify(nextValue);
+  const hadExistingFile = fileExists(targetPath);
+  const previous = hadExistingFile ? fs.readFileSync(targetPath, 'utf8') : null;
+  const changed = previous !== serialized;
+  const backupPath = hadExistingFile && changed ? `${targetPath}.bak` : null;
+
+  if (!dryRun && changed) {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    if (backupPath) {
+      fs.copyFileSync(targetPath, backupPath);
+    }
+    fs.writeFileSync(targetPath, serialized, 'utf8');
+  }
+
+  return {
+    changed,
+    targetPath,
+    backupPath,
+    dryRun,
+  };
+}
+
+function resolveCommand(command) {
+  const checker = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(checker, [command], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) return null;
+  const firstMatch = result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean);
+  return firstMatch || null;
+}
+
+function runCommand(command, args, cwd, tolerateFailure = false) {
+  const resolvedCommand = resolveCommand(command) || command;
+  const isWindowsScript = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolvedCommand);
+  const result = isWindowsScript
+    ? spawnSync(
+        process.env.ComSpec || 'cmd.exe',
+        ['/d', '/s', '/c', resolvedCommand, ...args],
+        {
+          cwd,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'pipe'],
+        },
+      )
+    : spawnSync(resolvedCommand, args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+  if (result.error && !tolerateFailure) {
+    throw result.error;
+  }
+
+  if (result.status !== 0 && !tolerateFailure) {
+    const detail = [result.stderr, result.stdout].find((value) => typeof value === 'string' && value.trim()) || '';
+    throw new Error(detail.trim() || `Command failed: ${command} ${args.join(' ')}`);
+  }
+
+  return result;
+}
+
+function commandExists(command) {
+  return Boolean(resolveCommand(command));
+}
+
+function cursorInstalled() {
+  const homeDir = os.homedir();
+  const appData = process.env.APPDATA || '';
+  const localAppData = process.env.LOCALAPPDATA || '';
+  return [
+    path.join(homeDir, '.cursor'),
+    path.join(appData, 'Cursor'),
+    path.join(localAppData, 'Programs', 'Cursor', 'Cursor.exe'),
+  ].some(fileExists);
+}
+
+function defaultUserClients() {
+  const detected = [];
+  if (commandExists('claude')) detected.push('claude');
+  if (cursorInstalled()) detected.push('cursor');
+  if (commandExists('code') || fileExists(path.join(process.env.APPDATA || '', 'Code'))) detected.push('vscode');
+  return detected;
+}
+
+function parseClientOption(raw) {
+  return String(raw || '')
+    .split(',')
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function parseArgs(argv) {
+  if (argv.length === 0) {
+    return {
+      command: 'help',
+      options: {
+        accessKey: process.env.NEUS_ACCESS_KEY || '',
+        clients: [],
+        json: false,
+        dryRun: false,
+        project: false,
       },
+    };
+  }
+
+  const command = argv[0];
+  const options = {
+    accessKey: process.env.NEUS_ACCESS_KEY || '',
+    clients: [],
+    json: false,
+    dryRun: false,
+    project: false,
+  };
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (token === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+    if (token === '--project') {
+      options.project = true;
+      continue;
+    }
+    if (token === '--client') {
+      const value = argv[index + 1];
+      if (!value) throw new Error('--client requires a value');
+      options.clients.push(...parseClientOption(value));
+      index += 1;
+      continue;
+    }
+    if (token === '--access-key') {
+      const value = argv[index + 1];
+      if (!value) throw new Error('--access-key requires a value');
+      options.accessKey = value;
+      index += 1;
+      continue;
+    }
+    if (token === '--help' || token === '-h') {
+      return { command: 'help', options };
+    }
+    throw new Error(`Unknown option: ${token}`);
+  }
+
+  options.accessKey = String(options.accessKey || '').trim();
+  options.clients = [...new Set(options.clients)];
+
+  return { command, options };
+}
+
+function printUsage(exitCode = 0) {
+  const lines = [
+    'Usage: neus <command> [options]',
+    '',
+    'Commands:',
+    '  init          Configure supported MCP clients automatically',
+    '  auth          Add or update a personal access key for NEUS MCP',
+    '  status        Show current NEUS MCP setup',
+    '  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',
+    '  --dry-run                Preview changes without writing files',
+  ];
+  const stream = exitCode === 0 ? process.stdout : process.stderr;
+  stream.write(`${lines.join('\n')}\n`);
+  process.exit(exitCode);
+}
+
+function assertValidClients(clients) {
+  for (const client of clients) {
+    if (!SUPPORTED_CLIENTS.includes(client)) {
+      throw new Error(`Unsupported client: ${client}`);
+    }
+  }
+}
+
+function resolveScope(options) {
+  return options.project ? 'project' : 'user';
+}
+
+function resolveClients(scope, requestedClients) {
+  assertValidClients(requestedClients);
+  if (requestedClients.length > 0) return requestedClients;
+  if (scope === 'project') return [...SUPPORTED_CLIENTS];
+  return defaultUserClients();
+}
+
+function ensureClientSelection(scope, clients) {
+  if (clients.length > 0) return;
+  if (scope === 'project') return;
+  throw new Error('No supported clients detected. Re-run with --project or use --client to target a specific client.');
+}
+
+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 (scope === 'project' && accessKey) {
+    throw new Error('Access keys are only supported in user scope. Remove --project or omit --access-key.');
+  }
+}
+
+function buildCursorServer(accessKey) {
+  return {
+    type: 'streamableHttp',
+    url: NEUS_MCP_URL,
+    ...(accessKey ? { headers: { Authorization: `Bearer ${accessKey}` } } : {}),
+  };
+}
+
+function buildVsCodeServer(accessKey) {
+  return {
+    type: 'http',
+    url: NEUS_MCP_URL,
+    ...(accessKey ? { headers: { Authorization: `Bearer ${accessKey}` } } : {}),
+  };
+}
+
+function buildClaudeServer(accessKey) {
+  return {
+    type: 'http',
+    url: NEUS_MCP_URL,
+    ...(accessKey ? { headers: { Authorization: `Bearer ${accessKey}` } } : {}),
+  };
+}
+
+function cursorConfigPath(scope, cwd) {
+  return scope === 'user'
+    ? path.join(os.homedir(), '.cursor', 'mcp.json')
+    : path.join(cwd, '.cursor', 'mcp.json');
+}
+
+function vscodeConfigPath(scope, cwd) {
+  return scope === 'user'
+    ? path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'), 'Code', 'User', 'mcp.json')
+    : path.join(cwd, '.vscode', 'mcp.json');
+}
+
+function claudeProjectConfigPath(cwd) {
+  return path.join(cwd, '.mcp.json');
+}
+
+function installCursor(scope, accessKey, dryRun, cwd) {
+  const targetPath = cursorConfigPath(scope, cwd);
+  const doc = readJsonFile(targetPath, { mcpServers: {} });
+  const next = {
+    ...doc,
+    mcpServers: {
+      ...(doc.mcpServers && typeof doc.mcpServers === 'object' && !Array.isArray(doc.mcpServers) ? doc.mcpServers : {}),
+      [NEUS_SERVER_NAME]: buildCursorServer(accessKey),
+    },
+  };
+  const writeResult = writeJsonFile(targetPath, next, dryRun);
+  return {
+    client: 'cursor',
+    scope,
+    configured: true,
+    authConfigured: Boolean(accessKey),
+    changed: writeResult.changed,
+    targetPath,
+    backupPath: writeResult.backupPath,
+    dryRun,
+  };
+}
+
+function installVsCode(scope, accessKey, dryRun, cwd) {
+  const targetPath = vscodeConfigPath(scope, cwd);
+  const doc = readJsonFile(targetPath, { servers: {} });
+  const next = {
+    ...doc,
+    servers: {
+      ...(doc.servers && typeof doc.servers === 'object' && !Array.isArray(doc.servers) ? doc.servers : {}),
+      [NEUS_SERVER_NAME]: buildVsCodeServer(accessKey),
     },
   };
+  const writeResult = writeJsonFile(targetPath, next, dryRun);
+  return {
+    client: 'vscode',
+    scope,
+    configured: true,
+    authConfigured: Boolean(accessKey),
+    changed: writeResult.changed,
+    targetPath,
+    backupPath: writeResult.backupPath,
+    dryRun,
+  };
+}
+
+function installClaudeProject(scope, accessKey, dryRun, cwd) {
+  const targetPath = claudeProjectConfigPath(cwd);
+  const doc = readJsonFile(targetPath, { mcpServers: {} });
+  const next = {
+    ...doc,
+    mcpServers: {
+      ...(doc.mcpServers && typeof doc.mcpServers === 'object' && !Array.isArray(doc.mcpServers) ? doc.mcpServers : {}),
+      [NEUS_SERVER_NAME]: buildClaudeServer(accessKey),
+    },
+  };
+  const writeResult = writeJsonFile(targetPath, next, dryRun);
+  return {
+    client: 'claude',
+    scope,
+    configured: true,
+    authConfigured: Boolean(accessKey),
+    changed: writeResult.changed,
+    targetPath,
+    backupPath: writeResult.backupPath,
+    dryRun,
+  };
+}
+
+function installClaudeUser(scope, accessKey, dryRun, cwd) {
+  if (!commandExists('claude')) {
+    throw new Error('Claude Code CLI is not installed or not on PATH.');
+  }
+
+  if (!dryRun) {
+    runCommand('claude', ['mcp', 'remove', '--scope', 'user', NEUS_SERVER_NAME], cwd, true);
+    const addArgs = [
+      'mcp',
+      'add',
+      '--transport',
+      'http',
+      '--scope',
+      'user',
+      NEUS_SERVER_NAME,
+      NEUS_MCP_URL,
+    ];
+    if (accessKey) {
+      addArgs.push('--header', `Authorization: Bearer ${accessKey}`);
+    }
+    runCommand('claude', addArgs, cwd);
+  }
+
+  return {
+    client: 'claude',
+    scope,
+    configured: true,
+    authConfigured: Boolean(accessKey),
+    changed: true,
+    targetPath: '~/.claude.json',
+    backupPath: null,
+    dryRun,
+  };
+}
+
+function installClaude(scope, accessKey, dryRun, cwd) {
+  if (scope === 'project') {
+    return installClaudeProject(scope, accessKey, dryRun, cwd);
+  }
+  return installClaudeUser(scope, accessKey, dryRun, cwd);
+}
 
+function installClient(client, scope, accessKey, dryRun, cwd) {
+  if (client === 'cursor') return installCursor(scope, accessKey, dryRun, cwd);
+  if (client === 'vscode') return installVsCode(scope, accessKey, dryRun, cwd);
+  if (client === 'claude') return installClaude(scope, accessKey, dryRun, cwd);
+  throw new Error(`Unsupported client: ${client}`);
+}
+
+function inspectCursor(scope, cwd) {
+  const targetPath = cursorConfigPath(scope, cwd);
+  if (!fileExists(targetPath)) {
+    return { client: 'cursor', scope, configured: false, authConfigured: false, targetPath };
+  }
+  const doc = readJsonFile(targetPath, {});
+  const server = doc.mcpServers?.[NEUS_SERVER_NAME];
+  return {
+    client: 'cursor',
+    scope,
+    configured: Boolean(server && server.url === NEUS_MCP_URL),
+    authConfigured: Boolean(server?.headers?.Authorization),
+    targetPath,
+  };
+}
+
+function inspectVsCode(scope, cwd) {
+  const targetPath = vscodeConfigPath(scope, cwd);
+  if (!fileExists(targetPath)) {
+    return { client: 'vscode', scope, configured: false, authConfigured: false, targetPath };
+  }
+  const doc = readJsonFile(targetPath, {});
+  const server = doc.servers?.[NEUS_SERVER_NAME];
+  return {
+    client: 'vscode',
+    scope,
+    configured: Boolean(server && server.url === NEUS_MCP_URL),
+    authConfigured: Boolean(server?.headers?.Authorization),
+    targetPath,
+  };
+}
+
+function inspectClaude(scope, cwd) {
+  if (scope === 'project') {
+    const targetPath = claudeProjectConfigPath(cwd);
+    if (!fileExists(targetPath)) {
+      return { client: 'claude', scope, configured: false, authConfigured: false, targetPath };
+    }
+    const doc = readJsonFile(targetPath, {});
+    const server = doc.mcpServers?.[NEUS_SERVER_NAME];
+    return {
+      client: 'claude',
+      scope,
+      configured: Boolean(server && server.url === NEUS_MCP_URL),
+      authConfigured: Boolean(server?.headers?.Authorization),
+      targetPath,
+    };
+  }
+
+  if (!commandExists('claude')) {
+    return { client: 'claude', scope, configured: false, authConfigured: null, targetPath: '~/.claude.json' };
+  }
+
+  const result = runCommand('claude', ['mcp', 'list'], cwd, true);
+  const configured = result.status === 0 && result.stdout.split(/\r?\n/).some((line) => line.trim() === NEUS_SERVER_NAME);
+  return {
+    client: 'claude',
+    scope,
+    configured,
+    authConfigured: null,
+    targetPath: '~/.claude.json',
+  };
+}
+
+function inspectClient(client, scope, cwd) {
+  if (client === 'cursor') return inspectCursor(scope, cwd);
+  if (client === 'vscode') return inspectVsCode(scope, cwd);
+  if (client === 'claude') return inspectClaude(scope, cwd);
+  throw new Error(`Unsupported client: ${client}`);
+}
+
+function printJson(payload) {
+  process.stdout.write(jsonStringify(payload));
+}
+
+function printResultSummary(command, scope, results, accessKey) {
+  const changedCount = results.filter((result) => result.changed).length;
+  const configuredClients = results.map((result) => result.client).join(', ');
   const lines = [
-    "# NEUS",
-    "",
-    "## MCP",
-    JSON.stringify(mcpBlock, null, 2),
-    "",
-    "## URLs",
-    "MCP: https://mcp.neus.network/mcp",
-    "Verify:    https://neus.network/verify",
-    "Explorer:  https://neus.network/hub",
-    "",
-    "## Docs",
-    "MCP setup:        https://docs.neus.network/mcp/setup",
-    "LLM / assistants: https://docs.neus.network/platform/llm-docs",
-    "Agents:           https://docs.neus.network/agents/overview",
-    "Agent identity:   https://docs.neus.network/agents/agent-identity",
-    "Agent delegation: https://docs.neus.network/agents/agent-delegation",
-    "Integration:      https://docs.neus.network/integration",
-    "Quickstart:       https://docs.neus.network/quickstart",
-    "Machine route map: https://neus.network/llms.txt",
-    "",
-    "This command only prints to stdout; it does not modify files or create accounts.",
-    "Use Authorization: Bearer <access key> when a tool returns auth_required (see MCP auth).",
+    `NEUS ${command} completed for ${results.length} client${results.length === 1 ? '' : 's'} in ${scope} scope.`,
+    `Configured: ${configuredClients || 'none'}.`,
   ];
 
-  process.stdout.write(`${lines.join("\n")}\n`);
+  if (changedCount > 0) {
+    lines.push(`Updated: ${changedCount} target${changedCount === 1 ? '' : 's'}.`);
+  }
+
+  if (command === 'init' && !accessKey) {
+    lines.push(`Account tools stay optional. Add personal auth later with: neus auth --access-key <npk_...>`);
+  }
+  if ((command === 'init' || command === 'auth') && accessKey) {
+    lines.push('Personal account tools are enabled where the client supports user-scope auth setup.');
+  }
+  if (command === 'status') {
+    const enabled = results.filter((result) => result.configured).map((result) => result.client);
+    lines.push(`Active: ${enabled.length > 0 ? enabled.join(', ') : 'none'}.`);
+  }
+
+  process.stdout.write(`${lines.join('\n')}\n`);
 }
 
-if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
-  usage();
+function runInit(options) {
+  const scope = resolveScope(options);
+  ensureSafeAuth('init', scope, options.accessKey);
+
+  const clients = resolveClients(scope, options.clients);
+  ensureClientSelection(scope, clients);
+
+  const results = clients.map((client) => installClient(client, scope, options.accessKey, options.dryRun, process.cwd()));
+  const payload = {
+    command: 'init',
+    scope,
+    detectedClients: defaultUserClients(),
+    clients,
+    accessKeyConfigured: Boolean(options.accessKey),
+    results,
+  };
+
+  if (options.json) {
+    printJson(payload);
+    return;
+  }
+  printResultSummary('init', scope, results, options.accessKey);
+}
+
+function runAuth(options) {
+  const scope = resolveScope(options);
+  ensureSafeAuth('auth', scope, options.accessKey);
+  if (!options.accessKey) {
+    throw new Error(`Missing access key. Create one at ${NEUS_ACCESS_KEYS_URL} and rerun neus auth --access-key <npk_...>.`);
+  }
+
+  const clients = resolveClients(scope, options.clients);
+  ensureClientSelection(scope, clients);
+
+  const results = clients.map((client) => installClient(client, scope, options.accessKey, options.dryRun, process.cwd()));
+  const payload = {
+    command: 'auth',
+    scope,
+    clients,
+    accessKeyConfigured: true,
+    results,
+  };
+
+  if (options.json) {
+    printJson(payload);
+    return;
+  }
+  printResultSummary('auth', scope, results, options.accessKey);
 }
 
-if (sub === "init") {
-  printInit();
-  process.exit(0);
+function runStatus(options) {
+  const scope = resolveScope(options);
+  const clients = resolveClients(scope, options.clients);
+  ensureClientSelection(scope, clients);
+
+  const inspected = clients.map((client) => inspectClient(client, scope, process.cwd()));
+  const payload = {
+    command: 'status',
+    scope,
+    clients: inspected,
+  };
+
+  if (options.json) {
+    printJson(payload);
+    return;
+  }
+  printResultSummary('status', scope, inspected, '');
+}
+
+function main() {
+  try {
+    const { command, options } = parseArgs(process.argv.slice(2));
+
+    if (command === 'help') {
+      printUsage(0);
+      return;
+    }
+    if (command === 'init') {
+      runInit(options);
+      return;
+    }
+    if (command === 'auth') {
+      runAuth(options);
+      return;
+    }
+    if (command === 'status') {
+      runStatus(options);
+      return;
+    }
+
+    process.stderr.write(`Unknown subcommand: ${command}\n`);
+    printUsage(1);
+  } catch (error) {
+    process.stderr.write(`${error?.message || 'Unknown error'}\n`);
+    process.exit(1);
+  }
 }
 
-usage();
+main();

package/client.js

@@ -25,7 +25,13 @@ const FALLBACK_PUBLIC_VERIFIER_CATALOG = {
   'ai-content-moderation': { supportsDirectApi: true }
 };
 
-const EVM_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+const EVM_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+const WALLET_LINK_RELATIONSHIP_TYPES = new Set(['primary', 'personal', 'org', 'affiliate', 'agent', 'linked']);
+
+function normalizeWalletLinkRelationshipType(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return WALLET_LINK_RELATIONSHIP_TYPES.has(normalized) ? normalized : 'linked';
+}
 
 const validateVerifierData = (verifierId, data) => {
   if (!data || typeof data !== 'object') {
@@ -477,22 +483,98 @@ export class NeusClient {
     };
   }
 
-  async createGatePrivateAuth(params = {}) {
-    const address = (params.address || '').toString();
-    if (!validateUniversalAddress(address, params.chain)) {
-      throw new ValidationError('Valid address is required');
-    }
+  async createGatePrivateAuth(params = {}) {
+    const address = (params.address || '').toString();
+    if (!validateUniversalAddress(address, params.chain)) {
+      throw new ValidationError('Valid address is required');
+    }
     return this._buildPrivateGateAuth({
       address,
       wallet: params.wallet,
       chain: params.chain,
-      signatureMethod: params.signatureMethod
-    });
-  }
-
-  /**
-   * Create a verification proof.
-   *
+      signatureMethod: params.signatureMethod
+    });
+  }
+
+  async createWalletLinkData(params = {}) {
+    const normalizedPrimary = this._normalizeIdentity(params.primaryWalletAddress);
+    const normalizedSecondary = this._normalizeIdentity(params.secondaryWalletAddress);
+
+    if (!EVM_ADDRESS_RE.test(normalizedPrimary)) {
+      throw new ValidationError('wallet-link requires a valid primaryWalletAddress');
+    }
+    if (!EVM_ADDRESS_RE.test(normalizedSecondary)) {
+      throw new ValidationError('wallet-link requires a valid secondaryWalletAddress');
+    }
+    if (normalizedPrimary === normalizedSecondary) {
+      throw new ValidationError('wallet-link secondaryWalletAddress must differ from primaryWalletAddress');
+    }
+
+    const providerWallet = params.wallet || this._getDefaultBrowserWallet();
+    const { signerWalletAddress, provider } = await this._resolveWalletSigner(providerWallet);
+    const normalizedSigner = this._normalizeIdentity(signerWalletAddress);
+    if (!EVM_ADDRESS_RE.test(normalizedSigner)) {
+      throw new ValidationError('wallet-link requires an EVM wallet/provider for the secondary wallet');
+    }
+    if (normalizedSigner !== normalizedSecondary) {
+      throw new ValidationError('wallet-link wallet/provider must be connected to secondaryWalletAddress');
+    }
+
+    const resolvedChain = (() => {
+      const raw = String(params.chain || '').trim();
+      if (!raw) return `eip155:${this._getHubChainId()}`;
+      if (!/^eip155:\d+$/.test(raw)) {
+        throw new ValidationError('wallet-link requires chain in the form eip155:<chainId>');
+      }
+      return raw;
+    })();
+    const signedTimestamp = Number.isFinite(Number(params.signedTimestamp)) && Number(params.signedTimestamp) > 0
+      ? Number(params.signedTimestamp)
+      : Date.now();
+    const linkData = {
+      primaryAccountId: `${resolvedChain}:${normalizedPrimary}`,
+      secondaryAccountId: `${resolvedChain}:${normalizedSecondary}`,
+      primaryWalletAddress: normalizedPrimary,
+      secondaryWalletAddress: normalizedSecondary
+    };
+    const message = constructVerificationMessage({
+      walletAddress: normalizedSecondary,
+      signedTimestamp,
+      data: linkData,
+      verifierIds: ['wallet-link'],
+      chain: resolvedChain
+    });
+
+    let signature;
+    try {
+      signature = await signMessage({
+        provider,
+        message,
+        walletAddress: signerWalletAddress
+      });
+    } catch (error) {
+      if (error?.code === 4001) {
+        throw new ValidationError('User rejected wallet-link signature request');
+      }
+      throw new ValidationError(`Failed to sign wallet-link message: ${error?.message || String(error)}`);
+    }
+
+    const label = String(params.label || '').trim().slice(0, 64);
+    return {
+      primaryWalletAddress: normalizedPrimary,
+      secondaryWalletAddress: normalizedSecondary,
+      signature,
+      chain: resolvedChain,
+      signatureMethod: 'eip191',
+      signedTimestamp,
+      relationshipType: normalizeWalletLinkRelationshipType(params.relationshipType),
+      ...(label ? { label } : {})
+    };
+  }
+
+  /**
+   * Create a verification proof.
+   *
    * Supports two paths:
    *   - **Auto:** Supply `verifier`, `content`, and/or `data` with an optional
    *     `wallet` provider. The SDK performs signing in the client.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@neus/sdk",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Portable trust for people, apps, and agents. Store a proof ID; check gates across surfaces.",
   "bin": {
-    "neus": "./cli/neus.mjs"
+    "neus": "cli/neus.mjs"
   },
   "main": "index.js",
   "type": "module",

package/types.d.ts

@@ -54,6 +54,20 @@ declare module '@neus/sdk' {
 
     /** Get the public verifier catalog, including per-verifier capabilities. */
     getVerifierCatalog(): Promise<VerifierCatalog>;
+
+    /**
+     * Build and sign a wallet-link verifier payload with the secondary wallet.
+     * Use this for advanced direct/API flows; browser user-facing flows should still prefer hosted `/verify`.
+     */
+    createWalletLinkData(params: {
+      primaryWalletAddress: string;
+      secondaryWalletAddress: string;
+      wallet?: WalletLike;
+      chain?: string;
+      signedTimestamp?: number;
+      relationshipType?: 'primary' | 'personal' | 'org' | 'affiliate' | 'agent' | 'linked';
+      label?: string;
+    }): Promise<WalletLinkData>;
     
   /**
    * Poll verification status until completion

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

@@ -548,7 +548,7 @@ function VerifyGate({
           if (verifierId === "wallet-link") {
             if (!explicit?.secondaryWalletAddress || !explicit?.signature || !explicit?.chain || !explicit?.signatureMethod) {
               throw new Error(
-                "wallet-link requires verifierData: { secondaryWalletAddress, signature, chain, signatureMethod }"
+                "wallet-link direct mode requires verifierData: { secondaryWalletAddress, signature, chain, signatureMethod }. For user-facing flows, prefer hosted checkout."
               );
             }
             return explicit;