@neus/sdk 1.0.8 → 1.0.10

package/README.md

@@ -1,8 +1,8 @@
 # @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.
 
-**Portable trust, shipped as APIs and widgets.** The JavaScript SDK runs NEUS verification, polling, and **`gateCheck`**. Store **`proofId`**, then reuse it. NEUS runs the checks; you do not fork verifier logic into your repo.
+NEUS turns signed claims, ownership checks, account links, access rules, and verification results into portable receipts your app can store, display, and check later.
 
 ## Install
 
@@ -10,75 +10,168 @@
 npm install @neus/sdk
 ```
 
-## Minimal working example
+## What you can build
 
-```javascript
-import { NeusClient } from '@neus/sdk';
+- 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
 
-const client = new NeusClient();
+## Fastest path: Hosted Verify
 
-const proof = await client.verify({
-  verifier: 'ownership-basic',
-  content: 'Hello NEUS',
-  wallet: window.ethereum,
-});
+Use Hosted Verify when you want NEUS to handle the signing/verification flow outside your app UI.
 
-const proofId = proof.proofId;
+```js
+import { getHostedCheckoutUrl } from '@neus/sdk';
 
-const check = await client.gateCheck({
-  address: '0x...',
-  verifierIds: ['ownership-basic'],
+const url = getHostedCheckoutUrl({
+  verifiers: ['ownership-basic'],
+  returnUrl: 'https://yourapp.com/neus/callback'
 });
+
+window.location.assign(url);
 ```
 
