@whooshbang/contracts 1.0.0-rc.13

package/dist/generated/whooshbang-v1.js

@@ -0,0 +1,6 @@
+/**
+ * Generated by `npm run contracts:generate`.
+ * Do not edit this file directly.
+ */
+export {};
+//# sourceMappingURL=whooshbang-v1.js.map

package/dist/generated/whooshbang-v1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whooshbang-v1.js","sourceRoot":"","sources":["../../src/generated/whooshbang-v1.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { contractManifest, contractVersion, } from "./generated/artifact-index.js";
+export { createMachineCredentialMaterial, verifyMachineCredentialToken, } from "./machine-credential.js";
+export { DEFAULT_WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS, MAX_WEBHOOK_SECRETS, MAX_WEBHOOK_SIGNATURES, verifyWebhookSignature, } from "./webhook-signature.js";
+export { consumeVerifiedWebhook, MIN_WEBHOOK_DEDUP_RETENTION_SECONDS, } from "./webhook-consumer.js";
+export { classifyWebhookDeliveryOutcome, MAX_WEBHOOK_DELIVERY_ATTEMPTS, MAX_WEBHOOK_DELIVERY_WINDOW_SECONDS, parseWebhookRetryAfter, WEBHOOK_FETCH_REDIRECT_MODE, } from "./webhook-delivery.js";
+export type { MachineCredentialCrypto, MachineCredentialMaterial, MachineCredentialRegistration, MachineCredentialVerificationRecord, } from "./machine-credential.js";
+export type { RejectedWebhookSignature, VerifiedWebhookSignature, VerifyWebhookSignatureOptions, WebhookCrypto, WebhookHeaderEntry, WebhookHeaderRecord, WebhookHeaders, WebhookSignatureVerification, WebhookVerificationFailureReason, } from "./webhook-signature.js";
+export type { ConsumeVerifiedWebhookOptions, DuplicateWebhookConsumption, ProcessedWebhookConsumption, RejectedWebhookConsumption, WebhookConsumptionResult, WebhookConsumerRejectionReason, WebhookDeduplicationInput, WebhookDeduplicationOutcome, WebhookDeduplicationStore, } from "./webhook-consumer.js";
+export type { AcceptedWebhookDelivery, ClassifyWebhookDeliveryOptions, HttpDeliveryOutcome, NetworkFailureOutcome, RetryWebhookDelivery, TerminalWebhookDelivery, WebhookDeliveryClassification, WebhookDeliveryOutcome, WebhookDeliveryRetryReason, WebhookDeliveryTerminalReason, } from "./webhook-delivery.js";
+export { contractValidationErrors, validateAccountProjection, validateApiCredential, validateApiCredentialCollection, validateApiCredentialRotation, validateApiCredentialSecretReveal, validateBindingSummary, validateCreateApiCredentialRequest, validateCreateCustomerEndpointRequest, validateCreateProjectRequest, validateCreateMachineClientRequest, validateCreateMessageRequest, validateCreateSubscriptionLinkRequest, validateDeliveryAttemptSummary, validateCustomerEndpoint, validateCustomerEndpointAttemptCollection, validateCustomerEndpointCollection, validateCustomerEndpointMutationResult, validateCustomerEndpointVerificationChallenge, validateIdempotencyKey, validateAgentBindingDegradedEvent, validateInteractionEvent, validateInteractionExpiredEvent, validateInteractionReceivedEvent, validateInteractionRequest, validateInteractionSummary, validateMachineClient, validateMachineCredential, validateMachineCredentialBearer, validateMachineEventAckRequest, validateMachineEventAckResponse, validateMachineEventPollResponse, validateMessage, validateMessageDeliveredEvent, validateMessageExpiredEvent, validateMessageFailedEvent, validateMessageProviderAcceptedEvent, validateWhooshBangEvent, validateProblem, validateProject, validateProjectCollection, validateProviderCallbackToken, validateProviderCapabilities, validateProviderCapabilitiesCollection, validateRegisterMachineCredentialRequest, validateRotateApiCredentialRequest, validateRotateCustomerEndpointRequest, validateSubscriptionActivatedEvent, validateSubscriptionLink, validateSubscriptionRevokedEvent, validateWebhookDeliveryCaseSet, validateWebhookSigningVectorSet, } from "./generated/validators.js";
+export type { Artifact, ContractManifest, FixtureSet, GeneratedArtifact, } from "./generated/contract-manifest.js";
+export type { AgentBindingDegradedData, AgentBindingDegradedEvent, ConfirmInteractionResponse as CustomerEventConfirmInteractionResponse, InteractionExpiredData, InteractionExpiredEvent, InteractionReceivedData, InteractionReceivedEvent, InteractionResponse as CustomerEventInteractionResponse, MessageDeliveredData, MessageDeliveredEvent, MessageExpiredData, MessageExpiredEvent, MessageFailedData, MessageFailedEvent, MessageProviderAcceptedData, MessageProviderAcceptedEvent, WhooshBangEventV1ContractDocument, SelectInteractionResponse as CustomerEventSelectInteractionResponse, SubscriptionActivatedData, SubscriptionActivatedEvent, SubscriptionRevokedData, SubscriptionRevokedEvent, InputInteractionResponse as CustomerEventInputInteractionResponse, } from "./generated/whooshbang-event-v1.js";
+export type { WebhookDeliveryCaseSetV1, DeliveryCase as WebhookDeliveryFixtureCase, } from "./generated/webhook-delivery-case-v1.js";
+export type { WebhookSigningVectorSetV1, VerificationCase as WebhookSigningVerificationCase, } from "./generated/webhook-signing-vector-v1.js";
+export type { AccountMembershipSummary, AccountProjection, AccountRole, ApiCredential, ApiCredentialCollection, ApiCredentialId, ApiCredentialPrefix, ApiCredentialRotation, ApiCredentialScope, ApiCredentialScopeSet, ApiCredentialSecret, ApiCredentialSecretReveal, BindingSummary, ClassifiedError, CreateApiCredentialRequest, CreateCustomerEndpointRequest, CreateMessageRequest, CreateProjectRequest, DefaultNotifierSummary, CreateSubscriptionLinkRequest, DeliveryAttemptSummary, CustomerEndpoint, CustomerEndpointAttemptCollection, CustomerEndpointAttemptDiagnostic, CustomerEndpointCollection, CustomerEndpointFailure, CustomerEndpointMutationResult, CustomerEndpointSecret, CustomerEndpointStatus, CustomerEndpointVerificationChallenge, CustomerEventType, Environment, IdempotencyKey, Message, MessageState, WhooshBangV1ContractDocument, Problem, ProblemCode, Project, ProjectCollection, ProjectEnvironment, ProviderCapabilitiesCollection, RotateApiCredentialRequest, RotateCustomerEndpointRequest, SubscriptionLink, } from "./generated/whooshbang-v1.js";
+export type { ConfirmInteractionRequest, ConfirmInteractionResponse, InputInteractionRequest, InputInteractionResponse, InteractionEvent, InteractionOption, InteractionRequest, InteractionResponse, InteractionState, InteractionSummary, ProviderCallbackToken, SafeChannelContext, SelectInteractionRequest, SelectInteractionResponse, } from "./generated/interaction-v1.js";
+export type { InteractionMachineScenario } from "./generated/interaction-machine-scenario.js";
+export type { CreateMachineClientRequest, MachineClient, MachineCredential, MachineCredentialBearer, MachineCredentialId, MachineCursor, MachineEventAckDisposition, MachineEventAckRequest, MachineEventAckResponse, MachineEventPollResponse, MachineScope, MachineScopeSummary, MachineSecretDigest, QuarantineReasonCode, RegisterMachineCredentialRequest, } from "./generated/machine-v1.js";
+export type { ContextSupport, Degradation, InteractionCapability, ProviderCapabilitiesV1, } from "./generated/provider-capabilities-v1.js";
+export type { ContractValidationError, ContractValidator, } from "./generated/validators.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { contractManifest, contractVersion, } from "./generated/artifact-index.js";
+export { createMachineCredentialMaterial, verifyMachineCredentialToken, } from "./machine-credential.js";
+export { DEFAULT_WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS, MAX_WEBHOOK_SECRETS, MAX_WEBHOOK_SIGNATURES, verifyWebhookSignature, } from "./webhook-signature.js";
+export { consumeVerifiedWebhook, MIN_WEBHOOK_DEDUP_RETENTION_SECONDS, } from "./webhook-consumer.js";
+export { classifyWebhookDeliveryOutcome, MAX_WEBHOOK_DELIVERY_ATTEMPTS, MAX_WEBHOOK_DELIVERY_WINDOW_SECONDS, parseWebhookRetryAfter, WEBHOOK_FETCH_REDIRECT_MODE, } from "./webhook-delivery.js";
+export { contractValidationErrors, validateAccountProjection, validateApiCredential, validateApiCredentialCollection, validateApiCredentialRotation, validateApiCredentialSecretReveal, validateBindingSummary, validateCreateApiCredentialRequest, validateCreateCustomerEndpointRequest, validateCreateProjectRequest, validateCreateMachineClientRequest, validateCreateMessageRequest, validateCreateSubscriptionLinkRequest, validateDeliveryAttemptSummary, validateCustomerEndpoint, validateCustomerEndpointAttemptCollection, validateCustomerEndpointCollection, validateCustomerEndpointMutationResult, validateCustomerEndpointVerificationChallenge, validateIdempotencyKey, validateAgentBindingDegradedEvent, validateInteractionEvent, validateInteractionExpiredEvent, validateInteractionReceivedEvent, validateInteractionRequest, validateInteractionSummary, validateMachineClient, validateMachineCredential, validateMachineCredentialBearer, validateMachineEventAckRequest, validateMachineEventAckResponse, validateMachineEventPollResponse, validateMessage, validateMessageDeliveredEvent, validateMessageExpiredEvent, validateMessageFailedEvent, validateMessageProviderAcceptedEvent, validateWhooshBangEvent, validateProblem, validateProject, validateProjectCollection, validateProviderCallbackToken, validateProviderCapabilities, validateProviderCapabilitiesCollection, validateRegisterMachineCredentialRequest, validateRotateApiCredentialRequest, validateRotateCustomerEndpointRequest, validateSubscriptionActivatedEvent, validateSubscriptionLink, validateSubscriptionRevokedEvent, validateWebhookDeliveryCaseSet, validateWebhookSigningVectorSet, } from "./generated/validators.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,eAAe,GAChB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,2CAA2C,EAC3C,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,sBAAsB,EACtB,mCAAmC,GACpC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC7B,mCAAmC,EACnC,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC;AAyC/B,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,qBAAqB,EACrB,+BAA+B,EAC/B,6BAA6B,EAC7B,iCAAiC,EACjC,sBAAsB,EACtB,kCAAkC,EAClC,qCAAqC,EACrC,4BAA4B,EAC5B,kCAAkC,EAClC,4BAA4B,EAC5B,qCAAqC,EACrC,8BAA8B,EAC9B,wBAAwB,EACxB,yCAAyC,EACzC,kCAAkC,EAClC,sCAAsC,EACtC,6CAA6C,EAC7C,sBAAsB,EACtB,iCAAiC,EACjC,wBAAwB,EACxB,+BAA+B,EAC/B,gCAAgC,EAChC,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,yBAAyB,EACzB,+BAA+B,EAC/B,8BAA8B,EAC9B,+BAA+B,EAC/B,gCAAgC,EAChC,eAAe,EACf,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,EAC1B,oCAAoC,EACpC,uBAAuB,EACvB,eAAe,EACf,eAAe,EACf,yBAAyB,EACzB,6BAA6B,EAC7B,4BAA4B,EAC5B,sCAAsC,EACtC,wCAAwC,EACxC,kCAAkC,EAClC,qCAAqC,EACrC,kCAAkC,EAClC,wBAAwB,EACxB,gCAAgC,EAChC,8BAA8B,EAC9B,+BAA+B,GAChC,MAAM,2BAA2B,CAAC"}

