@flintpay/node 5.1.0 → 6.0.0

package/runtime-plan.js

@@ -34,6 +34,56 @@ export function isDefaultBaseUrl(value) {
         return false;
     }
 }
+/** One owner for configuration diagnostics and restored Node descriptor validation. */
+export function webhookJwtIssue(value) {
+    const issue = (field, message) => ({ field, message });
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return issue('', 'expected a JWT signing object');
+    const j = Object.fromEntries(Object.entries(value));
+    const fields = [
+        'header',
+        'scheme',
+        'algorithm',
+        'typ',
+        'issuer',
+        'jwksPath',
+        'bodyHashClaim',
+        'bodyHashEncoding',
+        'lifetimeSeconds',
+        'leewaySeconds',
+    ];
+    for (const key of Object.keys(j))
+        if (!fields.includes(key))
+            return issue(key, 'unknown JWT setting');
+    if (typeof j.header !== 'string' || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(j.header))
+        return issue('header', 'expected an HTTP header name');
+    if (j.algorithm !== 'ES256')
+        return issue('algorithm', 'unsupported JWT algorithm ' + String(j.algorithm) + '; expected ES256');
+    if (j.scheme !== 'Bearer')
+        return issue('scheme', 'expected Bearer');
+    for (const name of ['typ', 'bodyHashClaim'])
+        if (typeof j[name] !== 'string' || !j[name] || /[\s\x00-\x1f\x7f]/.test(j[name]))
+            return issue(name, 'expected a nonempty token');
+    if (j.issuer !== 'baseUrl' && (!isDefaultBaseUrl(j.issuer) || !/^https:/i.test(j.issuer)))
+        return issue('issuer', 'expected baseUrl or a literal HTTPS URL without credentials, query or fragment');
+    if (typeof j.jwksPath !== 'string' ||
+        !/^\/(?!\/)[A-Za-z0-9/._~-]+$/.test(j.jwksPath) ||
+        j.jwksPath.split('/').some((part) => part === '.' || part === '..'))
+        return issue('jwksPath', 'expected an absolute path on the trusted issuer');
+    if (j.bodyHashEncoding !== 'base64url')
+        return issue('bodyHashEncoding', 'expected base64url');
+    if (typeof j.lifetimeSeconds !== 'number' ||
+        !Number.isInteger(j.lifetimeSeconds) ||
+        j.lifetimeSeconds < 1 ||
+        j.lifetimeSeconds > 3600)
+        return issue('lifetimeSeconds', 'expected an integer from 1 to 3600');
+    if (typeof j.leewaySeconds !== 'number' ||
+        !Number.isInteger(j.leewaySeconds) ||
+        j.leewaySeconds < 0 ||
+        j.leewaySeconds > 60)
+        return issue('leewaySeconds', 'expected an integer from 0 to 60');
+    return undefined;
+}
 import { compileCodec, assertCodecPlan, CODEC_FORMAT, CODEC_SEMANTICS, } from './codec-plan.js';
 /** Declared success statuses; default remains a runtime fallback, never an implicit redirect. */
 export function successStatus(status) {
@@ -469,6 +519,12 @@ export function assertRuntimePlan(value, historical = false) {
     if (plan.definitions !== undefined)
         for (const [name, codec] of Object.entries(record(plan.definitions, 'definitions')))
             assertCodecPlan(codec, 'definitions.' + name);
+    if (plan.webhook !== undefined) {
+        const jwt = record(plan.webhook, 'webhook').jwt;
+        const issue = jwt === undefined ? undefined : webhookJwtIssue(jwt);
+        if (issue)
+            throw new Error('webhook.jwt.' + issue.field + ': ' + issue.message);
+    }
     if (plan.webhook !== undefined && record(plan.webhook, 'webhook').certificate !== undefined)
         assertTypeCertificate(record(plan.webhook, 'webhook').certificate);
     if (plan.webhook !== undefined)

package/runtime.d.ts

@@ -309,6 +309,20 @@ export type WebhookVerification = {
     event: unknown;
     reason: 'unknown_event' | 'unmatched_envelope';
 };
+export interface WebhookVerificationOptions {
+    endpointIds?: string | string[];
+    secrets?: string | string[];
+    jwks?: {
+        keys: object[];
+    };
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    nowSeconds?: number;
+}
+/** JWT takes precedence whenever the caller supplies endpoint IDs and a bearer token. */
+export declare function verifyWebhookAsyncFromPlan(source: DescriptorSource | CompiledRuntimePlan, rawBody: Uint8Array | ArrayBuffer, headers: WebhookHeaders, options: WebhookVerificationOptions, redactFields?: string[]): Promise<WebhookVerification & {
+    signingMethod: 'jwt' | 'hmac';
+}>;
 /** Verify compiled webhook descriptors without constructing an HTTP runtime. */
 export declare function verifyWebhookFromPlan(source: DescriptorSource | CompiledRuntimePlan, rawBody: Uint8Array | ArrayBuffer, headers: WebhookHeaders, secrets: string | readonly string[], nowSeconds?: number, redactFields?: string[]): WebhookVerification;
 declare class CompiledRuntime {
@@ -339,6 +353,9 @@ declare class CompiledRuntime {
     items<T = unknown>(id: string, input?: Record<string, unknown>, options?: RequestOptions): AsyncGenerator<T>;
     wait<T = unknown>(id: string, input: Record<string, unknown>, options?: RequestOptions): Promise<Result<T>>;
     verifyWebhook(rawBody: Uint8Array | ArrayBuffer, headers: WebhookHeaders, secrets: string | readonly string[], nowSeconds?: number): WebhookVerification;
+    verifyWebhookAsync(rawBody: Uint8Array | ArrayBuffer, headers: WebhookHeaders, options: WebhookVerificationOptions): Promise<WebhookVerification & {
+        signingMethod: 'jwt' | 'hmac';
+    }>;
     money(currency: string, major: string): {
         currency: string;
         amount: string;

package/runtime.js

@@ -163,7 +163,7 @@ export function createSdkError(...args) {
 const webhookError = (kind, code, message) => {
     throw createSdkError(kind, message, 'not_sent', false, undefined, 'webhook_' + code);
 };
-function webhookHeaderValues(headers, name) {
+function webhookHeaderValues(headers, name, optional = false) {
     if (!headers || typeof headers !== 'object' || Array.isArray(headers))
         return webhookError('validation', 'invalid_input', 'Webhook headers must be Headers or a header record');
     const values = [];
@@ -176,8 +176,11 @@ function webhookHeaderValues(headers, name) {
             return webhookError('validation', 'invalid_input', 'Webhook signing header values must be strings');
         values.push(...parts);
     }
-    if (!values.length || values.every((value) => !value.trim()))
+    if (!values.length || values.every((value) => !value.trim())) {
+        if (optional)
+            return [];
         return webhookError('authentication', 'missing_header', 'Missing webhook signing header: ' + name);
+    }
     return values;
 }
 function webhookScalarHeader(headers, name, timestamp = false) {
@@ -2294,15 +2297,381 @@ function destinationUrl(value, base) {
         throw createSdkError('destination', 'Invalid destination URL');
     }
 }
-/** Verify compiled webhook descriptors without constructing an HTTP runtime. */
-export function verifyWebhookFromPlan(source, rawBody, headers, secrets, nowSeconds = Date.now() / 1000, redactFields = []) {
-    const decode = (value, codec, context) => executeCodec(value, codec, {
-        ...context,
-        definitions: source instanceof DescriptorSource ? source.definitions() : (source.definitions ?? {}),
+const webhookKeySets = new Map();
+const webhookKeyFlights = new Map();
+const webhookKeyAttempts = new Map();
+// After a failed refresh while serving stale keys, wait before blocking requests again.
+const webhookKeyRetryAfter = new Map();
+const webhookRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const webhookKeysUnavailable = () => {
+    throw createSdkError('transport', 'Webhook JWKS unavailable; respond with 5xx so delivery can retry', 'not_sent', false, undefined, 'webhook_jwks_unavailable');
+};
+function webhookBase64url(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/.test(value))
+        return undefined;
+    const bytes = Buffer.from(value, 'base64url');
+    return bytes.toString('base64url') === value ? bytes : undefined;
+}
+/** Index just past the JSON string literal starting at `start` in already-valid JSON. */
+function webhookJsonStringEnd(text, start) {
+    let index = start + 1;
+    while (text[index] !== '"')
+        index += text[index] === '\\' ? 2 : 1;
+    return index + 1;
+}
+/** Raw text of each direct member or element of the outer container of already-valid JSON. */
+function webhookJsonItems(text) {
+    const items = [];
+    let depth = 0;
+    let start = 0;
+    for (let index = 0; index < text.length; index++) {
+        const char = text[index];
+        if (char === '"')
+            index = webhookJsonStringEnd(text, index) - 1;
+        else if (char === '{' || char === '[') {
+            if (depth++ === 0)
+                start = index + 1;
+        }
+        else if ((char === ',' && depth === 1) || ((char === '}' || char === ']') && --depth === 0)) {
+            const item = text.slice(start, index).trim();
+            if (item)
+                items.push(item);
+            start = index + 1;
+        }
+    }
+    return items;
+}
+/** One JSON object with unique direct member names, mapped to raw member text. */
+function webhookJsonObject(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!webhookRecord(value))
+        return undefined;
+    const members = new Map();
+    for (const item of webhookJsonItems(text)) {
+        const end = webhookJsonStringEnd(item, 0);
+        const name = JSON.parse(item.slice(0, end));
+        if (typeof name !== 'string' || members.has(name))
+            return undefined;
+        members.set(name, item.slice(item.indexOf(':', end) + 1).trim());
+    }
+    return members;
+}
+const webhookJsonString = (members, name) => {
+    const raw = members.get(name);
+    const value = raw?.startsWith('"') ? JSON.parse(raw) : undefined;
+    return typeof value === 'string' ? value : undefined;
+};
+const webhookJsonInteger = (members, name) => {
+    const raw = members.get(name);
+    if (raw === undefined || !/^-?(?:0|[1-9][0-9]*)$/.test(raw))
+        return undefined;
+    const value = Number(raw);
+    return Number.isSafeInteger(value) ? value : undefined;
+};
+/** Validate a JWKS document's shape: unique members, a keys array, and a string kid per key. */
+function webhookJwks(text) {
+    const raw = webhookJsonObject(text)?.get('keys');
+    if (!raw?.startsWith('['))
+        throw new Error('Invalid JWKS');
+    return webhookJsonItems(raw).map((item) => {
+        const members = webhookJsonObject(item);
+        const kid = members && webhookJsonString(members, 'kid');
+        if (!members || kid === undefined)
+            throw new Error('Invalid JWK');
+        return { kid, members };
     });
+}
+/**
+ * Select the key for kid; other keys, including unsupported key types, are ignored. A duplicate
+ * kid makes the trusted set ambiguous; a unique but unusable key fails only the token naming it.
+ */
+async function webhookSelectKey(keys, kid) {
+    const matches = keys.filter((key) => key.kid === kid);
+    const key = matches[0]?.members;
+    if (!key)
+        return 'unknown';
+    if (matches.length !== 1)
+        return 'duplicate';
+    const x = webhookJsonString(key, 'x');
+    const y = webhookJsonString(key, 'y');
+    if (x === undefined ||
+        y === undefined ||
+        webhookJsonString(key, 'kty') !== 'EC' ||
+        webhookJsonString(key, 'crv') !== 'P-256' ||
+        webhookBase64url(x)?.length !== 32 ||
+        webhookBase64url(y)?.length !== 32 ||
+        (key.has('alg') && webhookJsonString(key, 'alg') !== 'ES256') ||
+        (key.has('use') && webhookJsonString(key, 'use') !== 'sig'))
+        return 'unusable';
+    try {
+        return await crypto.subtle.importKey('jwk', { kty: 'EC', crv: 'P-256', x, y }, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']);
+    }
+    catch {
+        return 'unusable';
+    }
+}
+async function webhookFetchKeys(url, transport) {
+    const active = webhookKeyFlights.get(url);
+    if (active)
+        return active;
+    const flight = (async () => {
+        // Publish the flight before invoking a caller-owned transport, which can reenter.
+        await Promise.resolve();
+        const controller = new AbortController();
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                reject(new Error('JWKS timeout'));
+            }, 5000);
+        });
+        const work = (async () => {
+            const response = await transport(url, {
+                signal: controller.signal,
+                redirect: 'error',
+                credentials: 'omit',
+                headers: { accept: 'application/json' },
+            });
+            if (response.status !== 200 || !response.body)
+                throw new Error('JWKS HTTP failure');
+            const reader = response.body.getReader();
+            const chunks = [];
+            let length = 0;
+            try {
+                for (;;) {
+                    const chunk = await reader.read();
+                    if (chunk.done)
+                        break;
+                    length += chunk.value.byteLength;
+                    if (length > 256 * 1024)
+                        throw new Error('JWKS response too large');
+                    chunks.push(chunk.value);
+                }
+            }
+            finally {
+                void reader.cancel().catch(() => { });
+            }
+            const keys = webhookJwks(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks)));
+            const match = /(?:^|,)\s*max-age\s*=\s*"?(\d+)"?(?=\s*(?:,|$))/i.exec(response.headers.get('cache-control') ?? '');
+            const ttl = match ? Math.min(86400, Math.max(300, Number(match[1]))) : 900;
+            const fetchedAt = Date.now() / 1000;
+            return { keys, fetchedAt, expiresAt: fetchedAt + ttl };
+        })();
+        try {
+            const entry = await Promise.race([work, timeout]);
+            webhookKeySets.set(url, entry);
+            webhookKeyRetryAfter.delete(url);
+            return entry;
+        }
+        catch {
+            const previous = webhookKeySets.get(url);
+            const now = Date.now() / 1000;
+            if (!previous || now - previous.fetchedAt > 86400)
+                return webhookKeysUnavailable();
+            webhookKeyRetryAfter.set(url, now + 60);
+            return previous;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            controller.abort();
+        }
+    })();
+    webhookKeyFlights.set(url, flight);
+    webhookKeyAttempts.set(url, Date.now() / 1000);
+    try {
+        return await flight;
+    }
+    finally {
+        webhookKeyFlights.delete(url);
+    }
+}
+async function webhookJwtKey(url, kid, options) {
+    let key;
+    if (options.jwks !== undefined) {
+        const invalidJwks = () => webhookError('validation', 'invalid_input', 'Webhook jwks must be a JWKS object with a string kid on every key and unique key IDs');
+        let keys;
+        try {
+            keys = webhookJwks(JSON.stringify(options.jwks));
+        }
+        catch {
+            return invalidJwks();
+        }
+        key = await webhookSelectKey(keys, kid);
+        if (key === 'duplicate')
+            return invalidJwks();
+    }
+    else {
+        const transport = options.fetch ?? fetch;
+        let entry = webhookKeySets.get(url);
+        const active = webhookKeyFlights.get(url);
+        const now = Date.now() / 1000;
+        if (active)
+            entry = await active;
+        else if (!entry ||
+            (entry.expiresAt <= now &&
+                (now >= (webhookKeyRetryAfter.get(url) ?? 0) || now - entry.fetchedAt > 86400)))
+            entry = await webhookFetchKeys(url, transport);
+        if (!entry.keys.some((key) => key.kid === kid) &&
+            Date.now() / 1000 - (webhookKeyAttempts.get(url) ?? -Infinity) >= 60)
+            entry = await webhookFetchKeys(url, transport);
+        key = await webhookSelectKey(entry.keys, kid);
+        // Like a malformed trusted set, a duplicate kid is a provider fault and retryable.
+        if (key === 'duplicate')
+            return webhookKeysUnavailable();
+    }
+    // A token naming an unusable key is invalid, never an outage, so forged tokens cannot cause 5xx.
+    if (key === 'unusable')
+        return webhookError('authentication', 'invalid_token', 'Invalid webhook JWT');
+    return key === 'unknown'
+        ? webhookError('authentication', 'unknown_key', 'Webhook signing key is unknown')
+        : key;
+}
+/** JWT takes precedence whenever the caller supplies endpoint IDs and a bearer token. */
+export async function verifyWebhookAsyncFromPlan(source, rawBody, headers, options, redactFields = []) {
     const w = source instanceof DescriptorSource ? source.webhook() : source.webhook;
     if (!w)
         return bad('webhook', 'capability is not declared');
+    if (!webhookRecord(options) ||
+        Object.keys(options).some((key) => !['endpointIds', 'secrets', 'jwks', 'baseUrl', 'fetch', 'nowSeconds'].includes(key)))
+        return webhookError('validation', 'invalid_input', 'Supply webhook verification options');
+    const strings = (value) => {
+        const values = typeof value === 'string' ? [value] : Array.isArray(value) ? value : [];
+        if (!values.length ||
+            !values.every((item) => typeof item === 'string' && item.length > 0))
+            return webhookError('validation', 'invalid_input', 'Supply a nonempty string or array of nonempty strings');
+        return values;
+    };
+    const endpointIds = options.endpointIds === undefined ? undefined : strings(options.endpointIds);
+    const secrets = options.secrets === undefined ? undefined : strings(options.secrets);
+    if (!endpointIds && options.secrets === undefined)
+        return webhookError('validation', 'invalid_input', 'Supply endpointIds or secrets');
+    if (options.fetch !== undefined && typeof options.fetch !== 'function')
+        return webhookError('validation', 'invalid_input', 'Webhook fetch must be a function');
+    const now = options.nowSeconds === undefined ? Date.now() / 1000 : options.nowSeconds;
+    if (typeof now !== 'number' || !Number.isFinite(now) || Math.abs(now) >= 100_000_000_000)
+        return webhookError('validation', 'invalid_input', 'Webhook nowSeconds must be finite Unix seconds, not milliseconds');
+    if (rawBody instanceof ArrayBuffer)
+        rawBody = new Uint8Array(rawBody);
+    if (!(rawBody instanceof Uint8Array))
+        return webhookError('validation', 'invalid_input', 'Webhook body must be original Buffer, Uint8Array or ArrayBuffer bytes');
+    // Own the bytes across asynchronous key fetching and signature verification.
+    const body = Buffer.from(rawBody);
+    const authorization = webhookHeaderValues(headers, w.jwt?.header ?? 'authorization', true);
+    const bearer = authorization.some((value) => /(?:^|,)[ \t]*Bearer(?:[ \t]|$)/i.test(value.trim()));
+    if (!bearer || !endpointIds) {
+        if (options.secrets !== undefined &&
+            w.algorithm === 'hmac-sha256' &&
+            w.header &&
+            webhookHeaderValues(headers, w.header, true).length &&
+            (w.format === 'timestamped-hex' ||
+                (w.timestampHeader && webhookHeaderValues(headers, w.timestampHeader, true).length)) &&
+            (w.format !== 'standard-webhooks' ||
+                (w.idHeader && webhookHeaderValues(headers, w.idHeader, true).length)))
+            return {
+                ...verifyWebhookFromPlan(source, body, headers, secrets ?? [], now, redactFields),
+                signingMethod: 'hmac',
+            };
+        return webhookError('authentication', 'missing_header', 'Missing webhook signing headers');
+    }
+    const j = w.jwt;
+    if (!j)
+        return webhookError('validation', 'invalid_input', 'JWT webhook verification is not declared');
+    let issuer;
+    if (j.issuer === 'baseUrl') {
+        if (!isBaseUrlSyntax(options.baseUrl) || !/^https?:/i.test(options.baseUrl))
+            return webhookError('validation', 'invalid_input', 'Supply a trusted API baseUrl for JWT verification');
+        try {
+            issuer = new URL(options.baseUrl).origin;
+        }
+        catch {
+            return webhookError('validation', 'invalid_input', 'Supply a trusted API baseUrl');
+        }
+    }
+    else
+        issuer = j.issuer;
+    const invalid = () => webhookError('authentication', 'invalid_token', 'Invalid webhook JWT');
+    if (authorization.length !== 1)
+        return invalid();
+    const match = /^Bearer ([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/i.exec(authorization[0]?.trim() ?? '');
+    if (!match || !match[1] || match[1].length > 16384)
+        return invalid();
+    const [encodedHeader, encodedClaims, encodedSignature] = match[1].split('.');
+    let jose;
+    let claims;
+    try {
+        const headerBytes = webhookBase64url(encodedHeader);
+        const claimBytes = webhookBase64url(encodedClaims);
+        if (!headerBytes || !claimBytes)
+            return invalid();
+        // Keep a BOM so JSON parsing rejects it, as Go's encoding/json does.
+        const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+        jose = webhookJsonObject(decoder.decode(headerBytes));
+        claims = webhookJsonObject(decoder.decode(claimBytes));
+    }
+    catch {
+        return invalid();
+    }
+    const signature = webhookBase64url(encodedSignature);
+    const kid = jose && webhookJsonString(jose, 'kid');
+    // Header members are exactly alg, kid and typ; claims are typed as in Flint's reference verifier.
+    const jti = claims && webhookJsonString(claims, 'jti');
+    const aud = claims && webhookJsonString(claims, 'aud');
+    const iat = claims && webhookJsonInteger(claims, 'iat');
+    const exp = claims && webhookJsonInteger(claims, 'exp');
+    const bodyHash = claims && webhookJsonString(claims, j.bodyHashClaim);
+    if (!jose ||
+        jose.size !== 3 ||
+        webhookJsonString(jose, 'alg') !== 'ES256' ||
+        webhookJsonString(jose, 'typ') !== j.typ ||
+        !kid ||
+        !signature ||
+        signature.length !== 64 ||
+        !claims ||
+        webhookJsonString(claims, 'iss') !== issuer ||
+        aud === undefined ||
+        iat === undefined ||
+        exp === undefined ||
+        !jti?.trim() ||
+        bodyHash === undefined ||
+        claims.has('sub'))
+        return invalid();
+    const key = await webhookJwtKey(issuer.replace(/\/$/, '') + j.jwksPath, kid, options);
+    try {
+        if (!(await crypto.subtle.verify({ name: 'ECDSA', hash: 'SHA-256' }, key, Uint8Array.from(signature), new TextEncoder().encode(encodedHeader + '.' + encodedClaims))))
+            return invalid();
+    }
+    catch {
+        return invalid();
+    }
+    if (!endpointIds.includes(aud))
+        return webhookError('authentication', 'invalid_audience', 'Webhook JWT audience does not match this endpoint');
+    if (iat <= 0 ||
+        exp <= iat ||
+        exp - iat > Math.min(300, j.lifetimeSeconds) ||
+        iat > now + j.leewaySeconds ||
+        now >= exp + j.leewaySeconds)
+        return webhookError('authentication', 'token_expired', 'Webhook JWT timestamps are outside the permitted lifetime or leeway');
+    const actualHash = webhookBase64url(bodyHash);
+    const { createHash, timingSafeEqual } = process.getBuiltinModule('crypto');
+    const expectedHash = createHash('sha256').update(body).digest();
+    if (!actualHash ||
+        actualHash.length !== expectedHash.length ||
+        !timingSafeEqual(expectedHash, actualHash))
+        return webhookError('authentication', 'body_mismatch', 'Webhook JWT does not match the original body bytes');
+    return { ...decodeWebhookFromPlan(source, body, redactFields), signingMethod: 'jwt' };
+}
+/** Verify compiled webhook descriptors without constructing an HTTP runtime. */
+export function verifyWebhookFromPlan(source, rawBody, headers, secrets, nowSeconds = Date.now() / 1000, redactFields = []) {
+    const w = source instanceof DescriptorSource ? source.webhook() : source.webhook;
+    if (!w || w.algorithm !== 'hmac-sha256' || !w.header || w.toleranceSeconds === undefined)
+        return bad('webhook', 'HMAC capability is not declared');
     if (rawBody instanceof ArrayBuffer)
         rawBody = new Uint8Array(rawBody);
     if (!(rawBody instanceof Uint8Array))
@@ -2385,6 +2754,16 @@ export function verifyWebhookFromPlan(source, rawBody, headers, secrets, nowSeco
     }
     if (!valid)
         return webhookError('authentication', 'invalid_signature', 'Invalid webhook signature; check the signing secret and preserve the original request body bytes without reserializing JSON');
+    return decodeWebhookFromPlan(source, rawBody, redactFields);
+}
+function decodeWebhookFromPlan(source, rawBody, redactFields) {
+    const decode = (value, codec, context) => executeCodec(value, codec, {
+        ...context,
+        definitions: source instanceof DescriptorSource ? source.definitions() : (source.definitions ?? {}),
+    });
+    const w = source instanceof DescriptorSource ? source.webhook() : source.webhook;
+    if (!w)
+        return bad('webhook', 'capability is not declared');
     let event;
     try {
         event = parseJson(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.from(rawBody)), true);
@@ -3287,6 +3666,9 @@ class CompiledRuntime {
     verifyWebhook(rawBody, headers, secrets, nowSeconds) {
         return verifyWebhookFromPlan(this.descriptors ?? this.contract, rawBody, headers, secrets, nowSeconds, this.options.redactFields ?? []);
     }
+    verifyWebhookAsync(rawBody, headers, options) {
+        return verifyWebhookAsyncFromPlan(this.descriptors ?? this.contract, rawBody, headers, { baseUrl: this.base.origin, fetch: this.options.transport ?? fetch, ...options }, this.options.redactFields ?? []);
+    }
     money(currency, major) {
         const currencies = this.contract.money?.currencies;
         const digits = currencies && Object.hasOwn(currencies, currency) ? currencies[currency] : undefined;

package/webhooks.d.ts

@@ -1,5 +1,43 @@
 export { parseExact } from './runtime.js';
-export { verifyWebhook } from './declarations/types-73.js';
+export { verifyWebhook, verifyWebhookAsync } from './declarations/types-73.js';
+export type {
+    WebhookVerificationOptions,
+    WebhookEventReturnDispositionUpdated,
+    WebhookEventReturnInspectionAcceptanceDecided,
+    WebhookEventReturnInspectionCreated,
+    WebhookEventReturnInspectionSuperseded,
+    WebhookEventReturnReceiptCreated,
+    WebhookEventReturnReceiptSuperseded,
+    WebhookEventReturnReceiptVerified,
+    WebhookEventReturnResolutionCreated,
+    WebhookEventReturnResolutionUpdated,
+    WebhookEventReturnReopened,
+    WebhookEventReturnUpdated,
+    WebhookEventShipmentCreated,
+    WebhookEventShipmentUpdated,
+    WebhookEventSubscriptionDeliveryMigrationCompleted,
+    WebhookEventSubscriptionPaymentRetryCreated,
+    WebhookEventSubscriptionPaymentRetryFailed,
+    WebhookEventSubscriptionPaymentRetrySucceeded,
+    WebhookEventSubscriptionActivated,
+    WebhookEventSubscriptionCanceled,
+    WebhookEventSubscriptionCancellationScheduled,
+    WebhookEventSubscriptionCreated,
+    WebhookEventSubscriptionCycleSkipped,
+    WebhookEventSubscriptionDeliveryActionRequired,
+    WebhookEventSubscriptionDeliveryPauseUpcoming,
+    WebhookEventSubscriptionDeliveryUpdated,
+    WebhookEventSubscriptionDunningExhausted,
+    WebhookEventSubscriptionPastDue,
+    WebhookEventSubscriptionPaused,
+    WebhookEventSubscriptionPaymentSucceeded,
+    WebhookEventSubscriptionPlanChanged,
+    WebhookEventSubscriptionReactivated,
+    WebhookEventSubscriptionRenewalUpcoming,
+    WebhookEventSubscriptionResumed,
+    WebhookEventSubscriptionTrialEnding,
+    WebhookEventSubscriptionUpdated
+} from './declarations/types-54.js';
 export type { KnownWebhookEvent } from './declarations/types-28.js';
 export type {
     VerifiedWebhook,
@@ -220,40 +258,3 @@ export type {
     WebhookEventReturnCreated,
     WebhookEventReturnDecisionRecorded
 } from './declarations/types-53.js';
-export type {
-    WebhookEventReturnDispositionUpdated,
-    WebhookEventReturnInspectionAcceptanceDecided,
-    WebhookEventReturnInspectionCreated,
-    WebhookEventReturnInspectionSuperseded,
-    WebhookEventReturnReceiptCreated,
-    WebhookEventReturnReceiptSuperseded,
-    WebhookEventReturnReceiptVerified,
-    WebhookEventReturnResolutionCreated,
-    WebhookEventReturnResolutionUpdated,
-    WebhookEventReturnReopened,
-    WebhookEventReturnUpdated,
-    WebhookEventShipmentCreated,
-    WebhookEventShipmentUpdated,
-    WebhookEventSubscriptionDeliveryMigrationCompleted,
-    WebhookEventSubscriptionPaymentRetryCreated,
-    WebhookEventSubscriptionPaymentRetryFailed,
-    WebhookEventSubscriptionPaymentRetrySucceeded,
-    WebhookEventSubscriptionActivated,
-    WebhookEventSubscriptionCanceled,
-    WebhookEventSubscriptionCancellationScheduled,
-    WebhookEventSubscriptionCreated,
-    WebhookEventSubscriptionCycleSkipped,
-    WebhookEventSubscriptionDeliveryActionRequired,
-    WebhookEventSubscriptionDeliveryPauseUpcoming,
-    WebhookEventSubscriptionDeliveryUpdated,
-    WebhookEventSubscriptionDunningExhausted,
-    WebhookEventSubscriptionPastDue,
-    WebhookEventSubscriptionPaused,
-    WebhookEventSubscriptionPaymentSucceeded,
-    WebhookEventSubscriptionPlanChanged,
-    WebhookEventSubscriptionReactivated,
-    WebhookEventSubscriptionRenewalUpcoming,
-    WebhookEventSubscriptionResumed,
-    WebhookEventSubscriptionTrialEnding,
-    WebhookEventSubscriptionUpdated
-} from './declarations/types-54.js';

package/webhooks.js

@@ -1,9 +1,10 @@
-import { verifyWebhookFromPlan } from './runtime.js';
+import { verifyWebhookFromPlan, verifyWebhookAsyncFromPlan } from './runtime.js';
 export { parseExact } from './runtime.js';
 
 import { DescriptorSource } from './descriptor-source.js';
-import settings from './descriptors/settings.js?sdk=ebff27e81aec9bdd0f095cae8c1add08bcdfa885028bf0eb87e3396a43a44aab';
-import webhook from './descriptors/webhook.js?sdk=ebff27e81aec9bdd0f095cae8c1add08bcdfa885028bf0eb87e3396a43a44aab';
+import settings from './descriptors/settings.js?sdk=fac4b718d892e7da91e9078fbe8a70d0df1d443420d01e46d9daffedbb5651c4';
+import webhook from './descriptors/webhook.js?sdk=fac4b718d892e7da91e9078fbe8a70d0df1d443420d01e46d9daffedbb5651c4';
 const _sdkDescriptors = new DescriptorSource(settings, {}, webhook);
 
 export function verifyWebhook(rawBody, headers, secrets, nowSeconds) { return verifyWebhookFromPlan(_sdkDescriptors, rawBody, headers, secrets, nowSeconds); }
+export function verifyWebhookAsync(rawBody, headers, options) { return verifyWebhookAsyncFromPlan(_sdkDescriptors, rawBody, headers, options); }