touchque-mcp-server 1.0.2

package/bundled/types.ts

@@ -0,0 +1,582 @@
+// TouchQue Node.js SDK — bundled type reference for AI assistants.
+// Concatenation of touchque-node/src/types.ts + touchque-node/src/steps.ts
+// from the SDK source. Regenerate by copying those files here whenever
+// the SDK's public API changes (see touchque-mcp-server/README.md).
+
+// src/types.ts
+// All TypeScript types and interfaces for the TouchQue Node.js SDK
+
+export interface TouchQueConfig {
+  /** Your TouchQue API key (starts with `tq_`) */
+  apiKey: string;
+  /** Your TouchQue API secret */
+  apiSecret: string;
+  /**
+   * Optional base URL override (default: https://api.touchque.com, or the
+   * TQ_API_URL environment variable). Must be `https://` unless it
+   * points at localhost — the SDK refuses plaintext `http://` to any other
+   * host so the API key / signature are never sent in the clear.
+   */
+  baseUrl?: string;
+  /** Request timeout in ms (default: 10000) */
+  timeout?: number;
+}
+
+// ─── Auth Resource ───────────────────────────────────────────────
+
+export interface GenerateSecretOptions {
+  /** The user's unique identifier in YOUR system (email, userId, etc.) */
+  externalUsername: string;
+}
+
+export interface GenerateSecretResponse {
+  /** New setup secret — show to user once (e.g. as QR code) */
+  secret: string;
+  externalUsername: string;
+  /** ISO string of when this secret expires if not used */
+  expiresAt: string;
+  ttlMs: number;
+  /**
+   * A ready-to-render `data:image/png;base64,...` QR code encoding `secret`
+   * for the TouchQue mobile app to scan. Show this directly in an `<img>`
+   * src — no client-side QR generation needed.
+   */
+  qrCodeDataUrl: string;
+  /**
+   * 10 one-time recovery codes to be shown to the user.
+   * If the user loses their device, they can use one of these codes to bypass 2FA.
+   */
+  recoveryCodes: string[];
+}
+
+export interface UnlinkSecretOptions {
+  externalUsername: string;
+}
+
+export interface UnlinkSecretResponse {
+  success: boolean;
+  externalUsername: string;
+  message: string;
+}
+
+export interface ValidateSecretOptions {
+  secret: string;
+}
+
+export interface ValidateSecretResponse {
+  valid: boolean;
+  externalUsername?: string;
+  integrationId?: string;
+  integration?: {
+    companyName: string;
+    icon: string;
+    color: string;
+  };
+  message?: string;
+  reason?: string;
+  usedAt?: string;
+  expiredAt?: string;
+}
+export interface ResetSecretOptions {
+  externalUsername: string;
+}
+
+export interface ResetSecretResponse {
+  /** New setup secret — show to user once */
+  secret: string;
+  externalUsername: string;
+  expiresAt?: string;
+  /** See GenerateSecretResponse.qrCodeDataUrl. */
+  qrCodeDataUrl?: string;
+  recoveryCodes?: string[];
+}
+
+export interface GetUserResponse {
+  externalUsername: string;
+  /** Set once the mobile app has linked (scanned) the secret. */
+  deviceId: string | null;
+  /** true once the secret has been linked to a device via /auth/secret/link. */
+  used: boolean;
+  frozen: boolean;
+  createdAt: string;
+  expireAt: string | null;
+}
+
+// ─── Offline Sign ────────────────────────────────────────────────
+
+export interface OfflineChallengeOptions {
+  /** User identifier in YOUR system */
+  externalUsername: string;
+  /** The action being approved (an Action Type slug/id from your Dashboard) */
+  type: string;
+  /**
+   * What the user is approving, shown on the phone (see LoginRequestOptions.details).
+   * REQUIRED for critical action types.
+   */
+  details?: LoginRequestDetails;
+  /** End user's IP / User-Agent: shown to the user as "where the request came from". */
+  clientIp?: string;
+  userAgent?: string;
+  /** Seconds the challenge stays valid (30–300, default 120). */
+  ttlSeconds?: number;
+  /** Set false to skip the ready-made QR image (`qrDataUrl` is then null). */
+  includeQrImage?: boolean;
+}
+
+export interface OfflineChallengeResponse {
+  challengeId: string;
+  /** QR text (`TQ2.…`, encrypted for the user's phone; nothing in it is readable) — draw it as a QR code if you don't use `qrDataUrl`. */
+  qr: string;
+  /** `data:image/png;base64,…` ready for `<img src>`; null when `includeQrImage: false`. */
+  qrDataUrl: string | null;
+  expiresAt: string;
+  expiresInSeconds: number;
+  /** True when the workspace allows the time-based code fallback (no camera). */
+  totpAvailable: boolean;
+}
+
+export interface OfflineVerifyOptions {
+  challengeId: string;
+  /** The 7 characters shown on the phone; dashes/spaces/case are ignored. */
+  code: string;
+}
+
+export interface OfflineTotpVerifyOptions {
+  externalUsername: string;
+  code: string;
+  /** The action the code is for; critical actions are refused. */
+  type?: string;
+  clientIp?: string;
+}
+
+export interface OfflineVerifyResult {
+  approved: boolean;
+  /** When not approved: invalid_code | locked | expired | used | unknown_challenge | too_many_failures | frozen | … */
+  reason?: string;
+  /** Wrong codes left before the challenge locks (only with reason `invalid_code`). */
+  attemptsLeft?: number;
+  challengeId?: string;
+  externalUsername?: string;
+  type?: string;
+}
+
+// ─── Login Resource ──────────────────────────────────────────────
+
+export type LoginType = 'LOGIN' | 'DISABLE_2FA' | string;
+
+/** Label → value pairs, or an explicit ordered list of `{ label, value }`. */
+export type LoginRequestDetails =
+  | Record<string, string | number>
+  | Array<{ label: string; value: string | number }>;
+
+export interface LoginRequestOptions {
+  /** User identifier in YOUR system */
+  externalUsername: string;
+  /**
+   * The type of action requiring 2FA confirmation.
+   * Built-in types: 'LOGIN', 'DISABLE_2FA'
+   * Custom types can be created/configured in your TouchQue Dashboard.
+   */
+  type: LoginType;
+  /** Optional reference (e.g. your internal transaction ID) */
+  referenceId?: string;
+  
+  /** The IP address of the user initiating the request. TouchQue will resolve this to a City/Country. */
+  clientIp?: string;
+  /**
+   * The User-Agent string of the user's browser/device. Shown on the approval
+   * screen as the requesting browser and device (e.g. "Chrome · macOS").
+   */
+  userAgent?: string;
+  /**
+   * Transaction context shown on the approval screen, so the user sees what
+   * they are approving — e.g. `{ Amount: '1,250.00 USD', Recipient: 'Jane Doe' }`.
+   * Keys and values are displayed as-is, in the order given.
+   *
+   * Limits (the request is rejected with a 400 otherwise — never truncated):
+   * at most 8 entries, labels up to 40 characters, values up to 120
+   * characters, strings or numbers only, no control characters.
+   *
+   * Always set this from your server-side state, never from browser input.
+   */
+  details?: LoginRequestDetails;
+  /** Require the user to authenticate with FaceID / TouchID on their device to approve this request. */
+  requireBiometric?: boolean;
+  /**
+   * Force Number Matching (anti-push-bombing).
+   * When true, the user must type a matching code shown on their screen to approve.
+   * The backend also auto-enables this if MFA fatigue is detected (2+ failed requests in 10 min).
+   */
+  requireNumberMatch?: boolean;
+}
+
+export interface LoginRequestResponse {
+  requestId: string;
+  /** Challenge code for number matching UI (if enabled for this integration) */
+  challengeCode?: string;
+  message: string;
+  expiresAt: string;
+  /**
+   * Present only when this integration has behavioral biometrics enabled
+   * (TenantPolicy.behavioralBiometricsEnabled). Pass this down to your
+   * frontend along with `requestId` to initialize the behavioral widget in
+   * `@touchque/web` (`tq.behavioral.attach(...)`), scoped to your 2FA
+   * challenge UI. Single-purpose and short-lived — do not reuse across requests.
+   */
+  telemetryToken?: string;
+  /**
+   * The workspace policy requires a phishing-resistant factor for this action:
+   * no push was sent. Approve it with a passkey in the browser
+   * (`@touchque/web` `passkeys.approveLogin({ requestId })`).
+   */
+  requiresPasskey?: boolean;
+}
+
+/** How an approved request was confirmed, and whether that is phishing-resistant. */
+export interface ApprovalAssurance {
+  /** true only for passkeys (WebAuthn): the signature is bound to your site's origin. */
+  phishingResistant: boolean;
+  /** 'passkey' | 'push' | 'recovery_code' | ... */
+  method: string | null;
+}
+
+export type LoginStatus = 'PENDING' | 'CONFIRMED' | 'REJECTED' | 'EXPIRED';
+
+export interface LoginStatusResponse {
+  status: LoginStatus;
+  /** How the request was confirmed ('DEVICE', 'WEBAUTHN', ...); null until confirmed */
+  confirmedVia?: string | null;
+  /**
+   * Device-signed proof of what was approved (only when the approving phone
+   * holds a Secure Enclave key). Check it with `verifyApprovalProof`.
+   */
+  approvalProof?: import('./approvalProof').ApprovalProof | null;
+  /** Set once CONFIRMED: rely on `assurance.phishingResistant` for high-assurance sessions. */
+  assurance?: ApprovalAssurance | null;
+  /** The request can only be approved with a passkey (phishing-resistant policy). */
+  requiresPasskey?: boolean;
+}
+
+export interface WaitForApprovalOptions {
+  requestId: string;
+  /** How long to poll in total, ms (default: 30000 = 30s) */
+  timeout?: number;
+  /** Polling interval, ms (default: 1500) */
+  pollInterval?: number;
+}
+
+export interface WaitForApprovalResult {
+  approved: boolean;
+  status: LoginStatus;
+}
+
+// ─── Webhook Resource ────────────────────────────────────────────
+
+export interface VerifyWebhookOptions {
+  /** Raw request body as string, exactly as received (before JSON.parse). */
+  rawBody: string;
+  /**
+   * The signature to check against. Pass the value of the `x-signature`
+   * header. Optional: if omitted, the SDK falls back to the `signature`
+   * field TouchQue also embeds in the JSON body.
+   */
+  signature?: string;
+  /**
+   * Reject the webhook if its `timestamp` is more than this many seconds
+   * from now (replay protection). Default 300 (5 minutes). Set to 0 to
+   * disable the freshness check.
+   */
+  toleranceSeconds?: number;
+}
+
+export interface WebhookPayload {
+  event: string;
+  requestId: string;
+  externalUsername: string;
+  status: LoginStatus;
+  timestamp: string;
+  /**
+   * On a SUCCESS webhook, the approving phone's device-signed proof of what
+   * was approved (when it holds a Secure Enclave key). Check it with
+   * `verifyApprovalProof` before releasing money or data.
+   */
+  approvalProof?: import('./approvalProof').ApprovalProof;
+  /** On SUCCESS: how it was approved and whether that was phishing-resistant. */
+  assurance?: ApprovalAssurance;
+  [key: string]: unknown;
+}
+
+// ─── Protect Wrapper ─────────────────────────────────────────────
+
+export interface ProtectOptions<TArgs extends any[]> {
+  /** The action type (e.g. 'WITHDRAW', 'LOGIN') */
+  type: string;
+  /** Function to extract the externalUsername from the wrapped function's arguments */
+  getUserIdentifier: (...args: TArgs) => string;
+  /** Optional function to extract a referenceId from the arguments */
+  getReferenceId?: (...args: TArgs) => string | undefined;
+  /**
+   * Optional function returning the end user's request context (IP address,
+   * User-Agent) and transaction details shown on the approval screen.
+   */
+  getContext?: (...args: TArgs) => Pick<LoginRequestOptions, 'clientIp' | 'userAgent' | 'details'> | undefined;
+  /** Timeout in ms */
+  timeout?: number;
+  /** Polling interval in ms */
+  pollInterval?: number;
+}
+
+// ─── Errors ──────────────────────────────────────────────────────
+
+export interface TouchQueErrorData {
+  error?: string;
+  message?: string;
+  code?: string;
+  /** Offline sign: why a code was not approved (`invalid_code`, `locked`, `expired`, `used`, …). */
+  reason?: string;
+  /** Offline sign: wrong codes left before the challenge locks. */
+  attemptsLeft?: number;
+  /** Seconds to wait before retrying (429 / 423). */
+  retryAfter?: number;
+}
+
+// ─────────────────────────────────────────────────────────────
+// From src/steps.ts — the headless step-up flow (start/check/complete)
+// ─────────────────────────────────────────────────────────────
+
+// src/steps.ts
+// The headless step-up flow shared by every integration (Express, Next.js,
+// touchqueRouter, or your own framework): start → show the step in YOUR UI →
+// check → complete exactly once.
+//
+// A "step" is plain JSON that is safe to send to the browser: what state the
+// approval is in and whatever the user has to see (the matching number, the
+// enrollment QR code, the offline QR code). It never contains API secrets.
+
+import * as crypto from 'crypto';
+import type { HttpClient } from './core/HttpClient';
+import type { Auth } from './resources/Auth';
+import type { Login } from './resources/Login';
+import type { Offline } from './resources/Offline';
+import type { ApprovalAssurance, LoginRequestDetails } from './types';
+import { TouchQueAPIError, TouchQueConfigError, TouchQueError } from './errors';
+import { detailsDigest } from './approvalProof';
+
+export type StepState =
+  | 'waiting' // push sent — show `number` (if any) and wait
+  | 'approved'
+  | 'rejected'
+  | 'expired'
+  | 'enroll' // no phone linked yet — show `enroll.qrCodeDataUrl`
+  | 'passkey_required' // policy: approve with a passkey (browser ceremony)
+  | 'offline' // offline approval started — show `offline.qrDataUrl`, ask for the code
+  | 'blocked' // refused by policy / risk / action disabled — see `reason`
+  | 'frozen' // too many rejections — see `retryAfter`
+  | 'rate_limited'; // too many requests — see `retryAfter`
+
+export interface Step {
+  state: StepState;
+  requestId?: string;
+  /** Number matching: show this on screen; the user picks it on the phone. */
+  number?: string;
+  expiresAt?: string;
+  /** Transaction details the phone shows (amount, recipient…). */
+  details?: Array<{ label: string; value: string }>;
+  enroll?: { qrCodeDataUrl: string; recoveryCodes?: string[]; expiresAt?: string };
+  offline?: { challengeId: string; qrDataUrl?: string; expiresAt?: string; totpAvailable?: boolean; attemptsLeft?: number };
+  reason?: string;
+  retryAfter?: number;
+  assurance?: ApprovalAssurance;
+}
+
+export interface StartOptions {
+  /** Your user's id in YOUR system (email, user id…). */
+  user: string;
+  /** Shown on the phone and bound to the approval. Build it from server-side state. */
+  details?: LoginRequestDetails;
+  /** Your own transaction id, bound to the approval. */
+  referenceId?: string;
+  /** End user's IP / user agent (location and device shown on the phone). */
+  ip?: string;
+  userAgent?: string;
+  /** Show an enrollment QR when the user has not linked a phone yet (default true). */
+  enroll?: boolean;
+}
+
+export interface Approval {
+  requestId: string;
+  user: string;
+  action: string;
+  /** How it was approved; `phishingResistant` is true only for passkeys. */
+  assurance: ApprovalAssurance | null;
+  confirmedVia: string | null;
+  /** Device-signed proof of what was approved (see verifyApprovalProof). */
+  approvalProof: unknown;
+}
+
+type Resources = { http: HttpClient; auth: Auth; login: Login; offline: Offline };
+
+/** Normalizes details the same way the API does: object or [{label, value}] → [{label, value}] strings. */
+export function normalizeDetails(details?: LoginRequestDetails): Array<{ label: string; value: string }> {
+  if (!details) return [];
+  const pairs = Array.isArray(details)
+    ? details.map((d) => [d.label, d.value] as const)
+    : Object.entries(details as Record<string, unknown>);
+  return pairs.map(([label, value]) => ({ label: String(label).trim(), value: String(value).trim() }));
+}
+
+const codeOf = (err: unknown): string | undefined =>
+  err instanceof TouchQueAPIError ? (err.code || (err.data as { error?: string })?.error) : undefined;
+
+/** Starts an approval for `action` — never waits. */
+export async function start(r: Resources, action: string, opts: StartOptions): Promise<Step> {
+  if (!opts?.user) throw new TouchQueConfigError('start() needs the user id (options.user)');
+  const details = normalizeDetails(opts.details);
+  try {
+    const res = await r.login.request({
+      externalUsername: opts.user,
+      type: action,
+      referenceId: opts.referenceId,
+      clientIp: opts.ip,
+      userAgent: opts.userAgent,
+      details: details.length ? details : undefined,
+    });
+    if (res.requiresPasskey) {
+      return { state: 'passkey_required', requestId: res.requestId, expiresAt: res.expiresAt, details: details.length ? details : undefined };
+    }
+    return {
+      state: 'waiting',
+      requestId: res.requestId,
+      number: res.challengeCode || undefined,
+      expiresAt: res.expiresAt,
+      details: details.length ? details : undefined,
+    };
+  } catch (err) {
+    if (!(err instanceof TouchQueAPIError)) throw err;
+    const code = codeOf(err);
+    const data = err.data as { retryAfter?: number; reason?: string; error?: string };
+    if (err.status === 404 && (code === 'device_not_linked' || /linked device/i.test(err.message))) {
+      if (opts.enroll === false) return { state: 'enroll' };
+      return enrollStep(r, opts.user);
+    }
+    if (err.status === 423) return { state: 'frozen', retryAfter: data.retryAfter };
+    if (err.status === 429) return { state: 'rate_limited', retryAfter: data.retryAfter };
+    if (err.status === 400 && (code === 'unknown_action' || /Invalid action type/i.test(err.message))) {
+      throw new TouchQueConfigError(
+        `Unknown action "${action}". Create it once with tq.actions.define('${action}') or in the Dashboard (Action Types).`,
+      );
+    }
+    if (err.status === 403) {
+      const reason = code === 'blocked' ? data.reason || 'policy'
+        : code === 'passkey_not_registered' || data.error === 'phishing_resistant_required' ? 'passkey_not_registered'
+          : code === 'action_disabled' ? 'action_disabled'
+            : code || 'blocked';
+      return { state: 'blocked', reason };
+    }
+    throw err;
+  }
+}
+
+/**
+ * First-time linking: a fresh QR for a user with no phone. Never unlinks a phone:
+ * a secret is only re-issued when the account is confirmed NOT linked.
+ */
+async function enrollStep(r: Resources, user: string): Promise<Step> {
+  try {
+    const gen = await r.auth.generateSecret({ externalUsername: user });
+    return { state: 'enroll', enroll: { qrCodeDataUrl: gen.qrCodeDataUrl, recoveryCodes: gen.recoveryCodes, expiresAt: gen.expiresAt } };
+  } catch (err) {
+    if (!(err instanceof TouchQueAPIError) || err.status !== 409) throw err;
+    const current = await r.auth.getUser({ externalUsername: user }).catch(() => null);
+    if (current && (current.used || current.deviceId)) {
+      // Linked in the meantime — the caller just starts again.
+      return { state: 'enroll', reason: 'already_linked' };
+    }
+    // A QR was issued earlier and not scanned yet: issue a new one (no device to lose).
+    const reset = await r.auth.resetSecret({ externalUsername: user });
+    return { state: 'enroll', enroll: { qrCodeDataUrl: reset.qrCodeDataUrl as string, recoveryCodes: reset.recoveryCodes, expiresAt: reset.expiresAt } };
+  }
+}
+
+/** Current state of a started approval. */
+export async function check(r: Resources, requestId: string): Promise<Step> {
+  const s = await r.login.status(requestId);
+  const map: Record<string, StepState> = { PENDING: 'waiting', CONFIRMED: 'approved', REJECTED: 'rejected', EXPIRED: 'expired' };
+  const state: StepState = s.status === 'PENDING' && s.requiresPasskey ? 'passkey_required' : map[s.status] || 'waiting';
+  return { state, requestId, ...(state === 'approved' && s.assurance ? { assurance: s.assurance } : {}) };
+}
+
+export interface CompleteExpectations {
+  user: string;
+  action: string;
+  details?: LoginRequestDetails;
+  referenceId?: string;
+}
+
+/**
+ * Uses an approved request exactly once and checks it is for THIS user, action and
+ * transaction. Throws if it was already used, not approved, or approved for something else.
+ */
+export async function complete(r: Resources, requestId: string, expect: CompleteExpectations): Promise<Approval> {
+  const res = await r.http.post<{
+    externalUsername: string; type: string; referenceId: string | null; details: Array<{ label: string; value: string }> | null;
+    confirmedVia: string | null; assurance: ApprovalAssurance | null; approvalProof: unknown;
+  }>(`/login/${encodeURIComponent(requestId)}/consume`, {});
+  const sameUser = String(res.externalUsername).toLowerCase() === String(expect.user).toLowerCase();
+  const sameDetails = detailsDigest(normalizeDetails(expect.details)) === detailsDigest(res.details || []);
+  const sameRef = (res.referenceId || null) === (expect.referenceId || null);
+  if (!sameUser || res.type !== expect.action || !sameDetails || !sameRef) {
+    throw new TouchQueError('TouchQue: this approval is for a different user, action or transaction.');
+  }
+  return {
+    requestId,
+    user: res.externalUsername,
+    action: res.type,
+    assurance: res.assurance,
+    confirmedVia: res.confirmedVia,
+    approvalProof: res.approvalProof,
+  };
+}
+
+// ─── Guard token ──────────────────────────────────────────────────────────
+// The browser echoes this back while it waits. It is signed with a key derived
+// from your API secret and binds the approval to one user, action and
+// transaction, so it cannot be replayed for another user, amount or route.
+
+export interface GuardTokenClaims {
+  u: string; // user
+  a: string; // action
+  d: string; // details digest
+  r: string | null; // referenceId
+  st: StepState;
+  rid?: string; // requestId
+  n?: string; // matching number
+  oc?: string; // offline challenge id
+  exp: number; // ms
+}
+
+const b64u = (b: Buffer) => b.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+const fromB64u = (s: string) => Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+const tokenKey = (apiSecret: string) => crypto.createHmac('sha256', apiSecret).update('touchque-guard-token-v1').digest();
+
+export function signGuardToken(apiSecret: string, claims: GuardTokenClaims): string {
+  const body = b64u(Buffer.from(JSON.stringify(claims), 'utf8'));
+  const mac = b64u(crypto.createHmac('sha256', tokenKey(apiSecret)).update(body).digest());
+  return `v1.${body}.${mac}`;
+}
+
+export function verifyGuardToken(apiSecret: string, token: unknown): GuardTokenClaims | null {
+  if (typeof token !== 'string' || token.length > 4096) return null;
+  const [v, body, mac] = token.split('.');
+  if (v !== 'v1' || !body || !mac) return null;
+  const expected = crypto.createHmac('sha256', tokenKey(apiSecret)).update(body).digest();
+  const given = fromB64u(mac);
+  if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) return null;
+  try {
+    const claims = JSON.parse(fromB64u(body).toString('utf8')) as GuardTokenClaims;
+    if (typeof claims.exp !== 'number' || claims.exp < Date.now()) return null;
+    return claims;
+  } catch {
+    return null;
+  }
+}