@faable/auth-sdk 2.7.108 → 2.8.0

package/README.md

@@ -20,12 +20,12 @@ Programmatically manage FaableAuth users, teams, connections and clients through
 > the whole tenant. A user's own bearer token or the browser's session cookie
 > only grant what that user can do, and those are fine client-side.
 
-| Strategy                | Credential                        | Grants                                                            | Where                                   |
-| ----------------------- | --------------------------------- | ----------------------------------------------------------------- | --------------------------------------- |
+| Strategy                | Credential                        | Grants                                                             | Where                                   |
+| ----------------------- | --------------------------------- | ------------------------------------------------------------------ | --------------------------------------- |
 | `authClientCredentials` | `client_id` + **`client_secret`** | The management scopes of the client (full catalog unless narrowed) | **Server only**                         |
-| `authApikey`            | **API key** (`fak_…`)             | The management scopes of the key                                  | **Server only**                         |
-| `authBearer`            | A token the caller already holds  | Whatever that token's scopes and subject allow                    | Anywhere the token itself may live      |
-| `authCookie`            | The browser's session cookie      | The signed-in user's own session (`/me`, MFA, passkeys…)          | Browser, same-origin with the auth host |
+| `authApikey`            | **API key** (`fak_…`)             | The management scopes of the key                                   | **Server only**                         |
+| `authBearer`            | A token the caller already holds  | Whatever that token's scopes and subject allow                     | Anywhere the token itself may live      |
+| `authCookie`            | The browser's session cookie      | The signed-in user's own session (`/me`, MFA, passkeys…)           | Browser, same-origin with the auth host |
 | _(none)_                | —                                 | Public endpoints only (login, passwordless start, device flow…)    | Anywhere                                |
 
 ---
@@ -136,7 +136,9 @@ discovery). Those are not on the generated client; call them through the
 fetcher:
 
 ```ts
-const api = FaableAuthApi.create({ domain: "https://<your-account>.auth.faable.link" });
+const api = FaableAuthApi.create({
+  domain: "https://<your-account>.auth.faable.link",
+});
 await api.fetcher.post("/passwordless/start", { email, client_id });
 ```
 
@@ -148,7 +150,10 @@ itself instead — the value you pass replaces the default, on data calls and on
 the token request alike:
 
 ```ts
-FaableAuthApi.create({ domain, clientInfo: { client: "my-app/1.4.0", name: "my-app" } });
+FaableAuthApi.create({
+  domain,
+  clientInfo: { client: "my-app/1.4.0", name: "my-app" },
+});
 ```
 
 ### Per-call options
@@ -164,14 +169,14 @@ await api.fetcher.get(`/user/${id}`, { timeout: 800, retry: false });
 
 ### Constructor options
 
-| Option         | Type                                  | Description                                                                                                                  |
-| -------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `domain`       | string                                | **Required.** The account host to target, e.g. `https://<your-account>.auth.faable.link`. No default. The protocol is optional — `<your-account>.auth.faable.link` and `https://<your-account>.auth.faable.link` are equivalent. |
-| `authStrategy` | strategy builder                      | Auth strategy (`authClientCredentials` \| `authApikey` \| `authBearer` \| `authCookie`), re-exported from `@faable/auth-sdk`. Defaults to `authClientCredentials` when `auth` is given; anonymous when neither is. |
-| `auth`         | config                                | Config for the chosen strategy. Its shape is inferred from `authStrategy` (e.g. `{ client_id, client_secret }`).            |
-| `debug`        | boolean                               | Enables verbose logging in the underlying fetcher.                                                                          |
-| `headers`      | `{ project_id?; account_id? }`        | Advanced / testing escape hatch — target `domain` but have the server resolve a different project/account (sent as `x-faable-project` / `x-faableauth-account`). `team_id` is a deprecated alias of `project_id`: a `team_<hex>` value is sent as `project_<hex>`, and passing both with different ids throws. The SDK no longer sends `x-faable-team`. |
-| `clientInfo`   | `{ client?; name?; instance? }`       | How this integration identifies itself (`x-faable-client` / `x-faable-instance`). `client` replaces the SDK's own `auth-sdk/<version>+<sha>`. |
+| Option         | Type                            | Description                                                                                                                                                                                                                                                                                                                                             |
+| -------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `domain`       | string                          | **Required.** The account host to target, e.g. `https://<your-account>.auth.faable.link`. No default. The protocol is optional — `<your-account>.auth.faable.link` and `https://<your-account>.auth.faable.link` are equivalent.                                                                                                                        |
+| `authStrategy` | strategy builder                | Auth strategy (`authClientCredentials` \| `authApikey` \| `authBearer` \| `authCookie`), re-exported from `@faable/auth-sdk`. Defaults to `authClientCredentials` when `auth` is given; anonymous when neither is.                                                                                                                                      |
+| `auth`         | config                          | Config for the chosen strategy. Its shape is inferred from `authStrategy` (e.g. `{ client_id, client_secret }`).                                                                                                                                                                                                                                        |
+| `debug`        | boolean                         | Enables verbose logging in the underlying fetcher.                                                                                                                                                                                                                                                                                                      |
+| `headers`      | `{ project_id?; account_id? }`  | Advanced / testing escape hatch — target `domain` but have the server resolve a different project/account (sent as `x-faable-project` / `x-faableauth-account`). `team_id` is a deprecated alias of `project_id`: a `team_<hex>` value is sent as `project_<hex>`, and passing both with different ids throws. The SDK no longer sends `x-faable-team`. |
+| `clientInfo`   | `{ client?; name?; instance? }` | How this integration identifies itself (`x-faable-client` / `x-faable-instance`). `client` replaces the SDK's own `auth-sdk/<version>+<sha>`.                                                                                                                                                                                                           |
 
 ---
 
