@castleio/sdk 2.3.3 → 3.1.0

package/README.md

@@ -1,60 +1,381 @@
 # Castle SDK for Node
 
-**[Castle](https://castle.io) analyzes user behavior in web and mobile apps to stop fraud before it happens.**
+[![Test](https://github.com/castle/castle-node/actions/workflows/test.yml/badge.svg)](https://github.com/castle/castle-node/actions/workflows/test.yml)
+[![Lint](https://github.com/castle/castle-node/actions/workflows/lint.yml/badge.svg)](https://github.com/castle/castle-node/actions/workflows/lint.yml)
+[![npm version](https://img.shields.io/npm/v/@castleio/sdk.svg)](https://www.npmjs.com/package/@castleio/sdk)
 
-## Usage
+The official Node.js SDK for [Castle](https://castle.io). Castle analyzes user behavior in web and mobile apps to stop fraud before it happens.
 
-See the [documentation](https://docs.castle.io) for how to use this SDK with the Castle APIs
+This package is a thin, dependency-light wrapper around the [Castle HTTP API](https://reference.castle.io). It exposes:
 
-## Installation
+- **Risk assessment** — `POST /v1/risk`, `POST /v1/filter`
+- **Event logging** — `POST /v1/log` (fire-and-forget, no verdict)
+- **Lists & List Items** — full CRUD + search + count + batch
+- **Privacy / GDPR** — `POST` and `DELETE /v1/privacy/users` (Article 15 & 17)
+- **Events** (enterprise) — search, group, and schema
+- **Webhook signature verification** — validate `X-Castle-Signature`
+- **Secure mode** — sign user IDs sent from the browser
+
+A full list of supported events and the JSON shape of every payload is documented at <https://reference.castle.io>.
+
+## Requirements
 
-Add the `@castleio/sdk` package to your `package.json`.
+- Node.js `>= 20` (the SDK uses the built-in global `fetch` / `AbortSignal`)
+- A [Castle](https://dashboard.castle.io) API secret
+
+The package ships both ESM and CommonJS builds, so both `import` and `require` work out of the box.
+
+## Installation
 
-### yarn
+```bash
+npm install --save @castleio/sdk
+```
 
 ```bash
 yarn add @castleio/sdk
 ```
 
-### npm
+## Quick start
 
-```bash
-npm install --save @castleio/sdk
+```js
+import { Castle, ContextPrepareService } from '@castleio/sdk';
+
+const castle = new Castle({ apiSecret: process.env.CASTLE_API_SECRET });
+
+const context = ContextPrepareService.call(
+  req,
+  undefined,
+  castle.configuration
+);
+
+const verdict = await castle.risk({
+  type: '$login',
+  status: '$succeeded',
+  request_token: req.body.castle_request_token,
+  user: { id: '12345', email: 'user@example.com' },
+  context,
+});
+
+switch (verdict.policy?.action) {
+  case 'deny':
+    // block the user
+    break;
+  case 'challenge':
+    // send 2FA / additional verification
+    break;
+  default:
+  // allow
+}
+```
+
+With CommonJS:
+
+```js
+const { Castle, ContextPrepareService } = require('@castleio/sdk');
 ```
 
+`ContextPrepareService.call(request, options, configuration)` extracts the IP and headers that Castle needs from a Node `request` object. See [Advanced configuration](#advanced-configuration) for how header allow/deny lists and proxy chains are resolved.
+
 ## Configuration
 
-### Framework configuration
+The library is configured per `Castle` instance:
+
+```js
+import { Castle, FailoverStrategy } from '@castleio/sdk';
+
+const castle = new Castle({
+  apiSecret: process.env.CASTLE_API_SECRET,
+
+  // Automatic verdict from `risk`/`filter` when Castle is unreachable or
+  // times out. One of FailoverStrategy.allow (default), .deny, .challenge.
+  failoverStrategy: FailoverStrategy.allow,
+
+  // Request timeout in milliseconds before the failover strategy kicks in.
+  timeout: 1500,
+
+  // Logs Castle API requests and responses; must respond to `info`.
+  logger: console,
+});
+```
+
+### Config options
+
+| Option              | Type                   | Default                    | Description                                                                                                     |
+| ------------------- | ---------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `apiSecret`         | `string`               |                            | API secret from the [dashboard](https://dashboard.castle.io/settings/general).                                  |
+| `timeout`           | `number`               | `1500`                     | Time in ms before returning the failover strategy.                                                              |
+| `failoverStrategy`  | `FailoverStrategy`     | `FailoverStrategy.allow`   | Automatic `risk` response on timeout: `allow`, `deny`, or `challenge`.                                          |
+| `logger`            | `object`               |                            | Logs Castle API requests/responses; must respond to `info`.                                                     |
+| `doNotTrack`        | `boolean`              | `false`                    | When `true`, suppresses all requests and triggers failover on `risk`. Useful in development and testing.        |
+| `allowlisted`       | `string[]`             | `[]`                       | Strict header allow-list (see [Header allow/deny lists](#header-allowdeny-lists)).                              |
+| `denylisted`        | `string[]`             | `[]`                       | Headers to always scrub, in addition to the always-blocked `Cookie` / `Authorization`.                          |
+| `ipHeaders`         | `string[]`             | `[]`                       | Custom headers to read the client IP from (see [Client IP detection](#client-ip-detection)).                    |
+| `trustedProxies`    | `(string \| RegExp)[]` | `[]`                       | Known proxy IPs (strings or regexes). Pick this **or** `trustedProxyDepth`, never both.                         |
+| `trustedProxyDepth` | `number`               | `0`                        | Number of known trusted proxies in the chain. Pick this **or** `trustedProxies`, never both.                    |
+| `trustProxyChain`   | `boolean`              | `false`                    | Trust the entire `X-Forwarded-For` chain. **Warning:** promiscuous — a malicious proxy can spoof the client IP. |
+| `baseUrl`           | `string`               | `https://api.castle.io/v1` | Base Castle API URL.                                                                                            |
+
+### Multi-environment / multi-tenant
+
+Each `Castle` instance carries its own configuration, so multiple environments or tenants are just multiple instances:
+
+```js
+const castleTenantA = new Castle({
+  apiSecret: process.env.CASTLE_API_SECRET_TENANT_A,
+});
+const castleTenantB = new Castle({
+  apiSecret: process.env.CASTLE_API_SECRET_TENANT_B,
+});
+```
+
+## Usage
+
+All endpoints are async methods on a `Castle` instance.
+
+### Risk
+
+Evaluates high-risk events (logins, registrations, password resets, transactions). Returns a verdict (`policy.action`) plus risk scores and signals.
+
+```js
+await castle.risk({
+  type: '$login',
+  status: '$succeeded',
+  request_token: req.body.castle_request_token,
+  user: { id: '12345', email: 'user@example.com' },
+  context,
+});
+```
+
+### Filter
+
+Blocks bots and bad traffic early in the chain (typically registration). Same response shape as Risk.
+
+```js
+await castle.filter({
+  type: '$registration',
+  status: '$attempted',
+  request_token: req.body.castle_request_token,
+  params: { email: 'user@example.com' },
+  context,
+});
+```
+
+### Log
+
+Fire-and-forget event logging; no verdict is returned. Useful for events that should be visible in the dashboard but don't need a real-time decision.
+
+```js
+await castle.log({
+  type: '$profile_update',
+  status: '$succeeded',
+  user: { id: '12345' },
+  context,
+});
+```
+
+### Lists & List Items
+
+Lists let you organize users, IPs, transactions, or any custom property and use them in policies as allow/deny lists:
+
+```js
+const list = await castle.createList({
+  name: 'Trusted IPs',
+  color: 'green',
+  primary_field: 'ip.address',
+});
+
+await castle.createListItem({
+  list_id: list.id,
+  primary_value: '1.2.3.4',
+  author: { type: '$analyst_email', identifier: 'analyst@example.com' },
+});
+
+await castle.searchListItems({
+  list_id: list.id,
+  filters: [{ field: 'primary_value', op: '$eq', value: '1.2.3.4' }],
+});
+```
+
+Available methods: `createList`, `fetchAllLists`, `fetchList`, `updateList`, `deleteList`, `searchLists`, `createListItem`, `batchUpdateListItems`, `fetchListItem`, `searchListItems`, `countListItems`, `updateListItem`, `archiveListItem`, `unarchiveListItem`.
+
+### Privacy (GDPR)
+
+Supports GDPR Articles 15 (right of access) and 17 (right to be forgotten) via `/v1/privacy/users`. Both take an `identifier` and `identifier_type` (`$id` or `$email`):
+
+```js
+await castle.requestUserData({
+  identifier: 'rhea@example.org',
+  identifier_type: '$email',
+});
+
+await castle.deleteUserData({
+  identifier: 'user_42',
+  identifier_type: '$id',
+});
+```
+
+### Events (enterprise)
+
+Query, group, and inspect the schema of stored events. Use `queryEvents`,
+`groupEvents`, and `eventsSchema`:
+
+```js
+await castle.queryEvents({
+  filters: [
+    /* ... */
+  ],
+});
+await castle.groupEvents({
+  filters: [],
+  group_by: { fields: [] },
+  columns: [],
+});
+await castle.eventsSchema();
+```
+
+`searchEvents` and `getEventsSchema` are also available as aliases of
+`queryEvents` and `eventsSchema`.
+
+### Webhook signature verification
+
+Castle signs every webhook with an `X-Castle-Signature` header. Verify it against the **raw** request body before trusting the payload — `verifyWebhookSignature` throws a `WebhookVerificationError` on mismatch:
+
+```js
+import express from 'express';
+import { WebhookVerificationError } from '@castleio/sdk';
+
+const app = express();
+
+// The signature is computed over the raw body, so capture it as a Buffer.
+app.post(
+  '/castle/webhooks',
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    try {
+      castle.verifyWebhookSignature(req.body, req.get('x-castle-signature'));
+    } catch (err) {
+      if (err instanceof WebhookVerificationError) {
+        return res.sendStatus(400);
+      }
+      throw err;
+    }
+
+    const event = JSON.parse(req.body.toString());
+    // signature is valid; proceed
+    res.sendStatus(200);
+  }
+);
+```
+
+### Secure mode
+
+Secure mode signs the user id server-side so it can't be tampered with in the browser. Pass the signature to the client-side `castle.js` SDK:
+
+```js
+const signature = castle.secureModeSignature('user_123');
+```
+
+The signature is a hex HMAC-SHA256 of the user id keyed with your API secret.
 
-Load and configure the library with your Castle API secret in an initializer or similar.
+## Advanced configuration
+
+The defaults are good for most deployments. The options below only matter if you have a non-trivial proxy chain or strict header policies.
+
+### Header allow/deny lists
+
+By default the SDK sends every HTTP header except `Cookie` and `Authorization`. Castle uses these headers to fingerprint the request, so the broader the better.
 
 ```js
-import { Castle } from '@castleio/sdk';
+import { DEFAULT_ALLOWLIST } from '@castleio/sdk';
+
+const castle = new Castle({
+  apiSecret: process.env.CASTLE_API_SECRET,
 
-const castle = new Castle({ apiSecret: 'YOUR SECRET HERE' });
+  // Always-blocked headers (in addition to Cookie/Authorization).
+  denylisted: ['X-Internal-Header'],
+
+  // Strict allow-list mode. Headers outside the list are sent with scrubbed
+  // values, except User-Agent which is always preserved. If you must use an
+  // allow list, we recommend starting from the curated default.
+  allowlisted: DEFAULT_ALLOWLIST,
+});
 ```
 
-When using setup without the modules:
+Header names are case-insensitive and accept both `_` and `-` as separators. A leading `HTTP_` prefix is stripped automatically.
+
+### Client IP detection
+
+Castle needs the original client IP, not the IP of your proxy or load balancer. The SDK reads `X-Forwarded-For` and `Remote-Addr` by default; pick **one** of the strategies below depending on your infrastructure:
 
 ```js
-const { Castle } = require('@castleio/sdk');
+const castle = new Castle({
+  apiSecret: process.env.CASTLE_API_SECRET,
 
-const castle = new Castle({ apiSecret: 'YOUR SECRET HERE' });
+  // 1. Custom header (e.g. Cloudflare's Cf-Connecting-Ip).
+  ipHeaders: ['Cf-Connecting-Ip'],
+
+  // 2. Static, known proxy IPs.
+  trustedProxies: ['10.0.0.1'],
+
+  // 3. Ephemeral proxies but known chain depth.
+  trustedProxyDepth: 2,
+
+  // 4. Last resort: trust the entire X-Forwarded-For chain.
+  // Warning: vulnerable to header spoofing if a malicious proxy is in path.
+  trustProxyChain: false,
+});
 ```
 
-#### Config options
+Pick **either** `trustedProxies` **or** `trustedProxyDepth`, never both. Private/loopback ranges in the exported `TRUSTED_PROXIES` constant are always considered trusted.
+
+## Errors
+
+All HTTP/API exceptions inherit from `APIError`. `ConfigurationError` (setup problems) and `WebhookVerificationError` (webhook signature mismatch) extend `Error` directly. The most useful ones:
+
+| Class                      | Raised when                                             |
+| -------------------------- | ------------------------------------------------------- |
+| `ConfigurationError`       | The SDK is misconfigured (missing API secret, bad URL). |
+| `BadRequestError`          | `400` response.                                         |
+| `UnauthorizedError`        | `401` — bad API secret.                                 |
+| `ForbiddenError`           | `403` response.                                         |
+| `NotFoundError`            | `404` response.                                         |
+| `InvalidParametersError`   | `422` response with validation details.                 |
+| `InvalidRequestTokenError` | `422` — the `request_token` is missing or invalid.      |
+| `RateLimitError`           | `429` — back off and retry.                             |
+| `InternalServerError`      | `5xx` response from Castle.                             |
+| `WebhookVerificationError` | A webhook signature did not match.                      |
+
+The full list lives in [`src/errors.ts`](src/errors.ts).
+
+## Upgrading to 3.0.0
+
+`3.0.0` is a modernization release. The public API (the `Castle` class and its
+methods) is unchanged — most projects can upgrade without code changes.
+
+What changed:
+
+- **Legacy endpoints removed.** `authenticate`, `track`, and the device
+  endpoints (`getDevice`, `getDevicesForUser`, `approveDevice`, `reportDevice`)
+  are gone — use `risk`, `filter`, and `log` instead. The matching payload types
+  (`Payload`, `DevicePayload`, `UserDevicePayload`, `AuthenticateResult`) were
+  removed too.
+  - If you previously used `reportDevice` / `approveDevice`, manage device
+    approvals and reports with the **Lists API** instead (e.g.
+    `createListItem` / `archiveListItem`). See
+    [Reporting devices using Lists](https://docs.castle.io/docs/reporting-devices-using-lists).
+- **Node.js `>= 20` is now required.** The SDK uses the runtime's built-in
+  `fetch` and `AbortSignal` instead of `node-fetch` / `abort-controller`, which
+  are no longer dependencies.
+- **Dual ESM + CommonJS build.** The package now exposes a proper `exports` map
+  with separate `import` and `require` entry points and type definitions. Deep
+  imports into `dist/` were never supported and remain unsupported; import from
+  the package root (`@castleio/sdk`).
+- The `lodash.*` micro-dependencies were removed in favor of native JavaScript;
+  this is internal and does not affect behavior.
+
+If you previously relied on a custom `overrideFetch`, it still works — pass any
+`fetch`-compatible implementation.
+
+## License
 
-| Config option     | Type               | Default                    | Explanation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ----------------- | ------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| apiSecret         | `string`           |                            | API key which can be found in the Castle dashboard https://dashboard.castle.io/settings/general                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| timeout           | `number`           | 1500                       | Time before returning the failover strategy.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| allowlisted       | `string[]`         | []                         | by default, the SDK sends all HTTP headers, except for Cookie and Authorization. <br/><br/> If you decide to use a allowlist, the SDK will:<br/>- always send the User-Agent header<br/>- send scrubbed values of non-allowlisted headers<br/>- send proper values of allowlisted headers.<br/><br/>We highly suggest using denylist instead of allowlist, so that Castle can use as many data points as possible to secure your users. If you want to use the allowlist, this is the minimal amount of headers we recommend: DEFAULT_ALLOWLIST                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| denylisted        | `string[]`         | []                         | Denylisted headers take precedence over allowlisted elements. We always denylist Cookie and Authentication headers. If you use any other headers that might contain sensitive information, you should denylist them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| failoverStrategy  | `FailoverStrategy` | `FailoverStrategy.allow`   | If the request to our service would for some reason time out, this is where you select the automatic response from `authenticate`. Options are `FailoverStrategy.allow`, `FailoverStrategy.deny`, `FailoverStrategy.challenge`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| logger            | `any`              |                            | Logs Castle API requests and responses, has to respond to `info` method.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| doNotTrack        | `boolean`          | False                      | setting it to true turns off all requests and triggers automatic failover on `authenticate`. Used for development and testing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ipHeaders         | `string[]`         | []                         | Castle needs the original IP of the client, not the IP of your proxy or load balancer. The SDK will only trust the proxy chain as defined in the configuration.We try to fetch the client IP based on X-Forwarded-For or Remote-Addr headers in that order, but sometimes the client IP may be stored in a different header or order. The SDK can be configured to look for the client IP address in headers that you specify.<br/>Sometimes, Cloud providers do not use consistent IP addresses to proxy requests. In this case, the client IP is usually preserved in a custom header. <br/>Example: Cloudflare preserves the client request in the 'Cf-Connecting-Ip' header.                                                                                                                                                                                                                                                                                                                                                  |
-| trustedProxies    | `string[]`         | []                         | If the specified header or X-Forwarded-For default contains a proxy chain with public IP addresses, then you must choose only one of the following (but not both): <br/>1. The trusted_proxies value must match the known proxy IPs. This option is preferable if the IP is static. <br/>2. The trusted_proxy_depth value must be set to the number of known trusted proxies in the chain (see below).This option is preferable if the IPs are ephemeral, but the depth is consistent. <br/>Additionally to make X-Forwarded-For and other headers work better discovering client ip address,and not the address of a reverse proxy server, you can define trusted proxies which will help to fetch proper ip from those headers. <br/>In order to extract the client IP of the X-Forwarded-For header and not the address of a reverse proxy server, you must define all trusted public proxies you can achieve this by listing all the proxies ip defined by string or regular expressions in the trusted_proxies setting <br/> |
-| trustedProxyDepth | `number`           | 0                          | ...or by providing number of trusted proxies used in the chain, (note that you must pick one approach over the other. either trustProxyChain orr trustedProxies)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| trustProxyChain   | `boolean`          | False                      | If there is no possibility to define options above and there is no other header that holds the client IP, then you may set this option to True to trust all of the proxy IPs in X-Forwarded-For , _Warning_: this mode is highly promiscuous and could lead to wrongly trusting a spoofed IP if the request passes through a malicious proxy                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| baseUrl           | `string`           | `https://api.castle.io/v1` | base Castle API url                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+Available as open source under the terms of the [MIT License](LICENSE).