@freecorps/ember-push 0.1.0 → 0.2.0

package/dist/devices.d.ts

@@ -1,5 +1,13 @@
+import type { ApnsEnvironment } from "./types.ts";
 export declare const PUSH_DEVICES_TABLE = "pushDevices";
-/** `{ userId, token, provider, platform?, deviceName?, updatedAt }` with `by_user` and `by_token` indexes. */
+export type PushProviderName = "expo" | "apns" | "fcm";
+/** Whether `p` is a provider `sendToDevices` knows (`expo`, `apns`, `fcm`; exact case). */
+export declare function isPushProviderName(p: unknown): p is PushProviderName;
+/**
+ * `{ userId, token, provider, platform?, deviceName?, environment?, voipToken?, publicKey?, updatedAt }` with
+ * `by_user` and `by_token` indexes. The direct-transport fields are optional, so an existing table gains them with no
+ * migration.
+ */
 export declare function pushDevicesTable(): import("@freecorps/ember-server").TableDefinition<import("@freecorps/ember-values").ObjectValidator<{
     userId: import("@freecorps/ember-values").Validator<string, "required", never>;
     token: import("@freecorps/ember-values").Validator<string, "required", never>;
@@ -7,6 +15,12 @@ export declare function pushDevicesTable(): import("@freecorps/ember-server").Ta
     provider: import("@freecorps/ember-values").Validator<string, "required", never>;
     platform: import("@freecorps/ember-values").Validator<string, "optional", never>;
     deviceName: import("@freecorps/ember-values").Validator<string, "optional", never>;
+    /** APNs environment of an iOS token: "sandbox" | "production". */
+    environment: import("@freecorps/ember-values").Validator<string, "optional", never>;
+    /** iOS PushKit token (VoIP pushes, `voip: true`). */
+    voipToken: import("@freecorps/ember-values").Validator<string, "optional", never>;
+    /** Device public key for sealed pushes (uncompressed P-256, base64url). */
+    publicKey: import("@freecorps/ember-values").Validator<string, "optional", never>;
     /** ms since epoch of the last registration (stale devices can be pruned). */
     updatedAt: import("@freecorps/ember-values").Validator<number, "required", never>;
 }>, {
@@ -21,6 +35,9 @@ export interface PushDevice {
     provider: string;
     platform?: string;
     deviceName?: string;
+    environment?: ApnsEnvironment;
+    voipToken?: string;
+    publicKey?: string;
     updatedAt: number;
 }
 /**
@@ -43,13 +60,20 @@ type WriterDb = Db & {
 export interface RegisterPushDeviceInput {
     userId: string;
     token: string;
+    /** Default: inferred from the token (Expo token → `expo`, hex → `apns`, `platform: "android"` → `fcm`), else `expo`. */
     provider?: string;
     platform?: string;
     deviceName?: string;
+    environment?: string;
+    voipToken?: string;
+    publicKey?: string;
 }