package/dist/machine-credential.d.ts

@@ -0,0 +1,31 @@
+export interface MachineCredentialCrypto {
+    getRandomValues(array: Uint8Array): Uint8Array;
+    readonly subtle: Pick<SubtleCrypto, "digest">;
+}
+export interface MachineCredentialRegistration {
+    readonly credential_id: string;
+    readonly secret_sha256: `sha256:${string}`;
+}
+export interface MachineCredentialMaterial {
+    readonly credentialId: string;
+    readonly bearerToken: string;
+    readonly registration: MachineCredentialRegistration;
+}
+export interface MachineCredentialVerificationRecord {
+    readonly credentialId: string;
+    readonly secretSha256: `sha256:${string}`;
+}
+/**
+ * Generates runtime credential material entirely on the caller's machine.
+ *
+ * Only `registration` is safe to send to the administration endpoint.
+ * `bearerToken` contains the one-time readable secret and must remain local.
+ */
+export declare function createMachineCredentialMaterial(crypto?: MachineCredentialCrypto): Promise<MachineCredentialMaterial>;
+/**
+ * Authentication-bound verification for the exact C0 machine bearer syntax.
+ *
+ * The readable token is parsed only here; callers receive a boolean and cannot
+ * derive machine, tenant, subscriber, or notifier identity from it.
+ */
+export declare function verifyMachineCredentialToken(token: string, expected: MachineCredentialVerificationRecord, crypto?: Pick<MachineCredentialCrypto, "subtle">): Promise<boolean>;