@@ -273,12 +278,65 @@ for await (const page of paginator) {
 }
 ```
 
+## Webhooks
+
+Faable Auth sends signed `POST`s to your server when something happens in the tenant (`user.created`, `team.member.added`…). Create the subscription with `faable auth webhooks create --url https://… -e user.created` (it prints the signing secret once), then verify every delivery before trusting it:
+
+```ts
+import {
+  constructWebhookEvent,
+  readRawBody,
+  WebhookVerificationError,
+} from "@faable/auth-sdk";
+
+// Next.js pages router: the signature is over the RAW body.
+export const config = { api: { bodyParser: false } };
+
+export default async function handler(req, res) {
+  let event;
+  try {
+    event = await constructWebhookEvent(
+      await readRawBody(req), // fetch-style handlers: await request.text()
+      req.headers,
+      process.env.FAABLEAUTH_WEBHOOK_SECRET!,
+    );
+  } catch (e) {
+    if (e instanceof WebhookVerificationError) return res.status(401).end();
+    throw e;
+  }
+
+  switch (event.type) {
+    case "user.created":
+      await welcome(event.payload.email); // payload is the User
+      break;
+    case "team.member.added":
+      await sync(event.payload.team_id, event.payload.user_id);
+      break;
+  }
+  res.status(200).end();
+}
+```
+
+- **Answer 2xx only when the work is done.** Timeouts, network errors, 5xx and 429 are retried at 1 min, 5 min, 30 min, 2 h and 12 h.
+- **The same event can arrive twice** (a retry after a response that was lost). `event.delivery_id` (`x-faable-delivery`) is the same on every retry: deduplicate by it, or make the work idempotent.
+- **Rotation:** `faable auth webhooks rotate-secret` keeps the old secret valid for 24 h and deliveries carry both signatures. To switch on your side without downtime, pass both: `await constructWebhookEvent(body, headers, [oldSecret, newSecret])`.
+- Uses Web Crypto, so it runs on Node ≥ 19, Deno, Bun and edge runtimes; that is why it is `async`.
+- Deliveries older than 5 minutes are refused as replays (`toleranceMs` to change it).
+
+`WebhookEvent`, `WebhookEventType`, `WebhookEventOf<"user.created">` and `WebhookPayload<"team.member.added">` are generated from the auth OpenAPI, like every other type.
+
 ## Types
 
 All response shapes are generated from the OpenAPI spec and re-exported from the package root:
 
 ```ts
-import type { User, Team, TeamMember, Connection, Client } from "@faable/auth-sdk";
+import type {
+  User,
+  Team,
+  TeamMember,
+  Connection,
+  Client,
+} from "@faable/auth-sdk";
 ```
 
 ## License

package/dist/index.d.ts

@@ -3,5 +3,7 @@ export { SDK_CLIENT, commit, version } from "./version.js";
 export * from "./api/generated-client.js";
 export * from "./api/api-types.js";
 export * from "./api/types.js";
+export { WEBHOOK_HEADERS, DEFAULT_WEBHOOK_TOLERANCE_MS, WebhookVerificationError, verifyWebhookSignature, constructWebhookEvent, readRawBody, } from "./webhooks.js";
+export type { WebhookEventOf, WebhookPayload, WebhookHeaders, WebhookVerificationFailure, VerifyWebhookOptions, VerifiedWebhookEvent, } from "./webhooks.js";
 export { authClientCredentials, authApikey, authBearer, authCookie, FaableApiError, } from "@faable/sdk-base";
 export type { ApiParams, ClientCredentialsConfig, ApikeyConfig, BearerConfig, RetryConfig, Fetcher, FetcherConfig, FetcherRequestParams, AuthStrategy, AuthStrategyBuilder, AuthStrategyContext, } from "@faable/sdk-base";

