@touchque/web 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The
+format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] — 2026-08-27
+
+Initial release.
+
+### Added
+- `createTouchQueWeb({ baseUrl, paths?, credentials?, headers?, fetch? })` —
+  a browser client that runs WebAuthn ceremonies and posts the JSON to the
+  partner's own relay backend (never TouchQue directly).
+- `passkeys.register()`, `passkeys.authenticate({ email })`,
+  `passkeys.approveLogin({ requestId })`, `passkeys.list()`,
+  `passkeys.remove(id)`.
+- `authenticate()` classifies the flow-control outcomes (`ok` /
+  `requiresStepUp` / `pending2fa`) and returns the relay's untouched body as
+  `raw`.
+- Typed errors: `PasskeyDismissedError`, `PasskeyNotRegisteredError`,
+  `PasskeyDisabledError`, `TouchQueWebAPIError`, `TouchQueWebError`.
+- `isPasskeySupported()` / `isPlatformAuthenticatorAvailable()`.
+- Behavioral biometrics widget: `tq.behavioral.attach(...)` /
+  `attachBehavioral(...)` (container-scoped mouse / click / keystroke-timing
+  telemetry). Also shipped as a standalone `<script>` build
+  (`dist/touchque-behavioral.global.js`, `window.TouchQueBehavioral`),
+  superseding the private `@touchque/behavioral-widget` package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TouchQue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# @touchque/web
+
+Browser SDK for [TouchQue Authenticator](https://touchque.com) — passkey
+sign-in / registration and behavioral telemetry.
+
+It runs the WebAuthn ceremonies in the browser and posts the collected JSON
+to **your own backend**, which relays it to TouchQue with its API key. The
+browser never holds the API key and never calls TouchQue's `/webauthn/*`
+endpoints directly.
+
+```bash
+npm install @touchque/web
+```
+
+## The relay pattern
+
+`@touchque/web` talks only to your backend (`baseUrl`). Your backend forwards
+each call to the TouchQue Authenticator API using the server SDK
+[`@touchque/node`](https://www.npmjs.com/package/@touchque/node) (or a signed
+HTTP call). You expose these routes — the paths are configurable, these are
+the defaults:
+
+| SDK method | Default browser path (`baseUrl` + …) | Relays to (`@touchque/node`) |
+|---|---|---|
+| `passkeys.register()` step 1 | `POST /passkey/register/options` | `tq.webauthn.registerOptions({ externalUsername, discoverable: true })` |
+| `passkeys.register()` step 2 | `POST /passkey/register/verify` | `tq.webauthn.registerVerify({ externalUsername, response, label })` |
+| `passkeys.authenticate()` step 1 | `POST /passkey/authenticate/options` | `tq.webauthn.primaryOptions({ externalUsername: body.email })` |
+| `passkeys.authenticate()` step 2 | `POST /passkey/authenticate/verify` | `tq.webauthn.primaryVerify({ attemptId, response })` |
+| `passkeys.approveLogin()` step 1 | `POST /passkey/login/options` | `tq.webauthn.authenticateOptions({ requestId })` |
+| `passkeys.approveLogin()` step 2 | `POST /passkey/login/verify` | `tq.webauthn.authenticateVerify({ requestId, response })` |
+| `passkeys.list()` | `GET /passkey/credentials` | `tq.webauthn.listCredentials({ externalUsername })` |
+| `passkeys.remove(id)` | `DELETE /passkey/credentials/:id` | `tq.webauthn.deleteCredential(id)` |
+
+Your backend is responsible for authenticating the browser (a session cookie,
+a bearer token, …) and for deriving `externalUsername` from that session — the
+SDK never sends it for `register` / `list` / `remove`.
+
+### Minimal Express relay
+
+```js
+const express = require('express');
+const { TouchQue } = require('@touchque/node');
+
+const tq = new TouchQue({ apiKey: process.env.TQ_API_KEY, apiSecret: process.env.TQ_API_SECRET });
+const app = express();
+app.use(express.json());
+
+// your own auth middleware sets req.user
+app.post('/passkey/authenticate/options', async (req, res) => {
+  try {
+    res.json(await tq.webauthn.primaryOptions({ externalUsername: req.body.email }));
+  } catch (e) {
+    res.status(e.status || 502).json({ error: e.data?.error || 'failed' });
+  }
+});
+app.post('/passkey/authenticate/verify', async (req, res) => {
+  const r = await tq.webauthn.primaryVerify({ attemptId: req.body.attemptId, response: req.body.response });
+  if (r.success) {
+    // issue your session here, then:
+    res.json({ status: 'success', redirect_url: '/dashboard' });
+  } else if (r.requiresStepUp) {
+    res.json({ requiresStepUp: true });
+  } else {
+    res.status(401).json({ error: 'verification_failed' });
+  }
+});
+
+app.post('/passkey/register/options', requireLogin, async (req, res) => {
+  res.json(await tq.webauthn.registerOptions({ externalUsername: req.user.email, discoverable: true }));
+});
+app.post('/passkey/register/verify', requireLogin, async (req, res) => {
+  res.json(await tq.webauthn.registerVerify({
+    externalUsername: req.user.email, response: req.body.response, label: req.body.label,
+  }));
+});
+app.get('/passkey/credentials', requireLogin, async (req, res) => {
+  res.json(await tq.webauthn.listCredentials({ externalUsername: req.user.email }));
+});
+app.delete('/passkey/credentials/:id', requireLogin, async (req, res) => {
+  res.json(await tq.webauthn.deleteCredential(req.params.id));
+});
+```
+
+## Browser usage
+
+```ts
+import { createTouchQueWeb, PasskeyNotRegisteredError } from '@touchque/web';
+
+const tq = createTouchQueWeb({
+  baseUrl: 'https://api.example.com',
+  // send cookies if your relay authenticates the browser with a session cookie
+  credentials: 'include',
+});
+```
+
+### Passwordless sign-in
+
+```ts
+try {
+  const result = await tq.passkeys.authenticate({
+    email,
+    context: { client_id, redirect_uri }, // merged into both relay calls
+  });
+
+  if (result.ok) {
+    // signed in — result.raw is your relay's untouched response
+    window.location.href = result.raw.redirect_url as string;
+  } else if (result.requiresStepUp) {
+    startPushOrNumberMatchFlow();
+  } else if (result.pending2fa) {
+    continuePending2faFlow(result.raw);
+  }
+} catch (err) {
+  if (err instanceof PasskeyNotRegisteredError) {
+    showPasswordForm(); // this account has no passkey
+  }
+  // ... see the error table below
+}
+```
+
+### Register a passkey (signed-in user)
+
+```ts
+await tq.passkeys.register({ label: 'MacBook Touch ID' });
+const passkeys = await tq.passkeys.list();
+await tq.passkeys.remove(passkeys[0].id);
+```
+
+### Approve a pending login with a passkey (second factor)
+
+```ts
+await tq.passkeys.approveLogin({ requestId });
+```
+
+### Feature detection
+
+```ts
+import { isPasskeySupported, isPlatformAuthenticatorAvailable } from '@touchque/web';
+
+if (!isPasskeySupported()) hidePasskeyButton();
+if (await isPlatformAuthenticatorAvailable()) preferPlatformUx();
+```
+
+## Behavioral biometrics widget
+
+This is the one call that goes **directly** from the browser to TouchQue,
+gated by a per-request `telemetryToken` your backend mints server-side
+(`POST /login/request` with `TenantPolicy.behavioralBiometricsEnabled`).
+
+```ts
+const widget = tq.behavioral.attach('#tq-2fa-box', {
+  telemetryToken: SERVER.telemetryToken,
+  requestId: SERVER.requestId,
+  apiBaseUrl: 'https://api-authenticator.touchque.com',
+});
+
+// call periodically and/or right before the challenge resolves
+await widget.submit();
+// on unmount
+widget.stop();
+```
+
+Or, without a bundler, via `<script>`:
+
+```html
+<script src="https://unpkg.com/@touchque/web/dist/touchque-behavioral.global.js"></script>
+<script>
+  const widget = TouchQueBehavioral.attach('#tq-2fa-box', { telemetryToken, requestId, apiBaseUrl });
+</script>
+```
+
+The widget only observes the container element (mouse movement, click count,
+inter-keystroke timing) — never `window`/`document`, and never a key or
+character. A failed telemetry POST is swallowed and never surfaces on your
+2FA flow.
+
+## Errors
+
+| Class | When | Typical handling |
+|---|---|---|
+| `PasskeyDismissedError` | User closed the system prompt (`NotAllowedError` / `AbortError`) | Let them retry or use a password |
+| `PasskeyNotRegisteredError` | Relay returned 404 / `no_passkey_registered` | Fall back to the password form |
+| `PasskeyDisabledError` | Relay returned 403 / `passwordless_login_disabled` | Fall back to the password form |
+| `TouchQueWebAPIError` | Any other non-2xx from the relay (`.status`, `.body`) | Show a generic error |
+| `TouchQueWebError` | Base class / an unexpected ceremony failure | Show a generic error |
+
+`requiresStepUp` and `pending2fa` are **not** errors — they come back as
+fields on the `authenticate()` result.
+
+## License
+MIT

package/dist/index.d.mts

@@ -0,0 +1,228 @@
+/**
+ * The relay endpoint paths on the *partner's own backend*. The browser SDK
+ * never talks to TouchQue directly for passkey ceremonies — the partner
+ * backend holds the API key and relays to TouchQue.
+ *
+ * Every path is appended to `baseUrl`. Override any subset; the rest keep
+ * their defaults.
+ */
+interface TouchQuePaths {
+    /** POST — returns `PublicKeyCredentialCreationOptionsJSON` (at the top level). */
+    registerOptions: string;
+    /** POST — body `{ response, ...extra }`; returns `{ verified, credentialId }`. */
+    registerVerify: string;
+    /** POST — body `{ email, ...context }`; returns `{ attemptId, options }`. */
+    authenticateOptions: string;
+    /** POST — body `{ attemptId, response, ...context }`; returns the relay's passthrough. */
+    authenticateVerify: string;
+    /** POST — body `{ requestId }`; returns `PublicKeyCredentialRequestOptionsJSON`. */
+    approveOptions: string;
+    /** POST — body `{ requestId, response }`; returns `{ success }`. */
+    approveVerify: string;
+    /** GET — returns `{ credentials: PasskeySummary[] }`. */
+    list: string;
+    /** DELETE `${remove}/${id}` — returns `{ deleted: true }`. */
+    remove: string;
+}
+interface TouchQueWebConfig {
+    /** Base URL of the partner's own relay backend, e.g. `https://api.example.com`. */
+    baseUrl: string;
+    /** Override any subset of the relay paths. */
+    paths?: Partial<TouchQuePaths>;
+    /**
+     * Whether the SDK's relay requests send credentials (cookies). Use
+     * `'include'` when the relay authenticates the browser with a cookie
+     * session. Default: `'same-origin'`.
+     */
+    credentials?: RequestCredentials;
+    /** Extra headers to attach to every relay request (e.g. a CSRF token). */
+    headers?: Record<string, string>;
+    /** Injectable fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+interface PasskeySummary {
+    id: string;
+    credentialId: string;
+    deviceType: string | null;
+    backedUp: boolean;
+    label: string | null;
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+interface RegisterResult {
+    verified: boolean;
+    credentialId: string;
+    [key: string]: unknown;
+}
+/**
+ * Result of `passkeys.authenticate()`. The SDK does not interpret a
+ * successful passwordless login for you — `raw` is whatever the relay
+ * returned (a redirect URL, a session, etc.). The SDK only classifies the
+ * three flow-control outcomes.
+ */
+interface AuthenticateResult {
+    /** `true` when the assertion verified and no step-up is required. */
+    ok: boolean;
+    /**
+     * `true` when risk/policy demands a second factor. The caller should start
+     * the normal push / number-match flow instead of trusting the assertion.
+     */
+    requiresStepUp: boolean;
+    /** `true` when the relay wants the caller to continue a pending 2FA flow. */
+    pending2fa: boolean;
+    /** The relay's untouched response body. */
+    raw: Record<string, unknown>;
+}
+interface ApproveResult {
+    success: boolean;
+    [key: string]: unknown;
+}
+
+/**
+ * Thin fetch wrapper for the partner relay backend. Joins `baseUrl` + path,
+ * sends/parses JSON, and normalizes the relay's error responses into the
+ * SDK's error classes.
+ */
+declare class RelayHttp {
+    private readonly baseUrl;
+    private readonly credentials;
+    private readonly headers;
+    private readonly fetchImpl;
+    constructor(config: TouchQueWebConfig);
+    post<T>(path: string, body?: unknown): Promise<T>;
+    get<T>(path: string): Promise<T>;
+    del<T>(path: string): Promise<T>;
+    private request;
+}
+
+declare class Passkeys {
+    private readonly http;
+    private readonly paths;
+    constructor(http: RelayHttp, paths: TouchQuePaths);
+    /**
+     * Register a passkey for the currently signed-in user.
+     *
+     * `extra` is merged into the verify request body — use it for a device
+     * label, for example: `register({ label: 'MacBook Touch ID' })`.
+     */
+    register(extra?: Record<string, unknown>): Promise<RegisterResult>;
+    /**
+     * Passwordless-primary sign-in: authenticate a user from zero with a
+     * passkey. `context` is merged into both relay calls (pass OAuth params,
+     * a redirect URI, etc.).
+     *
+     * Inspect the result: `ok` = signed in; `requiresStepUp` = start a push /
+     * number-match flow; `pending2fa` = continue a pending 2FA flow. `raw` is
+     * the relay's untouched response.
+     */
+    authenticate(input: {
+        email: string;
+        context?: Record<string, unknown>;
+    }): Promise<AuthenticateResult>;
+    /**
+     * Approve an already-pending login request (second-factor flow) with a
+     * passkey, instead of the mobile push.
+     */
+    approveLogin(input: {
+        requestId: string;
+    }): Promise<ApproveResult>;
+    /** List the signed-in user's registered passkeys (metadata only). */
+    list(): Promise<PasskeySummary[]>;
+    /** Remove one of the signed-in user's passkeys by its record id. */
+    remove(id: string): Promise<{
+        deleted: boolean;
+    }>;
+}
+/** `true` if the current browser exposes the WebAuthn API at all. */
+declare function isPasskeySupported(): boolean;
+/** `true` if a built-in platform authenticator (Touch ID / Windows Hello / …) is usable. */
+declare function isPlatformAuthenticatorAvailable(): Promise<boolean>;
+
+interface BehavioralMetrics {
+    mouseDistance: number;
+    mouseJitter: number;
+    clicks: number;
+    keystrokes: number;
+    keystrokeSpeedAvg: number;
+}
+
+interface AttachBehavioralOptions {
+    /** Per-request token minted by the partner backend. Required. */
+    telemetryToken: string;
+    /** The pending login request id this telemetry belongs to. Required. */
+    requestId: string;
+    /** TouchQue API base URL, e.g. `https://api-authenticator.touchque.com`. */
+    apiBaseUrl: string;
+    /** Opt in to canvas/device fingerprinting (bigger privacy footprint). */
+    collectDeviceFingerprint?: boolean;
+    /** Sampling interval (ms) for the internal tracker. Default 1000. */
+    sampleIntervalMs?: number;
+    /** Injectable fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+interface BehavioralHandle {
+    /** Stop tracking and remove the container listeners. */
+    stop(): void;
+    /** Zero the accumulated metrics without detaching. */
+    reset(): void;
+    /** Send the current metrics to TouchQue. Best-effort, never throws. */
+    submit(): Promise<void>;
+}
+declare function attachBehavioral(target: string | Element, options: AttachBehavioralOptions): BehavioralHandle;
+
+/** Base class for every error thrown by this SDK. */
+declare class TouchQueWebError extends Error {
+    constructor(message: string);
+}
+/**
+ * The WebAuthn ceremony did not complete because the user dismissed the
+ * system prompt (or the browser aborted it). Maps `NotAllowedError` /
+ * `AbortError` from `navigator.credentials.*`.
+ */
+declare class PasskeyDismissedError extends TouchQueWebError {
+    constructor(message?: string);
+}
+/**
+ * The account has no passkey registered. The relay backend returned 404 (or
+ * `error: "no_passkey_registered"`). The caller should fall back to another
+ * sign-in method (e.g. password).
+ */
+declare class PasskeyNotRegisteredError extends TouchQueWebError {
+    constructor(message?: string);
+}
+/**
+ * Passwordless sign-in is not enabled for this tenant/integration. The relay
+ * backend returned 403 (or `error: "passwordless_login_disabled"`).
+ */
+declare class PasskeyDisabledError extends TouchQueWebError {
+    constructor(message?: string);
+}
+/**
+ * The relay backend returned a non-2xx response that is not one of the
+ * specific cases above. `status` is the HTTP status, `body` is the parsed
+ * response body (if any).
+ */
+declare class TouchQueWebAPIError extends TouchQueWebError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message?: string);
+}
+
+interface TouchQueWeb {
+    passkeys: Passkeys;
+    behavioral: {
+        /**
+         * Attach the behavioral biometrics widget to a container. Unlike the
+         * passkey calls, this posts directly to TouchQue (`apiBaseUrl`), gated
+         * by the per-request `telemetryToken`.
+         */
+        attach(target: string | Element, options: AttachBehavioralOptions): BehavioralHandle;
+    };
+    /** `true` if the browser exposes the WebAuthn API. */
+    isPasskeySupported(): boolean;
+    /** `true` if a built-in platform authenticator is usable. */
+    isPlatformAuthenticatorAvailable(): Promise<boolean>;
+}
+declare function createTouchQueWeb(config: TouchQueWebConfig): TouchQueWeb;
+
+export { type ApproveResult, type AttachBehavioralOptions, type AuthenticateResult, type BehavioralHandle, type BehavioralMetrics, PasskeyDisabledError, PasskeyDismissedError, PasskeyNotRegisteredError, type PasskeySummary, type RegisterResult, type TouchQuePaths, type TouchQueWeb, TouchQueWebAPIError, type TouchQueWebConfig, TouchQueWebError, attachBehavioral, createTouchQueWeb, isPasskeySupported, isPlatformAuthenticatorAvailable };