@neus/sdk 1.0.2 → 1.0.4

package/cjs/client.cjs

@@ -1,3 +1,4 @@
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -20,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var client_exports = {};
 __export(client_exports, {
   NeusClient: () => NeusClient,
+  PORTABLE_PROOF_SIGNER_HEADER: () => PORTABLE_PROOF_SIGNER_HEADER,
   constructVerificationMessage: () => constructVerificationMessage
 });
 module.exports = __toCommonJS(client_exports);
@@ -128,21 +130,77 @@ var ConfigurationError = class extends SDKError {
 };
 
 // utils.js
+var PORTABLE_PROOF_SIGNER_HEADER = "Portable Proof Verification Request";
+var BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function encodeBase58Bytes(input) {
+  let source;
+  if (input instanceof Uint8Array) {
+    source = input;
+  } else if (input instanceof ArrayBuffer) {
+    source = new Uint8Array(input);
+  } else if (ArrayBuffer.isView(input)) {
+    source = new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+  } else if (typeof Buffer !== "undefined" && typeof Buffer.isBuffer === "function" && Buffer.isBuffer(input)) {
+    source = new Uint8Array(input);
+  } else {
+    throw new SDKError("Unsupported non-EVM signature byte format", "INVALID_SIGNATURE_FORMAT");
+  }
+  if (source.length === 0) return "";
+  let zeroes = 0;
+  while (zeroes < source.length && source[zeroes] === 0) {
+    zeroes++;
+  }
+  const iFactor = Math.log(256) / Math.log(58);
+  const size = (source.length - zeroes) * iFactor + 1 >>> 0;
+  const b58 = new Uint8Array(size);
+  let length = 0;
+  for (let i = zeroes; i < source.length; i++) {
+    let carry = source[i];
+    let j = 0;
+    for (let k = size - 1; (carry !== 0 || j < length) && k >= 0; k--, j++) {
+      carry += 256 * b58[k];
+      b58[k] = carry % 58;
+      carry = carry / 58 | 0;
+    }
+    length = j;
+  }
+  let it = size - length;
+  while (it < size && b58[it] === 0) {
+    it++;
+  }
+  let out = BASE58_ALPHABET[0].repeat(zeroes);
+  for (; it < size; it++) {
+    out += BASE58_ALPHABET[b58[it]];
+  }
+  return out;
+}
 function deterministicStringify(obj) {
   if (obj === null || obj === void 0) {
     return JSON.stringify(obj);
   }
   if (typeof obj !== "object") {
+    if (typeof obj === "string") return JSON.stringify(obj.normalize("NFC"));
     return JSON.stringify(obj);
   }
   if (Array.isArray(obj)) {
-    return "[" + obj.map((item) => deterministicStringify(item)).join(",") + "]";
+    return `[${obj.map((item) => item === void 0 ? "null" : deterministicStringify(item)).join(",")}]`;
   }
-  const sortedKeys = Object.keys(obj).sort();
+  const sortedKeys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
   const pairs = sortedKeys.map(
-    (key) => JSON.stringify(key) + ":" + deterministicStringify(obj[key])
+    (key) => `${JSON.stringify(key)}:${deterministicStringify(obj[key])}`
   );
-  return "{" + pairs.join(",") + "}";
+  return `{${pairs.join(",")}}`;
+}
+function chainLineForPortableProofSigner(chain, chainId) {
+  if (typeof chain === "string" && chain.length > 0) {
+    const m = chain.match(/^eip155:(\d+)$/);
+    if (m) return Number(m[1]);
+    return chain;
+  }
+  if (typeof chainId === "number" && Number.isFinite(chainId) && chainId > 0) {
+    return chainId;
+  }
+  throw new SDKError("chainId is required (or provide chain for universal mode)", "INVALID_CHAIN_CONTEXT");
 }
 function constructVerificationMessage({ walletAddress, signedTimestamp, data, verifierIds, chainId, chain }) {
   if (!walletAddress || typeof walletAddress !== "string") {
@@ -157,28 +215,28 @@ function constructVerificationMessage({ walletAddress, signedTimestamp, data, ve
   if (!Array.isArray(verifierIds) || verifierIds.length === 0) {
     throw new SDKError("verifierIds is required and must be a non-empty array", "INVALID_VERIFIER_IDS");
   }
-  const chainContext = typeof chain === "string" && chain.length > 0 ? chain : chainId;
-  if (!chainContext) {
+  if ((typeof chain !== "string" || !chain.length) && !(typeof chainId === "number" && chainId > 0)) {
     throw new SDKError("chainId is required (or provide chain for universal mode)", "INVALID_CHAIN_CONTEXT");
   }
-  if (chainContext === chainId && typeof chainId !== "number") {
-    throw new SDKError("chainId must be a number when provided", "INVALID_CHAIN_ID");
-  }
-  if (chainContext === chain && (typeof chain !== "string" || !chain.includes(":"))) {
+  if (typeof chain === "string" && chain.length > 0 && !chain.includes(":")) {
     throw new SDKError('chain must be a "namespace:reference" string', "INVALID_CHAIN");
   }
+  if ((!chain || !chain.length) && typeof chainId !== "number") {
+    throw new SDKError("chainId must be a number when provided", "INVALID_CHAIN_ID");
+  }
+  const chainLine = chainLineForPortableProofSigner(chain, chainId);
   const namespace = typeof chain === "string" && chain.includes(":") ? chain.split(":")[0] : "eip155";
   const normalizedWalletAddress = namespace === "eip155" ? walletAddress.toLowerCase() : walletAddress;
   const dataString = deterministicStringify(data);
   const messageComponents = [
-    "NEUS Verification Request",
+    PORTABLE_PROOF_SIGNER_HEADER,
     `Wallet: ${normalizedWalletAddress}`,
-    `Chain: ${chainContext}`,
+    `Chain: ${chainLine}`,
     `Verifiers: ${verifierIds.join(",")}`,
     `Data: ${dataString}`,
     `Timestamp: ${signedTimestamp}`
   ];
-  return messageComponents.join("\n");
+  return messageComponents.join("\n").normalize("NFC");
 }
 function validateWalletAddress(address) {
   if (!address || typeof address !== "string") {
@@ -186,8 +244,127 @@ function validateWalletAddress(address) {
   }
   return /^0x[a-fA-F0-9]{40}$/.test(address);
 }
+function validateUniversalAddress(address, chain) {
+  if (!address || typeof address !== "string") return false;
+  const value = address.trim();
+  if (!value) return false;
+  const chainRef = typeof chain === "string" ? chain.trim().toLowerCase() : "";
+  const namespace = chainRef.includes(":") ? chainRef.split(":")[0] : "";
+  if (validateWalletAddress(value)) return true;
+  if (namespace === "eip155") return false;
+  if (namespace === "solana") {
+    return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value);
+  }
+  if (namespace === "bip122") {
+    return /^(bc1|tb1|bcrt1)[a-z0-9]{11,87}$/.test(value.toLowerCase()) || /^[13mn2][a-km-zA-HJ-NP-Z1-9]{25,62}$/.test(value);
+  }
+  if (namespace === "near") {
+    return /^[a-z0-9._-]{2,64}$/.test(value);
+  }
+  return /^[A-Za-z0-9][A-Za-z0-9._:-]{1,127}$/.test(value);
+}
+function toHexUtf8(value) {
+  const input = typeof value === "string" ? value : String(value || "");
+  const bytes = new TextEncoder().encode(input);
+  return `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+async function signMessage({ provider, message, walletAddress, chain } = {}) {
+  const msg = typeof message === "string" ? message : String(message || "");
+  if (!msg) {
+    throw new SDKError("signMessage: message is required", "INVALID_ARGUMENT");
+  }
+  const resolvedProvider = provider || (typeof window !== "undefined" && window?.ethereum ? window.ethereum : null);
+  if (!resolvedProvider) {
+    throw new SDKError("signMessage: provider is required", "SIGNER_UNAVAILABLE");
+  }
+  const chainStr = typeof chain === "string" && chain.trim().length > 0 ? chain.trim() : "eip155";
+  const namespace = chainStr.includes(":") ? chainStr.split(":")[0] || "eip155" : "eip155";
+  const resolveAddress = async () => {
+    if (typeof walletAddress === "string" && walletAddress.trim().length > 0) return walletAddress;
+    if (namespace === "solana") {
+      if (resolvedProvider?.publicKey && typeof resolvedProvider.publicKey.toBase58 === "function") {
+        const pk = resolvedProvider.publicKey.toBase58();
+        if (typeof pk === "string" && pk) return pk;
+      }
+      if (typeof resolvedProvider.getAddress === "function") {
+        const addr = await resolvedProvider.getAddress().catch(() => null);
+        if (typeof addr === "string" && addr) return addr;
+      }
+      if (typeof resolvedProvider.address === "string" && resolvedProvider.address) return resolvedProvider.address;
+      return null;
+    }
+    if (typeof resolvedProvider.address === "string" && resolvedProvider.address) return resolvedProvider.address;
+    if (typeof resolvedProvider.getAddress === "function") return resolvedProvider.getAddress();
+    if (typeof resolvedProvider.request === "function") {
+      let accounts = await resolvedProvider.request({ method: "eth_accounts" }).catch(() => []);
+      if (!Array.isArray(accounts) || accounts.length === 0) {
+        accounts = await resolvedProvider.request({ method: "eth_requestAccounts" }).catch(() => []);
+      }
+      if (Array.isArray(accounts) && accounts[0]) return accounts[0];
+    }
+    return null;
+  };
+  if (namespace !== "eip155") {
+    if (typeof resolvedProvider.signMessage === "function") {
+      const encoded = typeof msg === "string" ? new TextEncoder().encode(msg) : msg;
+      const result = await resolvedProvider.signMessage(encoded);
+      if (typeof result === "string" && result) return result;
+      if (result instanceof Uint8Array) return encodeBase58Bytes(result);
+      if (result instanceof ArrayBuffer) return encodeBase58Bytes(new Uint8Array(result));
+      if (ArrayBuffer.isView(result)) return encodeBase58Bytes(result);
+      if (typeof Buffer !== "undefined" && typeof Buffer.isBuffer === "function" && Buffer.isBuffer(result)) return encodeBase58Bytes(result);
+    }
+    throw new SDKError("Non-EVM signing requires provider.signMessage", "SIGNER_UNAVAILABLE");
+  }
+  const address = await resolveAddress();
+  if (typeof resolvedProvider.request === "function" && address) {
+    let firstPersonalSignError = null;
+    try {
+      const sig = await resolvedProvider.request({ method: "personal_sign", params: [msg, address] });
+      if (typeof sig === "string" && sig) return sig;
+    } catch (error) {
+      firstPersonalSignError = error;
+    }
+    let secondPersonalSignError = null;
+    try {
+      const sig = await resolvedProvider.request({ method: "personal_sign", params: [address, msg] });
+      if (typeof sig === "string" && sig) return sig;
+    } catch (error) {
+      secondPersonalSignError = error;
+      const signatureErrorMessage = String(
+        error?.message || error?.reason || firstPersonalSignError?.message || firstPersonalSignError?.reason || ""
+      ).toLowerCase();
+      const needsHex = /byte|bytes|invalid byte sequence|encoding|non-hex/i.test(signatureErrorMessage);
+      if (needsHex) {
+        try {
+          const hexMsg = toHexUtf8(msg);
+          const sig = await resolvedProvider.request({ method: "personal_sign", params: [hexMsg, address] });
+          if (typeof sig === "string" && sig) return sig;
+        } catch {
+        }
+      }
+    }
+    try {
+      const sig = await resolvedProvider.request({ method: "eth_sign", params: [address, msg] });
+      if (typeof sig === "string" && sig) return sig;
+    } catch {
+    }
+    if (secondPersonalSignError || firstPersonalSignError) {
+      const lastError = secondPersonalSignError || firstPersonalSignError;
+      const isUserRejection = [4001, "ACTION_REJECTED"].includes(lastError?.code);
+      if (isUserRejection) {
+        throw lastError;
+      }
+    }
+  }
+  if (typeof resolvedProvider.signMessage === "function") {
+    const result = await resolvedProvider.signMessage(msg);
+    if (typeof result === "string" && result) return result;
+  }
+  throw new SDKError("Unable to sign message with provided wallet/provider", "SIGNER_UNAVAILABLE");
+}
 var NEUS_CONSTANTS = {
-  // Hub chain (where all verifications occur)
+  /** Default EVM chain id for NEUS protocol signing context (`HUB_CHAIN_ID` name kept for compatibility). */
   HUB_CHAIN_ID: 84532,
   // Supported target chains for cross-chain propagation
   TESTNET_CHAINS: [
@@ -217,18 +394,31 @@ var NEUS_CONSTANTS = {
 };
 
 // client.js
+var FALLBACK_PUBLIC_VERIFIER_CATALOG = {
+  "ownership-basic": { supportsDirectApi: true },
+  "ownership-pseudonym": { supportsDirectApi: true },
+  "ownership-dns-txt": { supportsDirectApi: true },
+  "ownership-social": { supportsDirectApi: false },
+  "ownership-org-oauth": { supportsDirectApi: false },
+  "contract-ownership": { supportsDirectApi: true },
+  "nft-ownership": { supportsDirectApi: true },
+  "token-holding": { supportsDirectApi: true },
+  "wallet-link": { supportsDirectApi: true },
+  "wallet-risk": { supportsDirectApi: true },
+  "proof-of-human": { supportsDirectApi: false },
+  "agent-identity": { supportsDirectApi: true },
+  "agent-delegation": { supportsDirectApi: true },
+  "ai-content-moderation": { supportsDirectApi: true }
+};
+var EVM_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
 var validateVerifierData = (verifierId, data) => {
   if (!data || typeof data !== "object") {
     return { valid: false, error: "Data object is required" };
   }
-  const ownerField = verifierId === "nft-ownership" || verifierId === "token-holding" ? "ownerAddress" : "owner";
-  if (data[ownerField] && !validateWalletAddress(data[ownerField])) {
-    return { valid: false, error: `Invalid ${ownerField} address` };
-  }
   switch (verifierId) {
     case "ownership-basic":
-      if (!data.owner || !validateWalletAddress(data.owner)) {
-        return { valid: false, error: "owner (wallet address) is required" };
+      if (!data.owner || !validateUniversalAddress(data.owner, typeof data.chain === "string" ? data.chain : void 0)) {
+        return { valid: false, error: "owner (universal wallet address) is required" };
       }
       if (data.content !== void 0 && data.content !== null) {
         if (typeof data.content !== "string") {
@@ -354,17 +544,20 @@ var validateVerifierData = (verifierId, data) => {
       }
       break;
     case "wallet-link":
-      if (!data.primaryWalletAddress || !validateWalletAddress(data.primaryWalletAddress)) {
+      if (!data.primaryWalletAddress || !validateUniversalAddress(data.primaryWalletAddress, data.chain)) {
         return { valid: false, error: "primaryWalletAddress is required" };
       }
-      if (!data.secondaryWalletAddress || !validateWalletAddress(data.secondaryWalletAddress)) {
+      if (!data.secondaryWalletAddress || !validateUniversalAddress(data.secondaryWalletAddress, data.chain)) {
         return { valid: false, error: "secondaryWalletAddress is required" };
       }
       if (!data.signature || typeof data.signature !== "string") {
         return { valid: false, error: "signature is required (signed by secondary wallet)" };
       }
-      if (typeof data.chainId !== "number") {
-        return { valid: false, error: "chainId is required" };
+      if (typeof data.chain !== "string" || !/^[a-z0-9]+:[^\s]+$/.test(data.chain)) {
+        return { valid: false, error: "chain is required (namespace:reference)" };
+      }
+      if (typeof data.signatureMethod !== "string" || !data.signatureMethod.trim()) {
+        return { valid: false, error: "signatureMethod is required" };
       }
       if (typeof data.signedTimestamp !== "number") {
         return { valid: false, error: "signedTimestamp is required" };
@@ -435,7 +628,10 @@ var validateVerifierData = (verifierId, data) => {
             const maxBytes = 50 * 1024;
             const bytes = typeof TextEncoder !== "undefined" ? new TextEncoder().encode(data.content).length : String(data.content).length;
             if (bytes > maxBytes) {
-              return { valid: false, error: `content exceeds ${maxBytes} bytes limit for ai-content-moderation verifier (text)` };
+              return {
+                valid: false,
+                error: `content exceeds ${maxBytes} bytes limit for ai-content-moderation verifier (text)`
+              };
             }
           } catch {
           }
@@ -459,7 +655,7 @@ var validateVerifierData = (verifierId, data) => {
       }
       break;
     case "wallet-risk":
-      if (data.walletAddress && !validateWalletAddress(data.walletAddress)) {
+      if (data.walletAddress && !validateUniversalAddress(data.walletAddress, data.chain)) {
         return { valid: false, error: "Invalid walletAddress" };
       }
       break;
@@ -491,6 +687,21 @@ var NeusClient = class {
     if (typeof this.config.apiKey === "string" && this.config.apiKey.trim().length > 0) {
       this.defaultHeaders["Authorization"] = `Bearer ${this.config.apiKey.trim()}`;
     }
+    if (typeof this.config.appId === "string" && this.config.appId.trim().length > 0) {
+      this.defaultHeaders["X-Neus-App"] = this.config.appId.trim();
+    }
+    if (typeof this.config.paymentSignature === "string" && this.config.paymentSignature.trim().length > 0) {
+      this.defaultHeaders["PAYMENT-SIGNATURE"] = this.config.paymentSignature.trim();
+    }
+    if (this.config.extraHeaders && typeof this.config.extraHeaders === "object") {
+      for (const [k, v] of Object.entries(this.config.extraHeaders)) {
+        if (!k || v === void 0 || v === null) continue;
+        const key = String(k).trim();
+        const value = String(v).trim();
+        if (!key || !value) continue;
+        this.defaultHeaders[key] = value;
+      }
+    }
     try {
       if (typeof window !== "undefined" && window.location && window.location.origin) {
         this.defaultHeaders["X-Client-Origin"] = window.location.origin;
@@ -498,87 +709,183 @@ var NeusClient = class {
     } catch {
     }
   }
-  // ============================================================================
-  // CORE VERIFICATION METHODS
-  // ============================================================================
+  _getHubChainId() {
+    const configured = Number(this.config?.hubChainId);
+    if (Number.isFinite(configured) && configured > 0) return Math.floor(configured);
+    return NEUS_CONSTANTS.HUB_CHAIN_ID;
+  }
+  _normalizeIdentity(value) {
+    let raw = String(value || "").trim();
+    if (!raw) return "";
+    const didMatch = raw.match(/^did:pkh:([^:]+):([^:]+):(.+)$/i);
+    if (didMatch && didMatch[3]) {
+      raw = String(didMatch[3]).trim();
+    }
+    return EVM_ADDRESS_RE.test(raw) ? raw.toLowerCase() : raw;
+  }
+  _inferChainForAddress(address, explicitChain) {
+    if (typeof explicitChain === "string" && explicitChain.includes(":")) return explicitChain.trim();
+    const raw = String(address || "").trim();
+    const didMatch = raw.match(/^did:pkh:([^:]+):([^:]+):(.+)$/i);
+    if (didMatch && didMatch[1] && didMatch[2]) {
+      return `${didMatch[1]}:${didMatch[2]}`;
+    }
+    if (EVM_ADDRESS_RE.test(raw)) {
+      return `eip155:${this._getHubChainId()}`;
+    }
+    return "solana:mainnet";
+  }
+  async _resolveWalletSigner(wallet) {
+    if (!wallet) {
+      throw new ConfigurationError("No wallet provider available");
+    }
+    if (wallet.address) {
+      return { signerWalletAddress: wallet.address, provider: wallet };
+    }
+    if (wallet.publicKey && typeof wallet.publicKey.toBase58 === "function") {
+      return { signerWalletAddress: wallet.publicKey.toBase58(), provider: wallet };
+    }
+    if (typeof wallet.getAddress === "function") {
+      const signerWalletAddress = await wallet.getAddress().catch(() => null);
+      return { signerWalletAddress, provider: wallet };
+    }
+    if (wallet.selectedAddress || wallet.request) {
+      const provider = wallet;
+      if (wallet.selectedAddress) {
+        return { signerWalletAddress: wallet.selectedAddress, provider };
+      }
+      const accounts = await provider.request({ method: "eth_accounts" });
+      if (!accounts || accounts.length === 0) {
+        throw new ConfigurationError("No wallet accounts available");
+      }
+      return { signerWalletAddress: accounts[0], provider };
+    }
+    throw new ConfigurationError("Invalid wallet provider");
+  }
+  _getDefaultBrowserWallet() {
+    if (typeof window === "undefined") return null;
+    return window.ethereum || window.solana || window.phantom && window.phantom.solana || null;
+  }
+  async _buildPrivateGateAuth({ address, wallet, chain, signatureMethod } = {}) {
+    const providerWallet = wallet || this._getDefaultBrowserWallet();
+    const { signerWalletAddress, provider } = await this._resolveWalletSigner(providerWallet);
+    if (!signerWalletAddress || typeof signerWalletAddress !== "string") {
+      throw new ConfigurationError("No wallet accounts available");
+    }
+    const normalizedSigner = this._normalizeIdentity(signerWalletAddress);
+    const normalizedAddress = this._normalizeIdentity(address);
+    if (!normalizedSigner || normalizedSigner !== normalizedAddress) {
+      throw new ValidationError("wallet must match address when includePrivate=true");
+    }
+    const signerIsEvm = EVM_ADDRESS_RE.test(normalizedSigner);
+    const resolvedChain = this._inferChainForAddress(normalizedSigner, chain);
+    const resolvedSignatureMethod = typeof signatureMethod === "string" && signatureMethod.trim() ? signatureMethod.trim() : signerIsEvm ? "eip191" : "ed25519";
+    const signedTimestamp = Date.now();
+    const message = constructVerificationMessage({
+      walletAddress: signerWalletAddress,
+      signedTimestamp,
+      data: { action: "gate_check_private_proofs", walletAddress: normalizedAddress },
+      verifierIds: ["ownership-basic"],
+      ...signerIsEvm ? { chainId: this._getHubChainId() } : { chain: resolvedChain }
+    });
+    let signature;
+    try {
+      signature = await signMessage({
+        provider,
+        message,
+        walletAddress: signerWalletAddress,
+        ...signerIsEvm ? {} : { chain: resolvedChain }
+      });
+    } catch (error) {
+      if (error.code === 4001) {
+        throw new ValidationError("User rejected signature request");
+      }
+      throw new ValidationError(`Failed to sign message: ${error.message}`);
+    }
+    return {
+      walletAddress: signerWalletAddress,
+      signature,
+      signedTimestamp,
+      ...signerIsEvm ? {} : { chain: resolvedChain, signatureMethod: resolvedSignatureMethod }
+    };
+  }
+  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
+    });
+  }
   /**
-   * VERIFY - Standard verification (auto or manual)
-   * 
-   * Create proofs with complete control over the verification process.
-   * If signature and walletAddress are omitted but verifier/content are provided,
-   * this method performs the wallet flow inline (no aliases, no secondary methods).
-   * 
+   * 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.
+   *   - **Manual:** Supply pre-signed `verifierIds`, `data`, `walletAddress`,
+   *     `signature`, and `signedTimestamp`.
+   *
    * @param {Object} params - Verification parameters
+   * @param {string} [params.verifier] - Verifier ID (auto path, e.g. 'ownership-basic')
+   * @param {string} [params.content] - Content to verify (auto path)
+   * @param {Object} [params.data] - Structured verification data
+   * @param {Object} [params.wallet] - Wallet provider (auto path)
+   * @param {Object} [params.options] - Additional options
    * @param {Array<string>} [params.verifierIds] - Array of verifier IDs (manual path)
-   * @param {Object} [params.data] - Verification data object (manual path)
    * @param {string} [params.walletAddress] - Wallet address that signed the request (manual path)
    * @param {string} [params.signature] - EIP-191 signature (manual path)
    * @param {number} [params.signedTimestamp] - Unix timestamp when signature was created (manual path)
-   * @param {number} [params.chainId] - Chain ID for verification context (optional, managed by protocol)
-   * @param {Object} [params.options] - Additional options
-   * @param {string} [params.verifier] - Verifier ID (auto path)
-   * @param {string} [params.content] - Content/description (auto path)
-   * @param {Object} [params.wallet] - Optional injected wallet/provider (auto path)
-   * @returns {Promise<Object>} Verification result with qHash
-   * 
+   * @param {number} [params.chainId] - EVM signing-context hint; when omitted, resolved to the NEUS protocol primary chain for signing
+   * @returns {Promise<Object>} Verification result with proofId
+   *
    * @example
+   * // Auto path
+   * const proof = await client.verify({
+   *   verifier: 'ownership-basic',
+   *   content: 'Hello World',
+   *   wallet: window.ethereum
+   * });
+   *
+   * @example
+   * // Manual path
    * const proof = await client.verify({
    *   verifierIds: ['ownership-basic'],
-   *   data: {
-   *     content: "My content",
-   *     owner: walletAddress, // or ownerAddress for nft-ownership/token-holding
-   *     reference: { type: 'other', id: 'my-unique-identifier' }
-   *   },
+   *   data: { content: "My content", owner: walletAddress },
    *   walletAddress: '0x...',
    *   signature: '0x...',
    *   signedTimestamp: Date.now(),
    *   options: { targetChains: [421614, 11155111] }
    * });
    */
-  /**
-   * Create a verification proof
-   *
-   * @param {Object} params - Verification parameters
-   * @param {string} [params.verifier] - Verifier ID (e.g., 'ownership-basic')
-   * @param {string} [params.content] - Content to verify
-   * @param {Object} [params.data] - Structured verification data
-   * @param {Object} [params.wallet] - Wallet provider
-   * @param {Object} [params.options] - Additional options
-   * @returns {Promise<Object>} Verification result with qHash
-   *
-   * @example
-   * // Simple ownership proof
-   * const proof = await client.verify({
-   *   verifier: 'ownership-basic',
-   *   content: 'Hello World',
-   *   wallet: window.ethereum
-   * });
-   */
   async verify(params) {
     if ((!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)");
       }
-      const validVerifiers = [
-        "ownership-basic",
-        "ownership-pseudonym",
-        // Pseudonymous identity (public)
-        "nft-ownership",
-        "token-holding",
-        "ownership-dns-txt",
-        "wallet-link",
-        "contract-ownership",
-        "wallet-risk",
-        // Wallet risk assessment (public)
-        // AI & Agent verifiers (ERC-8004 aligned)
-        "agent-identity",
-        "agent-delegation",
-        "ai-content-moderation"
-      ];
+      let verifierCatalog = FALLBACK_PUBLIC_VERIFIER_CATALOG;
+      try {
+        const discovered = await this.getVerifierCatalog();
+        if (discovered && discovered.metadata && Object.keys(discovered.metadata).length > 0) {
+          verifierCatalog = discovered.metadata;
+        }
+      } catch {
+      }
+      const validVerifiers = Object.keys(verifierCatalog);
       if (!validVerifiers.includes(verifier)) {
         throw new ValidationError(`Invalid verifier '${verifier}'. Must be one of: ${validVerifiers.join(", ")}.`);
       }
+      if (verifierCatalog?.[verifier]?.supportsDirectApi === false) {
+        const hostedCheckoutUrl = options2?.hostedCheckoutUrl || "https://neus.network/verify";
+        throw new ValidationError(
+          `${verifier} requires hosted interactive checkout. Use VerifyGate or redirect to ${hostedCheckoutUrl}.`
+        );
+      }
       const requiresDataParam = [
         "ownership-dns-txt",
         "wallet-link",
@@ -596,8 +903,12 @@ var NeusClient = class {
       }
       let walletAddress2, provider;
       if (wallet) {
-        walletAddress2 = wallet.address || wallet.selectedAddress;
+        walletAddress2 = wallet.address || wallet.selectedAddress || wallet.walletAddress || (typeof wallet.getAddress === "function" ? await wallet.getAddress() : null);
         provider = wallet.provider || wallet;
+        if (!walletAddress2 && provider && typeof provider.request === "function") {
+          const accounts = await provider.request({ method: "eth_accounts" });
+          walletAddress2 = Array.isArray(accounts) ? accounts[0] : null;
+        }
       } else {
         if (typeof window === "undefined" || !window.ethereum) {
           throw new ConfigurationError("No Web3 wallet detected. Please install MetaMask or provide wallet parameter.");
@@ -673,14 +984,18 @@ var NeusClient = class {
         if (!data2?.signature) {
           throw new ValidationError("wallet-link requires signature in data parameter (signed by secondary wallet)");
         }
-        if (typeof data2?.chainId !== "number") {
-          throw new ValidationError("wallet-link requires chainId (number) in data parameter");
+        if (typeof data2?.chain !== "string" || !/^[a-z0-9]+:[^\s]+$/.test(data2.chain)) {
+          throw new ValidationError("wallet-link requires chain (namespace:reference) in data parameter");
+        }
+        if (typeof data2?.signatureMethod !== "string" || !data2.signatureMethod.trim()) {
+          throw new ValidationError("wallet-link requires signatureMethod in data parameter");
         }
         verificationData = {
           primaryWalletAddress: walletAddress2,
           secondaryWalletAddress: data2.secondaryWalletAddress,
           signature: data2.signature,
-          chainId: data2.chainId,
+          chain: data2.chain,
+          signatureMethod: data2.signatureMethod,
           signedTimestamp: data2?.signedTimestamp || Date.now()
         };
       } else if (verifier === "contract-ownership") {
@@ -706,7 +1021,10 @@ var NeusClient = class {
           ...data2?.agentLabel && { agentLabel: data2.agentLabel },
           ...data2?.agentType && { agentType: data2.agentType },
           ...data2?.description && { description: data2.description },
-          ...data2?.capabilities && { capabilities: data2.capabilities }
+          ...data2?.capabilities && { capabilities: data2.capabilities },
+          ...data2?.instructions && { instructions: data2.instructions },
+          ...data2?.skills && { skills: data2.skills },
+          ...data2?.services && { services: data2.services }
         };
       } else if (verifier === "agent-delegation") {
         if (!data2?.agentWallet) {
@@ -719,7 +1037,11 @@ var NeusClient = class {
           ...data2?.scope && { scope: data2.scope },
           ...data2?.permissions && { permissions: data2.permissions },
           ...data2?.maxSpend && { maxSpend: data2.maxSpend },
-          ...data2?.expiresAt && { expiresAt: data2.expiresAt }
+          ...data2?.allowedPaymentTypes && { allowedPaymentTypes: data2.allowedPaymentTypes },
+          ...data2?.receiptDisclosure && { receiptDisclosure: data2.receiptDisclosure },
+          ...data2?.expiresAt && { expiresAt: data2.expiresAt },
+          ...data2?.instructions && { instructions: data2.instructions },
+          ...data2?.skills && { skills: data2.skills }
         };
       } else if (verifier === "ai-content-moderation") {
         if (!data2?.content) {
@@ -769,48 +1091,41 @@ var NeusClient = class {
         signedTimestamp: signedTimestamp2,
         data: verificationData,
         verifierIds: verifierIds2,
-        chainId: NEUS_CONSTANTS.HUB_CHAIN_ID
+        chainId: this._getHubChainId()
         // Protocol-managed chain
       });
       let signature2;
       try {
-        const toHexUtf8 = (s) => {
+        const toHexUtf82 = (s) => {
           try {
             const enc = new TextEncoder();
             const bytes = enc.encode(s);
             let hex = "0x";
-            for (let i = 0; i < bytes.length; i++)
-              hex += bytes[i].toString(16).padStart(2, "0");
+            for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, "0");
             return hex;
           } catch {
             let hex = "0x";
-            for (let i = 0; i < s.length; i++)
-              hex += s.charCodeAt(i).toString(16).padStart(2, "0");
+            for (let i = 0; i < s.length; i++) hex += s.charCodeAt(i).toString(16).padStart(2, "0");
             return hex;
           }
         };
         const isFarcasterWallet = (() => {
-          if (typeof window === "undefined")
-            return false;
+          if (typeof window === "undefined") return false;
           try {
             const w = window;
             const fc = w.farcaster;
-            if (!fc || !fc.context)
-              return false;
+            if (!fc || !fc.context) return false;
             const fcProvider = fc.provider || fc.walletProvider || fc.context && fc.context.walletProvider;
-            if (fcProvider === provider)
-              return true;
-            if (w.mini && w.mini.wallet === provider && fc && fc.context)
-              return true;
-            if (w.ethereum === provider && fc && fc.context)
-              return true;
+            if (fcProvider === provider) return true;
+            if (w.mini && w.mini.wallet === provider && fc && fc.context) return true;
+            if (w.ethereum === provider && fc && fc.context) return true;
           } catch {
           }
           return false;
         })();
         if (isFarcasterWallet) {
           try {
-            const hexMsg = toHexUtf8(message);
+            const hexMsg = toHexUtf82(message);
             signature2 = await provider.request({ method: "personal_sign", params: [hexMsg, walletAddress2] });
           } catch (e) {
           }
@@ -822,7 +1137,8 @@ var NeusClient = class {
             const msg = String(e && (e.message || e.reason) || e || "").toLowerCase();
             const errCode = e && (e.code || e.error && e.error.code) || null;
             const needsHex = /byte|bytes|invalid byte sequence|encoding|non-hex/i.test(msg);
-            const methodUnsupported = /method.*not.*supported|unsupported|not implemented|method not found|unknown method|does not support/i.test(msg) || errCode === -32601 || errCode === 4200 || msg.includes("personal_sign") && msg.includes("not") || msg.includes("request method") && msg.includes("not supported");
+            const unsupportedRe = /method.*not.*supported|unsupported|not implemented|method not found|unknown method|does not support/i;
+            const methodUnsupported = unsupportedRe.test(msg) || errCode === -32601 || errCode === 4200 || msg.includes("personal_sign") && msg.includes("not") || msg.includes("request method") && msg.includes("not supported");
             if (methodUnsupported) {
               this._log("personal_sign not supported; attempting eth_sign fallback");
               try {
@@ -831,35 +1147,30 @@ var NeusClient = class {
                 const prefix = `Ethereum Signed Message:
 ${bytes.length}`;
                 const full = new Uint8Array(prefix.length + bytes.length);
-                for (let i = 0; i < prefix.length; i++)
-                  full[i] = prefix.charCodeAt(i);
+                for (let i = 0; i < prefix.length; i++) full[i] = prefix.charCodeAt(i);
                 full.set(bytes, prefix.length);
                 let payloadHex = "0x";
-                for (let i = 0; i < full.length; i++)
-                  payloadHex += full[i].toString(16).padStart(2, "0");
+                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;
+                  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__;
+                  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__;
+                  if (typeof window !== "undefined") delete window.__NEUS_ALLOW_ETH_SIGN__;
                 } catch {
                 }
                 throw e;
               }
             } else if (needsHex) {
               this._log("Retrying personal_sign with hex-encoded message");
-              const hexMsg = toHexUtf8(message);
+              const hexMsg = toHexUtf82(message);
               signature2 = await provider.request({ method: "personal_sign", params: [hexMsg, walletAddress2] });
             } else {
               throw e;
@@ -894,8 +1205,7 @@ ${bytes.length}`;
     } = params;
     const resolvedChainId = chainId || (chain ? null : NEUS_CONSTANTS.HUB_CHAIN_ID);
     const normalizeVerifierId = (id) => {
-      if (typeof id !== "string")
-        return id;
+      if (typeof id !== "string") return id;
       const match = id.match(/^(.*)@\d+$/);
       return match ? match[1] : id;
     };
@@ -930,10 +1240,9 @@ ${bytes.length}`;
       // Privacy and storage options (defaults)
       privacyLevel: options?.privacyLevel || "private",
       publicDisplay: options?.publicDisplay || false,
-      storeOriginalContent: options?.storeOriginalContent || false
+      storeOriginalContent: typeof options?.storeOriginalContent === "boolean" ? options.storeOriginalContent : true
     };
-    if (typeof options?.enableIpfs === "boolean")
-      optionsPayload.enableIpfs = options.enableIpfs;
+    if (typeof options?.enableIpfs === "boolean") optionsPayload.enableIpfs = options.enableIpfs;
     const requestData = {
       verifierIds: normalizedVerifierIds,
       data,
@@ -951,96 +1260,94 @@ ${bytes.length}`;
     }
     return this._formatResponse(response);
   }
-  // ============================================================================
-  // STATUS AND UTILITY METHODS
-  // ============================================================================
   /**
-   * Get verification status
+   * Get proof record by proof receipt id.
    *
-   * @param {string} qHash - Verification ID (qHash or proofId)
-   * @returns {Promise<Object>} Verification status and data
+   * @param {string} proofId - Proof receipt ID (0x + 64 hex).
+   * @returns {Promise<Object>} Proof record and verification state
    *
    * @example
-   * const result = await client.getStatus('0x...');
+   * const result = await client.getProof('0x...');
    * console.log('Status:', result.status);
    */
-  async getStatus(qHash) {
-    if (!qHash || typeof qHash !== "string") {
-      throw new ValidationError("qHash is required");
+  async getProof(proofId) {
+    if (!proofId || typeof proofId !== "string") {
+      throw new ValidationError("proofId is required");
     }
-    const response = await this._makeRequest("GET", `/api/v1/verification/status/${qHash}`);
+    const response = await this._makeRequest("GET", `/api/v1/proofs/${proofId}`);
     if (!response.success) {
-      throw new ApiError(`Failed to get status: ${response.error?.message || "Unknown error"}`, response.error);
+      throw new ApiError(`Failed to get proof: ${response.error?.message || "Unknown error"}`, response.error);
     }
     return this._formatResponse(response);
   }
   /**
-   * Get private proof status with wallet signature
+   * Get private proof record with wallet signature
    *
-   * @param {string} qHash - Verification ID
+   * @param {string} proofId - Proof receipt ID.
    * @param {Object} wallet - Wallet provider (window.ethereum or ethers Wallet)
-   * @returns {Promise<Object>} Private verification status and data
+   * @returns {Promise<Object>} Private proof record and verification state
    *
    * @example
-   * // Access private proof
-   * const privateData = await client.getPrivateStatus(qHash, window.ethereum);
+   * const privateData = await client.getPrivateProof(proofId, window.ethereum);
    */
-  async getPrivateStatus(qHash, wallet = null) {
-    if (!qHash || typeof qHash !== "string") {
-      throw new ValidationError("qHash is required");
+  async getPrivateProof(proofId, wallet = null) {
+    if (!proofId || typeof proofId !== "string") {
+      throw new ValidationError("proofId is required");
     }
-    if (!wallet) {
-      if (typeof window === "undefined" || !window.ethereum) {
-        throw new ConfigurationError("No wallet provider available");
+    const isPreSignedAuth = wallet && typeof wallet === "object" && typeof wallet.walletAddress === "string" && typeof wallet.signature === "string" && typeof wallet.signedTimestamp === "number";
+    if (isPreSignedAuth) {
+      const auth = wallet;
+      const headers = {
+        "x-wallet-address": String(auth.walletAddress),
+        "x-signature": String(auth.signature),
+        "x-signed-timestamp": String(auth.signedTimestamp),
+        ...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);
+      if (!response2.success) {
+        throw new ApiError(
+          `Failed to access private proof: ${response2.error?.message || "Unauthorized"}`,
+          response2.error
+        );
       }
-      wallet = window.ethereum;
+      return this._formatResponse(response2);
     }
-    let walletAddress, provider;
-    if (wallet.address) {
-      walletAddress = wallet.address;
-      provider = wallet;
-    } else if (wallet.selectedAddress || wallet.request) {
-      provider = wallet;
-      if (wallet.selectedAddress) {
-        walletAddress = wallet.selectedAddress;
-      } else {
-        const accounts = await provider.request({ method: "eth_accounts" });
-        if (!accounts || accounts.length === 0) {
-          throw new ConfigurationError("No wallet accounts available");
-        }
-        walletAddress = accounts[0];
-      }
-    } else {
-      throw new ConfigurationError("Invalid wallet provider");
+    const providerWallet = wallet || this._getDefaultBrowserWallet();
+    const { signerWalletAddress: walletAddress, provider } = await this._resolveWalletSigner(providerWallet);
+    if (!walletAddress || typeof walletAddress !== "string") {
+      throw new ConfigurationError("No wallet accounts available");
     }
+    const signerIsEvm = EVM_ADDRESS_RE.test(this._normalizeIdentity(walletAddress));
+    const chain = this._inferChainForAddress(walletAddress);
+    const signatureMethod = signerIsEvm ? "eip191" : "ed25519";
     const signedTimestamp = Date.now();
     const message = constructVerificationMessage({
       walletAddress,
       signedTimestamp,
-      data: { action: "access_private_proof", qHash },
+      data: { action: "access_private_proof", qHash: proofId },
       verifierIds: ["ownership-basic"],
-      chainId: NEUS_CONSTANTS.HUB_CHAIN_ID
+      ...signerIsEvm ? { chainId: this._getHubChainId() } : { chain }
     });
     let signature;
     try {
-      if (provider.signMessage) {
-        signature = await provider.signMessage(message);
-      } else {
-        signature = await provider.request({
-          method: "personal_sign",
-          params: [message, walletAddress]
-        });
-      }
+      signature = await signMessage({
+        provider,
+        message,
+        walletAddress,
+        ...signerIsEvm ? {} : { chain }
+      });
     } catch (error) {
       if (error.code === 4001) {
         throw new ValidationError("User rejected signature request");
       }
       throw new ValidationError(`Failed to sign message: ${error.message}`);
     }
-    const response = await this._makeRequest("GET", `/api/v1/verification/status/${qHash}`, null, {
+    const response = await this._makeRequest("GET", `/api/v1/proofs/${proofId}`, null, {
       "x-wallet-address": walletAddress,
       "x-signature": signature,
-      "x-signed-timestamp": signedTimestamp.toString()
+      "x-signed-timestamp": signedTimestamp.toString(),
+      ...signerIsEvm ? {} : { "x-chain": chain, "x-signature-method": signatureMethod }
     });
     if (!response.success) {
       throw new ApiError(
@@ -1069,27 +1376,39 @@ ${bytes.length}`;
    * @returns {Promise<string[]>} Array of verifier IDs
    */
   async getVerifiers() {
+    const catalog = await this.getVerifierCatalog();
+    return Array.isArray(catalog?.data) ? catalog.data : [];
+  }
+  /**
+   * Get the public verifier catalog with per-verifier capabilities.
+   * @returns {Promise<{data: string[], metadata: Record<string, { supportsDirectApi?: boolean }>, meta?: object}>}
+   */
+  async getVerifierCatalog() {
     const response = await this._makeRequest("GET", "/api/v1/verification/verifiers");
     if (!response.success) {
       throw new ApiError(`Failed to get verifiers: ${response.error?.message || "Unknown error"}`, response.error);
     }
-    return Array.isArray(response.data) ? response.data : [];
+    return {
+      data: Array.isArray(response.data) ? response.data : [],
+      metadata: response.metadata && typeof response.metadata === "object" && !Array.isArray(response.metadata) ? response.metadata : {},
+      meta: response.meta && typeof response.meta === "object" && !Array.isArray(response.meta) ? response.meta : {}
+    };
   }
   /**
    * POLL PROOF STATUS - Wait for verification completion
-   * 
+   *
    * Polls the verification status until it reaches a terminal state (completed or failed).
    * Useful for providing real-time feedback to users during verification.
-   * 
-   * @param {string} qHash - Verification ID to poll
+   *
+   * @param {string} proofId - Proof ID to poll.
    * @param {Object} [options] - Polling options
    * @param {number} [options.interval=5000] - Polling interval in ms
    * @param {number} [options.timeout=120000] - Total timeout in ms
    * @param {Function} [options.onProgress] - Progress callback function
    * @returns {Promise<Object>} Final verification status
-   * 
+   *
    * @example
-   * const finalStatus = await client.pollProofStatus(qHash, {
+   * const finalStatus = await client.pollProofStatus(proofId, {
    *   interval: 3000,
    *   timeout: 60000,
    *   onProgress: (status) => {
@@ -1100,20 +1419,20 @@ ${bytes.length}`;
    *   }
    * });
    */
-  async pollProofStatus(qHash, options = {}) {
+  async pollProofStatus(proofId, options = {}) {
     const {
       interval = 5e3,
       timeout = 12e4,
       onProgress
     } = options;
-    if (!qHash || typeof qHash !== "string") {
-      throw new ValidationError("qHash is required");
+    if (!proofId || typeof proofId !== "string") {
+      throw new ValidationError("proofId is required");
     }
     const startTime = Date.now();
     let consecutiveRateLimits = 0;
     while (Date.now() - startTime < timeout) {
       try {
-        const status = await this.getStatus(qHash);
+        const status = await this.getProof(proofId);
         consecutiveRateLimits = 0;
         if (onProgress && typeof onProgress === "function") {
           onProgress(status.data || status);
@@ -1146,7 +1465,7 @@ ${bytes.length}`;
   }
   /**
    * DETECT CHAIN ID - Get current wallet chain
-   * 
+   *
    * @returns {Promise<number>} Current chain ID
    */
   async detectChainId() {
@@ -1161,70 +1480,49 @@ ${bytes.length}`;
     }
   }
   /** Revoke your own proof (owner-signed) */
-  async revokeOwnProof(qHash, wallet) {
-    if (!qHash || typeof qHash !== "string") {
-      throw new ValidationError("qHash is required");
+  async revokeOwnProof(proofId, wallet) {
+    if (!proofId || typeof proofId !== "string") {
+      throw new ValidationError("proofId is required");
+    }
+    const providerWallet = wallet || this._getDefaultBrowserWallet();
+    const { signerWalletAddress: address, provider } = await this._resolveWalletSigner(providerWallet);
+    if (!address || typeof address !== "string") {
+      throw new ConfigurationError("No wallet accounts available");
     }
-    const address = wallet?.address || await this._getWalletAddress();
+    const signerIsEvm = EVM_ADDRESS_RE.test(this._normalizeIdentity(address));
+    const chain = this._inferChainForAddress(address);
+    const signatureMethod = signerIsEvm ? "eip191" : "ed25519";
     const signedTimestamp = Date.now();
-    const hubChainId = NEUS_CONSTANTS.HUB_CHAIN_ID;
     const message = constructVerificationMessage({
       walletAddress: address,
       signedTimestamp,
-      data: { action: "revoke_proof", qHash },
+      data: { action: "revoke_proof", qHash: proofId },
       verifierIds: ["ownership-basic"],
-      chainId: hubChainId
+      ...signerIsEvm ? { chainId: this._getHubChainId() } : { chain }
     });
     let signature;
     try {
-      const toHexUtf8 = (s) => {
-        const enc = new TextEncoder();
-        const bytes = enc.encode(s);
-        let hex = "0x";
-        for (let i = 0; i < bytes.length; i++)
-          hex += bytes[i].toString(16).padStart(2, "0");
-        return hex;
-      };
-      const isFarcasterWallet = (() => {
-        if (typeof window === "undefined")
-          return false;
-        try {
-          const w = window;
-          const fc = w.farcaster;
-          if (!fc || !fc.context)
-            return false;
-          const fcProvider = fc.provider || fc.walletProvider || fc.context && fc.context.walletProvider;
-          if (fcProvider === w.ethereum)
-            return true;
-          if (w.mini && w.mini.wallet === w.ethereum && fc && fc.context)
-            return true;
-          if (w.ethereum && fc && fc.context)
-            return true;
-        } catch {
-        }
-        return false;
-      })();
-      if (isFarcasterWallet) {
-        try {
-          const hexMsg = toHexUtf8(message);
-          signature = await window.ethereum.request({ method: "personal_sign", params: [hexMsg, address] });
-        } catch {
-        }
-      }
-      if (!signature) {
-        signature = await window.ethereum.request({ method: "personal_sign", params: [message, address] });
-      }
+      signature = await signMessage({
+        provider,
+        message,
+        walletAddress: address,
+        ...signerIsEvm ? {} : { chain }
+      });
     } catch (error) {
       if (error.code === 4001) {
         throw new ValidationError("User rejected revocation signature");
       }
       throw new ValidationError(`Failed to sign revocation: ${error.message}`);
     }
-    const res = await fetch(`${this.config.apiUrl}/api/v1/proofs/${qHash}/revoke-self`, {
+    const res = await fetch(`${this.config.apiUrl}/api/v1/proofs/revoke-self/${proofId}`, {
       method: "POST",
-      // SECURITY: Do not put proof signatures into Authorization headers.
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ walletAddress: address, signature, signedTimestamp })
+      body: JSON.stringify({
+        walletAddress: address,
+        signature,
+        signedTimestamp,
+        ...signerIsEvm ? {} : { chain, signatureMethod }
+      })
     });
     const json = await res.json();
     if (!json.success) {
@@ -1232,18 +1530,16 @@ ${bytes.length}`;
     }
     return true;
   }
-  // ============================================================================
-  // PROOFS & GATING METHODS
-  // ============================================================================
   /**
    * GET PROOFS BY WALLET - Fetch proofs for a wallet address
-   * 
-   * @param {string} walletAddress - Wallet address (0x...) or DID (did:pkh:...)
+   *
+   * @param {string} walletAddress - Wallet identity (EVM/Solana/DID)
    * @param {Object} [options] - Filter options
    * @param {number} [options.limit] - Max results (default: 50; higher limits require owner access)
    * @param {number} [options.offset] - Pagination offset (default: 0)
+   * @param {string} [options.qHash] - Filter to single proof by qHash
    * @returns {Promise<Object>} Proofs result
-   * 
+   *
    * @example
    * const result = await client.getProofsByWallet('0x...', {
    *   limit: 50,
@@ -1257,14 +1553,13 @@ ${bytes.length}`;
     const id = walletAddress.trim();
     const pathId = /^0x[a-fA-F0-9]{40}$/i.test(id) ? id.toLowerCase() : id;
     const qs = [];
-    if (options.limit)
-      qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-    if (options.offset)
-      qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
+    if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
+    if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
+    if (options.qHash) qs.push(`qHash=${encodeURIComponent(options.qHash.toLowerCase())}`);
     const query = qs.length ? `?${qs.join("&")}` : "";
     const response = await this._makeRequest(
       "GET",
-      `/api/v1/proofs/byWallet/${encodeURIComponent(pathId)}${query}`
+      `/api/v1/proofs/by-wallet/${encodeURIComponent(pathId)}${query}`
     );
     if (!response.success) {
       throw new ApiError(`Failed to get proofs: ${response.error?.message || "Unknown error"}`, response.error);
@@ -1283,10 +1578,11 @@ ${bytes.length}`;
    *
    * Signs an owner-access intent and requests private proofs via signature headers.
    *
-   * @param {string} walletAddress - Wallet address (0x...) or DID (did:pkh:...)
+   * @param {string} walletAddress - Wallet identity (EVM/Solana/DID)
    * @param {Object} [options]
    * @param {number} [options.limit] - Max results (server enforces caps)
    * @param {number} [options.offset] - Pagination offset
+   * @param {string} [options.qHash] - Filter to single proof by qHash
    * @param {Object} [wallet] - Optional injected wallet/provider (MetaMask/ethers Wallet)
    */
   async getPrivateProofsByWallet(walletAddress, options = {}, wallet = null) {
@@ -1295,48 +1591,41 @@ ${bytes.length}`;
     }
     const id = walletAddress.trim();
     const pathId = /^0x[a-fA-F0-9]{40}$/i.test(id) ? id.toLowerCase() : id;
+    const requestedIdentity = this._normalizeIdentity(id);
     if (!wallet) {
-      if (typeof window === "undefined" || !window.ethereum) {
+      const defaultWallet = this._getDefaultBrowserWallet();
+      if (!defaultWallet) {
         throw new ConfigurationError("No wallet provider available");
       }
-      wallet = window.ethereum;
+      wallet = defaultWallet;
     }
-    let signerWalletAddress, provider;
-    if (wallet.address) {
-      signerWalletAddress = wallet.address;
-      provider = wallet;
-    } else if (wallet.selectedAddress || wallet.request) {
-      provider = wallet;
-      if (wallet.selectedAddress) {
-        signerWalletAddress = wallet.selectedAddress;
-      } else {
-        const accounts = await provider.request({ method: "eth_accounts" });
-        if (!accounts || accounts.length === 0) {
-          throw new ConfigurationError("No wallet accounts available");
-        }
-        signerWalletAddress = accounts[0];
-      }
-    } else {
-      throw new ConfigurationError("Invalid wallet provider");
+    const { signerWalletAddress, provider } = await this._resolveWalletSigner(wallet);
+    if (!signerWalletAddress || typeof signerWalletAddress !== "string") {
+      throw new ConfigurationError("No wallet accounts available");
+    }
+    const normalizedSigner = this._normalizeIdentity(signerWalletAddress);
+    if (!normalizedSigner || normalizedSigner !== requestedIdentity) {
+      throw new ValidationError("wallet must match walletAddress for private proof access");
     }
+    const signerIsEvm = EVM_ADDRESS_RE.test(normalizedSigner);
+    const chain = this._inferChainForAddress(normalizedSigner, options?.chain);
+    const signatureMethod = typeof options?.signatureMethod === "string" && options.signatureMethod.trim() ? options.signatureMethod.trim() : signerIsEvm ? "eip191" : "ed25519";
     const signedTimestamp = Date.now();
     const message = constructVerificationMessage({
       walletAddress: signerWalletAddress,
       signedTimestamp,
-      data: { action: "access_private_proofs_by_wallet", walletAddress: signerWalletAddress.toLowerCase() },
+      data: { action: "access_private_proofs_by_wallet", walletAddress: normalizedSigner },
       verifierIds: ["ownership-basic"],
-      chainId: NEUS_CONSTANTS.HUB_CHAIN_ID
+      ...signerIsEvm ? { chainId: this._getHubChainId() } : { chain }
     });
     let signature;
     try {
-      if (provider.signMessage) {
-        signature = await provider.signMessage(message);
-      } else {
-        signature = await provider.request({
-          method: "personal_sign",
-          params: [message, signerWalletAddress]
-        });
-      }
+      signature = await signMessage({
+        provider,
+        message,
+        walletAddress: signerWalletAddress,
+        ...signerIsEvm ? {} : { chain }
+      });
     } catch (error) {
       if (error.code === 4001) {
         throw new ValidationError("User rejected signature request");
@@ -1344,15 +1633,15 @@ ${bytes.length}`;
       throw new ValidationError(`Failed to sign message: ${error.message}`);
     }
     const qs = [];
-    if (options.limit)
-      qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
-    if (options.offset)
-      qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
+    if (options.limit) qs.push(`limit=${encodeURIComponent(String(options.limit))}`);
+    if (options.offset) qs.push(`offset=${encodeURIComponent(String(options.offset))}`);
+    if (options.qHash) qs.push(`qHash=${encodeURIComponent(options.qHash.toLowerCase())}`);
     const query = qs.length ? `?${qs.join("&")}` : "";
-    const response = await this._makeRequest("GET", `/api/v1/proofs/byWallet/${encodeURIComponent(pathId)}${query}`, null, {
+    const response = await this._makeRequest("GET", `/api/v1/proofs/by-wallet/${encodeURIComponent(pathId)}${query}`, null, {
       "x-wallet-address": signerWalletAddress,
       "x-signature": signature,
-      "x-signed-timestamp": signedTimestamp.toString()
+      "x-signed-timestamp": signedTimestamp.toString(),
+      ...signerIsEvm ? {} : { "x-chain": chain, "x-signature-method": signatureMethod }
     });
     if (!response.success) {
       throw new ApiError(`Failed to get proofs: ${response.error?.message || "Unauthorized"}`, response.error);
@@ -1367,51 +1656,52 @@ ${bytes.length}`;
     };
   }
   /**
-   * GATE CHECK (API) - Minimal eligibility check
+   * Gate check (HTTP API) — minimal eligibility response.
    *
-   * Calls the public gate endpoint and returns a **minimal** yes/no response
-   * against **public + discoverable** proofs only.
+   * Calls the gate endpoint and returns a **minimal** yes/no response.
+   * By default this checks **public + unlisted** proofs.
    *
-   * Prefer this over `checkGate()` for server-side integrations that want the
-   * smallest, most stable surface area (and do NOT need full proof payloads).
+   * When `includePrivate=true`, this can perform owner-signed private checks
+   * (no full proof payloads returned) by providing a wallet/provider.
+   *
+   * Prefer this over `checkGate()` when you need the smallest, most stable
+   * response shape and do not need full proof payloads.
    *
    * @param {Object} params - Gate check query params
-   * @param {string} params.address - Wallet address to check (0x...)
+   * @param {string} params.address - Wallet identity to check (EVM/Solana/DID)
    * @param {Array<string>|string} [params.verifierIds] - Verifier IDs to match (array or comma-separated)
    * @param {boolean} [params.requireAll] - Require all verifierIds on a single proof
    * @param {number} [params.minCount] - Minimum number of matching proofs
    * @param {number} [params.sinceDays] - Optional time window in days
    * @param {number} [params.since] - Optional unix timestamp in ms (lower bound)
    * @param {number} [params.limit] - Max rows to scan (server may clamp)
+   * @param {boolean} [params.includePrivate] - Include private proofs for owner-authenticated requests
+   * @param {boolean} [params.includeQHashes] - Include matched qHashes in response (minimal IDs only)
+   * @param {Object} [params.wallet] - Optional wallet/provider used to sign includePrivate owner checks
    * @returns {Promise<Object>} API response ({ success, data })
    */
   async gateCheck(params = {}) {
     const address = (params.address || "").toString();
-    if (!address || !/^0x[a-fA-F0-9]{40}$/i.test(address)) {
+    if (!validateUniversalAddress(address, params.chain)) {
       throw new ValidationError("Valid address is required");
     }
     const qs = new URLSearchParams();
     qs.set("address", address);
     const setIfPresent = (key, value) => {
-      if (value === void 0 || value === null)
-        return;
+      if (value === void 0 || value === null) return;
       const str = typeof value === "string" ? value : String(value);
-      if (str.length === 0)
-        return;
+      if (str.length === 0) return;
       qs.set(key, str);
     };
     const setBoolIfPresent = (key, value) => {
-      if (value === void 0 || value === null)
-        return;
+      if (value === void 0 || value === null) return;
       qs.set(key, value ? "true" : "false");
     };
     const setCsvIfPresent = (key, value) => {
-      if (value === void 0 || value === null)
-        return;
+      if (value === void 0 || value === null) return;
       if (Array.isArray(value)) {
         const items = value.map((v) => String(v).trim()).filter(Boolean);
-        if (items.length)
-          qs.set(key, items.join(","));
+        if (items.length) qs.set(key, items.join(","));
         return;
       }
       setIfPresent(key, value);
@@ -1422,6 +1712,8 @@ ${bytes.length}`;
     setIfPresent("sinceDays", params.sinceDays);
     setIfPresent("since", params.since);
     setIfPresent("limit", params.limit);
+    setBoolIfPresent("includePrivate", params.includePrivate);
+    setBoolIfPresent("includeQHashes", params.includeQHashes);
     setIfPresent("referenceType", params.referenceType);
     setIfPresent("referenceId", params.referenceId);
     setIfPresent("tag", params.tag);
@@ -1435,6 +1727,8 @@ ${bytes.length}`;
     setIfPresent("domain", params.domain);
     setIfPresent("minBalance", params.minBalance);
     setIfPresent("provider", params.provider);
+    setIfPresent("handle", params.handle);
+    setIfPresent("namespace", params.namespace);
     setIfPresent("ownerAddress", params.ownerAddress);
     setIfPresent("riskLevel", params.riskLevel);
     setBoolIfPresent("sanctioned", params.sanctioned);
@@ -1442,18 +1736,57 @@ ${bytes.length}`;
     setIfPresent("primaryWalletAddress", params.primaryWalletAddress);
     setIfPresent("secondaryWalletAddress", params.secondaryWalletAddress);
     setIfPresent("verificationMethod", params.verificationMethod);
-    const response = await this._makeRequest("GET", `/api/v1/proofs/gate/check?${qs.toString()}`);
+    let headersOverride = null;
+    if (params.includePrivate === true) {
+      const provided = params.privateAuth && typeof params.privateAuth === "object" ? params.privateAuth : null;
+      let auth = provided;
+      if (!auth) {
+        const walletCandidate = params.wallet || this._getDefaultBrowserWallet();
+        if (walletCandidate) {
+          auth = await this._buildPrivateGateAuth({
+            address,
+            wallet: walletCandidate,
+            chain: params.chain,
+            signatureMethod: params.signatureMethod
+          });
+        }
+      }
+      if (!auth) {
+      } else {
+        const normalizedAuthWallet = this._normalizeIdentity(auth.walletAddress);
+        const normalizedAddress = this._normalizeIdentity(address);
+        if (!normalizedAuthWallet || normalizedAuthWallet !== normalizedAddress) {
+          throw new ValidationError("privateAuth.walletAddress must match address when includePrivate=true");
+        }
+        const authChain = typeof auth.chain === "string" && auth.chain.includes(":") ? auth.chain.trim() : null;
+        const authSignatureMethod = typeof auth.signatureMethod === "string" && auth.signatureMethod.trim() ? auth.signatureMethod.trim() : null;
+        headersOverride = {
+          "x-wallet-address": String(auth.walletAddress),
+          "x-signature": String(auth.signature),
+          "x-signed-timestamp": String(auth.signedTimestamp),
+          ...authChain ? { "x-chain": authChain } : {},
+          ...authSignatureMethod ? { "x-signature-method": authSignatureMethod } : {}
+        };
+      }
+    }
+    const response = await this._makeRequest("GET", `/api/v1/proofs/check?${qs.toString()}`, null, headersOverride);
     if (!response.success) {
       throw new ApiError(`Gate check failed: ${response.error?.message || "Unknown error"}`, response.error);
     }
     return response;
   }
   /**
-   * CHECK GATE - Evaluate requirements against existing proofs
-   * 
+   * CHECK GATE — Local preview against proofs you already have in memory or from `getProofsByWallet`.
+   *
+   * **Not authoritative for access control.** For production allow/deny, use {@link NeusClient#gateCheck}
+   * (`GET /api/v1/proofs/check`), which applies the same rules as the NEUS API. This method is useful for
+   * UI previews, offline-ish flows, or when you already fetched proofs and want a quick match without
+   * another round trip — but it can disagree with the server (e.g. `contentHash` matching uses a local
+   * approximation when proof data only has inline `content`; the API uses the standard server-side hash).
+   *
    * Gate-first verification: checks if wallet has valid proofs satisfying requirements.
    * Returns which requirements are missing/expired.
-   * 
+   *
    * @param {Object} params - Gate check parameters
    * @param {string} params.walletAddress - Target wallet
    * @param {Array<Object>} params.requirements - Array of gate requirements
@@ -1466,12 +1799,12 @@ ${bytes.length}`;
    *   Supports verifier-specific:
    *     - NFT/Token: 'contractAddress', 'tokenId', 'chainId', 'ownerAddress', 'minBalance'
    *     - DNS: 'domain', 'walletAddress'
-   *     - Wallet-link: 'primaryWalletAddress', 'secondaryWalletAddress', 'chainId'
+   *     - Wallet-link: 'primaryWalletAddress', 'secondaryWalletAddress', 'chain', 'signatureMethod'
    *     - Contract-ownership: 'contractAddress', 'chainId', 'owner', 'verificationMethod'
    *   Note: contentHash matching uses approximation in SDK; for exact SHA-256 matching, use backend API
    * @param {Array} [params.proofs] - Pre-fetched proofs (skip API call)
    * @returns {Promise<Object>} Gate result with satisfied, missing, existing
-   * 
+   *
    * @example
    * // Basic gate check
    * const result = await client.checkGate({
@@ -1483,7 +1816,7 @@ ${bytes.length}`;
    */
   async checkGate(params) {
     const { walletAddress, requirements, proofs: preloadedProofs } = params;
-    if (!walletAddress || !/^0x[a-fA-F0-9]{40}$/i.test(walletAddress)) {
+    if (!validateUniversalAddress(walletAddress)) {
       throw new ValidationError("Valid walletAddress is required");
     }
     if (!Array.isArray(requirements) || requirements.length === 0) {
@@ -1504,20 +1837,20 @@ ${bytes.length}`;
         const verifier = verifiedVerifiers.find(
           (v) => v.verifierId === verifierId && v.verified === true
         );
-        if (!verifier)
-          return false;
-        if (proof.revokedAt)
-          return false;
+        if (!verifier) return false;
+        if (proof.revokedAt) return false;
         if (maxAgeMs) {
           const proofTimestamp = proof.createdAt || proof.signedTimestamp || 0;
           const proofAge = now - proofTimestamp;
-          if (proofAge > maxAgeMs)
-            return false;
+          if (proofAge > maxAgeMs) return false;
         }
         if (match && typeof match === "object") {
           const data = verifier.data || {};
           const input = data.input || {};
-          for (const [key, expected] of Object.entries(match)) {
+          const matchObj = Array.isArray(match) ? Object.fromEntries(
+            match.filter((m) => m && m.path && String(m.value ?? "").trim() !== "").map((m) => [String(m.path).trim(), m.value])
+          ) : match;
+          for (const [key, expected] of Object.entries(matchObj)) {
             let actualValue = null;
             if (key.includes(".")) {
               const parts = key.split(".");
@@ -1542,6 +1875,7 @@ ${bytes.length}`;
               actualValue = data.reference?.id || data.content;
             }
             if (actualValue === void 0) {
+              const claims = data.claims || {};
               if (key === "contractAddress") {
                 actualValue = input.contractAddress || data.contractAddress;
               } else if (key === "tokenId") {
@@ -1560,6 +1894,22 @@ ${bytes.length}`;
                 actualValue = data.verificationMethod;
               } else if (key === "domain") {
                 actualValue = data.domain;
+              } else if (key === "handle") {
+                actualValue = data.handle || data.pseudonymId;
+              } else if (key === "namespace") {
+                actualValue = data.namespace !== void 0 && data.namespace !== null && data.namespace !== "" ? data.namespace : "neus";
+              } else if (key === "claims.sanctions_passed") {
+                actualValue = claims.sanctions_passed ?? claims.sanctionsPassed;
+              } else if (key === "claims.age_min") {
+                actualValue = claims.age_min ?? claims.ageMin;
+              } else if (key === "neusPersonhoodId") {
+                actualValue = data.neusPersonhoodId;
+              } else if (key === "riskLevel") {
+                actualValue = data.riskLevel;
+              } else if (key === "sanctioned") {
+                actualValue = data.sanctioned;
+              } else if (key === "poisoned") {
+                actualValue = data.poisoned;
               }
             }
             if (key === "contentHash" && actualValue === void 0 && data.content) {
@@ -1571,7 +1921,7 @@ ${bytes.length}`;
                   hash = (hash << 5) - hash + char;
                   hash = hash & hash;
                 }
-                actualValue = "0x" + Math.abs(hash).toString(16).padStart(64, "0").substring(0, 66);
+                actualValue = `0x${Math.abs(hash).toString(16).padStart(64, "0").substring(0, 66)}`;
               } catch {
                 actualValue = String(data.content);
               }
@@ -1581,11 +1931,16 @@ ${bytes.length}`;
             if (actualValue === void 0 || actualValue === null) {
               return false;
             }
+            if (typeof actualValue === "boolean" || key && (key.includes("sanctions") || key.includes("sanctioned") || key.includes("poisoned"))) {
+              const bActual = Boolean(actualValue);
+              const bExpected = expected === true || expected === "true" || String(expected).toLowerCase() === "true";
+              if (bActual !== bExpected) return false;
+              continue;
+            }
             if (key === "chainId" || key === "tokenId" && (typeof actualValue === "number" || !isNaN(Number(actualValue)))) {
               normalizedActual = Number(actualValue);
               normalizedExpected = Number(expected);
-              if (isNaN(normalizedActual) || isNaN(normalizedExpected))
-                return false;
+              if (isNaN(normalizedActual) || isNaN(normalizedExpected)) return false;
             } else if (typeof actualValue === "string" && (actualValue.startsWith("0x") || actualValue.length > 20)) {
               normalizedActual = actualValue.toLowerCase();
               normalizedExpected = typeof expected === "string" ? String(expected).toLowerCase() : expected;
@@ -1614,13 +1969,6 @@ ${bytes.length}`;
       allProofs: proofs
     };
   }
-  // ============================================================================
-  // PRIVATE UTILITY METHODS
-  // ============================================================================
-  /**
-   * Get connected wallet address
-   * @private
-   */
   async _getWalletAddress() {
     if (typeof window === "undefined" || !window.ethereum) {
       throw new ConfigurationError("No Web3 wallet detected");
@@ -1631,10 +1979,6 @@ ${bytes.length}`;
     }
     return accounts[0];
   }
-  /**
-   * Make HTTP request to API
-   * @private
-   */
   async _makeRequest(method, endpoint, data = null, headersOverride = null) {
     const url = `${this.baseUrl}${endpoint}`;
     const controller = new AbortController();
@@ -1672,27 +2016,23 @@ ${bytes.length}`;
       throw new NetworkError(`Network error: ${error.message}`);
     }
   }
-  /**
-   * Format API response for consistent structure
-   * @private
-   */
   _formatResponse(response) {
-    const qHash = response?.data?.qHash || response?.qHash || response?.data?.resource?.qHash || response?.data?.id;
+    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 status = response?.data?.status || response?.status || response?.data?.resource?.status || (response?.success ? "completed" : "unknown");
     return {
       success: response.success,
-      qHash,
+      proofId: finalProofId,
+      qHash: finalQHash,
       status,
       data: response.data,
       message: response.message,
       timestamp: Date.now(),
-      statusUrl: qHash ? `${this.baseUrl}/api/v1/verification/status/${qHash}` : null
+      proofUrl: finalProofId ? `${this.baseUrl}/api/v1/proofs/${finalProofId}` : null
     };
   }
-  /**
-   * Check if status is terminal (completed or failed)
-   * @private
-   */
   _isTerminalStatus(status) {
     const terminalStates = [
       "verified",
@@ -1723,5 +2063,6 @@ ${bytes.length}`;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   NeusClient,
+  PORTABLE_PROOF_SIGNER_HEADER,
   constructVerificationMessage
 });