@neus/sdk 1.0.0 → 1.0.1

package/LICENSE

@@ -9,7 +9,8 @@
       "License" shall mean the terms and conditions for use, reproduction,
       and distribution as defined by Sections 1 through 9 of this document.
 
-      "Licensor" shall mean the copyright owner or entity granting the License.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
 
       "Legal Entity" shall mean the union of the acting entity and all
       other entities that control, are controlled by, or are under common
@@ -34,13 +35,15 @@
       "Work" shall mean the work of authorship, whether in Source or
       Object form, made available under the License, as indicated by a
       copyright notice that is included in or attached to the work
-      (which shall not include communication that is conspicuously
-      marked or otherwise designated in writing by the copyright owner
-      as "Not a Contribution").
+      (an example is provided in the Appendix below).
 
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
 
       "Contribution" shall mean any work of authorship, including
       the original version of the Work and any modifications or additions
@@ -50,16 +53,20 @@
       the copyright owner. For the purposes of this definition, "submitted"
       means any form of electronic, verbal, or written communication sent
       to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control
-      systems, and issue tracking systems that are managed by, or on behalf
-      of, the Licensor for the purpose of discussing and improving the Work,
-      but excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution".
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
 
    2. Grant of Copyright License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to use, reproduce, prepare Derivative Works of,
+      copyright license to reproduce, prepare Derivative Works of,
       publicly display, publicly perform, sublicense, and distribute the
       Work and such Derivative Works in Source or Object form.
 
@@ -113,11 +120,12 @@
           that such additional attribution notices cannot be construed
           as modifying the License.
 
-      You may add Your own copyright notice or additional
-      terms and conditions for use, reproduction, or distribution of Your
-      derivative works, or for any such Derivative Works as a whole,
-      provided Your use, reproduction, and distribution of the Work
-      otherwise complies with the conditions stated in this License.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
 
    5. Submission of Contributions. Unless You explicitly state otherwise,
       any Contribution intentionally submitted for inclusion in the Work
@@ -154,28 +162,16 @@
       other commercial damages or losses), even if such Contributor
       has been advised of the possibility of such damages.
 
-   9. Accepting Warranty or Support. When redistributing the Work or
-      Derivative Works thereof, You may choose to offer, and charge a fee
-      for, acceptance of support, warranty, indemnity, or other liability
-      obligations and/or rights consistent with this License. However, in
-      accepting such obligations, You may act only on Your own behalf and
-      on Your sole responsibility, not on behalf of any other Contributor,
-      and only if You agree to indemnify, defend, and hold each Contributor
-      harmless for any liability incurred by, or claims asserted against,
-      such Contributor by reason of your accepting any such warranty or support.
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2025 NEUS Network, Inc.
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

package/README.md

@@ -1,206 +1,140 @@
 # NEUS SDK
 
-JavaScript client for NEUS Network. Handles wallet signing and API calls automatically.
+JavaScript client (and optional widgets) for the NEUS Network verification API.
 
-## Installation
+## Install
 
 ```bash
 npm install @neus/sdk
 ```
 
-## Quick Start
+## Create a proof (browser wallet flow)
+
+This path requests a wallet signature in the browser and submits the verification request:
 
 ```javascript
 import { NeusClient } from '@neus/sdk';
 
-const client = new NeusClient();
-const proof = await client.verify({
-  verifier: 'ownership-basic',
-  content: 'Hello NEUS Network'
-});
-
-console.log('Proof created:', proof.qHash);
-```
-
-## Basic Usage
-
-### Create Proof
+const client = new NeusClient({ apiUrl: 'https://api.neus.network' });
 
