@freecorps/ember-push 0.1.0 → 0.3.0

package/dist/envelope.js

@@ -0,0 +1,121 @@
+// Adapted from Freecorps Brigade, packages/push/src/envelope.ts (MIT License, Copyright (c) 2026 Freecorps Tecnologia
+// da Informação LTDA; https://github.com/freecorps/brigade/tree/main/packages/push): the envelope shape (`v`, `k`,
+// `enc`, `ct`, base64url), the key id, the plaintext limit and the validation of untrusted input come from there. The
+// content is Ember's (title/subtitle/body/data instead of Brigade's incident fields) and the HPKE `info` is Ember's own,
+// so a Brigade ciphertext never opens as an Ember push or the other way round.
+import { fromBase64url, toBase64url } from "./base64url.js";
+import { open, P256_PUBLIC_KEY_LENGTH, seal } from "./hpke.js";
+export const EMBER_PUSH_ENVELOPE_VERSION = 1;
+/**
+ * HPKE `info`: binds every ciphertext to this protocol and version. The iOS Notification Service Extension and the
+ * Android decoder in `@freecorps/ember-expo-push` use the same string. Change it (and `v`) together everywhere.
+ */
+export const EMBER_PUSH_HPKE_INFO = "freecorps.ember push v1";
+/**
+ * Plaintext limit in UTF-8 bytes (Brigade's): about 2.8 KB once sealed and base64url-encoded, which leaves room in
+ * APNs' and FCM's 4 KB for the fallback text and the other fields.
+ */
+export const PUSH_PLAINTEXT_MAX_BYTES = 2048;
+/** A key id: 8 base64url characters (`pushKeyId`). */
+export const PUSH_KEY_ID = /^[A-Za-z0-9_-]{8}$/;
+const encoder = new TextEncoder();
+const info = encoder.encode(EMBER_PUSH_HPKE_INFO);
+/**
+ * Seals `content` for a device, given its public key as the device registered it (base64url of the uncompressed
+ * P-256 point, 65 bytes). Throws over `PUSH_PLAINTEXT_MAX_BYTES` or for a malformed key.
+ */
+export async function sealPushContent(devicePublicKey, content, opts = {}) {
+    const key = parseDevicePublicKey(devicePublicKey);
+    const iat = Math.floor((opts.now ?? Date.now()) / 1000);
+    const { title, subtitle, body, data } = content;
+    const plaintext = encoder.encode(JSON.stringify({ title, subtitle, body, data, iat }));
+    if (plaintext.length > PUSH_PLAINTEXT_MAX_BYTES) {
+        throw new Error(`push content is ${plaintext.length} bytes, over ${PUSH_PLAINTEXT_MAX_BYTES}`);
+    }
+    const sealed = await seal(key, plaintext, { info });
+    return { v: EMBER_PUSH_ENVELOPE_VERSION, k: await pushKeyId(key), enc: toBase64url(sealed.enc), ct: toBase64url(sealed.ct) };
+}
+/** Opens an envelope (what the device does; for tests and JS clients with WebCrypto). Throws if it does not open. */
+export async function openPushEnvelope(recipient, envelope) {
+    const plaintext = await open(recipient, { enc: fromBase64url(envelope.enc), ct: fromBase64url(envelope.ct) }, { info });
+    return parseOpenedContent(JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: false }).decode(plaintext)));
+}
+/** The plaintext of an envelope as a device accepts it; throws for anything else. */
+export function parseOpenedContent(value) {
+    if (!isRecord(value) || !Number.isSafeInteger(value.iat))
+        throw new Error("push content has no iat");
+    const out = { iat: value.iat };
+    for (const f of ["title", "subtitle", "body"]) {
+        const s = value[f];
+        if (s === undefined || s === null)
+            continue;
+        if (typeof s !== "string")
+            throw new Error(`push content ${f} is not a string`);
+        out[f] = s;
+    }
+    if (value.data !== undefined && value.data !== null) {
+        if (!isRecord(value.data))
+            throw new Error("push content data is not an object");
+        out.data = value.data;
+    }
+    return out;
+}
+/**
+ * The id of a device key, as an envelope names it (`k`): base64url of the first 6 bytes of SHA-256 over the
+ * uncompressed public key, 8 characters (Brigade's `pushKeyId`). Only a hint for which key to try; the AEAD decides.
+ */
+export async function pushKeyId(publicKey) {
+    const key = typeof publicKey === "string" ? parseDevicePublicKey(publicKey) : publicKey;
+    if (key.length !== P256_PUBLIC_KEY_LENGTH || key[0] !== 0x04)
+        throw new Error("device public key must be an uncompressed P-256 point");
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new Uint8Array(key)));
+    return toBase64url(digest.subarray(0, 6));
+}
+/** Accepts an envelope from untrusted JSON (or the JSON string FCM data carries), or returns null. */
+export function parsePushEnvelope(value) {
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!isRecord(value) || value.v !== EMBER_PUSH_ENVELOPE_VERSION)
+        return null;
+    const { k, enc, ct } = value;
+    if (typeof k !== "string" || !PUSH_KEY_ID.test(k) || typeof enc !== "string" || typeof ct !== "string")
+        return null;
+    try {
+        // 16 bytes is the GCM tag alone: an empty plaintext.
+        if (fromBase64url(enc).length !== P256_PUBLIC_KEY_LENGTH || fromBase64url(ct).length < 16)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { v: EMBER_PUSH_ENVELOPE_VERSION, k, enc, ct };
+}
+/** A device public key from its base64url form; throws unless it is an uncompressed P-256 point. */
+export function parseDevicePublicKey(value) {
+    const key = fromBase64url(value);
+    if (key.length !== P256_PUBLIC_KEY_LENGTH || key[0] !== 0x04) {
+        throw new Error("device public key must be an uncompressed P-256 point (65 bytes, base64url)");
+    }
+    return key;
+}
+/** Cheap shape check for registration (the curve check happens when sealing). */
+export function isDevicePublicKey(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        parseDevicePublicKey(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/expo.d.ts

@@ -1,8 +1,3 @@
-/**
- * Expo Push Service client (plain HTTPS + JSON, so it runs in a Worker action). Facts (docs.expo.dev, checked in
- * CLOUDFLARE.md §8): 100 messages per request, 600 notifications/s per project, 4096-byte payload, receipts kept
- * 24 h, optional access token ("enhanced push security").
- */
 import type { AddressedPushMessage, PushMessage, PushProvider, PushTicket, ReceiptCheck, SendPushResult } from "./types.ts";
 export declare const EXPO_PUSH_URL = "https://exp.host/--/api/v2/push/send";
 export declare const EXPO_RECEIPTS_URL = "https://exp.host/--/api/v2/push/getReceipts";
@@ -31,7 +26,13 @@ export interface ExpoPushOptions {
 }
 /** `ExponentPushToken[...]` / `ExpoPushToken[...]` (or the older bare UUID form). */
 export declare function isExpoPushToken(token: unknown): token is string;
-/** The JSON Expo expects for one message. */
+/**
+ * The JSON Expo expects for one message. `collapseId`, `threadId` and `interruptionLevel` are Expo fields too and go
+ * as they are; `collapseId` is also Expo's Android `tag` (unless one is set) so an Android notification already shown
+ * is replaced, as with direct FCM. Fields only the direct transports understand (`urgency`, `encryption`, `voip`,
+ * `environment`, `sealed`) are not sent; `urgency` becomes Expo's `priority` when that is not set (`low` → `normal`,
+ * else `high`).
+ */
 export declare function toExpoMessage(m: AddressedPushMessage): Record<string, unknown>;
 /** Payload size Expo checks against 4096 B: the notification fields plus `data`. */
 export declare function payloadSize(m: PushMessage): number;

package/dist/expo.js

@@ -1,3 +1,9 @@
+/**
+ * Expo Push Service client (plain HTTPS + JSON, so it runs in a Worker action). Facts (docs.expo.dev, checked in
+ * CLOUDFLARE.md §8): 100 messages per request, 600 notifications/s per project, 4096-byte payload, receipts kept
+ * 24 h, optional access token ("enhanced push security").
+ */
+import { soundName } from "./delivery.js";
 export const EXPO_PUSH_URL = "https://exp.host/--/api/v2/push/send";
 export const EXPO_RECEIPTS_URL = "https://exp.host/--/api/v2/push/getReceipts";
 /** Messages per `send` request. */
@@ -13,15 +19,29 @@ export function isExpoPushToken(token) {
     return (/^Expo(?:nent)?PushToken\[[^\]]+\]$/.test(token) ||
         /^[a-z\d]{8}-[a-z\d]{4}-[a-z\d]{4}-[a-z\d]{4}-[a-z\d]{12}$/i.test(token));
 }
-/** The JSON Expo expects for one message. */
+/**
+ * The JSON Expo expects for one message. `collapseId`, `threadId` and `interruptionLevel` are Expo fields too and go
+ * as they are; `collapseId` is also Expo's Android `tag` (unless one is set) so an Android notification already shown
+ * is replaced, as with direct FCM. Fields only the direct transports understand (`urgency`, `encryption`, `voip`,
+ * `environment`, `sealed`) are not sent; `urgency` becomes Expo's `priority` when that is not set (`low` → `normal`,
+ * else `high`).
+ */
 export function toExpoMessage(m) {
-    const { contentAvailable, ...rest } = m;
+    const { contentAvailable, urgency, encryption, voip, environment, sealed, payload, ...rest } = m;
+    void payload; // the app's own APNs/FCM payload: Expo builds its own
     const out = {};
     for (const [k, val] of Object.entries(rest))
         if (val !== undefined)
             out[k] = val;
+    // Expo takes a sound name: a Critical Alert sound plays its name there.
+    if (typeof out.sound === "object" && out.sound !== null)
+        out.sound = soundName(out.sound) ?? "default";
     if (contentAvailable)
         out._contentAvailable = true;
+    if (urgency && out.priority === undefined)
+        out.priority = urgency === "low" ? "normal" : "high";
+    if (typeof out.collapseId === "string" && out.tag === undefined)
+        out.tag = out.collapseId;
     return out;
 }
 const utf8Length = (s) => new TextEncoder().encode(s).length;

package/dist/fcm.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 longest a token exchange may take, retries included. It is shared by every send waiting for it, so it has its
+ * own limit, never a caller's `timeoutMs` or `signal` (a caller with a short deadline only stops its own wait).
+ */
+export declare const FCM_EXCHANGE_TIMEOUT_MS = 30000;
+/** 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. `force` exchanges again: `true`
+ * always; a token string only if the cache still holds that token (after FCM answered 401 to it, so concurrent sends
+ * that saw the same refused token exchange once, and a token another send already replaced is used as is).
+ * Concurrent callers share one exchange. `signal` (default: `o.signal` and `o.timeoutMs`) bounds this caller's wait
+ * only; the shared exchange runs under its own `FCM_EXCHANGE_TIMEOUT_MS`, whoever started it.
+ */
+export declare function fcmAccessToken(o: FcmOptions, force?: boolean | string, signal?: AbortSignal | undefined): 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,244 @@
+/**
+ * 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, deadlineSignal, soundName, fetchWithRetry, mapLimit, resolveTtlSeconds, resolveUrgency, untilAborted } 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;
+/**
+ * The longest a token exchange may take, retries included. It is shared by every send waiting for it, so it has its
+ * own limit, never a caller's `timeoutMs` or `signal` (a caller with a short deadline only stops its own wait).
+ */
+export const FCM_EXCHANGE_TIMEOUT_MS = 30_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. `force` exchanges again: `true`
+ * always; a token string only if the cache still holds that token (after FCM answered 401 to it, so concurrent sends
+ * that saw the same refused token exchange once, and a token another send already replaced is used as is).
+ * Concurrent callers share one exchange. `signal` (default: `o.signal` and `o.timeoutMs`) bounds this caller's wait
+ * only; the shared exchange runs under its own `FCM_EXCHANGE_TIMEOUT_MS`, whoever started it.
+ */
+export async function fcmAccessToken(o, force = false, signal = deadlineSignal(o)) {
+    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);
+    const fresh = !!hit && now < hit.expiresAt - FCM_TOKEN_MARGIN_MS;
+    const refresh = force === true || (typeof force === "string" && hit?.token === force);
+    if (fresh && !refresh)
+        return hit.token;
+    // Concurrent sends share one exchange instead of each fetching a token.
+    let p = inFlight.get(cacheKey);
+    if (!p) {
+        // Never the starter's deadline: other sends wait on this exchange too.
+        const started = exchange(o, sa, tokenUrl, now, AbortSignal.timeout(FCM_EXCHANGE_TIMEOUT_MS)).then((t) => {
+            accessTokens.set(cacheKey, t);
+            return t.token;
+        });
+        p = started;
+        inFlight.set(cacheKey, started);
+        started.then(() => inFlight.delete(cacheKey), () => inFlight.delete(cacheKey));
+    }
+    return untilAborted(p, signal);
+}
+const inFlight = new Map();
+async function exchange(o, sa, tokenUrl, now, signal) {
+    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, signal);
+    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 };
+    // The app built its own data message (its envelope, its keys): sent as given, with Ember's priority, TTL and collapse key.
+    if (m.payload?.fcmData) {
+        message.data = m.payload.fcmData;
+        return message;
+    }
+    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;
+        const sound = soundName(m.sound);
+        if (sound)
+            an.sound = 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 own = m.payload?.fcmData;
+        if (own && Object.values(own).some((x) => typeof x !== "string")) {
+            return { token: m.to, status: "error", error: "InvalidArgument", message: "payload.fcmData values must be strings (FCM data messages)" };
+        }
+        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` };
+        }
+        // One deadline for the whole send: the access token and every try.
+        const signal = deadlineSignal(o);
+        let refused;
+        try {
+            for (;;) {
+                const access = await fcmAccessToken(o, refused ?? false, signal);
+                const res = await fetchWithRetry(fetchFn, url, () => ({ method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${access}` }, body }), o, signal);
+                const json = (await res.json().catch(() => ({})));
+                if (res.ok)
+                    return { token: m.to, status: "ok", id: json.name ?? "" };
+                if (res.status === 401 && refused === undefined) {
+                    // A new token, unless another send already replaced this one; never this refused one again.
+                    refused = access;
+                    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(),
+                    ...(errorCode ? { reason: errorCode } : {}),
+                    httpStatus: res.status,
+                };
+            }
+        }
+        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 {};