@distilled.cloud/stripe 0.25.1 → 0.26.0

package/lib/webhooks.js

@@ -0,0 +1,161 @@
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { StripeWebhookPayloadParseError, StripeWebhookSignatureError, } from "./errors.js";
+export const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+const payloadToBytes = (payload) => {
+    if (typeof payload === "string") {
+        return textEncoder.encode(payload);
+    }
+    if (payload instanceof ArrayBuffer) {
+        return new Uint8Array(payload);
+    }
+    return payload;
+};
+const payloadToString = (payload) => {
+    if (typeof payload === "string") {
+        return payload;
+    }
+    return textDecoder.decode(payloadToBytes(payload));
+};
+const secretToString = (secret) => Redacted.isRedacted(secret) ? Redacted.value(secret) : secret;
+const parseSignatureHeader = (signature) => {
+    if (signature == null || signature.trim() === "") {
+        return new StripeWebhookSignatureError({
+            message: "Stripe-Signature header is required",
+        });
+    }
+    let timestamp;
+    const signatures = [];
+    for (const part of signature.split(",")) {
+        const separatorIndex = part.indexOf("=");
+        if (separatorIndex === -1) {
+            continue;
+        }
+        const key = part.slice(0, separatorIndex).trim();
+        const value = part.slice(separatorIndex + 1).trim();
+        if (key === "t" && timestamp === undefined) {
+            timestamp = value;
+        }
+        else if (key === "v1") {
+            signatures.push(value);
+        }
+    }
+    if (timestamp === undefined || timestamp === "") {
+        return new StripeWebhookSignatureError({
+            message: "Stripe-Signature header is missing a timestamp",
+        });
+    }
+    const timestampSeconds = Number(timestamp);
+    if (!Number.isSafeInteger(timestampSeconds) ||
+        timestampSeconds < 0 ||
+        String(timestampSeconds) !== timestamp) {
+        return new StripeWebhookSignatureError({
+            message: "Stripe-Signature header timestamp is invalid",
+        });
+    }
+    if (signatures.length === 0) {
+        return new StripeWebhookSignatureError({
+            message: "Stripe-Signature header is missing a v1 signature",
+        });
+    }
+    return { timestamp, timestampSeconds, signatures };
+};
+const signedPayloadBytes = (timestamp, payload) => {
+    const timestampBytes = textEncoder.encode(`${timestamp}.`);
+    const bodyBytes = payloadToBytes(payload);
+    const signedPayload = new Uint8Array(timestampBytes.byteLength + bodyBytes.byteLength);
+    signedPayload.set(timestampBytes, 0);
+    signedPayload.set(bodyBytes, timestampBytes.byteLength);
+    return signedPayload.buffer;
+};
+const hmacSha256 = (secret, timestamp, payload) => Effect.tryPromise({
+    try: async () => {
+        const key = await crypto.subtle.importKey("raw", textEncoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+        const signature = await crypto.subtle.sign("HMAC", key, signedPayloadBytes(timestamp, payload));
+        return new Uint8Array(signature);
+    },
+    catch: (cause) => new StripeWebhookSignatureError({
+        message: "Unable to compute Stripe webhook signature",
+        cause,
+    }),
+});
+const hexToBytes = (hex) => {
+    if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) {
+        return undefined;
+    }
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+};
+const constantTimeEqual = (expected, candidate) => {
+    // JavaScript cannot guarantee CPU-level constant time, but length mismatches
+    // are folded into the accumulator so a matching prefix can never succeed.
+    let difference = expected.byteLength ^ candidate.byteLength;
+    const byteLength = Math.max(expected.byteLength, candidate.byteLength);
+    for (let index = 0; index < byteLength; index += 1) {
+        const expectedByte = index < expected.byteLength ? expected[index] : 0;
+        const candidateByte = index < candidate.byteLength ? candidate[index] : 0;
+        difference |= expectedByte ^ candidateByte;
+    }
+    return difference === 0;
+};
+const hasMatchingSignature = (expectedSignature, signatures) => {
+    let matched = false;
+    for (const signature of signatures) {
+        const candidate = hexToBytes(signature) ?? new Uint8Array(0);
+        matched = constantTimeEqual(expectedSignature, candidate) || matched;
+    }
+    return matched;
+};
+const validateTolerance = (timestampSeconds, toleranceSeconds) => {
+    if (!Number.isFinite(toleranceSeconds) || toleranceSeconds < 0) {
+        return new StripeWebhookSignatureError({
+            message: "Stripe webhook tolerance must be a non-negative number",
+        });
+    }
+    if (toleranceSeconds === 0) {
+        return undefined;
+    }
+    const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - timestampSeconds);
+    if (ageSeconds > toleranceSeconds) {
+        return new StripeWebhookSignatureError({
+            message: `Stripe webhook timestamp is outside the tolerance window of ${toleranceSeconds} seconds`,
+        });
+    }
+    return undefined;
+};
+export const verifySignature = ({ payload, signature, secret, toleranceSeconds = DEFAULT_WEBHOOK_TOLERANCE_SECONDS, }) => Effect.gen(function* () {
+    const parsed = parseSignatureHeader(signature);
+    if (parsed instanceof StripeWebhookSignatureError) {
+        return yield* Effect.fail(parsed);
+    }
+    const expectedSignature = yield* hmacSha256(secretToString(secret), parsed.timestamp, payload);
+    if (!hasMatchingSignature(expectedSignature, parsed.signatures)) {
+        return yield* Effect.fail(new StripeWebhookSignatureError({
+            message: "No v1 signature matches the expected Stripe webhook signature",
+        }));
+    }
+    const toleranceError = validateTolerance(parsed.timestampSeconds, toleranceSeconds);
+    if (toleranceError !== undefined) {
+        return yield* Effect.fail(toleranceError);
+    }
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const constructEvent = ({ payload, signature, secret, toleranceSeconds, }) => verifySignature({ payload, signature, secret, toleranceSeconds }).pipe(Effect.flatMap(() => Effect.try({
+    try: () => {
+        const parsed = JSON.parse(payloadToString(payload));
+        if (!isRecord(parsed)) {
+            throw new Error("Stripe webhook payload must be a JSON object");
+        }
+        return parsed;
+    },
+    catch: (cause) => new StripeWebhookPayloadParseError({
+        message: "Unable to parse Stripe webhook payload as JSON",
+        cause,
+    }),
+})));
+//# sourceMappingURL=webhooks.js.map

package/lib/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": "@distilled.cloud/stripe",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/alchemy-run/distilled",
@@ -40,6 +40,11 @@
       "bun": "./src/errors.ts",
       "default": "./lib/errors.js"
     },
+    "./Webhooks": {
+      "types": "./lib/webhooks.d.ts",
+      "bun": "./src/webhooks.ts",
+      "default": "./lib/webhooks.js"
+    },
     "./Operations": {
       "types": "./lib/operations/index.d.ts",
       "bun": "./src/operations/index.ts",
@@ -75,7 +80,7 @@
     "specs:update": "git -C specs/stripe-openapi fetch && git -C specs/stripe-openapi checkout master && git -C specs/stripe-openapi pull"
   },
   "dependencies": {
-    "@distilled.cloud/core": "0.25.1"
+    "@distilled.cloud/core": "0.26.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.0",

package/src/client.ts

@@ -25,6 +25,40 @@ import { Credentials } from "./credentials.ts";
 // Re-export for convenience
 export { UnknownStripeError } from "./errors.ts";
 
+type StripeConnectRequestOptions =
+  | {
+      readonly stripeAccount?: string | undefined;
+      readonly stripeContext?: never;
+    }
+  | {
+      readonly stripeAccount?: never;
+      readonly stripeContext?: string | undefined;
+    };
+
+export type StripeRequestOptions = {
+  readonly idempotencyKey?: string | undefined;
+  readonly apiVersion?: string | undefined;
+} & StripeConnectRequestOptions;
+
+const stripeRequestHeaders = (
+  options: StripeRequestOptions | undefined,
+): Record<string, string> => {
+  const headers: Record<string, string> = {};
+  if (options?.idempotencyKey !== undefined) {
+    headers["Idempotency-Key"] = options.idempotencyKey;
+  }
+  if (options?.stripeAccount !== undefined) {
+    headers["Stripe-Account"] = options.stripeAccount;
+  }
+  if (options?.stripeContext !== undefined) {
+    headers["Stripe-Context"] = options.stripeContext;
+  }
+  if (options?.apiVersion !== undefined) {
+    headers["Stripe-Version"] = options.apiVersion;
+  }
+  return headers;
+};
+
 // Stripe API Error Response Schema
 // Stripe wraps errors in { error: { type, code, message, ... } }
 const StripeErrorInner = Schema.Struct({
@@ -160,12 +194,13 @@ const matchError = (
 /**
  * Stripe API client.
  */
-export const API = makeAPI<Credentials>({
+export const API = makeAPI<Credentials, StripeRequestOptions>({
   credentials: Credentials as any,
   getBaseUrl: (creds: any) => creds.apiBaseUrl,
   getAuthHeaders: (creds: any) => ({
     Authorization: `Bearer ${Redacted.value(creds.apiKey)}`,
   }),
+  getRequestHeaders: stripeRequestHeaders,
   matchError,
   ParseError: StripeParseError as any,
   retry: Retry as any,

package/src/errors.ts

@@ -148,3 +148,28 @@ export class StripeParseError extends Schema.TaggedErrorClass<StripeParseError>(
     cause: Schema.Unknown,
   },
 ).pipe(Category.withParseError) {}
+
+/**
+ * Stripe webhook signature verification failed.
+ *
+ * This is raised by the local webhook helpers when the Stripe-Signature header
+ * is missing, malformed, expired, or does not match the raw request payload.
+ */
+export class StripeWebhookSignatureError extends Schema.TaggedErrorClass<StripeWebhookSignatureError>()(
+  "StripeWebhookSignatureError",
+  {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown),
+  },
+).pipe(Category.withAuthError) {}
+
+/**
+ * Stripe webhook payload JSON parsing failed after signature verification.
+ */
+export class StripeWebhookPayloadParseError extends Schema.TaggedErrorClass<StripeWebhookPayloadParseError>()(
+  "StripeWebhookPayloadParseError",
+  {
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown),
+  },
+).pipe(Category.withParseError) {}

package/src/index.ts

@@ -10,6 +10,7 @@ export * from "./credentials.ts";
 export * as Category from "./category.ts";
 export * as T from "./traits.ts";
 export * as Retry from "./retry.ts";
+export * as Webhooks from "./webhooks.ts";
 export { API } from "./client.ts";
 export * from "./errors.ts";
 export * from "./operations/index.ts";

package/src/webhooks.ts

@@ -0,0 +1,307 @@
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import {
+  StripeWebhookPayloadParseError,
+  StripeWebhookSignatureError,
+} from "./errors.ts";
+
+export const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
+
+export type WebhookPayload = string | Uint8Array | ArrayBuffer;
+export type WebhookSecret = string | Redacted.Redacted<string>;
+
+export interface StripeEvent {
+  readonly id?: string;
+  readonly object?: string;
+  readonly api_version?: string;
+  readonly created?: number;
+  readonly data?: unknown;
+  readonly livemode?: boolean;
+  readonly pending_webhooks?: number;
+  readonly request?: unknown;
+  readonly type?: string;
+  readonly [key: string]: unknown;
+}
+
+export interface VerifySignatureOptions {
+  /**
+   * Raw request body exactly as Stripe sent it. Do not pass parsed or
+   * reserialized JSON.
+   */
+  readonly payload: WebhookPayload;
+  readonly signature: string | null | undefined;
+  readonly secret: WebhookSecret;
+  /**
+   * Maximum allowed webhook age in seconds. Pass `0` to skip timestamp
+   * tolerance verification for tests or offline reprocessing.
+   */
+  readonly toleranceSeconds?: number | undefined;
+}
+
+export interface ConstructEventOptions extends VerifySignatureOptions {}
+
+interface ParsedSignatureHeader {
+  readonly timestamp: string;
+  readonly timestampSeconds: number;
+  readonly signatures: ReadonlyArray<string>;
+}
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+
+const payloadToBytes = (payload: WebhookPayload): Uint8Array => {
+  if (typeof payload === "string") {
+    return textEncoder.encode(payload);
+  }
+
+  if (payload instanceof ArrayBuffer) {
+    return new Uint8Array(payload);
+  }
+
+  return payload;
+};
+
+const payloadToString = (payload: WebhookPayload): string => {
+  if (typeof payload === "string") {
+    return payload;
+  }
+
+  return textDecoder.decode(payloadToBytes(payload));
+};
+
+const secretToString = (secret: WebhookSecret): string =>
+  Redacted.isRedacted(secret) ? (Redacted.value(secret) as string) : secret;
+
+const parseSignatureHeader = (
+  signature: string | null | undefined,
+): ParsedSignatureHeader | StripeWebhookSignatureError => {
+  if (signature == null || signature.trim() === "") {
+    return new StripeWebhookSignatureError({
+      message: "Stripe-Signature header is required",
+    });
+  }
+
+  let timestamp: string | undefined;
+  const signatures: Array<string> = [];
+
+  for (const part of signature.split(",")) {
+    const separatorIndex = part.indexOf("=");
+    if (separatorIndex === -1) {
+      continue;
+    }
+
+    const key = part.slice(0, separatorIndex).trim();
+    const value = part.slice(separatorIndex + 1).trim();
+
+    if (key === "t" && timestamp === undefined) {
+      timestamp = value;
+    } else if (key === "v1") {
+      signatures.push(value);
+    }
+  }
+
+  if (timestamp === undefined || timestamp === "") {
+    return new StripeWebhookSignatureError({
+      message: "Stripe-Signature header is missing a timestamp",
+    });
+  }
+
+  const timestampSeconds = Number(timestamp);
+  if (
+    !Number.isSafeInteger(timestampSeconds) ||
+    timestampSeconds < 0 ||
+    String(timestampSeconds) !== timestamp
+  ) {
+    return new StripeWebhookSignatureError({
+      message: "Stripe-Signature header timestamp is invalid",
+    });
+  }
+
+  if (signatures.length === 0) {
+    return new StripeWebhookSignatureError({
+      message: "Stripe-Signature header is missing a v1 signature",
+    });
+  }
+
+  return { timestamp, timestampSeconds, signatures };
+};
+
+const signedPayloadBytes = (
+  timestamp: string,
+  payload: WebhookPayload,
+): ArrayBuffer => {
+  const timestampBytes = textEncoder.encode(`${timestamp}.`);
+  const bodyBytes = payloadToBytes(payload);
+  const signedPayload = new Uint8Array(
+    timestampBytes.byteLength + bodyBytes.byteLength,
+  );
+
+  signedPayload.set(timestampBytes, 0);
+  signedPayload.set(bodyBytes, timestampBytes.byteLength);
+
+  return signedPayload.buffer;
+};
+
+const hmacSha256 = (
+  secret: string,
+  timestamp: string,
+  payload: WebhookPayload,
+): Effect.Effect<Uint8Array, StripeWebhookSignatureError> =>
+  Effect.tryPromise({
+    try: async () => {
+      const key = await crypto.subtle.importKey(
+        "raw",
+        textEncoder.encode(secret),
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["sign"],
+      );
+      const signature = await crypto.subtle.sign(
+        "HMAC",
+        key,
+        signedPayloadBytes(timestamp, payload),
+      );
+
+      return new Uint8Array(signature);
+    },
+    catch: (cause) =>
+      new StripeWebhookSignatureError({
+        message: "Unable to compute Stripe webhook signature",
+        cause,
+      }),
+  });
+
+const hexToBytes = (hex: string): Uint8Array | undefined => {
+  if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]+$/.test(hex)) {
+    return undefined;
+  }
+
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+};
+
+const constantTimeEqual = (
+  expected: Uint8Array,
+  candidate: Uint8Array,
+): boolean => {
+  // JavaScript cannot guarantee CPU-level constant time, but length mismatches
+  // are folded into the accumulator so a matching prefix can never succeed.
+  let difference = expected.byteLength ^ candidate.byteLength;
+  const byteLength = Math.max(expected.byteLength, candidate.byteLength);
+
+  for (let index = 0; index < byteLength; index += 1) {
+    const expectedByte = index < expected.byteLength ? expected[index] : 0;
+    const candidateByte = index < candidate.byteLength ? candidate[index] : 0;
+    difference |= expectedByte ^ candidateByte;
+  }
+
+  return difference === 0;
+};
+
+const hasMatchingSignature = (
+  expectedSignature: Uint8Array,
+  signatures: ReadonlyArray<string>,
+): boolean => {
+  let matched = false;
+
+  for (const signature of signatures) {
+    const candidate = hexToBytes(signature) ?? new Uint8Array(0);
+    matched = constantTimeEqual(expectedSignature, candidate) || matched;
+  }
+
+  return matched;
+};
+
+const validateTolerance = (
+  timestampSeconds: number,
+  toleranceSeconds: number,
+): StripeWebhookSignatureError | undefined => {
+  if (!Number.isFinite(toleranceSeconds) || toleranceSeconds < 0) {
+    return new StripeWebhookSignatureError({
+      message: "Stripe webhook tolerance must be a non-negative number",
+    });
+  }
+
+  if (toleranceSeconds === 0) {
+    return undefined;
+  }
+
+  const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - timestampSeconds);
+  if (ageSeconds > toleranceSeconds) {
+    return new StripeWebhookSignatureError({
+      message: `Stripe webhook timestamp is outside the tolerance window of ${toleranceSeconds} seconds`,
+    });
+  }
+
+  return undefined;
+};
+
+export const verifySignature = ({
+  payload,
+  signature,
+  secret,
+  toleranceSeconds = DEFAULT_WEBHOOK_TOLERANCE_SECONDS,
+}: VerifySignatureOptions): Effect.Effect<void, StripeWebhookSignatureError> =>
+  Effect.gen(function* () {
+    const parsed = parseSignatureHeader(signature);
+    if (parsed instanceof StripeWebhookSignatureError) {
+      return yield* Effect.fail(parsed);
+    }
+
+    const expectedSignature = yield* hmacSha256(
+      secretToString(secret),
+      parsed.timestamp,
+      payload,
+    );
+
+    if (!hasMatchingSignature(expectedSignature, parsed.signatures)) {
+      return yield* Effect.fail(
+        new StripeWebhookSignatureError({
+          message:
+            "No v1 signature matches the expected Stripe webhook signature",
+        }),
+      );
+    }
+
+    const toleranceError = validateTolerance(
+      parsed.timestampSeconds,
+      toleranceSeconds,
+    );
+    if (toleranceError !== undefined) {
+      return yield* Effect.fail(toleranceError);
+    }
+  });
+
+const isRecord = (value: unknown): value is StripeEvent =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+export const constructEvent = ({
+  payload,
+  signature,
+  secret,
+  toleranceSeconds,
+}: ConstructEventOptions): Effect.Effect<
+  StripeEvent,
+  StripeWebhookSignatureError | StripeWebhookPayloadParseError
+> =>
+  verifySignature({ payload, signature, secret, toleranceSeconds }).pipe(
+    Effect.flatMap(() =>
+      Effect.try({
+        try: () => {
+          const parsed = JSON.parse(payloadToString(payload)) as unknown;
+          if (!isRecord(parsed)) {
+            throw new Error("Stripe webhook payload must be a JSON object");
+          }
+          return parsed;
+        },
+        catch: (cause) =>
+          new StripeWebhookPayloadParseError({
+            message: "Unable to parse Stripe webhook payload as JSON",
+            cause,
+          }),
+      }),
+    ),
+  );