-```javascript
-// Content ownership
-const proof = await client.verify({
+const res = await client.verify({
   verifier: 'ownership-basic',
-  content: 'My original content'
-});
-
-// NFT ownership  
-const proof = await client.verify({
-  verifier: 'nft-ownership',
-  data: {
-    ownerAddress: walletAddress,
-    contractAddress: '0x...',
-    tokenId: '1234',
-    chainId: 1
-  }
+  content: 'Hello NEUS',
+  wallet: window.ethereum
 });
 
-// Token holdings
-const proof = await client.verify({
-  verifier: 'token-holding',
-  data: {
-    ownerAddress: walletAddress,
-    contractAddress: '0x...',
-    minBalance: '100.0',
-    chainId: 1
-  }
-});
+// Proof ID (qHash): stable identifier you can store and use for status polling
+const proofId = res.qHash;
+const status = await client.getStatus(proofId);
 ```
 
-### Check Status
+## Client configuration
 
 ```javascript
-// Public proof status
-const status = await client.getStatus(proof.qHash);
-console.log('Verified:', status.success);
-
-// Private proof access (requires wallet signature)
-const privateStatus = await client.getPrivateStatus(proof.qHash, wallet);
-```
-
-### Monitor Progress
-
-```javascript
-// Poll until completion
-const finalStatus = await client.pollProofStatus(proof.qHash, {
-  interval: 3000,
-  onProgress: (status) => console.log('Current status:', status.status)
+const client = new NeusClient({
+  // Optional: point at a self-hosted deployment
+  apiUrl: 'https://api.neus.network',
+  // Optional: request timeout (ms)
+  timeout: 30000,
+  // Optional: server-side enterprise API key for higher limits on eligible endpoints
+  // (Do not embed API keys in browser apps.)
+  apiKey: process.env.NEUS_API_KEY
 });
 ```
 
-## Configuration
+## Create a proof (server / manual signing)
+
+If you already have a signature over the NEUS Standard Signing String, submit it directly:
 
 ```javascript
-const client = new NeusClient({
-  apiUrl: 'https://api.neus.network', // Default
-  timeout: 30000                      // Request timeout
+const res = await client.verify({
+  verifierIds: ['ownership-basic'],
+  data: {
+    owner: '0x1111111111111111111111111111111111111111',
+    content: 'Hello NEUS',
+    reference: { type: 'url', id: 'https://example.com' }
+  },
+  walletAddress: '0x1111111111111111111111111111111111111111',
+  signature: '0x...',
+  signedTimestamp: Date.now(),
+  chainId: 84532,
+  options: { privacyLevel: 'private' }
 });
 ```
 
-## Privacy Controls
+## What verifiers are available?
 
-```javascript
-// Public proof - publicly accessible verification details
-const publicProof = await client.verify({
-  verifier: 'ownership-basic',
-  content: 'Public content',
-  options: { privacyLevel: 'public' }
-});
+Use the API directly (avoids drift):
 
-// Private proof - restricted access; details require wallet authentication
-const privateProof = await client.verify({
-  verifier: 'ownership-basic', 
-  content: 'Private content',
-  options: { privacyLevel: 'private' }
-});
-```
+- `GET /api/v1/verification/verifiers`
 
-## Cross-Chain Storage
+## Gate checks (recommended for server-side gating)
 
-Store proofs on multiple testnets:
+For production server-side gating, prefer the minimal public endpoint:
 
 ```javascript
-const proof = await client.verify({
-  verifier: 'ownership-basic',
-  content: 'Multi-chain proof',
-  options: {
-    targetChains: [11155111, 80002, 421614] // Testnet chains
-  }
+const res = await client.gateCheck({
+  address: '0x...',
+  verifierIds: ['token-holding'],
+  contractAddress: '0x...',
+  minBalance: '100',
+  chainId: 1,
+  // Optional: require a recent proof for point-in-time verifiers (example: last hour)
+  since: Date.now() - 60 * 60 * 1000
 });
-```
-
-## Error Handling
 
-```javascript
-try {
-  const proof = await client.verify({
-    verifier: 'ownership-basic',
-    content: 'Hello NEUS'
-  });
-} catch (error) {
-  if (error.code === 4001) {
-    console.log('User cancelled verification');
-  } else {
-    console.error('Verification failed:', error.message);
-  }
+if (!res.data?.eligible) {
+  throw new Error('Access denied');
 }
 ```
 
