@freecorps/ember-push 0.1.0 → 0.3.0

package/dist/hpke.js

@@ -0,0 +1,153 @@
+// Ported from Freecorps Brigade, packages/push/src/hpke.ts (MIT License, Copyright (c) 2026 Freecorps Tecnologia da
+// Informação LTDA; https://github.com/freecorps/brigade/tree/main/packages/push). Kept byte-for-byte compatible with it:
+// same suite, same RFC 9180 steps, so Brigade's test vectors and native decoders apply unchanged.
+/**
+ * HPKE (RFC 9180), base mode, single-shot, with one cipher suite: DHKEM(P-256, HKDF-SHA256), HKDF-SHA256 and
+ * AES-128-GCM. Only WebCrypto, so it runs unchanged in Workers, browsers and Node. iOS opens it with CryptoKit
+ * (`HPKE.Ciphersuite(kem: .P256_HKDF_SHA256, kdf: .HKDF_SHA256, aead: .AES_GCM_128)`, iOS 17+) and Android
+ * with the pure-JS decoder in `@freecorps/ember-expo-push`. Why this suite: Brigade's spike S1
+ * (https://github.com/freecorps/brigade/blob/main/docs/spikes/s1-apns-encryption.md).
+ */
+import { toBase64url } from "./base64url.js";
+const KEM_ID = 0x0010; // DHKEM(P-256, HKDF-SHA256)
+const KDF_ID = 0x0001; // HKDF-SHA256
+const AEAD_ID = 0x0001; // AES-128-GCM
+const MODE_BASE = 0x00;
+/** Hash, shared secret, AES key and nonce lengths. */
+const N_H = 32;
+const N_SECRET = 32;
+const N_K = 16;
+const N_N = 12;
+/** An uncompressed P-256 point (0x04 || x || y): the encapsulated key and every public key. */
+export const P256_PUBLIC_KEY_LENGTH = 65;
+const ECDH = { name: "ECDH", namedCurve: "P-256" };
+const encoder = new TextEncoder();
+/** Encrypts `plaintext` to the holder of the private key for `recipientPublicKey` (uncompressed P-256). */
+export async function seal(recipientPublicKey, plaintext, options = {}) {
+    const pkR = await importPublicKey(recipientPublicKey);
+    const ephemeral = options.ephemeral ??
+        (await crypto.subtle.generateKey(ECDH, false, ["deriveBits"]));
+    const enc = new Uint8Array((await crypto.subtle.exportKey("raw", ephemeral.publicKey)));
+    const dh = await deriveDh(ephemeral.privateKey, pkR);
+    const sharedSecret = await extractAndExpand(dh, concat(enc, recipientPublicKey));
+    const { key, baseNonce } = await keySchedule(sharedSecret, options.info);
+    const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv: baseNonce, additionalData: bytes(options.aad) }, key, bytes(plaintext));
+    return { enc, ct: new Uint8Array(ct) };
+}
+/** Decrypts what `seal` produced. Throws if the key, `info`, `aad` or any byte does not match. */
+export async function open(recipient, sealed, options = {}) {
+    const pkE = await importPublicKey(sealed.enc);
+    const dh = await deriveDh(recipient.privateKey, pkE);
+    const sharedSecret = await extractAndExpand(dh, concat(sealed.enc, recipient.publicKey));
+    const { key, baseNonce } = await keySchedule(sharedSecret, options.info);
+    const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: baseNonce, additionalData: bytes(options.aad) }, key, bytes(sealed.ct));
+    return new Uint8Array(pt);
+}
+/** A fresh recipient key pair. The private key is not extractable. */
+export async function generateRecipient() {
+    const pair = (await crypto.subtle.generateKey(ECDH, false, ["deriveBits"]));
+    const publicKey = new Uint8Array((await crypto.subtle.exportKey("raw", pair.publicKey)));
+    return { privateKey: pair.privateKey, publicKey };
+}
+/**
+ * Imports a P-256 key pair from its raw private scalar (32 bytes) and uncompressed public key, the form CryptoKit
+ * (`rawRepresentation`, `x963Representation`) and the RFC 9180 test vectors use.
+ */
+export async function importKeyPair(privateKey, publicKey) {
+    if (privateKey.length !== 32)
+        throw new Error("P-256 private key must be 32 bytes");
+    const { x, y } = await publicJwk(publicKey);
+    const jwk = { kty: "EC", crv: "P-256", x, y, d: toBase64url(privateKey) };
+    const priv = await crypto.subtle.importKey("jwk", jwk, ECDH, false, ["deriveBits"]);
+    return { privateKey: priv, publicKey: await importPublicKey(publicKey) };
+}
+async function importPublicKey(raw) {
+    // Uncompressed only: WebCrypto's raw import also takes the 33-byte compressed form, which the KEM context
+    // would then hash differently from the other side.
+    if (raw.length !== P256_PUBLIC_KEY_LENGTH || raw[0] !== 0x04) {
+        throw new Error("expected an uncompressed P-256 public key (65 bytes)");
+    }
+    return crypto.subtle.importKey("raw", bytes(raw), ECDH, true, []);
+}
+async function publicJwk(raw) {
+    const jwk = (await crypto.subtle.exportKey("jwk", await importPublicKey(raw)));
+    if (!jwk.x || !jwk.y)
+        throw new Error("invalid P-256 public key");
+    return { x: jwk.x, y: jwk.y };
+}
+async function deriveDh(privateKey, publicKey) {
+    // The x coordinate of the shared point (RFC 9180, section 7.1.1).
+    return new Uint8Array(
+    // Cast: DOM lib types call the peer key `public`, @cloudflare/workers-types `$public`; runtimes read `public`.
+    await crypto.subtle.deriveBits({ name: "ECDH", public: publicKey }, privateKey, 256));
+}
+// RFC 9180, section 4.1: DHKEM's ExtractAndExpand.
+async function extractAndExpand(dh, kemContext) {
+    const suite = concat(encoder.encode("KEM"), i2osp(KEM_ID, 2));
+    const eaePrk = await labeledExtract(suite, new Uint8Array(0), "eae_prk", dh);
+    return labeledExpand(suite, eaePrk, "shared_secret", kemContext, N_SECRET);
+}
+// RFC 9180, section 5.1, base mode (no PSK).
+async function keySchedule(sharedSecret, info = new Uint8Array(0)) {
+    const suite = concat(encoder.encode("HPKE"), i2osp(KEM_ID, 2), i2osp(KDF_ID, 2), i2osp(AEAD_ID, 2));
+    const empty = new Uint8Array(0);
+    const pskIdHash = await labeledExtract(suite, empty, "psk_id_hash", empty);
+    const infoHash = await labeledExtract(suite, empty, "info_hash", bytes(info));
+    const context = concat(Uint8Array.of(MODE_BASE), pskIdHash, infoHash);
+    const secret = await labeledExtract(suite, sharedSecret, "secret", empty);
+    const keyBytes = await labeledExpand(suite, secret, "key", context, N_K);
+    const baseNonce = await labeledExpand(suite, secret, "base_nonce", context, N_N);
+    // Single-shot: one message at sequence number 0, so the nonce is the base nonce.
+    const key = await crypto.subtle.importKey("raw", keyBytes, "AES-GCM", false, [
+        "encrypt",
+        "decrypt",
+    ]);
+    return { key, baseNonce };
+}
+function labeledExtract(suite, salt, label, ikm) {
+    return hkdfExtract(salt, concat(encoder.encode("HPKE-v1"), suite, encoder.encode(label), ikm));
+}
+function labeledExpand(suite, prk, label, info, length) {
+    const labeled = concat(i2osp(length, 2), encoder.encode("HPKE-v1"), suite, encoder.encode(label), info);
+    return hkdfExpand(prk, labeled, length);
+}
+// RFC 5869 with SHA-256. WebCrypto's HKDF fuses extract and expand, and HPKE labels each step on its own.
+async function hkdfExtract(salt, ikm) {
+    // An empty salt means HashLen zero bytes; WebCrypto rejects a zero-length HMAC key, and HMAC pads either way.
+    return hmac(salt.length === 0 ? new Uint8Array(N_H) : salt, ikm);
+}
+async function hkdfExpand(prk, info, length) {
+    const out = new Uint8Array(length);
+    let block = new Uint8Array(0);
+    for (let i = 1, offset = 0; offset < length; i++) {
+        block = await hmac(prk, concat(block, info, Uint8Array.of(i)));
+        out.set(block.subarray(0, Math.min(N_H, length - offset)), offset);
+        offset += N_H;
+    }
+    return out;
+}
+async function hmac(key, data) {
+    const k = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, [
+        "sign",
+    ]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", k, data));
+}
+function i2osp(value, length) {
+    const out = new Uint8Array(length);
+    for (let i = length - 1, v = value; i >= 0; i--, v >>>= 8)
+        out[i] = v & 0xff;
+    return out;
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+/** A copy backed by a plain ArrayBuffer, which WebCrypto's types require. */
+function bytes(value = new Uint8Array(0)) {
+    return new Uint8Array(value);
+}

package/dist/index.d.ts

@@ -5,8 +5,20 @@
  * - Sending (`sendPush`, `checkPushReceipts`): plain `fetch`, so call them from an **action** (PLAN D6: I/O only in
  *   actions). Typical flow: a mutation schedules an action → the action reads tokens with `ctx.runQuery`, calls
  *   `sendPush`, deletes `unregisteredTokens` with `ctx.runMutation`, and schedules a receipts check ~15 min later.
- * - `PushProvider` keeps the backend pluggable: Expo Push today; direct APNs/FCM later.
+ * - Transports: Expo Push (`sendPush`, zero setup) or direct APNs + FCM (`sendApns`, `sendFcm`, `sendToDevices`), with
+ *   optional end-to-end encryption (HPKE envelopes, `sealPushContent`; the device side is `@freecorps/ember-expo-push`).
+ * - Or install it as a component (`pushComponent`, PLAN §12): devices in the component's own table, sends enqueued
+ *   from mutations (atomically), receipts checked later, dead tokens pruned. See `PushNotifications`.
  */
 export * from "./types.ts";
+export { fromBase64url, toBase64url } from "./base64url.ts";
+export { generateRecipient, importKeyPair, open, seal, P256_PUBLIC_KEY_LENGTH, type HpkeOptions, type HpkeRecipient, type HpkeSealed, type SealOptions } from "./hpke.ts";
+export { EMBER_PUSH_ENVELOPE_VERSION, EMBER_PUSH_HPKE_INFO, PUSH_KEY_ID, PUSH_PLAINTEXT_MAX_BYTES, isDevicePublicKey, openPushEnvelope, parseDevicePublicKey, parseOpenedContent, parsePushEnvelope, pushKeyId, sealPushContent, type EncryptedPushContent, type OpenedPushContent, type PushEnvelope, } from "./envelope.ts";
 export { EXPO_MAX_PAYLOAD, EXPO_PUSH_URL, EXPO_RECEIPTS_CHUNK, EXPO_RECEIPTS_URL, EXPO_SEND_CHUNK, checkPushReceipts, expoPushProvider, isExpoPushToken, payloadSize, sendExpoMessages, sendPush, toExpoMessage, type ExpoPushOptions, } from "./expo.ts";
-export { PUSH_DEVICES_TABLE, pushDevicesForUser, pushDevicesTable, pushTokensForUsers, registerPushDevice, removePushTokens, unregisterPushDevice, type PushDevice, type RegisterPushDeviceInput, } from "./devices.ts";
+export { PUSH_DEVICES_TABLE, inferPushProvider, isPushProviderName, pushDevicesForUser, pushDevicesForUsers, pushDevicesTable, pushTokensForUsers, registerPushDevice, removePushTokens, removeVoipTokens, setPushDeviceEnvironment, unregisterPushDevice, type PushDevice, type PushProviderName, type RegisterPushDeviceInput, } from "./devices.ts";
+export { apnsOptionsFromEnv, fcmOptionsFromEnv, pushComponent, pushFunctions, PushNotifications, setPushSeal, type PushComponentApi, type PushInstallConfig, type DeliveryResult } from "./component.ts";
+export { decodeJwt, importSigningKey, pemToDer, signJwt, verifyJwt, type CredentialsError, type JwtAlgorithm } from "./jwt.ts";
+export { DEFAULT_PUSH_FALLBACK, PUSH_MAX_TTL_SECONDS, PUSH_TTL_DEFAULTS, resolveInterruptionLevel, resolveTtlSeconds, resolveUrgency } from "./delivery.ts";
+export { APNS_MAX_PAYLOAD, APNS_PRODUCTION_URL, APNS_SANDBOX_URL, APNS_TOKEN_REFRESH_MS, APNS_VOIP_MAX_PAYLOAD, apnsErrorCode, apnsHeaders, apnsPayload, apnsProviderToken, apnsPushProvider, apnsPushType, clearApnsTokenCache, isApnsToken, sendApns, type ApnsCredentials, type ApnsOptions, } from "./apns.ts";
+export { FCM_MAX_PAYLOAD, FCM_MAX_TTL_SECONDS, FCM_SCOPE, FCM_SEND_URL, FCM_TOKEN_MARGIN_MS, GOOGLE_TOKEN_URL, clearFcmTokenCache, fcmAccessToken, fcmErrorCode, fcmMessage, fcmPushProvider, isFcmToken, parseServiceAccount, sendFcm, type FcmOptions, type ServiceAccount, } from "./fcm.ts";
+export { sendToDevices, type DeviceSendResult, type PushTarget, type PushTransports } from "./direct.ts";

package/dist/index.js

@@ -5,8 +5,20 @@
  * - Sending (`sendPush`, `checkPushReceipts`): plain `fetch`, so call them from an **action** (PLAN D6: I/O only in
  *   actions). Typical flow: a mutation schedules an action → the action reads tokens with `ctx.runQuery`, calls
  *   `sendPush`, deletes `unregisteredTokens` with `ctx.runMutation`, and schedules a receipts check ~15 min later.
- * - `PushProvider` keeps the backend pluggable: Expo Push today; direct APNs/FCM later.
+ * - Transports: Expo Push (`sendPush`, zero setup) or direct APNs + FCM (`sendApns`, `sendFcm`, `sendToDevices`), with
+ *   optional end-to-end encryption (HPKE envelopes, `sealPushContent`; the device side is `@freecorps/ember-expo-push`).
+ * - Or install it as a component (`pushComponent`, PLAN §12): devices in the component's own table, sends enqueued
+ *   from mutations (atomically), receipts checked later, dead tokens pruned. See `PushNotifications`.
  */
 export * from "./types.js";
+export { fromBase64url, toBase64url } from "./base64url.js";
+export { generateRecipient, importKeyPair, open, seal, P256_PUBLIC_KEY_LENGTH } from "./hpke.js";
+export { EMBER_PUSH_ENVELOPE_VERSION, EMBER_PUSH_HPKE_INFO, PUSH_KEY_ID, PUSH_PLAINTEXT_MAX_BYTES, isDevicePublicKey, openPushEnvelope, parseDevicePublicKey, parseOpenedContent, parsePushEnvelope, pushKeyId, sealPushContent, } from "./envelope.js";
 export { EXPO_MAX_PAYLOAD, EXPO_PUSH_URL, EXPO_RECEIPTS_CHUNK, EXPO_RECEIPTS_URL, EXPO_SEND_CHUNK, checkPushReceipts, expoPushProvider, isExpoPushToken, payloadSize, sendExpoMessages, sendPush, toExpoMessage, } from "./expo.js";
-export { PUSH_DEVICES_TABLE, pushDevicesForUser, pushDevicesTable, pushTokensForUsers, registerPushDevice, removePushTokens, unregisterPushDevice, } from "./devices.js";
+export { PUSH_DEVICES_TABLE, inferPushProvider, isPushProviderName, pushDevicesForUser, pushDevicesForUsers, pushDevicesTable, pushTokensForUsers, registerPushDevice, removePushTokens, removeVoipTokens, setPushDeviceEnvironment, unregisterPushDevice, } from "./devices.js";
+export { apnsOptionsFromEnv, fcmOptionsFromEnv, pushComponent, pushFunctions, PushNotifications, setPushSeal } from "./component.js";
+export { decodeJwt, importSigningKey, pemToDer, signJwt, verifyJwt } from "./jwt.js";
+export { DEFAULT_PUSH_FALLBACK, PUSH_MAX_TTL_SECONDS, PUSH_TTL_DEFAULTS, resolveInterruptionLevel, resolveTtlSeconds, resolveUrgency } from "./delivery.js";
+export { APNS_MAX_PAYLOAD, APNS_PRODUCTION_URL, APNS_SANDBOX_URL, APNS_TOKEN_REFRESH_MS, APNS_VOIP_MAX_PAYLOAD, apnsErrorCode, apnsHeaders, apnsPayload, apnsProviderToken, apnsPushProvider, apnsPushType, clearApnsTokenCache, isApnsToken, sendApns, } from "./apns.js";
+export { FCM_MAX_PAYLOAD, FCM_MAX_TTL_SECONDS, FCM_SCOPE, FCM_SEND_URL, FCM_TOKEN_MARGIN_MS, GOOGLE_TOKEN_URL, clearFcmTokenCache, fcmAccessToken, fcmErrorCode, fcmMessage, fcmPushProvider, isFcmToken, parseServiceAccount, sendFcm, } from "./fcm.js";
+export { sendToDevices } from "./direct.js";

package/dist/jwt.d.ts

@@ -0,0 +1,27 @@
+export type JwtAlgorithm = "ES256" | "RS256";
+/**
+ * The DER bytes of a PEM `PRIVATE KEY` (PKCS#8), the form of an Apple `.p8` file and of a Google service account's
+ * `private_key`. Tolerates what secrets go through: `\n` written as two characters, `\r\n`, surrounding whitespace and
+ * quotes. Throws for an encrypted or non-PKCS#8 key (`BEGIN EC PRIVATE KEY`, `BEGIN RSA PRIVATE KEY`).
+ */
+export declare function pemToDer(pem: string): Uint8Array<ArrayBuffer>;
+/** An error about the configured key itself (not the network): senders report it as `InvalidCredentials`. */
+export type CredentialsError = Error & {
+    credentials: true;
+};
+/**
+ * Imports a PKCS#8 PEM private key for signing with `alg`. The key is not extractable. Throws a `CredentialsError`
+ * (`credentials: true`) for anything wrong with the key: not PEM, not PKCS#8, bad base64, wrong curve or type.
+ */
+export declare function importSigningKey(pem: string, alg: JwtAlgorithm): Promise<CryptoKey>;
+/** `base64url(header).base64url(claims).base64url(signature)`, with `alg` and `typ: "JWT"` set in the header. */
+export declare function signJwt(alg: JwtAlgorithm, key: CryptoKey, claims: Record<string, unknown>, header?: Record<string, unknown>): Promise<string>;
+/** Splits a compact JWS into its decoded header, claims and raw signature (no verification). For tests and fakes. */
+export declare function decodeJwt(token: string): {
+    header: Record<string, unknown>;
+    claims: Record<string, unknown>;
+    signature: Uint8Array<ArrayBuffer>;
+    signingInput: string;
+};
+/** Verifies a compact JWS with a public key (`verify` usage). For tests and fakes. */
+export declare function verifyJwt(token: string, alg: JwtAlgorithm, publicKey: CryptoKey): Promise<boolean>;

package/dist/jwt.js

@@ -0,0 +1,77 @@
+/**
+ * Compact JWS signing on WebCrypto, for the two tokens direct push needs (RFC 7515/7518):
+ *
+ * - **ES256** — the APNs provider token, signed with the `.p8` key from Apple (a PKCS#8 P-256 key). WebCrypto's ECDSA
+ *   signature is already the raw `r ‖ s` (64 bytes) that JWS wants, so no DER conversion.
+ * - **RS256** — the assertion Google's OAuth token endpoint exchanges for an FCM access token, signed with the
+ *   service account's `private_key` (PKCS#8 RSA).
+ *
+ * Written for Ember from the RFCs and Apple/Google documentation; no Node APIs, so it runs in Workers.
+ */
+import { fromBase64url, toBase64url } from "./base64url.js";
+const ALGORITHMS = {
+    ES256: { importParams: { name: "ECDSA", namedCurve: "P-256" }, signParams: { name: "ECDSA", hash: "SHA-256" } },
+    RS256: { importParams: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, signParams: { name: "RSASSA-PKCS1-v1_5" } },
+};
+const encoder = new TextEncoder();
+/**
+ * The DER bytes of a PEM `PRIVATE KEY` (PKCS#8), the form of an Apple `.p8` file and of a Google service account's
+ * `private_key`. Tolerates what secrets go through: `\n` written as two characters, `\r\n`, surrounding whitespace and
+ * quotes. Throws for an encrypted or non-PKCS#8 key (`BEGIN EC PRIVATE KEY`, `BEGIN RSA PRIVATE KEY`).
+ */
+export function pemToDer(pem) {
+    const text = pem.trim().replace(/^"|"$/g, "").replace(/\\n/g, "\n").replace(/\r/g, "");
+    const m = /-----BEGIN ([A-Z ]+)-----([\s\S]*?)-----END \1-----/.exec(text);
+    if (!m)
+        throw new Error("not a PEM key (expected -----BEGIN PRIVATE KEY-----)");
+    if (m[1] !== "PRIVATE KEY")
+        throw new Error(`expected a PKCS#8 "PRIVATE KEY", got "${m[1]}" (convert it with \`openssl pkcs8 -topk8 -nocrypt\`)`);
+    const b64 = m[2].replace(/\s+/g, "");
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+const credentialsError = (message) => Object.assign(new Error(message), { credentials: true });
+/**
+ * Imports a PKCS#8 PEM private key for signing with `alg`. The key is not extractable. Throws a `CredentialsError`
+ * (`credentials: true`) for anything wrong with the key: not PEM, not PKCS#8, bad base64, wrong curve or type.
+ */
+export async function importSigningKey(pem, alg) {
+    let der;
+    try {
+        der = pemToDer(pem);
+    }
+    catch (e) {
+        throw credentialsError(e.message);
+    }
+    try {
+        return await crypto.subtle.importKey("pkcs8", der, ALGORITHMS[alg].importParams, false, ["sign"]);
+    }
+    catch (e) {
+        throw credentialsError(`cannot import the ${alg === "ES256" ? "P-256 (.p8)" : "RSA"} private key: ${e.message}`);
+    }
+}
+const b64json = (value) => toBase64url(encoder.encode(JSON.stringify(value)));
+/** `base64url(header).base64url(claims).base64url(signature)`, with `alg` and `typ: "JWT"` set in the header. */
+export async function signJwt(alg, key, claims, header = {}) {
+    const signingInput = `${b64json({ alg, typ: "JWT", ...header })}.${b64json(claims)}`;
+    const signature = await crypto.subtle.sign(ALGORITHMS[alg].signParams, key, encoder.encode(signingInput));
+    return `${signingInput}.${toBase64url(new Uint8Array(signature))}`;
+}
+/** Splits a compact JWS into its decoded header, claims and raw signature (no verification). For tests and fakes. */
+export function decodeJwt(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        throw new Error("not a compact JWS");
+    const json = (s) => JSON.parse(new TextDecoder().decode(fromBase64url(s)));
+    return { header: json(parts[0]), claims: json(parts[1]), signature: fromBase64url(parts[2]), signingInput: `${parts[0]}.${parts[1]}` };
+}
+/** Verifies a compact JWS with a public key (`verify` usage). For tests and fakes. */
+export async function verifyJwt(token, alg, publicKey) {
+    const { header, signature, signingInput } = decodeJwt(token);
+    if (header.alg !== alg)
+        return false;
+    return crypto.subtle.verify(ALGORITHMS[alg].signParams, publicKey, signature, encoder.encode(signingInput));
+}

package/dist/types.d.ts

@@ -1,7 +1,51 @@
 /**
- * Provider-neutral push types. Expo Push is the first provider (PLAN §10, CLOUDFLARE.md §8); direct APNs (ES256 JWT
- * over HTTP/2) and FCM v1 (service-account OAuth) can implement `PushProvider` later without changing callers.
+ * Provider-neutral push types. Two transports implement them: Expo Push (`expo.ts`, zero setup) and direct APNs (ES256
+ * provider token over HTTP/2, `apns.ts`) + FCM HTTP v1 (service-account OAuth, `fcm.ts`). Callers do not change.
  */
+import type { PushEnvelope } from "./envelope.ts";
+/**
+ * How urgent a push is. Direct transports map it to the APNs priority, the FCM Android priority, the TTL default and
+ * the iOS interruption level (Brigade's `low`/`high`/`page`, see `delivery.ts`):
+ *
+ * | urgency  | APNs priority | FCM priority | TTL default | interruption level |
+ * |----------|---------------|--------------|-------------|--------------------|
+ * | `low`    | 5             | NORMAL       | 4 h         | active             |
+ * | `normal` | 10            | HIGH         | 1 h         | active             |
+ * | `high`   | 10            | HIGH         | 15 min      | time-sensitive     |
+ */
+export type PushUrgency = "low" | "normal" | "high";
+/** iOS 15+ interruption levels. `time-sensitive` needs the entitlement; `critical` needs Apple's approval. */
+export type PushInterruptionLevel = "passive" | "active" | "time-sensitive" | "critical";
+/** APNs environment of an iOS device token: Xcode/development-signed builds get sandbox tokens, ad hoc/TestFlight/App Store ones production. */
+export type ApnsEnvironment = "sandbox" | "production";
+/**
+ * End-to-end encryption of a push (direct transport only):
+ * - `off`: content in clear;
+ * - `auto` (default): sealed for devices that registered a public key, in clear for the others;
+ * - `required`: sealed; a device without a key (or an Expo token) gets only the fallback text.
+ */
+export type PushEncryption = "off" | "auto" | "required";
+/**
+ * iOS Critical Alert sound (the app needs Apple's Critical Alerts entitlement): plays even on silent and through Focus.
+ * APNs gets `{ critical: 1, name, volume }` and `interruption-level: critical`; Android and Expo play `name`.
+ */
+export interface PushCriticalSound {
+    critical: true;
+    /** Sound file in the app bundle (default `"default"`). */
+    name?: string;
+    /** 0 to 1 (default 1). */
+    volume?: number;
+}
+/**
+ * A payload the app built itself (its own envelope and keys), sent as given by the direct transports. Ember still sets
+ * the headers (push type, priority, expiration, collapse id), the provider token, retries and error mapping.
+ * `apns`: the whole JSON body (`aps` included). `fcmData`: an FCM data message's `data` (string values only).
+ * A transport without its part builds the message from the other fields as usual; Expo ignores both.
+ */
+export interface PushPayload {
+    apns?: Record<string, unknown>;
+    fcmData?: Record<string, string>;
+}
 /** What a notification says. Fields a provider does not support are ignored by it. */
 export interface PushMessage {
     title?: string;
@@ -9,8 +53,8 @@ export interface PushMessage {
     body?: string;
     /** Delivered to the app (JSON object). Counts toward the 4 KiB payload limit. */
     data?: Record<string, unknown>;
-    /** `"default"` plays the default sound (iOS). */
-    sound?: "default" | null;
+    /** `"default"` plays the default sound (iOS); a `PushCriticalSound` rings as a Critical Alert. */
+    sound?: "default" | null | PushCriticalSound;
     /** iOS app icon badge; 0 clears it. */
     badge?: number;
     /** Android notification channel (created by the app, e.g. `registerForPush` creates `"default"`). */
@@ -24,23 +68,66 @@ export interface PushMessage {
     categoryId?: string;
     /** iOS Notification Service Extension may modify the content. */
     mutableContent?: boolean;
+    /** Direct transports: see `PushUrgency`. Without it, `priority: "normal"` means `low`, anything else `normal`. */
+    urgency?: PushUrgency;
+    /** Replaces an earlier notification with the same id (APNs `apns-collapse-id`, ≤ 64 bytes; FCM `collapse_key` + tag; Expo `collapseId` + `tag`). */
+    collapseId?: string;
+    /** iOS notification grouping (`thread-id`). */
+    threadId?: string;
+    /** iOS interruption level; default from `urgency` (`high` → `time-sensitive`). */
+    interruptionLevel?: PushInterruptionLevel;
+    /** Direct transports: overrides the install's encryption setting for this message (see `PushEncryption`). */
+    encryption?: PushEncryption;
+    /**
+     * iOS: send as a PushKit VoIP push to the device's `voipToken` (topic `<bundle id>.voip`, push type `voip`). The app
+     * must report a call to CallKit for every one, or iOS stops delivering them. Devices without a VoIP token are skipped.
+     */
+    voip?: boolean;
 }
 /** A message for one device token. */
 export interface AddressedPushMessage extends PushMessage {
     to: string;
+    /** APNs environment of `to` (iOS). Unknown: the transport's default, then the other host if APNs says `BadDeviceToken`. */
+    environment?: ApnsEnvironment;
+    /**
+     * Set by `sendToDevices` when the content is sealed for this device: the transport sends this envelope and the
+     * fallback text instead of title/subtitle/body/data.
+     */
+    sealed?: PushEnvelope;
+    /** The app's own payload for this device (see `PushPayload`); wins over `sealed` and the content fields. */
+    payload?: PushPayload;
+}
+/** What a device shows when an encrypted push cannot be opened (or, with `encryption: "required"`, has no key). */
+export interface PushFallback {
+    title?: string;
+    body?: string;
+    /** iOS: localization keys from the app's `Localizable.strings`, preferred over the plain text when set. */
+    titleLocKey?: string;
+    locKey?: string;
 }
 /** Well-known per-message errors (Expo names; APNs/FCM providers map theirs onto these). */
 export type PushErrorCode = "DeviceNotRegistered" | "MessageTooBig" | "MessageRateExceeded" | "MismatchSenderId" | "InvalidCredentials" | "InvalidToken" | "RequestFailed" | (string & {});
 /** The push service's answer at send time. `ok` means accepted, not delivered: check receipts later. */
-export type PushTicket = {
+export type PushTicket = 
+/** `environment`: set when a direct send found the device's APNs environment by trying the other host. */
+{
     token: string;
     status: "ok";
     id: string;
+    environment?: ApnsEnvironment;
 } | {
     token: string;
     status: "error";
     message: string;
     error?: PushErrorCode;
+    /**
+     * The provider's own reason, as it said it (direct sends): APNs' `reason` (`DeviceTokenNotForTopic`,
+     * `BadDeviceToken`, …) or FCM's `errorCode` / error `status` (`UNREGISTERED`, `INVALID_ARGUMENT`, …). For
+     * rules Ember's codes fold together (a token of another topic, a token FCM calls malformed).
+     */
+    reason?: string;
+    /** The provider's HTTP status (direct sends). */
+    httpStatus?: number;
 };
 /** Final delivery outcome reported by the provider (Expo keeps receipts for 24 h). */
 export type PushReceipt = {

package/dist/types.js

@@ -1,5 +1 @@
-/**
- * Provider-neutral push types. Expo Push is the first provider (PLAN §10, CLOUDFLARE.md §8); direct APNs (ES256 JWT
- * over HTTP/2) and FCM v1 (service-account OAuth) can implement `PushProvider` later without changing callers.
- */
 export {};

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@freecorps/ember-push",
-  "version": "0.1.0",
-  "description": "Push notifications for Ember actions: device table helpers and an Expo Push sender.",
+  "version": "0.3.0",
+  "description": "Push notifications for Ember: device registry, Expo Push, direct APNs + FCM, end-to-end encrypted payloads (HPKE), and a push component.",
   "keywords": [
-    "ember",
-    "convex",
+    "apns",
     "cloudflare",
-    "workers",
-    "push",
+    "convex",
+    "e2ee",
+    "ember",
     "expo",
-    "notifications"
+    "fcm",
+    "hpke",
+    "notifications",
+    "push",
+    "workers"
   ],
   "homepage": "https://github.com/freecorps/ember/tree/main/packages/push#readme",
   "bugs": {
@@ -41,7 +45,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@freecorps/ember-server": "0.1.0",
-    "@freecorps/ember-values": "0.1.0"
+    "@freecorps/ember-server": "0.3.0",
+    "@freecorps/ember-values": "0.3.0"
   }
 }