@serfab/cadre-core 0.7.1 → 0.8.1

package/src/push-notifier-fcm.ts

@@ -0,0 +1,221 @@
+/**
+ * push-notifier-fcm.ts — FCM HTTP v1 strand-wake delivery.
+ *
+ * Server-only: mints a Google OAuth2 access token (RS256 JWT bearer grant signed
+ * with `node:crypto`) and POSTs a data message to the FCM v1 endpoint. The legacy
+ * server-key `fcm.googleapis.com/fcm/send` API is deprecated, so we use HTTP v1.
+ *
+ * The network call is behind an injected `fetch`-like seam so unit tests assert
+ * the request shape and map every documented response code with no real network
+ * and no credentials. Failures are returned as {@link PushSendResult} values.
+ *
+ * Secret hygiene: the service-account `privateKey`, the minted JWT, and full
+ * device tokens are never logged — failure log lines carry only a status/error
+ * code and a redacted token prefix.
+ */
+
+// Namespace import (not `import { sign }`): this module is server-only and is
+// reached only via the guarded dynamic import in CadreNode, but bundlers still
+// analyse that lazy chunk. A *named* import of `node:crypto` hard-fails the
+// browser build ("sign is not exported by __vite-browser-external"), whereas a
+// namespace import of the deliberately-unaliased external only warns (matching
+// the `node:http2` namespace import in push-notifier-apns.ts). The browser
+// never executes this code (config.push is node-only), so the warning is benign.
+import * as nodeCrypto from 'node:crypto';
+import debug from 'debug';
+import type { FcmCredentials } from './types.js';
+import type { PushMessage, PushNotifier, PushSendResult } from './push-notifier.js';
+import { MAX_REASON_LEN, b64urlJson, errText, redact } from './push-notifier-shared.js';
+
+const TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+const FCM_SCOPE = 'https://www.googleapis.com/auth/firebase.messaging';
+const JWT_BEARER_GRANT = 'urn:ietf:params:oauth:grant-type:jwt-bearer';
+/** Re-mint the access token this many ms before its stated expiry. */
+const TOKEN_REFRESH_SKEW_MS = 60_000;
+/** OAuth2 access tokens are short-lived (≤1h); assume 1h when unstated. */
+const DEFAULT_TOKEN_TTL_MS = 3_600_000;
+
+const debugFcm = debug('sereus:cadre:push:fcm');
+
+/** Minimal `fetch` Response shape the FCM sender consumes. */
+export interface FcmResponseLike {
+  status: number;
+  json(): Promise<unknown>;
+  text(): Promise<string>;
+}
+
+/** Injected `fetch`-like transport (default: global `fetch`). */
+export type FcmFetch = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body: string }
+) => Promise<FcmResponseLike>;
+
+export interface FcmPushDeps {
+  /** Network transport. Defaults to global `fetch`. */
+  fetch?: FcmFetch;
+  /** Monotonic clock (ms). Defaults to `Date.now`. Injected for cache tests. */
+  now?: () => number;
+  /** Failure log seam (default: `debug('sereus:cadre:push:fcm')`). */
+  log?: (line: string) => void;
+}
+
+/** A cached OAuth2 access token and the wall-clock ms after which to re-mint. */
+interface CachedAccessToken {
+  value: string;
+  expiresAt: number;
+}
+
+export function createFcmPushNotifier(creds: FcmCredentials, deps: FcmPushDeps = {}): PushNotifier {
+  const doFetch: FcmFetch = deps.fetch ?? ((url, init) => fetch(url, init));
+  const now = deps.now ?? (() => Date.now());
+  const log = deps.log ?? ((line: string) => debugFcm(line));
+  const sendUrl = `https://fcm.googleapis.com/v1/projects/${creds.projectId}/messages:send`;
+
+  let cached: CachedAccessToken | null = null;
+
+  async function send(msg: PushMessage): Promise<PushSendResult> {
+    let token: string;
+    try {
+      token = await accessToken(false);
+    } catch (err) {
+      log(`oauth mint failed: ${errText(err)}`);
+      return { ok: false, unregistered: false, error: `fcm oauth mint failed: ${errText(err)}` };
+    }
+
+    const first = await postSend(msg, token);
+    if (first.status !== 401) return mapResult(first, msg.token);
+
+    // The cached access token was rejected (expired/revoked mid-flight). Re-mint
+    // once and retry the single send; a second failure is returned as-is.
+    let retryToken: string;
+    try {
+      retryToken = await accessToken(true);
+    } catch (err) {
+      log(`oauth re-mint failed: ${errText(err)}`);
+      return { ok: false, unregistered: false, error: `fcm oauth re-mint failed: ${errText(err)}` };
+    }
+    return mapResult(await postSend(msg, retryToken), msg.token);
+  }
+
+  async function postSend(msg: PushMessage, token: string): Promise<{ status: number; body: string }> {
+    const body = JSON.stringify({
+      message: {
+        token: msg.token,
+        data: {
+          type: msg.payload.type,
+          strandId: msg.payload.strandId,
+          reason: msg.payload.reason.slice(0, MAX_REASON_LEN),
+        },
+        android: { priority: 'high' },
+      },
+    });
+    const res = await doFetch(sendUrl, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body,
+    });
+    return { status: res.status, body: await safeText(res) };
+  }
+
+  function mapResult(res: { status: number; body: string }, deviceToken: string): PushSendResult {
+    if (res.status === 200) return { ok: true };
+    const summary = errorSummary(res.status, res.body);
+    if (isUnregistered(res.status, res.body)) {
+      log(`unregistered token=${redact(deviceToken)} (${summary})`);
+      return { ok: false, unregistered: true, error: summary };
+    }
+    log(`send failed token=${redact(deviceToken)} (${summary})`);
+    return { ok: false, unregistered: false, error: summary };
+  }
+
+  async function accessToken(forceRefresh: boolean): Promise<string> {
+    if (!forceRefresh && cached && cached.expiresAt > now()) return cached.value;
+    cached = null;
+    const minted = await mintAccessToken();
+    cached = { value: minted.value, expiresAt: now() + minted.ttlMs - TOKEN_REFRESH_SKEW_MS };
+    return minted.value;
+  }
+
+  async function mintAccessToken(): Promise<{ value: string; ttlMs: number }> {
+    const jwt = signOauthJwt();
+    const res = await doFetch(TOKEN_ENDPOINT, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: `grant_type=${encodeURIComponent(JWT_BEARER_GRANT)}&assertion=${encodeURIComponent(jwt)}`,
+    });
+    if (res.status !== 200) {
+      throw new Error(`token endpoint ${res.status}: ${await safeText(res)}`);
+    }
+    const parsed = (await res.json()) as { access_token?: unknown; expires_in?: unknown };
+    if (typeof parsed.access_token !== 'string') {
+      throw new Error('token endpoint returned no access_token');
+    }
+    const ttlMs = typeof parsed.expires_in === 'number' ? parsed.expires_in * 1000 : DEFAULT_TOKEN_TTL_MS;
+    return { value: parsed.access_token, ttlMs };
+  }
+
+  function signOauthJwt(): string {
+    const iat = Math.floor(now() / 1000);
+    const header = { alg: 'RS256', typ: 'JWT' };
+    const claims = {
+      iss: creds.clientEmail,
+      sub: creds.clientEmail,
+      scope: FCM_SCOPE,
+      aud: TOKEN_ENDPOINT,
+      iat,
+      exp: iat + 3600,
+    };
+    const signingInput = `${b64urlJson(header)}.${b64urlJson(claims)}`;
+    const sig = nodeCrypto.sign('RSA-SHA256', Buffer.from(signingInput), creds.privateKey).toString('base64url');
+    return `${signingInput}.${sig}`;
+  }
+
+  async function close(): Promise<void> {
+    cached = null;
+  }
+
+  return { send, close };
+}
+
+/**
+ * Whether an FCM v1 error response names a permanently-invalid registration
+ * token: a 404 (`UNREGISTERED`), or a 400 `INVALID_ARGUMENT` whose message names
+ * the registration token. A generic 400 (malformed message) is NOT unregistered.
+ */
+function isUnregistered(status: number, body: string): boolean {
+  if (status === 404) return true;
+  if (status !== 400) return false;
+  const code = fcmErrorCode(body);
+  if (code === 'UNREGISTERED') return true;
+  if (code === 'INVALID_ARGUMENT' && /registration[ -]token|not a valid fcm registration/i.test(body)) return true;
+  return false;
+}
+
+/** Pull the FCM `errorCode` (FcmError detail) or RPC `status` out of the body. */
+function fcmErrorCode(body: string): string | null {
+  try {
+    const parsed = JSON.parse(body) as {
+      error?: { status?: string; details?: Array<{ errorCode?: string }> };
+    };
+    const err = parsed.error;
+    if (!err) return null;
+    const detailCode = err.details?.find((d) => typeof d.errorCode === 'string')?.errorCode;
+    return detailCode ?? err.status ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** A secret-free one-line error summary (status + error code, never the token). */
+function errorSummary(status: number, body: string): string {
+  const code = fcmErrorCode(body);
+  return code ? `fcm ${status} ${code}` : `fcm ${status}`;
+}
+
+async function safeText(res: FcmResponseLike): Promise<string> {
+  try {
+    return await res.text();
+  } catch {
+    return '';
+  }
+}

package/src/push-notifier-shared.ts

@@ -0,0 +1,28 @@
+/**
+ * push-notifier-shared.ts — internal helpers shared by the FCM and APNs
+ * push-notifier implementations. Server-only (used only by modules that already
+ * reach for `node:crypto` / `node:http2`); never re-exported from the package
+ * entry. Centralized so the secret-redaction and payload-bounding rules have a
+ * single, hardenable source rather than drifting between the two transports.
+ */
+
+/** Defensive cap on the free-form `reason` carried in a strand-wake payload. */
+export const MAX_REASON_LEN = 256;
+
+/** Base64url-encode the JSON form of an object (JWT header/claims segments). */
+export function b64urlJson(obj: unknown): string {
+  return Buffer.from(JSON.stringify(obj)).toString('base64url');
+}
+
+/** A short, secret-free string for an unknown thrown value. */
+export function errText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Redact a device token to a short, non-reversible prefix for debug lines — the
+ * full FCM/APNs token is a secret and must never reach a log.
+ */
+export function redact(token: string): string {
+  return token.length <= 8 ? '…' : `${token.slice(0, 6)}…`;
+}

package/src/push-notifier.ts

@@ -0,0 +1,93 @@
+/**
+ * push-notifier.ts — the platform-push **delivery** seam for strand-wake.
+ *
+ * Given a resolved mobile peer token, send one `strand-wake` data message over
+ * the right platform channel (FCM for Android, APNs for iOS). This module owns no
+ * policy — *who* to wake and *when* is the fan-out (`push-fanout.ts`). It is the
+ * reusable, credential-injected, transport-injected unit the fan-out constructs
+ * inside a participating `CadreNode` when push credentials are configured.
+ *
+ * `createPushNotifier` returns a router that dispatches by `msg.platform` to an
+ * `FcmPushNotifier` and/or `ApnsPushNotifier`, constructing only the
+ * implementations whose credentials are present. Failures are values, never
+ * thrown — mirroring `ServiceWakeResult` / `resolveDeviceToken`'s no-throw
+ * conventions so a best-effort fan-out can branch on the outcome.
+ *
+ * Server-only by construction: the FCM/APNs implementations reach for
+ * `node:crypto` / `node:http2`. They are never pulled into the RN/browser bundle
+ * because the cross-platform `index.ts` re-exports only the *types* here (a
+ * type-only re-export is erased at emit), and the only runtime constructor of a
+ * notifier is the in-package fan-out that runs inside a Node `CadreNode`. A
+ * cross-platform consumer imports the payload contract + types, never this value.
+ */
+
+import type { PushPlatform, PushCredentials } from './types.js';
+import type { StrandWakePayload } from './strand-wake-payload.js';
+import { createFcmPushNotifier, type FcmPushDeps } from './push-notifier-fcm.js';
+import { createApnsPushNotifier, type ApnsPushDeps } from './push-notifier-apns.js';
+
+/** One strand-wake data message addressed to one device. */
+export interface PushMessage {
+  /** The resolved `DeviceToken.token` for the target peer. */
+  token: string;
+  /** Which channel — selects FCM vs APNs. */
+  platform: PushPlatform;
+  /** The strand-wake payload `{ type:'strand-wake', strandId, reason }`. */
+  payload: StrandWakePayload;
+}
+
+/**
+ * Outcome of a single {@link PushNotifier.send}. A delivery failure is a value,
+ * never a thrown error. `unregistered: true` means the platform reported the
+ * token is permanently invalid (FCM 404 `UNREGISTERED` / 400 naming the token;
+ * APNs 410 `Unregistered` / 400 `BadDeviceToken`) — the caller should expire the
+ * stale `DeviceToken`. Any other failure is `unregistered: false` and is treated
+ * as best-effort/transient (no retry storm).
+ */
+export type PushSendResult =
+  | { ok: true }
+  | { ok: false; unregistered: boolean; error: string };
+
+export interface PushNotifier {
+  /** Send one strand-wake data message to one device. Never throws. */
+  send(msg: PushMessage): Promise<PushSendResult>;
+  /** Release transport resources (e.g. the APNs HTTP/2 session). */
+  close(): Promise<void>;
+}
+
+/**
+ * Per-platform transport/clock/log seams, injected by tests. Defaults are the
+ * real implementations (global `fetch` for FCM, a `node:http2` session for APNs).
+ */
+export interface PushNotifierDeps {
+  fcm?: FcmPushDeps;
+  apns?: ApnsPushDeps;
+}
+
+/**
+ * Build a {@link PushNotifier} router over the configured credentials. Only the
+ * platforms whose credentials are present get a backing implementation; a `send`
+ * for an unconfigured platform returns a best-effort `no <platform> credentials`
+ * failure rather than throwing.
+ */
+export function createPushNotifier(creds: PushCredentials, deps: PushNotifierDeps = {}): PushNotifier {
+  const fcm = creds.fcm ? createFcmPushNotifier(creds.fcm, deps.fcm) : undefined;
+  const apns = creds.apns ? createApnsPushNotifier(creds.apns, deps.apns) : undefined;
+
+  async function send(msg: PushMessage): Promise<PushSendResult> {
+    if (msg.platform === 'fcm') return fcm ? fcm.send(msg) : noCreds('fcm');
+    if (msg.platform === 'apns') return apns ? apns.send(msg) : noCreds('apns');
+    return { ok: false, unregistered: false, error: `unknown platform ${String(msg.platform)}` };
+  }
+
+  async function close(): Promise<void> {
+    await Promise.all([fcm?.close(), apns?.close()]);
+  }
+
+  return { send, close };
+}
+
+/** Best-effort no-op result for a platform with no configured credentials. */
+function noCreds(platform: PushPlatform): PushSendResult {
+  return { ok: false, unregistered: false, error: `no ${platform} credentials` };
+}

package/src/schema-verification.ts

@@ -24,7 +24,7 @@ export class SchemaVerificationError extends Error {
  */
 function schemaDigest(schema: string, version: string): string {
   const payload = JSON.stringify({ schema, version });
-  return digest(payload, 'sha256', 'utf8', 'base64url') as string;
+  return digest([payload], 'sha256', 'base64url') as string;
 }
 
 /**
@@ -64,14 +64,28 @@ export function verifySchema(schema: string, version: string, signature: string,
  * Assert that an SAppConfig has a valid schema signature.
  * Throws SchemaVerificationError on failure.
  *
+ * Fail-closed by default: when `options.requireSignature` is not explicitly
+ * `false`, an absent signature is rejected with reason `'missing signature'`,
+ * distinct from the `'invalid signature'` (tampered/wrong-key) case. The
+ * relaxation (`requireSignature: false`) only excuses *absence* of a signature;
+ * a present-but-bad signature still throws.
+ *
  * @param sAppConfig - The sApp configuration to verify
- * @throws SchemaVerificationError if the signature is invalid
+ * @param options - Verification policy; `requireSignature` defaults to `true`
+ * @throws SchemaVerificationError if the signature is missing (when required) or invalid
  */
-export function assertSchemaSignature(sAppConfig: SAppConfig): void {
+export function assertSchemaSignature(
+  sAppConfig: SAppConfig,
+  options?: { requireSignature?: boolean }
+): void {
   const { id, version, schema, signature } = sAppConfig;
+  const requireSignature = options?.requireSignature ?? true;
 
   if (!signature) {
-    log('No signature provided for %s v%s — skipping verification', id, version);
+    if (requireSignature) {
+      throw new SchemaVerificationError(id ?? '', version, 'missing signature');
+    }
+    log('No signature provided for %s v%s — skipping verification (policy relaxed)', id, version);
     return;
   }