-## API Methods
-
-### `verify(params)`
-
-Create verification proof.
-
-**Parameters:**
-- `verifier` (string) - Verifier ID
-- `content` (string) - Content to verify (for ownership-basic)
-- `data` (object) - Verifier-specific data
-- `options` (object) - Privacy and storage options
-
-**Returns:** `{ qHash, status, data }`
-
-### `getStatus(qHash)`
+Note: `gateCheck` evaluates **existing public/discoverable proofs**. For strict real-time decisions, create a new proof via `client.verify(...)` (or `POST /api/v1/verification`) and use the final status.
 
-Get proof status.
+## Lookup mode (Premium, server-side only; non-persistent)
 
-**Parameters:**
-- `qHash` (string) - Proof identifier
+If you need a **real-time assessment** without minting/storing proofs (no `qHash`), use lookup mode:
 
-**Returns:** `{ success, status, data }`
+- **Endpoint:** `POST /api/v1/verification/lookup`
+- **Auth:** `Authorization: Bearer sk_live_...` (or `sk_test_...`)
+- **Semantics:** runs `external_lookup` verifiers only; **does not** create a proof record
 
-### `getPrivateStatus(qHash, wallet)`
+Note: lookup mode is deployment-dependent and is not part of the stable public integrator OpenAPI (`docs/api/public-api.json`).
 
-Access private proof with wallet signature.
-
-**Parameters:**
-- `qHash` (string) - Proof identifier  
-- `wallet` (object) - Wallet provider
-
-**Returns:** `{ success, status, data }`
-
-### `pollProofStatus(qHash, options)`
-
-Poll until verification completes.
-
-**Parameters:**
-- `qHash` (string) - Proof identifier
-- `options` (object) - Polling configuration
-  - `interval` (number) - Polling interval in ms
-  - `timeout` (number) - Total timeout in ms
-  - `onProgress` (function) - Progress callback
-
-**Returns:** `{ success, status, data }`
+```javascript
+const res = await client.lookup({
+  // Premium API key (keep server-side only)
+  apiKey: process.env.NEUS_API_KEY,
+  verifierIds: ['wallet-risk'],
+  targetWalletAddress: '0x...',
+  data: { chainId: 1 }
+});
 
-### `isHealthy()`
+if (!res.data?.verified) {
+  throw new Error('Rejected');
+}
+```
 
-Check API connectivity.
+Note: `gateCheck()` and `lookup()` are different tools.
+- Use **`gateCheck()`** when you want to gate based on **existing public/discoverable proofs** (fast, minimal response).
+- Use **`lookup()`** when you want a **fresh, non-persistent** decision (typically billable in hosted deployments).
+- Only combine them if you are intentionally doing a cache-first strategy (gate-check first to avoid unnecessary lookups).
 
-**Returns:** `boolean`
+## Private proof reads (owner)
 
-### `getVerifiers()`
+- Private proof by Proof ID (qHash): `client.getPrivateStatus(qHash, wallet)`
+- Private proofs by wallet/DID: `client.getPrivateProofsByWallet(walletOrDid, { limit, offset }, wallet)`
 
-List available verifiers.
+## React widgets
 
-**Returns:** `string[]`
+For UI gating, see `./widgets/README.md`.
 
-## Requirements
+Widget imports:
 
-- **Node.js**: 18+ 
-- **Browser**: Modern browser with Web3 wallet
-- **Wallet**: MetaMask, WalletConnect, or ethers.js Wallet
+```javascript
+import { VerifyGate, ProofBadge } from '@neus/sdk/widgets';
+```
 
-## Links
+## Reference docs
 
