@geekmidas/events 10.0.0-alpha.39 → 10.0.0-alpha.40

package/dist/sns/index.d.cts

@@ -36,6 +36,159 @@ export declare class SNSConnection implements EventConnection {
   get topicArn(): string;
 }
 //#endregion
+//#region src/sns/push.d.ts
+/**
+ * SNS delivering to an HTTP(S) endpoint, rather than to a queue that is polled.
+ *
+ * SNS POSTs each message to the subscribed URL as JSON. That is the whole
+ * transport: no queue in between, no poller, and the endpoint is handed the
+ * same envelope a Lambda subscription receives inside `Records[].Sns` — so the
+ * handler that runs deployed can be the one that runs here.
+ *
+ * The endpoint is public, so a message is trusted only once its signature
+ * checks out against a certificate SNS itself serves. Anything else that POSTs
+ * there is somebody's guess at the shape.
+ */
+/** A message SNS POSTs to a subscribed HTTP endpoint. */
+interface SnsHttpMessage {
+  Type: 'Notification' | 'SubscriptionConfirmation' | 'UnsubscribeConfirmation';
+  MessageId: string;
+  TopicArn: string;
+  Message: string;
+  Timestamp: string;
+  SignatureVersion: string;
+  Signature: string;
+  SigningCertURL: string;
+  Subject?: string;
+  /** Confirmation messages only. */
+  Token?: string;
+  /** Confirmation messages only: GET it to confirm. */
+  SubscribeURL?: string;
+  /** Notifications only. */
+  UnsubscribeURL?: string;
+  MessageAttributes?: Record<string, {
+    Type: string;
+    Value: string;
+  }>;
+}
+interface VerifySnsMessageOptions {
+  /**
+   * Fetch the PEM at a certificate URL. `fetch` by default; replaceable so a
+   * test signs with its own key instead of SNS's.
+   */
+  fetchCertificate?: (url: string) => Promise<string>;
+}
+/** The string SNS signed for this message. */
+export declare function snsStringToSign(message: SnsHttpMessage): string;
+/**
+ * Check that SNS sent this message: the certificate is SNS's own, and the
+ * signature over the message's signed fields verifies against it.
+ *
+ * Throws rather than returning false, so a caller cannot forget to look.
+ */
+export declare function verifySnsMessage(message: SnsHttpMessage, options?: VerifySnsMessageOptions): Promise<void>;
+/**
+ * Confirm a subscription by visiting the URL SNS sent. Until this happens SNS
+ * delivers nothing to the endpoint.
+ */
+export declare function confirmSnsSubscription(message: SnsHttpMessage, request?: (url: string) => Promise<{
+  ok: boolean;
+  status: number;
+}>): Promise<void>;
+interface SubscribeHttpEndpointOptions {
+  /** The URL SNS POSTs to — `http:` or `https:`, which picks the protocol. */
+  endpoint: string;
+  /**
+   * The event types this endpoint takes. Becomes the subscription's filter
+   * policy on the `type` attribute `SNSPublisher` sets, so SNS sends nothing
+   * else — fan-out to every subscriber, each seeing only what it named.
+   */
+  events: readonly string[];
+  /**
+   * An SQS queue's ARN for what SNS gives up delivering. SNS retries an HTTP
+   * endpoint for a limited time and then drops the message, so without one an
+   * outage longer than that loses events.
+   */
+  deadLetterQueueArn?: string;
+}
+/**
+ * Subscribe an HTTP endpoint to the connection's topic, converging on one
+ * confirmed subscription with the filter asked for — so it is safe on every
+ * start:
+ *
+ * - **none yet** — subscribed; SNS sends a confirmation to the endpoint.
+ * - **confirmed** — its filter and dead-letter queue are brought up to date.
+ *   Subscribing again with different attributes is an error on SNS, and the
+ *   events a subscriber names change.
+ * - **stuck pending** — a confirmation that never landed (the endpoint was
+ *   down, or answered wrong). Subscribing the same endpoint again is a no-op
+ *   on an emulator, so it is dropped and subscribed afresh, which sends a new
+ *   confirmation.
+ */
+export declare function subscribeHttpEndpoint(connection: SNSConnection, options: SubscribeHttpEndpointOptions): Promise<string | undefined>;
+/**
+ * A pushed notification as the Lambda event SNS would have invoked a function
+ * with, so it can be handed to the same adaptor.
+ */
+export declare function toSnsEvent(message: SnsHttpMessage, subscriptionArn?: string): {
+  Records: {
+    EventSource: string;
+    EventVersion: string;
+    EventSubscriptionArn: string;
+    Sns: {
+      Type: "Notification" | "SubscriptionConfirmation" | "UnsubscribeConfirmation";
+      MessageId: string;
+      TopicArn: string;
+      Subject: string | null;
+      Message: string;
+      Timestamp: string;
+      SignatureVersion: string;
+      Signature: string;
+      SigningCertUrl: string;
+      UnsubscribeUrl: string;
+      MessageAttributes: Record<string, {
+        Type: string;
+        Value: string;
+      }>;
+    };
+  }[];
+};
+export declare class SnsCertificateUntrusted extends Error {
+  readonly url: string;
+  constructor(url: string);
+}
+export declare class SnsCertificateUnavailable extends Error {
+  readonly url: string;
+  readonly status: number;
+  constructor(url: string, status: number);
+}
+export declare class SnsSignatureVersionUnknown extends Error {
+  readonly version: string;
+  constructor(version: string);
+}
+export declare class SnsSignatureInvalid extends Error {
+  readonly messageId: string;
+  readonly topicArn: string;
+  constructor(messageId: string, topicArn: string);
+}
+export declare class SnsMessageTypeUnknown extends Error {
+  readonly type: string;
+  constructor(type: string);
+}
+export declare class SnsNotAConfirmation extends Error {
+  readonly type: string;
+  constructor(type: string);
+}
+export declare class SnsConfirmationFailed extends Error {
+  readonly topicArn: string;
+  readonly status: number;
+  constructor(topicArn: string, status: number);
+}
+export declare class SnsEndpointNotHttp extends Error {
+  readonly endpoint: string;
+  constructor(endpoint: string);
+}
+//#endregion
 //#region src/sns/SNSPublisher.d.ts
 type SNSPublisherOptions = {};
 export declare class SNSPublisher<TMessage extends PublishableMessage<string, any>> implements EventPublisher<TMessage> {
@@ -108,5 +261,5 @@ export declare class SnsQueueMissing extends Error {
   constructor(queueName: string | undefined);
 }
 //#endregion
-export { type SNSConnectionConfig, type SNSPublisherOptions, type SNSSubscriberOptions, type SnsAddress, snsUrl_d_exports as snsUrl };
+export { type SNSConnectionConfig, type SNSPublisherOptions, type SNSSubscriberOptions, type SnsAddress, type SnsHttpMessage, type SubscribeHttpEndpointOptions, type VerifySnsMessageOptions, snsUrl_d_exports as snsUrl };
 //# sourceMappingURL=index.d.cts.map

package/dist/sns/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/sns/SNSConnection.ts","../../src/sns/SNSPublisher.ts","../../src/sns/SNSSubscriber.ts"],"mappings":";;;;UAKiB;EAChB;EACA;EACA;EACA;IACC;IACA;IACA;;;qBAIW,yBAAyB;WAC5B,OAAI,mBAAA;UACL;UACA;UACA;EAER,YAAY,QAAQ;;;;;SAgBP,qBACZ,2BACE,QAAQ;EA8BL,WAAW;EAKX,SAAS;EAKf;;;;MAOI,aAAa;;;;MAOb;;;;KC1FO;qBAEC,aAAa,iBAAiB,4CAC/B,eAAe;UAGjB;EADT,YACS,YAAY,eACpB,WAAU;;;;;SAOE,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,aAAa;EAQ5C,QAAQ,UAAU,aAAa;UAWvB;EAkBR,SAAS;;;;UC5CC;EAChB;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;qBAoBY,cAAc,iBAAiB,4CAChC,gBAAgB;UAUlB;UARD;UACA;UACA;UACA;UACA;UACA;EAER,YACS,YAAY,eACpB,UAAS;;;;;SAwBG,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,cAAc;EAoB7C,UACL,UAAU,oBACV,WAAW,SAAS,aAAa,gBAC/B;;;;EA2BG,QAAQ;UA6BA;UAwBA;UA4BA;;;;;;qBAgBF,wBAAwB;WACf;EAArB,YAAqB"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/sns/SNSConnection.ts","../../src/sns/push.ts","../../src/sns/SNSPublisher.ts","../../src/sns/SNSSubscriber.ts"],"mappings":";;;;UAKiB;EAChB;EACA;EACA;EACA;IACC;IACA;IACA;;;qBAIW,yBAAyB;WAC5B,OAAI,mBAAA;UACL;UACA;UACA;EAER,YAAY,QAAQ;;;;;SAgBP,qBACZ,2BACE,QAAQ;EA8BL,WAAW;EAKX,SAAS;EAKf;;;;MAOI,aAAa;;;;MAOb;;;;;;;;;;;;;;;;;UCrEY;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;;EAEA;EACA,oBAAoB;IAAiB;IAAc;;;UAwCnC;;;;;EAKhB,oBAAoB,gBAAgB;;;wBAwBrB,gBAAgB,SAAS;;;;;;;wBAgBnB,iBACrB,SAAS,gBACT,UAAS,0BACP;;;;;wBAsCmB,uBACrB,SAAS,gBACT,WAAU,gBAAgB;EAAU;EAAa;KAC/C;UAWc;;EAEhB;;;;;;EAMA;;;;;;EAMA;;;;;;;;;;;;;;;;wBAiBqB,sBACrB,YAAY,eACZ,SAAS,+BACP;;;;;wBAiFa,WAAW,SAAS,gBAAgB;;;;;;MAQ/C;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MAEA;MACA;MACA,mBAAiB;QAlRsB;QAAe;;;;;qBAyR9C,gCAAgC;WACvB;EAArB,YAAqB;;qBAUT,kCAAkC;WAEpC;WACA;EAFV,YACU,aACA;;qBAUE,mCAAmC;WAC1B;EAArB,YAAqB;;qBAST,4BAA4B;WAE9B;WACA;EAFV,YACU,mBACA;;qBAWE,8BAA8B;WACrB;EAArB,YAAqB;;qBAST,4BAA4B;WACnB;EAArB,YAAqB;;qBAST,8BAA8B;WAEhC;WACA;EAFV,YACU,kBACA;;qBAWE,2BAA2B;WAClB;EAArB,YAAqB;;;;KCjZV;qBAEC,aAAa,iBAAiB,4CAC/B,eAAe;UAGjB;EADT,YACS,YAAY,eACpB,WAAU;;;;;SAOE,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,aAAa;EAQ5C,QAAQ,UAAU,aAAa;UAWvB;EAkBR,SAAS;;;;UC5CC;EAChB;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;qBAoBY,cAAc,iBAAiB,4CAChC,gBAAgB;UAUlB;UARD;UACA;UACA;UACA;UACA;UACA;EAER,YACS,YAAY,eACpB,UAAS;;;;;SAwBG,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,cAAc;EAoB7C,UACL,UAAU,oBACV,WAAW,SAAS,aAAa,gBAC/B;;;;EA2BG,QAAQ;UA6BA;UAwBA;UA4BA;;;;;;qBAgBF,wBAAwB;WACf;EAArB,YAAqB"}

