@shware/workflow 3.3.0 → 4.1.0

package/README.md

@@ -564,9 +564,23 @@ with its secret in the environment:
 | `android` | `fcm: { androidChannelId? }`                   | `GOOGLE_APPLICATION_CREDENTIALS_BASE64` | `@shware/workflow/fcm`     |
 | `web`     | `webPush: { subject, openedEvent? }`           | `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY` | `@shware/workflow/webpush` |
 
-A secret is only read when something is sent on that platform. Tokens APNs,
-FCM or a push service report as gone are removed, and waits on
-`reachable('push')` wake on every device change.
+A secret is only read when something is sent on that platform. Only a token
+the provider reports as gone is removed (and waits on `reachable('push')` wake
+on every device change); a configuration error keeps the device and fails the
+step without retrying, and a transient answer is retried:
+
+| Provider | Token removed, copy settled         | Settled, device kept                          | Failed, no retry (`PermanentError`)                                                                                   | Retried                                                                 |
+| -------- | ----------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| APNs     | 410; `Unregistered`, `ExpiredToken` | `BadDeviceToken` (a token or the environment) | `DeviceTokenNotForTopic`, `TopicDisallowed`, `BadTopic`, `MissingTopic`, bad certificate or provider token, other 4xx | 403 `ExpiredProviderToken` (re-signed), 429, 5xx                        |
+| FCM      | `UNREGISTERED`; 404 `NOT_FOUND`     | `INVALID_ARGUMENT`                            | `SENDER_ID_MISMATCH`, `THIRD_PARTY_AUTH_ERROR`, other 4xx                                                             | 401 (access token re-minted), `QUOTA_EXCEEDED`, `UNAVAILABLE`, 429, 5xx |
+| Web Push | 404, 410                            | —                                             | payload over 3993 bytes (refused before sending), 400, 401, 403, 413, other 4xx                                       | 429, 5xx                                                                |
+
+Every APNs request carries `apns-id` and `apns-collapse-id`, and every web
+push a `Topic`, derived from the copy's idempotency key, so a copy sent again
+after a lost checkpoint collapses on the device. Provider credentials are kept
+per host (`ApnsProviderToken`, `FcmAccessToken`, `VapidSigner`): the APNs
+provider token, the FCM access token and the VAPID key are reused across runs,
+while the senders themselves are built per run.
 
 `apns.environment` maps a mode to `sandbox` or `production`; unlisted modes use
 `production` in production and `sandbox` otherwise. Generate a VAPID pair once
@@ -652,8 +666,10 @@ Secrets never go in the config; the Worker reads them from its environment:
 | `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY` | The Web Push key pair                                      |
 | `APNS_RELAY_ORIGIN`                     | Development only: the local APNs relay                     |
 
