@supa-media/convex 1.2.1

package/src/schema/tenantScoping.ts

@@ -0,0 +1,243 @@
+/**
+ * Tenant Scoping Discipline
+ *
+ * Query-time complement to `supaTenantTables` (`./tenantTables`). Where
+ * `supaTenantTables` defines the tenant + junction tables, `supaTenantScope`
+ * generalizes the read-enforcement discipline Fount Studios built on top of
+ * its (hardcoded, `organizationId`-specific) equivalent —
+ * `apps/convex/lib/org.ts` (`rowInOrg`, `activeOrgMemberIds`,
+ * `resolveActiveOrg`/`getCurrentOrg`/`requireOrg`) — parameterized by
+ * `tenantName` instead of a fixed field name, so it derives the exact same
+ * `{tenantName}Id` / `user{TenantName}s` identifiers `supaTenantTables` uses.
+ *
+ * Fount's pattern in one line: resolve the active tenant ONCE at the top of a
+ * handler, then filter every collected row with a cheap in-memory check — a
+ * null active tenant degrades to unfiltered reads (migration/pre-backfill
+ * safety net) rather than an error.
+ *
+ * Usage:
+ * ```ts
+ * // convex/schema.ts
+ * import { defineSchema } from "convex/server";
+ * import { supaAuthTables, supaTenantTables } from "@supa-media/convex/schema";
+ *
+ * const tenantName = "organization";
+ * export default defineSchema({
+ *   ...supaAuthTables,
+ *   ...supaTenantTables({ tenantName }),
+ * });
+ *
+ * // convex/lib/tenant.ts
+ * import { supaTenantScope } from "@supa-media/convex/schema";
+ * export const orgScope = supaTenantScope({ tenantName: "organization" });
+ *
+ * // convex/functions/bookings.ts
+ * import { requireAuthId } from "@supa-media/convex/auth";
+ * import { orgScope } from "../lib/tenant";
+ *
+ * export const list = query({
+ *   handler: async (ctx) => {
+ *     const userId = await requireAuthId(ctx);
+ *     const orgId = await orgScope.getCurrentTenantId(ctx, userId);
+ *     return (await ctx.db.query("bookings").collect())
+ *       .filter((row) => orgScope.rowInTenant(row, orgId));
+ *   },
+ * });
+ * ```
+ *
+ * Deviations from Fount's `lib/org.ts` (intentional, for genericity — see
+ * `packages/convex` PR description for the full callout):
+ *  - No Super Admin cross-tenant bypass. Fount's `requireOrg`/`requireMembership`
+ *    let a global "Super Admin" role skip the membership check; that assumes an
+ *    app-specific roles/permissions system this package doesn't ship. A
+ *    consumer that needs a bypass wraps `requireTenantId` with its own check.
+ *  - Auth resolution is decoupled. Fount's `requireOrg` calls `requireAuth`
+ *    internally; here the caller resolves `userId` itself (e.g. via
+ *    `requireAuthId` from `@supa-media/convex/auth`) and passes it in, so this
+ *    module has no dependency on the auth module.
+ */
+
+import { ConvexError } from "convex/values";
+
+/** Config shared with `supaTenantTables` — must use the same `tenantName`. */
+export interface TenantScopeConfig {
+  /** Name for the tenant entity (e.g. "organization", "workspace", "community"). Must match the `tenantName` passed to `supaTenantTables`. */
+  tenantName: string;
+}
+
+/** Minimal DB context — works with Convex `QueryCtx` and `MutationCtx` without importing generated types. */
+interface TenantScopeCtx {
+  db: {
+    get: (id: any) => Promise<any>;
+    query: (table: string) => any;
+  };
+}
+
+/** A row carrying a `{tenantName}Id` field, of unknown shape otherwise. */
+type TenantScopedRow = Record<string, any>;
+
+export interface SupaTenantScope {
+  /** The tenant id field name on scoped rows/documents, e.g. "organizationId". */
+  tenantIdField: string;
+  /** The field on `users` storing the user's active tenant, e.g. "activeOrganizationId". Not added by `supaAuthTables` — the consumer owns this field on their `users` table. */
+  activeTenantField: string;
+  /** The junction table name from `supaTenantTables`, e.g. "userOrganizations". */
+  junctionTableName: string;
+
+  /**
+   * Whether an org-stamped row belongs to the given tenant. A `null` tenantId
+   * (unresolvable — e.g. mid-migration, before backfill) degrades to
+   * unfiltered reads so the app keeps working; once a tenant is active, only
+   * its rows pass. Mirrors fount's `rowInOrg`.
+   */
+  rowInTenant(row: TenantScopedRow, tenantId: string | null): boolean;
+
+  /**
+   * Resolve the active tenant for a user id, or `null` if unresolvable.
+   * Prefers `users.{activeTenantField}`; if unset, falls back to the user's
+   * sole active membership row (a single-tenant user never needs an explicit
+   * switch). Returns `null` when ambiguous (0 or 2+ active memberships) —
+   * mirrors fount's `resolveActiveOrg`/`getCurrentOrg`.
+   */
+  getCurrentTenantId(
+    ctx: TenantScopeCtx,
+    userId: string,
+  ): Promise<string | null>;
+
+  /**
+   * Whether a user has an active membership row for the given tenant, via
+   * the junction table's `by_userId_{tenantIdField}` compound index.
+   */
+  isMemberOfTenant(
+    ctx: TenantScopeCtx,
+    userId: string,
+    tenantId: string,
+  ): Promise<boolean>;
+
+  /**
+   * Require a resolvable active tenant AND an active membership in it.
+   * Throws `ConvexError({ code: "NO_ACTIVE_TENANT" })` if no tenant is
+   * resolvable, `ConvexError({ code: "FORBIDDEN" })` if the user has no active
+   * membership in it. Mirrors fount's `requireOrg` (minus the Super Admin
+   * bypass — see module-level deviation note).
+   */
+  requireTenantId(ctx: TenantScopeCtx, userId: string): Promise<string>;
+
+  /**
+   * The set of user ids with an active membership in the tenant, for scoping
+   * queries over tables that have no `{tenantName}Id` column of their own
+   * (e.g. `users` — tenant membership lives in the junction table). Mirrors
+   * fount's `activeOrgMemberIds`.
+   */
+  activeTenantMemberIds(
+    ctx: TenantScopeCtx,
+    tenantId: string,
+  ): Promise<Set<string>>;
+}
+
+/**
+ * Build the tenant-scoping helpers for a given `tenantName`. The returned
+ * functions derive the same `{tenantName}Id` / `user{TenantName}s` identifiers
+ * `supaTenantTables` uses, so the two stay in lockstep as long as both are
+ * configured with the same `tenantName`.
+ */
+export function supaTenantScope(config: TenantScopeConfig): SupaTenantScope {
+  const { tenantName } = config;
+  const capitalName =
+    tenantName.charAt(0).toUpperCase() + tenantName.slice(1);
+  const tenantIdField = `${tenantName}Id`;
+  const activeTenantField = `active${capitalName}Id`;
+  const junctionTableName = `user${capitalName}s`;
+
+  function rowInTenant(row: TenantScopedRow, tenantId: string | null): boolean {
+    return tenantId === null || row[tenantIdField] === tenantId;
+  }
+
+  async function findMembership(
+    ctx: TenantScopeCtx,
+    userId: string,
+    tenantId: string,
+  ): Promise<TenantScopedRow | null> {
+    return await ctx.db
+      .query(junctionTableName)
+      .withIndex(`by_userId_${tenantIdField}`, (q: any) =>
+        q.eq("userId", userId).eq(tenantIdField, tenantId),
+      )
+      .unique();
+  }
+
+  async function isMemberOfTenant(
+    ctx: TenantScopeCtx,
+    userId: string,
+    tenantId: string,
+  ): Promise<boolean> {
+    const membership = await findMembership(ctx, userId, tenantId);
+    return membership !== null && membership.isActive !== false;
+  }
+
+  async function getCurrentTenantId(
+    ctx: TenantScopeCtx,
+    userId: string,
+  ): Promise<string | null> {
+    const user = await ctx.db.get(userId);
+    if (user === null) return null;
+    if (user[activeTenantField]) return user[activeTenantField];
+
+    const memberships = await ctx.db
+      .query(junctionTableName)
+      .withIndex("by_userId", (q: any) => q.eq("userId", userId))
+      .collect();
+    const active = memberships.filter(
+      (m: TenantScopedRow) => m.isActive !== false,
+    );
+    return active.length === 1 ? active[0][tenantIdField] : null;
+  }
+
+  async function requireTenantId(
+    ctx: TenantScopeCtx,
+    userId: string,
+  ): Promise<string> {
+    const tenantId = await getCurrentTenantId(ctx, userId);
+    if (tenantId === null) {
+      throw new ConvexError({
+        code: "NO_ACTIVE_TENANT",
+        message: `No active ${tenantName} for this user`,
+      });
+    }
+    if (!(await isMemberOfTenant(ctx, userId, tenantId))) {
+      throw new ConvexError({
+        code: "FORBIDDEN",
+        message: `No active membership in the active ${tenantName}`,
+      });
+    }
+    return tenantId;
+  }
+
+  async function activeTenantMemberIds(
+    ctx: TenantScopeCtx,
+    tenantId: string,
+  ): Promise<Set<string>> {
+    const memberships = await ctx.db
+      .query(junctionTableName)
+      .withIndex(`by_${tenantIdField}`, (q: any) =>
+        q.eq(tenantIdField, tenantId),
+      )
+      .collect();
+    return new Set(
+      memberships
+        .filter((m: TenantScopedRow) => m.isActive !== false)
+        .map((m: TenantScopedRow) => String(m.userId)),
+    );
+  }
+
+  return {
+    tenantIdField,
+    activeTenantField,
+    junctionTableName,
+    rowInTenant,
+    getCurrentTenantId,
+    isMemberOfTenant,
+    requireTenantId,
+    activeTenantMemberIds,
+  };
+}

