@freecorps/ember-push 0.1.0 → 0.3.0

package/README.md

@@ -1,12 +1,229 @@
 # @freecorps/ember-push
 
-Push notifications for Ember actions: device table helpers and an Expo Push sender.
+Push notifications for Ember apps. Sends go out from your own Worker (actions, or the `push` component). There is
+no relay to run: Ember is self-hosted per company.
 
-Part of [Ember](https://github.com/freecorps/ember), a Convex-style backend on Cloudflare Workers and Durable
-Objects. Source: [`packages/push`](https://github.com/freecorps/ember/tree/main/packages/push).
+| Transport | Device tokens | Setup | Notes |
+|---|---|---|---|
+| `expo` (default) | `ExponentPushToken[...]` (`registerForPush()`) | none (`EXPO_ACCESS_TOKEN` optional) | Expo Push: receipts ~15 min later, no encryption |
+| `direct` | native APNs / FCM tokens (`registerForPush({ kind: "device" })`) | APNs `.p8` + FCM service account, as Worker secrets | APNs over HTTP/2 + FCM HTTP v1 straight from the Worker; urgency, collapse ids, VoIP, **end-to-end encryption** |
+
+The transport is chosen **per device**, by how the app registered: Expo tokens go to Expo, native tokens go direct.
+Both kinds can coexist, for example during a migration.
+
+## The push component
+
+```ts
+// ember/ember.config.ts
+import { pushComponent } from "@freecorps/ember-push";
+export default defineApp().use(pushComponent, {
+  config: {
+    apns: { topic: "com.acme.mail" },            // the bundle id (or the APNS_TOPIC secret)
+    encryption: "required",                      // mail: subject and sender never in clear at Apple/Google
+    fallback: { title: "New mail", body: "Open Mail to read it" },
+  },
+});
+
+// ember/push.ts
+import { PushNotifications } from "@freecorps/ember-push";
+import { components, mutation } from "./_generated/server";
+const push = new PushNotifications(components.push);
+
+export const register = mutation({
+  args: { token: v.string(), platform: v.optional(v.string()), environment: v.optional(v.string()), publicKey: v.optional(v.string()) },
+  handler: (ctx, a) => push.register(ctx, { userId: me(ctx), ...a }),   // provider inferred from the token
+});
+
+// in the mutation that stores a new message (the push is enqueued atomically with it):
+push.send(ctx, [recipient], { title: from, body: subject, urgency: "high", collapseId: threadHash, data: { messageId } });
+```
+
+The full config, with every field optional:
+
+```ts
+{
+  accessTokenEnv: "EXPO_ACCESS_TOKEN", receiptsDelayMs: 15 * 60_000,               // Expo
+  apns: { topic, keyEnv: "APNS_KEY", keyIdEnv: "APNS_KEY_ID", teamIdEnv: "APNS_TEAM_ID", topicEnv: "APNS_TOPIC",
+          environment: "production" /* devices registered without one */, productionUrl, sandboxUrl },
+  fcm: { serviceAccountEnv: "FCM_SERVICE_ACCOUNT", sendUrl, tokenUrl },
+  encryption: "auto",                                                               // "off" | "auto" | "required"
+  fallback: { title, body, titleLocKey, locKey },
+}
+```
+
+What a delivery does:
+1. Reads the users' devices.
+2. Sends each device through its transport.
+3. Deletes devices whose token is dead, clears dead VoIP tokens, and records the APNs environment found for devices
+   registered without one.
+4. Schedules Expo receipt checks (Expo only; APNs and FCM answer synchronously).
+
+`sendNow` returns `{ sent, errors, removedTokens, errorCodes }`. When secrets are missing, those devices are kept;
+the result shows `ProviderNotConfigured` and `ember logs` shows a warning naming the missing secrets.
+
+## Without the component
+
+Use `sendPush(tokens, message)` (Expo) or `sendToDevices(devices, message, { apns, fcm, expo, encryption, fallback })`
+from an action, with your own `pushDevices` table (`pushDevicesTable()`, `registerPushDevice`, `pushDevicesForUsers`,
+`removePushTokens`, `removeVoipTokens`, `setPushDeviceEnvironment`). Lower level: `sendApns`, `sendFcm`,
+`apnsPushProvider`, `fcmPushProvider`, `sealPushContent`. See `apps/example-expo/ember/push.ts`.
+
+## Secrets
+
+| Secret | What |
+|---|---|
+| `APNS_KEY` | The `.p8` file's text (`-----BEGIN PRIVATE KEY-----...`). Escaped `\n` and CRLF are fine |
+| `APNS_KEY_ID` | The key's 10-character id |
+| `APNS_TEAM_ID` | Your Apple Developer team id |
+| `APNS_TOPIC` | The app's bundle id (or `config.apns.topic`, which is not secret) |
+| `FCM_SERVICE_ACCOUNT` | The service account's JSON key, the whole file |
+| `EXPO_ACCESS_TOKEN` | Optional, for Expo projects with enhanced push security |
+
+They are read from the Worker env at send time and are never stored or logged. Keep the files outside the
+repository. Set them with `ember env` (Worker secrets of `ember-<project>-<env>`, live at once and kept by every
+`ember deploy`). Secret values come from stdin (or `--from-env VAR`), never the command line; plain vars such as
+`APNS_TOPIC` are not secret, live in `ember.json`, and take their value on the command line with `--var`:
 
 ```sh
-npm install @freecorps/ember-push
+ember env set APNS_KEY --env prod < ~/secure/AuthKey_ABC123DEFG.p8
+printf %s ABC123DEFG | ember env set APNS_KEY_ID --env prod
+printf %s TEAM123456 | ember env set APNS_TEAM_ID --env prod
+ember env set APNS_TOPIC com.acme.mail --var --env prod   # not secret: a plain var in ember.json
+ember env set FCM_SERVICE_ACCOUNT --env prod < ~/secure/fcm-service-account.json
+ember env list --env prod                                  # names only
 ```
 
-License: MIT.
+In `ember dev`, put the same names in `.dev.vars` (gitignored).
+
+**APNs needs HTTP/2.** A deployed Worker's `fetch` reaches APNs, but local workerd (`ember dev`) cannot, so APNs
+sends fail locally with a network error. FCM works locally. Unit tests use fake endpoints (below).
+
+## Behaviour
+
+Urgency follows Brigade's relay as its README documents it (Brigade's `low`/`high`/`page`):
+
+| `urgency` | APNs priority | FCM priority | TTL default | iOS interruption level |
+|---|---|---|---|---|
+| `low` | 5 | NORMAL | 4 h | active |
+| `normal` (default; `priority: "normal"` means `low`) | 10 | HIGH | 1 h | active |
+| `high` | 10 | HIGH | 15 min | time-sensitive (entitlement added by the ember-expo-push plugin) |
+
+- `ttl` overrides the default (0 = deliver now or never; at most 30 days, 28 for FCM).
+- `collapseId` sets `apns-collapse-id` (max 64 bytes) and the FCM `collapse_key` plus notification tag. Expo devices get it as Expo's `collapseId` and Android `tag`.
+- `threadId`, `categoryId`, `badge` and `sound` map to their APNs/FCM fields. `contentAvailable` alone sends a
+  background push (APNs priority 5). `voip: true` sends to the device's PushKit `voipToken` (topic `<bundle>.voip`).
+- Each device token's APNs environment is recorded at registration (development-signed builds get sandbox tokens;
+  ad hoc, TestFlight and App Store builds get production). For a device registered without one, the default host is
+  tried first, then the other one after `BadDeviceToken`. The one that works is recorded.
+- The APNs provider token (ES256 over the `.p8`) is reused for 40 minutes. The FCM access token (RS256
+  service-account assertion) is kept until 5 minutes before it expires; concurrent sends share one exchange, and a
+  401 refetches it once for every send that saw the same token.
+- The token layer is usable on its own, around an app's own payloads: `apnsProviderToken(credentials, now, force)`
+  and `fcmAccessToken(options, force, signal)`. `force` is `true` (always new) or the token the provider just refused
+  (new only if the cache still holds it, so concurrent sends refresh once and a token another send already replaced
+  is reused).
+- 429 and 5xx answers and network errors are retried twice with backoff (`Retry-After` is honoured).
+- `timeoutMs` is a deadline for each send, retries and the token it needs included; `signal` aborts it. Either way the
+  ticket is `RequestFailed`. A caller's deadline only stops that caller waiting for a token exchange other sends share.
+- **An app's own payload** (its envelope, its keys): `AddressedPushMessage.payload = { apns?, fcmData? }` is sent as
+  given. `apns` is the whole JSON body (`aps` included; a body that is only `content-available` goes as a background
+  push); `fcmData` is a data message's `data`, string values only. Ember still sets the headers (push type, priority,
+  expiration, collapse id), the token, retries and error mapping. With `sendToDevices` and the component, a
+  `seal(device, message, provider)` hook in `PushTransports` returns that payload per direct device, or `null` for
+  Ember's own envelope; for the component, `setPushSeal(seal, installName?)` in the entry module (a function cannot
+  be part of the install config). Expo devices never reach it.
+- `sound: { critical: true, name?, volume? }` rings as an iOS Critical Alert (APNs' sound dictionary and
+  `interruption-level: critical`; needs Apple's entitlement); Android and Expo play `name`.
+- Error tickets from a direct send carry the provider's own `reason` (APNs' `reason`, FCM's `errorCode` or error
+  `status`) and `httpStatus`, for rules the codes below fold together (a token of another topic, a token FCM calls
+  malformed).
+
+| Answer | Code | Device |
+|---|---|---|
+| APNs `Unregistered` / `ExpiredToken` (410), `BadDeviceToken`; FCM `UNREGISTERED`; a malformed token | `DeviceNotRegistered` / `InvalidToken` | **deleted** |
+| APNs `DeviceTokenNotForTopic`, `TopicDisallowed`; FCM `SENDER_ID_MISMATCH` | `MismatchSenderId` | kept (configuration error) |
+| APNs `InvalidProviderToken`, `ExpiredProviderToken`; FCM 401/403, `THIRD_PARTY_AUTH_ERROR` | `InvalidCredentials` | kept |
+| FCM `INVALID_ARGUMENT` | `InvalidArgument` | kept (could be our payload) |
+| `PayloadTooLarge`, over 4 KB | `MessageTooBig` | kept |
+| `TooManyRequests`, `QUOTA_EXCEEDED` | `MessageRateExceeded` | kept |
+| no secrets for that provider | `ProviderNotConfigured` | kept |
+
+## End-to-end encryption
+
+With `encryption: "auto"` or `"required"`, a direct device that registered a `publicKey` gets its push sealed with
+HPKE (RFC 9180: P-256, HKDF-SHA256, AES-128-GCM, info `"freecorps.ember push v1"`). The envelope `{ v, k, enc, ct }`
+holds the title, subtitle, body and data. It is ported from Freecorps Brigade's MIT `packages/push`.
+- APNs gets the fallback alert, `mutable-content: 1` and `ember: <envelope>`. The Notification Service Extension
+  from `@freecorps/ember-expo-push` decrypts it on iOS 17+.
+- FCM gets a data-only message: `{ ember, fallbackTitle, fallbackBody, channelId?, tag?, urgency }`. The app's
+  background task decrypts it and shows the notification.
+- `required`: devices without a key, and Expo devices, get only the fallback text and no data.
+- In clear by design: the fallback text, urgency/priority, TTL, collapse id/tag, thread id, category, badge, sound and
+  the key id. Do not put anything sensitive in those (hash a thread id, for example).
+- Only pushes with something to show are sealed. Background and VoIP pushes go as they are under `auto` and lose
+  their `data` under `required`.
+
+Device side: [`@freecorps/ember-expo-push`](../expo-push/README.md).
+
+## Tests
+
+`bun run test` in this folder:
+- **Fake APNs and FCM servers** (`test/fakes.ts`) verify the ES256 provider token and the RS256 OAuth assertion with
+  WebCrypto, check headers, paths and payloads, and answer per token (`Unregistered`, `BadDeviceToken`, sandbox-only,
+  429, 503, `SENDER_ID_MISMATCH`...).
+- Covered: request format, priority/TTL/interruption mapping, token reuse and refresh, error mapping and pruning,
+  environment probing, VoIP, retries, payload limits; routing and encryption across Expo/APNs/FCM; the component with
+  secrets from the env; the RFC 9180 A.3.1 vector (Brigade's test, ported) and envelope round trips.
+- **workerd** (`vitest.workerd.config.ts`): the component in the real runtime (Worker + Shard DO). Miniflare's
+  `outboundService` routes every `fetch` to the fakes: `sendNow` from an action, and `push.send` from a mutation
+  delivered by the shard's alarm.
+
+## Real-device testing (not done yet; no credentials were used)
+
+What you need:
+1. **Apple:** a paid Apple Developer account, and your **Team ID** (developer.apple.com → Membership).
+2. **APNs key:** Certificates, IDs & Profiles → Keys → +, enable *Apple Push Notifications service (APNs)*. Download
+   `AuthKey_<KEYID>.p8` (only possible once) and note the **Key ID**. One key serves sandbox and production and every
+   app of the team.
+3. **Bundle id** of the app, for example `com.acme.mail`. Its App ID needs *Push Notifications*, *App Groups*
+   (`group.<bundle id>.ember`) and, for `urgency: "high"`, *Time Sensitive Notifications*. The extension's App ID is
+   `<bundle id>.EmberNotificationService`, with the same App Group. EAS Build creates and syncs these from the
+   entitlements and the `appExtensions` entry the plugin writes. With local Xcode signing, enable them by hand.
+4. **Firebase:** a project with an Android app for your package name. Download `google-services.json` (outside the
+   repository) and point `android.googleServicesFile` (or `GOOGLE_SERVICES_JSON` in the example) at it.
+5. **FCM service account:** in Google Cloud IAM for that project, create a service account with role *Firebase Cloud
+   Messaging API Admin* (`roles/firebasecloudmessaging.admin`), make sure the *Firebase Cloud Messaging API* (v1) is
+   enabled, and create a JSON key. That key is `FCM_SERVICE_ACCOUNT`.
+
+How to test, with the mail app or `apps/example-expo` with `EMBER_PUSH_DIRECT=1`:
+1. Deploy the backend and set the secrets (above).
+2. Build the app with the `@freecorps/ember-expo-push` plugin:
+   - EAS (`eas build --profile preview`): production APNs tokens.
+   - Local (`npx expo run:ios --device`): sandbox tokens.
+   - Android: any build with `google-services.json`.
+3. Sign in and allow notifications. Check that the device row has the right `provider`, `environment` and a
+   `publicKey` (dashboard data browser, or `ember run`).
+4. Send from another account. On a **locked** iPhone, the notification should show the real title and body (the NSE
+   decrypted it). Console.app, filtered on subsystem `<bundle id>.EmberNotificationService`, shows `push decrypted`.
+   On Android, test with the app in the foreground, in the background and swiped away (headless task).
+5. Negative checks:
+   - Delete the app, then send: `Unregistered` or `BadDeviceToken`, and the device row is gone.
+   - Register a development build's token as `production`: `BadDeviceToken`, pruned.
+   - An iOS 16 phone, or a push sent before the app created its key: the fallback text.
+   - `urgency: "high"`: a Time Sensitive banner.
+   - Two sends with the same `collapseId`: one notification.
+6. R12 open points to record (PLAN §18):
+   - APNs from both send paths: `sendNow` (the Worker) and `push.send` (Shard DO alarm, or the actions queue).
+   - No `TooManyProviderTokenUpdates` across many sends.
+   - Latency to the phone.
+
+Not provided:
+- A Brigade-relay transport: the relay's payload (`brigade` field, Brigade loc keys) is specific to Brigade's app,
+  and Ember instances send directly.
+- Client-side PushKit (VoIP) registration: expo-notifications has no PushKit, so use a native module. The registry
+  and sending already support `voipToken`.
+
+License: MIT. HPKE, base64url and the envelope format are adapted from Freecorps Brigade's `packages/push` (MIT).
+The APNs, FCM, NSE and config-plugin code is written for Ember from Apple's, Google's and Expo's documentation.
+Brigade's relay and mobile app are AGPL, so they were used only as documented behaviour (README, docs), never as
+code.

package/dist/apns.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Direct APNs sender: token-based (`.p8`) authentication over HTTP/2, written for Ember from Apple's documentation
+ * ("Establishing a token-based connection to APNs", "Sending notification requests to APNs", "Handling notification
+ * responses from APNs", "Generating a remote notification"). Its observable behaviour — 40-minute provider-token
+ * reuse, priority/TTL per urgency, the per-device sandbox/production host and which answers drop a device — matches
+ * Freecorps Brigade's relay as its README describes it; no code is taken from the relay (AGPL).
+ *
+ * HTTP/2: APNs speaks nothing else. A deployed Worker's `fetch` reaches it (Brigade spike S1, Ember ops E2E R12);
+ * local workerd (`ember dev`) does not, and fails with a network error. Test locally with a fake `fetch`.
+ */
+import { type RetryOptions } from "./delivery.ts";
+import type { AddressedPushMessage, ApnsEnvironment, PushErrorCode, PushFallback, PushProvider, PushTicket } from "./types.ts";
+export declare const APNS_PRODUCTION_URL = "https://api.push.apple.com";
+export declare const APNS_SANDBOX_URL = "https://api.sandbox.push.apple.com";
+/** Payload limits (bytes): 4 KB for regular pushes, 5 KB for VoIP. */
+export declare const APNS_MAX_PAYLOAD = 4096;
+export declare const APNS_VOIP_MAX_PAYLOAD = 5120;
+/**
+ * Provider tokens are reused for 40 minutes: APNs refuses one older than an hour (`ExpiredProviderToken`) and one
+ * refreshed more often than every 20 minutes (`TooManyProviderTokenUpdates`).
+ */
+export declare const APNS_TOKEN_REFRESH_MS: number;
+export interface ApnsCredentials {
+    /** The `.p8` key's 10-character id (developer.apple.com → Keys). */
+    keyId: string;
+    /** The Apple Developer team id. */
+    teamId: string;
+    /** The `.p8` file's text (PKCS#8 PEM). */
+    key: string;
+}
+export interface ApnsOptions extends ApnsCredentials, RetryOptions {
+    /** The app's bundle id (`apns-topic`). VoIP pushes use `<topic>.voip`. */
+    topic: string;
+    /** Host for devices that registered no environment (default `production`). */
+    environment?: ApnsEnvironment;
+    /** Endpoint overrides (tests, an HTTP/2 proxy for local development). */
+    productionUrl?: string;
+    sandboxUrl?: string;
+    /** Text shown in clear for sealed pushes (default `DEFAULT_PUSH_FALLBACK`). */
+    fallback?: PushFallback;
+    /** Requests in flight at once (default 10). */
+    concurrency?: number;
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+/** A device token as `getDevicePushTokenAsync` returns it on iOS: hex, 32 bytes on devices (Simulator tokens are longer). */
+export declare function isApnsToken(token: unknown): token is string;
+/** What APNs answers mean for the caller (Apple's reason strings → Ember's codes). */
+export declare function apnsErrorCode(status: number, reason: string | undefined): PushErrorCode;
+/**
+ * The ES256 provider token for these credentials, reused for `APNS_TOKEN_REFRESH_MS` (per isolate). Concurrent callers
+ * share one signing (APNs answers `TooManyProviderTokenUpdates` when tokens change too often). `force` signs a new
+ * one: `true` always; a token string only if the cache still holds that token (after `ExpiredProviderToken`, so
+ * concurrent sends that saw the same stale token refresh once).
+ */
+export declare function apnsProviderToken(c: ApnsCredentials, now?: number, force?: boolean | string): Promise<string>;
+/** Forgets cached provider tokens (tests; after rotating a key). */
+export declare function clearApnsTokenCache(): void;
+type PushType = "alert" | "background" | "voip";
+export declare function apnsPushType(m: AddressedPushMessage): PushType;
+/**
+ * The JSON body for one message. Custom `data` goes under `body`, where expo-notifications reads it on iOS
+ * (`notification.request.content.data`). A sealed message carries only the fallback text, `mutable-content` (so the
+ * Notification Service Extension runs) and the envelope under `ember`.
+ */
+export declare function apnsPayload(m: AddressedPushMessage, fallback?: PushFallback): Record<string, unknown>;
+/** The request headers for one message (without `authorization`). */
+export declare function apnsHeaders(m: AddressedPushMessage, topic: string, nowMs: number): Record<string, string>;
+/**
+ * Sends each message as its own request (APNs has no batch API), `concurrency` at a time. Never throws for message
+ * failures: they come back as error tickets with Ember's codes (`DeviceNotRegistered` for `Unregistered`, `ExpiredToken`
+ * and `BadDeviceToken`, which callers prune). A device with no recorded environment that gets `BadDeviceToken` is
+ * tried once on the other host; when that works, its ticket says which `environment` it was.
+ */
+export declare function sendApns(messages: AddressedPushMessage[], o: ApnsOptions): Promise<PushTicket[]>;
+/** Direct APNs as a `PushProvider`. No receipts: APNs answers each request synchronously. */
+export declare function apnsPushProvider(o: ApnsOptions): PushProvider;
+export {};

package/dist/apns.js

@@ -0,0 +1,284 @@
+/**
+ * Direct APNs sender: token-based (`.p8`) authentication over HTTP/2, written for Ember from Apple's documentation
+ * ("Establishing a token-based connection to APNs", "Sending notification requests to APNs", "Handling notification
+ * responses from APNs", "Generating a remote notification"). Its observable behaviour — 40-minute provider-token
+ * reuse, priority/TTL per urgency, the per-device sandbox/production host and which answers drop a device — matches
+ * Freecorps Brigade's relay as its README describes it; no code is taken from the relay (AGPL).
+ *
+ * HTTP/2: APNs speaks nothing else. A deployed Worker's `fetch` reaches it (Brigade spike S1, Ember ops E2E R12);
+ * local workerd (`ember dev`) does not, and fails with a network error. Test locally with a fake `fetch`.
+ */
+import { DEFAULT_PUSH_FALLBACK, apnsSound, byteLength, deadlineSignal, fetchWithRetry, mapLimit, resolveInterruptionLevel, resolveTtlSeconds, resolveUrgency, untilAborted } from "./delivery.js";
+import { importSigningKey, signJwt } from "./jwt.js";
+export const APNS_PRODUCTION_URL = "https://api.push.apple.com";
+export const APNS_SANDBOX_URL = "https://api.sandbox.push.apple.com";
+/** Payload limits (bytes): 4 KB for regular pushes, 5 KB for VoIP. */
+export const APNS_MAX_PAYLOAD = 4096;
+export const APNS_VOIP_MAX_PAYLOAD = 5120;
+/**
+ * Provider tokens are reused for 40 minutes: APNs refuses one older than an hour (`ExpiredProviderToken`) and one
+ * refreshed more often than every 20 minutes (`TooManyProviderTokenUpdates`).
+ */
+export const APNS_TOKEN_REFRESH_MS = 40 * 60_000;
+/** A device token as `getDevicePushTokenAsync` returns it on iOS: hex, 32 bytes on devices (Simulator tokens are longer). */
+export function isApnsToken(token) {
+    return typeof token === "string" && token.length % 2 === 0 && /^[0-9a-fA-F]{64,200}$/.test(token);
+}
+/** What APNs answers mean for the caller (Apple's reason strings → Ember's codes). */
+export function apnsErrorCode(status, reason) {
+    switch (reason) {
+        case "Unregistered":
+        case "ExpiredToken":
+        case "BadDeviceToken":
+            return "DeviceNotRegistered";
+        case "DeviceTokenNotForTopic":
+        case "TopicDisallowed":
+        case "BadTopic":
+        case "MissingTopic":
+            return "MismatchSenderId";
+        case "ExpiredProviderToken":
+        case "InvalidProviderToken":
+        case "MissingProviderToken":
+        case "Forbidden":
+        case "BadCertificate":
+        case "BadCertificateEnvironment":
+        case "BadEnvironmentKeyInToken":
+        case "UnrelatedKeyIdInToken":
+            return "InvalidCredentials";
+        case "PayloadTooLarge":
+            return "MessageTooBig";
+        case "TooManyRequests":
+        case "TooManyProviderTokenUpdates":
+            return "MessageRateExceeded";
+    }
+    if (status === 410)
+        return "DeviceNotRegistered";
+    if (status === 403)
+        return "InvalidCredentials";
+    if (status === 413)
+        return "MessageTooBig";
+    if (status === 429)
+        return "MessageRateExceeded";
+    return "RequestFailed";
+}
+const providerTokens = new Map();
+const signing = new Map();
+/**
+ * The ES256 provider token for these credentials, reused for `APNS_TOKEN_REFRESH_MS` (per isolate). Concurrent callers
+ * share one signing (APNs answers `TooManyProviderTokenUpdates` when tokens change too often). `force` signs a new
+ * one: `true` always; a token string only if the cache still holds that token (after `ExpiredProviderToken`, so
+ * concurrent sends that saw the same stale token refresh once).
+ */
+export async function apnsProviderToken(c, now = Date.now(), force = false) {
+    const cacheKey = `${c.teamId}\u0000${c.keyId}\u0000${c.key}`;
+    const hit = providerTokens.get(cacheKey);
+    const fresh = !!hit && now - hit.issuedAt < APNS_TOKEN_REFRESH_MS && now >= hit.issuedAt;
+    const refresh = force === true || (typeof force === "string" && hit?.token === force);
+    if (fresh && !refresh)
+        return hit.token;
+    const pending = signing.get(cacheKey);
+    if (pending)
+        return pending;
+    const p = (async () => {
+        const key = await importSigningKey(c.key, "ES256");
+        const token = await signJwt("ES256", key, { iss: c.teamId, iat: Math.floor(now / 1000) }, { kid: c.keyId });
+        providerTokens.set(cacheKey, { token, issuedAt: now });
+        return token;
+    })().finally(() => signing.delete(cacheKey));
+    signing.set(cacheKey, p);
+    return p;
+}
+/** Forgets cached provider tokens (tests; after rotating a key). */
+export function clearApnsTokenCache() {
+    providerTokens.clear();
+    signing.clear();
+}
+export function apnsPushType(m) {
+    if (m.voip)
+        return "voip";
+    if (m.payload?.apns) {
+        // The app's own body: an alert unless it is only `content-available`.
+        const aps = (m.payload.apns.aps ?? {});
+        const shows = aps.alert !== undefined || aps.sound !== undefined || aps.badge !== undefined;
+        return !shows && aps["content-available"] === 1 ? "background" : "alert";
+    }
+    if (m.sealed)
+        return "alert";
+    const visible = !!(m.title || m.subtitle || m.body || m.sound || m.badge !== undefined);
+    return !visible && m.contentAvailable ? "background" : "alert";
+}
+/**
+ * The JSON body for one message. Custom `data` goes under `body`, where expo-notifications reads it on iOS
+ * (`notification.request.content.data`). A sealed message carries only the fallback text, `mutable-content` (so the
+ * Notification Service Extension runs) and the envelope under `ember`.
+ */
+export function apnsPayload(m, fallback = DEFAULT_PUSH_FALLBACK) {
+    // The app built its own body (its envelope, its keys): sent as given.
+    if (m.payload?.apns)
+        return m.payload.apns;
+    if (m.voip) {
+        const out = { aps: {} };
+        if (m.sealed)
+            out.ember = m.sealed;
+        else if (m.data)
+            out.body = m.data;
+        return out;
+    }
+    const aps = {};
+    if (m.sealed) {
+        const alert = {};
+        if (fallback.titleLocKey)
+            alert["title-loc-key"] = fallback.titleLocKey;
+        else if (fallback.title)
+            alert.title = fallback.title;
+        if (fallback.locKey)
+            alert["loc-key"] = fallback.locKey;
+        else if (fallback.body)
+            alert.body = fallback.body;
+        aps.alert = alert;
+        aps["mutable-content"] = 1;
+    }
+    else {
+        const alert = {};
+        if (m.title)
+            alert.title = m.title;
+        if (m.subtitle)
+            alert.subtitle = m.subtitle;
+        if (m.body)
+            alert.body = m.body;
+        if (Object.keys(alert).length)
+            aps.alert = alert;
+        if (m.mutableContent)
+            aps["mutable-content"] = 1;
+    }
+    const sound = apnsSound(m.sound);
+    if (sound)
+        aps.sound = sound;
+    if (m.badge !== undefined)
+        aps.badge = m.badge;
+    if (m.threadId)
+        aps["thread-id"] = m.threadId;
+    if (m.categoryId)
+        aps.category = m.categoryId;
+    if (m.contentAvailable)
+        aps["content-available"] = 1;
+    const level = resolveInterruptionLevel(m);
+    if (level && aps.alert)
+        aps["interruption-level"] = level;
+    const out = { aps };
+    if (m.sealed)
+        out.ember = m.sealed;
+    else if (m.data)
+        out.body = m.data;
+    return out;
+}
+/** The request headers for one message (without `authorization`). */
+export function apnsHeaders(m, topic, nowMs) {
+    const type = apnsPushType(m);
+    const ttl = resolveTtlSeconds(m);
+    // Background pushes must go at priority 5 (APNs refuses 10 for them).
+    const priority = type === "background" || resolveUrgency(m) === "low" ? "5" : "10";
+    const h = {
+        "content-type": "application/json",
+        "apns-topic": type === "voip" ? `${topic}.voip` : topic,
+        "apns-push-type": type,
+        "apns-priority": priority,
+        "apns-expiration": ttl === 0 ? "0" : String(Math.floor(nowMs / 1000) + ttl),
+    };
+    if (m.collapseId)
+        h["apns-collapse-id"] = m.collapseId;
+    return h;
+}
+/**
+ * Sends each message as its own request (APNs has no batch API), `concurrency` at a time. Never throws for message
+ * failures: they come back as error tickets with Ember's codes (`DeviceNotRegistered` for `Unregistered`, `ExpiredToken`
+ * and `BadDeviceToken`, which callers prune). A device with no recorded environment that gets `BadDeviceToken` is
+ * tried once on the other host; when that works, its ticket says which `environment` it was.
+ */
+export async function sendApns(messages, o) {
+    const fetchFn = (o.fetch ?? globalThis.fetch)?.bind(globalThis);
+    if (!fetchFn)
+        throw new Error("@freecorps/ember-push: no fetch available; pass options.fetch");
+    const now = o.now ?? Date.now;
+    const urlFor = (env) => (env === "sandbox" ? (o.sandboxUrl ?? APNS_SANDBOX_URL) : (o.productionUrl ?? APNS_PRODUCTION_URL));
+    const attempt = async (m, env, body, signal) => {
+        let refreshed = false;
+        let stale = false;
+        for (;;) {
+            const jwt = await untilAborted(apnsProviderToken(o, now(), stale), signal);
+            const res = await fetchWithRetry(fetchFn, `${urlFor(env)}/3/device/${m.to}`, () => ({ method: "POST", headers: { ...apnsHeaders(m, o.topic, now()), authorization: `bearer ${jwt}` }, body }), o, signal);
+            const id = res.headers.get("apns-id") ?? undefined;
+            if (res.ok) {
+                await res.body?.cancel().catch(() => { });
+                return { status: res.status, ...(id ? { id } : {}) };
+            }
+            let reason;
+            try {
+                reason = (await res.json())?.reason;
+            }
+            catch {
+                reason = undefined;
+            }
+            if (reason === "ExpiredProviderToken" && !refreshed) {
+                refreshed = true;
+                stale = jwt;
+                continue;
+            }
+            if (reason === "InvalidProviderToken")
+                clearApnsTokenCache(); // a fixed secret is picked up on the next send
+            return { status: res.status, ...(reason ? { reason } : {}), ...(id ? { id } : {}) };
+        }
+    };
+    const sendOne = async (m) => {
+        if (!isApnsToken(m.to))
+            return { token: String(m.to), status: "error", error: "InvalidToken", message: "not an APNs device token (hex)" };
+        if (m.collapseId && byteLength(m.collapseId) > 64)
+            return { token: m.to, status: "error", error: "RequestFailed", message: "collapseId is over 64 bytes (APNs BadCollapseId)" };
+        const body = JSON.stringify(apnsPayload(m, o.fallback));
+        const limit = m.voip ? APNS_VOIP_MAX_PAYLOAD : APNS_MAX_PAYLOAD;
+        if (byteLength(body) > limit)
+            return { token: m.to, status: "error", error: "MessageTooBig", message: `APNs payload over ${limit} bytes` };
+        const env = m.environment ?? o.environment ?? "production";
+        let r;
+        let usedEnv = env;
+        // One deadline for the whole send, both hosts included.
+        const signal = deadlineSignal(o);
+        try {
+            r = await attempt(m, env, body, signal);
+            if (!m.environment && r.reason === "BadDeviceToken") {
+                const other = env === "production" ? "sandbox" : "production";
+                const second = await attempt(m, other, body, signal);
+                if (second.status === 200 || second.reason !== "BadDeviceToken") {
+                    r = second;
+                    usedEnv = other;
+                }
+            }
+        }
+        catch (e) {
+            // A bad .p8 (importSigningKey) is the configuration's fault, not the network's.
+            const err = e;
+            if (err.credentials)
+                return { token: m.to, status: "error", error: "InvalidCredentials", message: `APNs key: ${err.message}` };
+            return { token: m.to, status: "error", error: "RequestFailed", message: `APNs unreachable: ${err.message}` };
+        }
+        if (r.status === 200) {
+            const ticket = { token: m.to, status: "ok", id: r.id ?? "" };
+            if (!m.environment && usedEnv !== env)
+                ticket.environment = usedEnv;
+            return ticket;
+        }
+        return {
+            token: m.to,
+            status: "error",
+            error: apnsErrorCode(r.status, r.reason),
+            message: `APNs ${r.status} ${r.reason ?? ""}`.trim(),
+            ...(r.reason ? { reason: r.reason } : {}),
+            httpStatus: r.status,
+        };
+    };
+    return mapLimit(messages, o.concurrency ?? 10, sendOne);
+}
+/** Direct APNs as a `PushProvider`. No receipts: APNs answers each request synchronously. */
+export function apnsPushProvider(o) {
+    return { name: "apns", isToken: isApnsToken, send: (messages) => sendApns(messages, o) };
+}

package/dist/base64url.d.ts

@@ -0,0 +1,4 @@
+/** Base64url without padding (RFC 4648, section 5), the encoding of every binary field in a push. */
+export declare function toBase64url(value: Uint8Array): string;
+/** Decodes base64url, padded or not. Throws on any other character. */
+export declare function fromBase64url(value: string): Uint8Array<ArrayBuffer>;

package/dist/base64url.js

@@ -0,0 +1,19 @@
+// Ported from Freecorps Brigade, packages/push/src/base64url.ts (MIT License, Copyright (c) 2026 Freecorps Tecnologia da
+// Informação LTDA; https://github.com/freecorps/brigade/tree/main/packages/push). Unchanged.
+/** Base64url without padding (RFC 4648, section 5), the encoding of every binary field in a push. */
+export function toBase64url(value) {
+    let binary = "";
+    for (const byte of value)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** Decodes base64url, padded or not. Throws on any other character. */
+export function fromBase64url(value) {
+    if (!/^[A-Za-z0-9_-]*={0,2}$/.test(value))
+        throw new Error("invalid base64url");
+    const binary = atob(value.replace(/=+$/, "").replace(/-/g, "+").replace(/_/g, "/"));
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}