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

package/dist/index.d.cts

@@ -1420,7 +1420,8 @@ declare const NO_IDEMPOTENCY_KEY_WARNING: string;
  *   the host must re-list (sync token or full) AND re-subscribe.
  *
  * The boundaries are DECIDED, not measured, and they are pinned in
- * `fixtures/subscription-lease/cases.json`, which the PHP twin reads too.
+ * fancy-conformance's `shared/subscription-lease` suite, which drives the PHP
+ * twin too (`tests/subscription-lease.test.ts` and its Pest mirror).
  */
 
 type SubscriptionLease = {
@@ -1433,6 +1434,42 @@ type SubscriptionLease = {
 };
 type LeaseState = "active" | "due" | "expired";
 type LeaseAction = "none" | "renew" | "resync";
+/**
+ * How a provider spells its expiry. Two, because two providers: Google
+ * Calendar's channel `expiration` is epoch MILLISECONDS (as a JSON string, and
+ * a number is accepted too); Microsoft Graph's `expirationDateTime` is ISO
+ * 8601 with a seven-digit fraction. A unit no shipped provider spells is not
+ * here — a vocabulary with no provider is a claim that outruns the code.
+ *
+ * Data as well as a type: a host validates a definition at the JSON boundary,
+ * where `tsc` cannot see.
+ */
+declare const EXPIRES_AT_UNITS: readonly ["rfc3339", "epoch-ms"];
+type ExpiresAtUnit = (typeof EXPIRES_AT_UNITS)[number];
+/**
+ * What a subscription trigger DECLARES about its lease, so a host can build
+ * the value from the provider's create (or renew) response without knowing
+ * the provider.
+ */
+type LeaseDeclaration = {
+    /** Dotted path to the expiry in the create/renew response, e.g. `expiration` or `channel.expiration`. */
+    expiresAtFrom: string;
+    expiresAtUnit: ExpiresAtUnit;
+    /** How early the host renews, in seconds. Positive. */
+    renewBeforeSeconds: number;
+    /** The operation the host calls when the lease is due. */
+    renewOperation: string;
+};
+/**
+ * Build the lease from the provider's create (or renew) response, by
+ * declaration. The declared unit is never guessed around: digits under
+ * `rfc3339`, or an instant under `epoch-ms`, are refused — a lease built from
+ * a misread expiry is one that expires unannounced.
+ *
+ * The expiry is stored as an RFC 3339 instant in UTC at millisecond
+ * precision; the lease's own refusals (margin, operation) still apply.
+ */
+declare function leaseFromResponse(declaration: LeaseDeclaration, response: unknown, at?: ConnectorErrorContext): SubscriptionLease;
 /**
  * Validate a declaration and return the lease — a plain value a host stores
  * beside the trigger and hands back to `leaseState` / `leaseAction` later.
@@ -2296,6 +2333,15 @@ type WebhookVerification = {
     reason: string;
 };
 type HmacScheme = {
+    /**
+     * Optional and always `"hmac"`: every scheme written before 0.8.0 omits it
+     * and still means HMAC. It exists so `verifyDelivery` dispatches on a NAMED
+     * kind — `"shared-token"`, `"hmac"` or absent — and refuses any other value
+     * by name, rather than treating "has no kind" as HMAC forever. (Fancy's
+     * alignment review of 0.8.0: a third scheme that forgot its kind would
+     * otherwise be verified as HMAC, silently.)
+     */
+    kind?: "hmac";
     /** Hash to use. */
     algorithm: "SHA-256" | "SHA-1" | "SHA-512";
     /**
@@ -2335,6 +2381,58 @@ declare function hmac(secret: string, payload: string, algorithm: HmacScheme["al
  * attacker nothing they could not compute.
  */
 declare function constantTimeEquals(a: string, b: string): boolean;
+/**
+ * A delivery verified by a token the provider ECHOES rather than a signature
+ * it computes.
+ *
+ * Google Calendar sends the channel's `token` back in `X-Goog-Channel-Token`
+ * on every notification — with an EMPTY body, so there is nothing to sign.
+ * Microsoft Graph sends `clientState` inside every item of the notification's
+ * `value` array. Same refusal-by-default as HMAC, same result shape, and a
+ * constant-time comparison: a token is a secret, and `===` leaks which prefix
+ * was right.
+ *
+ * A body `path` is dotted; a segment ending in `[]` means EVERY element of that
+ * array, all of which must match — one wrong item refuses the whole delivery.
+ */
+type SharedTokenScheme = {
+    kind: "shared-token";
+    in: "header";
+    name: string;
+} | {
+    kind: "shared-token";
+    in: "body";
+    path: string;
+};
+declare function isSharedTokenScheme(scheme: HmacScheme | SharedTokenScheme): scheme is SharedTokenScheme;
+declare function verifySharedToken(options: {
+    raw: string;
+    headers: Record<string, string | string[] | undefined>;
+    secret: string | undefined;
+    scheme: SharedTokenScheme;
+}): WebhookVerification;
+/**
+ * A challenge the provider makes BEFORE it will deliver anything, answered by
+ * echoing a query parameter as plain text. Microsoft Graph POSTs
+ * `?validationToken=…` to the notification URL when a subscription is created
+ * and refuses to create it unless the token comes back, decoded, as
+ * `text/plain` within ten seconds.
+ *
+ * Declared as data on the trigger so a host can answer it in its own routing
+ * layer; `handshakeResponse` is the pure half — what to send, or `undefined`
+ * when the request is not a challenge at all.
+ */
+type ChallengeHandshake = {
+    kind: "echo-query";
+    /** The query parameter carrying the challenge. */
+    param: string;
+    contentType?: "text/plain";
+};
+declare function handshakeResponse(handshake: ChallengeHandshake | undefined, query: Record<string, string | string[] | undefined>): {
+    status: 200;
+    contentType: string;
+    body: string;
+} | undefined;
 /**
  * Pull one header case-insensitively.
  *
@@ -2385,6 +2483,13 @@ type TriggerDescriptor = {
     setup: string;
     /** For `subscription`: how long the provider keeps it alive, in seconds. */
     subscriptionTtl?: number;
+    /**
+     * For `subscription`: where the provider's expiry sits in the create/renew
+     * response and how it is spelled, so a host builds the `SubscriptionLease`
+     * with `leaseFromResponse` and runs ONE renewal scheduler for every
+     * expiring trigger.
+     */
+    lease?: LeaseDeclaration;
     /** For `webhook` / `subscription`: how a delivery is authenticated. */
     verification?: WebhookVerificationSpec;
     /** For `poll`: the provider's smallest sane interval, in seconds. */
@@ -2392,7 +2497,8 @@ type TriggerDescriptor = {
     /** A faked sample event, so the node is runnable before any of the above. */
     faker: ConnectorFaker;
 };
-type WebhookVerificationSpec = {
+/** The provider SIGNS each delivery. */
+type HmacVerificationSpec = {
     /** Header carrying the signature. */
     signatureHeader: string;
     /** Header carrying the timestamp, when the scheme signs one. */
@@ -2406,7 +2512,20 @@ type WebhookVerificationSpec = {
         signature?: string;
         timestamp?: string;
     };
+    /** A challenge the provider makes before it will deliver anything. */
+    handshake?: ChallengeHandshake;
+};
+/**
+ * The provider ECHOES a token the subscriber chose. Google Calendar's channel
+ * token, Graph's `clientState`. See `SharedTokenScheme`.
+ */
+type SharedTokenVerificationSpec = {
+    scheme: SharedTokenScheme;
+    /** A challenge the provider makes before it will deliver anything. */
+    handshake?: ChallengeHandshake;
 };
+type WebhookVerificationSpec = HmacVerificationSpec | SharedTokenVerificationSpec;
+declare function isSharedTokenSpec(spec: WebhookVerificationSpec): spec is SharedTokenVerificationSpec;
 type InboundDelivery = {
     /** The body EXACTLY as received. Not re-serialised. See `webhook.ts`. */
     raw: string;
@@ -2436,4 +2555,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 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, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type LeaseAction, 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 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, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isUnconditionallyRetryable, leaseAction, 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, 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, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifySharedToken, withResolvedLimit };

package/dist/index.d.ts

@@ -1420,7 +1420,8 @@ declare const NO_IDEMPOTENCY_KEY_WARNING: string;
  *   the host must re-list (sync token or full) AND re-subscribe.
  *
  * The boundaries are DECIDED, not measured, and they are pinned in
- * `fixtures/subscription-lease/cases.json`, which the PHP twin reads too.
+ * fancy-conformance's `shared/subscription-lease` suite, which drives the PHP
+ * twin too (`tests/subscription-lease.test.ts` and its Pest mirror).
  */
 
 type SubscriptionLease = {
@@ -1433,6 +1434,42 @@ type SubscriptionLease = {
 };
 type LeaseState = "active" | "due" | "expired";
 type LeaseAction = "none" | "renew" | "resync";
+/**
+ * How a provider spells its expiry. Two, because two providers: Google
+ * Calendar's channel `expiration` is epoch MILLISECONDS (as a JSON string, and
+ * a number is accepted too); Microsoft Graph's `expirationDateTime` is ISO
+ * 8601 with a seven-digit fraction. A unit no shipped provider spells is not
+ * here — a vocabulary with no provider is a claim that outruns the code.
+ *
+ * Data as well as a type: a host validates a definition at the JSON boundary,
+ * where `tsc` cannot see.
+ */
+declare const EXPIRES_AT_UNITS: readonly ["rfc3339", "epoch-ms"];
+type ExpiresAtUnit = (typeof EXPIRES_AT_UNITS)[number];
+/**
+ * What a subscription trigger DECLARES about its lease, so a host can build
+ * the value from the provider's create (or renew) response without knowing
+ * the provider.
+ */
+type LeaseDeclaration = {
+    /** Dotted path to the expiry in the create/renew response, e.g. `expiration` or `channel.expiration`. */
+    expiresAtFrom: string;
+    expiresAtUnit: ExpiresAtUnit;
+    /** How early the host renews, in seconds. Positive. */
+    renewBeforeSeconds: number;
+    /** The operation the host calls when the lease is due. */
+    renewOperation: string;
+};
+/**
+ * Build the lease from the provider's create (or renew) response, by
+ * declaration. The declared unit is never guessed around: digits under
+ * `rfc3339`, or an instant under `epoch-ms`, are refused — a lease built from
+ * a misread expiry is one that expires unannounced.
+ *
+ * The expiry is stored as an RFC 3339 instant in UTC at millisecond
+ * precision; the lease's own refusals (margin, operation) still apply.
+ */
+declare function leaseFromResponse(declaration: LeaseDeclaration, response: unknown, at?: ConnectorErrorContext): SubscriptionLease;
 /**
  * Validate a declaration and return the lease — a plain value a host stores
  * beside the trigger and hands back to `leaseState` / `leaseAction` later.
@@ -2296,6 +2333,15 @@ type WebhookVerification = {
     reason: string;
 };
 type HmacScheme = {
+    /**
+     * Optional and always `"hmac"`: every scheme written before 0.8.0 omits it
+     * and still means HMAC. It exists so `verifyDelivery` dispatches on a NAMED
+     * kind — `"shared-token"`, `"hmac"` or absent — and refuses any other value
+     * by name, rather than treating "has no kind" as HMAC forever. (Fancy's
+     * alignment review of 0.8.0: a third scheme that forgot its kind would
+     * otherwise be verified as HMAC, silently.)
+     */
+    kind?: "hmac";
     /** Hash to use. */
     algorithm: "SHA-256" | "SHA-1" | "SHA-512";
     /**
@@ -2335,6 +2381,58 @@ declare function hmac(secret: string, payload: string, algorithm: HmacScheme["al
  * attacker nothing they could not compute.
  */
 declare function constantTimeEquals(a: string, b: string): boolean;
+/**
+ * A delivery verified by a token the provider ECHOES rather than a signature
+ * it computes.
+ *
+ * Google Calendar sends the channel's `token` back in `X-Goog-Channel-Token`
+ * on every notification — with an EMPTY body, so there is nothing to sign.
+ * Microsoft Graph sends `clientState` inside every item of the notification's
+ * `value` array. Same refusal-by-default as HMAC, same result shape, and a
+ * constant-time comparison: a token is a secret, and `===` leaks which prefix
+ * was right.
+ *
+ * A body `path` is dotted; a segment ending in `[]` means EVERY element of that
+ * array, all of which must match — one wrong item refuses the whole delivery.
+ */
+type SharedTokenScheme = {
+    kind: "shared-token";
+    in: "header";
+    name: string;
+} | {
+    kind: "shared-token";
+    in: "body";
+    path: string;
+};
+declare function isSharedTokenScheme(scheme: HmacScheme | SharedTokenScheme): scheme is SharedTokenScheme;
+declare function verifySharedToken(options: {
+    raw: string;
+    headers: Record<string, string | string[] | undefined>;
+    secret: string | undefined;
+    scheme: SharedTokenScheme;
+}): WebhookVerification;
+/**
+ * A challenge the provider makes BEFORE it will deliver anything, answered by
+ * echoing a query parameter as plain text. Microsoft Graph POSTs
+ * `?validationToken=…` to the notification URL when a subscription is created
+ * and refuses to create it unless the token comes back, decoded, as
+ * `text/plain` within ten seconds.
+ *
+ * Declared as data on the trigger so a host can answer it in its own routing
+ * layer; `handshakeResponse` is the pure half — what to send, or `undefined`
+ * when the request is not a challenge at all.
+ */
+type ChallengeHandshake = {
+    kind: "echo-query";
+    /** The query parameter carrying the challenge. */
+    param: string;
+    contentType?: "text/plain";
+};
+declare function handshakeResponse(handshake: ChallengeHandshake | undefined, query: Record<string, string | string[] | undefined>): {
+    status: 200;
+    contentType: string;
+    body: string;
+} | undefined;
 /**
  * Pull one header case-insensitively.
  *
@@ -2385,6 +2483,13 @@ type TriggerDescriptor = {
     setup: string;
     /** For `subscription`: how long the provider keeps it alive, in seconds. */
     subscriptionTtl?: number;
+    /**
+     * For `subscription`: where the provider's expiry sits in the create/renew
+     * response and how it is spelled, so a host builds the `SubscriptionLease`
+     * with `leaseFromResponse` and runs ONE renewal scheduler for every
+     * expiring trigger.
+     */
+    lease?: LeaseDeclaration;
     /** For `webhook` / `subscription`: how a delivery is authenticated. */
     verification?: WebhookVerificationSpec;
     /** For `poll`: the provider's smallest sane interval, in seconds. */
@@ -2392,7 +2497,8 @@ type TriggerDescriptor = {
     /** A faked sample event, so the node is runnable before any of the above. */
     faker: ConnectorFaker;
 };
-type WebhookVerificationSpec = {
+/** The provider SIGNS each delivery. */
+type HmacVerificationSpec = {
     /** Header carrying the signature. */
     signatureHeader: string;
     /** Header carrying the timestamp, when the scheme signs one. */
@@ -2406,7 +2512,20 @@ type WebhookVerificationSpec = {
         signature?: string;
         timestamp?: string;
     };
+    /** A challenge the provider makes before it will deliver anything. */
+    handshake?: ChallengeHandshake;
+};
+/**
+ * The provider ECHOES a token the subscriber chose. Google Calendar's channel
+ * token, Graph's `clientState`. See `SharedTokenScheme`.
+ */
+type SharedTokenVerificationSpec = {
+    scheme: SharedTokenScheme;
+    /** A challenge the provider makes before it will deliver anything. */
+    handshake?: ChallengeHandshake;
 };
+type WebhookVerificationSpec = HmacVerificationSpec | SharedTokenVerificationSpec;
+declare function isSharedTokenSpec(spec: WebhookVerificationSpec): spec is SharedTokenVerificationSpec;
 type InboundDelivery = {
     /** The body EXACTLY as received. Not re-serialised. See `webhook.ts`. */
     raw: string;
@@ -2436,4 +2555,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 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, FAKE_EPOCH, type FailureKind, type FakeRequest, type FakeValues, type HmacScheme, type HostEnvironment, type IdempotencyOptions, type InboundDelivery, type LeaseAction, 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 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, header, hmac, httpFailure, idempotencyKeyFor, isEmptyPayload, isRemote, isUnconditionallyRetryable, leaseAction, 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, 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, seedFrom, shapeOf, shouldRetry, sliceByteRange, splitToFit, subscriptionLease, triggerEvent, unchecked, utf8Length, verifyDelivery, verifyHmac, verifySharedToken, withResolvedLimit };

package/dist/index.js

@@ -914,6 +914,7 @@ function fnv1a(value) {
 }
 
 // src/lease.ts
+var EXPIRES_AT_UNITS = ["rfc3339", "epoch-ms"];
 var INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
 var DEFAULT_CONTEXT = { service: "", operation: "subscription" };
 function instantMs(value, field, at) {
@@ -923,12 +924,59 @@ function instantMs(value, field, at) {
       at
     );
   }
-  const ms = Date.parse(value);
+  const ms = Date.parse(value.replace(/(\.\d{3})\d+/, "$1"));
   if (Number.isNaN(ms)) {
     throw new ConnectorConfigError(`${field} is not a real instant: ${JSON.stringify(value)}`, at);
   }
   return ms;
 }
+function leaseFromResponse(declaration, response, at = DEFAULT_CONTEXT) {
+  const { expiresAtFrom: path, expiresAtUnit: unit } = declaration;
+  if (!EXPIRES_AT_UNITS.includes(unit)) {
+    throw new ConnectorConfigError(
+      `expiresAtUnit must be one of ${EXPIRES_AT_UNITS.join(" | ")}, got ${JSON.stringify(unit)}.`,
+      at
+    );
+  }
+  const value = readPath(response, path);
+  if (value === void 0 || value === null) {
+    throw new ConnectorConfigError(
+      `${path} is not present in the response, so no lease can be built \u2014 a subscription with no known expiry is one nobody renews.`,
+      at
+    );
+  }
+  let expiresAt;
+  if (unit === "epoch-ms") {
+    const ms = typeof value === "number" ? value : typeof value === "string" && /^\d+$/.test(value) ? Number(value) : Number.NaN;
+    if (!Number.isSafeInteger(ms)) {
+      throw new ConnectorConfigError(
+        `${path} must be epoch milliseconds as digits under "epoch-ms", got ${JSON.stringify(value)}.`,
+        at
+      );
+    }
+    expiresAt = new Date(ms).toISOString();
+  } else {
+    if (typeof value !== "string" || !INSTANT.test(value)) {
+      throw new ConnectorConfigError(
+        `${path} must be an RFC 3339 instant under "rfc3339", got ${JSON.stringify(value)}.`,
+        at
+      );
+    }
+    expiresAt = new Date(instantMs(value, path, at)).toISOString();
+  }
+  return subscriptionLease(
+    { expiresAt, renewBeforeSeconds: declaration.renewBeforeSeconds, renewOperation: declaration.renewOperation },
+    at
+  );
+}
+function readPath(value, path) {
+  let current = value;
+  for (const segment of path.split(".")) {
+    if (current === null || typeof current !== "object") return void 0;
+    current = current[segment];
+  }
+  return current;
+}
 function subscriptionLease(input, at = DEFAULT_CONTEXT) {
   instantMs(input.expiresAt, "expiresAt", at);
   if (!Number.isInteger(input.renewBeforeSeconds) || input.renewBeforeSeconds <= 0) {
@@ -1558,6 +1606,52 @@ function constantTimeEquals(a, b) {
   for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
   return diff === 0;
 }
+function isSharedTokenScheme(scheme) {
+  return "kind" in scheme && scheme.kind === "shared-token";
+}
+function verifySharedToken(options) {
+  const { raw, headers, secret, scheme } = options;
+  if (!secret) {
+    return { ok: false, reason: "no shared token configured for this trigger" };
+  }
+  let tokens;
+  if (scheme.in === "header") {
+    tokens = [header2(headers, scheme.name)];
+  } else {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return { ok: false, reason: "delivery body is not JSON" };
+    }
+    tokens = readTokens(parsed, scheme.path.split("."));
+  }
+  const present = tokens.filter((t) => t !== void 0 && t !== null && t !== "");
+  if (present.length === 0) return { ok: false, reason: "delivery carried no token" };
+  let matched = present.length === tokens.length;
+  for (const token of present) {
+    matched = typeof token === "string" && constantTimeEquals(secret, token) && matched;
+  }
+  return matched ? { ok: true } : { ok: false, reason: "token did not match" };
+}
+function readTokens(value, segments) {
+  if (segments.length === 0) return [value];
+  const [head, ...rest] = segments;
+  const eachElement = head.endsWith("[]");
+  const key = eachElement ? head.slice(0, -2) : head;
+  if (value === null || typeof value !== "object") return [void 0];
+  const next = value[key];
+  if (!eachElement) return readTokens(next, rest);
+  if (!Array.isArray(next)) return [void 0];
+  return next.flatMap((element) => readTokens(element, rest));
+}
+function handshakeResponse(handshake, query) {
+  if (!handshake) return void 0;
+  const raw = query[handshake.param];
+  const token = Array.isArray(raw) ? raw[0] : raw;
+  if (!token) return void 0;
+  return { status: 200, contentType: handshake.contentType ?? "text/plain", body: token };
+}
 function header2(headers, name) {
   const wanted = name.toLowerCase();
   for (const [key, value] of Object.entries(headers)) {
@@ -1568,6 +1662,9 @@ function header2(headers, name) {
 }
 
 // src/trigger.ts
+function isSharedTokenSpec(spec) {
+  return isSharedTokenScheme(spec.scheme);
+}
 async function verifyDelivery(trigger, delivery, secret, now) {
   const spec = trigger.verification;
   if (!spec) {
@@ -1576,6 +1673,16 @@ async function verifyDelivery(trigger, delivery, secret, now) {
       reason: `${trigger.service}.${trigger.operation} declares no signature scheme, so a delivery cannot be trusted.`
     };
   }
+  if (isSharedTokenSpec(spec)) {
+    return verifySharedToken({ raw: delivery.raw, headers: delivery.headers, secret, scheme: spec.scheme });
+  }
+  const kind = spec.scheme.kind ?? "hmac";
+  if (kind !== "hmac") {
+    return {
+      ok: false,
+      reason: `${trigger.service}.${trigger.operation} declares a verification scheme "${kind}" this runtime does not know \u2014 refusing rather than guessing.`
+    };
+  }
   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);
@@ -1625,6 +1732,7 @@ export {
   ConnectorUnreachable,
   DEFAULT_IDEMPOTENCY_WINDOW_SECONDS,
   DEFAULT_RETRY,
+  EXPIRES_AT_UNITS,
   FAKE_EPOCH,
   MAX_IDEMPOTENCY_KEY_LENGTH,
   NO_IDEMPOTENCY_KEY_WARNING,
@@ -1651,14 +1759,18 @@ export {
   fakeValues,
   getConnectionHost,
   graphemes,
+  handshakeResponse,
   header2 as header,
   hmac,
   httpFailure,
   idempotencyKeyFor,
   isEmptyPayload,
   isRemote,
+  isSharedTokenScheme,
+  isSharedTokenSpec,
   isUnconditionallyRetryable,
   leaseAction,
+  leaseFromResponse,
   leaseRenewAt,
   leaseState,
   linkRanges,
@@ -1694,6 +1806,7 @@ export {
   utf8Length,
   verifyDelivery,
   verifyHmac,
+  verifySharedToken,
   withResolvedLimit
 };
 //# sourceMappingURL=index.js.map