@touchque/web 0.1.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,393 @@
+'use strict';
+
+var browser = require('@simplewebauthn/browser');
+
+// src/errors.ts
+var TouchQueWebError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TouchQueWebError";
+  }
+};
+var PasskeyDismissedError = class extends TouchQueWebError {
+  constructor(message = "The passkey prompt was dismissed before it completed.") {
+    super(message);
+    this.name = "PasskeyDismissedError";
+  }
+};
+var PasskeyNotRegisteredError = class extends TouchQueWebError {
+  constructor(message = "No passkey is registered for this account.") {
+    super(message);
+    this.name = "PasskeyNotRegisteredError";
+  }
+};
+var PasskeyDisabledError = class extends TouchQueWebError {
+  constructor(message = "Passwordless sign-in is not enabled for this account.") {
+    super(message);
+    this.name = "PasskeyDisabledError";
+  }
+};
+var TouchQueWebAPIError = class extends TouchQueWebError {
+  status;
+  body;
+  constructor(status, body, message) {
+    super(message || `Relay request failed with HTTP ${status}`);
+    this.name = "TouchQueWebAPIError";
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/http.ts
+var RelayHttp = class {
+  baseUrl;
+  credentials;
+  headers;
+  fetchImpl;
+  constructor(config) {
+    if (!config.baseUrl) {
+      throw new Error("createTouchQueWeb: `baseUrl` is required.");
+    }
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.credentials = config.credentials ?? "same-origin";
+    this.headers = config.headers ?? {};
+    const f = config.fetch ?? (typeof fetch !== "undefined" ? fetch : void 0);
+    if (!f) {
+      throw new Error("createTouchQueWeb: no `fetch` available \u2014 pass `fetch` in the config.");
+    }
+    this.fetchImpl = f.bind(globalThis);
+  }
+  post(path, body) {
+    return this.request("POST", path, body);
+  }
+  get(path) {
+    return this.request("GET", path);
+  }
+  del(path) {
+    return this.request("DELETE", path);
+  }
+  async request(method, path, body) {
+    const res = await this.fetchImpl(this.baseUrl + path, {
+      method,
+      credentials: this.credentials,
+      headers: {
+        Accept: "application/json",
+        ...body !== void 0 ? { "Content-Type": "application/json" } : {},
+        ...this.headers
+      },
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    const text = await res.text();
+    let parsed = void 0;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = text;
+      }
+    }
+    if (!res.ok) {
+      const errCode = parsed && typeof parsed === "object" && "error" in parsed ? String(parsed.error) : void 0;
+      if (errCode === "no_passkey_registered" || res.status === 404 && !errCode) {
+        throw new PasskeyNotRegisteredError();
+      }
+      if (errCode === "passwordless_login_disabled" || res.status === 403 && !errCode) {
+        throw new PasskeyDisabledError();
+      }
+      const message = parsed && typeof parsed === "object" && "message" in parsed ? String(parsed.message) : errCode;
+      throw new TouchQueWebAPIError(res.status, parsed, message);
+    }
+    return parsed;
+  }
+};
+function isDismissal(err) {
+  const name = err?.name;
+  return name === "NotAllowedError" || name === "AbortError";
+}
+async function ceremony(run) {
+  try {
+    return await run();
+  } catch (err) {
+    if (isDismissal(err)) throw new PasskeyDismissedError();
+    if (err instanceof TouchQueWebError) throw err;
+    throw new TouchQueWebError(
+      `WebAuthn ceremony failed: ${err?.message ?? String(err)}`
+    );
+  }
+}
+function unwrapOptions(body) {
+  if (body && typeof body === "object" && "options" in body) {
+    const b = body;
+    return { attemptId: b.attemptId, options: b.options };
+  }
+  return { options: body ?? {} };
+}
+var Passkeys = class {
+  constructor(http, paths) {
+    this.http = http;
+    this.paths = paths;
+  }
+  http;
+  paths;
+  /**
+   * 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' })`.
+   */
+  async register(extra = {}) {
+    const optionsBody = await this.http.post(this.paths.registerOptions, {});
+    const { options } = unwrapOptions(optionsBody);
+    const response = await ceremony(() => browser.startRegistration({ optionsJSON: options }));
+    return this.http.post(this.paths.registerVerify, { response, ...extra });
+  }
+  /**
+   * 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.
+   */
+  async authenticate(input) {
+    const context = input.context ?? {};
+    const optionsBody = await this.http.post(this.paths.authenticateOptions, {
+      email: input.email,
+      ...context
+    });
+    const { attemptId, options } = unwrapOptions(optionsBody);
+    const response = await ceremony(() => browser.startAuthentication({ optionsJSON: options }));
+    const raw = await this.http.post(this.paths.authenticateVerify, {
+      ...attemptId !== void 0 ? { attemptId } : {},
+      response,
+      ...context
+    });
+    const requiresStepUp = raw.requiresStepUp === true;
+    const pending2fa = raw.status === "pending_2fa";
+    const ok = !requiresStepUp && !pending2fa && (raw.success === true || raw.status === "success");
+    return { ok, requiresStepUp, pending2fa, raw };
+  }
+  /**
+   * Approve an already-pending login request (second-factor flow) with a
+   * passkey, instead of the mobile push.
+   */
+  async approveLogin(input) {
+    const optionsBody = await this.http.post(this.paths.approveOptions, {
+      requestId: input.requestId
+    });
+    const { options } = unwrapOptions(optionsBody);
+    const response = await ceremony(() => browser.startAuthentication({ optionsJSON: options }));
+    return this.http.post(this.paths.approveVerify, {
+      requestId: input.requestId,
+      response
+    });
+  }
+  /** List the signed-in user's registered passkeys (metadata only). */
+  async list() {
+    const body = await this.http.get(this.paths.list);
+    return body.credentials ?? [];
+  }
+  /** Remove one of the signed-in user's passkeys by its record id. */
+  async remove(id) {
+    return this.http.del(
+      `${this.paths.remove}/${encodeURIComponent(id)}`
+    );
+  }
+};
+function isPasskeySupported() {
+  return browser.browserSupportsWebAuthn();
+}
+function isPlatformAuthenticatorAvailable() {
+  return browser.platformAuthenticatorIsAvailable();
+}
+
+// src/behavioral/tracker.ts
+function createBehavioralTracker(containerEl, opts = {}) {
+  const sampleIntervalMs = opts.sampleIntervalMs || 1e3;
+  const keystrokeMaxGapMs = opts.keystrokeMaxGapMs || 2e3;
+  let running = false;
+  let distance = 0;
+  let jitterCount = 0;
+  let clickCount = 0;
+  let lastPos = { x: 0, y: 0 };
+  let lastKeyTime = null;
+  let keyIntervals = [];
+  let intervalHandle = null;
+  function handleMouseMove(e) {
+    const { clientX, clientY } = e;
+    if (lastPos.x !== 0 && lastPos.y !== 0) {
+      const dx = clientX - lastPos.x;
+      const dy = clientY - lastPos.y;
+      distance += Math.sqrt(dx * dx + dy * dy);
+      if (dx !== 0 && dy !== 0 && Math.abs(dx / dy) > 0.1) {
+        jitterCount += 1;
+      }
+    }
+    lastPos = { x: clientX, y: clientY };
+  }
+  function handleClick() {
+    clickCount += 1;
+  }
+  function handleKeyDown() {
+    const now = Date.now();
+    if (lastKeyTime !== null) {
+      const diff = now - lastKeyTime;
+      if (diff < keystrokeMaxGapMs) {
+        keyIntervals.push(diff);
+      }
+    }
+    lastKeyTime = now;
+  }
+  function getMetrics() {
+    const avgSpeed = keyIntervals.length ? keyIntervals.reduce((a, b) => a + b, 0) / keyIntervals.length : 0;
+    return {
+      mouseDistance: Math.floor(distance),
+      mouseJitter: jitterCount,
+      clicks: clickCount,
+      keystrokes: keyIntervals.length,
+      keystrokeSpeedAvg: Math.floor(avgSpeed)
+    };
+  }
+  function start() {
+    if (running || !containerEl) return;
+    running = true;
+    containerEl.addEventListener("mousemove", handleMouseMove);
+    containerEl.addEventListener("click", handleClick);
+    containerEl.addEventListener("keydown", handleKeyDown);
+    intervalHandle = setInterval(() => {
+      if (typeof opts.onSample === "function") opts.onSample(getMetrics());
+    }, sampleIntervalMs);
+  }
+  function stop() {
+    if (!running) return;
+    running = false;
+    containerEl.removeEventListener("mousemove", handleMouseMove);
+    containerEl.removeEventListener("click", handleClick);
+    containerEl.removeEventListener("keydown", handleKeyDown);
+    if (intervalHandle) clearInterval(intervalHandle);
+    intervalHandle = null;
+  }
+  function reset() {
+    distance = 0;
+    jitterCount = 0;
+    clickCount = 0;
+    keyIntervals = [];
+    lastPos = { x: 0, y: 0 };
+    lastKeyTime = null;
+  }
+  return { start, stop, reset, getMetrics };
+}
+
+// src/behavioral/fingerprint.ts
+function generateDeviceFingerprint() {
+  try {
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return "no-canvas";
+    ctx.textBaseline = "top";
+    ctx.font = "14px 'Arial'";
+    ctx.textBaseline = "alphabetic";
+    ctx.fillStyle = "#f60";
+    ctx.fillRect(125, 1, 62, 20);
+    ctx.fillStyle = "#069";
+    ctx.fillText("TouchQue Behavioral Widget Fingerprint", 2, 15);
+    ctx.fillStyle = "rgba(102, 204, 0, 0.7)";
+    ctx.fillText("TouchQue Behavioral Widget Fingerprint", 4, 17);
+    const canvasData = canvas.toDataURL();
+    const screenData = `${window.screen.width}x${window.screen.height}-${window.screen.colorDepth}`;
+    const browserData = `${navigator.userAgent}-${navigator.language}-${navigator.platform}-${navigator.hardwareConcurrency || 1}`;
+    const raw = canvasData + screenData + browserData;
+    let hash = 5381;
+    for (let i = 0; i < raw.length; i++) {
+      hash = (hash << 5) + hash + raw.charCodeAt(i);
+    }
+    return `tq_fp_${Math.abs(hash).toString(16)}`;
+  } catch {
+    return "fp_error";
+  }
+}
+
+// src/behavioral/index.ts
+function resolveContainer(target) {
+  if (typeof target === "string") return document.querySelector(target);
+  return target || null;
+}
+function attachBehavioral(target, options) {
+  const containerEl = resolveContainer(target);
+  if (!containerEl) {
+    throw new Error("attachBehavioral: container not found");
+  }
+  if (!options.telemetryToken || !options.requestId) {
+    throw new Error("attachBehavioral: telemetryToken and requestId are required");
+  }
+  const apiBaseUrl = (options.apiBaseUrl || "").replace(/\/+$/, "");
+  const fetchImpl = options.fetch ?? (typeof fetch !== "undefined" ? fetch : void 0);
+  if (!fetchImpl) {
+    throw new Error("attachBehavioral: no `fetch` available \u2014 pass `fetch` in the options.");
+  }
+  const doFetch = fetchImpl.bind(globalThis);
+  const tracker = createBehavioralTracker(containerEl, {
+    sampleIntervalMs: options.sampleIntervalMs
+  });
+  let fingerprint = null;
+  if (options.collectDeviceFingerprint === true) {
+    fingerprint = generateDeviceFingerprint();
+  }
+  tracker.start();
+  async function submit() {
+    const metrics = tracker.getMetrics();
+    const body = fingerprint ? { ...metrics, deviceFingerprint: fingerprint } : metrics;
+    try {
+      await doFetch(`${apiBaseUrl}/login/${encodeURIComponent(options.requestId)}/telemetry`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${options.telemetryToken}`
+        },
+        body: JSON.stringify(body)
+      });
+    } catch {
+    }
+  }
+  return {
+    stop: () => tracker.stop(),
+    reset: () => tracker.reset(),
+    submit
+  };
+}
+
+// src/index.ts
+var DEFAULT_PATHS = {
+  registerOptions: "/passkey/register/options",
+  registerVerify: "/passkey/register/verify",
+  authenticateOptions: "/passkey/authenticate/options",
+  authenticateVerify: "/passkey/authenticate/verify",
+  approveOptions: "/passkey/login/options",
+  approveVerify: "/passkey/login/verify",
+  list: "/passkey/credentials",
+  remove: "/passkey/credentials"
+};
+function createTouchQueWeb(config) {
+  const http = new RelayHttp(config);
+  const paths = { ...DEFAULT_PATHS, ...config.paths ?? {} };
+  const passkeys = new Passkeys(http, paths);
+  return {
+    passkeys,
+    behavioral: {
+      attach: (target, options) => attachBehavioral(target, { fetch: config.fetch, ...options })
+    },
+    isPasskeySupported,
+    isPlatformAuthenticatorAvailable
+  };
+}
+
+exports.PasskeyDisabledError = PasskeyDisabledError;
+exports.PasskeyDismissedError = PasskeyDismissedError;
+exports.PasskeyNotRegisteredError = PasskeyNotRegisteredError;
+exports.TouchQueWebAPIError = TouchQueWebAPIError;
+exports.TouchQueWebError = TouchQueWebError;
+exports.attachBehavioral = attachBehavioral;
+exports.createTouchQueWeb = createTouchQueWeb;
+exports.isPasskeySupported = isPasskeySupported;
+exports.isPlatformAuthenticatorAvailable = isPlatformAuthenticatorAvailable;