@supabase/server 0.1.0-alpha.1 → 0.1.1-rc.25

package/dist/{verify-auth-DxUT0XoT.mjs → verify-auth-2S7zFfR-.mjs}

@@ -2,6 +2,26 @@ import { createClient } from "@supabase/supabase-js";
 import { createLocalJWKSet, jwtVerify } from "jose";
 
 //#region src/errors.ts
+/**
+* Thrown when a required environment variable is missing or malformed.
+*
+* Has a fixed `status` of `500` since environment errors are server-side
+* configuration issues, not client errors.
+*
+* @example
+* ```ts
+* import { EnvError } from '@supabase/server'
+*
+* try {
+*   const client = createAdminClient()
+* } catch (e) {
+*   if (e instanceof EnvError) {
+*     console.error(`Config issue [${e.code}]: ${e.message}`)
+*     // → "Config issue [MISSING_SUPABASE_URL]: SUPABASE_URL is required but not set"
+*   }
+* }
+* ```
+*/
 var EnvError = class extends Error {
 	constructor(message, code = "ENV_ERROR") {
 		super(message);
@@ -10,6 +30,26 @@ var EnvError = class extends Error {
 		this.code = code;
 	}
 };
+/**
+* Thrown when authentication or authorization fails.
+*
+* Carries an HTTP `status` code suitable for returning directly in a response
+* (typically `401` for invalid credentials, `500` for server-side auth failures).
+*
+* @example
+* ```ts
+* import { AuthError, createSupabaseContext } from '@supabase/server'
+*
+* const { data: ctx, error } = await createSupabaseContext(request, { allow: 'user' })
+* if (error) {
+*   // error is an AuthError
+*   return Response.json(
+*     { error: error.message, code: error.code },
+*     { status: error.status },
+*   )
+* }
+* ```
+*/
 var AuthError = class extends Error {
 	constructor(message, code = "AUTH_ERROR", status = 401) {
 		super(message);
@@ -21,10 +61,20 @@ var AuthError = class extends Error {
 
 //#endregion
 //#region src/core/resolve-env.ts
+/**
+* Reads an environment variable from the current runtime (Deno, Node.js, or Bun).
+* Cloudflare Workers require node-compat or passing values via `overrides`.
+* @internal
+*/
 function getEnvVar(name) {
 	if (typeof Deno !== "undefined" && Deno.env?.get) return Deno.env.get(name);
 	if (typeof process !== "undefined" && process.env) return process.env[name];
 }
+/**
+* Parses a JSON string into a `Record<string, string>` key map.
+* Returns an empty object if the input is missing, malformed, or not a plain object.
+* @internal
+*/
 function parseKeys(raw) {
 	if (!raw) return {};
 	try {
@@ -35,6 +85,12 @@ function parseKeys(raw) {
 		return {};
 	}
 }
+/**
+* Resolves API keys from environment variables. Checks the plural form first
+* (`SUPABASE_PUBLISHABLE_KEYS` as JSON), then falls back to the singular form
+* (`SUPABASE_PUBLISHABLE_KEY` stored as `{ default: "<value>" }`).
+* @internal
+*/
 function resolveKeys(singularVar, pluralVar) {
 	const plural = getEnvVar(pluralVar);
 	if (plural) return parseKeys(plural);
@@ -42,6 +98,12 @@ function resolveKeys(singularVar, pluralVar) {
 	if (singular) return { default: singular };
 	return {};
 }
+/**
+* Parses a JWKS JSON string into a {@link JsonWebKeySet}.
+* Accepts both `{ keys: [...] }` and bare `[...]` array formats.
+* Returns `null` if the input is missing or malformed.
+* @internal
+*/
 function parseJwks(raw) {
 	if (!raw) return null;
 	try {
@@ -53,6 +115,25 @@ function parseJwks(raw) {
 		return null;
 	}
 }
+/**
+* Resolves Supabase environment configuration from runtime environment variables.
+*
+* Reads `SUPABASE_URL`, keys (`SUPABASE_PUBLISHABLE_KEYS` / `SUPABASE_SECRET_KEYS`),
+* and `SUPABASE_JWKS`. Works across Deno, Node.js, and Bun. For Cloudflare Workers,
+* use `overrides` or enable node-compat.
+*
+* @param overrides - Partial values that take precedence over env vars.
+* @returns `{ data: SupabaseEnv, error: null }` on success, `{ data: null, error: EnvError }` on failure.
+*
+* @example
+* ```ts
+* const { data: env, error } = resolveEnv()
+* if (error) throw error
+*
+* // Override for tests
+* const { data: env } = resolveEnv({ url: 'http://localhost:54321' })
+* ```
+*/
 function resolveEnv(overrides) {
 	const url = overrides?.url ?? getEnvVar("SUPABASE_URL");
 	if (!url) return {
@@ -72,6 +153,23 @@ function resolveEnv(overrides) {
 
 //#endregion
 //#region src/core/create-admin-client.ts
+/**
+* Creates an admin Supabase client that bypasses Row-Level Security.
+*
+* Uses a secret key for authentication, giving full access to all data.
+* Session persistence is disabled (stateless, one client per request).
+*
+* @param env - Optional environment overrides (passed through to {@link resolveEnv}).
+* @param keyName - Name of the secret key to use. Falls back to `"default"`, then first available.
+* @returns A configured {@link SupabaseClient} with admin (service-role) privileges.
+* @throws {@link EnvError} If `SUPABASE_URL` is missing or the specified secret key is not found.
+*
+* @example
+* ```ts
+* const supabaseAdmin = createAdminClient()
+* const { data } = await supabaseAdmin.from('audit_log').insert({ action: 'user_login' })
+* ```
+*/
 function createAdminClient(env, keyName) {
 	const { data: resolved, error } = resolveEnv(env);
 	if (error) throw error;
@@ -88,6 +186,26 @@ function createAdminClient(env, keyName) {
 
 //#endregion
 //#region src/core/create-context-client.ts
+/**
+* Creates a Supabase client scoped to the caller's context.
+*
+* Configured with a publishable key and (optionally) the caller's JWT,
+* so Row-Level Security policies apply. Session persistence is disabled
+* (stateless, one client per request).
+*
+* @param token - The caller's JWT, or `null` for anonymous access.
+* @param env - Optional environment overrides (passed through to {@link resolveEnv}).
+* @param keyName - Name of the publishable key to use. Falls back to `"default"`, then first available.
+* @returns A configured {@link SupabaseClient} with RLS enforced.
+* @throws {@link EnvError} If `SUPABASE_URL` is missing or the specified publishable key is not found.
+*
+* @example
+* ```ts
+* const { data: auth } = await verifyAuth(request, { allow: 'user' })
+* const supabase = createContextClient(auth.token)
+* const { data } = await supabase.rpc('get_my_items')
+* ```
+*/
 function createContextClient(token, env, keyName) {
 	const { data: resolved, error } = resolveEnv(env);
 	if (error) throw error;
@@ -107,6 +225,28 @@ function createContextClient(token, env, keyName) {
 
 //#endregion
 //#region src/core/extract-credentials.ts
+/**
+* Extracts authentication credentials from an incoming HTTP request.
+*
+* Reads two headers:
+* - `Authorization: Bearer <token>` → extracted as `token`
+* - `apikey: <key>` → extracted as `apikey`
+*
+* This is a pure extraction step — no validation or verification is performed.
+* Pass the result to {@link verifyCredentials} to validate against allowed auth modes.
+*
+* @param request - The incoming HTTP request.
+* @returns The extracted {@link Credentials}. Fields are `null` when the corresponding header is absent.
+*
+* @example
+* ```ts
+* import { extractCredentials } from '@supabase/server/core'
+*
+* const creds = extractCredentials(request)
+* console.log(creds.token)  // "eyJhbGci..." or null
+* console.log(creds.apikey) // "sb-abc123-publishable-..." or null
+* ```
+*/
 function extractCredentials(request) {
 	const authHeader = request.headers.get("authorization");
 	return {
@@ -118,6 +258,12 @@ function extractCredentials(request) {
 //#endregion
 //#region src/core/utils/timing-safe-equal.ts
 const encoder = new TextEncoder();
+/**
+* Compares two strings in constant time to prevent timing attacks.
+* Uses the double-HMAC technique with a random ephemeral key.
+*
+* @internal
+*/
 async function timingSafeEqual(a, b) {
 	const key = crypto.getRandomValues(new Uint8Array(32));
 	const cryptoKey = await crypto.subtle.importKey("raw", key, {
@@ -135,6 +281,18 @@ async function timingSafeEqual(a, b) {
 
 //#endregion
 //#region src/core/verify-credentials.ts
+/**
+* Parses an {@link AllowWithKey} string into its base mode and optional key name.
+*
+* @example
+* ```
+* parseAllowMode('user')         → { base: 'user',   keyName: null }
+* parseAllowMode('public:web')   → { base: 'public', keyName: 'web' }
+* parseAllowMode('secret:*')     → { base: 'secret', keyName: '*' }
+* ```
+*
+* @internal
+*/
 function parseAllowMode(mode) {
 	if (mode === "always" || mode === "public" || mode === "secret" || mode === "user") return {
 		base: mode,
@@ -152,6 +310,10 @@ function parseAllowMode(mode) {
 		keyName
 	};
 }
+/**
+* Converts raw {@link JWTClaims} (snake_case) to a normalized {@link UserClaims} (camelCase).
+* @internal
+*/
 function claimsToUserClaims(claims) {
 	return {
 		id: claims.sub,
@@ -161,6 +323,11 @@ function claimsToUserClaims(claims) {
 		userMetadata: claims.user_metadata
 	};
 }
+/**
+* Attempts to authenticate credentials against a single auth mode.
+* Returns the {@link AuthResult} on success, or `null` if the mode doesn't match.
+* @internal
+*/
 async function tryMode(mode, credentials, env) {
 	const { base, keyName } = parseAllowMode(mode);
 	switch (base) {
@@ -240,6 +407,27 @@ async function tryMode(mode, credentials, env) {
 		default: return null;
 	}
 }
+/**
+* Verifies pre-extracted credentials against one or more allowed auth modes.
+*
+* Tries each mode in order — first match wins. Use {@link verifyAuth} to extract
+* and verify in a single call.
+*
+* @param credentials - The credentials to verify (from {@link extractCredentials}).
+* @param options - Allowed auth modes and optional env overrides.
+* @returns `{ data: AuthResult, error: null }` on success, `{ data: null, error: AuthError }` on failure.
+*
+* @example
+* ```ts
+* const credentials = extractCredentials(request)
+* const { data: auth, error } = await verifyCredentials(credentials, {
+*   allow: ['user', 'public'],
+* })
+* if (error) {
+*   return Response.json({ error: error.message }, { status: error.status })
+* }
+* ```
+*/
 async function verifyCredentials(credentials, options) {
 	const { data: env, error: envError } = resolveEnv(options.env);
 	if (envError) return {
@@ -262,6 +450,35 @@ async function verifyCredentials(credentials, options) {
 
 //#endregion
 //#region src/core/verify-auth.ts
+/**
+* Extracts credentials from a request and verifies them in a single step.
+*
+* This is a convenience function that combines {@link extractCredentials} and
+* {@link verifyCredentials}. Use it when you want the full auth flow without
+* needing to inspect the raw credentials.
+*
+* @param request - The incoming HTTP request.
+* @param options - Auth modes to accept and optional environment overrides.
+*
+* @returns A result tuple: `{ data, error }`.
+*   - On success: `{ data: AuthResult, error: null }`
+*   - On failure: `{ data: null, error: AuthError }`
+*
+* @example
+* ```ts
+* import { verifyAuth } from '@supabase/server/core'
+*
+* const { data: auth, error } = await verifyAuth(request, {
+*   allow: 'user',
+* })
+*
+* if (error) {
+*   return Response.json({ error: error.message }, { status: error.status })
+* }
+*
+* console.log(auth.userClaims!.id) // "d0f1a2b3-..."
+* ```
+*/
 async function verifyAuth(request, options) {
 	return verifyCredentials(extractCredentials(request), options);
 }

package/dist/{verify-auth-6a1UPrFz.cjs → verify-auth-DvRVnjdq.cjs}

@@ -2,6 +2,26 @@ let _supabase_supabase_js = require("@supabase/supabase-js");
 let jose = require("jose");
 
 //#region src/errors.ts
+/**
+* Thrown when a required environment variable is missing or malformed.
+*
+* Has a fixed `status` of `500` since environment errors are server-side
+* configuration issues, not client errors.
+*
+* @example
+* ```ts
+* import { EnvError } from '@supabase/server'
+*
+* try {
+*   const client = createAdminClient()
+* } catch (e) {
+*   if (e instanceof EnvError) {
+*     console.error(`Config issue [${e.code}]: ${e.message}`)
+*     // → "Config issue [MISSING_SUPABASE_URL]: SUPABASE_URL is required but not set"
+*   }
+* }
+* ```
+*/
 var EnvError = class extends Error {
 	constructor(message, code = "ENV_ERROR") {
 		super(message);
@@ -10,6 +30,26 @@ var EnvError = class extends Error {
 		this.code = code;
 	}
 };
+/**
+* Thrown when authentication or authorization fails.
+*
+* Carries an HTTP `status` code suitable for returning directly in a response
+* (typically `401` for invalid credentials, `500` for server-side auth failures).
+*
+* @example
+* ```ts
+* import { AuthError, createSupabaseContext } from '@supabase/server'
+*
+* const { data: ctx, error } = await createSupabaseContext(request, { allow: 'user' })
+* if (error) {
+*   // error is an AuthError
+*   return Response.json(
+*     { error: error.message, code: error.code },
+*     { status: error.status },
+*   )
+* }
+* ```
+*/
 var AuthError = class extends Error {
 	constructor(message, code = "AUTH_ERROR", status = 401) {
 		super(message);
@@ -21,10 +61,20 @@ var AuthError = class extends Error {
 
 //#endregion
 //#region src/core/resolve-env.ts
+/**
+* Reads an environment variable from the current runtime (Deno, Node.js, or Bun).
+* Cloudflare Workers require node-compat or passing values via `overrides`.
+* @internal
+*/
 function getEnvVar(name) {
 	if (typeof Deno !== "undefined" && Deno.env?.get) return Deno.env.get(name);
 	if (typeof process !== "undefined" && process.env) return process.env[name];
 }
+/**
+* Parses a JSON string into a `Record<string, string>` key map.
+* Returns an empty object if the input is missing, malformed, or not a plain object.
+* @internal
+*/
 function parseKeys(raw) {
 	if (!raw) return {};
 	try {
@@ -35,6 +85,12 @@ function parseKeys(raw) {
 		return {};
 	}
 }
+/**
+* Resolves API keys from environment variables. Checks the plural form first
+* (`SUPABASE_PUBLISHABLE_KEYS` as JSON), then falls back to the singular form
+* (`SUPABASE_PUBLISHABLE_KEY` stored as `{ default: "<value>" }`).
+* @internal
+*/
 function resolveKeys(singularVar, pluralVar) {
 	const plural = getEnvVar(pluralVar);
 	if (plural) return parseKeys(plural);
@@ -42,6 +98,12 @@ function resolveKeys(singularVar, pluralVar) {
 	if (singular) return { default: singular };
 	return {};
 }
+/**
+* Parses a JWKS JSON string into a {@link JsonWebKeySet}.
+* Accepts both `{ keys: [...] }` and bare `[...]` array formats.
+* Returns `null` if the input is missing or malformed.
+* @internal
+*/
 function parseJwks(raw) {
 	if (!raw) return null;
 	try {
@@ -53,6 +115,25 @@ function parseJwks(raw) {
 		return null;
 	}
 }
+/**
+* Resolves Supabase environment configuration from runtime environment variables.
+*
+* Reads `SUPABASE_URL`, keys (`SUPABASE_PUBLISHABLE_KEYS` / `SUPABASE_SECRET_KEYS`),
+* and `SUPABASE_JWKS`. Works across Deno, Node.js, and Bun. For Cloudflare Workers,
+* use `overrides` or enable node-compat.
+*
+* @param overrides - Partial values that take precedence over env vars.
+* @returns `{ data: SupabaseEnv, error: null }` on success, `{ data: null, error: EnvError }` on failure.
+*
+* @example
+* ```ts
+* const { data: env, error } = resolveEnv()
+* if (error) throw error
+*
+* // Override for tests
+* const { data: env } = resolveEnv({ url: 'http://localhost:54321' })
+* ```
+*/
 function resolveEnv(overrides) {
 	const url = overrides?.url ?? getEnvVar("SUPABASE_URL");
 	if (!url) return {
@@ -72,6 +153,23 @@ function resolveEnv(overrides) {
 
 //#endregion
 //#region src/core/create-admin-client.ts
+/**
+* Creates an admin Supabase client that bypasses Row-Level Security.
+*
+* Uses a secret key for authentication, giving full access to all data.
+* Session persistence is disabled (stateless, one client per request).
+*
+* @param env - Optional environment overrides (passed through to {@link resolveEnv}).
+* @param keyName - Name of the secret key to use. Falls back to `"default"`, then first available.
+* @returns A configured {@link SupabaseClient} with admin (service-role) privileges.
+* @throws {@link EnvError} If `SUPABASE_URL` is missing or the specified secret key is not found.
+*
+* @example
+* ```ts
+* const supabaseAdmin = createAdminClient()
+* const { data } = await supabaseAdmin.from('audit_log').insert({ action: 'user_login' })
+* ```
+*/
 function createAdminClient(env, keyName) {
 	const { data: resolved, error } = resolveEnv(env);
 	if (error) throw error;
@@ -88,6 +186,26 @@ function createAdminClient(env, keyName) {
 
 //#endregion
 //#region src/core/create-context-client.ts
+/**
+* Creates a Supabase client scoped to the caller's context.
+*
+* Configured with a publishable key and (optionally) the caller's JWT,
+* so Row-Level Security policies apply. Session persistence is disabled
+* (stateless, one client per request).
+*
+* @param token - The caller's JWT, or `null` for anonymous access.
+* @param env - Optional environment overrides (passed through to {@link resolveEnv}).
+* @param keyName - Name of the publishable key to use. Falls back to `"default"`, then first available.
+* @returns A configured {@link SupabaseClient} with RLS enforced.
+* @throws {@link EnvError} If `SUPABASE_URL` is missing or the specified publishable key is not found.
+*
+* @example
+* ```ts
+* const { data: auth } = await verifyAuth(request, { allow: 'user' })
+* const supabase = createContextClient(auth.token)
+* const { data } = await supabase.rpc('get_my_items')
+* ```
+*/
 function createContextClient(token, env, keyName) {
 	const { data: resolved, error } = resolveEnv(env);
 	if (error) throw error;
@@ -107,6 +225,28 @@ function createContextClient(token, env, keyName) {
 
 //#endregion
 //#region src/core/extract-credentials.ts
+/**
+* Extracts authentication credentials from an incoming HTTP request.
+*
+* Reads two headers:
+* - `Authorization: Bearer <token>` → extracted as `token`
+* - `apikey: <key>` → extracted as `apikey`
+*
+* This is a pure extraction step — no validation or verification is performed.
+* Pass the result to {@link verifyCredentials} to validate against allowed auth modes.
+*
+* @param request - The incoming HTTP request.
+* @returns The extracted {@link Credentials}. Fields are `null` when the corresponding header is absent.
+*
+* @example
+* ```ts
+* import { extractCredentials } from '@supabase/server/core'
+*
+* const creds = extractCredentials(request)
+* console.log(creds.token)  // "eyJhbGci..." or null
+* console.log(creds.apikey) // "sb-abc123-publishable-..." or null
+* ```
+*/
 function extractCredentials(request) {
 	const authHeader = request.headers.get("authorization");
 	return {
@@ -118,6 +258,12 @@ function extractCredentials(request) {
 //#endregion
 //#region src/core/utils/timing-safe-equal.ts
 const encoder = new TextEncoder();
+/**
+* Compares two strings in constant time to prevent timing attacks.
+* Uses the double-HMAC technique with a random ephemeral key.
+*
+* @internal
+*/
 async function timingSafeEqual(a, b) {
 	const key = crypto.getRandomValues(new Uint8Array(32));
 	const cryptoKey = await crypto.subtle.importKey("raw", key, {
@@ -135,6 +281,18 @@ async function timingSafeEqual(a, b) {
 
 //#endregion
 //#region src/core/verify-credentials.ts
+/**
+* Parses an {@link AllowWithKey} string into its base mode and optional key name.
+*
+* @example
+* ```
+* parseAllowMode('user')         → { base: 'user',   keyName: null }
+* parseAllowMode('public:web')   → { base: 'public', keyName: 'web' }
+* parseAllowMode('secret:*')     → { base: 'secret', keyName: '*' }
+* ```
+*
+* @internal
+*/
 function parseAllowMode(mode) {
 	if (mode === "always" || mode === "public" || mode === "secret" || mode === "user") return {
 		base: mode,
@@ -152,6 +310,10 @@ function parseAllowMode(mode) {
 		keyName
 	};
 }
+/**
+* Converts raw {@link JWTClaims} (snake_case) to a normalized {@link UserClaims} (camelCase).
+* @internal
+*/
 function claimsToUserClaims(claims) {
 	return {
 		id: claims.sub,
@@ -161,6 +323,11 @@ function claimsToUserClaims(claims) {
 		userMetadata: claims.user_metadata
 	};
 }
+/**
+* Attempts to authenticate credentials against a single auth mode.
+* Returns the {@link AuthResult} on success, or `null` if the mode doesn't match.
+* @internal
+*/
 async function tryMode(mode, credentials, env) {
 	const { base, keyName } = parseAllowMode(mode);
 	switch (base) {
@@ -240,6 +407,27 @@ async function tryMode(mode, credentials, env) {
 		default: return null;
 	}
 }
+/**
+* Verifies pre-extracted credentials against one or more allowed auth modes.
+*
+* Tries each mode in order — first match wins. Use {@link verifyAuth} to extract
+* and verify in a single call.
+*
+* @param credentials - The credentials to verify (from {@link extractCredentials}).
+* @param options - Allowed auth modes and optional env overrides.
+* @returns `{ data: AuthResult, error: null }` on success, `{ data: null, error: AuthError }` on failure.
+*
+* @example
+* ```ts
+* const credentials = extractCredentials(request)
+* const { data: auth, error } = await verifyCredentials(credentials, {
+*   allow: ['user', 'public'],
+* })
+* if (error) {
+*   return Response.json({ error: error.message }, { status: error.status })
+* }
+* ```
+*/
 async function verifyCredentials(credentials, options) {
 	const { data: env, error: envError } = resolveEnv(options.env);
 	if (envError) return {
@@ -262,6 +450,35 @@ async function verifyCredentials(credentials, options) {
 
 //#endregion
 //#region src/core/verify-auth.ts
+/**
+* Extracts credentials from a request and verifies them in a single step.
+*
+* This is a convenience function that combines {@link extractCredentials} and
+* {@link verifyCredentials}. Use it when you want the full auth flow without
+* needing to inspect the raw credentials.
+*
+* @param request - The incoming HTTP request.
+* @param options - Auth modes to accept and optional environment overrides.
+*
+* @returns A result tuple: `{ data, error }`.
+*   - On success: `{ data: AuthResult, error: null }`
+*   - On failure: `{ data: null, error: AuthError }`
+*
+* @example
+* ```ts
+* import { verifyAuth } from '@supabase/server/core'
+*
+* const { data: auth, error } = await verifyAuth(request, {
+*   allow: 'user',
+* })
+*
+* if (error) {
+*   return Response.json({ error: error.message }, { status: error.status })
+* }
+*
+* console.log(auth.userClaims!.id) // "d0f1a2b3-..."
+* ```
+*/
 async function verifyAuth(request, options) {
 	return verifyCredentials(extractCredentials(request), options);
 }

package/dist/wrappers/index.cjs

@@ -2,6 +2,25 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 //#region src/wrappers/webhook.ts
 const encoder = new TextEncoder();
+/**
+* Verifies a webhook signature using HMAC-SHA256 with timing-safe comparison.
+*
+* @param payload - The raw request body as a string.
+* @param signature - The hex-encoded signature from the webhook header.
+* @param secret - The shared secret used to sign webhooks.
+* @returns `true` if the signature is valid, `false` otherwise.
+*
+* @example
+* ```ts
+* const payload = await req.text()
+* const signature = req.headers.get('x-webhook-signature') ?? ''
+*
+* const isValid = await verifyWebhookSignature(payload, signature, secret)
+* if (!isValid) {
+*   return Response.json({ error: 'Invalid signature' }, { status: 401 })
+* }
+* ```
+*/
 async function verifyWebhookSignature(payload, signature, secret) {
 	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
 		name: "HMAC",

package/dist/wrappers/index.d.cts

@@ -1,4 +1,23 @@
 //#region src/wrappers/webhook.d.ts
+/**
+ * Verifies a webhook signature using HMAC-SHA256 with timing-safe comparison.
+ *
+ * @param payload - The raw request body as a string.
+ * @param signature - The hex-encoded signature from the webhook header.
+ * @param secret - The shared secret used to sign webhooks.
+ * @returns `true` if the signature is valid, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * const payload = await req.text()
+ * const signature = req.headers.get('x-webhook-signature') ?? ''
+ *
+ * const isValid = await verifyWebhookSignature(payload, signature, secret)
+ * if (!isValid) {
+ *   return Response.json({ error: 'Invalid signature' }, { status: 401 })
+ * }
+ * ```
+ */
 declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
 //#endregion
 export { verifyWebhookSignature };