eve/dist/src/public/channels/twilio/verify.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

/**
 * Twilio inbound-webhook verification.
 *
 * Twilio signs webhook requests with `X-Twilio-Signature`. For form
 * posts, the signed payload is the exact public URL Twilio called plus
 * every POST parameter sorted by name and appended as `name + value`.
 */
/** Auth token, materialized either directly or from an async secret provider. */
export type TwilioAuthToken = string | (() => string | Promise<string>);
/** Public URL resolver used when the runtime request URL differs from Twilio's configured URL. */
export type TwilioWebhookUrl = string | ((request: Request) => string | Promise<string>);
/**
 * Parsed and verified Twilio webhook body.
 *
 * `params` contains every form parameter Twilio sent. Signature
 * validation happens before the channel reads any business fields.
 */
export interface TwilioVerifiedRequest {
    readonly body: string;
    readonly params: URLSearchParams;
}
/** Options for {@link verifyTwilioRequest}. */
export interface TwilioVerifyOptions {
    /** Auth token used to verify the signature. When undefined, falls back to `TWILIO_AUTH_TOKEN`. */
    readonly authToken: TwilioAuthToken | undefined;
    /** Public URL Twilio signed. Defaults to `request.url`; set this when a proxy or tunnel rewrites the URL. */
    readonly webhookUrl?: TwilioWebhookUrl;
}
/** Resolves a Twilio auth token, falling back to `TWILIO_AUTH_TOKEN`. */
export declare function resolveTwilioAuthToken(authToken?: TwilioAuthToken): Promise<string>;
/**
 * Verifies an inbound Twilio webhook and returns the raw body plus parsed form params.
 *
 * Consumes the request body, so the passed `Request` cannot be re-read afterward.
 * The signed URL comes from `options.webhookUrl` (falling back to `request.url`).
 * Set `webhookUrl` when a proxy or tunnel rewrites the URL. A rewritten URL causes
 * the signed payload to differ, so the signature check fails.
 *
 * Throws when the auth token is missing, the `X-Twilio-Signature` header is absent,
 * or the computed signature does not match.
 */
export declare function verifyTwilioRequest(request: Request, options: TwilioVerifyOptions): Promise<TwilioVerifiedRequest>;
/** Computes Twilio's HMAC-SHA1 request signature. */
export declare function signTwilioRequest(input: {
    readonly authToken: string;
    readonly url: string;
    readonly params: URLSearchParams;
}): string;
/** Builds the string Twilio signs for a form POST webhook. */
export declare function buildTwilioSignatureBase(url: string, params: URLSearchParams): string;