@worldcoin/idkit-core 4.0.1-dev.123c6a8 → 4.0.1-dev.370b7c0

package/README.md

@@ -1,186 +1,112 @@
 # @worldcoin/idkit-core
 
-Core bridge logic for IDKit (World ID SDK) powered by Rust/WASM.
+World ID verification SDK for JavaScript/TypeScript. Zero dependencies, WASM-powered.
 
 ## Installation
 
 ```bash
 npm install @worldcoin/idkit-core
-# or
-pnpm add @worldcoin/idkit-core
 ```
 
-## Quick Start
+## Backend: Generate RP Signature
+
+The RP signature authenticates your verification requests. Generate it server-side using the `/signing` subpath (pure JS, no WASM init needed):
 
 ```typescript
-import { useWorldBridgeStore } from "@worldcoin/idkit-core";
+import { signRequest } from "@worldcoin/idkit-core/signing";
 
-// 1. Get store instance
-const store = useWorldBridgeStore();
+// Never expose RP_SIGNING_KEY to clients
+const sig = signRequest("my-action", process.env.RP_SIGNING_KEY);
 
-// 2. Create client with explicit requests
-const client = await store.createClient({
-  app_id: "app_staging_xxxxx",
-  action: "my-action",
-  requests: [{ credential_type: "orb", signal: "user-id-123" }],
+// Return to client
+res.json({
+  sig: sig.sig,
+  nonce: sig.nonce,
+  created_at: sig.createdAt,
+  expires_at: sig.expiresAt,
 });
-
-// 3. Display QR code for World App
-console.log("Scan this:", client.connectorURI);
-
-// 4. Poll for proof (handles polling automatically)
-try {
-  const proof = await client.pollForUpdates();
-  console.log("Success:", proof);
-} catch (error) {
-  console.error("Verification failed:", error);
-}
 ```
 
-## Multiple Credential Types
-
-You can request verification with multiple credential types. The user can satisfy the request with any of them:
-
-```typescript
-const client = await store.createClient({
-  app_id: "app_staging_xxxxx",
-  action: "my-action",
-  requests: [
-    { credential_type: "orb", signal: "user-id-123" },
-    { credential_type: "device", signal: "user-id-123" },
-  ],
-});
-```
+## Client: Create Verification Request
 
-## Credential Types
+### Using Presets
 
-- `orb` - Verified via Orb biometric scan (highest trust)
-- `face` - Verified via Face ID
-- `device` - Verified via device binding
-- `document` - Verified via document scan
-- `secure_document` - Verified via secure document scan
-
-## API Reference
-
-### Creating a Client
-
-```typescript
-const client = await store.createClient(config);
-```
-
-**Config:**
+For common verification scenarios with World ID 3.0 backward compatibility:
 
 ```typescript
-interface IDKitConfig {
-  app_id: `app_${string}`; // Your World ID app ID
-  action: string; // Action identifier
-  requests: RequestConfig[]; // Required: credential type requests
-  bridge_url?: string; // Custom bridge URL (optional)
-  partner?: boolean; // Partner mode (optional)
-}
+import { IDKit, orbLegacy } from "@worldcoin/idkit-core";
 
-interface RequestConfig {
-  credential_type: CredentialType;
-  signal?: string | AbiEncodedValue; // Optional signal for this request
-}
+// Fetch signature from your backend
+const rpSig = await fetch("/api/rp-signature").then((r) => r.json());
 
-type CredentialType =
-  | "orb"
-  | "face"
-  | "device"
-  | "document"
-  | "secure_document";
+const request = await IDKit.request({
+  app_id: "app_xxxxx",
+  action: "my-action",
+  rp_context: {
+    rp_id: "rp_xxxxx",
+    nonce: rpSig.nonce,
+    created_at: rpSig.created_at,
+    expires_at: rpSig.expires_at,
+    signature: rpSig.sig,
+  },
+  allow_legacy_proofs: false,
+}).preset(orbLegacy({ signal: "user-123" }));
+
+// Display QR code for World App
+const qrUrl = request.connectorURI;
 ```
 
-**Client Properties:**
-
-- `connectorURI: string` - QR code URL for World App
-- `requestId: string` - Unique request ID
+**Available presets:** `orbLegacy`, `documentLegacy`, `secureDocumentLegacy`
 
-**Client Methods:**
+## Handling the Result
 
-- `pollForUpdates(options?: WaitOptions): Promise<ISuccessResult>` - Poll for proof (auto-polls)
-- `pollOnce(): Promise<Status>` - Poll once for status (manual polling)
-
-**WaitOptions:**
+Poll for the verification proof, then verify it server-side:
 
 ```typescript
-interface WaitOptions {
-  pollInterval?: number; // ms between polls (default: 1000)
-  timeout?: number; // total timeout ms (default: 300000 = 5min)
-  signal?: AbortSignal; // for cancellation
-}
-```
+// Wait for the user to scan and approve
+const completion = await request.pollUntilCompletion({
+  pollInterval: 2000,
+  timeout: 120_000,
+});
 
-### Store
+if (!completion.success) {
+  console.error("Verification failed:", completion.error);
+  return;
+}
 