package/src/schema/tenantTables.ts

@@ -0,0 +1,84 @@
+/**
+ * Tenant Tables
+ *
+ * Creates multi-tenant schema tables with configurable names.
+ * Provides a tenants table, a userTenants junction table, and
+ * adds an activeTenantId concept to the user model.
+ *
+ * Usage:
+ * ```ts
+ * import { defineSchema } from "convex/server";
+ * import { supaAuthTables, supaTenantTables } from "@supa-media/convex/schema";
+ *
+ * const tenantTables = supaTenantTables({
+ *   tenantName: "organization",
+ *   tenantFields: {
+ *     website: v.optional(v.string()),
+ *   },
+ * });
+ *
+ * export default defineSchema({
+ *   ...supaAuthTables,
+ *   ...tenantTables,
+ * });
+ * ```
+ */
+
+import { defineTable } from "convex/server";
+import { v, type Validator } from "convex/values";
+
+export interface TenantTableConfig {
+  /** Name for the tenant entity (e.g. "organization", "workspace", "community"). */
+  tenantName: string;
+  /** Additional fields to add to the tenant table. */
+  tenantFields?: Record<string, Validator<any, any, any>>;
+}
+
+/**
+ * Generate multi-tenant tables based on config.
+ *
+ * Returns an object with two table definitions:
+ * - `{tenantName}s` — the tenants table (e.g. "organizations")
+ * - `user{TenantName}s` — the junction table (e.g. "userOrganizations")
+ *
+ * The junction table includes:
+ * - userId, {tenantName}Id — foreign keys
+ * - role — user's role within the tenant
+ * - isActive — soft delete flag
+ * - joinedAt — when the user joined
+ */
+export function supaTenantTables(config: TenantTableConfig) {
+  const { tenantName, tenantFields = {} } = config;
+  const capitalName =
+    tenantName.charAt(0).toUpperCase() + tenantName.slice(1);
+  const tenantsTableName = `${tenantName}s`;
+  const junctionTableName = `user${capitalName}s`;
+  const tenantIdField = `${tenantName}Id`;
+
+  const tenantsTable = defineTable({
+    name: v.string(),
+    slug: v.optional(v.string()),
+    image: v.optional(v.string()),
+    isActive: v.optional(v.boolean()),
+    createdAt: v.optional(v.number()),
+    ...tenantFields,
+  })
+    .index("by_slug", ["slug"])
+    .index("by_name", ["name"]);
+
+  const junctionTable = defineTable({
+    userId: v.id("users"),
+    [`${tenantName}Id`]: v.string(), // v.id() requires literal table name; use string for flexibility
+    role: v.optional(v.string()),
+    isActive: v.optional(v.boolean()),
+    joinedAt: v.optional(v.number()),
+  })
+    .index("by_userId", ["userId"])
+    .index(`by_${tenantIdField}`, [tenantIdField])
+    .index(`by_userId_${tenantIdField}`, ["userId", tenantIdField]);
+
+  return {
+    [tenantsTableName]: tenantsTable,
+    [junctionTableName]: junctionTable,
+  } as Record<string, ReturnType<typeof defineTable>>;
+}

