@touchque/node 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# 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/).
+
+## [1.3.0] — 2026-09-06
+
+### Changed
+- `webauthn.deleteCredential()` return type corrected to `{ deleted: boolean }`
+  (the API returns `deleted`, not `success`).
+- Doc: the WebAuthn resource header no longer says "there's no client-side SDK"
+  — the browser side is `@touchque/web`.
+
+### Note
+- Version bumped to **1.3.0** to align the whole server SDK line (node / go /
+  php / python) now that Go/PHP/Python have caught up to full parity — WebAuthn
+  resource, `getUser`, and the `telemetryToken` login-response field.
+
+## [1.2.0] — 2026-08-27
+
+First release published to npm as **`@touchque/node`**.
+
+### Changed
+- **Reverted** the 1.1.0 rename: the package name is `@touchque/node` again
+  (never actually shipped to npm under either name). Every consumer, the
+  public docs, and the MCP server already reference `@touchque/node`; the
+  cross-language rename in 1.1.0 was applied to the manifests but never to a
+  single consumer. Product scoping for other TouchQue products (e.g.
+  Compliance) is expressed by the package *name* under the shared
+  `@touchque` scope, not by a separate scope.
+- `repository.url` corrected to `https://github.com/Touchque/touchque-sdks`.
+
+### Added
+- `tq.webauthn.primaryOptions()` / `tq.webauthn.primaryVerify()` — the
+  passwordless-primary passkey login flow (no password, no prior
+  `login.request`), gated on `TenantPolicy.passwordlessLoginEnabled`.
+  Returns `{ requiresStepUp }` when risk/policy demands a second factor.
+- `discoverable?: boolean` on `tq.webauthn.registerOptions()` — registers a
+  resident credential with forced user verification and a stable WebAuthn
+  user handle (the shape a passwordless-primary login authenticates against).
+- `tq.auth.getUser({ externalUsername })` — fetch a user's link status
+  (`{ used, deviceId }`), previously added but unreleased.
+- `telemetryToken` on `LoginRequestResponse` — issued when the integration
+  has `behavioralBiometricsEnabled`, for the `@touchque/behavioral-widget`
+  browser embed, previously added but unreleased.
+- `WebAuthn` resource test suite (`src/resources/WebAuthn.test.ts`); tests
+  for `Auth.getUser()` and the Express middleware.
+
+### Packaging
+- `package.json` is now publish-shaped: `files: ["dist"]` (no `src`/config in
+  the tarball), a conditional `exports` map (ESM/CJS + per-format types),
+  `engines.node >= 18`, `sideEffects: false`, `publishConfig.access public`,
+  a `prepublishOnly` build+test guard, and `express` declared as an optional
+  peer dependency (it is type-only in the SDK).
+
+## [1.1.0] — 2026-08-22
+
+### Changed
+- **Breaking:** package renamed from `@touchque/node` to
+  `@touchque-authenticator/node` to reflect that this SDK is scoped to the
+  TouchQue Authenticator (2FA/MFA) product specifically, not TouchQue as a
+  whole (TouchQue's other products, e.g. KVKK Compliance, have their own
+  separately-named SDKs).
+
+### Fixed
+- README no longer documents `tq.actionTypes.*` / `tq.users.*` — these
+  resources never existed in the SDK; the corresponding unused
+  `ActionType`/`ActionTypeOptions` types and the unused `UnlinkSecretOptions`/
+  `UnlinkSecretResponse` import in `Auth.ts` were also removed.
+
+### Added
+- First real automated test suite (`vitest`, 36 tests covering `HttpClient`
+  signing/error-handling, `Auth`, `Login`, `Webhook`, and error classes).
+  The previous `package.json` `test` script pointed at a nonexistent
+  `test.js` and never ran anything.
+- `LICENSE` (MIT) file, matching the license already declared in
+  `package.json`.
+
+## [1.0.1] — prior to this changelog
+
+Initial public functionality: `Auth` (generateSecret/resetSecret/
+validateSecret), `Login` (request/status/waitForApproval/verify/
+approveWithRecoveryCode), `Webhook` (verify/isValid), Express middleware,
+full TypeScript types.

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,255 @@
+# @touchque/node
+
+The official Node.js SDK for [TouchQue Authenticator](https://touchque.com) — add biometric 2FA to any application in minutes.
+
+[![npm version](https://img.shields.io/npm/v/@touchque/node.svg)](https://www.npmjs.com/package/@touchque/node)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+npm install @touchque/node
+```
+
+## Quick Start
+
+```typescript
+import { TouchQue } from '@touchque/node';
+
+const tq = new TouchQue({
+  apiKey: 'tq_auth_your_key',     // From TouchQue Dashboard
+  apiSecret: 'your_api_secret',   // From TouchQue Dashboard
+});
+
+// Protect any action with biometric 2FA — one line!
+await tq.login.verify({
+  externalUsername: 'user@company.com',
+  type: 'LOGIN',
+});
+// If we reach here, the user approved on their phone ✅
+```
+
+## Features
+
+- 🔐 **Biometric 2FA** — Face ID, Touch ID, fingerprint verification
+- ⚡ **One-line integration** — `tq.login.verify()` does everything
+- 🛡️ **HMAC-SHA256 signed requests** — every API call is cryptographically authenticated
+- 📱 **Real-time push notifications** — instant approval requests to user devices
+- 🔗 **Express.js middleware** — protect routes with a single middleware function
+- 🪝 **Webhook verification** — validate incoming webhook signatures
+- 📝 **Full TypeScript support** — complete type definitions included
+
+## Core Concepts
+
+### 1. Generate a Secret (User Onboarding)
+
+When a user enables 2FA, generate a secret and show them a QR code:
+
+```typescript
+const { secret, expiresAt } = await tq.auth.generateSecret({
+  externalUsername: 'user@company.com',
+});
+
+// Display `secret` as a QR code in your UI
+// User scans it with the TouchQue mobile app
+// Secret expires in 60 seconds if not scanned
+```
+
+### 2. Verify an Action (The Core Flow)
+
+Protect any sensitive action with biometric verification:
+
+```typescript
+import { TouchQueRejectedError, TouchQueTimeoutError } from '@touchque/node';
+
+try {
+  await tq.login.verify({
+    externalUsername: 'user@company.com',
+    type: 'WITHDRAW',           // Your custom action type
+    referenceId: 'txn_abc123',  // Optional: your internal reference
+    timeout: 30000,             // Optional: 30s timeout (default)
+  });
+
+  // ✅ User approved — execute the action
+  executeWithdrawal();
+
+} catch (err) {
+  if (err instanceof TouchQueRejectedError) {
+    // ❌ User rejected on their device
+  } else if (err instanceof TouchQueTimeoutError) {
+    // ⏰ User didn't respond in time
+  }
+}
+```
+
+### 3. Express.js Middleware
+
+Protect any Express route with a single middleware:
+
+```typescript
+import { TouchQue, requireTouchQue } from '@touchque/node';
+
+const tq = new TouchQue({
+  apiKey: 'tq_auth_xxx',
+  apiSecret: 'your_secret',
+});
+
+// Protect a route — that's it!
+app.post('/api/transfer',
+  authenticate,                              // Your auth middleware
+  requireTouchQue(tq, 'BANK_TRANSFER'),      // TouchQue 2FA
+  (req, res) => {
+    // Only reaches here if user approved ✅
+    res.json({ success: true });
+  }
+);
+```
+
+### 4. Webhook Verification
+
+Verify that incoming webhooks are genuinely from TouchQue:
+
+```typescript
+app.post('/webhooks/touchque',
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    try {
+      const event = tq.webhook.verify({
+        rawBody: req.body.toString(),
+        signature: req.headers['x-tq-signature'] as string,
+      });
+
+      switch (event.event) {
+        case 'login.confirmed':
+          handleApproval(event);
+          break;
+        case 'login.rejected':
+          handleRejection(event);
+          break;
+      }
+
+      res.sendStatus(200);
+    } catch (err) {
+      // Invalid signature — not from TouchQue!
+      res.sendStatus(403);
+    }
+  }
+);
+```
+
+## API Reference
+
+### `new TouchQue(config)`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `apiKey` | `string` | ✅ | Your API key (starts with `tq_auth_`) |
+| `apiSecret` | `string` | ✅ | Your API secret |
+| `baseUrl` | `string` | — | API base URL (default: `https://api-authenticator.touchque.com`) |
+| `timeout` | `number` | — | Request timeout in ms (default: `10000`) |
+
+### `tq.auth`
+
+| Method | Description |
+|--------|-------------|
+| `.generateSecret({ externalUsername })` | Generate a setup secret for user onboarding |
+| `.resetSecret({ externalUsername })` | Reset (regenerate) a user's secret |
+| `.validateSecret({ secret })` | Validate a setup secret code |
+| `.getUser({ externalUsername })` | Link status (`used`, `deviceId`, …) without sending a push; throws 404 if unknown |
+
+### `tq.login`
+
+| Method | Description |
+|--------|-------------|
+| `.request({ externalUsername, type, referenceId? })` | Send a 2FA request to the user's device |
+| `.status(requestId)` | Check the status of a login request |
+| `.waitForApproval({ requestId, timeout?, pollInterval? })` | Poll until approved/rejected/expired |
+| `.verify({ externalUsername, type, ...options })` | **Recommended**: Request + wait in one call |
+| `.approveWithRecoveryCode({ requestId, code })` | Approve a pending request using a backup recovery code |
+
+The `request()` / `verify()` response carries `telemetryToken` when the
+integration has behavioral biometrics enabled — pass it plus `requestId` to your
+frontend for the [`@touchque/web`](https://www.npmjs.com/package/@touchque/web)
+behavioral widget (`tq.behavioral.attach(...)`). There is no widget in this
+server SDK.
+
+### `tq.webauthn` — passkey / FIDO2
+
+Phishing-resistant login, alongside the push flow. Server-to-server: the passkey
+ceremony runs in the browser (`@touchque/web`, or `navigator.credentials.*`);
+your backend relays the JSON through these.
+
+| Method | Description |
+|--------|-------------|
+| `.registerOptions({ externalUsername, discoverable? })` / `.registerVerify({ externalUsername, response, label? })` | Register a passkey |
+| `.authenticateOptions({ requestId })` / `.authenticateVerify({ requestId, response })` | Approve a pending `login.request` with a passkey |
+| `.primaryOptions({ externalUsername })` / `.primaryVerify({ attemptId, response })` | Passwordless-primary login |
+| `.listCredentials({ externalUsername })` / `.deleteCredential(id)` | Credential management |
+
+### `tq.webhook`
+
+| Method | Description |
+|--------|-------------|
+| `.verify({ rawBody, signature?, toleranceSeconds? })` | Verify webhook signature (throws on invalid) |
+| `.isValid({ rawBody, signature? })` | Check webhook signature (returns boolean) |
+
+### Express Middleware
+
+```typescript
+requireTouchQue(tqClient, actionType, options?)
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `timeout` | `number` | Approval timeout in ms (default: `30000`) |
+| `getUserId` | `(req) => string` | Custom function to extract user ID from request |
+| `getReferenceId` | `(req) => string` | Custom function to extract reference ID |
+
+## Error Handling
+
+All SDK errors extend `TouchQueError`:
+
+| Error Class | When Thrown |
+|-------------|-----------|
+| `TouchQueAPIError` | API returned a non-2xx response |
+| `TouchQueRejectedError` | User rejected the 2FA request |
+| `TouchQueTimeoutError` | User didn't respond in time |
+| `TouchQueWebhookSignatureError` | Webhook signature verification failed |
+| `TouchQueConfigError` | Invalid SDK configuration |
+
+```typescript
+import {
+  TouchQueAPIError,
+  TouchQueRejectedError,
+  TouchQueTimeoutError,
+} from '@touchque/node';
+
+try {
+  await tq.login.verify({ ... });
+} catch (err) {
+  if (err instanceof TouchQueRejectedError) {
+    console.log('Request ID:', err.requestId);
+  }
+  if (err instanceof TouchQueAPIError) {
+    console.log('HTTP Status:', err.status);
+    console.log('Error Data:', err.data);
+  }
+}
+```
+
+## Security
+
+- All requests are signed with **HMAC-SHA256** using your API secret
+- Signatures include method, path, timestamp, nonce, and body hash
+- Webhook verification uses **timing-safe comparison** to prevent timing attacks
+- Your API secret never leaves your server
+
+## Requirements
+
+- Node.js 18+
+- An active [TouchQue Dashboard](https://authenticator.touchque.com) account
+
+## License
+
+MIT © [TouchQue](https://touchque.com)