+/** The provider a token belongs to when the caller did not say. */
+export declare function inferPushProvider(token: string, platform?: string): PushProviderName;
 /**
  * Upserts a device by token. A token re-registered by another user (shared device, account switch) moves to that
- * user. Returns the device id.
+ * user. Fields left out keep their stored value. Returns the device id. Throws for an `environment` other than
+ * `sandbox`/`production`, a `provider` other than `expo`/`apns`/`fcm` or a malformed `publicKey`, so a bad registration fails at the client instead of at send time.
  */
 export declare function registerPushDevice(ctx: {
     db: WriterDb;
@@ -59,7 +83,19 @@ export declare function registerPushDevice(ctx: {
 export declare function unregisterPushDevice(db: WriterDb, token: string, table?: string): boolean;
 /** Removes every device with one of `tokens` (e.g. `unregisteredTokens` from `sendPush`/`checkPushReceipts`). */
 export declare function removePushTokens(db: WriterDb, tokens: Iterable<string>, table?: string): number;
+/** Clears dead VoIP tokens (`unregisteredVoipTokens` from `sendToDevices`); the devices keep their push token. */
+export declare function removeVoipTokens(db: WriterDb, entries: Iterable<{
+    userId: string;
+    voipToken: string;
+}>, table?: string): number;
+/** Records the APNs environment a send discovered for a device registered without one. */
+export declare function setPushDeviceEnvironment(db: WriterDb, token: string, environment: ApnsEnvironment, table?: string): boolean;
 export declare function pushDevicesForUser(db: Db, userId: string, table?: string): PushDevice[];
+/** Devices of these users (one per token), optionally of one provider: what `sendToDevices` takes. */
+export declare function pushDevicesForUsers(db: Db, userIds: Iterable<string>, opts?: {
+    provider?: string;
+    table?: string;
+}): PushDevice[];
 /** Distinct tokens of these users, optionally of one provider. */
 export declare function pushTokensForUsers(db: Db, userIds: Iterable<string>, opts?: {
     provider?: string;

package/dist/devices.js

@@ -10,11 +10,26 @@
  *     args: { token: v.string(), platform: v.optional(v.string()) },
  *     handler: (ctx, args) => registerPushDevice(ctx, { userId: requireUser(ctx).subject, ...args }),
  *   });
+ *
+ * A device is one push token: an Expo token (`provider: "expo"`), or a native one for the direct transport (`apns`
+ * with its `environment`, `fcm`). Direct devices may also carry a PushKit `voipToken` and the `publicKey` their pushes
+ * are sealed to (end-to-end encryption, `@freecorps/ember-expo-push`).
  */
 import { defineTable } from "@freecorps/ember-server";
 import { v } from "@freecorps/ember-values";
+import { isApnsToken } from "./apns.js";
+import { isDevicePublicKey } from "./envelope.js";
+import { isExpoPushToken } from "./expo.js";
 export const PUSH_DEVICES_TABLE = "pushDevices";
-/** `{ userId, token, provider, platform?, deviceName?, updatedAt }` with `by_user` and `by_token` indexes. */
+/** Whether `p` is a provider `sendToDevices` knows (`expo`, `apns`, `fcm`; exact case). */
+export function isPushProviderName(p) {
+    return p === "expo" || p === "apns" || p === "fcm";
+}
+/**
+ * `{ userId, token, provider, platform?, deviceName?, environment?, voipToken?, publicKey?, updatedAt }` with
+ * `by_user` and `by_token` indexes. The direct-transport fields are optional, so an existing table gains them with no
+ * migration.
+ */
 export function pushDevicesTable() {
     return defineTable({
         userId: v.string(),
@@ -23,6 +38,12 @@ export function pushDevicesTable() {
         provider: v.string(),
         platform: v.optional(v.string()),
         deviceName: v.optional(v.string()),
+        /** APNs environment of an iOS token: "sandbox" | "production". */
+        environment: v.optional(v.string()),
+        /** iOS PushKit token (VoIP pushes, `voip: true`). */
+        voipToken: v.optional(v.string()),
+        /** Device public key for sealed pushes (uncompressed P-256, base64url). */
+        publicKey: v.optional(v.string()),
         /** ms since epoch of the last registration (stale devices can be pruned). */
         updatedAt: v.number(),
     })
@@ -30,23 +51,42 @@ export function pushDevicesTable() {
         .index("by_token", ["token"]);
 }
 const byToken = (db, table, token) => db.query(table).withIndex("by_token", (q) => q.eq("token", token)).unique();
+/** The provider a token belongs to when the caller did not say. */
+export function inferPushProvider(token, platform) {
+    if (isExpoPushToken(token))
+        return "expo";
+    if (isApnsToken(token))
+        return "apns";
+    if (platform === "android")
+        return "fcm";
+    return "expo";
+}
 /**
  * Upserts a device by token. A token re-registered by another user (shared device, account switch) moves to that
- * user. Returns the device id.
+ * user. Fields left out keep their stored value. Returns the device id. Throws for an `environment` other than
+ * `sandbox`/`production`, a `provider` other than `expo`/`apns`/`fcm` or a malformed `publicKey`, so a bad registration fails at the client instead of at send time.
  */
 export function registerPushDevice(ctx, input, table = PUSH_DEVICES_TABLE) {
     if (!input.token)
         throw new Error("registerPushDevice: empty token");
+    if (input.environment !== undefined && input.environment !== "sandbox" && input.environment !== "production") {
+        throw new Error(`registerPushDevice: environment must be "sandbox" or "production", got ${JSON.stringify(input.environment)}`);
+    }
+    if (input.provider !== undefined && !isPushProviderName(input.provider)) {
+        throw new Error(`registerPushDevice: provider must be "expo", "apns" or "fcm", got ${JSON.stringify(input.provider)}`);
+    }
+    if (input.publicKey !== undefined && !isDevicePublicKey(input.publicKey)) {
+        throw new Error("registerPushDevice: publicKey must be an uncompressed P-256 point (65 bytes, base64url)");
+    }
     const fields = {
         userId: input.userId,
         token: input.token,
-        provider: input.provider ?? "expo",
+        provider: input.provider ?? inferPushProvider(input.token, input.platform),
         updatedAt: ctx.now,
     };
-    if (input.platform !== undefined)
-        fields.platform = input.platform;
-    if (input.deviceName !== undefined)
-        fields.deviceName = input.deviceName;
+    for (const f of ["platform", "deviceName", "environment", "voipToken", "publicKey"])
+        if (input[f] !== undefined)
+            fields[f] = input[f];
     const existing = byToken(ctx.db, table, input.token);
     if (existing) {
         ctx.db.patch(existing._id, fields);
@@ -69,15 +109,40 @@ export function removePushTokens(db, tokens, table = PUSH_DEVICES_TABLE) {
             n++;
     return n;
 }
+/** Clears dead VoIP tokens (`unregisteredVoipTokens` from `sendToDevices`); the devices keep their push token. */
+export function removeVoipTokens(db, entries, table = PUSH_DEVICES_TABLE) {
+    let n = 0;
+    for (const e of entries) {
+        for (const d of pushDevicesForUser(db, e.userId, table)) {
+            if (d.voipToken !== e.voipToken)
+                continue;
+            db.patch(d._id, { voipToken: undefined }); // undefined removes the field (Convex semantics)
+            n++;
+        }
+    }
+    return n;
+}
+/** Records the APNs environment a send discovered for a device registered without one. */
+export function setPushDeviceEnvironment(db, token, environment, table = PUSH_DEVICES_TABLE) {
+    const existing = byToken(db, table, token);
+    if (!existing || existing.environment === environment)
+        return false;
+    db.patch(existing._id, { environment });
+    return true;
+}
 export function pushDevicesForUser(db, userId, table = PUSH_DEVICES_TABLE) {
     return db.query(table).withIndex("by_user", (q) => q.eq("userId", userId)).collect();
 }
-/** Distinct tokens of these users, optionally of one provider. */
-export function pushTokensForUsers(db, userIds, opts = {}) {
-    const out = new Set();
+/** Devices of these users (one per token), optionally of one provider: what `sendToDevices` takes. */
+export function pushDevicesForUsers(db, userIds, opts = {}) {
+    const out = new Map();
     for (const u of new Set(userIds))
         for (const d of pushDevicesForUser(db, u, opts.table))
             if (!opts.provider || d.provider === opts.provider)
-                out.add(d.token);
-    return [...out];
+                out.set(d.token, d);
+    return [...out.values()];
+}
+/** Distinct tokens of these users, optionally of one provider. */
+export function pushTokensForUsers(db, userIds, opts = {}) {
+    return pushDevicesForUsers(db, userIds, opts).map((d) => d.token);
 }

package/dist/direct.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Sending to registered devices through whichever transport each one uses: Expo Push for Expo tokens, APNs or FCM
+ * directly for native tokens (`provider` in the device table). Content is sealed per device when the device has a
+ * public key and encryption allows it (see `PushEncryption`); APNs and FCM then see only the envelope and the fallback
+ * text.
+ *
+ *   const devices = await ctx.runQuery(internal.push.devicesOf, { userIds });
+ *   const r = await sendToDevices(devices, { title: "Ana Souza", body: "Re: orçamento", urgency: "high" }, {
+ *     apns: { keyId: env.APNS_KEY_ID, teamId: env.APNS_TEAM_ID, key: env.APNS_KEY, topic: "com.acme.mail" },
+ *     fcm: { serviceAccount: env.FCM_SERVICE_ACCOUNT },
+ *     encryption: "required",
+ *   });
+ *   // r.unregisteredTokens / r.unregisteredVoipTokens → prune; r.environments → record; r.expoTickets → receipts later
+ */
+import { type ApnsOptions } from "./apns.ts";
+import { type ExpoPushOptions } from "./expo.ts";
+import { type FcmOptions } from "./fcm.ts";
+import type { ApnsEnvironment, PushEncryption, PushFallback, PushMessage, PushTicket } from "./types.ts";
+/** What `sendToDevices` needs of a device (a `PushDevice` row fits). */
+export interface PushTarget {
+    token: string;
+    provider?: string;
+    platform?: string;
+    environment?: string;
+    publicKey?: string;
+    voipToken?: string;
+    userId?: string;
+}
+export interface PushTransports {
+    /** Expo Push options; `false` refuses Expo devices. Default `{}` (enabled, no access token). */
+    expo?: ExpoPushOptions | false;
+    /** Direct APNs; without it, `apns` devices get `ProviderNotConfigured` tickets (never pruned). */
+    apns?: ApnsOptions;
+    /** Direct FCM; without it, `fcm` devices get `ProviderNotConfigured` tickets. */
+    fcm?: FcmOptions;
+    /** Default `auto`; a message's `encryption` wins. */
+    encryption?: PushEncryption;
+    /** What sealed pushes show in clear (and `required` sends to devices without a key). */
+    fallback?: PushFallback;
+    now?: () => number;
+}
+export interface DeviceSendResult {
+    /** One per target (VoIP sends: one per target with a VoIP token), in order. */
+    tickets: PushTicket[];
+    /** Push tokens to delete (`DeviceNotRegistered` or a malformed token). */
+    unregisteredTokens: string[];
+    /** VoIP tokens APNs no longer accepts: clear them (`removeVoipTokens`), the device keeps its push token. */
+    unregisteredVoipTokens: Array<{
+        userId: string;
+        voipToken: string;
+    }>;
+    /** APNs environments discovered for devices registered without one: record them (`setPushDeviceEnvironment`). */
+    environments: Array<{
+        token: string;
+        environment: ApnsEnvironment;
+    }>;
+    /** Expo `ok` tickets, for `checkPushReceipts` later (APNs/FCM answers are final). */
+    expoTickets: PushTicket[];
+}
+/**
+ * Sends `message` to every target (duplicate tokens once). Never throws for per-device failures: they come back as
+ * error tickets (a provider other than `expo`/`apns`/`fcm` is `ProviderNotConfigured`, like one with no credentials). Encryption, per device:
+ * - `off`: clear;
+ * - `auto`: sealed when the device is `apns`/`fcm` and registered a public key, else clear;
+ * - `required`: sealed, or the fallback text only (no data) for an Expo device or one without a key.
+ * Only pushes with something to show (title/subtitle/body) are sealed; background (`contentAvailable` only) and VoIP
+ * pushes go as they are under `auto`, and lose their `data` under `required`.
+ */
+export declare function sendToDevices(targets: Iterable<PushTarget>, message: PushMessage, t?: PushTransports): Promise<DeviceSendResult>;

package/dist/direct.js

@@ -0,0 +1,136 @@
+/**
+ * Sending to registered devices through whichever transport each one uses: Expo Push for Expo tokens, APNs or FCM
+ * directly for native tokens (`provider` in the device table). Content is sealed per device when the device has a
+ * public key and encryption allows it (see `PushEncryption`); APNs and FCM then see only the envelope and the fallback
+ * text.
+ *
+ *   const devices = await ctx.runQuery(internal.push.devicesOf, { userIds });
+ *   const r = await sendToDevices(devices, { title: "Ana Souza", body: "Re: orçamento", urgency: "high" }, {
+ *     apns: { keyId: env.APNS_KEY_ID, teamId: env.APNS_TEAM_ID, key: env.APNS_KEY, topic: "com.acme.mail" },
+ *     fcm: { serviceAccount: env.FCM_SERVICE_ACCOUNT },
+ *     encryption: "required",
+ *   });
+ *   // r.unregisteredTokens / r.unregisteredVoipTokens → prune; r.environments → record; r.expoTickets → receipts later
+ */
+import { sendApns } from "./apns.js";
+import { DEFAULT_PUSH_FALLBACK } from "./delivery.js";
+import { sealPushContent } from "./envelope.js";
+import { sendExpoMessages } from "./expo.js";
+import { sendFcm } from "./fcm.js";
+import { inferPushProvider, isPushProviderName } from "./devices.js";
+const hasVisibleContent = (m) => !!(m.title || m.subtitle || m.body);
+/** The fallback-only version of a message: no title/subtitle/body/data beyond the fallback text. */
+function fallbackOnly(m, fallback) {
+    const { title, subtitle, body, data, ...rest } = m;
+    void title;
+    void subtitle;
+    void body;
+    void data;
+    const out = { ...rest };
+    if (fallback.title)
+        out.title = fallback.title;
+    if (fallback.body)
+        out.body = fallback.body;
+    return out;
+}
+/**
+ * Sends `message` to every target (duplicate tokens once). Never throws for per-device failures: they come back as
+ * error tickets (a provider other than `expo`/`apns`/`fcm` is `ProviderNotConfigured`, like one with no credentials). Encryption, per device:
+ * - `off`: clear;
+ * - `auto`: sealed when the device is `apns`/`fcm` and registered a public key, else clear;
+ * - `required`: sealed, or the fallback text only (no data) for an Expo device or one without a key.
+ * Only pushes with something to show (title/subtitle/body) are sealed; background (`contentAvailable` only) and VoIP
+ * pushes go as they are under `auto`, and lose their `data` under `required`.
+ */
+export async function sendToDevices(targets, message, t = {}) {
+    const mode = message.encryption ?? t.encryption ?? "auto";
+    const fallback = t.fallback ?? DEFAULT_PUSH_FALLBACK;
+    const now = t.now ?? Date.now;
+    const seen = new Set();
+    // `provider` is whatever the device row holds: anything but expo/apns/fcm gets an error ticket below.
+    const list = [];
+    for (const target of targets) {
+        const provider = target.provider ?? inferPushProvider(target.token, target.platform);
+        let to = target.token;
+        if (message.voip) {
+            if (provider !== "apns" || !target.voipToken)
+                continue;
+            to = target.voipToken;
+        }
+        if (seen.has(to))
+            continue;
+        seen.add(to);
+        list.push({ target, provider, to });
+    }
+    const tickets = new Array(list.length);
+    const groups = { expo: [], apns: [], fcm: [] };
+    await Promise.all(list.map(async ({ target, provider, to }, i) => {
+        if (!isPushProviderName(provider)) {
+            tickets[i] = { token: to, status: "error", error: "ProviderNotConfigured", message: `unknown push provider ${JSON.stringify(provider)} (expected expo, apns or fcm)` };
+            return;
+        }
+        let m = { ...message, to };
+        if (provider === "apns" && (target.environment === "sandbox" || target.environment === "production"))
+            m.environment = target.environment;
+        const direct = provider === "apns" || provider === "fcm";
+        const sealable = direct && !message.voip && hasVisibleContent(message);
+        if (mode !== "off" && sealable && target.publicKey) {
+            try {
+                const content = {};
+                for (const f of ["title", "subtitle", "body", "data"])
+                    if (message[f] !== undefined)
+                        content[f] = message[f];
+                m.sealed = await sealPushContent(target.publicKey, content, { now: now() });
+            }
+            catch (e) {
+                const msg = e.message;
+                tickets[i] = { token: to, status: "error", error: /over \d+/.test(msg) ? "MessageTooBig" : "RequestFailed", message: `cannot seal: ${msg}` };
+                return;
+            }
+        }
+        else if (mode === "required") {
+            const { data, ...withoutData } = message;
+            void data;
+            const base = hasVisibleContent(message) ? fallbackOnly(message, fallback) : withoutData;
+            m = { ...base, to, ...(m.environment ? { environment: m.environment } : {}) };
+        }
+        groups[provider].push({ i, m });
+    }));
+    const run = async (provider, send) => {
+        const g = groups[provider];
+        if (!g.length)
+            return;
+        if (!send) {
+            for (const { i, m } of g)
+                tickets[i] = { token: m.to, status: "error", error: "ProviderNotConfigured", message: `no ${provider} credentials configured` };
+            return;
+        }
+        const out = await send(g.map((x) => x.m));
+        g.forEach(({ i }, k) => (tickets[i] = out[k]));
+    };
+    await Promise.all([
+        run("expo", t.expo === false ? null : (ms) => sendExpoMessages(ms, t.expo || {})),
+        run("apns", t.apns ? (ms) => sendApns(ms, { ...t.apns, fallback: t.apns.fallback ?? fallback }) : null),
+        run("fcm", t.fcm ? (ms) => sendFcm(ms, { ...t.fcm, fallback: t.fcm.fallback ?? fallback }) : null),
+    ]);
+    const result = { tickets, unregisteredTokens: [], unregisteredVoipTokens: [], environments: [], expoTickets: [] };
+    const dead = new Set();
+    tickets.forEach((ticket, i) => {
+        const { target, provider } = list[i];
+        if (ticket.status === "ok") {
+            if (provider === "expo")
+                result.expoTickets.push(ticket);
+            if (ticket.environment && !message.voip)
+                result.environments.push({ token: target.token, environment: ticket.environment });
+            return;
+        }
+        if (ticket.error !== "DeviceNotRegistered" && ticket.error !== "InvalidToken")
+            return;
+        if (message.voip)
+            result.unregisteredVoipTokens.push({ userId: target.userId ?? "", voipToken: ticket.token });
+        else
+            dead.add(target.token);
+    });
+    result.unregisteredTokens = [...dead];
+    return result;
+}

package/dist/envelope.d.ts

@@ -0,0 +1,62 @@
+import { type HpkeRecipient } from "./hpke.ts";
+/**
+ * What is sealed for one device: everything a person would read. APNs and FCM only see the envelope (and the
+ * fallback text the sender chose, which should say nothing).
+ */
+export interface EncryptedPushContent {
+    title?: string;
+    subtitle?: string;
+    body?: string;
+    /** Delivered to the app after decryption (`notification.request.content.data` in expo-notifications). */
+    data?: Record<string, unknown>;
+}
+/** What opening an envelope gives: the content and when the server sealed it (Unix seconds). */
+export interface OpenedPushContent extends EncryptedPushContent {
+    iat: number;
+}
+/**
+ * The encrypted push as it travels, in the APNs payload's `ember` field or the FCM data's `ember` field (as a JSON
+ * string): HPKE's encapsulated key and ciphertext, base64url, and `k`, the id of the device key it was sealed to, so a
+ * device holding a rotated key tries the right one.
+ */
+export interface PushEnvelope {
+    v: typeof EMBER_PUSH_ENVELOPE_VERSION;
+    k: string;
+    enc: string;
+    ct: string;
+}
+export declare 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 declare 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 declare const PUSH_PLAINTEXT_MAX_BYTES = 2048;
+/** A key id: 8 base64url characters (`pushKeyId`). */
+export declare const PUSH_KEY_ID: RegExp;
+/**
+ * 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 declare function sealPushContent(devicePublicKey: string, content: EncryptedPushContent, opts?: {
+    now?: number;
+}): Promise<PushEnvelope>;
+/** Opens an envelope (what the device does; for tests and JS clients with WebCrypto). Throws if it does not open. */
+export declare function openPushEnvelope(recipient: HpkeRecipient, envelope: PushEnvelope): Promise<OpenedPushContent>;
+/** The plaintext of an envelope as a device accepts it; throws for anything else. */
+export declare function parseOpenedContent(value: unknown): OpenedPushContent;
+/**
+ * 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 declare function pushKeyId(publicKey: string | Uint8Array): Promise<string>;
+/** Accepts an envelope from untrusted JSON (or the JSON string FCM data carries), or returns null. */
+export declare function parsePushEnvelope(value: unknown): PushEnvelope | null;
+/** A device public key from its base64url form; throws unless it is an uncompressed P-256 point. */
+export declare function parseDevicePublicKey(value: string): Uint8Array<ArrayBuffer>;
+/** Cheap shape check for registration (the curve check happens when sealing). */
+export declare function isDevicePublicKey(value: unknown): value is string;

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

@@ -31,7 +31,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

@@ -13,15 +13,25 @@ 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, ...rest } = m;
     const out = {};
     for (const [k, val] of Object.entries(rest))
         if (val !== undefined)
             out[k] = val;
     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;