-- **[Complete Reference](https://github.com/neus/network/tree/main/docs/REFERENCE.md)** - Full API and verifier documentation
-- **[Available Verifiers](https://github.com/neus/network/tree/main/docs/VERIFIERS.md)** - All verification types
-- **[GitHub Issues](https://github.com/neus/network/issues)** - Community support
+- API Reference: `../docs/api/README.md`
+- OpenAPI (JSON): `../docs/api/public-api.json`

package/SECURITY.md

@@ -1,224 +1,29 @@
-# NEUS SDK Security Guidelines
-
-## Overview
-
-The NEUS Network provides cryptographic verification infrastructure with strong security guarantees at the protocol level. Developers implementing custom verifiers or integrating the SDK must understand and follow security best practices to maintain system integrity.
-
-## Core Security Model
-
-### What NEUS Guarantees
-
-- **EIP-191/EIP-1271 Signature Verification**: All API calls require valid signatures (supports contract wallets)
-- **Replay Protection**: 5-minute timestamp windows with anti-replay protections
-- **Cross-Chain Integrity**: Cryptographic proofs propagated across multiple chains
-- **Immutable Audit Trail**: All verifications stored with quantum-safe qHash identifiers
-- **Privacy-Respecting IPFS**: Public snapshots protect sensitive data; signatures never exposed
-
-### Developer Responsibilities
-
-- **Input Validation**: Sanitize all user-provided data before verification
-- **Contract Security**: Verify smart contract addresses before interaction
-- **API Rate Limiting**: Implement appropriate limits for external service calls
-- **Key Management**: Never expose private keys in verifier logic
-
-## Verifier Security Checklist
-
-### 1. Input Validation
-
-```javascript
-// CORRECT: Validate inputs
-async verify(data, options) {
-  // Validate address format
-  if (!ethers.isAddress(data.contractAddress)) {
-    throw new ValidationError('Invalid contract address');
-  }
-  
-  // Sanitize content
-  const sanitizedContent = data.content.trim().slice(0, 1000);
-  
-  // Verify required fields (owner for ownership-basic/licensed, ownerAddress for nft-ownership/token-holding)
-  if ((!data.owner && !data.ownerAddress) || !data.reference) {
-    throw new ValidationError('Missing required fields');
-  }
-}
-
-// WRONG: Direct usage without validation
-async verify(data, options) {
-  const result = await contract.balanceOf(data.address); // Unsafe!
-}
-```
-
-### 2. External API Security
-
-```javascript
-// CORRECT: Rate limiting and error handling
-class ExternalVerifier {
-  constructor() {
-    this.rateLimiter = new Map();
-    this.maxRequests = 100; // per hour
-  }
-  
-  async callExternalAPI(userId) {
-    // Check rate limits
-    if (this.isRateLimited(userId)) {
-      throw new Error('Rate limit exceeded');
-    }
-    
-    try {
-      const result = await fetch(url, { timeout: 5000 });
-      return result;
-    } catch (error) {
-      // Don't expose internal errors
-      throw new Error('External verification failed');
-    }
-  }
-}
-```
-
-### 3. Smart Contract Interaction
-
-```javascript
-// CORRECT: Verify contract bytecode
-async verifyContract(address, expectedBytecode) {
-  const provider = new ethers.JsonRpcProvider(RPC_URL);
-  const code = await provider.getCode(address);
-  
-  if (code === '0x') {
-    throw new Error('No contract at address');
-  }
-  
-  // Optionally verify against known bytecode
-  if (expectedBytecode && code !== expectedBytecode) {
-    throw new Error('Contract bytecode mismatch');
-  }
-}
-```
-
-## Common Attack Vectors
-
-### 1. Proof Spoofing
-
-**Risk**: Malicious users attempting to forge verification results
-
-**Mitigation**:
-- Always verify ownership through on-chain data or cryptographic signatures
-- Never trust client-provided verification results
-- Use the protocol's signature verification for all critical operations
- - Use `verifierContentHash` for proof-of-existence; avoid publishing full content unless explicitly intended
-
-### 2. Replay Attacks
-
-**Risk**: Reusing old signatures or proofs
-
-**Mitigation**:
-- Built-in: 5-minute timestamp validation and anti-replay protections
-- Additional: Include chain-specific data in verification
-
-### 3. Unintended Data Exposure
-
-**Risk**: Accidentally exposing private content in public snapshots
-
-**Mitigation**:
-- Set `privacyLevel: 'private'` and avoid `publicDisplay`/`storeOriginalContent`
-- For anchoring without exposure, use `enableIpfs: true` with `publicDisplay: false`, `storeOriginalContent: false`
-- Ensure UI defaults use secure privacy settings
-
-### 4. Contract Upgrades
-
-**Risk**: Verified contracts changing implementation
-
-**Mitigation**:
-- Store contract address AND block number in proof
-- Consider proxy pattern detection
-- Document upgrade implications for users
-
-## Rate Limiting Guidelines
-
-### External APIs
-
-| Service Type | Recommended Limit | Timeout |
-|-------------|------------------|---------|
-| Blockchain RPC | 100 req/sec | 10s |
-| Social APIs | 10 req/min | 5s |
-| DNS Lookups | 50 req/min | 3s |
-| IPFS Gateway | 30 req/min | 30s |
-
-### Implementation Example
-
-```javascript
-class RateLimiter {
-  constructor(maxRequests, windowMs) {
-    this.requests = new Map();
-    this.maxRequests = maxRequests;
-    this.windowMs = windowMs;
-  }
-  
-  allow(identifier) {
-    const now = Date.now();
-    const requests = this.requests.get(identifier) || [];
-    
-    // Clean old requests
-    const valid = requests.filter(t => now - t < this.windowMs);
-    
-    if (valid.length >= this.maxRequests) {
-      return false;
-    }
-    
-    valid.push(now);
-    this.requests.set(identifier, valid);
-    return true;
-  }
-}
-```
-
-## Error Handling
-
-### Security-First Error Messages
-
-```javascript
-// CORRECT: Generic external errors
-catch (error) {
-  logger.error('Verification failed', { 
-    error: error.message,
-    userId: data.owner 
-  });
-  throw new Error('Verification failed');
-}
-
-// WRONG: Exposing internal details
-catch (error) {
-  throw new Error(`Database query failed: ${error.stack}`);
-}
-```
-
-## Reporting Security Issues
-
-Found a security vulnerability? Please report it responsibly:
-
-1. **DO NOT** create public GitHub issues for security vulnerabilities
-2. Email: dev@neus.network
-3. Include:
-   - Description of the vulnerability
-   - Steps to reproduce
-   - Potential impact
-   - Suggested fix (if applicable)
-
-## Security Updates
-
-Monitor security updates:
-- GitHub Security Advisories: https://github.com/neus/network/security
-- NPM Audit: Run `npm audit` regularly
-- Email updates: dev@neus.network
-
-## Compliance
-
-The NEUS Network is designed for:
-- GDPR compliance (no PII storage by default)
-- Cryptographic proof integrity
-- Decentralized trust model
-
-However, verifier implementations must ensure their own compliance based on data handled.
-
----
-
-*Version: 1.0.0*
+# NEUS SDK security notes
+
+Treat **wallet signatures** and **API keys** as secrets. Do not log them, expose them to clients, or store them in analytics.
+
+## Authentication model (public surface)
+
+- **Verification submission** (`POST /api/v1/verification`) is authenticated by a signature over the **NEUS Standard Signing String**.
+- **Status by Proof ID (qHash)** (`GET /api/v1/verification/status/{qHash}`) is safe to call publicly.
+- **Owner-only reads** of private proof payloads require an additional owner signature. The SDK uses:
+  - `x-wallet-address`
+  - `x-signature`
+  - `x-signed-timestamp`
+
+## Do not
+
+- Do not treat proof signatures as bearer tokens (they are request-bound).
+- Do not embed API keys in browser apps. Keep API keys server-side only.
+- Do not log or persist:
+  - proof signatures
+  - API keys
+  - third-party auth credentials or provider tokens (if your integration uses them)
+
+## Recommended privacy defaults
+
+- `privacyLevel: 'private'`
+- `publicDisplay: false`
+- `storeOriginalContent: false`
+
+“Discoverable” proofs are **public** (`privacyLevel='public'`) and explicitly opted into discovery (`publicDisplay=true`).