package/dist/sns/index.d.mts

@@ -36,6 +36,159 @@ export declare class SNSConnection implements EventConnection {
   get topicArn(): string;
 }
 //#endregion
+//#region src/sns/push.d.ts
+/**
+ * SNS delivering to an HTTP(S) endpoint, rather than to a queue that is polled.
+ *
+ * SNS POSTs each message to the subscribed URL as JSON. That is the whole
+ * transport: no queue in between, no poller, and the endpoint is handed the
+ * same envelope a Lambda subscription receives inside `Records[].Sns` — so the
+ * handler that runs deployed can be the one that runs here.
+ *
+ * The endpoint is public, so a message is trusted only once its signature
+ * checks out against a certificate SNS itself serves. Anything else that POSTs
+ * there is somebody's guess at the shape.
+ */
+/** A message SNS POSTs to a subscribed HTTP endpoint. */
+interface SnsHttpMessage {
+  Type: 'Notification' | 'SubscriptionConfirmation' | 'UnsubscribeConfirmation';
+  MessageId: string;
+  TopicArn: string;
+  Message: string;
+  Timestamp: string;
+  SignatureVersion: string;
+  Signature: string;
+  SigningCertURL: string;
+  Subject?: string;
+  /** Confirmation messages only. */
+  Token?: string;
+  /** Confirmation messages only: GET it to confirm. */
+  SubscribeURL?: string;
+  /** Notifications only. */
+  UnsubscribeURL?: string;
+  MessageAttributes?: Record<string, {
+    Type: string;
+    Value: string;
+  }>;
+}
+interface VerifySnsMessageOptions {
+  /**
+   * Fetch the PEM at a certificate URL. `fetch` by default; replaceable so a
+   * test signs with its own key instead of SNS's.
+   */
+  fetchCertificate?: (url: string) => Promise<string>;
+}
+/** The string SNS signed for this message. */
+export declare function snsStringToSign(message: SnsHttpMessage): string;
+/**
+ * Check that SNS sent this message: the certificate is SNS's own, and the
+ * signature over the message's signed fields verifies against it.
+ *
+ * Throws rather than returning false, so a caller cannot forget to look.
+ */
+export declare function verifySnsMessage(message: SnsHttpMessage, options?: VerifySnsMessageOptions): Promise<void>;
+/**
+ * Confirm a subscription by visiting the URL SNS sent. Until this happens SNS
+ * delivers nothing to the endpoint.
+ */
+export declare function confirmSnsSubscription(message: SnsHttpMessage, request?: (url: string) => Promise<{
+  ok: boolean;
+  status: number;
+}>): Promise<void>;
+interface SubscribeHttpEndpointOptions {
+  /** The URL SNS POSTs to — `http:` or `https:`, which picks the protocol. */
+  endpoint: string;
+  /**
+   * The event types this endpoint takes. Becomes the subscription's filter
+   * policy on the `type` attribute `SNSPublisher` sets, so SNS sends nothing
+   * else — fan-out to every subscriber, each seeing only what it named.
+   */
+  events: readonly string[];
+  /**
+   * An SQS queue's ARN for what SNS gives up delivering. SNS retries an HTTP
+   * endpoint for a limited time and then drops the message, so without one an
+   * outage longer than that loses events.
+   */
+  deadLetterQueueArn?: string;
+}
+/**
+ * Subscribe an HTTP endpoint to the connection's topic, converging on one
+ * confirmed subscription with the filter asked for — so it is safe on every
+ * start:
+ *
+ * - **none yet** — subscribed; SNS sends a confirmation to the endpoint.
+ * - **confirmed** — its filter and dead-letter queue are brought up to date.
+ *   Subscribing again with different attributes is an error on SNS, and the
+ *   events a subscriber names change.
+ * - **stuck pending** — a confirmation that never landed (the endpoint was
+ *   down, or answered wrong). Subscribing the same endpoint again is a no-op
+ *   on an emulator, so it is dropped and subscribed afresh, which sends a new
+ *   confirmation.
+ */
+export declare function subscribeHttpEndpoint(connection: SNSConnection, options: SubscribeHttpEndpointOptions): Promise<string | undefined>;
+/**
+ * A pushed notification as the Lambda event SNS would have invoked a function
+ * with, so it can be handed to the same adaptor.
+ */
+export declare function toSnsEvent(message: SnsHttpMessage, subscriptionArn?: string): {
+  Records: {
+    EventSource: string;
+    EventVersion: string;
+    EventSubscriptionArn: string;
+    Sns: {
+      Type: "Notification" | "SubscriptionConfirmation" | "UnsubscribeConfirmation";
+      MessageId: string;
+      TopicArn: string;
+      Subject: string | null;
+      Message: string;
+      Timestamp: string;
+      SignatureVersion: string;
+      Signature: string;
+      SigningCertUrl: string;
+      UnsubscribeUrl: string;
+      MessageAttributes: Record<string, {
+        Type: string;
+        Value: string;
+      }>;
+    };
+  }[];
+};
+export declare class SnsCertificateUntrusted extends Error {
+  readonly url: string;
+  constructor(url: string);
+}
+export declare class SnsCertificateUnavailable extends Error {
+  readonly url: string;
+  readonly status: number;
+  constructor(url: string, status: number);
+}
+export declare class SnsSignatureVersionUnknown extends Error {
+  readonly version: string;
+  constructor(version: string);
+}
+export declare class SnsSignatureInvalid extends Error {
+  readonly messageId: string;
+  readonly topicArn: string;
+  constructor(messageId: string, topicArn: string);
+}
+export declare class SnsMessageTypeUnknown extends Error {
+  readonly type: string;
+  constructor(type: string);
+}
+export declare class SnsNotAConfirmation extends Error {
+  readonly type: string;
+  constructor(type: string);
+}
+export declare class SnsConfirmationFailed extends Error {
+  readonly topicArn: string;
+  readonly status: number;
+  constructor(topicArn: string, status: number);
+}
+export declare class SnsEndpointNotHttp extends Error {
+  readonly endpoint: string;
+  constructor(endpoint: string);
+}
+//#endregion
 //#region src/sns/SNSPublisher.d.ts
 type SNSPublisherOptions = {};
 export declare class SNSPublisher<TMessage extends PublishableMessage<string, any>> implements EventPublisher<TMessage> {
@@ -108,5 +261,5 @@ export declare class SnsQueueMissing extends Error {
   constructor(queueName: string | undefined);
 }
 //#endregion
-export { type SNSConnectionConfig, type SNSPublisherOptions, type SNSSubscriberOptions, type SnsAddress, snsUrl_d_exports as snsUrl };
+export { type SNSConnectionConfig, type SNSPublisherOptions, type SNSSubscriberOptions, type SnsAddress, type SnsHttpMessage, type SubscribeHttpEndpointOptions, type VerifySnsMessageOptions, snsUrl_d_exports as snsUrl };
 //# sourceMappingURL=index.d.mts.map

package/dist/sns/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/sns/SNSConnection.ts","../../src/sns/SNSPublisher.ts","../../src/sns/SNSSubscriber.ts"],"mappings":";;;;UAKiB;EAChB;EACA;EACA;EACA;IACC;IACA;IACA;;;qBAIW,yBAAyB;WAC5B,OAAI,mBAAA;UACL;UACA;UACA;EAER,YAAY,QAAQ;;;;;SAgBP,qBACZ,2BACE,QAAQ;EA8BL,WAAW;EAKX,SAAS;EAKf;;;;MAOI,aAAa;;;;MAOb;;;;KC1FO;qBAEC,aAAa,iBAAiB,4CAC/B,eAAe;UAGjB;EADT,YACS,YAAY,eACpB,WAAU;;;;;SAOE,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,aAAa;EAQ5C,QAAQ,UAAU,aAAa;UAWvB;EAkBR,SAAS;;;;UC5CC;EAChB;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;qBAoBY,cAAc,iBAAiB,4CAChC,gBAAgB;UAUlB;UARD;UACA;UACA;UACA;UACA;UACA;EAER,YACS,YAAY,eACpB,UAAS;;;;;SAwBG,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,cAAc;EAoB7C,UACL,UAAU,oBACV,WAAW,SAAS,aAAa,gBAC/B;;;;EA2BG,QAAQ;UA6BA;UAwBA;UA4BA;;;;;;qBAgBF,wBAAwB;WACf;EAArB,YAAqB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/sns/SNSConnection.ts","../../src/sns/push.ts","../../src/sns/SNSPublisher.ts","../../src/sns/SNSSubscriber.ts"],"mappings":";;;;UAKiB;EAChB;EACA;EACA;EACA;IACC;IACA;IACA;;;qBAIW,yBAAyB;WAC5B,OAAI,mBAAA;UACL;UACA;UACA;EAER,YAAY,QAAQ;;;;;SAgBP,qBACZ,2BACE,QAAQ;EA8BL,WAAW;EAKX,SAAS;EAKf;;;;MAOI,aAAa;;;;MAOb;;;;;;;;;;;;;;;;;UCrEY;EAChB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;EAEA;;EAEA;;EAEA;EACA,oBAAoB;IAAiB;IAAc;;;UAwCnC;;;;;EAKhB,oBAAoB,gBAAgB;;;wBAwBrB,gBAAgB,SAAS;;;;;;;wBAgBnB,iBACrB,SAAS,gBACT,UAAS,0BACP;;;;;wBAsCmB,uBACrB,SAAS,gBACT,WAAU,gBAAgB;EAAU;EAAa;KAC/C;UAWc;;EAEhB;;;;;;EAMA;;;;;;EAMA;;;;;;;;;;;;;;;;wBAiBqB,sBACrB,YAAY,eACZ,SAAS,+BACP;;;;;wBAiFa,WAAW,SAAS,gBAAgB;;;;;;MAQ/C;MACA;MACA;MACA;MACA;MACA;MACA;MACA;MAEA;MACA;MACA,mBAAiB;QAlRsB;QAAe;;;;;qBAyR9C,gCAAgC;WACvB;EAArB,YAAqB;;qBAUT,kCAAkC;WAEpC;WACA;EAFV,YACU,aACA;;qBAUE,mCAAmC;WAC1B;EAArB,YAAqB;;qBAST,4BAA4B;WAE9B;WACA;EAFV,YACU,mBACA;;qBAWE,8BAA8B;WACrB;EAArB,YAAqB;;qBAST,4BAA4B;WACnB;EAArB,YAAqB;;qBAST,8BAA8B;WAEhC;WACA;EAFV,YACU,kBACA;;qBAWE,2BAA2B;WAClB;EAArB,YAAqB;;;;KCjZV;qBAEC,aAAa,iBAAiB,4CAC/B,eAAe;UAGjB;EADT,YACS,YAAY,eACpB,WAAU;;;;;SAOE,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,aAAa;EAQ5C,QAAQ,UAAU,aAAa;UAWvB;EAkBR,SAAS;;;;UC5CC;EAChB;EACA;EACA;EACA;EACA;;;;;;;;;;;;;;;;;;;qBAoBY,cAAc,iBAAiB,4CAChC,gBAAgB;UAUlB;UARD;UACA;UACA;UACA;UACA;UACA;EAER,YACS,YAAY,eACpB,UAAS;;;;;SAwBG,qBACZ,iBAAiB,iCAChB,2BAA2B,QAAQ,cAAc;EAoB7C,UACL,UAAU,oBACV,WAAW,SAAS,aAAa,gBAC/B;;;;EA2BG,QAAQ;UA6BA;UAwBA;UA4BA;;;;;;qBAgBF,wBAAwB;WACf;EAArB,YAAqB"}

package/dist/sns/index.mjs

@@ -2,7 +2,259 @@ import "../types-Bk5JM6MP.mjs";
 import { n as SQSConnection, t as SQSSubscriber } from "../SQSSubscriber-BXLE_1L3.mjs";
 import { parse, t as snsUrl_exports } from "./snsUrl.mjs";
 import { CreateQueueCommand, DeleteQueueCommand, GetQueueAttributesCommand, SQSClient, SetQueueAttributesCommand } from "@aws-sdk/client-sqs";
-import { PublishCommand, SNSClient, SubscribeCommand, UnsubscribeCommand } from "@aws-sdk/client-sns";
+import { createVerify } from "node:crypto";
+import { GetSubscriptionAttributesCommand, ListSubscriptionsByTopicCommand, PublishCommand, SNSClient, SetSubscriptionAttributesCommand, SubscribeCommand, UnsubscribeCommand } from "@aws-sdk/client-sns";
+//#region src/sns/push.ts
+/** The fields signed, in the order SNS signs them, per message type. */
+const SIGNED_FIELDS = {
+	Notification: [
+		"Message",
+		"MessageId",
+		"Subject",
+		"Timestamp",
+		"TopicArn",
+		"Type"
+	],
+	SubscriptionConfirmation: [
+		"Message",
+		"MessageId",
+		"SubscribeURL",
+		"Timestamp",
+		"Token",
+		"TopicArn",
+		"Type"
+	],
+	UnsubscribeConfirmation: [
+		"Message",
+		"MessageId",
+		"SubscribeURL",
+		"Timestamp",
+		"Token",
+		"TopicArn",
+		"Type"
+	]
+};
+/**
+* Where SNS serves its signing certificates. Anywhere else is a certificate
+* the sender chose, which would let the sender sign its own forgeries.
+*/
+const SNS_CERTIFICATE_HOST = /^sns\.[a-z0-9-]+\.amazonaws\.com(\.cn)?$/;
+const certificates = /* @__PURE__ */ new Map();
+async function defaultFetchCertificate(url) {
+	const response = await fetch(url);
+	if (!response.ok) throw new SnsCertificateUnavailable(url, response.status);
+	return response.text();
+}
+/**
+* A URL, or undefined for a value that is not one at all — what an emulator
+* sends — so it is untrusted rather than a crash. (`URL.parse` is Node 22.1+.)
+*/
+function parseUrl(value) {
+	try {
+		return new URL(String(value));
+	} catch {
+		return;
+	}
+}
+/** The string SNS signed for this message. */
+function snsStringToSign(message) {
+	const fields = SIGNED_FIELDS[message.Type];
+	if (!fields) throw new SnsMessageTypeUnknown(String(message.Type));
+	return fields.filter((field) => message[field] !== void 0).map((field) => `${field}\n${message[field]}\n`).join("");
+}
+/**
+* Check that SNS sent this message: the certificate is SNS's own, and the
+* signature over the message's signed fields verifies against it.
+*
+* Throws rather than returning false, so a caller cannot forget to look.
+*/
+async function verifySnsMessage(message, options = {}) {
+	const url = parseUrl(message.SigningCertURL);
+	if (url?.protocol !== "https:" || !SNS_CERTIFICATE_HOST.test(url.hostname)) throw new SnsCertificateUntrusted(message.SigningCertURL);
+	const algorithm = message.SignatureVersion === "1" ? "RSA-SHA1" : message.SignatureVersion === "2" ? "RSA-SHA256" : void 0;
+	if (!algorithm) throw new SnsSignatureVersionUnknown(message.SignatureVersion);
+	const fetchCertificate = options.fetchCertificate ?? defaultFetchCertificate;
+	let certificate = certificates.get(message.SigningCertURL);
+	if (!certificate || options.fetchCertificate) {
+		certificate = fetchCertificate(message.SigningCertURL);
+		if (!options.fetchCertificate) {
+			certificates.set(message.SigningCertURL, certificate);
+			certificate.catch(() => certificates.delete(message.SigningCertURL));
+		}
+	}
+	const verifier = createVerify(algorithm);
+	verifier.update(snsStringToSign(message), "utf8");
+	if (!verifier.verify(await certificate, message.Signature, "base64")) throw new SnsSignatureInvalid(message.MessageId, message.TopicArn);
+}
+/**
+* Confirm a subscription by visiting the URL SNS sent. Until this happens SNS
+* delivers nothing to the endpoint.
+*/
+async function confirmSnsSubscription(message, request = fetch) {
+	if (message.Type !== "SubscriptionConfirmation" || !message.SubscribeURL) throw new SnsNotAConfirmation(message.Type);
+	const response = await request(message.SubscribeURL);
+	if (!response.ok) throw new SnsConfirmationFailed(message.TopicArn, response.status);
+}
+/**
+* Subscribe an HTTP endpoint to the connection's topic, converging on one
+* confirmed subscription with the filter asked for — so it is safe on every
+* start:
+*
+* - **none yet** — subscribed; SNS sends a confirmation to the endpoint.
+* - **confirmed** — its filter and dead-letter queue are brought up to date.
+*   Subscribing again with different attributes is an error on SNS, and the
+*   events a subscriber names change.
+* - **stuck pending** — a confirmation that never landed (the endpoint was
+*   down, or answered wrong). Subscribing the same endpoint again is a no-op
+*   on an emulator, so it is dropped and subscribed afresh, which sends a new
+*   confirmation.
+*/
+async function subscribeHttpEndpoint(connection, options) {
+	const protocol = new URL(options.endpoint).protocol.replace(":", "");
+	if (protocol !== "http" && protocol !== "https") throw new SnsEndpointNotHttp(options.endpoint);
+	const attributes = {
+		FilterPolicyScope: "MessageAttributes",
+		FilterPolicy: JSON.stringify({ type: [...options.events] })
+	};
+	if (options.deadLetterQueueArn) attributes.RedrivePolicy = JSON.stringify({ deadLetterTargetArn: options.deadLetterQueueArn });
+	const client = connection.snsClient;
+	const existing = await existingSubscription(connection, options.endpoint);
+	if (existing) {
+		const { Attributes = {} } = await client.send(new GetSubscriptionAttributesCommand({ SubscriptionArn: existing }));
+		if (Attributes.PendingConfirmation === "true") await client.send(new UnsubscribeCommand({ SubscriptionArn: existing }));
+		else {
+			for (const [name, value] of Object.entries(attributes)) {
+				if (Attributes[name] === value) continue;
+				await client.send(new SetSubscriptionAttributesCommand({
+					SubscriptionArn: existing,
+					AttributeName: name,
+					AttributeValue: value
+				}));
+			}
+			return existing;
+		}
+	}
+	const { SubscriptionArn } = await client.send(new SubscribeCommand({
+		TopicArn: connection.topicArn,
+		Protocol: protocol,
+		Endpoint: options.endpoint,
+		Attributes: attributes,
+		ReturnSubscriptionArn: true
+	}));
+	return SubscriptionArn;
+}
+/**
+* The ARN of the endpoint's subscription to the topic, if it has one SNS will
+* name. (Real SNS lists a pending one as `PendingConfirmation`, with no ARN to
+* act on — and resends its confirmation on a new Subscribe anyway.)
+*/
+async function existingSubscription(connection, endpoint) {
+	let NextToken;
+	do {
+		const page = await connection.snsClient.send(new ListSubscriptionsByTopicCommand({
+			TopicArn: connection.topicArn,
+			NextToken
+		}));
+		const match = page.Subscriptions?.find((s) => s.Endpoint === endpoint && s.SubscriptionArn?.startsWith("arn:"));
+		if (match) return match.SubscriptionArn;
+		NextToken = page.NextToken;
+	} while (NextToken);
+}
+/**
+* A pushed notification as the Lambda event SNS would have invoked a function
+* with, so it can be handed to the same adaptor.
+*/
+function toSnsEvent(message, subscriptionArn = "") {
+	return { Records: [{
+		EventSource: "aws:sns",
+		EventVersion: "1.0",
+		EventSubscriptionArn: subscriptionArn,
+		Sns: {
+			Type: message.Type,
+			MessageId: message.MessageId,
+			TopicArn: message.TopicArn,
+			Subject: message.Subject ?? null,
+			Message: message.Message,
+			Timestamp: message.Timestamp,
+			SignatureVersion: message.SignatureVersion,
+			Signature: message.Signature,
+			SigningCertUrl: message.SigningCertURL,
+			UnsubscribeUrl: message.UnsubscribeURL ?? "",
+			MessageAttributes: message.MessageAttributes ?? {}
+		}
+	}] };
+}
+var SnsCertificateUntrusted = class extends Error {
+	url;
+	constructor(url) {
+		super(`The SNS message names a signing certificate at '${url}', which is not an https URL on sns.<region>.amazonaws.com. Only SNS can send to this endpoint; reject the request.`);
+		this.url = url;
+		this.name = "SnsCertificateUntrusted";
+	}
+};
+var SnsCertificateUnavailable = class extends Error {
+	url;
+	status;
+	constructor(url, status) {
+		super(`Fetching the SNS signing certificate at '${url}' answered ${status}. The message cannot be verified, so it is not handled; SNS will retry.`);
+		this.url = url;
+		this.status = status;
+		this.name = "SnsCertificateUnavailable";
+	}
+};
+var SnsSignatureVersionUnknown = class extends Error {
+	version;
+	constructor(version) {
+		super(`SNS signature version '${version}' is not one this endpoint verifies (it knows '1' and '2'). Reject the request.`);
+		this.version = version;
+		this.name = "SnsSignatureVersionUnknown";
+	}
+};
+var SnsSignatureInvalid = class extends Error {
+	messageId;
+	topicArn;
+	constructor(messageId, topicArn) {
+		super(`SNS message '${messageId}' from '${topicArn}' does not verify against its signing certificate. It was not sent by SNS, or was altered on the way; reject it.`);
+		this.messageId = messageId;
+		this.topicArn = topicArn;
+		this.name = "SnsSignatureInvalid";
+	}
+};
+var SnsMessageTypeUnknown = class extends Error {
+	type;
+	constructor(type) {
+		super(`'${type}' is not an SNS message type (Notification, SubscriptionConfirmation, UnsubscribeConfirmation). Reject it.`);
+		this.type = type;
+		this.name = "SnsMessageTypeUnknown";
+	}
+};
+var SnsNotAConfirmation = class extends Error {
+	type;
+	constructor(type) {
+		super(`Only a SubscriptionConfirmation carries a URL to confirm; this is a '${type}'.`);
+		this.type = type;
+		this.name = "SnsNotAConfirmation";
+	}
+};
+var SnsConfirmationFailed = class extends Error {
+	topicArn;
+	status;
+	constructor(topicArn, status) {
+		super(`Confirming the subscription to '${topicArn}' answered ${status}. SNS will deliver nothing until it is confirmed; it resends the confirmation, or subscribe the endpoint again.`);
+		this.topicArn = topicArn;
+		this.status = status;
+		this.name = "SnsConfirmationFailed";
+	}
+};
+var SnsEndpointNotHttp = class extends Error {
+	endpoint;
+	constructor(endpoint) {
+		super(`'${endpoint}' is not an http(s) URL. SNS pushes to an HTTP endpoint; subscribe a queue for anything else.`);
+		this.endpoint = endpoint;
+		this.name = "SnsEndpointNotHttp";
+	}
+};
+//#endregion
 //#region src/sns/SNSConnection.ts
 var SNSConnection = class SNSConnection {
 	type = "sns";
@@ -245,6 +497,6 @@ var SnsQueueMissing = class extends Error {
 	}
 };
 //#endregion
-export { SNSConnection, SNSPublisher, SNSSubscriber, SnsQueueMissing, snsUrl_exports as snsUrl };
+export { SNSConnection, SNSPublisher, SNSSubscriber, SnsCertificateUnavailable, SnsCertificateUntrusted, SnsConfirmationFailed, SnsEndpointNotHttp, SnsMessageTypeUnknown, SnsNotAConfirmation, SnsQueueMissing, SnsSignatureInvalid, SnsSignatureVersionUnknown, confirmSnsSubscription, snsStringToSign, snsUrl_exports as snsUrl, subscribeHttpEndpoint, toSnsEvent, verifySnsMessage };
 
 //# sourceMappingURL=index.mjs.map