@particle-academy/fancy-connector-core 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -2468,7 +2468,7 @@ type HmacScheme = {
      * `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, id?: string) => string;
+    payload: (raw: string, timestamp?: string, id?: string, request?: SignedRequestLine) => string;
     /** Seconds a delivery stays acceptable. */
     tolerance?: number;
     /** Encoding of the signature the provider sends. */
@@ -2483,7 +2483,37 @@ type HmacScheme = {
     secretEncoding?: "utf8" | "base64";
     /** A prefix to strip before decoding (`whsec_`). Its absence is a refusal, never a guess. */
     secretPrefix?: string;
+    /**
+     * The unit the timestamp header is in. Seconds unless said otherwise:
+     * HubSpot sends MILLISECONDS, and comparing those with a window in seconds
+     * refuses every delivery ever made.
+     */
+    timestampUnit?: "s" | "ms";
+    /**
+     * The provider signs the REQUEST LINE too (HubSpot v3:
+     * method + uri + body + timestamp). A delivery the host passed without its
+     * method or URL is refused by name, never signed with a gap.
+     */
+    signsRequestLine?: boolean;
+    /** How the signed URI is spelled from the URL the request was sent to. */
+    uri?: SignedUriRule;
+};
+/** The URI rules a provider's signature can follow. Closed: each is a decision. */
+declare const SIGNED_URI_RULES: readonly ["hubspot-v3"];
+type SignedUriRule = (typeof SIGNED_URI_RULES)[number];
+/** The request line as signed: the method, and the URI after the scheme's rule. */
+type SignedRequestLine = {
+    method: string;
+    uri: string;
 };
+/**
+ * The URI a provider signs, from the URL the request arrived on.
+ *
+ * `hubspot-v3`: only the QUERY portion is percent-decoded, and only for twelve
+ * escapes (case-insensitive); never its leading `?`; any `#fragment` dropped.
+ * Everything else, `%26` and `%3D` included, stays as sent.
+ */
+declare function normaliseSignedUri(url: string, rule: SignedUriRule): 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";
@@ -2516,6 +2546,11 @@ declare function verifyHmac(options: {
     timestamp?: string;
     /** The delivery's id, when the scheme signs one (Svix's `svix-id`). */
     id?: string;
+    /** The request line as RECEIVED, when the scheme signs it (HubSpot v3). */
+    request?: {
+        method: string;
+        url: string;
+    };
     /** Seconds since the epoch. Injected so tests are not clock-dependent. */
     now?: number;
 }): Promise<WebhookVerification>;
@@ -2627,6 +2662,11 @@ declare function header(headers: Record<string, string | string[] | undefined>,
  *   SSE, CometD).
  */
 type DeliveryMechanism = "webhook" | "subscription" | "poll" | "pubsub" | "stream";
+/** See `TriggerDescriptor.route`. `path` is dotted; `[]` means every element. */
+type DeliveryRoute = {
+    by: string;
+    path: string;
+};
 type TriggerDescriptor = {
     service: string;
     operation: string;
@@ -2655,6 +2695,15 @@ type TriggerDescriptor = {
      * it, over the same raw bytes the signature was checked against.
      */
     decode?: DeliveryDecode;
+    /**
+     * For a delivery that reaches ONE endpoint on behalf of many tenants
+     * (HubSpot app webhooks, Gmail's Pub/Sub topic): the ONLY key a host may
+     * route by, and where it sits in the verified payload. The rule that goes
+     * with it is fixed, not configurable: route only AFTER verification, only
+     * to a connection or watch the host minted, and drop an unmapped key with a
+     * 2xx and a log line, creating nothing. The package declares; the HOST routes.
+     */
+    route?: DeliveryRoute;
     /** For `poll`: the provider's smallest sane interval, in seconds. */
     minPollSeconds?: number;
     /** A faked sample event, so the node is runnable before any of the above. */
@@ -2703,6 +2752,13 @@ type InboundDelivery = {
     /** The body EXACTLY as received. Not re-serialised. See `webhook.ts`. */
     raw: string;
     headers: Record<string, string | string[] | undefined>;
+    /**
+     * The request line as RECEIVED, for a provider that signs it (HubSpot v3).
+     * Pass the full URL the provider called, scheme, host, path and query,
+     * exactly as it arrived.
+     */
+    method?: string;
+    url?: string;
 };
 /**
  * Verify an inbound delivery against a trigger's declared scheme.
@@ -2728,4 +2784,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 Attendee, 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, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, type JoinTarget, type JoinTargetKind, 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 RecurrenceRule, 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, decodeDelivery, decodeFormFieldJson, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, parseInvite, 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 };
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type Attendee, 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, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DeliveryRoute, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, type JoinTarget, type JoinTargetKind, 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 RecurrenceRule, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SIGNED_URI_RULES, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SignedRequestLine, type SignedUriRule, 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, decodeDelivery, decodeFormFieldJson, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, normaliseSignedUri, parseInvite, 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

@@ -2468,7 +2468,7 @@ type HmacScheme = {
      * `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, id?: string) => string;
+    payload: (raw: string, timestamp?: string, id?: string, request?: SignedRequestLine) => string;
     /** Seconds a delivery stays acceptable. */
     tolerance?: number;
     /** Encoding of the signature the provider sends. */
@@ -2483,7 +2483,37 @@ type HmacScheme = {
     secretEncoding?: "utf8" | "base64";
     /** A prefix to strip before decoding (`whsec_`). Its absence is a refusal, never a guess. */
     secretPrefix?: string;
+    /**
+     * The unit the timestamp header is in. Seconds unless said otherwise:
+     * HubSpot sends MILLISECONDS, and comparing those with a window in seconds
+     * refuses every delivery ever made.
+     */
+    timestampUnit?: "s" | "ms";
+    /**
+     * The provider signs the REQUEST LINE too (HubSpot v3:
+     * method + uri + body + timestamp). A delivery the host passed without its
+     * method or URL is refused by name, never signed with a gap.
+     */
+    signsRequestLine?: boolean;
+    /** How the signed URI is spelled from the URL the request was sent to. */
+    uri?: SignedUriRule;
+};
+/** The URI rules a provider's signature can follow. Closed: each is a decision. */
+declare const SIGNED_URI_RULES: readonly ["hubspot-v3"];
+type SignedUriRule = (typeof SIGNED_URI_RULES)[number];
+/** The request line as signed: the method, and the URI after the scheme's rule. */
+type SignedRequestLine = {
+    method: string;
+    uri: string;
 };
+/**
+ * The URI a provider signs, from the URL the request arrived on.
+ *
+ * `hubspot-v3`: only the QUERY portion is percent-decoded, and only for twelve
+ * escapes (case-insensitive); never its leading `?`; any `#fragment` dropped.
+ * Everything else, `%26` and `%3D` included, stays as sent.
+ */
+declare function normaliseSignedUri(url: string, rule: SignedUriRule): 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";
@@ -2516,6 +2546,11 @@ declare function verifyHmac(options: {
     timestamp?: string;
     /** The delivery's id, when the scheme signs one (Svix's `svix-id`). */
     id?: string;
+    /** The request line as RECEIVED, when the scheme signs it (HubSpot v3). */
+    request?: {
+        method: string;
+        url: string;
+    };
     /** Seconds since the epoch. Injected so tests are not clock-dependent. */
     now?: number;
 }): Promise<WebhookVerification>;
@@ -2627,6 +2662,11 @@ declare function header(headers: Record<string, string | string[] | undefined>,
  *   SSE, CometD).
  */
 type DeliveryMechanism = "webhook" | "subscription" | "poll" | "pubsub" | "stream";
+/** See `TriggerDescriptor.route`. `path` is dotted; `[]` means every element. */
+type DeliveryRoute = {
+    by: string;
+    path: string;
+};
 type TriggerDescriptor = {
     service: string;
     operation: string;
@@ -2655,6 +2695,15 @@ type TriggerDescriptor = {
      * it, over the same raw bytes the signature was checked against.
      */
     decode?: DeliveryDecode;
+    /**
+     * For a delivery that reaches ONE endpoint on behalf of many tenants
+     * (HubSpot app webhooks, Gmail's Pub/Sub topic): the ONLY key a host may
+     * route by, and where it sits in the verified payload. The rule that goes
+     * with it is fixed, not configurable: route only AFTER verification, only
+     * to a connection or watch the host minted, and drop an unmapped key with a
+     * 2xx and a log line, creating nothing. The package declares; the HOST routes.
+     */
+    route?: DeliveryRoute;
     /** For `poll`: the provider's smallest sane interval, in seconds. */
     minPollSeconds?: number;
     /** A faked sample event, so the node is runnable before any of the above. */
@@ -2703,6 +2752,13 @@ type InboundDelivery = {
     /** The body EXACTLY as received. Not re-serialised. See `webhook.ts`. */
     raw: string;
     headers: Record<string, string | string[] | undefined>;
+    /**
+     * The request line as RECEIVED, for a provider that signs it (HubSpot v3).
+     * Pass the full URL the provider called, scheme, host, path and query,
+     * exactly as it arrived.
+     */
+    method?: string;
+    url?: string;
 };
 /**
  * Verify an inbound delivery against a trigger's declared scheme.
@@ -2728,4 +2784,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 Attendee, 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, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, type JoinTarget, type JoinTargetKind, 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 RecurrenceRule, 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, decodeDelivery, decodeFormFieldJson, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, parseInvite, 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 };
+export { AMBIGUOUS_REFUSAL, type ApiContract, type Attempt, type Attendee, 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, DELIVERY_DECODE_KINDS, type DeliveryDeclaration, type DeliveryDecode, type DeliveryMechanism, type DeliveryOutcome, type DeliveryRoute, type DriftFinding, type DriftReport, EXPIRES_AT_UNITS, type ExpiresAtUnit, FAKE_EPOCH, FORM_FIELD_JSON_REASONS, type FailureKind, type FakeRequest, type FakeValues, FormFieldJsonError, type FormFieldJsonReason, type HmacScheme, type HmacVerificationSpec, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type Invite, type InviteMethod, type JoinTarget, type JoinTargetKind, 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 RecurrenceRule, type RenderRules, type RenderedPayload, type RequestedMode, type ResolveOptions, type ResolvedConnection, type RetryPolicy, type RunIdentity, SANDBOX_KINDS, SIGNED_URI_RULES, SUPPORTED_CONNECTOR_API, type SandboxKind, type Segment, type ServiceDescriptor, type SetupStep, type ShapeMismatch, type SharedTokenScheme, type SharedTokenVerificationSpec, type SignedRequestLine, type SignedUriRule, 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, decodeDelivery, decodeFormFieldJson, deliver, fakeRequest, fakeValues, getConnectionHost, graphemes, handshakeResponse, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isSharedTokenScheme, isSharedTokenSpec, isUnconditionallyRetryable, joinTargets, leaseAction, leaseFromResponse, leaseRenewAt, leaseState, linkRanges, measure, nextOccurrence, normaliseSignedUri, parseInvite, 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

@@ -1953,6 +1953,29 @@ var PROBLEM_SEVERITIES = ["block", "warn"];
 var CANONICAL_METRICS = ["like", "share", "reply", "quote", "view"];
 
 // src/webhook.ts
+var SIGNED_URI_RULES = ["hubspot-v3"];
+var HUBSPOT_V3_DECODE = {
+  "%3A": ":",
+  "%2F": "/",
+  "%3F": "?",
+  "%40": "@",
+  "%21": "!",
+  "%24": "$",
+  "%27": "'",
+  "%28": "(",
+  "%29": ")",
+  "%2A": "*",
+  "%2C": ",",
+  "%3B": ";"
+};
+function normaliseSignedUri(url, rule) {
+  if (rule !== "hubspot-v3") throw new Error(`unknown signed-uri rule ${JSON.stringify(rule)}`);
+  const withoutFragment = url.split("#", 1)[0] ?? "";
+  const q = withoutFragment.indexOf("?");
+  if (q === -1) return withoutFragment;
+  const query = withoutFragment.slice(q + 1).replace(/%[0-9A-Fa-f]{2}/g, (e) => HUBSPOT_V3_DECODE[e.toUpperCase()] ?? e);
+  return `${withoutFragment.slice(0, q)}?${query}`;
+}
 function secretKeyBytes(secret, options = {}) {
   let material = secret;
   if (options.secretPrefix !== void 0) {
@@ -1987,13 +2010,26 @@ async function verifyHmac(options) {
     const sent = Number(timestamp);
     if (!Number.isFinite(sent)) return { ok: false, reason: "timestamp header is not a number" };
     const now = options.now ?? Math.floor(Date.now() / 1e3);
-    if (Math.abs(now - sent) > scheme.tolerance) {
+    const sentSeconds = scheme.timestampUnit === "ms" ? sent / 1e3 : sent;
+    if (Math.abs(now - sentSeconds) > scheme.tolerance) {
       return { ok: false, reason: `delivery is outside the ${scheme.tolerance}s replay window` };
     }
   }
   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);
+  let line;
+  if (scheme.signsRequestLine) {
+    const { method, url } = options.request ?? {};
+    if (!method || !url) return { ok: false, reason: "delivery carried no request method or url" };
+    line = { method, uri: scheme.uri ? normaliseSignedUri(url, scheme.uri) : url };
+  }
+  const expected = await hmac(
+    secret,
+    scheme.payload(raw, timestamp, id, line),
+    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", options = {}) {
@@ -2118,6 +2154,7 @@ async function verifyDelivery(trigger, delivery, secret, now) {
     scheme: spec.scheme,
     timestamp,
     id,
+    ...delivery.method === void 0 && delivery.url === void 0 ? {} : { request: { method: delivery.method ?? "", url: delivery.url ?? "" } },
     ...now === void 0 ? {} : { now }
   });
 }
@@ -2169,6 +2206,7 @@ export {
   RENDERER_VERSION,
   REVIEW_STALE_DAYS,
   SANDBOX_KINDS,
+  SIGNED_URI_RULES,
   SUPPORTED_CONNECTOR_API,
   assertConnectorApi,
   byteRangeOf,
@@ -2208,6 +2246,7 @@ export {
   linkRanges,
   measure,
   nextOccurrence,
+  normaliseSignedUri,
   parseInvite,
   parseMime,
   payloadHash,