@calmlens/sdk 0.11.0 → 0.12.0

package/esm/CalmLensWebhooks-DShmAal4.js

@@ -0,0 +1,148 @@
+import { i as invalidArgument, n as CalmLensError, r as SDK_ERROR_CODES } from "./CalmLensError-CihGG26K.js";
+import { n as encodePathSegment } from "./CalmLensUtils-Cx32j2zt.js";
+//#region ../shared/src/JsonUtils.ts
+const stringifyJsonCanonical = (value) => JSON.stringify(value, (_key, nestedValue) => {
+	if (!nestedValue || typeof nestedValue !== "object" || Array.isArray(nestedValue)) return nestedValue;
+	return Object.fromEntries(Object.keys(nestedValue).sort().map((key) => [key, nestedValue[key]]));
+});
+//#endregion
+//#region ../shared/src/CryptoUtils.ts
+const encoder = new TextEncoder();
+/** Lowercase hex of `bytes`, two characters per byte. */
+const bytesToHex = (bytes) => Array.from(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+/** SHA-256 of the UTF-8 encoding of `value`, as lowercase hex. */
+const sha256Hex = async (value) => bytesToHex(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
+/** HMAC-SHA256 of `message` keyed with `secret` (both UTF-8 encoded), as lowercase hex. */
+const hmacSha256Hex = async (secret, message) => {
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return bytesToHex(await crypto.subtle.sign("HMAC", key, encoder.encode(message)));
+};
+/**
+* Compares two strings without leaking, through timing, where they first differ. Strings of
+* different lengths are unequal immediately (the length itself is not secret here).
+*/
+const timingSafeEqual = (a, b) => {
+	if (a.length !== b.length) return false;
+	let difference = 0;
+	for (let index = 0; index < a.length; index++) difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+	return difference === 0;
+};
+//#endregion
+//#region ../shared/src/UploadToken.ts
+const UPLOAD_TOKEN_PREFIX = "clut_";
+const UPLOAD_TOKEN_MAX_TTL_SECONDS = 3600;
+const SIGNING_CONTEXT = "calmlens-upload-token:v1:";
+const toBase64Url = (value) => btoa(String.fromCharCode(...new TextEncoder().encode(value))).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+/**
+* The part of an API key a token names so the backend can find the key's hash. The same rule as
+* the stored `keyPrefix`: the fixed `clsk_<region>_` part plus four random characters.
+*/
+const uploadTokenKeyPrefix = (apiKey) => apiKey.substring(0, apiKey.startsWith("clsk_") ? 13 : 8);
+/** The signing secret: the SHA-256 of the API key, which the backend stores instead of the key. */
+const signingSecret = (apiKey) => sha256Hex(apiKey);
+/** Signs `claims` with `apiKey` and returns the token. */
+const signUploadToken = async (claims, apiKey) => {
+	const body = toBase64Url(JSON.stringify(claims));
+	const signature = await hmacSha256Hex(await signingSecret(apiKey), SIGNING_CONTEXT + body);
+	return `${UPLOAD_TOKEN_PREFIX}${body}.${signature}`;
+};
+//#endregion
+//#region src/client/CalmLensUploadTokens.ts
+/**
+* Signs a single-use upload token with `apiKey`, locally. `CalmLensServerClient` and
+* `MockCalmLensServerClient` share it so both check options the same way.
+*/
+const signUploadTokenWithApiKey = async (apiKey, options, { now = Date.now(), nonce = crypto.randomUUID() } = {}) => {
+	if (!options || typeof options !== "object") throw invalidArgument("Options are required");
+	const { uploadPresetId, externalId, expiresInSeconds = 600 } = options;
+	encodePathSegment(uploadPresetId, "Upload preset ID");
+	if (!Number.isInteger(expiresInSeconds) || expiresInSeconds < 1 || expiresInSeconds > 3600) throw invalidArgument(`expiresInSeconds must be a whole number from 1 to ${UPLOAD_TOKEN_MAX_TTL_SECONDS}`);
+	if (externalId !== void 0 && (typeof externalId !== "string" || !externalId)) throw invalidArgument("externalId must be a non-empty string");
+	const expiresAt = now + expiresInSeconds * 1e3;
+	return {
+		token: await signUploadToken({
+			v: 1,
+			u: uploadPresetId,
+			k: uploadTokenKeyPrefix(apiKey),
+			e: expiresAt,
+			n: nonce,
+			...externalId === void 0 ? {} : { x: externalId }
+		}, apiKey),
+		expiresAt
+	};
+};
+//#endregion
+//#region src/client/CalmLensWebhooks.ts
+const WEBHOOK_DELIVERY_HEADER = "x-calmlens-delivery";
+const WEBHOOK_TIMESTAMP_HEADER = "x-calmlens-timestamp";
+const WEBHOOK_SIGNATURE_HEADER = "x-calmlens-signature";
+/** Deliveries whose timestamp is further than this from the receiver's clock are rejected. */
+const WEBHOOK_SIGNATURE_TOLERANCE_SECONDS = 300;
+const readHeader = (headers, name) => {
+	if (!headers) return void 0;
+	if (typeof headers.get === "function") return headers.get(name) ?? void 0;
+	const record = headers;
+	const key = Object.keys(record).find((candidate) => candidate.toLowerCase() === name);
+	const value = key === void 0 ? void 0 : record[key];
+	return Array.isArray(value) ? value.join(",") : value ?? void 0;
+};
+/** The raw body as text. Parsed objects are refused: re-serializing JSON changes the signed bytes. */
+const payloadToText = (payload) => {
+	if (typeof payload === "string") return payload;
+	if (payload instanceof ArrayBuffer || ArrayBuffer.isView(payload)) {
+		const view = ArrayBuffer.isView(payload) ? new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength) : new Uint8Array(payload);
+		return new TextDecoder("utf-8", { fatal: false }).decode(view);
+	}
+	throw invalidArgument("Webhook payload must be the raw request body as a string, Uint8Array/Buffer or ArrayBuffer, not parsed JSON");
+};
+/**
+* Verifies a webhook delivery: `x-calmlens-signature` must contain a `v1=` HMAC-SHA256 of
+* `"<x-calmlens-timestamp>.<raw body>"`, and the timestamp must be within `toleranceSeconds`
+* (default 300) of now. Returns `false` for anything missing, malformed or stale, and throws
+* `sdk/invalid-argument` when `payload` is not a raw body (for example, parsed JSON).
+*/
+async function verifyWebhookSignature(options) {
+	const { payload, secret, toleranceSeconds = 300, now, headers } = options;
+	const body = payloadToText(payload);
+	const signature = options.signature ?? readHeader(headers, "x-calmlens-signature");
+	const timestamp = options.timestamp ?? readHeader(headers, "x-calmlens-timestamp");
+	if (!secret || !signature || timestamp === null || timestamp === void 0) return false;
+	const timestampText = String(timestamp).trim();
+	if (!/^\d+$/.test(timestampText)) return false;
+	const nowMs = now === void 0 ? Date.now() : now instanceof Date ? now.getTime() : now;
+	if (Math.abs(Math.floor(nowMs / 1e3) - Number(timestampText)) > toleranceSeconds) return false;
+	const candidates = signature.split(",").map((part) => part.trim()).filter((part) => part.startsWith("v1=")).map((part) => part.slice(3).toLowerCase());
+	if (candidates.length === 0) return false;
+	const expected = await hmacSha256Hex(secret, `${timestampText}.${body}`);
+	let matched = false;
+	for (const candidate of candidates) if (timingSafeEqual(expected, candidate)) matched = true;
+	return matched;
+}
+/**
+* Verifies a webhook delivery and parses its body. Throws `sdk/invalid-webhook-signature`
+* when the signature or timestamp does not verify, and `sdk/invalid-webhook-payload` when a
+* verified body is not a webhook event. Narrow the result on `type` for typed `data.facts`.
+*
+* Event types and fact keys added to CalmLens after this SDK version are returned as they are,
+* so keep a default branch when you switch on `type`.
+*/
+async function parseWebhookEvent(options) {
+	if (!await verifyWebhookSignature(options)) throw new CalmLensError(SDK_ERROR_CODES.INVALID_WEBHOOK_SIGNATURE, { message: "Webhook signature or timestamp did not verify" });
+	let event;
+	try {
+		event = JSON.parse(payloadToText(options.payload));
+	} catch (cause) {
+		throw new CalmLensError(SDK_ERROR_CODES.INVALID_WEBHOOK_PAYLOAD, {
+			message: "Webhook body is not JSON",
+			cause
+		});
+	}
+	const candidate = event;
+	if (!candidate || typeof candidate !== "object" || typeof candidate.id !== "string" || typeof candidate.type !== "string" || typeof candidate.projectId !== "string" || !candidate.data || typeof candidate.data !== "object") throw new CalmLensError(SDK_ERROR_CODES.INVALID_WEBHOOK_PAYLOAD, { message: "Webhook body is not a CalmLens event" });
+	return event;
+}
+//#endregion
+export { parseWebhookEvent as a, hmacSha256Hex as c, WEBHOOK_TIMESTAMP_HEADER as i, stringifyJsonCanonical as l, WEBHOOK_SIGNATURE_HEADER as n, verifyWebhookSignature as o, WEBHOOK_SIGNATURE_TOLERANCE_SECONDS as r, signUploadTokenWithApiKey as s, WEBHOOK_DELIVERY_HEADER as t };