attestid_js_sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,454 @@
-# Temporary Holding Version
+# attestid_js_sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official JavaScript / TypeScript SDK for the AttestID KYC API.
+
+Handles credential management, ID photo quality checks, liveness sequencing, and fraud detection — so your integration is a few lines, not hundreds.
+
+---
+
+## Installation
+
+```bash
+npm install attestid_js_sdk
+```
+
+React support is included via a separate entry point. Peer deps `react` and `react-dom` (≥ 18) are optional — only install them if you use `attestid_js_sdk/react`.
+
+---
+
+## Quick start
+
+`apiKey` is a long-lived secret. **Never construct `AttestID` with `apiKey` in browser or mobile app code** — a bundler would ship it to every visitor, and anyone could read it from devtools or a decompiled bundle. `AttestID` enforces this at runtime: passing `apiKey` outside a real Node.js backend process throws `INSECURE_CONFIG` immediately.
+
+`apiUrl` must be `https://` — the SDK also enforces this at runtime, throwing `INSECURE_CONFIG` for a plain `http://` URL. The one exception is a loopback host (`localhost` / `127.0.0.1` / `::1`), which stays `http://` so you can point the SDK at a local backend that isn't running TLS. This means the same guard applies whether you're testing locally or integrating against a real environment — if a QA or staging URL isn't `localhost`, it must be `https://` too, so API keys, SDK tokens, and uploaded ID photos are never sent in the clear.
+
+In the browser, configure `getSdkToken` instead — a callback that fetches an already-minted `sdk_token` from **your own backend**, which holds `apiKey` server-side and calls `POST /kyc/session` on your behalf:
+
+```ts
+// your-backend/routes/attestid-session.ts (Node.js — never shipped to the browser)
+export async function attestidSession(userId: string) {
+  const res = await fetch(`${process.env.ATTESTID_API_URL}/v1/kyc/session`, {
+    method: 'POST',
+    headers: {
+      'X-API-Key': process.env.ATTESTID_API_KEY!,           // sk_live_... — server-only
+      'X-Access-Key-Id': process.env.ATTESTID_ACCESS_KEY_ID!,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ user_id: userId }),
+  });
+  return res.json(); // { sdk_token, user_id, expires_in }
+}
+```
+
+```ts
+// browser code
+import { AttestID } from 'attestid_js_sdk';
+
+const client = new AttestID({
+  apiUrl: 'https://<your-attestid-api-host>', // from your AttestID dashboard
+  // Never embed apiKey here — fetch a short-lived sdk_token from your backend instead.
+  getSdkToken: (userId) =>
+    fetch('/api/attestid-session', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ userId }),
+    }).then(r => r.json()),
+});
+```
+
+Then run the flow in React, either way:
+
+- **Drop-in:** render `<AttestIDVerifier client={client} />` — consent, camera capture, quality checks, the face check and the result screen in one component. See [Drop-in React component](#drop-in-react-component).
+- **Custom UI:** drive the steps yourself with `useAttestID(client)`, and mount `<AttestIDLivenessCheck />` for the face check. See [React hook](#react-hook).
+
+Either way, send `result.attestation` to your backend and verify it there before acting on the result — see [Verify results on your backend](#verify-results-on-your-backend).
+
+---
+
+## Account setup
+
+Signing up and issuing API keys is a dashboard-only flow, not something this SDK exposes:
+
+1. Register your company and owner account, then verify the owner's email address.
+2. Log in to the AttestID dashboard.
+3. Self-issue an API key (test or live) from the dashboard — it's shown once, so store it in your backend's secret store immediately.
+
+Use that `api_key` (and its paired `access_key_id`) to construct `AttestID` in server mode, as shown above.
+
+---
+
+## Security
+
+The SDK supports the AttestID API's security hardening. Everything below is
+on by default where it applies, and it all degrades gracefully against an
+older API.
+
+| Feature | Where it runs | What you need to do |
+|---|---|---|
+| Safe automatic retries (`Idempotency-Key`) | everywhere | Nothing. Optionally tune `retry` |
+| Device-bound capture signing | browser | Nothing. Opt out with `deviceBinding: false` |
+| Signed results (`result.attestation`) | **your backend** | Call `verifyAttestation()` before trusting `verified` |
+| Signed webhooks + secret rotation | **your backend** | Call `verifyWebhook()` on every delivery |
+| Mutual TLS (optional, per account) | your backend | Pass an mTLS-bound `fetch` |
+
+### Safe automatic retries
+
+Every `POST` (`/kyc/session`, `/kyc/start`, `/kyc/complete`) carries an
+`Idempotency-Key`, and failed calls are retried automatically (default 3
+attempts, exponential backoff):
+
+- **Network error:** retried with the **same** key, so if the first attempt actually reached the server, you get its stored response back instead of a duplicate session or a second billed verification.
+- **`409` (still processing):** waits for `Retry-After`, then retries with the same key.
+- **`5xx` / `429`:** the server stored nothing, so the request is rebuilt with a fresh key, and a fresh device-signing nonce when the request is a photo upload.
+- **Any other `4xx`:** thrown immediately, never retried.
+
+```ts
+new AttestID({ apiUrl, getSdkToken, retry: { attempts: 4, baseDelayMs: 750 } });
+```
+
+### Device-bound capture signing (browser)
+
+In browser mode the SDK creates an ECDSA P-256 key with WebCrypto as
+**non-extractable**: script, including this SDK, can sign with it but can
+never read or export it. It's stored in IndexedDB, with an in-memory
+fallback in private mode or webviews. On every `startVerification()` it:
+
+1. registers the public key with AttestID (`POST /kyc/device/challenge` + `/kyc/device/register`). The server de-duplicates, so this is cheap.
+2. signs `attestid-capture-v1|sha256(exact photo bytes)|user_id|nonce|timestamp` with a fresh single-use nonce, and sends the signature with the upload.
+
+AttestID records the result as the verification's `capture_assurance`
+(inside the signed attestation). A photo replayed or injected straight
+into the API, with a wrong key, a reused nonce or altered bytes, is **held
+for fraud review**.
+
+- **Best-effort:** if WebCrypto, IndexedDB or the device endpoints are unavailable, the photo is uploaded **unsigned** (assurance `none`, not penalised). The SDK never sends a partial signature.
+- **What the web can prove:** browsers have no hardware attestation, so web keys reach `key_bound`, never `hardware_attested` (that needs the native SDKs with App Attest / Play Integrity). It proves the photo came through this SDK on the device that holds the key, not that it came from the physical camera.
+- **Server mode:** always off, because a backend process isn't the user's device.
+
+```ts
+new AttestID({ apiUrl, getSdkToken, deviceBinding: false }); // opt out
+```
+
+### Verify results on your backend
+
+Every result includes `result.attestation`, an ES256-signed
+record of the decision issued by AttestID. The plain `verified` field
+travels through the browser, so it can be tampered with there. **Before you
+act on a result (open an account, release funds), verify the attestation on
+your backend** against AttestID's public keys:
+
+```ts
+// your backend (Node 19+, or any runtime with WebCrypto)
+import { verifyAttestation, SignatureError } from 'attestid_js_sdk';
+
+const claims = await verifyAttestation(result.attestation, {
+  apiUrl: process.env.ATTESTID_API_URL!,     // keys fetched from /.well-known/jwks.json (cached)
+  verificationId: expectedVerificationId,     // must be the session you started
+  companyId: process.env.ATTESTID_COMPANY_ID, // optional
+  document: result.document,                  // optional: proves the ID data wasn't altered
+});
+if (!claims.verified) throw new Error('Not verified');
+claims.capture_assurance; // 'hardware_attested' | 'key_bound' | 'none' | 'invalid'
+```
+
+It throws `SignatureError` on a bad signature, an unexpected algorithm
+(`alg: none` and HS256 are rejected), the wrong verification or company id,
+or document data that doesn't match `document_sha256`. Signing keys rotate
+on the server; the SDK refetches the key set when it sees a new `kid`.
+
+### Verify webhooks
+
+Pass the **raw** request body (before JSON parsing) and the headers:
+
+```ts
+import express from 'express';
+import { verifyWebhook } from 'attestid_js_sdk';
+
+app.post('/webhooks/attestid', express.raw({ type: 'application/json' }), async (req, res) => {
+  try {
+    const event = await verifyWebhook(req.body, req.headers, {
+      // During a secret rotation, list BOTH secrets: either one verifies.
+      secrets: [process.env.ATTESTID_WEBHOOK_SECRET!, process.env.ATTESTID_WEBHOOK_SECRET_OLD].filter(Boolean) as string[],
+      apiUrl: process.env.ATTESTID_API_URL, // also verifies the asymmetric AttestID-JWS header
+    });
+    // ...handle event...
+    res.sendStatus(200);
+  } catch {
+    res.sendStatus(400);
+  }
+});
+```
+
+- **`secrets`** checks the HMAC `AttestID-Signature` header. During a rotation AttestID signs with both the new and the old secret until you confirm the rotation (`POST /v1/webhooks/rotation/confirm`) or the overlap window ends.
+- **`apiUrl`** checks `AttestID-JWS`, a signature anyone can verify with AttestID's public key. Unlike the shared HMAC secret, it proves to a third party (an auditor) that AttestID sent it.
+- **Replay protection:** both timestamps must be within `toleranceSeconds` (default 300).
+
+### Mutual TLS (server mode)
+
+If your account requires a client certificate (dashboard → Client
+certificates), give the SDK a `fetch` that presents it. For example, with
+Node's bundled undici:
+
+```ts
+import { Agent, fetch as undiciFetch } from 'undici';
+import { readFileSync } from 'node:fs';
+
+const mtls = new Agent({ connect: { cert: readFileSync('client.crt'), key: readFileSync('client.key') } });
+
+const client = new AttestID({
+  apiUrl: process.env.ATTESTID_API_URL!,
+  apiKey: process.env.ATTESTID_API_KEY!,
+  accessKeyId: process.env.ATTESTID_ACCESS_KEY_ID!,
+  fetch: (url, init) => undiciFetch(url, { ...init, dispatcher: mtls } as never) as unknown as Promise<Response>,
+});
+```
+
+Generate the key and CSR on your server (`openssl ecparam -name prime256v1 -genkey -noout -out client.key && openssl req -new -key client.key -subj "/CN=attestid-client" -out client.csr`). Your private key never leaves your infrastructure.
+
+### Runtime requirements
+
+The verification helpers and device signing use WebCrypto
+(`globalThis.crypto.subtle`): any modern browser, **Node.js 19+**, Deno,
+Bun, or edge runtimes. On a runtime without it, `verifyAttestation` /
+`verifyWebhook` throw `CRYPTO_UNAVAILABLE`, and device signing is skipped
+silently.
+
+---
+
+## Photo quality check
+
+Run `checkPhotoQuality` client-side before uploading to give users instant feedback and avoid unnecessary API calls:
+
+```ts
+import { checkPhotoQuality } from 'attestid_js_sdk';
+
+const result = await checkPhotoQuality(file, idType);
+// result.ok     — true when all checks pass
+// result.issues — array of human-readable strings describing problems
+
+if (!result.ok) {
+  // Show result.issues to the user before letting them submit
+}
+```
+
+Checks performed:
+- **File size** — rejects obviously non-image blobs
+- **Blur** — Laplacian variance; flags camera shake or out-of-focus shots
+- **Brightness** — flags underexposed and overexposed images
+- **Document type** — flags a passport uploaded as an ID card (or vice versa) from its shape
+- **Passport MRZ** — the data page must show the machine-readable zone (the two lines of `<<<` text). Rejects the cover, visa pages, a cropped-off MRZ, or glare across it. In a two-page spread the half with the MRZ is treated as the data page, and only its blur is evaluated
+- **ID card / driver's licence text** — the front must show several printed lines in a column (name, date of birth, ID number). Rejects the back of the card, a blank surface, or a photo of something else. No MRZ is needed on cards
+- **Face count** — where the browser supports the Shape Detection API, flags no face or more than one face
+
+The MRZ, card-size and text checks look at shapes and layout, not characters: no OCR library is bundled, and together they take about 20-70 ms. Where Chromium's `TextDetector` is available it's used as a second opinion that can only pass a photo, never reject one. A present but partly unreadable MRZ still goes to the API, which reads it properly.
+
+`AttestIDVerifier` and `useAttestID` won't submit a photo while `checkPhotoQuality` reports issues. If you call `startKYC` directly, gating on `checkPhotoQuality` is up to you.
+
+---
+
+## Drop-in React component
+
+`AttestIDVerifier` is the fastest way to ship KYC in a React app: consent capture, in-browser camera capture with a review-before-submit step, client-side photo quality gating, liveness detection, and a result screen — all built in.
+
+```tsx
+import { AttestID } from 'attestid_js_sdk';
+import { AttestIDVerifier } from 'attestid_js_sdk/react';
+import 'attestid_js_sdk/styles.css';
+
+const client = new AttestID({
+  apiUrl: 'https://<your-attestid-api-host>', // from your AttestID dashboard
+  getSdkToken: (userId) =>
+    fetch('/api/attestid-session', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ userId }),
+    }).then(r => r.json()),
+});
+
+function KYCPage() {
+  return (
+    <AttestIDVerifier
+      client={client}
+      defaultUserId="user-123"
+      onVerified={(result) => console.log('Verified:', result.verified)}
+      onError={(error) => console.error('Verification error:', error)}
+    />
+  );
+}
+```
+
+| Prop | Type | Description |
+|---|---|---|
+| `client` | `AttestID` | Configured client instance |
+| `defaultUserId` | `string?` | Pre-fills the user ID field |
+| `onVerified` | `(result: KYCResult) => void` | Called once the flow reaches `done` |
+| `onError` | `(error: string) => void` | Called on any error message from the flow |
+| `mobileHandoffUrl` | `string?` | Page a desktop visitor's phone is sent to via QR/link. Defaults to the current page |
+| `allowDesktopCapture` | `boolean?` | Let laptops/desktops capture the document with the webcam (phone QR still offered as an option). Default `true`; `false` makes capture phone-only |
+| `allowPhotoUpload` | `boolean?` | Show an "Upload photo" option to pick an existing image instead of using the camera. For testing — uploads bypass live capture. Default `false` |
+
+Need more control over the steps, styling, or layout? Build on `useAttestID` directly — see below.
+
+---
+
+## React hook
+
+```tsx
+import { useAttestID, AttestIDLivenessCheck } from 'attestid_js_sdk/react';
+
+function KYCPage() {
+  const verification = useAttestID(client);
+  const { state, error, qualityIssues, result, isLoading,
+          startVerification, canRetryLiveness, retryLiveness, reset } = verification;
+
+  // consentGivenAt must be when the user actually agreed, not when the upload fires.
+  const upload = (file: File) =>
+    startVerification({ userId: 'user-123', idType: 'national_id', idPhoto: file, consentGivenAt });
+
+  if (state === 'liveness') {
+    // Runs the face check, then completes the verification.
+    return <AttestIDLivenessCheck verification={verification} onError={console.error} />;
+  }
+  if (state === 'done' && result) {
+    return (
+      <>
+        <p>{result.verified ? 'Verified' : result.message}</p>
+        {canRetryLiveness && <button onClick={retryLiveness}>Retry face check</button>}
+        <button onClick={reset}>Start again</button>
+      </>
+    );
+  }
+  // ...your consent + document capture UI, calling upload(file)...
+}
+```
+
+`startVerification` runs the quality check first, then on pass uploads the ID and prepares the face check. If quality fails, `state` becomes `'error'` and `qualityIssues` is populated — no API call is made.
+
+### Return values
+
+| Property | Type | Description |
+|---|---|---|
+| `state` | `VerifyState` | Current flow state (see below) |
+| `error` | `string \| null` | Last API error message |
+| `qualityIssues` | `string[]` | Human-readable quality problems (populated on `error` after a quality failure) |
+| `result` | `KYCResult \| null` | Final verification result |
+| `isLoading` | `boolean` | `true` while in `quality_check`, `uploading`, `retrying`, or `completing` |
+| `startVerification` | `(opts: StartKYCOptions) => Promise<void>` | Start the flow |
+| `canRetryLiveness` | `boolean` | `true` when `result` failed only at the face check, so `retryLiveness()` can be offered |
+| `retryLiveness` | `() => Promise<void>` | Get a fresh face-check session on the same verification and go back to `liveness`, without uploading the ID again |
+| `reset` | `() => void` | Reset all state back to `idle` |
+
+### States
+
+| State | Meaning |
+|---|---|
+| `idle` | Ready to start |
+| `quality_check` | Running client-side photo quality checks |
+| `uploading` | Uploading ID photo and preparing the face check |
+| `retrying` | Getting a fresh face-check session for `retryLiveness()` |
+| `liveness` | Waiting for the face check: mount `AttestIDLivenessCheck` |
+| `completing` | Fetching the final result |
+| `done` | Result available in `result` |
+| `error` | Something went wrong; see `error` or `qualityIssues` |
+
+---
+
+## Face check
+
+`AttestIDVerifier` runs the face check for you. With the hook, mount `AttestIDLivenessCheck` while `state === 'liveness'`: it runs the check and completes the verification when it finishes. It renders nothing in any other state.
+
+| Prop | Type | Description |
+|---|---|---|
+| `verification` | `ReturnType<typeof useAttestID>` | The object returned by `useAttestID()` (required) |
+| `onError` | `(error: unknown) => void` | Called on a camera or face-check error |
+| `deviceId` | `string?` | Forwarded to the backend when the verification completes |
+| `showFlashNotice` | `boolean?` | Show the flashing-colours notice first. Default `true` |
+| `lightingCheckMs` | `number?` | How long to coach the user towards better light before starting. Default `10000`; `0` skips it |
+
+Things to know:
+- **Timing.** A face-check session expires about 3 minutes after it starts. A failed or expired check needs a new session (see "Retrying a failed face check" below).
+- **Photosensitivity.** The check can flash colours on screen. The SDK shows a notice before starting (`showFlashNotice`, default on). Keep it, or show your own.
+- **Device binding.** With device binding on, the face-check capture is signed with the same device key as the ID photo.
+- **Browser support.** Current Chrome, Edge, Firefox, Safari 14.1+, and iOS 14.3+, in a secure context (https, or http://localhost).
+
+### Retrying a failed face check
+
+When a verification fails only at the face check (`liveness_failed`, `liveness_confidence_too_low`, or `face_match_failed` with a score), the user can retry it without uploading the ID photo again; the document checks already done still count. `AttestIDVerifier` shows a **Try again** button (retake the selfie, same ID) next to **Start over** (upload a new ID) when this applies. Each failed face match still counts toward the API's per-user face-match strike limit. With the hook, offer your own button when `canRetryLiveness` is `true` and call `retryLiveness()`: `state` goes back to `liveness` and `AttestIDLivenessCheck` runs the check again.
+
+The API refuses a retry (`KYCError`, HTTP 409/410) in these cases:
+- suspected spoofs, face-match failures and fraud holds, which always need a new verification;
+- after 2 retries on one verification;
+- more than 30 minutes after the ID was uploaded.
+
+When it refuses, start over with `reset()` / a new `startVerification()`.
+
+---
+
+## Camera utilities
+
+```ts
+import { openCameraSession, DOC_ASPECT } from 'attestid_js_sdk';
+
+const session = await openCameraSession('national_id');
+// session.stream          — raw MediaStream
+// session.captureFrame(frameEl, videoEl) → Promise<File>  — crop to document frame
+// session.stop()          — release camera
+
+// Aspect ratios for sizing your document overlay frame
+// DOC_ASPECT.national_id      === 85.6 / 54  (ISO 7810 ID-1)
+// DOC_ASPECT.drivers_licence  === 85.6 / 54  (ISO 7810 ID-1)
+// DOC_ASPECT.passport         === 125  / 88  (ISO 7810 ID-3)
+```
+
+---
+
+## Supported ID types
+
+| `IdType` value | Document |
+|---|---|
+| `national_id` | National ID card (any country, ISO 7810 ID-1) |
+| `passport` | Passport booklet data page (ISO 7810 ID-3) |
+| `drivers_licence` | Driver's licence (ISO 7810 ID-1) |
+
+---
+
+## Error handling
+
+All errors extend `AttestIDError` and expose `code` and optionally `status`:
+
+```ts
+import { AttestIDError, AuthError, KYCError, CameraError } from 'attestid_js_sdk';
+
+try {
+  await client.startVerification({ ... });
+} catch (e) {
+  if (e instanceof AuthError)     console.error('Auth failed', e.status);   // 401/403
+  if (e instanceof KYCError)      console.error('KYC failed', e.code, e.status);
+  if (e instanceof CameraError)   console.error('Camera error', e.message);
+  if (e instanceof AttestIDError) console.error(e.code, e.message);         // e.g. CONSENT_REQUIRED, INSECURE_CONFIG
+}
+```
+
+| Class | `code` | When thrown |
+|---|---|---|
+| `AuthError` | `AUTH_ERROR` | Invalid API key/access key, an expired or invalid `sdk_token` (401 / 403), or `getSdkToken()` resolving without a valid token |
+| `KYCError` | `KYC_ERROR` | API returned a non-auth error |
+| `CameraError` | `CAMERA_ERROR` | Camera access denied or capture failed |
+| `AttestIDError` | `CONSENT_REQUIRED` / `INSECURE_CONFIG` | Missing `consentGivenAt`; `apiKey`/`accessKeyId` configured outside a trusted Node.js backend; or `apiUrl` isn't `https://` (non-loopback host) |
+| `SignatureError` | `SIGNATURE_INVALID` | `verifyAttestation()` / `verifyWebhook()`: bad signature, wrong verification/company id, altered document data, or a webhook timestamp outside the replay window |
+| `AttestIDError` | `LIVENESS_UNSUPPORTED` / `LIVENESS_RECORDING_FAILED` / `LIVENESS_ABORTED` / `LIVENESS_TIMEOUT` | Face check: the browser can't run it; it failed or was cancelled; or no decision arrived in time (default 120 s) |
+| `AttestIDError` | `JWKS_UNAVAILABLE` / `CRYPTO_UNAVAILABLE` / `INVALID_ARGUMENT` | AttestID's public keys couldn't be fetched; the runtime has no WebCrypto; `verifyWebhook()` called without `secrets` or `apiUrl` |
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build          # compile to dist/
+npm test               # run tests
+npm run test:watch     # watch mode
+npm run test:coverage  # coverage report
+npm run lint           # type-check only
+npm run dev            # build in watch mode
+```