@openliveness/web 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @openliveness/web
 
-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.
+Browser side of openliveness. Shows the QR code and waits for the phone to finish.
+
+```bash
+pnpm add @openliveness/web
+```
+
+```ts
+import { verify } from '@openliveness/web';
+
+const result = await verify({
+  relayUrl: 'localhost:3000',              // your relay host
+  assuranceRequired: 'IAL2',
+  onQRReady: (dataUrl) => (img.src = dataUrl),
+  onPhoneConnected: () => setStatus('Follow the steps on your phone'),
+});
+
+// send result.token to your backend and verify it with @openliveness/verify
+```
+
+**You run the relay yourself.** It's the Node server that brokers the
+browser↔phone handshake — see
+[openliveness/relay](https://github.com/ramuvenky/openliveness/tree/main/relay)
+for the `docker compose` setup. Point `relayUrl` at wherever you deploy it.
+
+It uses a WebSocket and falls back to polling (1s, growing 1.5x up to 5s) if the socket fails.
+If the phone reports a failed check, `verify()` rejects with `CDLRetryableError`. Call `verify()` again for a fresh session.
+
+React:
+
+```tsx
+import { LivenessWidget } from '@openliveness/web/react';
+
+<LivenessWidget relayUrl="relay.openliveness.dev" onComplete={(r) => send(r.token)} />
+```
+
+`relyingParty` defaults to the page hostname. Always re-check the token on your backend,
+the browser result alone is not proof.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { CDLOptions, CDLResult } from './types';
+export declare function verify(options: CDLOptions): Promise<CDLResult>;
+export { CDLError, CDLRetryableError } from './types';
+export type { CDLOptions, CDLResult } from './types';

package/dist/index.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CDLRetryableError = exports.CDLError = void 0;
+exports.verify = verify;
+const qr_1 = require("./qr");
+const session_1 = require("./session");
+const types_1 = require("./types");
+const websocket_1 = require("./websocket");
+async function verify(options) {
+    const session = await (0, session_1.initiate)(options);
+    options.onQRReady?.(await (0, qr_1.qrDataUrl)(session.qr_payload));
+    const limit = options.timeoutMs ?? Math.max(Date.parse(session.expires_at) - Date.now(), 0) + 60000;
+    // One controller lets the timeout and the caller's own signal stop both transports.
+    const controller = new AbortController();
+    options.signal?.addEventListener('abort', () => controller.abort());
+    const timer = setTimeout(() => controller.abort(), limit);
+    const signal = controller.signal;
+    try {
+        try {
+            return await (0, websocket_1.waitForResult)(session.ws_url, session.poll_token, session.session_id, {
+                onPhoneConnected: options.onPhoneConnected,
+                onProcessing: options.onProcessing,
+                signal,
+            });
+        }
+        catch (e) {
+            if (!(0, websocket_1.isFallback)(e) || signal.aborted)
+                throw e;
+            return await (0, session_1.pollWithBackoff)(session.session_id, session.poll_token, options.relayUrl, (state) => {
+                if (state === 'phone_connected')
+                    options.onPhoneConnected?.();
+            }, { signal });
+        }
+    }
+    catch (e) {
+        if (e instanceof types_1.CDLError && e.code === 'aborted' && !options.signal?.aborted) {
+            throw new types_1.CDLError('timeout', 'liveness check timed out');
+        }
+        throw e;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+var types_2 = require("./types");
+Object.defineProperty(exports, "CDLError", { enumerable: true, get: function () { return types_2.CDLError; } });
+Object.defineProperty(exports, "CDLRetryableError", { enumerable: true, get: function () { return types_2.CDLRetryableError; } });

package/dist/qr.d.ts

@@ -0,0 +1 @@
+export declare function qrDataUrl(qrPayload: string): Promise<string>;

package/dist/qr.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.qrDataUrl = qrDataUrl;
+const qrcode_1 = __importDefault(require("qrcode"));
+// The relay already returns qr_payload as base64 JSON. The image holds that string as is,
+// which is what the phone SDKs expect to base64 decode.
+async function qrDataUrl(qrPayload) {
+    return qrcode_1.default.toDataURL(qrPayload, { errorCorrectionLevel: 'M', margin: 2, width: 320 });
+}

package/dist/react/LivenessWidget.d.ts

@@ -0,0 +1,6 @@
+import type { CDLOptions, CDLResult } from '../types';
+export interface LivenessWidgetProps extends Omit<CDLOptions, 'onQRReady' | 'signal'> {
+    onComplete: (result: CDLResult) => void;
+    onError?: (error: Error) => void;
+}
+export declare function LivenessWidget({ onComplete, onError, ...options }: LivenessWidgetProps): import("react").JSX.Element;

package/dist/react/LivenessWidget.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LivenessWidget = LivenessWidget;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const index_1 = require("../index");
+function LivenessWidget({ onComplete, onError, ...options }) {
+    const [qr, setQr] = (0, react_1.useState)(null);
+    const [status, setStatus] = (0, react_1.useState)('Preparing...');
+    (0, react_1.useEffect)(() => {
+        const controller = new AbortController();
+        (0, index_1.verify)({
+            ...options,
+            signal: controller.signal,
+            onQRReady: (url) => {
+                setQr(url);
+                setStatus('Scan the code with your phone');
+            },
+            onPhoneConnected: () => setStatus('Phone connected, follow the steps on your phone'),
+            onProcessing: (progress) => setStatus(`Checking... ${Math.round(progress * 100)}%`),
+        })
+            .then(onComplete)
+            .catch((e) => {
+            if (controller.signal.aborted)
+                return;
+            setStatus('Something went wrong, please try again');
+            onError?.(e);
+        });
+        return () => controller.abort();
+        // the session is started once per mount
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return ((0, jsx_runtime_1.jsxs)("div", { children: [qr && (0, jsx_runtime_1.jsx)("img", { src: qr, alt: "Scan with your phone to start liveness check", width: 320, height: 320 }), (0, jsx_runtime_1.jsx)("p", { role: "status", children: status })] }));
+}

package/dist/session.d.ts

@@ -0,0 +1,16 @@
+import { CDLOptions, CDLResult, InitiateResponse } from './types';
+export declare const POLL_INITIAL_INTERVAL_MS = 1000;
+export declare const POLL_MAX_INTERVAL_MS = 5000;
+export declare const POLL_BACKOFF_MULTIPLIER = 1.5;
+type Fetch = typeof fetch;
+export declare function httpBase(relayUrl: string): string;
+export declare function isLocalHost(host: string): boolean;
+export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+export declare function initiate(options: CDLOptions, doFetch?: Fetch): Promise<InitiateResponse>;
+export declare function toResult(status: Record<string, string>, sessionId: string): CDLResult;
+export declare function pollWithBackoff(sessionId: string, pollToken: string, relayUrl: string, onUpdate: (state: string) => void, opts?: {
+    signal?: AbortSignal;
+    doFetch?: Fetch;
+    sleepFn?: (ms: number) => Promise<void>;
+}): Promise<CDLResult>;
+export {};

package/dist/session.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = exports.POLL_BACKOFF_MULTIPLIER = exports.POLL_MAX_INTERVAL_MS = exports.POLL_INITIAL_INTERVAL_MS = void 0;
+exports.httpBase = httpBase;
+exports.isLocalHost = isLocalHost;
+exports.initiate = initiate;
+exports.toResult = toResult;
+exports.pollWithBackoff = pollWithBackoff;
+const types_1 = require("./types");
+exports.POLL_INITIAL_INTERVAL_MS = 1000;
+exports.POLL_MAX_INTERVAL_MS = 5000;
+exports.POLL_BACKOFF_MULTIPLIER = 1.5;
+// "relay.openliveness.dev" becomes https, local / private addresses become http.
+// RFC 1918 covers 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 — the previous
+// regex missed the 172.16/12 range, so a developer running the relay on a
+// private corporate subnet in that range got https:// (and a TLS handshake
+// failure) instead of http://. We also recognize 0.0.0.0 (wildcard bind
+// addresses hit from the same host) and IPv6 loopback / unique-local
+// prefixes. If a caller is on a non-loopback IPv6 and wants plaintext they
+// can still pass the scheme explicitly in relayUrl.
+function httpBase(relayUrl) {
+    const withScheme = /^https?:\/\//i.test(relayUrl)
+        ? relayUrl
+        : `${isLocalHost(relayUrl) ? 'http' : 'https'}://${relayUrl}`;
+    return withScheme.replace(/\/+$/, '');
+}
+// Exported so tests can pin the host-classification contract directly.
+function isLocalHost(host) {
+    // Strip :port and any trailing path for the match. For bracketed IPv6
+    // ([::1]:3000) the bracketed form is kept so the ipv6 branch sees it.
+    const bare = host.replace(/\/.*$/, '').replace(/:(\d+)$/, '');
+    if (/^localhost$/i.test(bare))
+        return true;
+    if (bare === '0.0.0.0')
+        return true;
+    if (/^127\./.test(bare))
+        return true;
+    if (/^10\./.test(bare))
+        return true;
+    if (/^192\.168\./.test(bare))
+        return true;
+    // RFC 1918 172.16.0.0/12 — second octet 16..31. The previous heuristic
+    // missed this entirely.
+    if (/^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(bare))
+        return true;
+    // IPv6: ::1 (loopback), fc00::/7 (unique local), fe80::/10 (link local).
+    // Accept with or without brackets. Match the leading hex chunk only; a
+    // bogus host like "fcx..." falls through to https.
+    const ipv6 = bare.replace(/^\[|\]$/g, '').toLowerCase();
+    if (ipv6 === '::1')
+        return true;
+    if (/^(fc|fd)[0-9a-f]{2}:/.test(ipv6))
+        return true;
+    if (/^fe[89ab][0-9a-f]:/.test(ipv6))
+        return true;
+    return false;
+}
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(t);
+        reject(new types_1.CDLError('aborted'));
+    });
+});
+exports.sleep = sleep;
+async function initiate(options, doFetch = fetch) {
+    const relyingParty = options.relyingParty ?? (typeof location !== 'undefined' ? location.hostname : undefined);
+    if (!relyingParty)
+        throw new types_1.CDLError('ERR_SCHEMA_INVALID', 'relyingParty is required outside a browser');
+    const res = await doFetch(`${httpBase(options.relayUrl)}/cdl/session/initiate`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            relying_party: relyingParty,
+            assurance_required: options.assuranceRequired ?? 'IAL2',
+            webhook_url: options.webhookUrl,
+        }),
+        signal: options.signal,
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok)
+        throw new types_1.CDLError(body.error_code ?? 'ERR_INTERNAL', body.message);
+    return body;
+}
+function toResult(status, sessionId) {
+    return {
+        decision: status.liveness_decision,
+        assuranceLevel: status.assurance_level,
+        token: status.attestation_token,
+        sessionId,
+    };
+}
+// Fallback for networks that block WebSockets.
+async function pollWithBackoff(sessionId, pollToken, relayUrl, onUpdate, opts = {}) {
+    const doFetch = opts.doFetch ?? fetch;
+    const wait = opts.sleepFn ?? ((ms) => (0, exports.sleep)(ms, opts.signal));
+    let interval = exports.POLL_INITIAL_INTERVAL_MS;
+    for (;;) {
+        await wait(interval);
+        interval = Math.min(interval * exports.POLL_BACKOFF_MULTIPLIER, exports.POLL_MAX_INTERVAL_MS);
+        const res = await doFetch(`${httpBase(relayUrl)}/cdl/session/${sessionId}/status`, {
+            headers: { Authorization: `Bearer ${pollToken}` },
+            signal: opts.signal,
+        });
+        const status = await res.json();
+        if (!res.ok)
+            throw new types_1.CDLError(status.error_code ?? 'ERR_INTERNAL', status.message);
+        onUpdate(status.state);
+        if (status.state === 'complete')
+            return toResult(status, sessionId);
+        if (status.state === 'failed')
+            throw new types_1.CDLRetryableError('liveness_check_failed');
+        if (status.state === 'expired')
+            throw new types_1.CDLError('session_expired');
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+export interface CDLOptions {
+    /** Relay host or url, e.g. "relay.openliveness.dev" or "http://localhost:3000". */
+    relayUrl: string;
+    /** Who the token is issued for. Defaults to the current page hostname. */
+    relyingParty?: string;
+    assuranceRequired?: 'IAL2' | 'IAL1' | 'any';
+    /** Optional url the relay calls when the session finishes. */
+    webhookUrl?: string;
+    onQRReady?: (qrDataUrl: string) => void;
+    onPhoneConnected?: () => void;
+    onProcessing?: (progress: number, layer: string) => void;
+    /** Overall limit for the whole flow. Defaults to the session lifetime plus a minute. */
+    timeoutMs?: number;
+    /** Stop waiting and reject. */
+    signal?: AbortSignal;
+}
+export interface CDLResult {
+    decision: 'pass' | 'fail' | 'inconclusive';
+    assuranceLevel: 'IAL2' | 'IAL1' | 'software_only';
+    token: string;
+    sessionId: string;
+}
+export declare class CDLError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+/** The session failed but the user can start over by calling verify() again. */
+export declare class CDLRetryableError extends CDLError {
+    constructor(reason: string);
+}
+export interface InitiateResponse {
+    session_id: string;
+    challenge_id: string;
+    challenge_sequence: string[];
+    qr_payload: string;
+    poll_token: string;
+    expires_at: string;
+    ws_url: string;
+}

package/dist/types.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CDLRetryableError = exports.CDLError = void 0;
+class CDLError extends Error {
+    constructor(code, message) {
+        super(message ?? code);
+        this.name = 'CDLError';
+        this.code = code;
+    }
+}
+exports.CDLError = CDLError;
+/** The session failed but the user can start over by calling verify() again. */
+class CDLRetryableError extends CDLError {
+    constructor(reason) {
+        super(reason);
+        this.name = 'CDLRetryableError';
+    }
+}
+exports.CDLRetryableError = CDLRetryableError;

package/dist/websocket.d.ts

@@ -0,0 +1,6 @@
+import { CDLOptions, CDLResult } from './types';
+export interface WsFallback extends Error {
+    fallback: true;
+}
+export declare const isFallback: (e: unknown) => e is WsFallback;
+export declare function waitForResult(wsUrl: string, pollToken: string, sessionId: string, options: Pick<CDLOptions, 'onPhoneConnected' | 'onProcessing' | 'signal'>): Promise<CDLResult>;

package/dist/websocket.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFallback = void 0;
+exports.waitForResult = waitForResult;
+const types_1 = require("./types");
+const fallbackError = (msg) => Object.assign(new Error(msg), { fallback: true });
+const isFallback = (e) => !!e?.fallback;
+exports.isFallback = isFallback;
+// Resolves with the result. Rejects with a WsFallback if the socket itself fails,
+// so the caller can switch to polling instead of giving up.
+function waitForResult(wsUrl, pollToken, sessionId, options) {
+    return new Promise((resolve, reject) => {
+        if (typeof WebSocket === 'undefined')
+            return reject(fallbackError('no WebSocket'));
+        // The pollToken used to ride on the URL as ?token=, which lands it in
+        // LB / CDN / Fastify access logs. We now open the WS unauthenticated
+        // and send {type:"auth",token} as the first frame — the server closes
+        // the socket after 5s if the frame doesn't arrive.
+        const ws = new WebSocket(wsUrl);
+        ws.onopen = () => {
+            try {
+                ws.send(JSON.stringify({ type: 'auth', token: pollToken }));
+            }
+            catch {
+                // onerror / onclose will fire next tick
+            }
+        };
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            ws.close();
+            fn();
+        };
+        options.signal?.addEventListener('abort', () => finish(() => reject(new types_1.CDLError('aborted'))));
+        ws.onerror = () => finish(() => reject(fallbackError('socket error')));
+        ws.onclose = () => finish(() => reject(fallbackError('socket closed')));
+        ws.onmessage = (ev) => {
+            let msg;
+            try {
+                msg = JSON.parse(String(ev.data));
+            }
+            catch {
+                return;
+            }
+            switch (msg.type) {
+                case 'phone_connected':
+                    options.onPhoneConnected?.();
+                    break;
+                case 'processing_update':
+                    options.onProcessing?.(msg.progress, msg.current_layer);
+                    break;
+                case 'session_complete':
+                    finish(() => resolve({
+                        decision: msg.liveness_decision,
+                        assuranceLevel: msg.assurance_level,
+                        token: msg.attestation_token,
+                        sessionId,
+                    }));
+                    break;
+                case 'session_failed':
+                    finish(() => reject(msg.retry_allowed
+                        ? new types_1.CDLRetryableError(msg.reason)
+                        : new types_1.CDLError(msg.reason ?? 'session_failed')));
+                    break;
+                case 'session_expired':
+                    finish(() => reject(new types_1.CDLError('session_expired', msg.reason)));
+                    break;
+                case 'error':
+                    finish(() => reject(new types_1.CDLError(msg.error_code, msg.message)));
+                    break;
+            }
+        };
+    });
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@openliveness/web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Browser SDK for openliveness: QR display and session tracking",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/LivenessWidget.d.ts",
+      "default": "./dist/react/LivenessWidget.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.lint.json"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/qrcode": "^1.5.0",
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.4.0"
+  }
+}