package/src/webhooks/hmac.ts

@@ -0,0 +1,125 @@
+/**
+ * Generic HMAC Signature Verification
+ *
+ * A small, dependency-free core for verifying HMAC-signed webhook requests
+ * (Stripe, GitHub, custom internal callbacks, ...) from inside a Convex
+ * `httpAction`. Convex's default runtime doesn't have `node:crypto`, so this
+ * uses the standard Web Crypto API (`crypto.subtle`) — the same approach
+ * production code in both Fount Studios and Togather already relies on for
+ * hand-rolled webhook verification (as opposed to pulling in a provider SDK).
+ *
+ * Provider-specific verifiers (`verifyStripeSignature`, `verifyTwilioSignature`,
+ * ...) are built on top of this — see the sibling files in this directory.
+ */
+
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ * Compares every character regardless of where a mismatch occurs, so an
+ * attacker can't use response-time differences to guess the signature
+ * byte-by-byte.
+ */
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}
+
+function toHex(bytes: ArrayBuffer): string {
+  return Array.from(new Uint8Array(bytes))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function toBase64(bytes: ArrayBuffer): string {
+  let binary = "";
+  const view = new Uint8Array(bytes);
+  for (let i = 0; i < view.byteLength; i++) {
+    binary += String.fromCharCode(view[i] as number);
+  }
+  // btoa is a Web standard available in the Convex runtime.
+  return btoa(binary);
+}
+
+/** Compute an HMAC digest and encode it as hex or base64. */
+export async function computeHmac(
+  secret: string,
+  message: string,
+  options: { hash?: "SHA-256" | "SHA-1"; encoding?: "hex" | "base64" } = {},
+): Promise<string> {
+  const { hash = "SHA-256", encoding = "hex" } = options;
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash },
+    false,
+    ["sign"],
+  );
+  const digest = await crypto.subtle.sign("HMAC", key, encoder.encode(message));
+  return encoding === "base64" ? toBase64(digest) : toHex(digest);
+}
+
+export interface VerifyHmacSignatureOptions {
+  /** Hash algorithm backing the HMAC. Defaults to "SHA-256". */
+  hash?: "SHA-256" | "SHA-1";
+  /** Digest encoding the provided signature is expressed in. Defaults to "hex". */
+  encoding?: "hex" | "base64";
+  /**
+   * Literal prefix the provided signature must start with (e.g. GitHub's
+   * `"sha256="` on `X-Hub-Signature-256`). Stripped before comparing. A
+   * signature missing this prefix is rejected. Omit for headers that carry
+   * the bare digest (e.g. a custom `x-app-signature: <hex>` header).
+   */
+  prefix?: string;
+}
+
+/**
+ * Verify an HMAC-signed webhook payload against a provided signature header
+ * value. Generic building block for simple "HMAC over the raw body" schemes —
+ * providers with a more structured signing input (Stripe's `t=...,v1=...`,
+ * Twilio's URL+params concatenation) layer their own signing-input
+ * construction on top of {@link computeHmac} / {@link timingSafeEqual} instead
+ * (see `./stripe` and `./twilio`).
+ *
+ * Usage (GitHub `X-Hub-Signature-256`, e.g. dispatching a repo webhook):
+ * ```ts
+ * const ok = await verifyHmacSignature(rawBody, request.headers.get("x-hub-signature-256"), secret, {
+ *   prefix: "sha256=",
+ * });
+ * ```
+ *
+ * Usage (a bare hex-digest internal callback header, no prefix):
+ * ```ts
+ * const ok = await verifyHmacSignature(rawBody, request.headers.get("x-app-signature"), secret);
+ * ```
+ */
+export async function verifyHmacSignature(
+  payload: string,
+  providedSignature: string | null | undefined,
+  secret: string,
+  options: VerifyHmacSignatureOptions = {},
+): Promise<boolean> {
+  if (!providedSignature || !secret) return false;
+
+  const { prefix } = options;
+  let candidate = providedSignature;
+  if (prefix !== undefined) {
+    if (!candidate.startsWith(prefix)) return false;
+    candidate = candidate.slice(prefix.length);
+  }
+
+  try {
+    const expected = await computeHmac(secret, payload, options);
+    // Hex digests are case-insensitive (providers vary on casing); base64
+    // digests are case-sensitive and must compare exactly.
+    const encoding = options.encoding ?? "hex";
+    return encoding === "hex"
+      ? timingSafeEqual(candidate.toLowerCase(), expected.toLowerCase())
+      : timingSafeEqual(candidate, expected);
+  } catch {
+    return false;
+  }
+}