package/dist/index.js

@@ -3,6 +3,8 @@ export { SDK_CLIENT, commit, version } from "./version.js";
 export * from "./api/generated-client.js";
 export * from "./api/api-types.js";
 export * from "./api/types.js";
+// Receiving webhooks: verify the signature, get the event typed.
+export { WEBHOOK_HEADERS, DEFAULT_WEBHOOK_TOLERANCE_MS, WebhookVerificationError, verifyWebhookSignature, constructWebhookEvent, readRawBody, } from "./webhooks.js";
 // Re-export the auth strategies (and their config/types) from
 // @faable/sdk-base so consumers depend on @faable/auth-sdk ONLY — sdk-base
 // stays a transitive dependency and no app needs to import it directly.

package/dist/version.js

@@ -9,13 +9,13 @@
 // login pages could not import the SDK at all. Same pattern as auth-js.
 //
 // The sentinels MUST stay byte-identical to the `from` values in `.releaserc`.
-export const version = "2.7.108";
+export const version = "2.8.0";
 // Short git SHA of the released commit. The version dates a build; this names
 // the exact tree, so a canonical log line or an audit entry leads straight to
 // `git show <sha>`. Deliberately NOT hex: an unreleased build (dev, a local
 // link) cannot be mistaken for a real commit — auth only records values that
 // look like a SHA, and this one never will.
-export const commit = "e70d451";
+export const commit = "861ed06";
 // What this SDK writes in `x-faable-client`. Exported for a consumer that
 // builds a strategy on its own (outside `FaableAuthApi`) and still wants the
 // token request attributed — a bare `authClientCredentials` stamps only what

package/dist/webhooks.d.ts