package/dist/machine-credential.js

@@ -0,0 +1,78 @@
+import { decodeBase64Url, encodeBase64Url } from "./base64url.js";
+const machineCredentialToken = /^wb_mc1\.(mcred_[A-Za-z0-9_-]{21}[AQgw])\.([A-Za-z0-9_-]{42}[AEIMQUYcgkosw048])$/u;
+const sha256Digest = /^sha256:([a-f0-9]{64})$/u;
+const runtimeGlobal = globalThis;
+function randomBytes(crypto, length) {
+    return crypto.getRandomValues(new Uint8Array(length));
+}
+function hex(bytes) {
+    return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function decodeHex(value) {
+    return Uint8Array.from(Array.from({ length: value.length / 2 }, (_, index) => Number.parseInt(value.slice(index * 2, index * 2 + 2), 16)));
+}
+function constantTimeEqual(left, right) {
+    let mismatch = left.byteLength ^ right.byteLength;
+    const length = Math.max(left.byteLength, right.byteLength);
+    for (let index = 0; index < length; index += 1) {
+        mismatch |=
+            (left[index % left.byteLength] ?? 0) ^
+                (right[index % right.byteLength] ?? 0);
+    }
+    return mismatch === 0;
+}
+/**
+ * Generates runtime credential material entirely on the caller's machine.
+ *
+ * Only `registration` is safe to send to the administration endpoint.
+ * `bearerToken` contains the one-time readable secret and must remain local.
+ */
+export async function createMachineCredentialMaterial(crypto) {
+    const runtimeCrypto = crypto ?? runtimeGlobal.crypto;
+    if (runtimeCrypto === undefined) {
+        throw new Error("Web Crypto is required to generate a machine credential");
+    }
+    const credentialId = `mcred_${encodeBase64Url(randomBytes(runtimeCrypto, 16))}`;
+    const secret = randomBytes(runtimeCrypto, 32);
+    const encodedSecret = encodeBase64Url(secret);
+    const digestBuffer = await runtimeCrypto.subtle.digest("SHA-256", Uint8Array.from(secret));
+    const secretDigest = `sha256:${hex(new Uint8Array(digestBuffer))}`;
+    return {
+        bearerToken: `wb_mc1.${credentialId}.${encodedSecret}`,
+        credentialId,
+        registration: {
+            credential_id: credentialId,
+            secret_sha256: secretDigest,
+        },
+    };
+}
+/**
+ * Authentication-bound verification for the exact C0 machine bearer syntax.
+ *
+ * The readable token is parsed only here; callers receive a boolean and cannot
+ * derive machine, tenant, subscriber, or notifier identity from it.
+ */
+export async function verifyMachineCredentialToken(token, expected, crypto) {
+    const runtimeCrypto = crypto ?? runtimeGlobal.crypto;
+    if (runtimeCrypto === undefined) {
+        throw new Error("Web Crypto is required to verify a machine credential");
+    }
+    const tokenMatch = machineCredentialToken.exec(token);
+    const digestMatch = sha256Digest.exec(expected.secretSha256);
+    const credentialId = tokenMatch?.[1];
+    const encodedSecret = tokenMatch?.[2];
+    const expectedDigest = digestMatch?.[1];
+    if (credentialId === undefined ||
+        encodedSecret === undefined ||
+        expectedDigest === undefined ||
+        credentialId !== expected.credentialId) {
+        return false;
+    }
+    const secret = decodeBase64Url(encodedSecret);
+    if (secret === undefined || secret.byteLength !== 32) {
+        return false;
+    }
+    const candidateDigest = new Uint8Array(await runtimeCrypto.subtle.digest("SHA-256", Uint8Array.from(secret)));
+    return constantTimeEqual(candidateDigest, decodeHex(expectedDigest));
+}
+//# sourceMappingURL=machine-credential.js.map

package/dist/machine-credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-credential.js","sourceRoot":"","sources":["../src/machine-credential.ts"],"names":[],"mappings":"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"}

package/dist/webhook-consumer.d.ts

@@ -0,0 +1,50 @@
+import type { WhooshBangEventV1ContractDocument } from "./generated/whooshbang-event-v1.js";
+import type { WebhookCrypto, WebhookHeaders } from "./webhook-signature.js";
+export declare const MIN_WEBHOOK_DEDUP_RETENTION_SECONDS: number;
+export interface WebhookDeduplicationInput {
+    readonly eventId: string;
+    readonly projectId: string;
+    readonly retainUntilEpochSeconds: number;
+}
+export type WebhookDeduplicationOutcome = "processed" | "duplicate";
+/**
+ * A durable consumer supplies this boundary.
+ *
+ * Implementations must atomically check/claim `eventId` before invoking the
+ * handler, commit the claim with the handler's business transaction, and keep
+ * the committed claim through `retainUntilEpochSeconds`. A failed handler must
+ * not leave a committed claim that suppresses a later delivery.
+ */
+export interface WebhookDeduplicationStore {
+    executeOnce(input: WebhookDeduplicationInput, handler: () => Promise<void>): Promise<WebhookDeduplicationOutcome>;
+}
+export interface ConsumeVerifiedWebhookOptions {
+    readonly crypto?: WebhookCrypto;
+    readonly deduplication: WebhookDeduplicationStore;
+    readonly expectedProjectId: string;
+    readonly handle: (event: WhooshBangEventV1ContractDocument) => Promise<void>;
+    readonly headers: WebhookHeaders;
+    readonly nowSeconds?: number;
+    readonly rawBody: Uint8Array;
+    readonly secrets: readonly string[];
+    readonly toleranceSeconds?: number;
+}
+export type WebhookConsumerRejectionReason = "event_id_mismatch" | "invalid_event" | "invalid_json" | "processing_failed" | "project_mismatch" | "signature_rejected";
+export interface RejectedWebhookConsumption {
+    readonly reason: WebhookConsumerRejectionReason;
+    readonly status: "rejected";
+}
+export interface ProcessedWebhookConsumption {
+    readonly eventId: string;
+    readonly status: "processed";
+}
+export interface DuplicateWebhookConsumption {
+    readonly eventId: string;
+    readonly status: "duplicate";
+}
+export type WebhookConsumptionResult = RejectedWebhookConsumption | ProcessedWebhookConsumption | DuplicateWebhookConsumption;
+/**
+ * Minimal receiver flow: verify raw bytes, validate the event and tenant, then
+ * hand business processing to a caller-owned durable deduplication boundary.
+ */
+export declare function consumeVerifiedWebhook(options: ConsumeVerifiedWebhookOptions): Promise<WebhookConsumptionResult>;

package/dist/webhook-consumer.js

@@ -0,0 +1,71 @@
+import { validateWhooshBangEvent } from "./generated/validators.js";
+import { verifyWebhookSignature } from "./webhook-signature.js";
+export const MIN_WEBHOOK_DEDUP_RETENTION_SECONDS = 7 * 24 * 60 * 60;
+function rejected(reason) {
+    return { reason, status: "rejected" };
+}
+function decodeEvent(rawBody) {
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(rawBody);
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Minimal receiver flow: verify raw bytes, validate the event and tenant, then
+ * hand business processing to a caller-owned durable deduplication boundary.
+ */
+export async function consumeVerifiedWebhook(options) {
+    const nowSeconds = options.nowSeconds === undefined
+        ? Math.floor(Date.now() / 1000)
+        : options.nowSeconds;
+    const verificationOptions = {
+        headers: options.headers,
+        nowSeconds,
+        rawBody: options.rawBody,
+        secrets: options.secrets,
+        ...(options.crypto === undefined ? {} : { crypto: options.crypto }),
+        ...(options.toleranceSeconds === undefined
+            ? {}
+            : { toleranceSeconds: options.toleranceSeconds }),
+    };
+    const verification = await verifyWebhookSignature(verificationOptions);
+    if (!verification.verified) {
+        return rejected("signature_rejected");
+    }
+    const candidate = decodeEvent(options.rawBody);
+    if (candidate === undefined) {
+        return rejected("invalid_json");
+    }
+    if (!validateWhooshBangEvent(candidate)) {
+        return rejected("invalid_event");
+    }
+    if (candidate.id !== verification.eventId) {
+        return rejected("event_id_mismatch");
+    }
+    if (candidate.project_id !== options.expectedProjectId) {
+        return rejected("project_mismatch");
+    }
+    try {
+        const outcome = await options.deduplication.executeOnce({
+            eventId: candidate.id,
+            projectId: candidate.project_id,
+            retainUntilEpochSeconds: nowSeconds + MIN_WEBHOOK_DEDUP_RETENTION_SECONDS,
+        }, async () => {
+            await options.handle(candidate);
+        });
+        if (outcome === "duplicate") {
+            return { eventId: candidate.id, status: "duplicate" };
+        }
+        if (outcome === "processed") {
+            return { eventId: candidate.id, status: "processed" };
+        }
+    }
+    catch {
+        return rejected("processing_failed");
+    }
+    return rejected("processing_failed");
+}
+//# sourceMappingURL=webhook-consumer.js.map

package/dist/webhook-consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-consumer.js","sourceRoot":"","sources":["../src/webhook-consumer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAMpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAiEpE,SAAS,QAAQ,CACf,MAAsC;IAEtC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,WAAW,CAAC,OAAmB;IACtC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAsC;IAEtC,MAAM,UAAU,GACd,OAAO,CAAC,UAAU,KAAK,SAAS;QAC9B,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QAC/B,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;IACzB,MAAM,mBAAmB,GAAkC;QACzD,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,UAAU;QACV,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACnE,GAAG,CAAC,OAAO,CAAC,gBAAgB,KAAK,SAAS;YACxC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,EAAE,CAAC;KACpD,CAAC;IACF,MAAM,YAAY,GAAG,MAAM,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;IACvE,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC;QAC3B,OAAO,QAAQ,CAAC,oBAAoB,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC,cAAc,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,uBAAuB,CAAC,SAAS,CAAC,EAAE,CAAC;QACxC,OAAO,QAAQ,CAAC,eAAe,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,SAAS,CAAC,EAAE,KAAK,YAAY,CAAC,OAAO,EAAE,CAAC;QAC1C,OAAO,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,SAAS,CAAC,UAAU,KAAK,OAAO,CAAC,iBAAiB,EAAE,CAAC;QACvD,OAAO,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAY,MAAM,OAAO,CAAC,aAAa,CAAC,WAAW,CAC9D;YACE,OAAO,EAAE,SAAS,CAAC,EAAE;YACrB,SAAS,EAAE,SAAS,CAAC,UAAU;YAC/B,uBAAuB,EACrB,UAAU,GAAG,mCAAmC;SACnD,EACD,KAAK,IAAI,EAAE;YACT,MAAM,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC,CACF,CAAC;QACF,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QACxD,CAAC;QACD,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QACxD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,QAAQ,CAAC,mBAAmB,CAAC,CAAC;AACvC,CAAC"}

package/dist/webhook-delivery.d.ts

@@ -0,0 +1,46 @@
+export declare const MAX_WEBHOOK_DELIVERY_ATTEMPTS = 8;
+export declare const MAX_WEBHOOK_DELIVERY_WINDOW_SECONDS: number;
+export declare const WEBHOOK_FETCH_REDIRECT_MODE: "manual";
+export interface NetworkFailureOutcome {
+    readonly kind: "network_failure";
+}
+export interface HttpDeliveryOutcome {
+    readonly kind: "http";
+    readonly retryAfter?: string;
+    readonly status: number;
+}
+export type WebhookDeliveryOutcome = NetworkFailureOutcome | HttpDeliveryOutcome;
+export interface ClassifyWebhookDeliveryOptions {
+    readonly attempt: number;
+    readonly firstAttemptAtEpochSeconds: number;
+    readonly nowEpochSeconds: number;
+    readonly outcome: WebhookDeliveryOutcome;
+}
+export type WebhookDeliveryTerminalReason = "attempt_limit_exhausted" | "delivery_window_exhausted" | "http_terminal" | "invalid_input" | "redirect_not_followed" | "unexpected_http_status";
+export type WebhookDeliveryRetryReason = "network_failure" | "retryable_http_status";
+export interface AcceptedWebhookDelivery {
+    readonly action: "accepted";
+    readonly reason: "http_2xx";
+}
+export interface TerminalWebhookDelivery {
+    readonly action: "terminal";
+    readonly reason: WebhookDeliveryTerminalReason;
+}
+export interface RetryWebhookDelivery {
+    readonly action: "retry";
+    readonly latestRetryAtEpochSeconds: number;
+    readonly reason: WebhookDeliveryRetryReason;
+    readonly retryAfterSeconds?: number;
+}
+export type WebhookDeliveryClassification = AcceptedWebhookDelivery | TerminalWebhookDelivery | RetryWebhookDelivery;
+/**
+ * Parses only bounded canonical delta-seconds. HTTP-date values, signs,
+ * whitespace, and values longer than the delivery window are ignored.
+ */
+export declare function parseWebhookRetryAfter(value: string | undefined): number | undefined;
+/**
+ * Classifies one completed attempt. It does not perform network I/O or choose
+ * jitter; callers must use `redirect: "manual"` and schedule no later than the
+ * returned delivery-window deadline.
+ */
+export declare function classifyWebhookDeliveryOutcome(options: ClassifyWebhookDeliveryOptions): WebhookDeliveryClassification;

package/dist/webhook-delivery.js

@@ -0,0 +1,126 @@
+export const MAX_WEBHOOK_DELIVERY_ATTEMPTS = 8;
+export const MAX_WEBHOOK_DELIVERY_WINDOW_SECONDS = 24 * 60 * 60;
+export const WEBHOOK_FETCH_REDIRECT_MODE = "manual";
+const retryAfterDelta = /^(?:0|[1-9][0-9]{0,4})$/u;
+/**
+ * Parses only bounded canonical delta-seconds. HTTP-date values, signs,
+ * whitespace, and values longer than the delivery window are ignored.
+ */
+export function parseWebhookRetryAfter(value) {
+    if (typeof value !== "string" || !retryAfterDelta.test(value)) {
+        return undefined;
+    }
+    const seconds = Number(value);
+    return seconds <= MAX_WEBHOOK_DELIVERY_WINDOW_SECONDS ? seconds : undefined;
+}
+function terminal(reason) {
+    return { action: "terminal", reason };
+}
+function isSafeInteger(value) {
+    return Number.isSafeInteger(value);
+}
+/**
+ * Classifies one completed attempt. It does not perform network I/O or choose
+ * jitter; callers must use `redirect: "manual"` and schedule no later than the
+ * returned delivery-window deadline.
+ */
+export function classifyWebhookDeliveryOutcome(options) {
+    const runtimeOptions = options;
+    if (typeof runtimeOptions !== "object" ||
+        runtimeOptions === null ||
+        Array.isArray(runtimeOptions)) {
+        return terminal("invalid_input");
+    }
+    const input = runtimeOptions;
+    const attempt = input.attempt;
+    const firstAttemptAtEpochSeconds = input.firstAttemptAtEpochSeconds;
+    const nowEpochSeconds = input.nowEpochSeconds;
+    if (typeof attempt !== "number" ||
+        !isSafeInteger(attempt) ||
+        attempt < 1 ||
+        attempt > MAX_WEBHOOK_DELIVERY_ATTEMPTS ||
+        typeof firstAttemptAtEpochSeconds !== "number" ||
+        !isSafeInteger(firstAttemptAtEpochSeconds) ||
+        firstAttemptAtEpochSeconds < 0 ||
+        typeof nowEpochSeconds !== "number" ||
+        !isSafeInteger(nowEpochSeconds) ||
+        nowEpochSeconds < firstAttemptAtEpochSeconds) {
+        return terminal("invalid_input");
+    }
+    let retryReason;
+    let retryAfter;
+    const runtimeOutcome = input.outcome;
+    if (typeof runtimeOutcome !== "object" ||
+        runtimeOutcome === null ||
+        Array.isArray(runtimeOutcome)) {
+        return terminal("invalid_input");
+    }
+    const outcome = runtimeOutcome;
+    if (outcome.kind === "network_failure") {
+        if (Object.keys(outcome).some((key) => key !== "kind")) {
+            return terminal("invalid_input");
+        }
+        retryReason = "network_failure";
+    }
+    else if (outcome.kind === "http") {
+        const retryAfterHeader = outcome.retryAfter;
+        if (Object.keys(outcome).some((key) => !["kind", "status", "retryAfter"].includes(key)) ||
+            (retryAfterHeader !== undefined && typeof retryAfterHeader !== "string")) {
+            return terminal("invalid_input");
+        }
+        const status = outcome.status;
+        if (typeof status !== "number" ||
+            !isSafeInteger(status) ||
+            status < 100 ||
+            status > 599) {
+            return terminal("invalid_input");
+        }
+        if (status >= 200 && status <= 299) {
+            return { action: "accepted", reason: "http_2xx" };
+        }
+        if (status >= 300 && status <= 399) {
+            return terminal("redirect_not_followed");
+        }
+        if (status === 408 || status === 425 || status === 429 || status >= 500) {
+            retryReason = "retryable_http_status";
+            if (status === 429 || status === 503) {
+                retryAfter = parseWebhookRetryAfter(retryAfterHeader);
+            }
+        }
+        else if (status >= 400) {
+            return terminal("http_terminal");
+        }
+        else {
+            return terminal("unexpected_http_status");
+        }
+    }
+    else {
+        return terminal("invalid_input");
+    }
+    if (attempt >= MAX_WEBHOOK_DELIVERY_ATTEMPTS) {
+        return terminal("attempt_limit_exhausted");
+    }
+    const latestRetryAtEpochSeconds = firstAttemptAtEpochSeconds + MAX_WEBHOOK_DELIVERY_WINDOW_SECONDS;
+    if (!Number.isSafeInteger(latestRetryAtEpochSeconds)) {
+        return terminal("invalid_input");
+    }
+    if (nowEpochSeconds >= latestRetryAtEpochSeconds) {
+        return terminal("delivery_window_exhausted");
+    }
+    const retryAfterEpochSeconds = retryAfter === undefined ? undefined : nowEpochSeconds + retryAfter;
+    const safeRetryAfter = retryAfter !== undefined &&
+        retryAfterEpochSeconds !== undefined &&
+        Number.isSafeInteger(retryAfterEpochSeconds) &&
+        retryAfterEpochSeconds <= latestRetryAtEpochSeconds
+        ? retryAfter
+        : undefined;
+    return {
+        action: "retry",
+        latestRetryAtEpochSeconds,
+        reason: retryReason,
+        ...(safeRetryAfter === undefined
+            ? {}
+            : { retryAfterSeconds: safeRetryAfter }),
+    };
+}
+//# sourceMappingURL=webhook-delivery.js.map

package/dist/webhook-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-delivery.js","sourceRoot":"","sources":["../src/webhook-delivery.ts"],"names":[],"mappings":"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"}

package/dist/webhook-signature.d.ts

@@ -0,0 +1,36 @@
+export declare const DEFAULT_WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS = 300;
+export declare const MAX_WEBHOOK_SIGNATURES = 2;
+export declare const MAX_WEBHOOK_SECRETS = 2;
+export interface WebhookCrypto {
+    readonly subtle: Pick<SubtleCrypto, "importKey" | "sign">;
+}
+export type WebhookHeaderEntry = readonly [name: string, value: string];
+export type WebhookHeaderRecord = Readonly<Record<string, string | readonly string[] | undefined>>;
+export type WebhookHeaders = readonly WebhookHeaderEntry[] | WebhookHeaderRecord;
+export type WebhookVerificationFailureReason = "crypto_unavailable" | "duplicate_header" | "duplicate_secret" | "duplicate_signature" | "invalid_body" | "invalid_clock" | "invalid_secret" | "invalid_tolerance" | "malformed_attempt" | "malformed_header" | "malformed_signature" | "malformed_timestamp" | "malformed_webhook_id" | "missing_header" | "signature_mismatch" | "timestamp_outside_tolerance" | "too_many_secrets" | "too_many_signatures" | "unsupported_signature_version";
+export interface VerifiedWebhookSignature {
+    readonly attempt: number;
+    readonly eventId: string;
+    readonly timestamp: number;
+    readonly verified: true;
+}
+export interface RejectedWebhookSignature {
+    readonly reason: WebhookVerificationFailureReason;
+    readonly verified: false;
+}
+export type WebhookSignatureVerification = VerifiedWebhookSignature | RejectedWebhookSignature;
+export interface VerifyWebhookSignatureOptions {
+    readonly crypto?: WebhookCrypto;
+    readonly headers: WebhookHeaders;
+    readonly nowSeconds?: number;
+    readonly rawBody: Uint8Array;
+    readonly secrets: readonly string[];
+    readonly toleranceSeconds?: number;
+}
+/**
+ * Verifies the Standard Webhooks V1 signature over the exact request bytes.
+ *
+ * Header entries are accepted as tuples so callers can preserve and reject
+ * duplicate security headers before framework normalization.
+ */
+export declare function verifyWebhookSignature(options: VerifyWebhookSignatureOptions): Promise<WebhookSignatureVerification>;