@trigora/sdk 0.3.0 → 0.5.0

package/README.md

@@ -184,6 +184,36 @@ If you do not provide your own payload type, `event.payload` defaults to `JsonVa
 
 For webhook flows, request metadata may also be available on `event.request`, including headers, method, URL, and the raw request body. `event.request.rawBody` is useful when you want to verify webhook signatures yourself.
 
+## Stripe Webhooks
+
+Trigora includes a small helper for verifying Stripe webhook signatures:
+
+```ts
+import { verifyStripeWebhook } from '@trigora/sdk/stripe';
+
+const stripeEvent = await verifyStripeWebhook(event, {
+  secret: ctx.env.STRIPE_WEBHOOK_SECRET,
+});
+```
+
+This verifies against `event.request.rawBody` and the `Stripe-Signature` header.
+
+Production Stripe webhooks should verify signatures before trusting payloads.
+
+## GitHub Webhooks
+
+Trigora includes a small helper for verifying GitHub webhook signatures:
+
+```ts
+import { verifyGitHubWebhook } from '@trigora/sdk/github';
+
+const githubEvent = await verifyGitHubWebhook(event, {
+  secret: ctx.env.GITHUB_WEBHOOK_SECRET,
+});
+```
+
+This verifies against `event.request.rawBody` and the `X-Hub-Signature-256` header.
+
 ## Context
 
 Flows receive a context object with logging and environment access:
@@ -196,6 +226,8 @@ ctx.log.error('message')
 ctx.env
 ```
 
+In local CLI runs, `ctx.env` includes the process environment after loading `.env` and `.env.local`, with existing shell variables taking precedence.
+
 The exact exported type is `FlowContext<TEnv>`.
 
 ## Exported Types

package/dist/defineFlow.d.ts

@@ -1,4 +1,10 @@
-import type { CronFlowDefinition, JsonValue, ManualFlowDefinition, WebhookFlowDefinition } from '@trigora/contracts';
+import type { CronEventPayload, CronFlowDefinition, FlowDefinition, FlowRunFn, JsonValue, ManualFlowDefinition, ManualTrigger, Trigger, WebhookTrigger, WebhookFlowDefinition, CronTrigger } from '@trigora/contracts';
+type DefineFlowInput<TPayload, TEnv extends Record<string, string>, TTrigger extends Trigger> = {
+    id: string;
+    trigger: TTrigger;
+    run: TTrigger extends ManualTrigger ? FlowRunFn<TPayload, TEnv, ManualTrigger> : TTrigger extends WebhookTrigger ? FlowRunFn<TPayload, TEnv, WebhookTrigger> : TTrigger extends CronTrigger ? FlowRunFn<CronEventPayload, TEnv, CronTrigger> : never;
+};
+type DefineFlowOutput<TPayload, TEnv extends Record<string, string>, TTrigger extends Trigger> = TTrigger extends ManualTrigger ? ManualFlowDefinition<TPayload, TEnv> : TTrigger extends WebhookTrigger ? WebhookFlowDefinition<TPayload, TEnv> : TTrigger extends CronTrigger ? CronFlowDefinition<TEnv> : FlowDefinition<TPayload, TEnv, TTrigger>;
 /**
  * Define a Trigora flow.
  *
@@ -29,6 +35,8 @@ import type { CronFlowDefinition, JsonValue, ManualFlowDefinition, WebhookFlowDe
  * });
  * ```
  */
+export declare function defineFlow<TTrigger extends Trigger, TPayload = JsonValue, TEnv extends Record<string, string> = Record<string, string>>(flow: DefineFlowInput<TPayload, TEnv, TTrigger>): DefineFlowOutput<TPayload, TEnv, TTrigger>;
 export declare function defineFlow<TPayload = JsonValue, TEnv extends Record<string, string> = Record<string, string>>(flow: ManualFlowDefinition<TPayload, TEnv>): ManualFlowDefinition<TPayload, TEnv>;
 export declare function defineFlow<TPayload = JsonValue, TEnv extends Record<string, string> = Record<string, string>>(flow: WebhookFlowDefinition<TPayload, TEnv>): WebhookFlowDefinition<TPayload, TEnv>;
