@freecorps/ember-expo-push 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeCorps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @freecorps/ember-expo-push
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The device side of Ember's **end-to-end encrypted pushes**. Notifications are sealed on your Ember Worker
+(`@freecorps/ember-push`, direct APNs/FCM transport) to a key that only the phone holds. Apple and Google carry
+ciphertext plus a fallback text that says nothing ("New mail"). Subject and sender never pass through them in
+clear.
+
+- **iOS:** a Notification Service Extension (added by this package's Expo config plugin) decrypts each push with
+  CryptoKit before it is shown.
+- **Android:** sealed pushes are FCM data-only messages. A background task decrypts them and posts a local
+  notification.
+- If something fails (no key yet, iOS 16, a push sealed to an old or foreign key), the fallback text is shown. The
+  device never stays silent.
+
+The cipher suite is HPKE (RFC 9180) base mode: DHKEM(P-256, HKDF-SHA256) + HKDF-SHA256 + AES-128-GCM. It was chosen
+by Freecorps Brigade's spike S1 and is ported from Brigade's MIT `packages/push`. JS decryption uses
+[noble](https://paulmillr.com/noble/), since React Native has no WebCrypto.
+
+## Setup
+
+```sh
+npx expo install expo-notifications expo-secure-store expo-constants expo-task-manager expo-crypto
+npm install @freecorps/ember-expo-push @freecorps/ember-react-native
+```
+
+```ts
+// app.config.ts
+plugins: [
+  "expo-secure-store",
+  "expo-notifications",
+  ["@freecorps/ember-expo-push", { /* appGroup, apsEnvironment, timeSensitive, deploymentTarget */ }],
+],
+ios: { bundleIdentifier: "com.acme.mail" },
+android: { package: "com.acme.mail", googleServicesFile: process.env.GOOGLE_SERVICES_JSON ?? "./google-services.json" },
+```
+
+```ts
+// index.ts: at module top level, before registerRootComponent (Android headless JS needs it)
+import { defineEmberPushTask } from "@freecorps/ember-expo-push";
+defineEmberPushTask();
+
+// after sign-in
+import { ensurePushKey, registerEmberPushTask } from "@freecorps/ember-expo-push";
+import { registerForPush } from "@freecorps/ember-react-native";
+
+const key = await ensurePushKey();                         // P-256, created once, kept in SecureStore
+const r = await registerForPush({ kind: "device", publicKey: key.publicKey, androidChannels: [{ id: "mail", name: "Mail" }] });
+if (r.status === "granted") {
+  await registerDevice({ token: r.token, platform: r.platform, environment: r.environment, publicKey: r.publicKey });
+  if (r.platform === "android") await registerEmberPushTask();
+}
+```
+
+`registerDevice` is your mutation calling `push.register(ctx, { userId, ...args })` (component) or
+`registerPushDevice`. On the server, enable the direct transport and encryption (see
+[`@freecorps/ember-push`](../push/README.md)): `pushComponent` with `encryption: "required"` for mail.
+
+## Config plugin options
+
+| Option | Default | What |
+|---|---|---|
+| `appGroup` | `group.<bundle id>.ember` | App Group shared by the app and the extension; also the keychain access group of the device key |
+| `apsEnvironment` | `development` locally, `production` when `EAS_BUILD` is set | The `aps-environment` entitlement; `EMBER_APS_ENVIRONMENT` overrides it too. Recorded in `extra.emberPush.apsEnvironment`, which `pushEnvironment()` in `@freecorps/ember-react-native` reads, so the token registers with the right APNs host |
+| `timeSensitive` | `true` | Adds `com.apple.developer.usernotifications.time-sensitive`, needed for `urgency: "high"` |
+| `deploymentTarget` | `16.4` | The extension's minimum iOS version. Decryption needs iOS 17 (CryptoKit HPKE); older devices show the fallback |
+| `keychainService`, `keyName` | `ember.push`, `ember.push.keys.v1` | Where the key lives (must match `ensurePushKey` options if you change them) |
+
+What it generates on iOS:
+- an `EmberNotificationService` app-extension target (bundle id `<bundle id>.EmberNotificationService`), embedded
+  in the app, built from `ios/EmberNotificationService/*.swift`;
+- the App Group on both targets;
+- `aps-environment`, plus the time-sensitive entitlement;
+- an `extra.eas.build.experimental.ios.appExtensions` entry, so EAS Build creates and signs the extension's
+  provisioning profile.
+
+Android needs nothing from the plugin.
+
+## API
+
+| Export | What |
+|---|---|
+| `ensurePushKey(opts?)` | `{ publicKey, keyId }`. Creates the key pair on first use and stores it with `AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY` (readable while locked, never synced or restored to another device), in the App Group's access group on iOS |
+| `rotatePushKey()`, `deletePushKeys()`, `loadPushKeys()` | Rotation keeps one previous key, so pushes sealed before the server learned the new key still open. Call delete at sign-out |
+| `defineEmberPushTask(opts?)`, `registerEmberPushTask()` | Android: define the task at top level and register it after sign-in |
+| `presentEncryptedPush(payload, opts?)` | What the task does: decrypt, then show the content on its `channelId`, replacing by `tag` (the collapse id), or else the fallback |
+| `openPushEnvelope(envelope, keys)`, `hpkeOpen`, `hpkeSeal`, `pushKeyId` | Pure-JS HPKE for any JS client |
+
+## Verifying the extension (done for this package, macOS + Xcode)
+
+- `test/swift.test.ts` compiles `EmberPushCrypto.swift` with CryptoKit on macOS. It opens envelopes the server sealed
+  (WebCrypto) with keys stored the way `ensurePushKey` stores them, including a rotated key. Foreign and tampered
+  envelopes are refused. The test also type-checks the whole extension against the iOS Simulator SDK. It is skipped
+  where there is no Swift toolchain.
+- `test/crypto.test.ts` checks the noble decoder against RFC 9180 vector A.3.1 and against the server's WebCrypto,
+  in both directions.
+- `test/plugin.test.ts` applies the plugin to a real Expo SDK 58 `project.pbxproj`.
+- By hand, on apps/example-expo with `EMBER_PUSH_DIRECT=1`: `npx expo prebuild --platform ios --no-install`, then
+  `xcodebuild -project ios/EmberChat.xcodeproj -target EmberNotificationService -sdk iphonesimulator
+  CODE_SIGNING_ALLOWED=NO build` gives `BUILD SUCCEEDED`. The app embeds the `.appex` in PlugIns, and running
+  prebuild again does not add the target twice.
+
+Still to do on a real device: see "Real-device testing" in [`@freecorps/ember-push`](../push/README.md).
+
+License: MIT.

package/app.plugin.cjs

@@ -0,0 +1,221 @@
+// @ts-check
+/**
+ * Expo config plugin for Ember's end-to-end encrypted pushes (`plugins: ["@freecorps/ember-expo-push"]` or
+ * `["@freecorps/ember-expo-push", { appGroup, apsEnvironment, timeSensitive, deploymentTarget }]`).
+ *
+ * iOS (written for Ember from Apple's and Expo's documentation; same arrangement Freecorps Brigade verified on a real
+ * iPhone in its spike S1):
+ * - an `EmberNotificationService` Notification Service Extension target (bundle id `<app>.EmberNotificationService`)
+ *   built from this package's `ios/EmberNotificationService/*.swift`, embedded in the app, iOS 16.4+ (decrypts on
+ *   iOS 17+, shows the fallback text below);
+ * - the App Group `group.<bundle id>.ember` on both targets: the device key is stored in its keychain access group so
+ *   the extension can read it (`ensurePushKey`);
+ * - `aps-environment`: `development` for local builds, `production` when `EAS_BUILD` is set (EAS builds are ad hoc or
+ *   App Store signed); `EMBER_APS_ENVIRONMENT` or the `apsEnvironment` option override it. Recorded in
+ *   `extra.emberPush.apsEnvironment` so the app registers its tokens with the right environment (`pushEnvironment()`
+ *   in @freecorps/ember-react-native);
+ * - `com.apple.developer.usernotifications.time-sensitive` (urgency `high`) unless `timeSensitive: false`;
+ * - the extension declared to EAS Build (`extra.eas.build.experimental.ios.appExtensions`) so EAS signs it.
+ *
+ * Android needs nothing from this plugin: sealed pushes are data-only FCM messages the app decrypts in a background
+ * task (`defineEmberPushTask`). Set `android.googleServicesFile` for FCM as usual.
+ */
+const fs = require("fs");
+const path = require("path");
+
+/** @returns {any} */
+function configPlugins() {
+  try {
+    return require("expo/config-plugins");
+  } catch {
+    return require("@expo/config-plugins");
+  }
+}
+
+const TARGET = "EmberNotificationService";
+const SWIFT_FILES = ["NotificationService.swift", "EmberPushCrypto.swift"];
+const DEFAULTS = { keychainService: "ember.push", keyName: "ember.push.keys.v1", deploymentTarget: "16.4", timeSensitive: true };
+
+/**
+ * @typedef {{ appGroup?: string; apsEnvironment?: "development" | "production"; timeSensitive?: boolean;
+ *   deploymentTarget?: string; keychainService?: string; keyName?: string; extensionBundleIdentifier?: string }} EmberPushPluginProps
+ */
+
+/** @param {EmberPushPluginProps} props @param {Record<string, string | undefined>} env */
+function resolveApsEnvironment(props = {}, env = process.env) {
+  const v = props.apsEnvironment ?? env.EMBER_APS_ENVIRONMENT ?? (env.EAS_BUILD ? "production" : "development");
+  if (v !== "development" && v !== "production") throw new Error(`@freecorps/ember-expo-push: apsEnvironment must be "development" or "production", got ${JSON.stringify(v)}`);
+  return v;
+}
+
+/** @param {any} config @param {EmberPushPluginProps} props @param {Record<string, string | undefined>} env */
+function emberPushSettings(config, props = {}, env = process.env) {
+  const bundleId = config.ios?.bundleIdentifier;
+  if (!bundleId) throw new Error("@freecorps/ember-expo-push: set ios.bundleIdentifier in the app config");
+  return {
+    bundleId,
+    appGroup: props.appGroup ?? `group.${bundleId}.ember`,
+    extensionBundleId: props.extensionBundleIdentifier ?? `${bundleId}.${TARGET}`,
+    apsEnvironment: resolveApsEnvironment(props, env),
+    keychainService: props.keychainService ?? DEFAULTS.keychainService,
+    keyName: props.keyName ?? DEFAULTS.keyName,
+    deploymentTarget: props.deploymentTarget ?? DEFAULTS.deploymentTarget,
+    timeSensitive: props.timeSensitive ?? DEFAULTS.timeSensitive,
+  };
+}
+
+/** @param {unknown} v @param {string} indent @returns {string} */
+function plistValue(v, indent) {
+  const esc = (/** @type {string} */ s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  if (Array.isArray(v)) return `<array>\n${v.map((x) => `${indent}\t${plistValue(x, indent + "\t")}`).join("\n")}\n${indent}</array>`;
+  if (typeof v === "boolean") return v ? "<true/>" : "<false/>";
+  if (v && typeof v === "object") {
+    const lines = Object.entries(v).map(([k, x]) => `${indent}\t<key>${esc(k)}</key>\n${indent}\t${plistValue(x, indent + "\t")}`);
+    return `<dict>\n${lines.join("\n")}\n${indent}</dict>`;
+  }
+  return `<string>${esc(String(v))}</string>`;
+}
+
+/** @param {Record<string, unknown>} dict */
+function plist(dict) {
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0">\n${plistValue(dict, "")}\n</plist>\n`;
+}
+
+/** The extension's Info.plist: NSExtension + where the device key is (read by NotificationService.swift). */
+function extensionInfoPlist(/** @type {ReturnType<typeof emberPushSettings>} */ s) {
+  return plist({
+    CFBundleDevelopmentRegion: "$(DEVELOPMENT_LANGUAGE)",
+    CFBundleDisplayName: TARGET,
+    CFBundleExecutable: "$(EXECUTABLE_NAME)",
+    CFBundleIdentifier: "$(PRODUCT_BUNDLE_IDENTIFIER)",
+    CFBundleInfoDictionaryVersion: "6.0",
+    CFBundleName: "$(PRODUCT_NAME)",
+    CFBundlePackageType: "$(PRODUCT_BUNDLE_PACKAGE_TYPE)",
+    CFBundleShortVersionString: "$(MARKETING_VERSION)",
+    CFBundleVersion: "$(CURRENT_PROJECT_VERSION)",
+    NSExtension: { NSExtensionPointIdentifier: "com.apple.usernotifications.service", NSExtensionPrincipalClass: "$(PRODUCT_MODULE_NAME).NotificationService" },
+    EmberPushAppGroup: s.appGroup,
+    EmberPushKeychainService: s.keychainService,
+    EmberPushKeyName: s.keyName,
+  });
+}
+
+function extensionEntitlements(/** @type {ReturnType<typeof emberPushSettings>} */ s) {
+  return plist({ "com.apple.security.application-groups": [s.appGroup] });
+}
+
+/** Adds the app's entitlements (pure: for tests). */
+function applyAppEntitlements(/** @type {Record<string, any>} */ ent, /** @type {ReturnType<typeof emberPushSettings>} */ s) {
+  ent["aps-environment"] = s.apsEnvironment;
+  const groups = new Set([...(ent["com.apple.security.application-groups"] ?? []), s.appGroup]);
+  ent["com.apple.security.application-groups"] = [...groups];
+  if (s.timeSensitive) ent["com.apple.developer.usernotifications.time-sensitive"] = true;
+  return ent;
+}
+
+/** Records the settings for the app (expo-constants) and declares the extension to EAS (pure: for tests). */
+function applyAppConfig(/** @type {any} */ config, /** @type {ReturnType<typeof emberPushSettings>} */ s) {
+  config.extra = config.extra ?? {};
+  config.extra.emberPush = { apsEnvironment: s.apsEnvironment, appGroup: s.appGroup, keychainService: s.keychainService, keyName: s.keyName };
+  const eas = (config.extra.eas = config.extra.eas ?? {});
+  const build = (eas.build = eas.build ?? {});
+  const exp = (build.experimental = build.experimental ?? {});
+  const ios = (exp.ios = exp.ios ?? {});
+  const list = (ios.appExtensions = (ios.appExtensions ?? []).filter((/** @type {any} */ e) => e.targetName !== TARGET));
+  list.push({ targetName: TARGET, bundleIdentifier: s.extensionBundleId, entitlements: { "com.apple.security.application-groups": [s.appGroup] } });
+  return config;
+}
+
+/**
+ * Adds the extension target to the Xcode project (idempotent): group with the sources, Info.plist and entitlements;
+ * an `app_extension` target embedded in the app (the xcode library adds the copy phase and the dependency); Sources,
+ * Resources and Frameworks phases; build settings.
+ */
+function addExtensionTarget(/** @type {any} */ project, /** @type {ReturnType<typeof emberPushSettings>} */ s, /** @type {any} */ config) {
+  // `addTarget` stores the name quoted until the project is written and parsed again: match both forms.
+  const targets = project.pbxNativeTargetSection();
+  if (Object.values(targets).some((/** @type {any} */ t) => typeof t === "object" && (t.name === TARGET || t.name === `"${TARGET}"`))) return project;
+  const objects = project.hash.project.objects;
+  objects.PBXTargetDependency = objects.PBXTargetDependency ?? {};
+  objects.PBXContainerItemProxy = objects.PBXContainerItemProxy ?? {};
+
+  const files = [...SWIFT_FILES, "Info.plist", `${TARGET}.entitlements`];
+  const group = project.addPbxGroup(files, TARGET, TARGET);
+  const mainGroup = project.getFirstProject().firstProject.mainGroup;
+  project.addToPbxGroup(group.uuid, mainGroup);
+
+  const target = project.addTarget(TARGET, "app_extension", TARGET, s.extensionBundleId);
+  project.addBuildPhase(SWIFT_FILES, "PBXSourcesBuildPhase", "Sources", target.uuid);
+  project.addBuildPhase([], "PBXResourcesBuildPhase", "Resources", target.uuid);
+  project.addBuildPhase([], "PBXFrameworksBuildPhase", "Frameworks", target.uuid);
+
+  const configs = project.pbxXCBuildConfigurationSection();
+  const listId = target.pbxNativeTarget.buildConfigurationList;
+  const list = project.pbxXCConfigurationList()[listId];
+  const ids = new Set((list?.buildConfigurations ?? []).map((/** @type {any} */ c) => c.value));
+  for (const id of ids) {
+    const bs = configs[id]?.buildSettings;
+    if (!bs) continue;
+    Object.assign(bs, {
+      INFOPLIST_FILE: `${TARGET}/Info.plist`,
+      CODE_SIGN_ENTITLEMENTS: `${TARGET}/${TARGET}.entitlements`,
+      CODE_SIGN_STYLE: "Automatic",
+      IPHONEOS_DEPLOYMENT_TARGET: s.deploymentTarget,
+      SWIFT_VERSION: "5.0",
+      TARGETED_DEVICE_FAMILY: '"1,2"',
+      MARKETING_VERSION: config.version ?? "1.0.0",
+      CURRENT_PROJECT_VERSION: config.ios?.buildNumber ?? "1",
+      PRODUCT_BUNDLE_IDENTIFIER: s.extensionBundleId,
+      GENERATE_INFOPLIST_FILE: "NO",
+      APPLICATION_EXTENSION_API_ONLY: "YES",
+      SKIP_INSTALL: "YES",
+    });
+    if (config.ios?.appleTeamId) bs.DEVELOPMENT_TEAM = config.ios.appleTeamId;
+  }
+  return project;
+}
+
+/** @param {any} config @param {EmberPushPluginProps} [props] */
+function withEmberPush(config, props = {}) {
+  const { withEntitlementsPlist, withDangerousMod, withXcodeProject } = configPlugins();
+  const s = emberPushSettings(config, props);
+  applyAppConfig(config, s);
+  config = withEntitlementsPlist(config, (/** @type {any} */ c) => {
+    applyAppEntitlements(c.modResults, s);
+    return c;
+  });
+  config = withDangerousMod(config, [
+    "ios",
+    async (/** @type {any} */ c) => {
+      const dir = path.join(c.modRequest.platformProjectRoot, TARGET);
+      fs.mkdirSync(dir, { recursive: true });
+      for (const f of SWIFT_FILES) fs.copyFileSync(path.join(__dirname, "ios", TARGET, f), path.join(dir, f));
+      fs.writeFileSync(path.join(dir, "Info.plist"), extensionInfoPlist(s));
+      fs.writeFileSync(path.join(dir, `${TARGET}.entitlements`), extensionEntitlements(s));
+      return c;
+    },
+  ]);
+  config = withXcodeProject(config, (/** @type {any} */ c) => {
+    addExtensionTarget(c.modResults, s, c);
+    return c;
+  });
+  return config;
+}
+
+const pkg = require("./package.json");
+let plugin = withEmberPush;
+try {
+  plugin = configPlugins().createRunOncePlugin(withEmberPush, pkg.name, pkg.version);
+} catch {
+  // Without expo installed (tests of the pure helpers), export the plain function.
+}
+module.exports = plugin;
+module.exports.withEmberPush = withEmberPush;
+module.exports.emberPushSettings = emberPushSettings;
+module.exports.resolveApsEnvironment = resolveApsEnvironment;
+module.exports.applyAppEntitlements = applyAppEntitlements;
+module.exports.applyAppConfig = applyAppConfig;
+module.exports.addExtensionTarget = addExtensionTarget;
+module.exports.extensionInfoPlist = extensionInfoPlist;
+module.exports.extensionEntitlements = extensionEntitlements;
+module.exports.EMBER_NSE_TARGET = TARGET;

package/dist/android.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Android: sealed pushes arrive as FCM data-only messages (`@freecorps/ember-push` `fcmMessage`): `{ ember: <envelope
+ * JSON>, fallbackTitle, fallbackBody, channelId?, tag?, urgency }`. Nothing is shown by the system for those;
+ * expo-notifications hands them to a background task (`Notifications.registerTaskAsync`), which runs in the foreground,
+ * in the background and with the app killed (headless JS). The task decrypts with the device key and posts a local
+ * notification with the content — or, when the push does not open, the fallback text: never silence.
+ *
+ *   // index.ts — at module top level, before registerRootComponent:
+ *   import { defineEmberPushTask } from "@freecorps/ember-expo-push";
+ *   defineEmberPushTask();
+ *   // after sign-in (once per launch is fine):
+ *   await registerEmberPushTask();
+ *
+ * iOS needs none of this: the Notification Service Extension decrypts before the notification is shown.
+ */
+import { type OpenedPush, type PushKeyPair } from "./crypto.ts";
+import { type PushKeyOptions } from "./keys.ts";
+import { type NotificationsLike, type TaskManagerLike } from "./modules.ts";
+export declare const EMBER_PUSH_TASK = "ember-push-decrypt";
+/** The sealed fields of a data message, wherever expo-notifications put them in the task payload. */
+export interface EncryptedPushData {
+    ember: string;
+    fallbackTitle?: string;
+    fallbackBody?: string;
+    channelId?: string;
+    tag?: string;
+    urgency?: string;
+}
+/**
+ * Finds the sealed fields in a background-task payload. expo-notifications passes `{ data: { ...fcmData } }`, with the
+ * data also as a JSON string in `data.dataString` on some versions; a `RemoteMessage`-like `{ data }` or the FCM data
+ * itself works too. Null when this is not an Ember sealed push.
+ */
+export declare function extractEncryptedPush(payload: unknown): EncryptedPushData | null;
+export interface PresentOptions extends PushKeyOptions {
+    notifications?: NotificationsLike | null;
+    /** Keys to open with (default: the stored device keys). */
+    keys?: readonly PushKeyPair[];
+    /** Change the content before it is shown (e.g. a per-app layout); return null to show nothing. */
+    transform?: (opened: OpenedPush, data: EncryptedPushData) => Record<string, unknown> | null;
+    /** Default fallback when the push carries none. */
+    fallback?: {
+        title: string;
+        body: string;
+    };
+}
+export type PresentResult = {
+    shown: "content" | "fallback";
+    identifier: string;
+    reason?: string;
+} | {
+    shown: "nothing";
+    reason: string;
+};
+/** Decrypts a sealed data push and posts it as a local notification (the content, or the fallback text). */
+export declare function presentEncryptedPush(payload: unknown, o?: PresentOptions): Promise<PresentResult>;
+export interface TaskOptions extends PresentOptions {
+    taskManager?: TaskManagerLike | null;
+    taskName?: string;
+    /** Default Platform.OS; the task does nothing on iOS (the NSE decrypts there). */
+    platform?: string;
+    onResult?: (r: PresentResult) => void;
+}
+/**
+ * Defines the background task that shows sealed pushes on Android. Call at module top level (headless JS needs the
+ * definition before the app renders). Returns the task name.
+ */
+export declare function defineEmberPushTask(o?: TaskOptions): string;
+/** Registers the task with expo-notifications so data-only pushes reach it. */
+export declare function registerEmberPushTask(o?: {
+    notifications?: NotificationsLike | null;
+    taskName?: string;
+}): Promise<void>;

package/dist/android.js

@@ -0,0 +1,120 @@
+/**
+ * Android: sealed pushes arrive as FCM data-only messages (`@freecorps/ember-push` `fcmMessage`): `{ ember: <envelope
+ * JSON>, fallbackTitle, fallbackBody, channelId?, tag?, urgency }`. Nothing is shown by the system for those;
+ * expo-notifications hands them to a background task (`Notifications.registerTaskAsync`), which runs in the foreground,
+ * in the background and with the app killed (headless JS). The task decrypts with the device key and posts a local
+ * notification with the content — or, when the push does not open, the fallback text: never silence.
+ *
+ *   // index.ts — at module top level, before registerRootComponent:
+ *   import { defineEmberPushTask } from "@freecorps/ember-expo-push";
+ *   defineEmberPushTask();
+ *   // after sign-in (once per launch is fine):
+ *   await registerEmberPushTask();
+ *
+ * iOS needs none of this: the Notification Service Extension decrypts before the notification is shown.
+ */
+import { openPushEnvelope, parsePushEnvelope } from "./crypto.js";
+import { loadPushKeys } from "./keys.js";
+import { loadNotifications, loadPlatformOS, loadTaskManager } from "./modules.js";
+export const EMBER_PUSH_TASK = "ember-push-decrypt";
+const isRecord = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
+/**
+ * Finds the sealed fields in a background-task payload. expo-notifications passes `{ data: { ...fcmData } }`, with the
+ * data also as a JSON string in `data.dataString` on some versions; a `RemoteMessage`-like `{ data }` or the FCM data
+ * itself works too. Null when this is not an Ember sealed push.
+ */
+export function extractEncryptedPush(payload) {
+    const candidates = [];
+    if (isRecord(payload)) {
+        candidates.push(payload);
+        const data = payload.data;
+        if (isRecord(data)) {
+            candidates.push(data);
+            if (typeof data.dataString === "string") {
+                try {
+                    candidates.push(JSON.parse(data.dataString));
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            if (isRecord(data.data))
+                candidates.push(data.data);
+        }
+        if (isRecord(payload.notification) && isRecord(payload.notification.data))
+            candidates.push(payload.notification.data);
+    }
+    for (const c of candidates) {
+        if (!isRecord(c) || typeof c.ember !== "string")
+            continue;
+        const out = { ember: c.ember };
+        for (const f of ["fallbackTitle", "fallbackBody", "channelId", "tag", "urgency"])
+            if (typeof c[f] === "string")
+                out[f] = c[f];
+        return out;
+    }
+    return null;
+}
+/** Decrypts a sealed data push and posts it as a local notification (the content, or the fallback text). */
+export async function presentEncryptedPush(payload, o = {}) {
+    const data = extractEncryptedPush(payload);
+    if (!data)
+        return { shown: "nothing", reason: "not an Ember sealed push" };
+    const N = o.notifications === undefined ? loadNotifications() : o.notifications;
+    if (!N)
+        return { shown: "nothing", reason: "expo-notifications is not installed" };
+    const trigger = data.channelId ? { channelId: data.channelId } : null;
+    const base = { ...(data.tag ? { identifier: data.tag } : {}), trigger };
+    let content;
+    let reason;
+    try {
+        const envelope = parsePushEnvelope(data.ember);
+        if (!envelope)
+            throw new Error("malformed envelope");
+        const keys = o.keys ?? (await loadPushKeys(o));
+        if (!keys.length)
+            throw new Error("no device key");
+        const opened = openPushEnvelope(envelope, keys);
+        content = o.transform ? o.transform(opened, data) : { title: opened.title, subtitle: opened.subtitle, body: opened.body, data: opened.data ?? {}, sound: "default" };
+        if (content === null)
+            return { shown: "nothing", reason: "transform returned null" };
+        for (const k of Object.keys(content))
+            if (content[k] === undefined)
+                delete content[k];
+        const identifier = await N.scheduleNotificationAsync({ ...base, content });
+        return { shown: "content", identifier };
+    }
+    catch (e) {
+        reason = e.message;
+    }
+    // Never silence: the fallback the server sent (or ours).
+    const fb = { title: data.fallbackTitle ?? o.fallback?.title ?? "New notification", body: data.fallbackBody ?? o.fallback?.body ?? "Open the app to see it." };
+    const identifier = await N.scheduleNotificationAsync({ ...base, content: { ...fb, data: {} } });
+    return { shown: "fallback", identifier, reason };
+}
+/**
+ * Defines the background task that shows sealed pushes on Android. Call at module top level (headless JS needs the
+ * definition before the app renders). Returns the task name.
+ */
+export function defineEmberPushTask(o = {}) {
+    const TM = o.taskManager === undefined ? loadTaskManager() : o.taskManager;
+    const name = o.taskName ?? EMBER_PUSH_TASK;
+    if (!TM)
+        throw new Error("@freecorps/ember-expo-push: expo-task-manager is required for the Android decrypt task");
+    TM.defineTask(name, async ({ data, error }) => {
+        if (error)
+            return;
+        if ((o.platform ?? loadPlatformOS()) === "ios")
+            return;
+        const r = await presentEncryptedPush(data, o);
+        o.onResult?.(r);
+    });
+    return name;
+}
+/** Registers the task with expo-notifications so data-only pushes reach it. */
+export async function registerEmberPushTask(o = {}) {
+    const N = o.notifications === undefined ? loadNotifications() : o.notifications;
+    if (!N?.registerTaskAsync)
+        throw new Error("@freecorps/ember-expo-push: expo-notifications registerTaskAsync is unavailable");
+    await N.registerTaskAsync(o.taskName ?? EMBER_PUSH_TASK);
+}

package/dist/crypto.d.ts

@@ -0,0 +1,50 @@
+/** Must equal `EMBER_PUSH_HPKE_INFO` in `@freecorps/ember-push` and the NSE's (test/crypto.test.ts checks). */
+export declare const EMBER_PUSH_HPKE_INFO = "freecorps.ember push v1";
+export declare const EMBER_PUSH_ENVELOPE_VERSION = 1;
+export declare function toBase64url(value: Uint8Array): string;
+export declare function fromBase64url(value: string): Uint8Array;
+/** HPKE single-shot open (base mode, sequence 0). Throws if anything does not match. */
+export declare function hpkeOpen(privateKey: Uint8Array, publicKey: Uint8Array, enc: Uint8Array, ct: Uint8Array, opts?: {
+    info?: Uint8Array;
+    aad?: Uint8Array;
+}): Uint8Array;
+/** HPKE single-shot seal (for tests and JS senders). `ephemeralKey` only for test vectors. */
+export declare function hpkeSeal(publicKey: Uint8Array, plaintext: Uint8Array, opts?: {
+    info?: Uint8Array;
+    aad?: Uint8Array;
+    ephemeralKey?: Uint8Array;
+    random?: (n: number) => Uint8Array;
+}): {
+    enc: Uint8Array;
+    ct: Uint8Array;
+};
+/** A device key pair: the raw private scalar (32 bytes) and the uncompressed public key (65 bytes). */
+export interface PushKeyPair {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}
+/** A new P-256 key pair from 48 random bytes (`random`: `crypto.getRandomValues`-backed on the device). */
+export declare function generatePushKeyPair(random: (n: number) => Uint8Array): PushKeyPair;
+/** The key id an envelope names (`k`): base64url of SHA-256(public key)'s first 6 bytes. Same as the server's. */
+export declare function pushKeyId(publicKey: Uint8Array): string;
+export interface PushEnvelope {
+    v: 1;
+    k: string;
+    enc: string;
+    ct: string;
+}
+/** What an envelope opens to. `iat`: when the server sealed it (Unix seconds). */
+export interface OpenedPush {
+    title?: string;
+    subtitle?: string;
+    body?: string;
+    data?: Record<string, unknown>;
+    iat: number;
+}
+/** An envelope from a push payload (object, or the JSON string FCM data carries), or null. */
+export declare function parsePushEnvelope(value: unknown): PushEnvelope | null;
+/**
+ * Opens an envelope with the device's keys (the one named by `k` first, then the others, e.g. right after a
+ * rotation). Throws when none opens it or the plaintext is not a push.
+ */
+export declare function openPushEnvelope(envelope: PushEnvelope, keys: readonly PushKeyPair[]): OpenedPush;

package/dist/crypto.js

@@ -0,0 +1,148 @@
+/**
+ * The device side of Ember's encrypted pushes, in pure JS (noble), because React Native has no WebCrypto: HPKE
+ * (RFC 9180) base mode with DHKEM(P-256, HKDF-SHA256) + HKDF-SHA256 + AES-128-GCM — the suite and `info` the server
+ * seals with (`@freecorps/ember-push`, ported from Freecorps Brigade's packages/push, MIT) and iOS CryptoKit opens in
+ * the Notification Service Extension. Checked against RFC 9180 test vector A.3.1 and against the server's WebCrypto
+ * implementation in both directions (test/crypto.test.ts).
+ */
+import { gcm } from "@noble/ciphers/aes.js";
+import { p256 } from "@noble/curves/nist.js";
+import { expand, extract } from "@noble/hashes/hkdf.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+/** Must equal `EMBER_PUSH_HPKE_INFO` in `@freecorps/ember-push` and the NSE's (test/crypto.test.ts checks). */
+export const EMBER_PUSH_HPKE_INFO = "freecorps.ember push v1";
+export const EMBER_PUSH_ENVELOPE_VERSION = 1;
+const te = new TextEncoder();
+export function toBase64url(value) {
+    let binary = "";
+    for (const byte of value)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function fromBase64url(value) {
+    if (!/^[A-Za-z0-9_-]*={0,2}$/.test(value))
+        throw new Error("invalid base64url");
+    const binary = atob(value.replace(/=+$/, "").replace(/-/g, "+").replace(/_/g, "/"));
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+const i2osp2 = (v) => Uint8Array.of((v >> 8) & 0xff, v & 0xff);
+const EMPTY = new Uint8Array(0);
+const KEM_SUITE = concat(te.encode("KEM"), i2osp2(0x0010));
+const HPKE_SUITE = concat(te.encode("HPKE"), i2osp2(0x0010), i2osp2(0x0001), i2osp2(0x0001));
+const labeledExtract = (suite, salt, label, ikm) => extract(sha256, concat(te.encode("HPKE-v1"), suite, te.encode(label), ikm), salt);
+const labeledExpand = (suite, prk, label, info, length) => expand(sha256, prk, concat(i2osp2(length), te.encode("HPKE-v1"), suite, te.encode(label), info), length);
+function checkPoint(raw) {
+    if (raw.length !== 65 || raw[0] !== 0x04)
+        throw new Error("expected an uncompressed P-256 public key (65 bytes)");
+    p256.Point.fromBytes(raw).assertValidity();
+}
+function keySchedule(dh, enc, pkR, info) {
+    const sharedSecret = labeledExpand(KEM_SUITE, labeledExtract(KEM_SUITE, EMPTY, "eae_prk", dh), "shared_secret", concat(enc, pkR), 32);
+    const context = concat(Uint8Array.of(0), labeledExtract(HPKE_SUITE, EMPTY, "psk_id_hash", EMPTY), labeledExtract(HPKE_SUITE, EMPTY, "info_hash", info));
+    const secret = labeledExtract(HPKE_SUITE, sharedSecret, "secret", EMPTY);
+    return { key: labeledExpand(HPKE_SUITE, secret, "key", context, 16), nonce: labeledExpand(HPKE_SUITE, secret, "base_nonce", context, 12) };
+}
+/** HPKE single-shot open (base mode, sequence 0). Throws if anything does not match. */
+export function hpkeOpen(privateKey, publicKey, enc, ct, opts = {}) {
+    checkPoint(enc);
+    const dh = p256.getSharedSecret(privateKey, enc, true).subarray(1);
+    const { key, nonce } = keySchedule(dh, enc, publicKey, opts.info ?? EMPTY);
+    return gcm(key, nonce, opts.aad ?? EMPTY).decrypt(ct);
+}
+/** HPKE single-shot seal (for tests and JS senders). `ephemeralKey` only for test vectors. */
+export function hpkeSeal(publicKey, plaintext, opts = {}) {
+    checkPoint(publicKey);
+    const skE = opts.ephemeralKey ?? p256.utils.randomSecretKey(opts.random ? opts.random(48) : undefined);
+    const enc = p256.getPublicKey(skE, false);
+    const dh = p256.getSharedSecret(skE, publicKey, true).subarray(1);
+    const { key, nonce } = keySchedule(dh, enc, publicKey, opts.info ?? EMPTY);
+    return { enc, ct: gcm(key, nonce, opts.aad ?? EMPTY).encrypt(plaintext) };
+}
+/** A new P-256 key pair from 48 random bytes (`random`: `crypto.getRandomValues`-backed on the device). */
+export function generatePushKeyPair(random) {
+    const privateKey = p256.utils.randomSecretKey(random(48));
+    return { privateKey, publicKey: p256.getPublicKey(privateKey, false) };
+}
+/** The key id an envelope names (`k`): base64url of SHA-256(public key)'s first 6 bytes. Same as the server's. */
+export function pushKeyId(publicKey) {
+    return toBase64url(sha256(publicKey).subarray(0, 6));
+}
+const isRecord = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
+/** An envelope from a push payload (object, or the JSON string FCM data carries), or 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" || !/^[A-Za-z0-9_-]{8}$/.test(k) || typeof enc !== "string" || typeof ct !== "string")
+        return null;
+    try {
+        if (fromBase64url(enc).length !== 65 || fromBase64url(ct).length < 16)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { v: 1, k, enc, ct };
+}
+/**
+ * Opens an envelope with the device's keys (the one named by `k` first, then the others, e.g. right after a
+ * rotation). Throws when none opens it or the plaintext is not a push.
+ */
+export function openPushEnvelope(envelope, keys) {
+    const info = te.encode(EMBER_PUSH_HPKE_INFO);
+    const enc = fromBase64url(envelope.enc);
+    const ct = fromBase64url(envelope.ct);
+    const ordered = [...keys].sort((a, b) => Number(pushKeyId(b.publicKey) === envelope.k) - Number(pushKeyId(a.publicKey) === envelope.k));
+    let last = new Error("no device key");
+    for (const key of ordered) {
+        let pt;
+        try {
+            pt = hpkeOpen(key.privateKey, key.publicKey, enc, ct, { info });
+        }
+        catch (e) {
+            last = e;
+            continue;
+        }
+        return parseOpened(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(pt)));
+    }
+    throw new Error(`push did not open: ${last.message}`);
+}
+function parseOpened(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;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@freecorps/ember-expo-push`: the device side of Ember's end-to-end encrypted pushes (server side:
+ * `@freecorps/ember-push` with the direct transport). Subject and sender never pass through Apple or Google in clear.
+ *
+ * - `app.plugin.cjs` (Expo config plugin `"@freecorps/ember-expo-push"`): iOS Notification Service Extension target that
+ *   decrypts with CryptoKit, App Group + keychain sharing, `aps-environment` per build, time-sensitive entitlement.
+ * - `ensurePushKey()`: the device key (P-256, SecureStore, shared with the NSE); register its `publicKey`.
+ * - `defineEmberPushTask()`: Android decrypt-and-show for data-only sealed pushes.
+ * - `openPushEnvelope()`: pure-JS HPKE (noble) for any JS client.
+ */
+export { EMBER_PUSH_ENVELOPE_VERSION, EMBER_PUSH_HPKE_INFO, fromBase64url, generatePushKeyPair, hpkeOpen, hpkeSeal, openPushEnvelope, parsePushEnvelope, pushKeyId, toBase64url, type OpenedPush, type PushEnvelope, type PushKeyPair, } from "./crypto.ts";
+export { DEFAULT_KEY_NAME, DEFAULT_KEYCHAIN_SERVICE, deletePushKeys, ensurePushKey, loadPushKeys, rotatePushKey, type DevicePushKey, type PushKeyOptions } from "./keys.ts";
+export { EMBER_PUSH_TASK, defineEmberPushTask, extractEncryptedPush, presentEncryptedPush, registerEmberPushTask, type EncryptedPushData, type PresentOptions, type PresentResult, type TaskOptions, } from "./android.ts";
+export type { ConstantsLike, EmberPushExtra, NotificationsLike, SecureStoreLike, TaskManagerLike } from "./modules.ts";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@freecorps/ember-expo-push`: the device side of Ember's end-to-end encrypted pushes (server side:
+ * `@freecorps/ember-push` with the direct transport). Subject and sender never pass through Apple or Google in clear.
+ *
+ * - `app.plugin.cjs` (Expo config plugin `"@freecorps/ember-expo-push"`): iOS Notification Service Extension target that
+ *   decrypts with CryptoKit, App Group + keychain sharing, `aps-environment` per build, time-sensitive entitlement.
+ * - `ensurePushKey()`: the device key (P-256, SecureStore, shared with the NSE); register its `publicKey`.
+ * - `defineEmberPushTask()`: Android decrypt-and-show for data-only sealed pushes.
+ * - `openPushEnvelope()`: pure-JS HPKE (noble) for any JS client.
+ */
+export { EMBER_PUSH_ENVELOPE_VERSION, EMBER_PUSH_HPKE_INFO, fromBase64url, generatePushKeyPair, hpkeOpen, hpkeSeal, openPushEnvelope, parsePushEnvelope, pushKeyId, toBase64url, } from "./crypto.js";
+export { DEFAULT_KEY_NAME, DEFAULT_KEYCHAIN_SERVICE, deletePushKeys, ensurePushKey, loadPushKeys, rotatePushKey } from "./keys.js";
+export { EMBER_PUSH_TASK, defineEmberPushTask, extractEncryptedPush, presentEncryptedPush, registerEmberPushTask, } from "./android.js";

package/dist/keys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The device key for sealed pushes. Created on first use, kept in SecureStore, and on iOS shared with the
+ * Notification Service Extension through the App Group, which doubles as a keychain access group (Brigade spike S1
+ * found the same arrangement works on a locked phone: `AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY`, never synced or restored
+ * to another device).
+ *
+ * The stored value is JSON, `{ "v": 1, "keys": [{ "d": <private scalar>, "pub": <public key> }, ...] }` (base64url),
+ * current key first; after `rotatePushKey` the previous key stays second so pushes sealed before the server learned
+ * the new key still open. The NSE (ios/EmberNotificationService/EmberPushCrypto.swift) reads the same item:
+ * expo-secure-store saves it as a generic password with service `<keychainService>:no-auth`, account `<keyName>` as UTF-8
+ * Data, and the App Group as access group.
+ */
+import { type PushKeyPair } from "./crypto.ts";
+import { type ConstantsLike, type SecureStoreLike } from "./modules.ts";
+export declare const DEFAULT_KEYCHAIN_SERVICE = "ember.push";
+export declare const DEFAULT_KEY_NAME = "ember.push.keys.v1";
+export interface PushKeyOptions {
+    secureStore?: SecureStoreLike | null;
+    /** iOS: the App Group (keychain access group) the NSE reads. Default: what the config plugin recorded. */
+    accessGroup?: string;
+    keychainService?: string;
+    keyName?: string;
+    /** Random bytes (default `crypto.getRandomValues` or expo-crypto). */
+    random?: (n: number) => Uint8Array;
+    constants?: ConstantsLike | null;
+    /** Default: Platform.OS. The access group only applies on iOS. */
+    platform?: string;
+}
+export interface DevicePushKey {
+    /** Register this with the device (`publicKey` of `registerForPush` / `push.register`). */
+    publicKey: string;
+    keyId: string;
+}
+/** The device's current public key, creating the key pair on first use. */
+export declare function ensurePushKey(o?: PushKeyOptions): Promise<DevicePushKey>;
+/** Every key this device can open with (current first). For the Android decrypt task and JS clients. */
+export declare function loadPushKeys(o?: PushKeyOptions): Promise<PushKeyPair[]>;
+/** A new current key; the previous one is kept (only one) until the next rotation. Register the returned key. */
+export declare function rotatePushKey(o?: PushKeyOptions): Promise<DevicePushKey>;
+/** Forgets every key (sign-out): pushes sealed to them show the fallback text from now on. */
+export declare function deletePushKeys(o?: PushKeyOptions): Promise<void>;

package/dist/keys.js

@@ -0,0 +1,76 @@
+/**
+ * The device key for sealed pushes. Created on first use, kept in SecureStore, and on iOS shared with the
+ * Notification Service Extension through the App Group, which doubles as a keychain access group (Brigade spike S1
+ * found the same arrangement works on a locked phone: `AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY`, never synced or restored
+ * to another device).
+ *
+ * The stored value is JSON, `{ "v": 1, "keys": [{ "d": <private scalar>, "pub": <public key> }, ...] }` (base64url),
+ * current key first; after `rotatePushKey` the previous key stays second so pushes sealed before the server learned
+ * the new key still open. The NSE (ios/EmberNotificationService/EmberPushCrypto.swift) reads the same item:
+ * expo-secure-store saves it as a generic password with service `<keychainService>:no-auth`, account `<keyName>` as UTF-8
+ * Data, and the App Group as access group.
+ */
+import { fromBase64url, generatePushKeyPair, pushKeyId, toBase64url } from "./crypto.js";
+import { defaultRandom, loadConstants, loadPlatformOS, loadSecureStore } from "./modules.js";
+export const DEFAULT_KEYCHAIN_SERVICE = "ember.push";
+export const DEFAULT_KEY_NAME = "ember.push.keys.v1";
+function resolve(o) {
+    const store = o.secureStore === undefined ? loadSecureStore() : o.secureStore;
+    if (!store)
+        throw new Error("@freecorps/ember-expo-push: expo-secure-store is required for the device key");
+    const extra = (o.constants === undefined ? loadConstants() : o.constants)?.expoConfig?.extra?.emberPush ?? {};
+    const platform = o.platform ?? loadPlatformOS() ?? "ios";
+    const options = { keychainService: o.keychainService ?? extra.keychainService ?? DEFAULT_KEYCHAIN_SERVICE };
+    if (store.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY !== undefined)
+        options.keychainAccessible = store.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY;
+    const group = o.accessGroup ?? extra.appGroup;
+    if (group && platform === "ios")
+        options.accessGroup = group;
+    return { store, key: o.keyName ?? extra.keyName ?? DEFAULT_KEY_NAME, options, random: o.random ?? defaultRandom };
+}
+async function read(r) {
+    const raw = await r.store.getItemAsync(r.key, r.options);
+    if (!raw)
+        return [];
+    try {
+        const s = JSON.parse(raw);
+        if (s?.v !== 1 || !Array.isArray(s.keys))
+            return [];
+        return s.keys.map((k) => ({ privateKey: fromBase64url(k.d), publicKey: fromBase64url(k.pub) })).filter((k) => k.privateKey.length === 32 && k.publicKey.length === 65);
+    }
+    catch {
+        return [];
+    }
+}
+async function write(r, keys) {
+    const s = { v: 1, keys: keys.map((k) => ({ d: toBase64url(k.privateKey), pub: toBase64url(k.publicKey) })) };
+    await r.store.setItemAsync(r.key, JSON.stringify(s), r.options);
+}
+const describe = (k) => ({ publicKey: toBase64url(k.publicKey), keyId: pushKeyId(k.publicKey) });
+/** The device's current public key, creating the key pair on first use. */
+export async function ensurePushKey(o = {}) {
+    const r = resolve(o);
+    const keys = await read(r);
+    if (keys[0])
+        return describe(keys[0]);
+    const created = generatePushKeyPair(r.random);
+    await write(r, [created]);
+    return describe(created);
+}
+/** Every key this device can open with (current first). For the Android decrypt task and JS clients. */
+export async function loadPushKeys(o = {}) {
+    return read(resolve(o));
+}
+/** A new current key; the previous one is kept (only one) until the next rotation. Register the returned key. */
+export async function rotatePushKey(o = {}) {
+    const r = resolve(o);
+    const keys = await read(r);
+    const created = generatePushKeyPair(r.random);
+    await write(r, [created, ...keys.slice(0, 1)]);
+    return describe(created);
+}
+/** Forgets every key (sign-out): pushes sealed to them show the fallback text from now on. */
+export async function deletePushKeys(o = {}) {
+    const r = resolve(o);
+    await r.store.deleteItemAsync(r.key, r.options);
+}

package/dist/modules.d.ts

@@ -0,0 +1,44 @@
+export interface SecureStoreLike {
+    getItemAsync(key: string, options?: Record<string, unknown>): Promise<string | null>;
+    setItemAsync(key: string, value: string, options?: Record<string, unknown>): Promise<void>;
+    deleteItemAsync(key: string, options?: Record<string, unknown>): Promise<void>;
+    AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY?: number;
+}
+export interface NotificationsLike {
+    scheduleNotificationAsync(request: {
+        identifier?: string;
+        content: Record<string, unknown>;
+        trigger: Record<string, unknown> | null;
+    }): Promise<string>;
+    registerTaskAsync?(taskName: string): Promise<null | void>;
+}
+export interface TaskManagerLike {
+    defineTask(name: string, task: (body: {
+        data: unknown;
+        error: unknown;
+        executionInfo?: unknown;
+    }) => Promise<unknown> | unknown): void;
+}
+export interface ConstantsLike {
+    expoConfig?: {
+        extra?: {
+            emberPush?: EmberPushExtra;
+        };
+    } | null;
+}
+/** What the config plugin records in `expo.extra.emberPush` (read at runtime through expo-constants). */
+export interface EmberPushExtra {
+    apsEnvironment?: "development" | "production";
+    /** iOS App Group shared by the app and the Notification Service Extension; also the keychain access group. */
+    appGroup?: string;
+    keychainService?: string;
+    keyName?: string;
+}
+export declare const pick: <T>(m: any, named?: string) => T | null;
+export declare function loadSecureStore(): SecureStoreLike | null;
+export declare function loadNotifications(): NotificationsLike | null;
+export declare function loadTaskManager(): TaskManagerLike | null;
+export declare function loadConstants(): ConstantsLike | null;
+export declare function loadPlatformOS(): string | undefined;
+/** Random bytes: `crypto.getRandomValues` when the runtime has it, else expo-crypto's. Throws without either. */
+export declare function defaultRandom(n: number): Uint8Array;

package/dist/modules.js

@@ -0,0 +1,62 @@
+export const pick = (m, named) => (m ? ((named ? m[named] : undefined) ?? m.default ?? m) : null);
+export function loadSecureStore() {
+    try {
+        const m = require("expo-secure-store");
+        return m && typeof m.getItemAsync === "function" ? m : pick(m);
+    }
+    catch {
+        return null;
+    }
+}
+export function loadNotifications() {
+    try {
+        const m = require("expo-notifications");
+        return m && typeof m.scheduleNotificationAsync === "function" ? m : pick(m);
+    }
+    catch {
+        return null;
+    }
+}
+export function loadTaskManager() {
+    try {
+        const m = require("expo-task-manager");
+        return m && typeof m.defineTask === "function" ? m : pick(m);
+    }
+    catch {
+        return null;
+    }
+}
+export function loadConstants() {
+    try {
+        return pick(require("expo-constants"));
+    }
+    catch {
+        return null;
+    }
+}
+export function loadPlatformOS() {
+    try {
+        return require("react-native")?.Platform?.OS;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Random bytes: `crypto.getRandomValues` when the runtime has it, else expo-crypto's. Throws without either. */
+export function defaultRandom(n) {
+    const out = new Uint8Array(n);
+    const c = globalThis.crypto;
+    if (c?.getRandomValues)
+        return c.getRandomValues(out);
+    try {
+        const m = require("expo-crypto");
+        if (typeof m.getRandomValues === "function")
+            return m.getRandomValues(out);
+        if (typeof m.getRandomBytes === "function")
+            return m.getRandomBytes(n);
+    }
+    catch {
+        /* fall through */
+    }
+    throw new Error("@freecorps/ember-expo-push: no secure random source (install expo-crypto)");
+}

package/ios/EmberNotificationService/EmberPushCrypto.swift

@@ -0,0 +1,149 @@
+// Ember end-to-end encrypted pushes, device side (iOS Notification Service Extension).
+//
+// Opens the `ember` envelope `{ v: 1, k, enc, ct }` that @freecorps/ember-push seals: HPKE (RFC 9180) base mode,
+// DHKEM(P-256, HKDF-SHA256) + HKDF-SHA256 + AES-128-GCM, info "freecorps.ember push v1" — CryptoKit's HPKE (iOS 17+).
+// The suite is the one Freecorps Brigade chose in its spike S1 (one CryptoKit call); this file is written for Ember.
+//
+// The device keys are the JSON the app stored with expo-secure-store (@freecorps/ember-expo-push `ensurePushKey`):
+// `{ "v": 1, "keys": [{ "d": <raw P-256 scalar>, "pub": <uncompressed public key> }] }`, base64url, in the keychain as a
+// generic password (service "<keychainService>:no-auth", account "<keyName>") in the App Group's access group.
+//
+// Pure Foundation + CryptoKit + Security, so it compiles and is tested on macOS too (test/swift).
+
+import CryptoKit
+import Foundation
+import Security
+
+public struct EmberPushContent {
+  public var title: String?
+  public var subtitle: String?
+  public var body: String?
+  public var data: [String: Any]?
+  public var iat: Int
+}
+
+public enum EmberPushError: Error, CustomStringConvertible {
+  case noEnvelope, malformedEnvelope, noKeys, unsupportedOS, notOpened, malformedContent
+
+  public var description: String {
+    switch self {
+    case .noEnvelope: return "noEnvelope"
+    case .malformedEnvelope: return "malformedEnvelope"
+    case .noKeys: return "noKeys"
+    case .unsupportedOS: return "unsupportedOS"
+    case .notOpened: return "notOpened"
+    case .malformedContent: return "malformedContent"
+    }
+  }
+}
+
+public struct EmberPushKey {
+  public let privateKey: Data  // 32-byte scalar
+  public let publicKey: Data  // 65-byte uncompressed point
+}
+
+public enum EmberPushCrypto {
+  public static let info = Data("freecorps.ember push v1".utf8)
+  public static let envelopeVersion = 1
+
+  public static func base64url(_ string: String) -> Data? {
+    var s = string.replacingOccurrences(of: "-", with: "+").replacingOccurrences(of: "_", with: "/")
+    while s.count % 4 != 0 { s += "=" }
+    return Data(base64Encoded: s)
+  }
+
+  public static func base64urlString(_ data: Data) -> String {
+    data.base64EncodedString().replacingOccurrences(of: "+", with: "-").replacingOccurrences(of: "/", with: "_")
+      .replacingOccurrences(of: "=", with: "")
+  }
+
+  /// The key id an envelope names: base64url of SHA-256(public key)'s first 6 bytes (same as the server's `pushKeyId`).
+  public static func keyId(_ publicKey: Data) -> String {
+    base64urlString(Data(SHA256.hash(data: publicKey).prefix(6)))
+  }
+
+  /// The stored key JSON → keys (current first). Malformed entries are skipped.
+  public static func parseKeys(_ json: Data) -> [EmberPushKey] {
+    guard let obj = try? JSONSerialization.jsonObject(with: json) as? [String: Any],
+      (obj["v"] as? Int) == 1, let list = obj["keys"] as? [[String: Any]]
+    else { return [] }
+    return list.compactMap { entry in
+      guard let d = (entry["d"] as? String).flatMap(base64url), let pub = (entry["pub"] as? String).flatMap(base64url),
+        d.count == 32, pub.count == 65
+      else { return nil }
+      return EmberPushKey(privateKey: d, publicKey: pub)
+    }
+  }
+
+  /// The envelope in a notification's userInfo (`ember`), as a dictionary or a JSON string.
+  public static func envelope(in userInfo: [AnyHashable: Any]) -> [String: Any]? {
+    if let e = userInfo["ember"] as? [String: Any] { return e }
+    if let s = userInfo["ember"] as? String, let d = s.data(using: .utf8) {
+      return (try? JSONSerialization.jsonObject(with: d)) as? [String: Any]
+    }
+    return nil
+  }
+
+  /// Opens an envelope with the device keys (the one named by `k` first). Throws `EmberPushError`.
+  public static func open(envelope: [String: Any], keys: [EmberPushKey]) throws -> EmberPushContent {
+    guard (envelope["v"] as? Int) == envelopeVersion, let k = envelope["k"] as? String,
+      let enc = (envelope["enc"] as? String).flatMap(base64url), let ct = (envelope["ct"] as? String).flatMap(base64url),
+      enc.count == 65, ct.count >= 16
+    else { throw EmberPushError.malformedEnvelope }
+    guard !keys.isEmpty else { throw EmberPushError.noKeys }
+    guard #available(iOS 17.0, macOS 14.0, *) else { throw EmberPushError.unsupportedOS }
+    let ordered = keys.filter { keyId($0.publicKey) == k } + keys.filter { keyId($0.publicKey) != k }
+    for key in ordered {
+      guard let plaintext = try? hpkeOpen(privateKey: key.privateKey, enc: enc, ct: ct) else { continue }
+      return try parseContent(plaintext)
+    }
+    throw EmberPushError.notOpened
+  }
+
+  @available(iOS 17.0, macOS 14.0, *)
+  static func hpkeOpen(privateKey: Data, enc: Data, ct: Data) throws -> Data {
+    let sk = try P256.KeyAgreement.PrivateKey(rawRepresentation: privateKey)
+    let suite = HPKE.Ciphersuite(kem: .P256_HKDF_SHA256, kdf: .HKDF_SHA256, aead: .AES_GCM_128)
+    var recipient = try HPKE.Recipient(privateKey: sk, ciphersuite: suite, info: info, encapsulatedKey: enc)
+    return try recipient.open(ct)
+  }
+
+  static func parseContent(_ plaintext: Data) throws -> EmberPushContent {
+    guard let obj = try? JSONSerialization.jsonObject(with: plaintext) as? [String: Any], let iat = obj["iat"] as? Int else {
+      throw EmberPushError.malformedContent
+    }
+    func str(_ k: String) throws -> String? {
+      guard let v = obj[k], !(v is NSNull) else { return nil }
+      guard let s = v as? String else { throw EmberPushError.malformedContent }
+      return s
+    }
+    var data: [String: Any]? = nil
+    if let d = obj["data"], !(d is NSNull) {
+      guard let dict = d as? [String: Any] else { throw EmberPushError.malformedContent }
+      data = dict
+    }
+    return EmberPushContent(title: try str("title"), subtitle: try str("subtitle"), body: try str("body"), data: data, iat: iat)
+  }
+
+  /// Reads the stored key JSON from the keychain (expo-secure-store's layout), or nil.
+  ///
+  /// The query mirrors expo-secure-store's (v57/v58 `SecureStoreModule.query`) byte for byte: generic password,
+  /// service `<keychainService>:no-auth` (then the legacy un-suffixed service), account `Data(key.utf8)` (Data, as
+  /// expo-secure-store writes it, not a String), and the App Group as access group. test/swift.test.ts checks it in
+  /// the iOS Simulator against an item written the way expo-secure-store writes it.
+  public static func readKeychain(service: String, account: String, accessGroup: String?) -> Data? {
+    for svc in ["\(service):no-auth", service] {
+      var query: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: svc,
+        kSecAttrAccount as String: Data(account.utf8),
+        kSecReturnData as String: true,
+        kSecMatchLimit as String: kSecMatchLimitOne,
+      ]
+      if let group = accessGroup, !group.isEmpty { query[kSecAttrAccessGroup as String] = group }
+      var out: CFTypeRef?
+      if SecItemCopyMatching(query as CFDictionary, &out) == errSecSuccess, let data = out as? Data { return data }
+    }
+    return nil
+  }
+}

package/ios/EmberNotificationService/NotificationService.swift

@@ -0,0 +1,53 @@
+// Ember Notification Service Extension (generated into the app by the @freecorps/ember-expo-push config plugin).
+//
+// For a push with `mutable-content: 1` and an `ember` envelope, replaces the fallback title/body APNs delivered with
+// the decrypted title, subtitle and body, and puts the decrypted `data` where expo-notifications reads it
+// (`userInfo["body"]`). When anything fails (no key yet, iOS 16, malformed or foreign envelope, out of time) the
+// fallback text stays: never an empty notification. Logs the failing step, never content.
+
+import UserNotifications
+import os
+
+final class NotificationService: UNNotificationServiceExtension {
+  private var contentHandler: ((UNNotificationContent) -> Void)?
+  private var bestAttempt: UNMutableNotificationContent?
+  private let log = Logger(subsystem: Bundle.main.bundleIdentifier ?? "EmberNotificationService", category: "push")
+
+  override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
+    self.contentHandler = contentHandler
+    guard let content = request.content.mutableCopy() as? UNMutableNotificationContent else {
+      contentHandler(request.content)
+      return
+    }
+    bestAttempt = content
+    guard let envelope = EmberPushCrypto.envelope(in: content.userInfo) else {
+      contentHandler(content)  // not an Ember sealed push
+      return
+    }
+    let info = Bundle.main.infoDictionary ?? [:]
+    let service = info["EmberPushKeychainService"] as? String ?? "ember.push"
+    let account = info["EmberPushKeyName"] as? String ?? "ember.push.keys.v1"
+    let group = info["EmberPushAppGroup"] as? String
+    do {
+      guard let stored = EmberPushCrypto.readKeychain(service: service, account: account, accessGroup: group) else {
+        throw EmberPushError.noKeys
+      }
+      let opened = try EmberPushCrypto.open(envelope: envelope, keys: EmberPushCrypto.parseKeys(stored))
+      if let t = opened.title { content.title = t }
+      if let s = opened.subtitle { content.subtitle = s }
+      if let b = opened.body { content.body = b }
+      var userInfo = content.userInfo
+      userInfo.removeValue(forKey: "ember")
+      if let data = opened.data { userInfo["body"] = data }
+      content.userInfo = userInfo
+      log.info("push decrypted")
+    } catch {
+      log.error("push not decrypted: \(String(describing: error), privacy: .public)")
+    }
+    contentHandler(content)
+  }
+
+  override func serviceExtensionTimeWillExpire() {
+    if let contentHandler, let bestAttempt { contentHandler(bestAttempt) }
+  }
+}

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@freecorps/ember-expo-push",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "End-to-end encrypted push for Ember Expo apps: device key, Notification Service Extension (iOS) config plugin, Android decrypt task, pure-JS HPKE.",
+  "keywords": [
+    "ember",
+    "expo",
+    "react-native",
+    "push",
+    "apns",
+    "fcm",
+    "hpke",
+    "e2ee",
+    "notification-service-extension"
+  ],
+  "homepage": "https://github.com/freecorps/ember/tree/main/packages/expo-push#readme",
+  "bugs": {
+    "url": "https://github.com/freecorps/ember/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freecorps/ember.git",
+    "directory": "packages/expo-push"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./app.plugin.cjs": "./app.plugin.cjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "app.plugin.cjs",
+    "ios"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.4.0",
+    "@noble/curves": "^2.4.0",
+    "@noble/hashes": "^2.4.0"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "expo-constants": "*",
+    "expo-crypto": "*",
+    "expo-notifications": "*",
+    "expo-secure-store": "*",
+    "expo-task-manager": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    },
+    "expo-constants": {
+      "optional": true
+    },
+    "expo-crypto": {
+      "optional": true
+    },
+    "expo-notifications": {
+      "optional": true
+    },
+    "expo-secure-store": {
+      "optional": true
+    },
+    "expo-task-manager": {
+      "optional": true
+    }
+  }
+}