@neus/sdk 1.0.3 → 1.0.5

package/README.md

@@ -1,150 +1,127 @@
-# NEUS SDK
-
-JavaScript client (and optional widgets) for the NEUS Network verification API.
-
-## Install
-
-```bash
-npm install @neus/sdk
-```
-
-## 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({ apiUrl: 'https://api.neus.network' });
-
-const res = await client.verify({
-  verifier: 'ownership-basic',
-  content: 'Hello NEUS'
-});
-
-// Proof ID (standard). qHash is a deprecated alias.
-const proofId = res.proofId;
-const status = await client.getStatus(proofId);
-```
-
-## Client configuration
-
-```javascript
-const client = new NeusClient({
-  // Optional: API base URL (default: https://api.neus.network)
-  apiUrl: 'https://api.neus.network',
-  // Optional: request timeout (ms)
-  timeout: 30000,
-});
-```
-
-## Create a proof (server / manual signing)
-
-If you already have a signature over the NEUS Standard Signing String, submit it directly:
-
-```javascript
-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' }
-});
-```
-
-## What verifiers are available?
-
-Use the API directly (avoids drift):
-
-- `GET /api/v1/verification/verifiers`
-
-## Hosted interactive verifiers
-
-For interactive verifiers (`ownership-social`, `ownership-org-oauth`, `proof-of-human`), use `VerifyGate` hosted checkout mode.
-These flows require NEUS-hosted popup/redirect UX (OAuth/ZK), not direct wallet-only creation via `client.verify(...)`.
-
-```jsx
-import { VerifyGate } from '@neus/sdk/widgets';
-
-export default function HostedGateExample() {
-  return (
-    <VerifyGate
-      requiredVerifiers={['ownership-social']}
-      onVerified={(result) => {
-        console.log('Hosted verification complete:', result.proofId);
-      }}
-    >
-      <button>Unlock with Social</button>
-    </VerifyGate>
-  );
-}
-```
-
-## Gate checks (recommended for server-side gating)
-
-For production server-side gating, prefer the minimal public endpoint:
-
-```javascript
-const res = await client.gateCheck({
-  address: 'YOUR_WALLET_OR_DID',
-  verifierIds: ['token-holding'],
-  contractAddress: '0x...',
-  minBalance: '100',
-  chainId: 8453,
-  // Optional: require a recent proof for point-in-time verifiers (example: last hour)
-  since: Date.now() - 60 * 60 * 1000
-});
-
-if (!res.data?.eligible) {
-  throw new Error('Access denied');
-}
-```
-
-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.
-
-## Resilience & Polling
-
-The SDK is designed for production stability:
-- **Automatic Backoff**: `pollProofStatus()` automatically detects rate limiting (`429`) and applies jittered exponential backoff.
-- **Wallet Identification**: Automatically attaches headers to preferred wallet-based limiting for higher reliability behind shared IPs (NATs).
-
-- Private proof by Proof ID: `client.getPrivateStatus(proofId, wallet)`
-- Private proofs by wallet/DID: `client.getPrivateProofsByWallet(walletOrDid, { limit, offset }, wallet)` (owner dashboard / first-party UX only; not recommended for integrator gating)
-- Revoke your proof: `client.revokeOwnProof(proofId, wallet)`
-
-Example:
-
-```javascript
-const privateData = await client.getPrivateStatus(proofId, window.ethereum);
-
-const privateProofs = await client.getPrivateProofsByWallet(
-  'YOUR_WALLET_OR_DID',
-  { limit: 50, offset: 0 },
-  window.ethereum
-);
-
-await client.revokeOwnProof(proofId, window.ethereum);
-```
-
-Compatibility note: `qHash` remains supported as a deprecated alias (`proofId === qHash`).
-
-## React widgets
-
-For UI gating, see `./widgets/README.md`.
-
-Widget imports:
-
-```javascript
-import { VerifyGate, ProofBadge } from '@neus/sdk/widgets';
-```
-
-## Reference docs
-
-- API Reference: `../docs/api/README.md`
-- OpenAPI (JSON): `../docs/api/public-api.json`
+# @neus/sdk
+
+[![npm](https://img.shields.io/npm/v/%40neus%2Fsdk?logo=npm&label=%40neus%2Fsdk&color=98C0EF)](https://www.npmjs.com/package/@neus/sdk)
+
+**Portable trust, shipped as APIs and widgets.** The JavaScript SDK runs NEUS verification, polling, and **`gateCheck`**. Store **`proofId`** (your **proof ID**) once, then reuse. NEUS runs the checks; you do not fork verifier logic into your repo.
+
+## Install
+
+```bash
+npm install @neus/sdk
+```
+
+## One-command onboarding
+
+```bash
+npx -y -p @neus/sdk neus init
+```
+
+Configures supported MCP clients automatically. By default the command installs NEUS into user-level Claude Code, Cursor, and VS Code MCP config when those clients are detected.
+
+## CLI
+
+```bash
+# Autopilot setup for detected clients
+npx -y -p @neus/sdk neus init
+
+# Enable personal account tools such as neus_me and private reads
+npx -y -p @neus/sdk neus auth --access-key <npk_...>
+
+# Inspect current NEUS MCP setup
+npx -y -p @neus/sdk neus status --json
+```
+
+Use `neus init --project` when you want shared repo config instead of personal user-scope setup. Access keys stay user-scope only so secrets do not land in checked-in config.
+
+## Minimal working example
+
+```javascript
+import { NeusClient } from '@neus/sdk';
+
+const client = new NeusClient();
+
+const proof = await client.verify({
+  verifier: 'ownership-basic',
+  content: 'Hello NEUS',
+  wallet: window.ethereum,
+});
+
+const proofId = proof.proofId;
+
+const check = await client.gateCheck({
+  address: '0x...',
+  verifierIds: ['ownership-basic'],
+});
+```
+
+> [Hosted Verify](https://docs.neus.network/cookbook/auth-hosted-verify) | [Get started](https://docs.neus.network/get-started)
+
+## Core methods
+
+| Method | Purpose |
+| --- | --- |
+| `client.verify()` | Create proof |
+| `client.getProof()` | Fetch by `proofId` |
+| `client.pollProofStatus()` | Wait for async completion |
+| `client.gateCheck()` | **Server eligibility** (use for real gates) |
+| `client.checkGate()` | Local preview only |
+| `getHostedCheckoutUrl()` | Hosted verify URL |
+| `client.createWalletLinkData()` | Build advanced direct wallet-link payload |
+
+## VerifyGate (React)
+
+Defaults: unlisted public create (`privacyLevel: 'public'`, `publicDisplay: false`). Set `proofOptions` for other visibility.
+
+```jsx
+import { VerifyGate } from '@neus/sdk/widgets';
+
+<VerifyGate appId="your-app-id" requiredVerifiers={['ownership-basic']}>
+  <ProtectedContent />
+</VerifyGate>
+```
+
+[Widgets README](./widgets/README.md)
+
+## Config
+
+```javascript
+const client = new NeusClient({
+  apiUrl: 'https://api.neus.network',
+  appId: 'my-app',
+  timeout: 30000,
+});
+```
+
+## Wallet-link
+
+For user-facing browser flows, prefer Hosted Verify so the user can select a secondary wallet, sign once, see the linked state, and only then continue to proof creation.
+
+Use `client.createWalletLinkData()` only for advanced direct/API flows where your app already controls the secondary-wallet provider:
+
+```javascript
+const walletLinkData = await client.createWalletLinkData({
+  primaryWalletAddress: '0xprimary...',
+  secondaryWalletAddress: '0xsecondary...',
+  wallet: window.ethereum,
+  relationshipType: 'linked',
+  label: 'ops-wallet'
+});
+
+await client.verify({
+  verifier: 'wallet-link',
+  data: walletLinkData
+});
+```
+
+## Docs
+
+- [Quickstart](https://docs.neus.network/quickstart)
+- [SDK](https://docs.neus.network/sdks/javascript)
+- [MCP](https://docs.neus.network/mcp/overview) (IDEs and assistants)
+- [Widgets](https://docs.neus.network/widgets/overview)
+- [API](https://docs.neus.network/api/overview)
+- [Hosted Verify](https://docs.neus.network/cookbook/auth-hosted-verify)
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for how to propose documentation, SDK, and example changes.

package/SECURITY.md

@@ -1,29 +1,33 @@
-# 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`).
+# 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
+
+- **Verification requests** are authenticated with a wallet signature over the **CAIP-380 Portable Proof** six-line signing string. Never roll your own message format in production—use the SDK or the hosted preparation step documented for HTTP integrations.
+- **Proof lookups by `proofId`** are safe for public proofs. Private proofs return a minimal payload unless the caller proves ownership (authenticated owner or signed request).
+- **Owner-only reads** of private proof payloads require an extra owner-signed request. The SDK attaches the required signed headers for you.
+
+## 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, or third-party auth credentials (if your integration uses them).
+
+## Privacy defaults
+
+**`client.verify()`** defaults to **private** stored results with **original content stored** (owner-authenticated reads).
+
+**`VerifyGate`** create mode defaults to **unlisted public** (`privacyLevel: 'public'`, `publicDisplay: false`, `storeOriginalContent: true`) so gates and `gateCheck` work without extra options.
+
+For raw SDK flows that must power **`gateCheck`** without owner-authenticated access, set **unlisted public** explicitly (`privacyLevel: 'public'`, `publicDisplay: false`). Anyone with the proof id can resolve public proofs. Do not treat unlisted as secret.
+
+**Hide original content** (metadata/hash only): set `storeOriginalContent: false` when your product must not persist original bytes.
+
+Controls:
+
+- `privacyLevel` - private (vaulted to the wallet) vs public (eligible for policy checks without proving owner identity)
+- `publicDisplay` - discovery vs unlisted
+- `storeOriginalContent` - retain original content vs hash/metadata only
+
+Discoverable listings require **`privacyLevel: 'public'`** and **`publicDisplay: true`**.