-> [Hosted Verify](https://docs.neus.network/cookbook/auth-hosted-verify) | [Get started](https://docs.neus.network/get-started)
+After completion, NEUS redirects back with a `qHash`.
 
-## Core methods
+Store that `qHash` in your database next to your user, workspace, project, claim, listing, or record.
+
+## Create a signed receipt directly
+
+Use this when your app already controls the signing flow.
+
+```js
+import { NeusClient } from '@neus/sdk';
 
-| Method | Purpose |
-| --- | --- |
-| `client.verify()` | Create proof |
-| `client.getProof()` | Fetch by `proofId` |
-| `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 |
+const client = new NeusClient({
+  appId: 'your-app-id'
+});
 
-## VerifyGate (React)
+const proof = await client.verify({
+  verifier: 'ownership-basic',
+  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
+});
 
-Defaults: private create (`privacyLevel: 'private'`, `publicDisplay: false`). Set `proofOptions` only when you intentionally need public visibility.
+console.log(proof.qHash);
+console.log(proof.proofUrl);
+```
+
+## React widget
+
+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)
+Access keys are only for trusted server, IDE, or agent environments. 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.
+
+## Optional MCP setup
 
-- [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)
+Use MCP when you want IDEs, assistants, or agents to inspect receipts, check proof state, or work with NEUS tools.
+
+```bash
+npx -y -p @neus/sdk neus init
+```
 
-## Contributing
+Add account-aware/private access only when needed:
+
+```bash
+npx -y -p @neus/sdk neus auth --access-key <npk_...>
+```
+
+## 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

@@ -5,7 +5,7 @@ Treat **wallet signatures** and **API keys** as secrets. Do not log them, expose
 ## Authentication model
 
 - **Verification requests** are authenticated with a wallet signature over the **CAIP-380 Portable Proof** six-line signing string. Never roll your own message format in production—use the SDK or the hosted preparation step documented for HTTP integrations.
-- **Proof lookups by `proofId`** are safe for public proofs. Private proofs return a minimal payload unless the caller proves ownership (authenticated owner or signed request).
+- **Proof lookups by `qHash`** are safe for public proofs. Private proofs return a minimal payload unless the caller proves ownership (authenticated owner or signed request).
 - **Owner-only reads** of private proof payloads require an extra owner-signed request. The SDK attaches the required signed headers for you.
 
 ## Do not

package/cjs/client.cjs

@@ -1225,19 +1225,15 @@ ${bytes.length}`;
                 for (let i = 0; i < full.length; i++) payloadHex += full[i].toString(16).padStart(2, "0");
                 try {
                   if (typeof window !== "undefined") window.__NEUS_ALLOW_ETH_SIGN__ = true;
-                } catch {
-                }
-                signature2 = await provider.request({ method: "eth_sign", params: [walletAddress2, payloadHex], neusAllowEthSign: true });
-                try {
-                  if (typeof window !== "undefined") delete window.__NEUS_ALLOW_ETH_SIGN__;
-                } catch {
+                  signature2 = await provider.request({ method: "eth_sign", params: [walletAddress2, payloadHex], neusAllowEthSign: true });
+                } finally {
+                  try {
+                    if (typeof window !== "undefined") delete window.__NEUS_ALLOW_ETH_SIGN__;
+                  } catch {
+                  }
                 }
               } catch (fallbackErr) {
                 this._log("eth_sign fallback failed", { message: fallbackErr?.message || String(fallbackErr) });
-                try {
-                  if (typeof window !== "undefined") delete window.__NEUS_ALLOW_ETH_SIGN__;
-                } catch {
-                }
                 throw e;
               }
             } else if (needsHex) {
@@ -1331,19 +1327,21 @@ ${bytes.length}`;
     }
     return this._formatResponse(response);
   }
-  async getProof(proofId) {
-    if (!proofId || typeof proofId !== "string") {
-      throw new ValidationError("proofId is required");
+  async getProof(qHash) {
+    const resolvedQHash = qHash;
+    if (!resolvedQHash || typeof resolvedQHash !== "string") {
+      throw new ValidationError("qHash is required");
     }
-    const response = await this._makeRequest("GET", `/api/v1/proofs/${proofId}`);
+    const response = await this._makeRequest("GET", `/api/v1/proofs/${resolvedQHash}`);
     if (!response.success) {
       throw new ApiError(`Failed to get proof: ${response.error?.message || "Unknown error"}`, response.error);
     }
     return this._formatResponse(response);
   }
-  async getPrivateProof(proofId, wallet = null) {
-    if (!proofId || typeof proofId !== "string") {
-      throw new ValidationError("proofId is required");
+  async getPrivateProof(qHash, wallet = null) {
+    const resolvedQHash = qHash;
+    if (!resolvedQHash || typeof resolvedQHash !== "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";
     if (isPreSignedAuth) {
@@ -1355,7 +1353,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/${proofId}`, null, headers);
+      const response2 = await this._makeRequest("GET", `/api/v1/proofs/${resolvedQHash}`, null, headers);
       if (!response2.success) {
         throw new ApiError(
           `Failed to access private proof: ${response2.error?.message || "Unauthorized"}`,
@@ -1376,7 +1374,7 @@ ${bytes.length}`;
     const message = constructVerificationMessage({
       walletAddress,
       signedTimestamp,
-      data: { action: "access_private_proof", qHash: proofId },
+      data: { action: "access_private_proof", qHash: resolvedQHash },
       verifierIds: ["ownership-basic"],
       ...signerIsEvm ? { chainId: this._getHubChainId() } : { chain }
     });
@@ -1394,7 +1392,7 @@ ${bytes.length}`;
       }
       throw new ValidationError(`Failed to sign message: ${error.message}`);
     }