-`journeyWorker` also takes `observer`, `messages` and `runtime` overrides, and
-`contractMode: 'report'` to log contract refusals instead of answering 400.
+`journeyWorker` (and `journeyLambda`) also take `observer`, `messages` and `runtime` overrides,
+`contractMode: 'report'` to log contract refusals instead of answering 400, and `authorize` to
+replace the `API_TOKEN` bearer with a check of your own (see
+[AWS deployment notes](#aws-deployment-notes)).
 
 ## `JourneyClient`
 
@@ -726,20 +742,47 @@ backward-compatible changes, so a new required prop means a new id.
 
 ## Cloudflare setup
 
-The default store needs three bindings, named as in `JourneyEnv`:
+The default store needs two bindings, named as in `JourneyEnv`:
 
-| Binding       | Type         | Holds                                     |
-| ------------- | ------------ | ----------------------------------------- |
-| `WORKFLOW_KV` | KV namespace | Compiled IR, content-addressed by hash    |
-| `DB`          | D1 database  | Events, profiles, routing, entries, wakes |
-| `JOURNEY`     | Workflow     | The `JourneyRunner` entrypoint            |
+| Binding   | Type        | Holds                                                  |
+| --------- | ----------- | ------------------------------------------------------ |
+| `DB`      | D1 database | Events, profiles, routing, compiled IR, entries, wakes |
+| `JOURNEY` | Workflow    | The `JourneyRunner` entrypoint                         |
 
-A Worker on Postgres needs only `JOURNEY`. Add the `EMAIL` send_email binding
+The compiled IR lives in D1 with the routes, never in a KV namespace: KV is eventually consistent
+while the routes in D1 are not, so an instance started in another colo right after a deploy could
+miss its IR.
+
+The Worker needs the `nodejs_compat` compatibility flag (the bearer check uses
+`node:crypto`'s `timingSafeEqual`). A Worker on Postgres needs only `JOURNEY`. Add the `EMAIL` send_email binding
 when it sends through Cloudflare Email (`cloudflareEmailTransport({ binding: env.EMAIL })`), and a `triggers.crons` entry with `scheduled`
 exported to run the segment sweep.
 
-Set `API_TOKEN` in production. Without it every mutating endpoint is open, and
-`/deploy` rewrites the whole routing table.
+Set `API_TOKEN` in production: a host whose `ENVIRONMENT` resolves to `production` refuses every
+request but `GET /health` and `/t/...` with a 503 until it is set. Any other mode (`development`,
+say) runs open, for local work only — `/deploy` rewrites the whole routing table.
+
+Erasing a user (`POST /users/forget`) commits an erasure tombstone first,
+which every write about the user is conditional on from then on. A runner
+admits itself against that tombstone before its first effect — before the
+observer hears of it, before any action or send — on every invocation and on
+every replay after an eviction, never from a checkpoint: an instance whose
+`create` lands after the tombstone, or that wakes after it, exits without
+running. The erasure stops the admitted instances (`terminate`), and only once
+each is known stopped deletes the data; `erased: true` means every admitted
+runner was confirmed stopped, the entries never admitted can never run, and
+the data is gone. An admitted instance that will not stop answers
+`erased: false` and the scheduled sweep retries it. Every write about the user
+runs in the user's locked transaction, the lock the tombstone itself takes: a
+write either committed before the tombstone and is deleted by the erase, or
+waited for the lock and is refused by the tombstone it then sees. There is no
+window to come back for and no second pass; the tombstone stays, so a late
+write cannot bring the user back.
+
+One database per host. The routing tables are global (`triggers`, `segments`, the live
+`deployment` row), so two Workers on one D1 database or one Postgres schema would swap each
+other's routes on every deploy: give staging and production their own database or schema
+(`database: { schema }`).
 
 The D1 schema ships with the package. Apply it before the first deploy:
 
@@ -754,7 +797,31 @@ the single source for both.
 There are no migrations, and re-applying the file is not one: every statement is
 `CREATE TABLE IF NOT EXISTS`, so an existing database keeps its old tables and
 the first insert needing a new column fails. Recreate it instead. The demo has
-`pnpm db:reset`.
+`pnpm db:reset`. The `events` key is `(user_id, id)`, and `workflow_ir` holds the compiled IR.
+
+### Cloudflare deployment notes
+
+- **Email transport.** Pass `email` explicitly: `cloudflareEmailTransport({ binding: env.EMAIL })`
+  for Cloudflare Email, or `sesEmailTransport({ region, credentials })` with credentials from the
+  Worker's env, since a Worker has no execution role. A Worker whose workflows email without one
+  fails at startup.
+- **List-Unsubscribe.** Cloudflare Email rejects a `List-Unsubscribe` header with a non-TLS URI, so
+  the one-click header is only sent with an https `WORKFLOW_ORIGIN`. `wrangler dev` on
+  `http://localhost` sends none.
+- **Workflows limits** (paid plan):
+  - An instance's wall time is unlimited.
+  - A single `step.sleep` lasts at most 365 days.
+  - 10,000 steps per instance by default, configurable up to 25,000. Sleeps do not count, but every
+    wait attempt costs a few steps.
+  - A step's result is at most 1 MiB.
+  - A completed instance's state is kept 30 days.
+- **Authorization.** Set `API_TOKEN` with `wrangler secret put`, or pass `authorize` (below).
+  The tracking routes (`/t/...`) stay public by design.
+- **Deploying.** With the `CF_VERSION_METADATA` binding and a Postgres store, each `wrangler deploy`
+  makes its own bundle live (see [Postgres](#postgres)). On D1, call `POST /bundle/deploy`.
+- **APNs in development.** `wrangler dev` (workerd) cannot make HTTP/2 subrequests: run
+  `@shware/workflow/apns-relay` and point `APNS_RELAY_ORIGIN` at it. A deployed Worker needs no
+  relay.
 
 ## AWS Lambda
 
@@ -804,11 +871,18 @@ re-entered as a second execution. Retries stop after 12 hours (`startRetryMs`,
 keep it under the execution retention) and the start is left unresolved. A
 failed entry that is entered again gets a new execution, never the closed one.
 
-Erasing a user (`POST /users/forget`) stops their executions, then waits
-`stopDrainMs` (15 minutes by default; at least the function's timeout) before
-erasing: a stop does not interrupt an invocation already running, which goes on
-to its next checkpoint. Until then the erasure answers `erased: false` and the
-sweep finishes it.
+Erasing a user (`POST /users/forget`) commits the tombstone, stops their
+admitted executions, then waits `stopDrainMs` (15 minutes by default; at least
+the function's timeout) before erasing: a stop does not interrupt an invocation
+already running, which goes on to its next checkpoint. Until then the erasure
+answers `erased: false` and the sweep finishes it; the drain is one judgment
+for every path — the sweep's reconcile keeps a stopped execution's entry
+`running` until the drain has passed, and an execution the platform reports
+stopped before the stop was recorded is dated at its first sighting, never
+later. An execution whose runner never admitted itself needs no stop: its run
+entry meets the tombstone and exits, and so does a wake of a stopped one. The
+tombstone takes the user's lock, which every write about the user also takes,
+so nothing of theirs lands after it and no second pass is needed.
 
 Deploy one artifact per version: publish a numbered version and point the
 `live` alias, which the Function URL is bound to, at it. Each version carries its
@@ -832,19 +906,122 @@ Workflow:
     FunctionUrlConfig: { AuthType: NONE, InvokeMode: BUFFERED }
 ```
 
-The execution role needs the durable checkpoint permissions,
-`lambda:InvokeFunction` on its own versions, `lambda:SendDurableExecutionCallbackSuccess`,
-`lambda:GetDurableExecution`, `lambda:ListDurableExecutionsByFunction` and
-`lambda:StopDurableExecution`, plus `ses:SendEmail` when it sends through SES.
-With `AuthType: NONE`, scope the public `lambda:InvokeFunction` grant to
-`lambda:InvokedViaFunctionUrl = true` so the URL cannot be used to invoke the
-function directly. APNs goes over Node's HTTP/2 client; a custom domain needs
-CloudFront (or another HTTPS proxy) in front of the Function URL.
+### AWS deployment notes
+
+Checked against a real durable Lambda (Node 24, us-east-1).
+
+**Function URL: `AuthType: NONE`, with the API protected in the app.** Not every caller can
+sign a request:
+
+| Caller                                     | Routes                                                   |
+| ------------------------------------------ | -------------------------------------------------------- |
+| Your backend                               | `/events`, `/identify`, `/devices`, `/users/forget`, ... |
+| Recipients' mail clients and browsers      | `/t/o`, `/t/l`, `/t/u`                                   |
+| Gmail / Yahoo one-click unsubscribe        | `POST /t/u/<message>` (RFC 8058)                         |
+| iOS notification extension, service worker | `POST /t/d`, `POST /t/p`                                 |
+
+An alias has one URL and one auth type, and the tracking and one-click routes must stay public:
+
+- `AWS_IAM` would break those routes. SigV4 also takes the `Authorization` header, so the bearer
+  could not travel with it.
+- CloudFront's origin access control (OAC) does not help either: with OAC, every POST must carry
+  the body's SHA-256 in `x-amz-content-sha256`, and a mail provider's one-click POST does not.
+
+Keep the routes public and protect the API in the app: the `API_TOKEN` bearer by default, or
+your own `authorize`. Production refuses to serve without one of the two.
+
+**Your own authorization.** `authorize(request, env)` replaces the bearer check on every API
+route, in any format you choose: an HMAC over the body, a JWT, a header your proxy adds. It
+receives a copy of the request, so it can read the body, and the env the host validated. True
+lets the request through, false answers 401, and a throw answers 500 rather than letting the
+request in. The tracking routes and `/health` never ask it. `bearerMatches` and
+`timingSafeEqual` are exported for building one:
+
+```ts
+import { journeyLambda, timingSafeEqual } from '@shware/workflow/aws';
+
+journeyLambda({
+  // ...
+  authorize: async (request, env) =>
+    timingSafeEqual(
+      request.headers.get('x-signature') ?? '',
+      await hmac(env.SECRET, await request.text())
+    ),
+});
+```
+
+**Resource policy.** Grant `lambda:InvokeFunctionUrl` to everyone (`FunctionUrlAuthType: NONE`)
+and `lambda:InvokeFunction` only with `lambda:InvokedViaFunctionUrl = true`, so the URL cannot
+be used to invoke the function directly.
+
+**Put CloudFront and WAF in front, without OAC.** A custom domain needs CloudFront (or another
+HTTPS proxy) anyway; Route 53 alone cannot terminate TLS for a Function URL. Add a rate-based WAF
+rule there: every request that reaches the function starts a durable execution and is billed,
+even one the app answers 401. Reserved concurrency caps what a flood can cost.
+
+**What a request costs.** Every Function URL request is a durable execution of its own:
+
+| Execution                                   | Durable ops | Per million |
+| ------------------------------------------- | ----------- | ----------- |
+| `GET` (pixel, redirect, `/health`), no step | 1           | about $9    |
+| `POST` (an event, an identify), one step    | 2           | about $17   |
+| A plain, non-durable Lambda for comparison  | -           | about $1    |
+| A journey: email, delay, one wake-up, email | 24          | about $190  |
+
+Durable operations cost $8 per million, on top of Lambda's request and duration charges. That is
+negligible at thousands of requests a month and worth a second, non-durable function for HTTP at
+tens of millions. Server-side latency stays small: `/health` takes about 6 ms, a write 40–300 ms.
+
+**Quotas.**
+
+- Starting durable executions: 3,000 per second (6,000 in us-east-1, us-west-2 and eu-west-1).
+  HTTP requests and journey starts share it.
+- 30,000 operations per execution, which cannot be raised. A wait attempt costs about five: the
+  callback plus four steps.
+- 1 MB per operation's payload. Reads (`GET`, `HEAD`) are answered outside a step so their bodies
+  are not checkpointed.
+
+**Timeouts and retention.**
+
+- Set `DurableConfig.ExecutionTimeout` to the longest journey (waits, delays and the goal
+  window), up to 366 days, and pass the same value as `journeyLambda({ executionTimeoutMs })`: a
+  workflow that could outlive it fails at startup instead of being stopped midway.
+- `RetentionPeriodInDays` (1–90) only keeps history after an execution ends. Keep `startRetryMs`
+  (12 hours) well under it.
+- Keep `stopDrainMs` (15 minutes) at least the function's `Timeout`: a stop does not interrupt a
+  running invocation.
+
+**Execution role.**
+
+- `AWSLambdaBasicDurableExecutionRolePolicy` (checkpoints, state, logs).
+- On `arn:...:function:<name>` and `arn:...:function:<name>:*`: `lambda:InvokeFunction`,
+  `lambda:SendDurableExecutionCallbackSuccess`, `lambda:GetDurableExecution`,
+  `lambda:StopDurableExecution` and `lambda:ListDurableExecutionsByFunction`. Durable execution
+  ARNs carry the version, so an unqualified ARN alone matches nothing.
+- `ses:SendEmail` when sending through SES.
+
+**Versions.**
+
+- Publish numbered versions behind the `live` alias. `$LATEST` lets a paused execution resume on
+  changed code.
+- Do not delete a version while executions are pinned to it.
+- Rolling the alias back does not roll the routes back: the newer bundle stays live until
+  `POST /bundle/deploy` from the restored version.
+
+**Emails.** The one-click unsubscribe header needs an https `WORKFLOW_ORIGIN`; over http no
+`List-Unsubscribe` is sent. Mailbox providers honour the header only when DKIM signs it, so check
+one real message for `dkim=pass` with `list-unsubscribe` in `h=`.
+
+**Memory.** Size it for the app; the store is remote. APNs goes over the package's Node HTTP/2
+client, because Node 24's `fetch` speaks HTTP/1.1 only (see `src/http2-client.ts`).
 
 ## Postgres
 
 A host on Postgres (through Hyperdrive, say) keeps Cloudflare Workflows for
-execution and the data in its own database:
+execution and the data in its own database. Turn Hyperdrive's query caching off for this
+database (`caching: { disabled: true }` on the Hyperdrive config): the engine reads wake
+subscriptions, profiles and segment membership right after writing them, and a cached answer
+up to 60 seconds old misses wakes and decides on stale data.
 
 ```ts
 const journeys = journeyWorker<Env>({
@@ -859,7 +1036,10 @@ says `database: { schema }`, so their short names never meet the app's. The
 host owns the migrations. `npx workflow-ui generate --out <file>` (from
 `@shware/workflow-ui`) writes the tables as one drizzle file on that schema;
 re-export it from your drizzle schema and let drizzle-kit write the migration.
-Run `--check` in CI to catch an SDK upgrade that changed them. Without drizzle,
+Run `--check` in CI to catch an SDK upgrade that changed them. The unique index
+on `event` is on `(user_id, event_id)`: regenerate and migrate before deploying —
+the deploy check verifies the unique indexes as well as the columns, and refuses
+to run until they match. Without drizzle,
 `renderPostgresDdl()` returns the same tables as plain DDL. Nothing creates or
 alters them at runtime: `POST /bundle/deploy` checks the live database first
 and answers 503 with every missing table or column.
@@ -910,13 +1090,22 @@ On Postgres the engine also keeps:
 
 `handleRequest` serves the ingest API:
 
-- `GET /health` is the only unauthenticated one.
+- `GET /health` is the only unauthenticated one. Every other route asks the
+  host's `authorize`, or without one the `API_TOKEN` bearer: its scheme is
+  matched case-insensitively and the token compared in constant time.
 - `POST /events` takes `{ userId, event, payload?, ts?, id? }` and answers with
   the id the occurrence was recorded under. Event names beginning with `$` are
-  reserved for internal use.
+  reserved for internal use. `ts` is epoch milliseconds: a non-negative integer
+  no later than five minutes ahead of the host's clock (400 otherwise).
 - `POST /identify` takes `{ userId, props }` and merges the properties into the
-  profile. A property set to `null` is removed, which is the only way to unset
-  one.
+  profile. Values are scalars (string, number, boolean); a property set to
+  `null` is removed, which is the only way to unset one. Nested objects are
+  refused with a 400.
+- A user with an erasure tombstone (`POST /users/forget`, finished or not) is
+  refused on `/events`, `/identify` and `/devices` with a 410: nothing is
+  written about them between the stop of their journeys and the erase, and the
+  id is never reactivated after it.
+- A body that is not JSON answers 400, never 500.
 - `POST /devices` takes `{ userId, token, platform, ts? }`;
   `POST /devices/unbind` and `POST /devices/remove` take `{ token }`.
 - `POST /messages/opened` takes `{ userId, messageId }`.
@@ -931,8 +1120,8 @@ anything is stored, woken or started.
 
 ### Give each event an `id`
 
-`id` is the occurrence's identity, and sending the same one twice records it
-once. This matters because every count- and window-based condition reads the
+`id` is the occurrence's identity **for that user**, and sending the same one
+twice records it once. This matters because every count- and window-based condition reads the
 event log, so a second copy of one event silently changes what a journey
 decides.
 
@@ -947,7 +1136,8 @@ you can reproduce and the retry costs nothing.
 
 Use something that identifies the occurrence, not the event name: a row id from
 your own system, an upstream webhook's delivery id, or a message id from your
-queue. Workflows emitting events through `.sendEvent()` already do this, passing
+queue. The id is scoped to the user (the unique key is `(user_id, event_id)`),
+so two users may reuse one id without one of them losing their event. Workflows emitting events through `.sendEvent()` already do this, passing
 the node's identity within the running instance.
 
 ## Entry policy
@@ -970,10 +1160,10 @@ is a design question this package does not yet answer.
 | `@shware/workflow/postgres-js` | `postgresJsStore`, the Postgres store over postgres.js (peer `postgres`)                           |
 | `@shware/workflow/react-email` | `registryRenderer`, the email renderer over the registry (peers `react`, `react-dom`)              |
 | `@shware/workflow/push`        | `registryPushRenderer`, push content from the registry                                             |
-| `@shware/workflow/apns`        | `ApnsPushSender`, token-based APNs over HTTP/2                                                     |
+| `@shware/workflow/apns`        | `ApnsPushSender` over an `ApnsProviderToken`, token-based APNs over HTTP/2                         |
 | `@shware/workflow/apns-relay`  | `startApnsRelay`, the Node HTTP/1.1 to HTTP/2 relay for `wrangler dev`                             |
-| `@shware/workflow/fcm`         | `FcmPushSender`, FCM HTTP v1 for Android                                                           |
-| `@shware/workflow/webpush`     | `WebPushSender` and `generateVapidKeys`, standard Web Push with VAPID                              |
+| `@shware/workflow/fcm`         | `FcmPushSender` over an `FcmAccessToken`, FCM HTTP v1 for Android                                  |
+| `@shware/workflow/webpush`     | `WebPushSender` over a `VapidSigner`, `generateVapidKeys`; standard Web Push with VAPID            |
 | `@shware/workflow/webhooks`    | `SlackWebhookSender` and `DiscordWebhookSender`                                                    |
 | `@shware/workflow/schema.sql`  | The D1 schema file                                                                                 |
 

package/dist/apns.cjs

@@ -1,22 +1,94 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_engine_retry = require("./engine/retry.cjs");
 const require_jwt = require("./jwt.cjs");
 //#region src/apns.ts
 const APNS_HOSTS = {
 	sandbox: "https://api.sandbox.push.apple.com",
 	production: "https://api.push.apple.com"
 };
-/** Reasons APNs gives for a token that will never deliver again — not worth a retry. */
-const DEAD_TOKEN_REASONS = /* @__PURE__ */ new Set([
-	"Unregistered",
-	"BadDeviceToken",
+/**
+* How an APNs answer is classified, after Apple's response table
+* (https://developer.apple.com/documentation/usernotifications/handling-notification-responses-from-apns):
+*
+* - dead token: HTTP 410 `Unregistered` (the app was removed, or the token is inactive for the
+*   topic) and 400 `ExpiredToken`. The device will never deliver again, so the copy settles
+*   undelivered and the host forgets the token.
+* - undelivered, device kept: 400 `BadDeviceToken`. Apple gives it for a malformed token but
+*   just as well for a token of the other environment (a sandbox build pushed through the
+*   production host), which would answer for every device at once; the copy settles with the
+*   reason, so the report shows it, and nothing is deleted on a guess.
+* - configuration: the topic, certificate or provider key is wrong. Every device on this app
+*   would answer the same, so it is a `PermanentError` and the devices are kept — they are fine,
+*   the deployment is not.
+* - transient: 429 (`TooManyRequests`, `TooManyProviderTokenUpdates`), 5xx (`InternalServerError`,
+*   `ServiceUnavailable`, `Shutdown`) and 403 `ExpiredProviderToken`, which a fresh token fixes.
+* - everything else (400 `BadMessageId`, `BadPriority`, `PayloadEmpty`, 413 `PayloadTooLarge`,
+*   404 `BadPath`, 405 `MethodNotAllowed`, …) is this request itself: a `PermanentError`.
+*/
+const DEAD_TOKEN_REASONS = /* @__PURE__ */ new Set(["Unregistered", "ExpiredToken"]);
+/** The app's topic, certificate or provider key is wrong: the request is refused for every device. */
+const CONFIGURATION_REASONS = /* @__PURE__ */ new Set([
 	"DeviceTokenNotForTopic",
-	"ExpiredToken"
+	"TopicDisallowed",
+	"BadTopic",
+	"MissingTopic",
+	"BadCertificate",
+	"BadCertificateEnvironment",
+	"Forbidden",
+	"InvalidProviderToken",
+	"MissingProviderToken"
 ]);
+/**
+* The copy's identity on the wire: a canonical UUID derived from the idempotency key (SHA-256, the
+* first 16 bytes laid out as an RFC 9562 v8 UUID). The same on every attempt, so a resend of the
+* same copy carries the same `apns-id` and — as `apns-collapse-id`, which is limited to 64 bytes —
+* collapses onto the first notification. The whole key is hashed: cut to 64 bytes it would lose
+* the node id at its end, and two nodes of one instance would collapse into one notification.
+*/
+async function apnsIdFromKey(idempotencyKey) {
+	const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(idempotencyKey))).slice(0, 16);
+	bytes[6] = bytes[6] & 15 | 128;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
 /** Apple: reuse a provider token for at least 20 minutes, never past 60. */
 const TOKEN_TTL_MS = 3e6;
+/**
+* The provider JWT for one APNs auth key, signed once and reused for `TOKEN_TTL_MS`: Apple
+* answers a sender that re-signs on every push with 429 `TooManyProviderTokenUpdates`. Concurrent
+* callers on a fresh or aged token share the one signing in flight, and a signing that failed is
+* not kept, so the next call tries again. One instance serves every sender built on the key — a
+* host keeps it across runs, and builds the senders per run.
+*/
+var ApnsProviderToken = class {
+	options;
+	signed;
+	signing;
+	constructor(options) {
+		this.options = options;
+	}
+	/** The current token, signed now if there is none or it has aged out. */
+	async token(now = Date.now()) {
+		if (this.signed !== void 0 && now - this.signed.issuedAt < TOKEN_TTL_MS) return this.signed.value;
+		this.signing ??= signApnsJwt(this.options, now).then((value) => {
+			this.signed = {
+				value,
+				issuedAt: now
+			};
+			return value;
+		}).finally(() => {
+			this.signing = void 0;
+		});
+		return this.signing;
+	}
+	/** Forget the token: APNs refused it (`ExpiredProviderToken`), so the next call signs a new one. */
+	invalidate() {
+		this.signed = void 0;
+	}
+};
 var ApnsPushSender = class {
 	options;
-	token;
 	constructor(options) {
 		this.options = options;
 	}
@@ -27,13 +99,17 @@ var ApnsPushSender = class {
 		const mutable = image !== void 0 || message.tracking?.data?.delivered_url !== void 0;
 		const upstream = APNS_HOSTS[this.options.environment];
 		const origin = this.options.origin ?? upstream;
-		const response = await (this.options.fetch ?? fetch)(`${origin}/3/device/${message.recipient}`, {
+		const doFetch = this.options.fetch ?? fetch;
+		const copyId = await apnsIdFromKey(message.idempotencyKey);
+		const response = await doFetch(`${origin}/3/device/${message.recipient}`, {
 			method: "POST",
 			headers: {
-				authorization: `bearer ${await this.providerToken()}`,
+				authorization: `bearer ${await this.options.credentials.token()}`,
 				"apns-topic": this.options.topic,
 				"apns-push-type": "alert",
 				"apns-priority": "10",
+				"apns-id": copyId,
+				"apns-collapse-id": copyId,
 				"content-type": "application/json",
 				...this.options.origin === void 0 ? {} : { "apns-relay-upstream": upstream }
 			},
@@ -55,26 +131,29 @@ var ApnsPushSender = class {
 		});
 		if (response.ok) return;
 		const text = await response.text();
-		const reason = apnsReason(text);
-		if (response.status === 410 || DEAD_TOKEN_REASONS.has(reason)) {
-			console.warn(`[apns] token gone for user ${message.userId}: ${reason || response.status}`);
-			await this.options.onUnregistered?.(message);
+		const { status } = response;
+		const reason = apnsReason(text) || (status === 410 ? "Unregistered" : "");
+		if (status === 410 || DEAD_TOKEN_REASONS.has(reason)) {
+			console.warn(`[apns] token gone for user ${message.userId}: ${reason}`);
 			return {
 				delivered: false,
-				reason: reason || `HTTP ${response.status}`
+				reason
 			};
 		}
-		throw new Error(`APNs send failed: ${response.status} ${text}`);
-	}
-	async providerToken() {
-		const now = Date.now();
-		if (this.token !== void 0 && now - this.token.issuedAt < TOKEN_TTL_MS) return this.token.value;
-		const value = await signApnsJwt(this.options, now);
-		this.token = {
-			value,
-			issuedAt: now
-		};
-		return value;
+		if (reason === "BadDeviceToken") {
+			console.warn(`[apns] refused for user ${message.userId}: ${status} ${reason}`);
+			return {
+				delivered: false,
+				reason
+			};
+		}
+		if (reason === "ExpiredProviderToken") {
+			this.options.credentials.invalidate();
+			throw new Error(`APNs send failed: ${status} ${reason} (provider token renewed for the retry)`);
+		}
+		if (CONFIGURATION_REASONS.has(reason)) throw new require_engine_retry.PermanentError(`APNs refused the request for topic '${this.options.topic}' (${this.options.environment}): ${status} ${reason}`);
+		if (require_engine_retry.isRetryableStatus(status)) throw new Error(`APNs send failed: ${status} ${reason || text}`);
+		throw new require_engine_retry.PermanentError(`APNs refused the request: ${status} ${reason || text}`);
 	}
 };
 /** APNs error bodies are `{ "reason": "…" }`. */
@@ -107,13 +186,21 @@ async function signApnsJwt(key, nowMs = Date.now()) {
 }
 /** The `.p8` as it is usually shipped in a secret: base64 of the file. */
 function apnsKeyFromBase64(value) {
-	const pem = atob(value);
-	if (!pem.includes("-----BEGIN PRIVATE KEY-----")) throw new Error("APNs key is not a PKCS #8 PEM (.p8) file");
+	let pem;
+	try {
+		pem = atob(value);
+	} catch (error) {
+		throw new require_engine_retry.PermanentError("APNs key is not base64 (expected the .p8 file, base64-encoded)", { cause: error });
+	}
+	if (!pem.includes("-----BEGIN PRIVATE KEY-----")) throw new require_engine_retry.PermanentError("APNs key is not a PKCS #8 PEM (.p8) file");
 	return pem;
 }
 //#endregion
 exports.APNS_HOSTS = APNS_HOSTS;
+exports.ApnsProviderToken = ApnsProviderToken;
 exports.ApnsPushSender = ApnsPushSender;
+exports.DEAD_TOKEN_REASONS = DEAD_TOKEN_REASONS;
+exports.apnsIdFromKey = apnsIdFromKey;
 exports.apnsKeyFromBase64 = apnsKeyFromBase64;
 exports.apnsReason = apnsReason;
 exports.signApnsJwt = signApnsJwt;

package/dist/apns.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"apns.cjs","names":["base64url","pemToDer"],"sources":["../src/apns.ts"],"sourcesContent":["import type { MessageSender, OutboundMessage, SendResult } from './engine';\nimport { base64url, pemToDer } from './jwt';\nimport type { PushRenderer } from './push';\n\n/**\n * `@shware/workflow/apns` — iOS push delivery straight to the Apple Push\n * Notification service, token-based (an APNs auth key, the `.p8` file from the\n * developer portal). No Firebase in between: the app registers the APNs device\n * token in its own device table, and the host's DeviceDirectory hands it to the\n * engine, which sends one message per device.\n * No dependencies: the provider JWT is ES256-signed with WebCrypto.\n *\n * APNs speaks HTTP/2 only. A deployed Worker's `fetch` negotiates it, but\n * workerd under `wrangler dev` does not (the connection is dropped), so a local\n * host points `origin` at the Node relay in `@shware/workflow/apns-relay`.\n */\n\nexport interface ApnsPushOptions {\n  /** The key's 10-character id, shown next to it in the developer portal. */\n  keyId: string;\n  /** The Apple Developer team id. */\n  teamId: string;\n  /** The `.p8` file's contents: PEM, `-----BEGIN PRIVATE KEY-----` (PKCS #8, P-256). */\n  privateKey: string;\n  /** The app's bundle id — APNs's `apns-topic`. */\n  topic: string;\n  /**\n   * Which APNs environment the device tokens come from: `sandbox` for builds\n   * signed with `aps-environment: development` (Xcode, the simulator),\n   * `production` for App Store and TestFlight builds. A token from one is\n   * `BadDeviceToken` on the other.\n   */\n  environment: 'sandbox' | 'production';\n  render: PushRenderer;\n  /**\n   * POST here instead of Apple's host — the dev relay, which forwards over\n   * HTTP/2. The real host still travels along (`apns-relay-upstream`), so the\n   * relay needs no configuration of its own.\n   */\n  origin?: string;\n  /** Fetch implementation (defaults to the global one). */\n  fetch?: typeof fetch;\n  /** Called for a token APNs reports as gone (`Unregistered`, `BadDeviceToken`); `channelsFromConfig` passes it on to the DeviceDirectory's `disable`. */\n  onUnregistered?: (message: OutboundMessage) => Promise<void> | void;\n}\n\nexport const APNS_HOSTS = {\n  sandbox: 'https://api.sandbox.push.apple.com',\n  production: 'https://api.push.apple.com',\n} as const;\n\n/** Reasons APNs gives for a token that will never deliver again — not worth a retry. */\nconst DEAD_TOKEN_REASONS = new Set([\n  'Unregistered',\n  'BadDeviceToken',\n  'DeviceTokenNotForTopic',\n  'ExpiredToken',\n]);\n\n/** Apple: reuse a provider token for at least 20 minutes, never past 60. */\nconst TOKEN_TTL_MS = 50 * 60_000;\n\nexport class ApnsPushSender implements MessageSender {\n  private token: { value: string; issuedAt: number } | undefined;\n\n  constructor(private readonly options: ApnsPushOptions) {}\n\n  async send(message: OutboundMessage): Promise<void | SendResult> {\n    if (message.channel !== 'push') {\n      throw new Error(`ApnsPushSender: unsupported channel '${message.channel}'`);\n    }\n    if (message.recipient === undefined) {\n      throw new Error(`ApnsPushSender: no push token for user '${message.userId}'`);\n    }\n    const { title, body, image, url } = await this.options.render(message.template, message.props);\n    // A notification service extension runs only for a mutable push: it attaches the image and\n    // reports the device delivery (`delivered_url`)\n    const mutable = image !== undefined || message.tracking?.data?.delivered_url !== undefined;\n    const upstream = APNS_HOSTS[this.options.environment];\n    const origin = this.options.origin ?? upstream;\n    const doFetch = this.options.fetch ?? fetch;\n\n    const response = await doFetch(`${origin}/3/device/${message.recipient}`, {\n      method: 'POST',\n      headers: {\n        authorization: `bearer ${await this.providerToken()}`,\n        'apns-topic': this.options.topic,\n        'apns-push-type': 'alert',\n        'apns-priority': '10',\n        'content-type': 'application/json',\n        ...(this.options.origin === undefined ? {} : { 'apns-relay-upstream': upstream }),\n      },\n      body: JSON.stringify({\n        aps: {\n          alert: { title, body },\n          sound: 'default',\n          ...(mutable ? { 'mutable-content': 1 } : {}),\n        },\n        // The template key travels so the app can route a tap; the idempotency\n        // key lets the app de-duplicate a redelivered push.\n        template: message.template,\n        idempotencyKey: message.idempotencyKey,\n        ...(image === undefined ? {} : { image }),\n        ...(url === undefined ? {} : { url }),\n        ...message.tracking?.data,\n      }),\n    });\n    if (response.ok) return;\n\n    const text = await response.text();\n    const reason = apnsReason(text);\n    if (response.status === 410 || DEAD_TOKEN_REASONS.has(reason)) {\n      // A dead token is a fact about the recipient, not a transient failure:\n      // report it and move on, so the step does not retry into the same wall.\n      console.warn(`[apns] token gone for user ${message.userId}: ${reason || response.status}`);\n      await this.options.onUnregistered?.(message);\n      return { delivered: false, reason: reason || `HTTP ${response.status}` };\n    }\n    throw new Error(`APNs send failed: ${response.status} ${text}`);\n  }\n\n  private async providerToken(): Promise<string> {\n    const now = Date.now();\n    if (this.token !== undefined && now - this.token.issuedAt < TOKEN_TTL_MS) {\n      return this.token.value;\n    }\n    const value = await signApnsJwt(this.options, now);\n    this.token = { value, issuedAt: now };\n    return value;\n  }\n}\n\n/** APNs error bodies are `{ \"reason\": \"…\" }`. */\nexport function apnsReason(body: string): string {\n  try {\n    const parsed = JSON.parse(body) as { reason?: string };\n    return parsed.reason ?? '';\n  } catch {\n    return '';\n  }\n}\n\n/** ES256-sign the APNs provider token: header `kid`, claims `iss` (team) and `iat`. */\nexport async function signApnsJwt(\n  key: Pick<ApnsPushOptions, 'keyId' | 'teamId' | 'privateKey'>,\n  nowMs = Date.now()\n): Promise<string> {\n  const header = base64url(JSON.stringify({ alg: 'ES256', kid: key.keyId }));\n  const claims = base64url(JSON.stringify({ iss: key.teamId, iat: Math.floor(nowMs / 1000) }));\n  const cryptoKey = await crypto.subtle.importKey(\n    'pkcs8',\n    pemToDer(key.privateKey),\n    { name: 'ECDSA', namedCurve: 'P-256' },\n    false,\n    ['sign']\n  );\n  // WebCrypto's ECDSA signature is the raw r‖s pair, which is exactly JWS's ES256 encoding.\n  const signature = await crypto.subtle.sign(\n    { name: 'ECDSA', hash: 'SHA-256' },\n    cryptoKey,\n    new TextEncoder().encode(`${header}.${claims}`)\n  );\n  return `${header}.${claims}.${base64url(new Uint8Array(signature))}`;\n}\n\n/** The `.p8` as it is usually shipped in a secret: base64 of the file. */\nexport function apnsKeyFromBase64(value: string): string {\n  const pem = atob(value);\n  if (!pem.includes('-----BEGIN PRIVATE KEY-----')) {\n    throw new Error('APNs key is not a PKCS #8 PEM (.p8) file');\n  }\n  return pem;\n}\n"],"mappings":"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"}
+{"version":3,"file":"apns.cjs","names":["PermanentError","isRetryableStatus","base64url","pemToDer"],"sources":["../src/apns.ts"],"sourcesContent":["import type { MessageSender, OutboundMessage, SendResult } from './engine';\nimport { PermanentError, isRetryableStatus } from './engine/retry';\nimport { base64url, pemToDer } from './jwt';\nimport type { PushRenderer } from './push';\n\n/**\n * `@shware/workflow/apns` — iOS push delivery straight to the Apple Push\n * Notification service, token-based (an APNs auth key, the `.p8` file from the\n * developer portal). No Firebase in between: the app registers the APNs device\n * token in its own device table, and the host's DeviceDirectory hands it to the\n * engine, which sends one message per device.\n * No dependencies: the provider JWT is ES256-signed with WebCrypto.\n *\n * APNs speaks HTTP/2 only. A deployed Worker's `fetch` negotiates it, but\n * workerd under `wrangler dev` does not (the connection is dropped), so a local\n * host points `origin` at the Node relay in `@shware/workflow/apns-relay`.\n */\n\n/** The APNs auth key — the `.p8` file from the developer portal, and the ids that name it. */\nexport interface ApnsProviderTokenOptions {\n  /** The key's 10-character id, shown next to it in the developer portal. */\n  keyId: string;\n  /** The Apple Developer team id. */\n  teamId: string;\n  /** The `.p8` file's contents: PEM, `-----BEGIN PRIVATE KEY-----` (PKCS #8, P-256). */\n  privateKey: string;\n}\n\nexport interface ApnsPushOptions {\n  /** The provider token the requests are signed with — shared by every sender on the same key. */\n  credentials: ApnsProviderToken;\n  /** The app's bundle id — APNs's `apns-topic`. */\n  topic: string;\n  /**\n   * Which APNs environment the device tokens come from: `sandbox` for builds\n   * signed with `aps-environment: development` (Xcode, the simulator),\n   * `production` for App Store and TestFlight builds. A token from one is\n   * `BadDeviceToken` on the other.\n   */\n  environment: 'sandbox' | 'production';\n  render: PushRenderer;\n  /**\n   * POST here instead of Apple's host — the dev relay, which forwards over\n   * HTTP/2. The real host still travels along (`apns-relay-upstream`), so the\n   * relay needs no configuration of its own.\n   */\n  origin?: string;\n  /** Fetch implementation (defaults to the global one). */\n  fetch?: typeof fetch;\n}\n\nexport const APNS_HOSTS = {\n  sandbox: 'https://api.sandbox.push.apple.com',\n  production: 'https://api.push.apple.com',\n} as const;\n\n/**\n * How an APNs answer is classified, after Apple's response table\n * (https://developer.apple.com/documentation/usernotifications/handling-notification-responses-from-apns):\n *\n * - dead token: HTTP 410 `Unregistered` (the app was removed, or the token is inactive for the\n *   topic) and 400 `ExpiredToken`. The device will never deliver again, so the copy settles\n *   undelivered and the host forgets the token.\n * - undelivered, device kept: 400 `BadDeviceToken`. Apple gives it for a malformed token but\n *   just as well for a token of the other environment (a sandbox build pushed through the\n *   production host), which would answer for every device at once; the copy settles with the\n *   reason, so the report shows it, and nothing is deleted on a guess.\n * - configuration: the topic, certificate or provider key is wrong. Every device on this app\n *   would answer the same, so it is a `PermanentError` and the devices are kept — they are fine,\n *   the deployment is not.\n * - transient: 429 (`TooManyRequests`, `TooManyProviderTokenUpdates`), 5xx (`InternalServerError`,\n *   `ServiceUnavailable`, `Shutdown`) and 403 `ExpiredProviderToken`, which a fresh token fixes.\n * - everything else (400 `BadMessageId`, `BadPriority`, `PayloadEmpty`, 413 `PayloadTooLarge`,\n *   404 `BadPath`, 405 `MethodNotAllowed`, …) is this request itself: a `PermanentError`.\n */\nexport const DEAD_TOKEN_REASONS: ReadonlySet<string> = new Set(['Unregistered', 'ExpiredToken']);\n\n/** The app's topic, certificate or provider key is wrong: the request is refused for every device. */\nconst CONFIGURATION_REASONS: ReadonlySet<string> = new Set([\n  'DeviceTokenNotForTopic',\n  'TopicDisallowed',\n  'BadTopic',\n  'MissingTopic',\n  'BadCertificate',\n  'BadCertificateEnvironment',\n  'Forbidden',\n  'InvalidProviderToken',\n  'MissingProviderToken',\n]);\n\n/**\n * The copy's identity on the wire: a canonical UUID derived from the idempotency key (SHA-256, the\n * first 16 bytes laid out as an RFC 9562 v8 UUID). The same on every attempt, so a resend of the\n * same copy carries the same `apns-id` and — as `apns-collapse-id`, which is limited to 64 bytes —\n * collapses onto the first notification. The whole key is hashed: cut to 64 bytes it would lose\n * the node id at its end, and two nodes of one instance would collapse into one notification.\n */\nexport async function apnsIdFromKey(idempotencyKey: string): Promise<string> {\n  const digest = new Uint8Array(\n    await crypto.subtle.digest('SHA-256', new TextEncoder().encode(idempotencyKey))\n  );\n  const bytes = digest.slice(0, 16);\n  bytes[6] = (bytes[6] & 0x0f) | 0x80; // version 8: custom, deterministic\n  bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant\n  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');\n  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;\n}\n\n/** Apple: reuse a provider token for at least 20 minutes, never past 60. */\nconst TOKEN_TTL_MS = 50 * 60_000;\n\n/**\n * The provider JWT for one APNs auth key, signed once and reused for `TOKEN_TTL_MS`: Apple\n * answers a sender that re-signs on every push with 429 `TooManyProviderTokenUpdates`. Concurrent\n * callers on a fresh or aged token share the one signing in flight, and a signing that failed is\n * not kept, so the next call tries again. One instance serves every sender built on the key — a\n * host keeps it across runs, and builds the senders per run.\n */\nexport class ApnsProviderToken {\n  private signed: { value: string; issuedAt: number } | undefined;\n  private signing: Promise<string> | undefined;\n\n  constructor(private readonly options: ApnsProviderTokenOptions) {}\n\n  /** The current token, signed now if there is none or it has aged out. */\n  async token(now = Date.now()): Promise<string> {\n    if (this.signed !== undefined && now - this.signed.issuedAt < TOKEN_TTL_MS) {\n      return this.signed.value;\n    }\n    this.signing ??= signApnsJwt(this.options, now)\n      .then((value) => {\n        this.signed = { value, issuedAt: now };\n        return value;\n      })\n      .finally(() => {\n        this.signing = undefined;\n      });\n    return this.signing;\n  }\n\n  /** Forget the token: APNs refused it (`ExpiredProviderToken`), so the next call signs a new one. */\n  invalidate(): void {\n    this.signed = undefined;\n  }\n}\n\nexport class ApnsPushSender implements MessageSender {\n  constructor(private readonly options: ApnsPushOptions) {}\n\n  async send(message: OutboundMessage): Promise<void | SendResult> {\n    if (message.channel !== 'push') {\n      throw new Error(`ApnsPushSender: unsupported channel '${message.channel}'`);\n    }\n    if (message.recipient === undefined) {\n      throw new Error(`ApnsPushSender: no push token for user '${message.userId}'`);\n    }\n    const { title, body, image, url } = await this.options.render(message.template, message.props);\n    // A notification service extension runs only for a mutable push: it attaches the image and\n    // reports the device delivery (`delivered_url`)\n    const mutable = image !== undefined || message.tracking?.data?.delivered_url !== undefined;\n    const upstream = APNS_HOSTS[this.options.environment];\n    const origin = this.options.origin ?? upstream;\n    const doFetch = this.options.fetch ?? fetch;\n\n    const copyId = await apnsIdFromKey(message.idempotencyKey);\n    const response = await doFetch(`${origin}/3/device/${message.recipient}`, {\n      method: 'POST',\n      headers: {\n        authorization: `bearer ${await this.options.credentials.token()}`,\n        'apns-topic': this.options.topic,\n        'apns-push-type': 'alert',\n        'apns-priority': '10',\n        // A resend of the same copy (an at-least-once retry after APNs accepted the first attempt)\n        // carries the same id and collapses onto the first notification instead of showing twice\n        'apns-id': copyId,\n        'apns-collapse-id': copyId,\n        'content-type': 'application/json',\n        ...(this.options.origin === undefined ? {} : { 'apns-relay-upstream': upstream }),\n      },\n      body: JSON.stringify({\n        aps: {\n          alert: { title, body },\n          sound: 'default',\n          ...(mutable ? { 'mutable-content': 1 } : {}),\n        },\n        // The template key travels so the app can route a tap; the idempotency\n        // key lets the app de-duplicate a redelivered push.\n        template: message.template,\n        idempotencyKey: message.idempotencyKey,\n        ...(image === undefined ? {} : { image }),\n        ...(url === undefined ? {} : { url }),\n        ...message.tracking?.data,\n      }),\n    });\n    if (response.ok) return;\n\n    const text = await response.text();\n    const { status } = response;\n    // A 410 without a body is still \"unregistered\": settle it under that reason\n    const reason = apnsReason(text) || (status === 410 ? 'Unregistered' : '');\n    if (status === 410 || DEAD_TOKEN_REASONS.has(reason)) {\n      // A dead token is a fact about the recipient, not a transient failure:\n      // report it and move on, so the step does not retry into the same wall.\n      console.warn(`[apns] token gone for user ${message.userId}: ${reason}`);\n      return { delivered: false, reason };\n    }\n    if (reason === 'BadDeviceToken') {\n      // The token or the environment: settled so the report says which device, nothing deleted\n      console.warn(`[apns] refused for user ${message.userId}: ${status} ${reason}`);\n      return { delivered: false, reason };\n    }\n    if (reason === 'ExpiredProviderToken') {\n      // The token aged out (clock skew, a long-lived isolate): sign a new one on the retry\n      this.options.credentials.invalidate();\n      throw new Error(\n        `APNs send failed: ${status} ${reason} (provider token renewed for the retry)`\n      );\n    }\n    if (CONFIGURATION_REASONS.has(reason)) {\n      throw new PermanentError(\n        `APNs refused the request for topic '${this.options.topic}' (${this.options.environment}): ${status} ${reason}`\n      );\n    }\n    if (isRetryableStatus(status)) {\n      throw new Error(`APNs send failed: ${status} ${reason || text}`);\n    }\n    throw new PermanentError(`APNs refused the request: ${status} ${reason || text}`);\n  }\n}\n\n/** APNs error bodies are `{ \"reason\": \"…\" }`. */\nexport function apnsReason(body: string): string {\n  try {\n    const parsed = JSON.parse(body) as { reason?: string };\n    return parsed.reason ?? '';\n  } catch {\n    return '';\n  }\n}\n\n/** ES256-sign the APNs provider token: header `kid`, claims `iss` (team) and `iat`. */\nexport async function signApnsJwt(\n  key: ApnsProviderTokenOptions,\n  nowMs = Date.now()\n): Promise<string> {\n  const header = base64url(JSON.stringify({ alg: 'ES256', kid: key.keyId }));\n  const claims = base64url(JSON.stringify({ iss: key.teamId, iat: Math.floor(nowMs / 1000) }));\n  const cryptoKey = await crypto.subtle.importKey(\n    'pkcs8',\n    pemToDer(key.privateKey),\n    { name: 'ECDSA', namedCurve: 'P-256' },\n    false,\n    ['sign']\n  );\n  // WebCrypto's ECDSA signature is the raw r‖s pair, which is exactly JWS's ES256 encoding.\n  const signature = await crypto.subtle.sign(\n    { name: 'ECDSA', hash: 'SHA-256' },\n    cryptoKey,\n    new TextEncoder().encode(`${header}.${claims}`)\n  );\n  return `${header}.${claims}.${base64url(new Uint8Array(signature))}`;\n}\n\n/** The `.p8` as it is usually shipped in a secret: base64 of the file. */\nexport function apnsKeyFromBase64(value: string): string {\n  let pem: string;\n  try {\n    pem = atob(value);\n  } catch (error) {\n    // A secret that is not base64 is the same on every attempt: not worth a retry\n    throw new PermanentError('APNs key is not base64 (expected the .p8 file, base64-encoded)', {\n      cause: error,\n    });\n  }\n  if (!pem.includes('-----BEGIN PRIVATE KEY-----')) {\n    throw new PermanentError('APNs key is not a PKCS #8 PEM (.p8) file');\n  }\n  return pem;\n}\n"],"mappings":"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"}