@@ -0,0 +1,117 @@
+import type { WebhookEvent, WebhookEventType } from "./api/api-types.js";
+/**
+ * Receiving Faable Auth webhooks.
+ *
+ * Every delivery is a `POST` whose JSON body is a {@link WebhookEvent}, signed
+ * with the subscription's secret:
+ *
+ * - `x-faable-timestamp`: when it was sent, in Unix milliseconds.
+ * - `x-faable-signature`: `sha256=<hex>` — HMAC-SHA256 of
+ *   `${timestamp}.${raw body}`. During a secret rotation it carries two,
+ *   comma-separated (new first); one matching is enough.
+ * - `x-faable-delivery`: the event id, the same on every retry.
+ *
+ * Failed deliveries (timeout, network, 5xx, 429) are retried at 1 min, 5 min,
+ * 30 min, 2 h and 12 h, so a receiver must answer 2xx only once it has done
+ * its work, and must tolerate the same event twice.
+ *
+ * The event types come from the auth OpenAPI of the release this SDK was
+ * generated from: `type` narrows `payload`.
+ */
+export type { WebhookEvent, WebhookEventType };
+/** The delivery of one event type, e.g. `WebhookEventOf<"user.created">`. */
+export type WebhookEventOf<T extends WebhookEventType> = Extract<WebhookEvent, {
+    type: T;
+}>;
+/** The payload of one event type, e.g. the `User` for `"user.created"`. */
+export type WebhookPayload<T extends WebhookEventType> = WebhookEventOf<T>["payload"];
+export declare const WEBHOOK_HEADERS: {
+    readonly signature: "x-faable-signature";
+    readonly timestamp: "x-faable-timestamp";
+    readonly delivery: "x-faable-delivery";
+    readonly event: "x-faable-event";
+};
+/** How far a delivery's timestamp may be from now before it is a replay. */
+export declare const DEFAULT_WEBHOOK_TOLERANCE_MS: number;
+export type WebhookVerificationFailure = "missing_secret" | "missing_headers" | "timestamp_out_of_tolerance" | "signature_mismatch" | "invalid_body";
+/**
+ * Thrown by {@link verifyWebhookSignature} and {@link constructWebhookEvent}.
+ * Answer the delivery with a 400/401 and do nothing else: it was not sent by
+ * Faable Auth with your secret, or it was tampered with or replayed.
+ */
+export declare class WebhookVerificationError extends Error {
+    readonly reason: WebhookVerificationFailure;
+    constructor(reason: WebhookVerificationFailure, message: string);
+}
+/** Fetch `Headers`, Node's `IncomingHttpHeaders`, or a plain object. */
+export type WebhookHeaders = {
+    get(name: string): string | null;
+} | Record<string, string | string[] | undefined>;
+type RawBody = string | Uint8Array;
+export type VerifyWebhookOptions = {
+    /** The raw request body, exactly as received — not re-serialised JSON. */
+    body: RawBody;
+    /** `x-faable-signature`. */
+    signature: string | undefined;
+    /** `x-faable-timestamp`. */
+    timestamp: string | undefined;
+    /**
+     * The subscription's signing secret. Pass several while you rotate on your
+     * side (old and new): any of them may verify the delivery.
+     */
+    secret: string | string[];
+    /** Defaults to 5 minutes. */
+    toleranceMs?: number;
+    /** For tests. Defaults to `Date.now()`. */
+    now?: number;
+};
+/**
+ * Checks that a delivery was signed by Faable Auth with your secret, recently.
+ * Throws {@link WebhookVerificationError}; returns nothing when it is valid.
+ *
+ * Prefer {@link constructWebhookEvent}, which also parses and types the body.
+ */
+export declare function verifyWebhookSignature(options: VerifyWebhookOptions): Promise<void>;
+/** A verified delivery: the typed event plus the delivery id to deduplicate on. */
+export type VerifiedWebhookEvent = WebhookEvent & {
+    /** `x-faable-delivery`: the same on every retry of this event. */
+    delivery_id: string;
+};
+/**
+ * Verifies a delivery and returns its typed event.
+ *
+ * @example Next.js (pages router)
+ * ```ts
+ * import { constructWebhookEvent, readRawBody } from "@faable/auth-sdk";
+ *
+ * export const config = { api: { bodyParser: false } };
+ *
+ * export default async function handler(req, res) {
+ *   let event;
+ *   try {
+ *     event = await constructWebhookEvent(
+ *       await readRawBody(req),
+ *       req.headers,
+ *       process.env.FAABLEAUTH_WEBHOOK_SECRET!,
+ *     );
+ *   } catch {
+ *     return res.status(401).end();
+ *   }
+ *   if (event.type === "user.created") {
+ *     event.payload.email; // typed: the User
+ *   }
+ *   res.status(200).end();
+ * }
+ * ```
+ */
+export declare function constructWebhookEvent(body: RawBody, headers: WebhookHeaders, secret: string | string[], options?: {
+    toleranceMs?: number;
+    now?: number;
+}): Promise<VerifiedWebhookEvent>;
+/**
+ * The raw body of a Node request (`IncomingMessage`, Next.js pages API with
+ * `bodyParser: false`, Express without `express.json()` on the route): what
+ * the signature is computed over. With fetch-style handlers (Next.js route
+ * handlers, Hono…) use `await request.text()` instead.
+ */
+export declare const readRawBody: (req: AsyncIterable<Uint8Array | string>) => Promise<string>;

package/dist/webhooks.js