-    const response = await this._makeRequest("GET", `/api/v1/proofs/${proofId}`, null, {
+    const response = await this._makeRequest("GET", `/api/v1/proofs/${resolvedQHash}`, null, {
       "x-wallet-address": walletAddress,
       "x-signature": signature,
       "x-signed-timestamp": signedTimestamp.toString(),
@@ -1431,20 +1429,21 @@ ${bytes.length}`;
       meta: response.meta && typeof response.meta === "object" && !Array.isArray(response.meta) ? response.meta : {}
     };
   }
-  async pollProofStatus(proofId, options = {}) {
+  async pollProofStatus(qHash, options = {}) {
+    const resolvedQHash = qHash;
     const {
       interval = 5e3,
       timeout = 12e4,
       onProgress
     } = options;
-    if (!proofId || typeof proofId !== "string") {
-      throw new ValidationError("proofId is required");
+    if (!resolvedQHash || typeof resolvedQHash !== "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(proofId);
+        const status = await this.getProof(resolvedQHash);
         consecutiveRateLimits = 0;
         if (onProgress && typeof onProgress === "function") {
           onProgress(status.data || status);
@@ -1486,9 +1485,10 @@ ${bytes.length}`;
       throw new NetworkError(`Failed to detect chain ID: ${error.message}`);
     }
   }
-  async revokeOwnProof(proofId, wallet) {
-    if (!proofId || typeof proofId !== "string") {
-      throw new ValidationError("proofId is required");
+  async revokeOwnProof(qHash, wallet) {
+    const resolvedQHash = qHash;
+    if (!resolvedQHash || typeof resolvedQHash !== "string") {
+      throw new ValidationError("qHash is required");
     }
     const providerWallet = wallet || this._getDefaultBrowserWallet();
     const { signerWalletAddress: address, provider } = await this._resolveWalletSigner(providerWallet);
@@ -1502,7 +1502,7 @@ ${bytes.length}`;
     const message = constructVerificationMessage({
       walletAddress: address,
       signedTimestamp,
-      data: { action: "revoke_proof", qHash: proofId },
+      data: { action: "revoke_proof", qHash: resolvedQHash },
       verifierIds: ["ownership-basic"],
       ...signerIsEvm ? { chainId: this._getHubChainId() } : { chain }
     });
@@ -1520,15 +1520,11 @@ ${bytes.length}`;
       }
       throw new ValidationError(`Failed to sign revocation: ${error.message}`);
     }
-    const res = await fetch(`${this.config.apiUrl}/api/v1/proofs/revoke-self/${proofId}`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        walletAddress: address,
-        signature,
-        signedTimestamp,
-        ...signerIsEvm ? {} : { chain, signatureMethod }
-      })
+    const res = await this._makeRequest("POST", `/api/v1/proofs/revoke-self/${resolvedQHash}`, {
+      walletAddress: address,
+      signature,
+      signedTimestamp,
+      ...signerIsEvm ? {} : { chain, signatureMethod }
     });
     const json = await res.json();
     if (!json.success) {
@@ -1689,6 +1685,7 @@ ${bytes.length}`;
     setIfPresent("primaryWalletAddress", params.primaryWalletAddress);
     setIfPresent("secondaryWalletAddress", params.secondaryWalletAddress);
     setIfPresent("verificationMethod", params.verificationMethod);
+    setIfPresent("neusPersonhoodId", params.neusPersonhoodId);
     let headersOverride = null;
     if (params.includePrivate === true) {
       const provided = params.privateAuth && typeof params.privateAuth === "object" ? params.privateAuth : null;
@@ -1930,20 +1927,19 @@ ${bytes.length}`;
     }
   }
   _formatResponse(response) {
-    const proofId = response?.data?.proofId || response?.proofId || response?.data?.resource?.proofId || response?.data?.qHash || response?.qHash || response?.data?.resource?.qHash || response?.data?.id;
-    const qHash = response?.data?.qHash || response?.qHash || response?.data?.resource?.qHash || proofId || response?.data?.id;
-    const finalProofId = proofId || qHash || null;
-    const finalQHash = qHash || proofId || finalProofId;
+    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 status = response?.data?.status || response?.status || response?.data?.resource?.status || (response?.success ? "completed" : "unknown");
     return {
       success: response.success,
-      proofId: finalProofId,
-      qHash: finalQHash,
+      qHash,
       status,
       data: response.data,
       message: response.message,
       timestamp: Date.now(),
-      proofUrl: finalProofId ? `${this.baseUrl}/api/v1/proofs/${finalProofId}` : null
+      proofUrl: qHash ? `${this.baseUrl}/api/v1/proofs/${qHash}` : null
     };
   }
   _isTerminalStatus(status) {

package/cjs/index.cjs

@@ -1909,19 +1909,15 @@ ${bytes.length}`;
                     for (let i = 0; i < full.length; i++) payloadHex += full[i].toString(16).padStart(2, "0");
                     try {
                       if (typeof window !== "undefined") window.__NEUS_ALLOW_ETH_SIGN__ = true;
-                    } catch {
-                    }
-                    signature2 = await provider.request({ method: "eth_sign", params: [walletAddress2, payloadHex], neusAllowEthSign: true });
-                    try {
-                      if (typeof window !== "undefined") delete window.__NEUS_ALLOW_ETH_SIGN__;
-                    } catch {
+                      signature2 = await provider.request({ method: "eth_sign", params: [walletAddress2, payloadHex], neusAllowEthSign: true });
+                    } finally {
+                      try {
+                        if (typeof window !== "undefined") delete window.__NEUS_ALLOW_ETH_SIGN__;
+                      } catch {
+                      }
                     }
                   } catch (fallbackErr) {
                     this._log("eth_sign fallback failed", { message: fallbackErr?.message || String(fallbackErr) });
-                    try {
-                      if (typeof window !== "undefined") delete window.__NEUS_ALLOW_ETH_SIGN__;
-                    } catch {
-                    }
                     throw e;
                   }
                 } else if (needsHex) {
@@ -2015,19 +2011,21 @@ ${bytes.length}`;
         }
         return this._formatResponse(response);
       }
