@freecorps/ember-push 0.1.0 → 0.2.0

package/dist/fcm.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Direct FCM sender (HTTP v1 API), written for Ember from Google's documentation ("Authorize send requests",
+ * "Using OAuth 2.0 for Server to Server Applications", "FCM HTTP v1 API" and its `FcmError` codes). Behaviour matches
+ * Freecorps Brigade's relay as its README describes it (access token kept until 5 minutes before it expires and
+ * refetched on a 401; `UNREGISTERED` drops the device, `SENDER_ID_MISMATCH` does not; data-only messages for sealed
+ * pushes); no code is taken from the relay (AGPL).
+ *
+ * FCM speaks HTTP/1.1, so unlike APNs this also works from local workerd (`ember dev`).
+ */
+import { type RetryOptions } from "./delivery.ts";
+import type { AddressedPushMessage, PushErrorCode, PushFallback, PushProvider, PushTicket } from "./types.ts";
+export declare const FCM_SEND_URL: (projectId: string) => string;
+export declare const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+export declare const FCM_SCOPE = "https://www.googleapis.com/auth/firebase.messaging";
+/** FCM's own limits: 4096 bytes of message payload, TTL at most 28 days. */
+export declare const FCM_MAX_PAYLOAD = 4096;
+export declare const FCM_MAX_TTL_SECONDS: number;
+/** An access token is refetched this long before it expires. */
+export declare const FCM_TOKEN_MARGIN_MS: number;
+/** The fields of a Google service-account JSON key that sending needs. */
+export interface ServiceAccount {
+    project_id: string;
+    client_email: string;
+    private_key: string;
+    private_key_id?: string;
+    token_uri?: string;
+}
+export interface FcmOptions extends RetryOptions {
+    /** The service account's JSON key: the file's text (as kept in a secret) or the parsed object. */
+    serviceAccount: string | ServiceAccount;
+    /** Endpoint overrides (tests, proxies). The token URL defaults to the key's `token_uri`. */
+    sendUrl?: string;
+    tokenUrl?: string;
+    /** Text shown for sealed pushes when the app cannot decrypt (sent in clear as `fallbackTitle`/`fallbackBody`). */
+    fallback?: PushFallback;
+    /** Requests in flight at once (default 10). */
+    concurrency?: number;
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+/** Parses and checks a service-account key; throws a message naming what is missing (never echoing the key). */
+export declare function parseServiceAccount(value: string | ServiceAccount): ServiceAccount;
+/** A registration token as `getDevicePushTokenAsync` returns it on Android. */
+export declare function isFcmToken(token: unknown): token is string;
+/** FCM's error codes (`google.firebase.fcm.v1.FcmError`, falling back to the HTTP status) → Ember's codes. */
+export declare function fcmErrorCode(status: number, errorCode: string | undefined): PushErrorCode;
+/** Forgets cached access tokens (tests; after rotating a key). */
+export declare function clearFcmTokenCache(): void;
+/**
+ * An OAuth access token for the service account (scope `firebase.messaging`): an RS256 assertion exchanged at the
+ * token endpoint, cached per isolate until `FCM_TOKEN_MARGIN_MS` before it expires.
+ */
+export declare function fcmAccessToken(o: FcmOptions, force?: boolean): Promise<string>;
+/**
+ * The v1 `message` for one push. In clear: a `notification` (title/body; the system shows it while the app is in the
+ * background) and `data.body` = JSON of `data`, where expo-notifications reads it on Android. Sealed: a data-only
+ * message, `{ ember: <envelope JSON>, fallbackTitle, fallbackBody, channelId?, tag? }`, which the app's background
+ * task decrypts and shows (`@freecorps/ember-expo-push`). Background (`contentAvailable` with nothing to show): data only.
+ */
+export declare function fcmMessage(m: AddressedPushMessage, fallback?: PushFallback): Record<string, unknown>;
+/**
+ * Sends each message as its own v1 request, `concurrency` at a time. Never throws for message failures: they come
+ * back as error tickets (`DeviceNotRegistered` for `UNREGISTERED`, which callers prune). A broken service account
+ * fails every message with `InvalidCredentials`.
+ */
+export declare function sendFcm(messages: AddressedPushMessage[], o: FcmOptions): Promise<PushTicket[]>;
+/** Direct FCM as a `PushProvider`. No receipts: FCM answers each request synchronously. */
+export declare function fcmPushProvider(o: FcmOptions): PushProvider;

package/dist/fcm.js

@@ -0,0 +1,215 @@
+/**
+ * Direct FCM sender (HTTP v1 API), written for Ember from Google's documentation ("Authorize send requests",
+ * "Using OAuth 2.0 for Server to Server Applications", "FCM HTTP v1 API" and its `FcmError` codes). Behaviour matches
+ * Freecorps Brigade's relay as its README describes it (access token kept until 5 minutes before it expires and
+ * refetched on a 401; `UNREGISTERED` drops the device, `SENDER_ID_MISMATCH` does not; data-only messages for sealed
+ * pushes); no code is taken from the relay (AGPL).
+ *
+ * FCM speaks HTTP/1.1, so unlike APNs this also works from local workerd (`ember dev`).
+ */
+import { DEFAULT_PUSH_FALLBACK, byteLength, fetchWithRetry, mapLimit, resolveTtlSeconds, resolveUrgency } from "./delivery.js";
+import { isExpoPushToken } from "./expo.js";
+import { importSigningKey, signJwt } from "./jwt.js";
+export const FCM_SEND_URL = (projectId) => `https://fcm.googleapis.com/v1/projects/${encodeURIComponent(projectId)}/messages:send`;
+export const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+export const FCM_SCOPE = "https://www.googleapis.com/auth/firebase.messaging";
+/** FCM's own limits: 4096 bytes of message payload, TTL at most 28 days. */
+export const FCM_MAX_PAYLOAD = 4096;
+export const FCM_MAX_TTL_SECONDS = 28 * 24 * 3600;
+/** An access token is refetched this long before it expires. */
+export const FCM_TOKEN_MARGIN_MS = 5 * 60_000;
+/** Parses and checks a service-account key; throws a message naming what is missing (never echoing the key). */
+export function parseServiceAccount(value) {
+    let sa = value;
+    if (typeof value === "string") {
+        try {
+            sa = JSON.parse(value);
+        }
+        catch {
+            throw new Error("FCM service account is not valid JSON (expected the key file's contents)");
+        }
+    }
+    const o = sa;
+    const missing = ["project_id", "client_email", "private_key"].filter((k) => typeof o?.[k] !== "string" || !o[k]);
+    if (missing.length)
+        throw new Error(`FCM service account is missing ${missing.join(", ")}`);
+    return o;
+}
+/** A registration token as `getDevicePushTokenAsync` returns it on Android. */
+export function isFcmToken(token) {
+    return typeof token === "string" && /^[\w\-:.]{20,4096}$/.test(token) && !isExpoPushToken(token);
+}
+/** FCM's error codes (`google.firebase.fcm.v1.FcmError`, falling back to the HTTP status) → Ember's codes. */
+export function fcmErrorCode(status, errorCode) {
+    switch (errorCode) {
+        case "UNREGISTERED":
+            return "DeviceNotRegistered";
+        case "SENDER_ID_MISMATCH":
+            return "MismatchSenderId";
+        case "QUOTA_EXCEEDED":
+            return "MessageRateExceeded";
+        case "THIRD_PARTY_AUTH_ERROR":
+            return "InvalidCredentials";
+        case "INVALID_ARGUMENT":
+            // Also a malformed token, but just as often a bad payload: never prune on it.
+            return "InvalidArgument";
+    }
+    if (status === 401 || status === 403)
+        return "InvalidCredentials";
+    if (status === 429)
+        return "MessageRateExceeded";
+    return "RequestFailed";
+}
+const accessTokens = new Map();
+/** Forgets cached access tokens (tests; after rotating a key). */
+export function clearFcmTokenCache() {
+    accessTokens.clear();
+    inFlight.clear();
+}
+/**
+ * An OAuth access token for the service account (scope `firebase.messaging`): an RS256 assertion exchanged at the
+ * token endpoint, cached per isolate until `FCM_TOKEN_MARGIN_MS` before it expires.
+ */
+export async function fcmAccessToken(o, force = false) {
+    const sa = parseServiceAccount(o.serviceAccount);
+    const now = (o.now ?? Date.now)();
+    const tokenUrl = o.tokenUrl ?? sa.token_uri ?? GOOGLE_TOKEN_URL;
+    const cacheKey = `${sa.client_email}\u0000${sa.private_key_id ?? ""}\u0000${tokenUrl}`;
+    const hit = accessTokens.get(cacheKey);
+    if (!force && hit && now < hit.expiresAt - FCM_TOKEN_MARGIN_MS)
+        return hit.token;
+    // Concurrent sends share one exchange instead of each fetching a token.
+    const pending = inFlight.get(cacheKey);
+    if (pending)
+        return pending;
+    const p = exchange(o, sa, tokenUrl, now).then((t) => {
+        accessTokens.set(cacheKey, t);
+        return t.token;
+    });
+    inFlight.set(cacheKey, p);
+    try {
+        return await p;
+    }
+    finally {
+        inFlight.delete(cacheKey);
+    }
+}
+const inFlight = new Map();
+async function exchange(o, sa, tokenUrl, now) {
+    const key = await importSigningKey(sa.private_key, "RS256");
+    const iat = Math.floor(now / 1000);
+    const assertion = await signJwt("RS256", key, { iss: sa.client_email, scope: FCM_SCOPE, aud: tokenUrl, iat, exp: iat + 3600 }, sa.private_key_id ? { kid: sa.private_key_id } : {});
+    const fetchFn = (o.fetch ?? globalThis.fetch).bind(globalThis);
+    const res = await fetchWithRetry(fetchFn, tokenUrl, () => ({
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion }).toString(),
+    }), o);
+    const body = (await res.json().catch(() => ({})));
+    if (!res.ok || !body.access_token) {
+        throw Object.assign(new Error(`Google token endpoint: ${res.status} ${body.error ?? ""} ${body.error_description ?? ""}`.trim()), { credentials: res.status === 400 || res.status === 401 });
+    }
+    return { token: body.access_token, expiresAt: now + (body.expires_in ?? 3600) * 1000 };
+}
+/**
+ * The v1 `message` for one push. In clear: a `notification` (title/body; the system shows it while the app is in the
+ * background) and `data.body` = JSON of `data`, where expo-notifications reads it on Android. Sealed: a data-only
+ * message, `{ ember: <envelope JSON>, fallbackTitle, fallbackBody, channelId?, tag? }`, which the app's background
+ * task decrypts and shows (`@freecorps/ember-expo-push`). Background (`contentAvailable` with nothing to show): data only.
+ */
+export function fcmMessage(m, fallback = DEFAULT_PUSH_FALLBACK) {
+    const urgency = resolveUrgency(m);
+    const ttl = Math.min(FCM_MAX_TTL_SECONDS, resolveTtlSeconds(m));
+    const android = { priority: urgency === "low" ? "NORMAL" : "HIGH", ttl: `${ttl}s` };
+    if (m.collapseId)
+        android.collapse_key = m.collapseId;
+    const message = { token: m.to, android };
+    if (m.sealed) {
+        const data = { ember: JSON.stringify(m.sealed), urgency };
+        if (fallback.title)
+            data.fallbackTitle = fallback.title;
+        if (fallback.body)
+            data.fallbackBody = fallback.body;
+        if (m.channelId)
+            data.channelId = m.channelId;
+        if (m.collapseId)
+            data.tag = m.collapseId;
+        message.data = data;
+        return message;
+    }
+    if (m.title || m.body) {
+        const notification = {};
+        if (m.title)
+            notification.title = m.title;
+        if (m.body)
+            notification.body = m.body;
+        message.notification = notification;
+        const an = {};
+        if (m.channelId)
+            an.channel_id = m.channelId;
+        if (m.sound)
+            an.sound = m.sound;
+        if (m.collapseId)
+            an.tag = m.collapseId;
+        if (m.badge !== undefined)
+            an.notification_count = m.badge;
+        if (Object.keys(an).length)
+            android.notification = an;
+    }
+    if (m.data)
+        message.data = { body: JSON.stringify(m.data) };
+    return message;
+}
+/**
+ * Sends each message as its own v1 request, `concurrency` at a time. Never throws for message failures: they come
+ * back as error tickets (`DeviceNotRegistered` for `UNREGISTERED`, which callers prune). A broken service account
+ * fails every message with `InvalidCredentials`.
+ */
+export async function sendFcm(messages, o) {
+    const fetchFn = (o.fetch ?? globalThis.fetch)?.bind(globalThis);
+    if (!fetchFn)
+        throw new Error("@freecorps/ember-push: no fetch available; pass options.fetch");
+    let sa;
+    try {
+        sa = parseServiceAccount(o.serviceAccount);
+    }
+    catch (e) {
+        return messages.map((m) => ({ token: String(m.to), status: "error", error: "InvalidCredentials", message: e.message }));
+    }
+    const url = o.sendUrl ?? FCM_SEND_URL(sa.project_id);
+    const sendOne = async (m) => {
+        if (!isFcmToken(m.to))
+            return { token: String(m.to), status: "error", error: "InvalidToken", message: "not an FCM registration token" };
+        const message = fcmMessage(m, o.fallback);
+        const body = JSON.stringify({ message });
+        if (byteLength(JSON.stringify({ n: message.notification, d: message.data })) > FCM_MAX_PAYLOAD) {
+            return { token: m.to, status: "error", error: "MessageTooBig", message: `FCM payload over ${FCM_MAX_PAYLOAD} bytes` };
+        }
+        let refreshed = false;
+        try {
+            for (;;) {
+                const access = await fcmAccessToken(o, refreshed);
+                const res = await fetchWithRetry(fetchFn, url, () => ({ method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${access}` }, body }), o);
+                const json = (await res.json().catch(() => ({})));
+                if (res.ok)
+                    return { token: m.to, status: "ok", id: json.name ?? "" };
+                if (res.status === 401 && !refreshed) {
+                    refreshed = true;
+                    continue;
+                }
+                const errorCode = json.error?.details?.find((d) => d.errorCode)?.errorCode ?? json.error?.status;
+                return { token: m.to, status: "error", error: fcmErrorCode(res.status, errorCode), message: `FCM ${res.status} ${errorCode ?? ""}: ${json.error?.message ?? ""}`.trim() };
+            }
+        }
+        catch (e) {
+            const err = e;
+            const message = err.message.startsWith("Google") ? err.message : err.credentials ? `FCM service account key: ${err.message}` : `FCM unreachable: ${err.message}`;
+            return { token: m.to, status: "error", error: err.credentials ? "InvalidCredentials" : "RequestFailed", message };
+        }
+    };
+    return mapLimit(messages, o.concurrency ?? 10, sendOne);
+}
+/** Direct FCM as a `PushProvider`. No receipts: FCM answers each request synchronously. */
+export function fcmPushProvider(o) {
+    return { name: "fcm", isToken: isFcmToken, send: (messages) => sendFcm(messages, o) };
+}

package/dist/hpke.d.ts

@@ -0,0 +1,37 @@
+type Bytes = Uint8Array<ArrayBuffer>;
+/** An uncompressed P-256 point (0x04 || x || y): the encapsulated key and every public key. */
+export declare const P256_PUBLIC_KEY_LENGTH = 65;
+export interface HpkeSealed {
+    /** The sender's ephemeral public key (65 bytes). */
+    enc: Bytes;
+    /** Ciphertext followed by the 16-byte GCM tag. */
+    ct: Bytes;
+}
+export interface HpkeRecipient {
+    privateKey: CryptoKey;
+    /** The recipient's public key, uncompressed (65 bytes); part of the KEM context. */
+    publicKey: Uint8Array;
+}
+export interface HpkeOptions {
+    info?: Uint8Array;
+    aad?: Uint8Array;
+}
+export interface SealOptions extends HpkeOptions {
+    /** Test vectors only: a fixed ephemeral key pair instead of a fresh one. Never reuse one in real use. */
+    ephemeral?: CryptoKeyPair;
+}
+/** Encrypts `plaintext` to the holder of the private key for `recipientPublicKey` (uncompressed P-256). */
+export declare function seal(recipientPublicKey: Uint8Array, plaintext: Uint8Array, options?: SealOptions): Promise<HpkeSealed>;
+/** Decrypts what `seal` produced. Throws if the key, `info`, `aad` or any byte does not match. */
+export declare function open(recipient: HpkeRecipient, sealed: {
+    enc: Uint8Array;
+    ct: Uint8Array;
+}, options?: HpkeOptions): Promise<Bytes>;
+/** A fresh recipient key pair. The private key is not extractable. */
+export declare function generateRecipient(): Promise<HpkeRecipient>;
+/**
+ * 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 declare function importKeyPair(privateKey: Uint8Array, publicKey: Uint8Array): Promise<CryptoKeyPair>;
+export {};

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, 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 } 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));
+}