@@ -0,0 +1,170 @@
+export const WEBHOOK_HEADERS = {
+    signature: "x-faable-signature",
+    timestamp: "x-faable-timestamp",
+    delivery: "x-faable-delivery",
+    event: "x-faable-event",
+};
+/** How far a delivery's timestamp may be from now before it is a replay. */
+export const DEFAULT_WEBHOOK_TOLERANCE_MS = 5 * 60 * 1000;
+/**
+ * Thrown by {@link verifyWebhookSignature} and {@link constructWebhookEvent}.
+ * Answer the delivery with a 400/401 and do nothing else: it was not sent by
+ * Faable Auth with your secret, or it was tampered with or replayed.
+ */
+export class WebhookVerificationError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+        this.reason = reason;
+    }
+}
+const readHeader = (headers, name) => {
+    if (typeof headers.get === "function") {
+        return (headers.get(name) ?? undefined);
+    }
+    const record = headers;
+    const value = record[name] ??
+        Object.entries(record).find(([k]) => k.toLowerCase() === name)?.[1];
+    return Array.isArray(value) ? value[0] : value;
+};
+// Web Crypto and TextEncoder, not `node:crypto` / `Buffer`: this package also
+// loads in browser bundles (the hosted login pages), and the same code then
+// runs on Node ≥ 19, Deno, Bun and edge runtimes.
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const bodyText = (body) => typeof body === "string" ? body : decoder.decode(body);
+const fromHex = (hex) => {
+    if (hex.length % 2 !== 0 || !/^[0-9a-f]*$/i.test(hex))
+        return null;
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+};
+// Constant time for equal lengths: the comparison does not stop at the first
+// differing byte, so its timing does not leak how much of a guess was right.
+const sameBytes = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+};
+const hmacSha256 = async (secret, data) => {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error("Web Crypto (globalThis.crypto.subtle) is not available: verifying webhooks needs Node ≥ 19 or a runtime with Web Crypto.");
+    }
+    const key = await subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await subtle.sign("HMAC", key, encoder.encode(data)));
+};
+/**
+ * Checks that a delivery was signed by Faable Auth with your secret, recently.
+ * Throws {@link WebhookVerificationError}; returns nothing when it is valid.
+ *
+ * Prefer {@link constructWebhookEvent}, which also parses and types the body.
+ */
+export async function verifyWebhookSignature(options) {
+    const secrets = (Array.isArray(options.secret) ? options.secret : [options.secret]).filter((s) => typeof s === "string" && s.length > 0);
+    if (secrets.length === 0) {
+        throw new WebhookVerificationError("missing_secret", "No webhook secret configured: refusing every delivery.");
+    }
+    const { signature, timestamp } = options;
+    if (!signature || !timestamp) {
+        throw new WebhookVerificationError("missing_headers", `Missing ${WEBHOOK_HEADERS.signature} or ${WEBHOOK_HEADERS.timestamp}.`);
+    }
+    const sent = Number(timestamp);
+    const tolerance = options.toleranceMs ?? DEFAULT_WEBHOOK_TOLERANCE_MS;
+    const now = options.now ?? Date.now();
+    if (!Number.isFinite(sent) || Math.abs(now - sent) > tolerance) {
+        throw new WebhookVerificationError("timestamp_out_of_tolerance", "The delivery timestamp is outside the tolerance: a replay, or a clock far off.");
+    }
+    const signed = `${timestamp}.${bodyText(options.body)}`;
+    const received = signature
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.startsWith("sha256="))
+        .map((part) => fromHex(part.slice("sha256=".length)))
+        .filter((r) => r !== null);
+    let matches = false;
+    for (const secret of secrets) {
+        const expected = await hmacSha256(secret, signed);
+        if (received.some((r) => sameBytes(r, expected)))
+            matches = true;
+    }
+    if (!matches) {
+        throw new WebhookVerificationError("signature_mismatch", "The signature does not match: wrong secret, or the body was changed (verify the RAW body, not re-serialised JSON).");
+    }
+}
+/**
+ * Verifies a delivery and returns its typed event.
+ *
+ * @example Next.js (pages router)
+ * ```ts
+ * import { constructWebhookEvent, readRawBody } from "@faable/auth-sdk";
+ *
+ * export const config = { api: { bodyParser: false } };
+ *
+ * export default async function handler(req, res) {
+ *   let event;
+ *   try {
+ *     event = await constructWebhookEvent(
+ *       await readRawBody(req),
+ *       req.headers,
+ *       process.env.FAABLEAUTH_WEBHOOK_SECRET!,
+ *     );
+ *   } catch {
+ *     return res.status(401).end();
+ *   }
+ *   if (event.type === "user.created") {
+ *     event.payload.email; // typed: the User
+ *   }
+ *   res.status(200).end();
+ * }
+ * ```
+ */
+export async function constructWebhookEvent(body, headers, secret, options = {}) {
+    await verifyWebhookSignature({
+        body,
+        signature: readHeader(headers, WEBHOOK_HEADERS.signature),
+        timestamp: readHeader(headers, WEBHOOK_HEADERS.timestamp),
+        secret,
+        ...options,
+    });
+    let event;
+    try {
+        event = JSON.parse(bodyText(body));
+    }
+    catch {
+        throw new WebhookVerificationError("invalid_body", "The body is not JSON.");
+    }
+    if (!event || typeof event !== "object" || typeof event.type !== "string") {
+        throw new WebhookVerificationError("invalid_body", "The body is not a webhook event.");
+    }
+    return {
+        ...event,
+        delivery_id: readHeader(headers, WEBHOOK_HEADERS.delivery) ?? event.id,
+    };
+}
+/**
+ * The raw body of a Node request (`IncomingMessage`, Next.js pages API with
+ * `bodyParser: false`, Express without `express.json()` on the route): what
+ * the signature is computed over. With fetch-style handlers (Next.js route
+ * handlers, Hono…) use `await request.text()` instead.
+ */
+export const readRawBody = async (req) => {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(typeof chunk === "string" ? encoder.encode(chunk) : chunk);
+    }
+    const all = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+    let at = 0;
+    for (const c of chunks) {
+        all.set(c, at);
+        at += c.length;
+    }
+    return decoder.decode(all);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/auth-sdk",
-  "version": "2.7.108",
+  "version": "2.8.0",
   "author": "Marc Pomar <marc@faable.com>",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",