-```typescript
-const store = useWorldBridgeStore();
+// Send proof to your backend for verification
+const verified = await fetch("/api/verify-proof", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify(completion.result),
+}).then((r) => r.json());
 ```
 
-**Methods:**
-
-- `createClient(config: IDKitConfig): Promise<WorldBridgeClient>` - Create new client
-- `reset(): void` - Clear state and start over
-
-**State (for reactive frameworks):**
-
-- `verificationState: VerificationState` - Current verification state
-- `connectorURI: string | null` - QR code URL for World App
-- `result: ISuccessResult | null` - Proof data when verified
-- `errorCode: AppErrorCodes | null` - Error code if failed
-
-### Result Types
+On your backend, forward the result to the Developer Portal:
 
 ```typescript
-interface ISuccessResult {
-  proof: string;
-  merkle_root: string;
-  nullifier_hash: string;
-  verification_level: CredentialType; // The credential type used
-}
+const response = await fetch(
+  `https://developer.worldcoin.org/api/v4/verify/${RP_ID}`,
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(req.body),
+  },
+);
+
+const { success } = await response.json();
 ```
 
-## React Integration
-
-```tsx
-import { useWorldBridgeStore, IDKitWidget } from "@worldcoin/idkit-core";
-
-function MyComponent() {
-  const handleSuccess = (result) => {
-    console.log("Verified:", result);
-  };
-
-  return (
-    <IDKitWidget
-      app_id="app_staging_xxxxx"
-      action="my-action"
-      requests={[{ credential_type: "orb", signal: "user-123" }]}
-      onSuccess={handleSuccess}
-    >
-      {({ open }) => <button onClick={open}>Verify with World ID</button>}
-    </IDKitWidget>
-  );
-}
-```
-
-## Examples
-
-See [examples/browser](../../examples/browser) for a complete working example.
+## Subpath Exports
 
-## Building from Source
+Pure JS subpath exports are available for server-side use without WASM initialization:
 
-```bash
-# Build WASM module
-npm run build:wasm
-
-# Build TypeScript
-npm run build:ts
+| Subpath    | Exports                                                          |
+| ---------- | ---------------------------------------------------------------- |
+| `/signing` | `signRequest`, `computeRpSignatureMessage`, `RpSignature` (type) |
+| `/hashing` | `hashSignal`                                                     |
 
-# Or both
-npm run build
+```typescript
+import { signRequest } from "@worldcoin/idkit-core/signing";
+import { hashSignal } from "@worldcoin/idkit-core/hashing";
 ```
-
-## License
-
-MIT

package/dist/hashing.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+var sha3 = require('@noble/hashes/sha3');
+var utils = require('@noble/hashes/utils');
+
+// src/lib/hashing.ts
+function hashToField(input) {
+  const hash = BigInt("0x" + utils.bytesToHex(sha3.keccak_256(input))) >> 8n;
+  return utils.hexToBytes(hash.toString(16).padStart(64, "0"));
+}
+function hashSignal(signal) {
+  let input;
+  if (signal instanceof Uint8Array) {
+    input = signal;
+  } else if (signal.startsWith("0x") && isValidHex(signal.slice(2))) {
+    input = utils.hexToBytes(signal.slice(2));
+  } else {
+    input = new TextEncoder().encode(signal);
+  }
+  return "0x" + utils.bytesToHex(hashToField(input));
+}
+function isValidHex(s) {
+  if (s.length === 0) return false;
+  if (s.length % 2 !== 0) return false;
+  return /^[0-9a-fA-F]+$/.test(s);
+}
+
+exports.hashSignal = hashSignal;

package/dist/hashing.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Hashes a signal to its field element hex representation.
+ *
+ * @param signal - The signal to hash (string or Uint8Array)
+ * @returns 0x-prefixed hex string representing the signal hash
+ */
+declare function hashSignal(signal: string | Uint8Array): string;
+
+export { hashSignal };

package/dist/hashing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hashes a signal to its field element hex representation.
+ *
+ * @param signal - The signal to hash (string or Uint8Array)
+ * @returns 0x-prefixed hex string representing the signal hash
+ */
+declare function hashSignal(signal: string | Uint8Array): string;
+
+export { hashSignal };

package/dist/hashing.js

@@ -0,0 +1,26 @@
+import { keccak_256 } from '@noble/hashes/sha3';
+import { hexToBytes, bytesToHex } from '@noble/hashes/utils';
+
+// src/lib/hashing.ts
+function hashToField(input) {
+  const hash = BigInt("0x" + bytesToHex(keccak_256(input))) >> 8n;
+  return hexToBytes(hash.toString(16).padStart(64, "0"));
+}
+function hashSignal(signal) {
+  let input;
+  if (signal instanceof Uint8Array) {
+    input = signal;
+  } else if (signal.startsWith("0x") && isValidHex(signal.slice(2))) {
+    input = hexToBytes(signal.slice(2));
+  } else {
+    input = new TextEncoder().encode(signal);
+  }
+  return "0x" + bytesToHex(hashToField(input));
+}
+function isValidHex(s) {
+  if (s.length === 0) return false;
+  if (s.length % 2 !== 0) return false;
+  return /^[0-9a-fA-F]+$/.test(s);
+}
+
+export { hashSignal };