package/src/webhooks/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Webhook Signature Verification
+ *
+ * Dependency-free helpers for verifying signed (or shared-secret-gated)
+ * inbound webhooks from inside a Convex `httpAction`. Built on the Web Crypto
+ * API (`crypto.subtle`) so nothing here needs `node:crypto` or a provider SDK.
+ *
+ * - `verifyHmacSignature` / `computeHmac` / `timingSafeEqual` — the generic
+ *   core for "HMAC over the raw body, compare against a header" schemes
+ *   (GitHub's `X-Hub-Signature-256`, custom internal callback signing, ...).
+ * - `verifyStripeSignature` — Stripe's `t=...,v1=...` scheme with timestamp
+ *   tolerance and multi-signature (secret rotation) support.
+ * - `verifyTwilioSignature` — Twilio's URL+sorted-params signing scheme.
+ * - `verifySharedSecretHeader` — for providers with no signing scheme at all
+ *   (e.g. Resend inbound email), gated by a constant shared-secret header
+ *   instead of a cryptographic signature.
+ *
+ * Ported from production webhook handlers in Fount Studios
+ * (`apps/convex/lib/webhooks/*`) and Togather (`apps/convex/http.ts`).
+ *
+ * NOTE: unlike most of this package's subpaths, this module is deliberately
+ * NOT re-exported from the package root (`@supa-media/convex`). The
+ * `./payments` subpath already exports its own `verifyStripeSignature` (a
+ * simpler, single-signature variant scoped to `handleStripeWebhook`); adding
+ * this module's `verifyStripeSignature` to the root barrel would collide with
+ * it. Import from `@supa-media/convex/webhooks` explicitly.
+ */
+export {
+  verifyHmacSignature,
+  computeHmac,
+  timingSafeEqual,
+} from "./hmac";
+export type { VerifyHmacSignatureOptions } from "./hmac";
+
+export { verifyStripeSignature } from "./stripe";
+export type { VerifyStripeSignatureOptions } from "./stripe";
+
+export { verifyTwilioSignature } from "./twilio";
+export type { VerifyTwilioSignatureArgs } from "./twilio";
+
+export { verifySharedSecretHeader } from "./sharedSecret";

package/src/webhooks/sharedSecret.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared-secret header verification.
+ *
+ * Not every inbound webhook is HMAC-signed. Fount Studios' Resend inbound-email
+ * handler (`apps/convex/lib/webhooks/resend.ts`, `shouldDropInbound`) is a real
+ * example: Resend does not sign inbound webhook payloads (no Svix/HMAC scheme
+ * in play there), so the production guard is a constant shared-secret header
+ * (`x-inbound-test-secret`) compared against an env var, used to gate
+ * non-production deployments from ingesting real mail. This helper generalizes
+ * that comparison — do not reach for `verifyHmacSignature` when a provider
+ * genuinely has no signing scheme; a plain shared secret is what fount's
+ * production code actually does here.
+ *
+ * Deviation from fount's inline version: the original does a plain `!==`
+ * string compare (fine for a low-value dev/test gate secret). This helper
+ * uses a timing-safe compare instead, since it's meant to be reused for
+ * higher-value secrets too.
+ */
+import { timingSafeEqual } from "./hmac";
+
+/** Minimal header-reader interface — matches both `Request.headers` and a plain `Headers` instance. */
+interface HeaderReader {
+  get(name: string): string | null;
+}
+
+/**
+ * Verify a request carries the expected value in a given header, via a
+ * timing-safe comparison. Returns `false` if the expected secret is unset
+ * (nothing to compare against) or the header is missing/mismatched.
+ *
+ * Usage:
+ * ```ts
+ * // convex/http.ts — Resend inbound email (no signing scheme; shared secret only)
+ * import { verifySharedSecretHeader } from "@supa-media/convex/webhooks";
+ *
+ * const ok = verifySharedSecretHeader(request.headers, "x-inbound-test-secret", process.env.INBOUND_TEST_SECRET);
+ * ```
+ */
+export function verifySharedSecretHeader(
+  headers: HeaderReader,
+  headerName: string,
+  expectedSecret: string | undefined,
+): boolean {
+  if (!expectedSecret) return false;
+  const provided = headers.get(headerName);
+  if (provided === null) return false;
+  return timingSafeEqual(provided, expectedSecret);
+}

package/src/webhooks/stripe.ts

@@ -0,0 +1,97 @@
+/**
+ * Stripe webhook signature verification.
+ *
+ * Stripe signs webhooks with `Stripe-Signature: t=<timestamp>,v1=<hex hmac>[,v1=<hex hmac>...]`.
+ * The signed payload is `${timestamp}.${rawBody}`, HMAC-SHA256'd with the
+ * endpoint's webhook signing secret. Stripe can send multiple `v1=` values
+ * during a secret rotation window — any one matching is sufficient.
+ *
+ * This is a hand-rolled Web Crypto implementation (mirrors Togather's
+ * `apps/convex/http.ts`) rather than the `stripe` npm SDK's
+ * `stripe.webhooks.constructEventAsync`. The SDK works too, but pulling it
+ * into a framework package for signature verification alone would be a heavy
+ * runtime dependency for one function — the signing scheme itself is public
+ * and documented, so we verify it directly with `crypto.subtle`.
+ *
+ * https://docs.stripe.com/webhooks#verify-official-libraries
+ */
+import { timingSafeEqual, computeHmac } from "./hmac";
+
+export interface VerifyStripeSignatureOptions {
+  /** Max allowed clock skew between the signed timestamp and now, in seconds. Defaults to 300 (5 minutes), matching Stripe's own tolerance. */
+  toleranceSeconds?: number;
+}
+
+/**
+ * Verify a Stripe `Stripe-Signature` header against the raw request body.
+ * Returns `false` (never throws) on any malformed header, expired timestamp,
+ * or signature mismatch.
+ *
+ * Usage:
+ * ```ts
+ * // convex/http.ts
+ * import { verifyStripeSignature } from "@supa-media/convex/webhooks";
+ *
+ * http.route({
+ *   path: "/stripe/webhook",
+ *   method: "POST",
+ *   handler: httpAction(async (ctx, request) => {
+ *     const body = await request.text();
+ *     const signature = request.headers.get("stripe-signature");
+ *     const ok = await verifyStripeSignature(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+ *     if (!ok) return new Response("Invalid signature", { status: 400 });
+ *     const event = JSON.parse(body);
+ *     // ...
+ *   }),
+ * });
+ * ```
+ */
+export async function verifyStripeSignature(
+  payload: string,
+  signatureHeader: string | null | undefined,
+  secret: string,
+  options: VerifyStripeSignatureOptions = {},
+): Promise<boolean> {
+  if (!signatureHeader || !secret) return false;
+  const { toleranceSeconds = 300 } = options;
+
+  try {
+    // Parse signature header into timestamp and all v1 signatures. Stripe
+    // may send multiple v1 signatures during secret rotation, so we collect
+    // them all and match against any one.
+    let timestamp = "";
+    const v1Signatures: string[] = [];
+
+    for (const part of signatureHeader.split(",")) {
+      const [key, value] = part.split("=");
+      if (key === undefined || value === undefined) continue;
+      const trimmedKey = key.trim();
+      if (trimmedKey === "t") {
+        timestamp = value;
+      } else if (trimmedKey === "v1") {
+        v1Signatures.push(value);
+      }
+    }
+
+    if (!timestamp || v1Signatures.length === 0) return false;
+
+    // Check timestamp is within tolerance to prevent replay attacks.
+    const currentTime = Math.floor(Date.now() / 1000);
+    if (Math.abs(currentTime - parseInt(timestamp, 10)) > toleranceSeconds) {
+      return false;
+    }
+
+    const signedPayload = `${timestamp}.${payload}`;
+    const computedSig = await computeHmac(secret, signedPayload, {
+      hash: "SHA-256",
+      encoding: "hex",
+    });
+
+    // Accept if any v1 signature matches (constant-time comparison).
+    return v1Signatures.some((sig) =>
+      timingSafeEqual(sig.toLowerCase(), computedSig.toLowerCase()),
+    );
+  } catch {
+    return false;
+  }
+}