-      async getProof(proofId) {
-        if (!proofId || typeof proofId !== "string") {
-          throw new ValidationError("proofId is required");
+      async getProof(qHash) {
+        const resolvedQHash = qHash;
+        if (!resolvedQHash || typeof resolvedQHash !== "string") {
+          throw new ValidationError("qHash is required");
         }
-        const response = await this._makeRequest("GET", `/api/v1/proofs/${proofId}`);
+        const response = await this._makeRequest("GET", `/api/v1/proofs/${resolvedQHash}`);
         if (!response.success) {
           throw new ApiError(`Failed to get proof: ${response.error?.message || "Unknown error"}`, response.error);
         }
         return this._formatResponse(response);
       }
-      async getPrivateProof(proofId, wallet = null) {
-        if (!proofId || typeof proofId !== "string") {
-          throw new ValidationError("proofId is required");
+      async getPrivateProof(qHash, wallet = null) {
+        const resolvedQHash = qHash;
+        if (!resolvedQHash || typeof resolvedQHash !== "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";
         if (isPreSignedAuth) {
@@ -2039,7 +2037,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/${proofId}`, null, headers);
+          const response2 = await this._makeRequest("GET", `/api/v1/proofs/${resolvedQHash}`, null, headers);
           if (!response2.success) {
             throw new ApiError(
               `Failed to access private proof: ${response2.error?.message || "Unauthorized"}`,
@@ -2060,7 +2058,7 @@ ${bytes.length}`;
         const message = constructVerificationMessage({
           walletAddress,
           signedTimestamp,
-          data: { action: "access_private_proof", qHash: proofId },
+          data: { action: "access_private_proof", qHash: resolvedQHash },
           verifierIds: ["ownership-basic"],
           ...signerIsEvm ? { chainId: this._getHubChainId() } : { chain }
         });
@@ -2078,7 +2076,7 @@ ${bytes.length}`;
           }
           throw new ValidationError(`Failed to sign message: ${error.message}`);
         }
-        const response = await this._makeRequest("GET", `/api/v1/proofs/${proofId}`, null, {
+        const response = await this._makeRequest("GET", `/api/v1/proofs/${resolvedQHash}`, null, {
           "x-wallet-address": walletAddress,
           "x-signature": signature,
           "x-signed-timestamp": signedTimestamp.toString(),
@@ -2115,20 +2113,21 @@ ${bytes.length}`;
           meta: response.meta && typeof response.meta === "object" && !Array.isArray(response.meta) ? response.meta : {}
         };
       }
-      async pollProofStatus(proofId, options = {}) {
+      async pollProofStatus(qHash, options = {}) {
+        const resolvedQHash = qHash;
         const {
           interval = 5e3,
           timeout = 12e4,
           onProgress
         } = options;
-        if (!proofId || typeof proofId !== "string") {
-          throw new ValidationError("proofId is required");
+        if (!resolvedQHash || typeof resolvedQHash !== "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(proofId);
+            const status = await this.getProof(resolvedQHash);
             consecutiveRateLimits = 0;
             if (onProgress && typeof onProgress === "function") {
               onProgress(status.data || status);
@@ -2170,9 +2169,10 @@ ${bytes.length}`;
           throw new NetworkError(`Failed to detect chain ID: ${error.message}`);
         }
       }
-      async revokeOwnProof(proofId, wallet) {
-        if (!proofId || typeof proofId !== "string") {
-          throw new ValidationError("proofId is required");
+      async revokeOwnProof(qHash, wallet) {
+        const resolvedQHash = qHash;
+        if (!resolvedQHash || typeof resolvedQHash !== "string") {
+          throw new ValidationError("qHash is required");
         }
         const providerWallet = wallet || this._getDefaultBrowserWallet();
         const { signerWalletAddress: address, provider } = await this._resolveWalletSigner(providerWallet);
@@ -2186,7 +2186,7 @@ ${bytes.length}`;
         const message = constructVerificationMessage({
           walletAddress: address,
           signedTimestamp,
-          data: { action: "revoke_proof", qHash: proofId },
+          data: { action: "revoke_proof", qHash: resolvedQHash },
           verifierIds: ["ownership-basic"],
           ...signerIsEvm ? { chainId: this._getHubChainId() } : { chain }
         });
@@ -2204,15 +2204,11 @@ ${bytes.length}`;
           }
           throw new ValidationError(`Failed to sign revocation: ${error.message}`);
         }
-        const res = await fetch(`${this.config.apiUrl}/api/v1/proofs/revoke-self/${proofId}`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            walletAddress: address,
-            signature,
-            signedTimestamp,
-            ...signerIsEvm ? {} : { chain, signatureMethod }
-          })
+        const res = await this._makeRequest("POST", `/api/v1/proofs/revoke-self/${resolvedQHash}`, {
+          walletAddress: address,
+          signature,
+          signedTimestamp,
+          ...signerIsEvm ? {} : { chain, signatureMethod }
         });
         const json = await res.json();
         if (!json.success) {
@@ -2373,6 +2369,7 @@ ${bytes.length}`;
         setIfPresent("primaryWalletAddress", params.primaryWalletAddress);
         setIfPresent("secondaryWalletAddress", params.secondaryWalletAddress);
         setIfPresent("verificationMethod", params.verificationMethod);
+        setIfPresent("neusPersonhoodId", params.neusPersonhoodId);
         let headersOverride = null;
         if (params.includePrivate === true) {
           const provided = params.privateAuth && typeof params.privateAuth === "object" ? params.privateAuth : null;
@@ -2614,20 +2611,19 @@ ${bytes.length}`;
         }
       }
       _formatResponse(response) {
-        const proofId = response?.data?.proofId || response?.proofId || response?.data?.resource?.proofId || response?.data?.qHash || response?.qHash || response?.data?.resource?.qHash || response?.data?.id;
-        const qHash = response?.data?.qHash || response?.qHash || response?.data?.resource?.qHash || proofId || response?.data?.id;
-        const finalProofId = proofId || qHash || null;
-        const finalQHash = qHash || proofId || finalProofId;
+        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 status = response?.data?.status || response?.status || response?.data?.resource?.status || (response?.success ? "completed" : "unknown");
         return {
           success: response.success,
-          proofId: finalProofId,
-          qHash: finalQHash,
+          qHash,
           status,
           data: response.data,
           message: response.message,
           timestamp: Date.now(),
-          proofUrl: finalProofId ? `${this.baseUrl}/api/v1/proofs/${finalProofId}` : null
+          proofUrl: qHash ? `${this.baseUrl}/api/v1/proofs/${qHash}` : null
         };
       }
       _isTerminalStatus(status) {