-export declare function defineFlow<TPayload = JsonValue, TEnv extends Record<string, string> = Record<string, string>>(flow: CronFlowDefinition<TPayload, TEnv>): CronFlowDefinition<TPayload, TEnv>;
+export declare function defineFlow<TEnv extends Record<string, string> = Record<string, string>>(flow: CronFlowDefinition<TEnv>): CronFlowDefinition<TEnv>;
+export {};

package/dist/github.d.ts

@@ -0,0 +1,8 @@
+import type { WebhookFlowEvent } from '@trigora/contracts';
+export type VerifyGitHubWebhookOptions = {
+    secret: string | undefined;
+};
+export declare class GitHubWebhookVerificationError extends Error {
+    name: string;
+}
+export declare function verifyGitHubWebhook<T = unknown>(event: WebhookFlowEvent, options: VerifyGitHubWebhookOptions): Promise<T>;

package/dist/github.js

@@ -0,0 +1,120 @@
+// src/webhookSignature.ts
+function encodeUtf8(value) {
+  return new TextEncoder().encode(value);
+}
+function toArrayBuffer(bytes) {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function getHeaderCaseInsensitive(headers, headerName) {
+  const normalizedName = headerName.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === normalizedName) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function isHexString(value) {
+  return value.length > 0 && value.length % 2 === 0 && /^[0-9a-f]+$/i.test(value);
+}
+function timingSafeEqualStrings(left, right) {
+  const leftBytes = encodeUtf8(left);
+  const rightBytes = encodeUtf8(right);
+  const length = Math.max(leftBytes.length, rightBytes.length);
+  let difference = leftBytes.length === rightBytes.length ? 0 : 1;
+  for (let index = 0; index < length; index += 1) {
+    difference |= (leftBytes[index] ?? 0) ^ (rightBytes[index] ?? 0);
+  }
+  return difference === 0;
+}
+async function computeHmacSha256Hex(secret, signedPayload) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error("Web Crypto API is unavailable in this runtime.");
+  }
+  const key = await subtle.importKey(
+    "raw",
+    toArrayBuffer(encodeUtf8(secret)),
+    {
+      name: "HMAC",
+      hash: "SHA-256"
+    },
+    false,
+    ["sign"]
+  );
+  const signature = await subtle.sign("HMAC", key, toArrayBuffer(encodeUtf8(signedPayload)));
+  return bytesToHex(new Uint8Array(signature));
+}
+function requireWebhookRequestParts(event, providerName) {
+  if (!event.request || typeof event.request.headers !== "object" || event.request.headers === null) {
+    throw new Error(`${providerName} webhook request metadata is required.`);
+  }
+  if (typeof event.request.rawBody !== "string") {
+    throw new Error(`${providerName} webhook raw body is required.`);
+  }
+  return {
+    headers: event.request.headers,
+    rawBody: event.request.rawBody
+  };
+}
+
+// src/github.ts
+var GITHUB_SIGNATURE_HEADER = "x-hub-signature-256";
+var GITHUB_SIGNATURE_PREFIX = "sha256=";
+var GitHubWebhookVerificationError = class extends Error {
+  name = "GitHubWebhookVerificationError";
+};
+function createVerificationError(message) {
+  return new GitHubWebhookVerificationError(message);
+}
+function parseGitHubSignatureHeader(headerValue) {
+  const normalizedValue = headerValue.trim();
+  if (!normalizedValue.toLowerCase().startsWith(GITHUB_SIGNATURE_PREFIX)) {
+    return null;
+  }
+  const signature = normalizedValue.slice(GITHUB_SIGNATURE_PREFIX.length).trim().toLowerCase();
+  if (!isHexString(signature)) {
+    return null;
+  }
+  return signature;
+}
+async function verifyGitHubWebhook(event, options) {
+  if (!options.secret || options.secret.trim().length === 0) {
+    throw createVerificationError("A GitHub webhook secret is required.");
+  }
+  let requestParts;
+  try {
+    requestParts = requireWebhookRequestParts(event, "GitHub");
+  } catch (error) {
+    throw createVerificationError(error instanceof Error ? error.message : String(error));
+  }
+  const signatureHeader = getHeaderCaseInsensitive(requestParts.headers, GITHUB_SIGNATURE_HEADER);
+  if (!signatureHeader) {
+    throw createVerificationError("X-Hub-Signature-256 header is required.");
+  }
+  const parsedSignature = parseGitHubSignatureHeader(signatureHeader);
+  if (!parsedSignature) {
+    throw createVerificationError("X-Hub-Signature-256 header is invalid.");
+  }
+  let expectedSignature;
+  try {
+    expectedSignature = await computeHmacSha256Hex(options.secret, requestParts.rawBody);
+  } catch (error) {
+    throw createVerificationError(error instanceof Error ? error.message : String(error));
+  }
+  if (!timingSafeEqualStrings(parsedSignature, expectedSignature)) {
+    throw createVerificationError("GitHub webhook signature did not match.");
+  }
+  try {
+    return JSON.parse(requestParts.rawBody);
+  } catch {
+    throw createVerificationError("GitHub webhook body contained invalid JSON.");
+  }
+}
+export {
+  GitHubWebhookVerificationError,
+  verifyGitHubWebhook
+};

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { defineFlow } from './defineFlow';
-export type { FlowContext, FlowDefinition, FlowEvent, FlowRunFn, JsonValue, Trigger, WebhookFlowResult, } from '@trigora/contracts';
+export type { CronEventPayload, CronFlowEvent, FlowContext, FlowDefinition, FlowEvent, FlowRunFn, JsonValue, ManualFlowEvent, Trigger, WebhookFlowEvent, WebhookFlowResult, } from '@trigora/contracts';

package/dist/stripe.d.ts

@@ -0,0 +1,9 @@
+import type { WebhookFlowEvent } from '@trigora/contracts';
+export type VerifyStripeWebhookOptions = {
+    secret: string | undefined;
+    toleranceSeconds?: number;
+};
+export declare class StripeWebhookVerificationError extends Error {
+    name: string;
+}
+export declare function verifyStripeWebhook<T = unknown>(event: WebhookFlowEvent, options: VerifyStripeWebhookOptions): Promise<T>;

package/dist/stripe.js

@@ -0,0 +1,147 @@
+// src/webhookSignature.ts
+function encodeUtf8(value) {
+  return new TextEncoder().encode(value);
+}
+function toArrayBuffer(bytes) {
+  return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+function bytesToHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function getHeaderCaseInsensitive(headers, headerName) {
+  const normalizedName = headerName.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === normalizedName) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function isHexString(value) {
+  return value.length > 0 && value.length % 2 === 0 && /^[0-9a-f]+$/i.test(value);
+}
+function timingSafeEqualStrings(left, right) {
+  const leftBytes = encodeUtf8(left);
+  const rightBytes = encodeUtf8(right);
+  const length = Math.max(leftBytes.length, rightBytes.length);
+  let difference = leftBytes.length === rightBytes.length ? 0 : 1;
+  for (let index = 0; index < length; index += 1) {
+    difference |= (leftBytes[index] ?? 0) ^ (rightBytes[index] ?? 0);
+  }
+  return difference === 0;
+}
+async function computeHmacSha256Hex(secret, signedPayload) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new Error("Web Crypto API is unavailable in this runtime.");
+  }
+  const key = await subtle.importKey(
+    "raw",
+    toArrayBuffer(encodeUtf8(secret)),
+    {
+      name: "HMAC",
+      hash: "SHA-256"
+    },
+    false,
+    ["sign"]
+  );
+  const signature = await subtle.sign("HMAC", key, toArrayBuffer(encodeUtf8(signedPayload)));
+  return bytesToHex(new Uint8Array(signature));
+}
+function requireWebhookRequestParts(event, providerName) {
+  if (!event.request || typeof event.request.headers !== "object" || event.request.headers === null) {
+    throw new Error(`${providerName} webhook request metadata is required.`);
+  }
+  if (typeof event.request.rawBody !== "string") {
+    throw new Error(`${providerName} webhook raw body is required.`);
+  }
+  return {
+    headers: event.request.headers,
+    rawBody: event.request.rawBody
+  };
+}
+
+// src/stripe.ts
+var DEFAULT_TOLERANCE_SECONDS = 300;
+var STRIPE_SIGNATURE_HEADER = "stripe-signature";
+var StripeWebhookVerificationError = class extends Error {
+  name = "StripeWebhookVerificationError";
+};
+function createVerificationError(message) {
+  return new StripeWebhookVerificationError(message);
+}
+function parseStripeSignatureHeader(headerValue) {
+  let timestamp;
+  const signatures = [];
+  for (const part of headerValue.split(",")) {
+    const separatorIndex = part.indexOf("=");
+    if (separatorIndex <= 0) {
+      continue;
+    }
+    const key = part.slice(0, separatorIndex).trim();
+    const value = part.slice(separatorIndex + 1).trim();
+    if (key === "t") {
+      const parsedTimestamp = Number(value);
+      if (!Number.isInteger(parsedTimestamp)) {
+        return null;
+      }
+      timestamp = parsedTimestamp;
+      continue;
+    }
+    if (key === "v1" && isHexString(value)) {
+      signatures.push(value.toLowerCase());
+    }
+  }
+  if (timestamp === void 0 || signatures.length === 0) {
+    return null;
+  }
+  return { timestamp, signatures };
+}
+async function verifyStripeWebhook(event, options) {
+  if (!options.secret || options.secret.trim().length === 0) {
+    throw createVerificationError("A Stripe webhook secret is required.");
+  }
+  let requestParts;
+  try {
+    requestParts = requireWebhookRequestParts(event, "Stripe");
+  } catch (error) {
+    throw createVerificationError(error instanceof Error ? error.message : String(error));
+  }
+  const signatureHeader = getHeaderCaseInsensitive(requestParts.headers, STRIPE_SIGNATURE_HEADER);
+  if (!signatureHeader) {
+    throw createVerificationError("Stripe-Signature header is required.");
+  }
+  const parsedHeader = parseStripeSignatureHeader(signatureHeader);
+  if (!parsedHeader) {
+    throw createVerificationError("Stripe-Signature header is invalid.");
+  }
+  const toleranceSeconds = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (toleranceSeconds !== 0) {
+    const currentTimestamp = Math.floor(Date.now() / 1e3);
+    if (Math.abs(currentTimestamp - parsedHeader.timestamp) > toleranceSeconds) {
+      throw createVerificationError("Stripe webhook timestamp is outside the allowed tolerance.");
+    }
+  }
+  const signedPayload = `${parsedHeader.timestamp}.${requestParts.rawBody}`;
+  let expectedSignature;
+  try {
+    expectedSignature = await computeHmacSha256Hex(options.secret, signedPayload);
+  } catch (error) {
+    throw createVerificationError(error instanceof Error ? error.message : String(error));
+  }
+  const matches = parsedHeader.signatures.some(
+    (signature) => timingSafeEqualStrings(signature, expectedSignature)
+  );
+  if (!matches) {
+    throw createVerificationError("Stripe webhook signature did not match.");
+  }
+  try {
+    return JSON.parse(requestParts.rawBody);
+  } catch {
+    throw createVerificationError("Stripe webhook body contained invalid JSON.");
+  }
+}
+export {
+  StripeWebhookVerificationError,
+  verifyStripeWebhook
+};

package/dist/webhookSignature.d.ts

@@ -0,0 +1,12 @@
+import type { WebhookFlowEvent } from '@trigora/contracts';
+export declare function encodeUtf8(value: string): Uint8Array;
+export declare function toArrayBuffer(bytes: Uint8Array): ArrayBuffer;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function getHeaderCaseInsensitive(headers: Record<string, string>, headerName: string): string | undefined;
+export declare function isHexString(value: string): boolean;
+export declare function timingSafeEqualStrings(left: string, right: string): boolean;
+export declare function computeHmacSha256Hex(secret: string, signedPayload: string): Promise<string>;
+export declare function requireWebhookRequestParts(event: WebhookFlowEvent, providerName: string): {
+    headers: Record<string, string>;
+    rawBody: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigora/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/trigora-dev/trigora"
@@ -28,6 +28,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./github": {
+      "types": "./dist/github.d.ts",
+      "default": "./dist/github.js"
+    },
+    "./stripe": {
+      "types": "./dist/stripe.d.ts",
+      "default": "./dist/stripe.js"
     }
   },
   "files": [
@@ -37,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@trigora/contracts": "0.3.0"
+    "@trigora/contracts": "0.5.5"
   },
   "devDependencies": {
     "tsup": "^8.5.1"