@atlasauth/backend 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './jwks-cache';
 export * from './verify';
 export * from './handshake';
+export * from './webhooks';
 export { createAtlasClient } from './client';
 export type { AtlasClient } from './client';
 export * from './client';

package/dist/index.js

@@ -19,6 +19,8 @@ exports.createAtlasClient = void 0;
 __exportStar(require("./jwks-cache"), exports);
 __exportStar(require("./verify"), exports);
 __exportStar(require("./handshake"), exports);
+// §12.2 inbound webhook verification for consumers.
+__exportStar(require("./webhooks"), exports);
 // The typed management client for the secret-key Backend API.
 var client_1 = require("./client");
 Object.defineProperty(exports, "createAtlasClient", { enumerable: true, get: function () { return client_1.createAtlasClient; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6DAA6D;AAC7D,+CAA6B;AAC7B,2CAAyB;AACzB,8CAA4B;AAE5B,8DAA8D;AAC9D,mCAA6C;AAApC,2GAAA,iBAAiB,OAAA;AAE1B,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6DAA6D;AAC7D,+CAA6B;AAC7B,2CAAyB;AACzB,8CAA4B;AAE5B,oDAAoD;AACpD,6CAA2B;AAE3B,8DAA8D;AAC9D,mCAA6C;AAApC,2GAAA,iBAAiB,OAAA;AAE1B,2CAAyB"}

package/dist/webhooks.d.ts

@@ -0,0 +1,45 @@
+/** Header names Atlas sends on every delivery (lower-case; match case-insensitively). */
+export declare const ATLAS_WEBHOOK_HEADERS: {
+    readonly id: "atlas-id";
+    readonly timestamp: "atlas-timestamp";
+    readonly signature: "atlas-signature";
+};
+export type WebhookVerifyFailure = 'missing_headers' | 'malformed_signature' | 'stale_timestamp' | 'signature_mismatch';
+export interface WebhookVerifyResult<T = unknown> {
+    /** True only when the signature and timestamp both check out. */
+    verified: boolean;
+    /** Why verification failed, when it did. */
+    reason?: WebhookVerifyFailure;
+    /** The parsed event envelope `{ id, type, timestamp, instance_id, data }` — present only when `verified`. */
+    event?: T;
+}
+type HeadersLike = Headers | Record<string, string | string[] | undefined>;
+export interface VerifyWebhookInput {
+    /** The RAW request body as received — a string or Buffer, NOT a parsed object. */
+    body: string | Buffer;
+    /** The request headers (a plain object, Node `req.headers`, or a Fetch `Headers`). */
+    headers: HeadersLike;
+    /** The endpoint's signing secret (shown once when the endpoint was created/rotated). */
+    secret: string;
+    /** Override "now" (tests); defaults to the current time. */
+    now?: Date;
+    /** Override the ±replay tolerance (defaults to 5 minutes). */
+    toleranceMs?: number;
+}
+/**
+ * Verify and parse an Atlas webhook. Returns `{ verified, reason?, event? }` —
+ * it never throws on a bad signature (a thrown verifier is easy to accidentally
+ * swallow). On success, `event` is the parsed envelope.
+ *
+ * ```ts
+ * // Express (raw body):
+ * app.post('/webhooks/atlas', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const { verified, event } = verifyWebhook({ body: req.body, headers: req.headers, secret });
+ *   if (!verified) return res.sendStatus(400);
+ *   // handle event.type ...
+ *   res.sendStatus(200);
+ * });
+ * ```
+ */
+export declare function verifyWebhook<T = unknown>(input: VerifyWebhookInput): WebhookVerifyResult<T>;
+export {};

package/dist/webhooks.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATLAS_WEBHOOK_HEADERS = void 0;
+exports.verifyWebhook = verifyWebhook;
+const node_crypto_1 = require("node:crypto");
+/**
+ * §12.2 — verify an inbound Atlas webhook, for the CUSTOMER consuming events.
+ *
+ * Atlas signs every delivery: `atlas-signature: v1,<base64>` is HMAC-SHA256 over
+ * `<id>.<timestamp>.<rawBody>` keyed with the endpoint secret, with `atlas-id`
+ * and `atlas-timestamp` (epoch ms) headers. The timestamp is INSIDE the signed
+ * material — a header-only timestamp would let an attacker replay a captured
+ * body under a fresh timestamp — and a delivery older than 5 minutes is rejected
+ * so a captured request cannot be replayed later.
+ *
+ * The signing logic is identical to the server's (`@atlas/core` `verifyWebhook`),
+ * reimplemented here with zero dependencies so an integrator gets a first-party
+ * verifier without pulling in Atlas internals. Verify over the RAW request body,
+ * BEFORE any JSON parse — re-serializing reorders keys and breaks the MAC.
+ */
+const SIGNATURE_VERSION = 'v1';
+const REPLAY_TOLERANCE_MS = 5 * 60_000;
+/** Header names Atlas sends on every delivery (lower-case; match case-insensitively). */
+exports.ATLAS_WEBHOOK_HEADERS = {
+    id: 'atlas-id',
+    timestamp: 'atlas-timestamp',
+    signature: 'atlas-signature',
+};
+/** Read a header case-insensitively from a plain object or a Fetch `Headers`. */
+function readHeader(headers, name) {
+    if (typeof headers.get === 'function') {
+        return headers.get(name) ?? undefined;
+    }
+    const bag = headers;
+    const direct = bag[name] ?? bag[name.toLowerCase()];
+    const v = Array.isArray(direct) ? direct[0] : direct;
+    if (v !== undefined)
+        return v;
+    // Fall back to a case-insensitive scan (Node lower-cases, but be safe).
+    const hit = Object.keys(bag).find((k) => k.toLowerCase() === name);
+    const found = hit ? bag[hit] : undefined;
+    return Array.isArray(found) ? found[0] : found;
+}
+/**
+ * Verify and parse an Atlas webhook. Returns `{ verified, reason?, event? }` —
+ * it never throws on a bad signature (a thrown verifier is easy to accidentally
+ * swallow). On success, `event` is the parsed envelope.
+ *
+ * ```ts
+ * // Express (raw body):
+ * app.post('/webhooks/atlas', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const { verified, event } = verifyWebhook({ body: req.body, headers: req.headers, secret });
+ *   if (!verified) return res.sendStatus(400);
+ *   // handle event.type ...
+ *   res.sendStatus(200);
+ * });
+ * ```
+ */
+function verifyWebhook(input) {
+    const raw = typeof input.body === 'string' ? input.body : input.body.toString('utf8');
+    const id = readHeader(input.headers, exports.ATLAS_WEBHOOK_HEADERS.id);
+    const timestampRaw = readHeader(input.headers, exports.ATLAS_WEBHOOK_HEADERS.timestamp);
+    const signature = readHeader(input.headers, exports.ATLAS_WEBHOOK_HEADERS.signature);
+    if (!id || !timestampRaw || !signature)
+        return { verified: false, reason: 'missing_headers' };
+    const [version, provided] = signature.split(',');
+    if (version !== SIGNATURE_VERSION || !provided)
+        return { verified: false, reason: 'malformed_signature' };
+    const timestamp = Number(timestampRaw);
+    const now = (input.now ?? new Date()).getTime();
+    const tolerance = input.toleranceMs ?? REPLAY_TOLERANCE_MS;
+    // Rejected in both directions: a far-future timestamp is as suspicious as a
+    // stale one — accepting it would let an attacker mint a long-lived replay.
+    if (!Number.isFinite(timestamp) || Math.abs(now - timestamp) > tolerance) {
+        return { verified: false, reason: 'stale_timestamp' };
+    }
+    const expected = (0, node_crypto_1.createHmac)('sha256', input.secret).update(`${id}.${timestamp}.${raw}`).digest('base64');
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length || !(0, node_crypto_1.timingSafeEqual)(a, b))
+        return { verified: false, reason: 'signature_mismatch' };
+    try {
+        return { verified: true, event: JSON.parse(raw) };
+    }
+    catch {
+        // Signature is valid but the body isn't JSON — surface it as verified with no event.
+        return { verified: true };
+    }
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlasauth/backend",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {