@particle-academy/fancy-connector-core 0.8.1 → 0.9.0

package/dist/index.d.cts

@@ -2347,13 +2347,33 @@ type HmacScheme = {
     /**
      * Build the exact string that gets signed. Providers differ here more than
      * anywhere else — Stripe signs `${timestamp}.${body}`, Slack signs
-     * `v0:${timestamp}:${body}`, GitHub signs the body alone.
+     * `v0:${timestamp}:${body}`, GitHub signs the body alone, and Svix signs
+     * `${id}.${timestamp}.${body}` where `id` is the delivery's own id header.
      */
-    payload: (raw: string, timestamp?: string) => string;
+    payload: (raw: string, timestamp?: string, id?: string) => string;
     /** Seconds a delivery stays acceptable. */
     tolerance?: number;
     /** Encoding of the signature the provider sends. */
     encoding?: "hex" | "base64";
+    /**
+     * How the SECRET is spelled. `utf8` (the default, and every provider before
+     * Svix): the key is the text's bytes. `base64`: the key is the DECODED
+     * bytes — Svix hands out `whsec_<base64>`, and half of the decoded bytes are
+     * not valid UTF-8, so encoding the text would sign with the wrong key and
+     * fail exactly like a wrong secret.
+     */
+    secretEncoding?: "utf8" | "base64";
+    /** A prefix to strip before decoding (`whsec_`). Its absence is a refusal, never a guess. */
+    secretPrefix?: string;
+};
+/** The HMAC key a scheme's secret spells, or the reason it cannot be one. */
+declare function secretKeyBytes(secret: string, options?: {
+    secretEncoding?: "utf8" | "base64";
+    secretPrefix?: string;
+}): {
+    bytes: Uint8Array;
+} | {
+    reason: string;
 };
 /**
  * Verify an HMAC-signed delivery.
@@ -2364,15 +2384,33 @@ type HmacScheme = {
  */
 declare function verifyHmac(options: {
     raw: string;
-    signature: string | undefined;
+    /**
+     * The signature(s) the delivery carried. A LIST when the provider sends
+     * several — Stripe signs once per active secret while a secret is rolled
+     * and Svix's header "could be any number of signatures" — and the delivery
+     * is accepted when ANY matches. A first-only rule fails every delivery
+     * whose first signature came from the new secret, for the whole roll, and
+     * it reads exactly like a wrong secret.
+     */
+    signature: string | string[] | undefined;
     secret: string | undefined;
     scheme: HmacScheme;
     timestamp?: string;
+    /** The delivery's id, when the scheme signs one (Svix's `svix-id`). */
+    id?: string;
     /** Seconds since the epoch. Injected so tests are not clock-dependent. */
     now?: number;
 }): Promise<WebhookVerification>;
-/** HMAC of `payload` under `secret`, hex or base64 encoded. */
-declare function hmac(secret: string, payload: string, algorithm: HmacScheme["algorithm"], encoding?: "hex" | "base64"): Promise<string>;
+/**
+ * HMAC of `payload` under `secret`, hex or base64 encoded. `options` says how
+ * the secret is spelled (see `HmacScheme.secretEncoding`); a secret that
+ * cannot be a key THROWS here — signing has no result to carry a reason in —
+ * while `verifyHmac` names it in its result before ever calling this.
+ */
+declare function hmac(secret: string, payload: string, algorithm: HmacScheme["algorithm"], encoding?: "hex" | "base64", options?: {
+    secretEncoding?: "utf8" | "base64";
+    secretPrefix?: string;
+}): Promise<string>;
 /**
  * Compare two strings without leaking where they diverge.
  *
@@ -2503,13 +2541,23 @@ type HmacVerificationSpec = {
     signatureHeader: string;
     /** Header carrying the timestamp, when the scheme signs one. */
     timestampHeader?: string;
+    /**
+     * Header carrying the delivery's ID, when the scheme signs one — Svix
+     * signs `${svix-id}.${svix-timestamp}.${body}`. A declared id header the
+     * delivery does not carry is a refusal, never a payload with a hole in it.
+     */
+    idHeader?: string;
     scheme: HmacScheme;
     /**
      * Some schemes pack the timestamp INTO the signature header
      * (Stripe: `t=…,v1=…`). Given the raw header value, return the parts.
+     * `signatures` carries EVERY signature the header held (a provider rolling
+     * a secret sends one per active secret); `signature` alone is the 0.8.x
+     * shape and still means one.
      */
     parse?: (raw: string) => {
         signature?: string;
+        signatures?: string[];
         timestamp?: string;
     };
     /** A challenge the provider makes before it will deliver anything. */
@@ -2555,4 +2603,4 @@ declare function verifyDelivery(trigger: TriggerDescriptor, delivery: InboundDel
  */
 declare function triggerEvent(trigger: TriggerDescriptor, connection: ResolvedConnection, injected: unknown, config: Record<string, unknown>): unknown;
 
-export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, type DeliveryDeclaration, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, PROBLEM_SEVERITIES, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifySharedToken, withResolvedLimit };
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, type DeliveryDeclaration, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, PROBLEM_SEVERITIES, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, secretKeyBytes, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifySharedToken, withResolvedLimit };

package/dist/index.d.ts

@@ -2347,13 +2347,33 @@ type HmacScheme = {
     /**
      * Build the exact string that gets signed. Providers differ here more than
      * anywhere else — Stripe signs `${timestamp}.${body}`, Slack signs
-     * `v0:${timestamp}:${body}`, GitHub signs the body alone.
+     * `v0:${timestamp}:${body}`, GitHub signs the body alone, and Svix signs
+     * `${id}.${timestamp}.${body}` where `id` is the delivery's own id header.
      */
-    payload: (raw: string, timestamp?: string) => string;
+    payload: (raw: string, timestamp?: string, id?: string) => string;
     /** Seconds a delivery stays acceptable. */
     tolerance?: number;
     /** Encoding of the signature the provider sends. */
     encoding?: "hex" | "base64";
+    /**
+     * How the SECRET is spelled. `utf8` (the default, and every provider before
+     * Svix): the key is the text's bytes. `base64`: the key is the DECODED
+     * bytes — Svix hands out `whsec_<base64>`, and half of the decoded bytes are
+     * not valid UTF-8, so encoding the text would sign with the wrong key and
+     * fail exactly like a wrong secret.
+     */
+    secretEncoding?: "utf8" | "base64";
+    /** A prefix to strip before decoding (`whsec_`). Its absence is a refusal, never a guess. */
+    secretPrefix?: string;
+};
+/** The HMAC key a scheme's secret spells, or the reason it cannot be one. */
+declare function secretKeyBytes(secret: string, options?: {
+    secretEncoding?: "utf8" | "base64";
+    secretPrefix?: string;
+}): {
+    bytes: Uint8Array;
+} | {
+    reason: string;
 };
 /**
  * Verify an HMAC-signed delivery.
@@ -2364,15 +2384,33 @@ type HmacScheme = {
  */
 declare function verifyHmac(options: {
     raw: string;
-    signature: string | undefined;
+    /**
+     * The signature(s) the delivery carried. A LIST when the provider sends
+     * several — Stripe signs once per active secret while a secret is rolled
+     * and Svix's header "could be any number of signatures" — and the delivery
+     * is accepted when ANY matches. A first-only rule fails every delivery
+     * whose first signature came from the new secret, for the whole roll, and
+     * it reads exactly like a wrong secret.
+     */
+    signature: string | string[] | undefined;
     secret: string | undefined;
     scheme: HmacScheme;
     timestamp?: string;
+    /** The delivery's id, when the scheme signs one (Svix's `svix-id`). */
+    id?: string;
     /** Seconds since the epoch. Injected so tests are not clock-dependent. */
     now?: number;
 }): Promise<WebhookVerification>;
-/** HMAC of `payload` under `secret`, hex or base64 encoded. */
-declare function hmac(secret: string, payload: string, algorithm: HmacScheme["algorithm"], encoding?: "hex" | "base64"): Promise<string>;
+/**
+ * HMAC of `payload` under `secret`, hex or base64 encoded. `options` says how
+ * the secret is spelled (see `HmacScheme.secretEncoding`); a secret that
+ * cannot be a key THROWS here — signing has no result to carry a reason in —
+ * while `verifyHmac` names it in its result before ever calling this.
+ */
+declare function hmac(secret: string, payload: string, algorithm: HmacScheme["algorithm"], encoding?: "hex" | "base64", options?: {
+    secretEncoding?: "utf8" | "base64";
+    secretPrefix?: string;
+}): Promise<string>;
 /**
  * Compare two strings without leaking where they diverge.
  *
@@ -2503,13 +2541,23 @@ type HmacVerificationSpec = {
     signatureHeader: string;
     /** Header carrying the timestamp, when the scheme signs one. */
     timestampHeader?: string;
+    /**
+     * Header carrying the delivery's ID, when the scheme signs one — Svix
+     * signs `${svix-id}.${svix-timestamp}.${body}`. A declared id header the
+     * delivery does not carry is a refusal, never a payload with a hole in it.
+     */
+    idHeader?: string;
     scheme: HmacScheme;
     /**
      * Some schemes pack the timestamp INTO the signature header
      * (Stripe: `t=…,v1=…`). Given the raw header value, return the parts.
+     * `signatures` carries EVERY signature the header held (a provider rolling
+     * a secret sends one per active secret); `signature` alone is the 0.8.x
+     * shape and still means one.
      */
     parse?: (raw: string) => {
         signature?: string;
+        signatures?: string[];
         timestamp?: string;
     };
     /** A challenge the provider makes before it will deliver anything. */
@@ -2555,4 +2603,4 @@ declare function verifyDelivery(trigger: TriggerDescriptor, delivery: InboundDel
  */
 declare function triggerEvent(trigger: TriggerDescriptor, connection: ResolvedConnection, injected: unknown, config: Record<string, unknown>): unknown;
 
-export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, type DeliveryDeclaration, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, PROBLEM_SEVERITIES, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifySharedToken, withResolvedLimit };
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type ByteRange, CANONICAL_METRICS, CONNECTOR_API_VERSION, CONNECTOR_MODES, CREDENTIAL_SCOPES, type CallOptions, type CallResult, type Capabilities, type Catalogue, type ChainLinks, type ChainOutcome, type ChainRef, type ChallengeHandshake, type Citation, type Classified, type ConnectionCredentials, type ConnectionHost, type ConnectionSpec, type Connector, ConnectorAmbiguous, ConnectorApiMismatch, ConnectorAuthError, ConnectorConfigError, ConnectorError, type ConnectorErrorContext, type ConnectorFaker, ConnectorIdempotencyExpiredError, type ConnectorMode, ConnectorModeError, ConnectorRateLimited, type ConnectorRequest, ConnectorRequestError, type ConnectorResult, ConnectorTransient, ConnectorUnreachable, type ContractOperation, type CredentialField, type CredentialScope, DEFAULT_IDEMPOTENCY_WINDOW_SECONDS, DEFAULT_RETRY, type DeliveryDeclaration, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type LeaseAction, type LeaseDeclaration, type LeaseState, MAX_IDEMPOTENCY_KEY_LENGTH, type MetricDescriptor, type MetricSample, type MimeAttachment, type MimeHeader, type MimeMessage, type MimePart, type ModeInputs, NO_IDEMPOTENCY_KEY_WARNING, PROBLEM_SEVERITIES, type PreparedRequest, type ProbeOutcome, type ProbeReport, type ProbeResult, type ProbeSpec, type Problem, type ProviderAdapter, RENDERER_VERSION, REVIEW_STALE_DAYS, type RecordedShape, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SpecSource, type SubscriptionLease, type TextUnit, type Transport, type TransportResponse, type TriggerDescriptor, type VerifyResult, type WebhookVerification, type WebhookVerificationSpec, assertConnectorApi, byteRangeOf, callConnector, capabilityProblems, checkAgainstOpenApi, checkAgainstRecordedShape, classifyError, classifyHttp, classifyStatus, classifyThrown, compareShape, connectionsFor, constantTimeEquals, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, parseMime, payloadHash, postChain, probe, providerProblems, providerSandboxIsSelectable, registerConnectionHost, registerTransport, render, reported, resetRateState, resolveConnection, resolveConnectorMode, respectRate, runIdentityFrom, runKeyFrom, runProbes, sandboxIsSelectable, sandboxRefusal, satisfiesMinimum, secretKeyBytes, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifySharedToken, withResolvedLimit };

package/dist/index.js

@@ -1557,12 +1557,35 @@ var PROBLEM_SEVERITIES = ["block", "warn"];
 var CANONICAL_METRICS = ["like", "share", "reply", "quote", "view"];
 
 // src/webhook.ts
+function secretKeyBytes(secret, options = {}) {
+  let material = secret;
+  if (options.secretPrefix !== void 0) {
+    if (!material.startsWith(options.secretPrefix)) {
+      return { reason: `signing secret does not start with ${JSON.stringify(options.secretPrefix)}` };
+    }
+    material = material.slice(options.secretPrefix.length);
+  }
+  if ((options.secretEncoding ?? "utf8") === "base64") {
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(material) || material.length % 4 !== 0) {
+      return { reason: "signing secret is not valid base64" };
+    }
+    try {
+      return { bytes: Uint8Array.from(atob(material), (c) => c.charCodeAt(0)) };
+    } catch {
+      return { reason: "signing secret is not valid base64" };
+    }
+  }
+  return { bytes: new TextEncoder().encode(material) };
+}
 async function verifyHmac(options) {
-  const { raw, signature, secret, scheme, timestamp } = options;
+  const { raw, secret, scheme, timestamp, id } = options;
+  const signatures = (Array.isArray(options.signature) ? options.signature : [options.signature]).filter(
+    (s) => typeof s === "string" && s !== ""
+  );
   if (!secret) {
     return { ok: false, reason: "no signing secret configured for this trigger" };
   }
-  if (!signature) return { ok: false, reason: "delivery carried no signature header" };
+  if (signatures.length === 0) return { ok: false, reason: "delivery carried no signature header" };
   if (scheme.tolerance !== void 0) {
     if (!timestamp) return { ok: false, reason: "delivery carried no timestamp header" };
     const sent = Number(timestamp);
@@ -1572,20 +1595,24 @@ async function verifyHmac(options) {
       return { ok: false, reason: `delivery is outside the ${scheme.tolerance}s replay window` };
     }
   }
-  const expected = await hmac(secret, scheme.payload(raw, timestamp), scheme.algorithm, scheme.encoding ?? "hex");
-  return constantTimeEquals(expected, signature) ? { ok: true } : { ok: false, reason: "signature did not match" };
+  const key = secretKeyBytes(secret, scheme);
+  if ("reason" in key) return { ok: false, reason: key.reason };
+  const expected = await hmac(secret, scheme.payload(raw, timestamp, id), scheme.algorithm, scheme.encoding ?? "hex", scheme);
+  return signatures.some((candidate) => constantTimeEquals(expected, candidate)) ? { ok: true } : { ok: false, reason: "signature did not match" };
 }
-async function hmac(secret, payload, algorithm, encoding = "hex") {
+async function hmac(secret, payload, algorithm, encoding = "hex", options = {}) {
   const subtle = globalThis.crypto?.subtle;
   if (!subtle) {
     throw new Error(
       "WebCrypto is not available in this runtime, so webhook signatures cannot be verified. Refusing to accept deliveries unverified."
     );
   }
+  const material = secretKeyBytes(secret, options);
+  if ("reason" in material) throw new Error(material.reason);
   const encoder2 = new TextEncoder();
   const key = await subtle.importKey(
     "raw",
-    encoder2.encode(secret),
+    material.bytes,
     { name: "HMAC", hash: algorithm },
     false,
     ["sign"]
@@ -1686,12 +1713,15 @@ async function verifyDelivery(trigger, delivery, secret, now) {
   const rawHeader = header2(delivery.headers, spec.signatureHeader);
   const parsed = spec.parse && rawHeader ? spec.parse(rawHeader) : { signature: rawHeader };
   const timestamp = parsed.timestamp ?? (spec.timestampHeader ? header2(delivery.headers, spec.timestampHeader) : void 0);
+  const id = spec.idHeader ? header2(delivery.headers, spec.idHeader) : void 0;
+  if (spec.idHeader && !id) return { ok: false, reason: "delivery carried no id header" };
   return verifyHmac({
     raw: delivery.raw,
-    signature: parsed.signature,
+    signature: parsed.signatures ?? parsed.signature,
     secret,
     scheme: spec.scheme,
     timestamp,
+    id,
     ...now === void 0 ? {} : { now }
   });
 }
@@ -1795,6 +1825,7 @@ export {
   sandboxIsSelectable,
   sandboxRefusal,
   satisfiesMinimum,
+  secretKeyBytes,
   seedFrom,
   shapeOf,
   shouldRetry,