@openchambery/relay-server 1.19.0-beta.35 → 1.19.0-beta.37

package/bin/openchamber-push-relay.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import packageJson from '../package.json' with { type: 'json' };
+
+import { isModuleCliExecution } from './cli-entry.js';
+import { runPushRelayCli } from '../src/push/cli.js';
+
+const version = packageJson.version;
+
+if (isModuleCliExecution(process.argv[1], import.meta.url, undefined, 'openchamber-push-relay')) {
+  runPushRelayCli(process.argv.slice(2), { version }).then((code) => { process.exitCode = code; });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openchambery/relay-server",
-  "version": "1.19.0-beta.35",
+  "version": "1.19.0-beta.37",
   "description": "Self-hosted private relay server for OpenChamber",
   "private": false,
   "type": "module",
@@ -11,16 +11,22 @@
       "types": "./src/index.d.ts",
       "import": "./src/index.js",
       "default": "./src/index.js"
+    },
+    "./push": {
+      "types": "./src/push/index.d.ts",
+      "import": "./src/push/index.js",
+      "default": "./src/push/index.js"
     }
   },
   "bin": {
-    "openchamber-relay": "./bin/openchamber-relay.js"
+    "openchamber-relay": "./bin/openchamber-relay.js",
+    "openchamber-push-relay": "./bin/openchamber-push-relay.js"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.13.0"
   },
   "license": "MIT",
   "repository": {
@@ -40,8 +46,8 @@
   "scripts": {
     "test": "vitest run",
     "test:node": "node test/node-smoke.js",
-    "type-check": "node --check src/index.js && node --check src/cli.js && node --check bin/openchamber-relay.js && node --check bin/cli-entry.js",
-    "lint": "node --check src/index.js && node --check src/cli.js && node --check bin/openchamber-relay.js && node --check bin/cli-entry.js",
+    "type-check": "node --check src/index.js && node --check src/cli.js && node --check bin/openchamber-relay.js && node --check bin/cli-entry.js && node --check src/push/index.js && node --check src/push/server.js && node --check src/push/cli.js && node --check src/push/config.js && node --check src/push/schema.js && node --check src/push/crypto.js && node --check src/push/store.js && node --check src/push/guard.js && node --check src/push/apns.js && node --check bin/openchamber-push-relay.js",
+    "lint": "node --check src/index.js && node --check src/cli.js && node --check bin/openchamber-relay.js && node --check bin/cli-entry.js && node --check src/push/index.js && node --check src/push/server.js && node --check src/push/cli.js && node --check src/push/config.js && node --check src/push/schema.js && node --check src/push/crypto.js && node --check src/push/store.js && node --check src/push/guard.js && node --check src/push/apns.js && node --check bin/openchamber-push-relay.js",
     "build:standalone": "bun build --compile --outfile dist/openchamber-relay bin/openchamber-relay.js"
   },
   "dependencies": {

package/src/push/apns.js

@@ -0,0 +1,120 @@
+import crypto from 'node:crypto';
+import http2 from 'node:http2';
+
+const APNS_HOST = {
+  production: 'https://api.push.apple.com',
+  sandbox: 'https://api.sandbox.push.apple.com',
+};
+const JWT_TTL_MS = 50 * 60 * 1000;
+const REQUEST_TIMEOUT_MS = 5_000;
+const MAX_RESPONSE_BYTES = 4_096;
+export const DEAD_TOKEN_REASONS = new Set(['BadDeviceToken', 'Unregistered', 'DeviceTokenNotForTopic']);
+
+const normalizePem = (value) => (typeof value === 'string' ? value.replace(/\\n/g, '\n').trim() : '');
+
+export const createApnsProvider = (options = {}) => {
+  const clock = { now: Date.now, setTimeout, clearTimeout, ...options.clock };
+  const connect = options.http2?.connect ?? http2.connect;
+  let privateKey;
+  try {
+    privateKey = crypto.createPrivateKey(normalizePem(options.p8));
+  } catch {
+    throw new Error('Invalid APNs key');
+  }
+  const bundleId = options.bundleId;
+  const sessions = new Map();
+  let cachedJwt = null;
+
+  const signJwt = () => {
+    const header = Buffer.from(JSON.stringify({ alg: 'ES256', kid: options.keyId })).toString('base64url');
+    const claims = Buffer.from(JSON.stringify({ iss: options.teamId, iat: Math.floor(clock.now() / 1000) })).toString('base64url');
+    const signingInput = `${header}.${claims}`;
+    const signature = crypto.sign('sha256', Buffer.from(signingInput), { key: privateKey, dsaEncoding: 'ieee-p1363' }).toString('base64url');
+    return `${signingInput}.${signature}`;
+  };
+
+  const getJwt = (force) => {
+    const now = clock.now();
+    if (!force && cachedJwt && now - cachedJwt.issuedAtMs < JWT_TTL_MS) return cachedJwt.token;
+    cachedJwt = { token: signJwt(), issuedAtMs: now };
+    return cachedJwt.token;
+  };
+
+  const dropSession = (env, client) => {
+    if (sessions.get(env) === client) sessions.delete(env);
+    try { client.close(); } catch { /* session already gone */ }
+  };
+
+  const getSession = (env) => {
+    const existing = sessions.get(env);
+    if (existing && !existing.closed && existing.destroyed !== true) return existing;
+    const client = connect(APNS_HOST[env]);
+    client.on('error', () => dropSession(env, client));
+    client.on('close', () => { if (sessions.get(env) === client) sessions.delete(env); });
+    sessions.set(env, client);
+    return client;
+  };
+
+  const dispatch = (input, forceJwt) => new Promise((resolve) => {
+    const jwt = getJwt(forceJwt);
+    let client;
+    try { client = getSession(input.env); } catch { resolve({ ok: false }); return; }
+    const headers = {
+      ':method': 'POST',
+      ':path': `/3/device/${input.token}`,
+      authorization: `bearer ${jwt}`,
+      'apns-topic': bundleId,
+      'apns-push-type': 'alert',
+      'apns-priority': '10',
+    };
+    if (input.collapseId) headers['apns-collapse-id'] = input.collapseId;
+    let req;
+    try { req = client.request(headers); } catch { resolve({ ok: false }); return; }
+    let status = 0;
+    let responseBody = '';
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clock.clearTimeout(timer);
+      resolve(result);
+    };
+    const timer = clock.setTimeout(() => {
+      try { req.close(); } catch { /* ignore */ }
+      finish({ ok: false });
+    }, options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS);
+    req.on('response', (responseHeaders) => { status = Number(responseHeaders[':status']) || 0; });
+    req.setEncoding('utf8');
+    req.on('data', (chunk) => {
+      if (responseBody.length < MAX_RESPONSE_BYTES) responseBody += chunk.slice(0, MAX_RESPONSE_BYTES - responseBody.length);
+    });
+    req.on('end', () => {
+      if (status === 200) { finish({ ok: true }); return; }
+      let reason = '';
+      try { reason = JSON.parse(responseBody)?.reason || ''; } catch { /* non-JSON */ }
+      if (reason === 'ExpiredProviderToken') { finish({ ok: false, expired: true }); return; }
+      if (status === 410 || DEAD_TOKEN_REASONS.has(reason)) { finish({ ok: false, drop: true }); return; }
+      finish({ ok: false });
+    });
+    req.on('error', () => finish({ ok: false }));
+    req.end(JSON.stringify(input.payload));
+  });
+
+  return {
+    async send(input) {
+      const first = await dispatch(input, false);
+      if (first.expired) {
+        const retry = await dispatch(input, true);
+        return { ok: retry.ok === true, drop: retry.drop === true ? true : undefined };
+      }
+      return { ok: first.ok === true, drop: first.drop === true ? true : undefined };
+    },
+    close() {
+      for (const [env, client] of sessions) {
+        sessions.delete(env);
+        try { client.close(); } catch { /* ignore */ }
+      }
+      cachedJwt = null;
+    },
+  };
+};

package/src/push/cli.js

@@ -0,0 +1,73 @@
+import { startPushRelayServer } from './server.js';
+import { buildPushRelayConfig, fail, formatPushRelayUrl } from './config.js';
+
+export { buildPushRelayConfig } from './config.js';
+
+export const parsePushRelayArgs = (argv = []) => {
+  const parsed = {};
+  const values = new Map([['--host', 'host'], ['--port', 'port']]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (values.has(arg)) {
+      const value = argv[++index];
+      if (!value || value.startsWith('--')) fail(arg);
+      parsed[values.get(arg)] = value;
+      continue;
+    }
+    if (arg === '--trust-proxy') { parsed.trustProxy = true; continue; }
+    if (arg === '--no-trust-proxy') { parsed.trustProxy = false; continue; }
+    if (arg === '--json') { parsed.json = true; continue; }
+    if (arg === '--quiet' || arg === '-q') { parsed.quiet = true; continue; }
+    if (arg === '--help' || arg === '-h') { parsed.help = true; continue; }
+    if (arg === '--version' || arg === '-v') { parsed.version = true; continue; }
+    fail(arg);
+  }
+  return parsed;
+};
+
+const helpText = 'Usage: openchamber-push-relay [--host HOST] [--port PORT] [--trust-proxy] [--json] [--quiet]\nEnable --trust-proxy only when public ingress reaches this relay through a trusted reverse proxy.\n';
+const writeJson = (stdout, payload) => stdout.write(`${JSON.stringify(payload)}\n`);
+
+export const runPushRelayCli = async (argv, dependencies = {}) => {
+  const processLike = dependencies.process ?? process;
+  const stdout = dependencies.stdout ?? process.stdout;
+  const stderr = dependencies.stderr ?? process.stderr;
+  const version = dependencies.version ?? '0.0.0';
+  let parsed;
+  try { parsed = parsePushRelayArgs(argv ?? processLike.argv?.slice(2) ?? []); } catch (error) {
+    const json = (argv ?? processLike.argv?.slice(2) ?? []).includes('--json');
+    if (json) writeJson(stdout, { status: 'error', error: error.message }); else stderr.write(`${error.message}\n`);
+    processLike.exitCode = 1; return 1;
+  }
+  const json = parsed.json;
+  const respond = (payload, error = false, essential = false) => {
+    if (json) writeJson(stdout, payload);
+    else if (payload.message && (essential || !parsed.quiet || error)) (error ? stderr : stdout).write(`${payload.message}\n`);
+  };
+  if (parsed.help) { respond(json ? { status: 'ok', help: helpText.trim() } : { message: helpText.trim() }, false, true); return 0; }
+  if (parsed.version) { respond(json ? { status: 'ok', version } : { message: version }, false, true); return 0; }
+  let config;
+  try { config = buildPushRelayConfig(parsed, processLike.env ?? {}); } catch (error) { respond({ status: 'error', error: error.message, message: error.message }, true); processLike.exitCode = 1; return 1; }
+  try {
+    const relay = await (dependencies.start ?? startPushRelayServer)(config);
+    const port = relay.address?.()?.port ?? config.port;
+    const url = formatPushRelayUrl(config.host, port);
+    respond(json ? { status: 'ok', url, host: config.host, port } : { message: `Push relay listening at ${url}` });
+    let stopping = false;
+    const stop = async () => {
+      if (stopping) return Promise.resolve();
+      stopping = true;
+      processLike.off?.('SIGINT', stop); processLike.off?.('SIGTERM', stop);
+      try {
+        await relay.stop();
+        processLike.exit?.(0);
+      } catch {
+        processLike.exitCode = 1;
+        if (json) writeJson(stderr, { status: 'error', error: 'Push relay stop failed' }); else stderr.write('Push relay stop failed\n');
+        processLike.exit?.(1);
+      }
+    };
+    processLike.on?.('SIGINT', stop); processLike.on?.('SIGTERM', stop);
+    return 0;
+  } catch (error) { respond({ status: 'error', error: error.message, message: error.message }, true); processLike.exitCode = 1; return 1; }
+};

package/src/push/config.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import { isIP } from 'node:net';
+
+export const DEFAULT_HOST = '127.0.0.1';
+export const DEFAULT_PORT = 8788;
+export const DEFAULT_DATABASE_PATH = './data/push-relay.sqlite';
+export const DEFAULT_BUNDLE_ID = 'com.openchamber.app';
+export const ENV_PREFIX = 'OPENCHAMBER_PUSH_RELAY_';
+export const DEFAULT_LIMITS = {
+  timestampSkewMs: 300_000,
+  replayMs: 600_000,
+  maxReplayEntries: 10_000,
+  registerLimitPerMinute: 60,
+  sendLimitPerMinute: 60,
+  serverSendLimitPerMinute: 120,
+  maxTokens: 100_000,
+  maxInFlight: 64,
+  maxRateLimitEntries: 10_000,
+  jsonBodyBytes: 16 * 1024,
+};
+
+const LIMIT_KEYS = ['timestampSkewMs', 'replayMs', 'maxReplayEntries', 'registerLimitPerMinute', 'sendLimitPerMinute', 'serverSendLimitPerMinute', 'maxTokens', 'maxInFlight'];
+
+export const resolvePushRelayClientIp = (request, trustProxy = false) => {
+  const remoteAddress = request.socket.remoteAddress ?? 'unknown';
+  if (!trustProxy) return remoteAddress;
+  const forwarded = request.headers['x-forwarded-for'];
+  const candidate = typeof forwarded === 'string' && !forwarded.includes(',') ? forwarded.trim() : '';
+  return isIP(candidate) ? candidate : remoteAddress;
+};
+
+export const formatPushRelayUrl = (host, port) => `http://${isIP(host) === 6 ? `[${host}]` : host}:${port}`;
+
+const upperSnake = (key) => key.replace(/[A-Z]/g, (letter) => `_${letter}`).toUpperCase();
+export const envName = (key) => `${ENV_PREFIX}${upperSnake(key)}`;
+export const fail = (name) => { throw new Error(`Invalid ${name}`); };
+
+export const positive = (name, value) => {
+  if (!/^[1-9][0-9]*$/.test(String(value))) fail(name);
+  const number = Number(value);
+  if (!Number.isSafeInteger(number)) fail(name);
+  return number;
+};
+
+export const bool = (name, value) => {
+  if (value === undefined) return false;
+  if (value === 'true' || value === '1' || value === true) return true;
+  if (value === 'false' || value === '0' || value === false) return false;
+  fail(name);
+};
+
+export const validHost = (name, value) => {
+  if (typeof value !== 'string' || value.trim() !== value || value.length === 0 || value.includes('/') || value.includes('\\') || value.includes('@') || value.includes(':') && !isIP(value) || (!isIP(value) && !/^(?=.{1,253}$)(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)(?:\.(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?))*$/.test(value))) fail(name);
+  return value;
+};
+
+export const validDatabasePath = (name, value) => {
+  if (typeof value !== 'string' || value.trim() !== value || value.length === 0 || value.includes('\0')) fail(name);
+  return value;
+};
+
+export const normalizePem = (value) => (typeof value === 'string' ? value.replace(/\\n/g, '\n').trim() : '');
+
+export const validatePushRelayLimits = (limits) => {
+  if (limits.replayMs < limits.timestampSkewMs * 2 || limits.maxReplayEntries < 1) throw new RangeError('invalid replay limits');
+  if (limits.maxTokens < 1 || limits.maxInFlight < 1 || limits.registerLimitPerMinute < 1 || limits.sendLimitPerMinute < 1 || limits.serverSendLimitPerMinute < 1) {
+    throw new RangeError('invalid push limits');
+  }
+  return limits;
+};
+
+export const normalizePushRelayOptions = (options = {}) => {
+  const limits = validatePushRelayLimits({ ...DEFAULT_LIMITS, ...options.limits });
+  const host = options.host ?? DEFAULT_HOST;
+  validHost('host', host);
+  const port = options.port ?? DEFAULT_PORT;
+  if (!Number.isSafeInteger(port) || port < 0 || port > 65535) fail('port');
+  const databasePath = options.databasePath ?? DEFAULT_DATABASE_PATH;
+  validDatabasePath('databasePath', databasePath);
+  if (!options.apnsProvider) {
+    const apns = options.apns ?? {};
+    if (!apns.keyId || !apns.teamId || !apns.p8 || !apns.bundleId) throw new Error('Invalid APNs configuration');
+  }
+  return {
+    host,
+    port,
+    trustProxy: Boolean(options.trustProxy),
+    databasePath,
+    limits,
+    apns: options.apns,
+    apnsProvider: options.apnsProvider,
+    clock: options.clock,
+    logger: options.logger,
+    resolveClientIp: options.resolveClientIp,
+    store: options.store,
+    http2: options.http2,
+  };
+};
+
+const envValue = (env, key) => {
+  const value = env[envName(key)];
+  return typeof value === 'string' && value.trim().length === 0 ? undefined : value;
+};
+
+const loadP8 = (env) => {
+  const inline = envValue(env, 'apnsP8') ?? env[`${ENV_PREFIX}APNS_P8`];
+  if (typeof inline === 'string' && inline.trim().length > 0) return normalizePem(inline);
+  const p8Path = envValue(env, 'apnsP8Path') ?? env[`${ENV_PREFIX}APNS_P8_PATH`];
+  if (typeof p8Path === 'string' && p8Path.trim().length > 0) {
+    try { return normalizePem(fs.readFileSync(p8Path.trim(), 'utf8')); } catch { fail(`${ENV_PREFIX}APNS_P8_PATH`); }
+  }
+  fail(`${ENV_PREFIX}APNS_P8`);
+};
+
+export const buildPushRelayConfig = (parsed = {}, env = process.env) => {
+  const pick = (key, fallback) => parsed[key] ?? envValue(env, key) ?? fallback;
+  const portValue = pick('port', DEFAULT_PORT);
+  const port = positive(parsed.port !== undefined ? '--port' : envName('port'), portValue);
+  if (port > 65535) fail(parsed.port !== undefined ? '--port' : envName('port'));
+  const host = validHost(parsed.host !== undefined ? '--host' : envName('host'), pick('host', DEFAULT_HOST));
+  const databasePath = validDatabasePath(envName('databasePath'), pick('databasePath', DEFAULT_DATABASE_PATH));
+  const limits = {};
+  for (const key of LIMIT_KEYS) {
+    const value = pick(key, undefined);
+    if (value !== undefined) limits[key] = positive(parsed[key] !== undefined ? `--${upperSnake(key).toLowerCase().replaceAll('_', '-')}` : envName(key), value);
+  }
+  const merged = { ...DEFAULT_LIMITS, ...limits };
+  if (merged.replayMs < merged.timestampSkewMs * 2) fail(parsed.replayMs !== undefined ? '--replay-ms' : envName('replayMs'));
+  validatePushRelayLimits(merged);
+  const keyId = pick('apnsKeyId', env[`${ENV_PREFIX}APNS_KEY_ID`]);
+  const teamId = pick('apnsTeamId', env[`${ENV_PREFIX}APNS_TEAM_ID`]);
+  const bundleId = pick('apnsBundleId', env[`${ENV_PREFIX}APNS_BUNDLE_ID`]) || DEFAULT_BUNDLE_ID;
+  if (typeof keyId !== 'string' || keyId.trim().length === 0) fail(`${ENV_PREFIX}APNS_KEY_ID`);
+  if (typeof teamId !== 'string' || teamId.trim().length === 0) fail(`${ENV_PREFIX}APNS_TEAM_ID`);
+  const p8 = loadP8(env);
+  if (!p8) fail(`${ENV_PREFIX}APNS_P8`);
+  return {
+    host,
+    port,
+    databasePath,
+    trustProxy: parsed.trustProxy ?? bool(envName('trustProxy'), envValue(env, 'trustProxy')),
+    limits: merged,
+    apns: { keyId: keyId.trim(), teamId: teamId.trim(), p8, bundleId: String(bundleId).trim() },
+  };
+};

package/src/push/crypto.js

@@ -0,0 +1,34 @@
+import crypto from 'node:crypto';
+
+const B64 = /^[A-Za-z0-9_-]+$/;
+
+export const canonicalPublicJwkString = (jwk) => JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y });
+
+export const b64urlExact = (value, length) => {
+  if (typeof value !== 'string' || !B64.test(value)) return null;
+  try {
+    const decoded = Buffer.from(value, 'base64url');
+    return decoded.length === length && decoded.toString('base64url') === value ? decoded : null;
+  } catch {
+    return null;
+  }
+};
+
+export const parsePublicJwk = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const keys = Object.keys(value);
+  if (keys.length !== 4 || !keys.includes('crv') || !keys.includes('kty') || !keys.includes('x') || !keys.includes('y')) return null;
+  if (value.kty !== 'EC' || value.crv !== 'P-256' || !b64urlExact(value.x, 32) || !b64urlExact(value.y, 32)) return null;
+  return { crv: value.crv, kty: value.kty, x: value.x, y: value.y };
+};
+
+export const deriveServerId = (jwk) => crypto.createHash('sha256').update(canonicalPublicJwkString(jwk)).digest('base64url');
+
+export const verifyP1363 = (message, jwk, signature) => {
+  try {
+    const key = crypto.createPublicKey({ key: { kty: jwk.kty, crv: jwk.crv, x: jwk.x, y: jwk.y }, format: 'jwk' });
+    return crypto.verify('SHA256', Buffer.from(message), { key, dsaEncoding: 'ieee-p1363' }, signature);
+  } catch {
+    return false;
+  }
+};

package/src/push/guard.js

@@ -0,0 +1,80 @@
+export const createReplayGuard = ({ replayMs, maxReplayEntries, now }) => {
+  const replay = new Map();
+  const purge = () => {
+    const ts = now();
+    for (const [key, expiry] of replay) if (expiry <= ts) replay.delete(key);
+  };
+  return {
+    has(key) {
+      purge();
+      return replay.has(key);
+    },
+    remember(key) {
+      purge();
+      if (replay.size >= maxReplayEntries && !replay.has(key)) return false;
+      replay.set(key, now() + replayMs);
+      return true;
+    },
+    clear() { replay.clear(); },
+    get size() { return replay.size; },
+  };
+};
+
+export const createSlidingWindowLimiter = ({ windowMs, maxCount, maxEntries, now }) => {
+  const entries = new Map();
+  const pruneKey = (key, cutoff) => {
+    const stamps = entries.get(key);
+    if (!stamps) return null;
+    let index = 0;
+    while (index < stamps.length && stamps[index] <= cutoff) index += 1;
+    if (index) stamps.splice(0, index);
+    if (stamps.length === 0) { entries.delete(key); return null; }
+    return stamps;
+  };
+  const purge = (cutoff) => {
+    for (const key of [...entries.keys()]) pruneKey(key, cutoff);
+  };
+  return {
+    allow(key) {
+      const ts = now();
+      const cutoff = ts - windowMs;
+      let stamps = pruneKey(key, cutoff);
+      if (!stamps) {
+        if (entries.size >= maxEntries) {
+          purge(cutoff);
+          if (entries.size >= maxEntries) return false;
+        }
+        stamps = [];
+        entries.set(key, stamps);
+      }
+      if (stamps.length >= maxCount) return false;
+      stamps.push(ts);
+      return true;
+    },
+    clear() { entries.clear(); },
+  };
+};
+
+export const createInFlightGate = (maxInFlight) => {
+  const maxWaiters = maxInFlight;
+  let active = 0;
+  const waiters = [];
+  return {
+    acquire() {
+      if (active < maxInFlight) { active += 1; return Promise.resolve(true); }
+      if (waiters.length >= maxWaiters) return Promise.resolve(false);
+      return new Promise((resolve) => { waiters.push(resolve); });
+    },
+    release() {
+      const next = waiters.shift();
+      if (next) next(true);
+      else active = Math.max(0, active - 1);
+    },
+    clear() {
+      while (waiters.length) waiters.shift()(false);
+      active = 0;
+    },
+    get active() { return active; },
+    get waiting() { return waiters.length; },
+  };
+};

package/src/push/index.d.ts

@@ -0,0 +1,110 @@
+import type { IncomingMessage } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+export type PushRelayState = 'idle' | 'starting' | 'running' | 'stopping' | 'stopped';
+export type PushRelayEnv = 'production' | 'sandbox';
+
+export interface PushRelayLimits {
+  timestampSkewMs: number;
+  replayMs: number;
+  maxReplayEntries: number;
+  registerLimitPerMinute: number;
+  sendLimitPerMinute: number;
+  serverSendLimitPerMinute: number;
+  maxTokens: number;
+  maxInFlight: number;
+  maxRateLimitEntries: number;
+  jsonBodyBytes: number;
+}
+
+export interface PushRelayApnsConfig {
+  keyId: string;
+  teamId: string;
+  p8: string;
+  bundleId: string;
+}
+
+export interface PushRelayClock {
+  now: () => number;
+  setTimeout: typeof globalThis.setTimeout;
+  clearTimeout: typeof globalThis.clearTimeout;
+  setInterval: typeof globalThis.setInterval;
+  clearInterval: typeof globalThis.clearInterval;
+  setImmediate: typeof globalThis.setImmediate;
+}
+
+export interface PushApnsSendInput {
+  token: string;
+  env: PushRelayEnv;
+  payload: unknown;
+  collapseId?: string;
+}
+
+export interface PushApnsSendResult {
+  ok: boolean;
+  drop?: boolean;
+}
+
+export interface PushApnsProvider {
+  send(input: PushApnsSendInput): Promise<PushApnsSendResult>;
+  close?(): void;
+}
+
+export interface PushTokenRecord {
+  serverId: string;
+  platform: string;
+  updatedAt: number;
+}
+
+export interface PushTokenStore {
+  get(token: string): PushTokenRecord | null;
+  upsert(token: string, serverId: string, platform: string, updatedAt: number): void;
+  delete(token: string): void;
+  count(): number;
+  close(): void;
+}
+
+export interface PushRelaySnapshotReasons {
+  authRejected: number;
+  policyRejected: number;
+  limited: number;
+  replayRejected: number;
+}
+
+export interface PushRelaySnapshot {
+  state: PushRelayState;
+  tokenCount: number;
+  inFlight: number;
+  replayEntries: number;
+  reasons: PushRelaySnapshotReasons;
+}
+
+export interface PushRelayOptions {
+  host?: string;
+  port?: number;
+  trustProxy?: boolean;
+  databasePath?: string;
+  limits?: Partial<PushRelayLimits>;
+  apns?: PushRelayApnsConfig;
+  apnsProvider?: PushApnsProvider;
+  clock?: Partial<PushRelayClock>;
+  logger?: Pick<Console, 'info' | 'warn' | 'error'>;
+  resolveClientIp?: (request: IncomingMessage) => string;
+  store?: PushTokenStore;
+  http2?: { connect: typeof import('node:http2').connect };
+}
+
+export interface PushRelayServerInstance {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  address(): string | AddressInfo | null | undefined;
+  readonly url: string | null;
+  getSnapshot(): PushRelaySnapshot;
+}
+
+export function resolvePushRelayClientIp(request: IncomingMessage, trustProxy?: boolean): string;
+export function formatPushRelayUrl(host: string, port: number): string;
+export function canonicalPublicJwkString(jwk: { crv: string; kty: string; x: string; y: string }): string;
+export function deriveServerId(jwk: { crv: string; kty: string; x: string; y: string }): string;
+export function createPushRelayServer(options?: PushRelayOptions): PushRelayServerInstance;
+export function startPushRelayServer(options?: PushRelayOptions): Promise<PushRelayServerInstance>;

package/src/push/index.js

@@ -0,0 +1,3 @@
+export { createPushRelayServer, startPushRelayServer } from './server.js';
+export { resolvePushRelayClientIp, formatPushRelayUrl } from './config.js';
+export { canonicalPublicJwkString, deriveServerId } from './crypto.js';

package/src/push/schema.js

@@ -0,0 +1,108 @@
+import { b64urlExact, parsePublicJwk } from './crypto.js';
+
+export const IOS_TOKEN = /^[0-9a-fA-F]{64}$/;
+export const JSON_BODY_BYTES = 16 * 1024;
+export const APNS_PAYLOAD_BYTES = 4096;
+export const MAX_TOKENS_PER_REQUEST = 100;
+export const MAX_TITLE_BYTES = 256;
+export const MAX_BODY_BYTES = 1024;
+export const MAX_COLLAPSE_ID_BYTES = 64;
+export const MAX_DATA_ENTRIES = 16;
+export const MAX_DATA_KEY_BYTES = 64;
+export const MAX_DATA_VALUE_BYTES = 256;
+export const MAX_DATA_TOTAL_BYTES = 2048;
+
+const bytes = (value) => Buffer.byteLength(value, 'utf8');
+const isSafeInt = (value) => typeof value === 'number' && Number.isSafeInteger(value);
+
+export const isIosToken = (value) => typeof value === 'string' && IOS_TOKEN.test(value);
+
+const parseTs = (value) => (isSafeInt(value) ? value : null);
+const parseSig = (value) => b64urlExact(value, 64);
+
+const parseData = (value) => {
+  if (value === undefined) return {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const entries = Object.entries(value);
+  if (entries.length > MAX_DATA_ENTRIES) return null;
+  let total = 0;
+  const data = {};
+  for (const [key, entry] of entries) {
+    if (typeof key !== 'string' || key.length === 0 || key === 'aps' || typeof entry !== 'string') return null;
+    const keyBytes = bytes(key);
+    const valueBytes = bytes(entry);
+    if (keyBytes > MAX_DATA_KEY_BYTES || valueBytes > MAX_DATA_VALUE_BYTES) return null;
+    total += keyBytes + valueBytes;
+    if (total > MAX_DATA_TOTAL_BYTES) return null;
+    data[key] = entry;
+  }
+  return data;
+};
+
+export const buildApnsPayload = ({ title, body, badge, collapseId, data }) => {
+  const alert = { title };
+  if (body) alert.body = body;
+  const aps = { alert, sound: 'default', 'mutable-content': 1 };
+  if (badge !== undefined) aps.badge = badge;
+  if (collapseId) aps['thread-id'] = collapseId;
+  return Object.keys(data).length > 0 ? { aps, ...data } : { aps };
+};
+
+export const validateRegisterBody = (body) => {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return { error: 'invalid_request' };
+  if (body.platform === 'android') return { error: 'unsupported_platform' };
+  if (body.platform !== 'ios') return { error: 'invalid_request' };
+  if (!isIosToken(body.token)) return { error: 'invalid_request' };
+  const jwk = parsePublicJwk(body.publicKeyJwk);
+  const ts = parseTs(body.ts);
+  const sig = parseSig(body.sig);
+  if (!jwk || ts === null || !sig) return { error: 'invalid_request' };
+  return { value: { token: body.token, platform: 'ios', publicKeyJwk: jwk, ts, sig } };
+};
+
+export const validateSendBody = (body) => {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return { error: 'invalid_request' };
+  const tokens = body.tokens;
+  if (!Array.isArray(tokens) || tokens.length < 1 || tokens.length > MAX_TOKENS_PER_REQUEST) return { error: 'invalid_request' };
+  if (tokens.some((token) => !isIosToken(token))) return { error: 'invalid_request' };
+  if (typeof body.title !== 'string' || body.title.length === 0 || bytes(body.title) > MAX_TITLE_BYTES) return { error: 'invalid_request' };
+  if (body.body !== undefined && (typeof body.body !== 'string' || bytes(body.body) > MAX_BODY_BYTES)) return { error: 'invalid_request' };
+  if (body.badge !== undefined && (!isSafeInt(body.badge) || body.badge < 0)) return { error: 'invalid_request' };
+  if (body.collapseId !== undefined && (typeof body.collapseId !== 'string' || bytes(body.collapseId) > MAX_COLLAPSE_ID_BYTES)) return { error: 'invalid_request' };
+  if (body.env !== undefined && body.env !== 'production' && body.env !== 'sandbox') return { error: 'invalid_request' };
+  const jwk = parsePublicJwk(body.publicKeyJwk);
+  const ts = parseTs(body.ts);
+  const sig = parseSig(body.sig);
+  const data = parseData(body.data);
+  if (!jwk || ts === null || !sig || !data) return { error: 'invalid_request' };
+  const unique = [];
+  const seen = new Set();
+  for (const token of tokens) {
+    if (seen.has(token)) continue;
+    seen.add(token);
+    unique.push(token);
+  }
+  const payload = buildApnsPayload({
+    title: body.title,
+    body: body.body ?? '',
+    badge: body.badge,
+    collapseId: body.collapseId,
+    data,
+  });
+  if (bytes(JSON.stringify(payload)) > APNS_PAYLOAD_BYTES) return { error: 'invalid_request' };
+  return {
+    value: {
+      tokens,
+      uniqueTokens: unique,
+      title: body.title,
+      body: typeof body.body === 'string' ? body.body : '',
+      badge: body.badge,
+      collapseId: body.collapseId || undefined,
+      env: body.env === 'production' ? 'production' : 'sandbox',
+      publicKeyJwk: jwk,
+      ts,
+      sig,
+      payload,
+    },
+  };
+};

package/src/push/server.js

@@ -0,0 +1,245 @@
+import http from 'node:http';
+
+import { createApnsProvider } from './apns.js';
+import { normalizePushRelayOptions, resolvePushRelayClientIp, formatPushRelayUrl } from './config.js';
+import { deriveServerId, verifyP1363 } from './crypto.js';
+import { createInFlightGate, createReplayGuard, createSlidingWindowLimiter } from './guard.js';
+import { JSON_BODY_BYTES, validateRegisterBody, validateSendBody } from './schema.js';
+import { createTokenStore } from './store.js';
+
+const WINDOW_MS = 60_000;
+
+const sendJson = (response, status, payload, method = 'GET') => {
+  if (response.writableEnded) return;
+  response.setHeader('cache-control', 'no-store');
+  response.writeHead(status, { 'content-type': 'application/json' });
+  response.end(method === 'HEAD' ? undefined : JSON.stringify(payload));
+};
+
+const readBody = (request, maxBytes) => new Promise((resolve, reject) => {
+  let done = false;
+  const fail = (error) => { if (done) return; done = true; reject(error); };
+  const succeed = (value) => { if (done) return; done = true; resolve(value); };
+  const tooLarge = () => {
+    const error = new Error('payload too large');
+    error.code = 'PAYLOAD_TOO_LARGE';
+    fail(error);
+  };
+  const declared = Number(request.headers['content-length']);
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    tooLarge();
+    request.resume();
+    return;
+  }
+  const chunks = [];
+  let size = 0;
+  request.on('data', (chunk) => {
+    size += chunk.length;
+    if (size > maxBytes) {
+      tooLarge();
+      request.destroy();
+      return;
+    }
+    chunks.push(chunk);
+  });
+  request.on('end', () => succeed(Buffer.concat(chunks)));
+  request.on('error', fail);
+});
+
+export const createPushRelayServer = (options = {}) => {
+  const config = normalizePushRelayOptions(options);
+  const limits = config.limits;
+  const clock = { now: Date.now, setTimeout, clearTimeout, setInterval, clearInterval, setImmediate, ...config.clock };
+  const resolveClientIp = config.resolveClientIp ?? ((request) => resolvePushRelayClientIp(request, config.trustProxy));
+  const ownedStore = !config.store;
+  const ownedApns = !config.apnsProvider;
+  const openStore = () => config.store ?? createTokenStore(config.databasePath);
+  const openApns = () => config.apnsProvider ?? createApnsProvider({ ...config.apns, clock, http2: config.http2 });
+  let store = openStore();
+  let apns;
+  try {
+    apns = openApns();
+  } catch (error) {
+    if (ownedStore) try { store.close(); } catch { /* ignore */ }
+    throw error;
+  }
+  const liveStore = () => {
+    if (!ownedStore) return store;
+    try { store.count(); return store; } catch {
+      store = createTokenStore(config.databasePath);
+      return store;
+    }
+  };
+  const replay = createReplayGuard({ replayMs: limits.replayMs, maxReplayEntries: limits.maxReplayEntries, now: () => clock.now() });
+  const registerIpLimit = createSlidingWindowLimiter({ windowMs: WINDOW_MS, maxCount: limits.registerLimitPerMinute, maxEntries: limits.maxRateLimitEntries, now: () => clock.now() });
+  const sendIpLimit = createSlidingWindowLimiter({ windowMs: WINDOW_MS, maxCount: limits.sendLimitPerMinute, maxEntries: limits.maxRateLimitEntries, now: () => clock.now() });
+  const sendServerLimit = createSlidingWindowLimiter({ windowMs: WINDOW_MS, maxCount: limits.serverSendLimitPerMinute, maxEntries: limits.maxRateLimitEntries, now: () => clock.now() });
+  const inFlight = createInFlightGate(limits.maxInFlight);
+  const reasons = { authRejected: 0, policyRejected: 0, limited: 0, replayRejected: 0 };
+  let server = null; let startPromise = null; let stopPromise = null; let abortStart = null; let state = 'idle'; let generation = 0;
+  const snapshot = () => {
+    let tokenCount = 0;
+    try { tokenCount = store.count(); } catch { /* closed after stop */ }
+    return { state, tokenCount, inFlight: inFlight.active, replayEntries: replay.size, reasons: { ...reasons } };
+  };
+
+  const authenticate = (jwk, message, signature, ts) => {
+    if (Math.abs(clock.now() - ts) > limits.timestampSkewMs) { reasons.authRejected += 1; return 'timestamp'; }
+    if (!verifyP1363(message, jwk, signature)) { reasons.authRejected += 1; return 'invalid_signature'; }
+    return null;
+  };
+
+  const handleRegister = (parsed) => {
+    const authError = authenticate(parsed.publicKeyJwk, `${parsed.ts}.${parsed.token}.${parsed.platform}`, parsed.sig, parsed.ts);
+    if (authError) return { status: 401, body: { error: authError } };
+    const serverId = deriveServerId(parsed.publicKeyJwk);
+    const tokens = liveStore();
+    const existing = tokens.get(parsed.token);
+    if (!existing && tokens.count() >= limits.maxTokens) { reasons.limited += 1; return { status: 429, body: { error: 'token_limit' } }; }
+    tokens.upsert(parsed.token, serverId, parsed.platform, clock.now());
+    return { status: 200, body: { ok: true } };
+  };
+
+  const handleSend = async (parsed) => {
+    const sorted = [...parsed.tokens].sort();
+    const authError = authenticate(parsed.publicKeyJwk, `${parsed.ts}.${sorted.join(',')}.${parsed.title}`, parsed.sig, parsed.ts);
+    if (authError) return { status: 401, body: { error: authError } };
+    const serverId = deriveServerId(parsed.publicKeyJwk);
+    const replayKey = `${serverId}.${parsed.ts}.${parsed.sig.toString('base64url')}`;
+    if (replay.has(replayKey)) { reasons.replayRejected += 1; return { status: 401, body: { error: 'replay' } }; }
+    if (!replay.remember(replayKey)) { reasons.limited += 1; return { status: 429, body: { error: 'rate_limited' } }; }
+    if (!sendServerLimit.allow(serverId)) { reasons.limited += 1; return { status: 429, body: { error: 'rate_limited' } }; }
+    const tokens = liveStore();
+    const results = await Promise.all(parsed.uniqueTokens.map(async (token) => {
+      const binding = tokens.get(token);
+      if (!binding || binding.serverId !== serverId) return { token, ok: false };
+      const acquired = await inFlight.acquire();
+      if (!acquired) { reasons.limited += 1; return { token, ok: false }; }
+      try {
+        const outcome = await apns.send({ token, env: parsed.env, payload: parsed.payload, collapseId: parsed.collapseId });
+        if (outcome?.drop === true) {
+          tokens.delete(token);
+          return { token, ok: false, drop: true };
+        }
+        return { token, ok: outcome?.ok === true };
+      } catch {
+        return { token, ok: false };
+      } finally {
+        inFlight.release();
+      }
+    }));
+    return { status: 200, body: { results } };
+  };
+
+  const onRequest = (request, response) => {
+    let pathname;
+    try { pathname = new URL(request.url ?? '/', 'http://push-relay').pathname; } catch { response.writeHead(404); response.end(); return; }
+    const ready = pathname === '/readyz' && state === 'running';
+    const healthy = pathname === '/healthz';
+    if ((healthy || ready) && (request.method === 'GET' || request.method === 'HEAD')) {
+      sendJson(response, 200, { status: 'ok' }, request.method);
+      return;
+    }
+    const isRegister = pathname === '/v1/push/register-token';
+    const isSend = pathname === '/v1/push/send';
+    if (request.method !== 'POST' || (!isRegister && !isSend)) { response.writeHead(404); response.end(); return; }
+    const ip = resolveClientIp(request);
+    const limiter = isRegister ? registerIpLimit : sendIpLimit;
+    if (!limiter.allow(ip)) { reasons.limited += 1; sendJson(response, 429, { error: 'rate_limited' }); return; }
+    readBody(request, limits.jsonBodyBytes ?? JSON_BODY_BYTES).then(async (buffer) => {
+      let body;
+      try { body = JSON.parse(buffer.toString('utf8')); } catch { reasons.policyRejected += 1; sendJson(response, 400, { error: 'invalid_request' }); return; }
+      const parsed = isRegister ? validateRegisterBody(body) : validateSendBody(body);
+      if (parsed.error) {
+        reasons.policyRejected += 1;
+        sendJson(response, 400, { error: parsed.error });
+        return;
+      }
+      const result = isRegister ? handleRegister(parsed.value) : await handleSend(parsed.value);
+      sendJson(response, result.status, result.body);
+    }).catch((error) => {
+      if (error?.code === 'PAYLOAD_TOO_LARGE') { reasons.policyRejected += 1; sendJson(response, 413, { error: 'payload_too_large' }); return; }
+      sendJson(response, 500, { error: 'internal' });
+    });
+  };
+
+  const start = () => {
+    if (state === 'running') return Promise.resolve();
+    if (state === 'stopping') return stopPromise.then(() => start());
+    if (startPromise) return startPromise;
+    liveStore();
+    if (ownedApns && state === 'stopped') apns = openApns();
+    state = 'starting';
+    const localGeneration = ++generation;
+    const localServer = http.createServer(onRequest);
+    server = localServer;
+    startPromise = new Promise((resolve, rejectStart) => {
+      const failStart = (error) => {
+        if (localGeneration !== generation) return;
+        localServer.off('listening', ready);
+        cleanupStart();
+        rejectStart(error);
+      };
+      const ready = () => {
+        localServer.off('error', failStart);
+        if (localGeneration !== generation || state !== 'starting') return;
+        state = 'running';
+        resolve();
+      };
+      const cleanupStart = () => {
+        localServer.close();
+        if (server === localServer) server = null;
+        state = 'stopped';
+      };
+      abortStart = () => {
+        if (state === 'starting') { cleanupStart(); rejectStart(new Error('push relay stopped during start')); }
+      };
+      localServer.once('error', failStart);
+      localServer.once('listening', ready);
+      localServer.listen(config.port, config.host);
+    }).finally(() => { startPromise = null; abortStart = null; });
+    return startPromise;
+  };
+
+  const stop = () => {
+    if (stopPromise) return stopPromise;
+    if (state === 'idle' || state === 'stopped') { state = 'stopped'; return Promise.resolve(); }
+    if (state === 'starting') abortStart?.();
+    state = 'stopping';
+    generation += 1;
+    const localServer = server;
+    stopPromise = new Promise((resolve) => {
+      inFlight.clear();
+      replay.clear();
+      registerIpLimit.clear();
+      sendIpLimit.clear();
+      sendServerLimit.clear();
+      try { apns.close?.(); } catch { /* ignore */ }
+      if (!localServer) return resolve();
+      localServer.close(() => resolve());
+      clock.setTimeout(resolve, 100);
+    }).then(() => {
+      if (server === localServer) { server = null; state = 'stopped'; }
+      if (ownedStore) try { store.close(); } catch { /* ignore */ }
+      stopPromise = null;
+    });
+    return stopPromise;
+  };
+
+  return {
+    start,
+    stop,
+    address: () => server?.address(),
+    get url() {
+      const address = server?.address();
+      return address && typeof address === 'object' ? formatPushRelayUrl(config.host, address.port) : null;
+    },
+    getSnapshot: snapshot,
+  };
+};
+
+export const startPushRelayServer = async (options) => {
+  const server = createPushRelayServer(options);
+  await server.start();
+  return server;
+};

package/src/push/store.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+const SCHEMA = `CREATE TABLE IF NOT EXISTS push_tokens (
+  token TEXT PRIMARY KEY,
+  server_id TEXT NOT NULL,
+  platform TEXT NOT NULL,
+  updated_at INTEGER NOT NULL
+) STRICT`;
+
+export const createTokenStore = (databasePath) => {
+  if (typeof databasePath !== 'string' || databasePath.length === 0 || databasePath.includes('\0')) {
+    throw new RangeError('invalid database path');
+  }
+  if (databasePath !== ':memory:') {
+    fs.mkdirSync(path.dirname(path.resolve(databasePath)), { recursive: true });
+  }
+  const db = new DatabaseSync(databasePath, { timeout: 5_000 });
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA busy_timeout = 5000');
+  db.exec(SCHEMA);
+  const getStmt = db.prepare('SELECT server_id AS serverId, platform, updated_at AS updatedAt FROM push_tokens WHERE token = ?');
+  const upsertStmt = db.prepare(`INSERT INTO push_tokens (token, server_id, platform, updated_at) VALUES (?, ?, ?, ?)
+    ON CONFLICT(token) DO UPDATE SET server_id = excluded.server_id, platform = excluded.platform, updated_at = excluded.updated_at`);
+  const deleteStmt = db.prepare('DELETE FROM push_tokens WHERE token = ?');
+  const countStmt = db.prepare('SELECT COUNT(*) AS n FROM push_tokens');
+  let closed = false;
+  const assertOpen = () => { if (closed) throw new Error('token store closed'); };
+  return {
+    get(token) {
+      assertOpen();
+      const row = getStmt.get(token);
+      return row ? { serverId: row.serverId, platform: row.platform, updatedAt: row.updatedAt } : null;
+    },
+    upsert(token, serverId, platform, updatedAt) {
+      assertOpen();
+      upsertStmt.run(token, serverId, platform, updatedAt);
+    },
+    delete(token) {
+      assertOpen();
+      deleteStmt.run(token);
+    },
+    count() {
+      assertOpen();
+      return Number(countStmt.get().n);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      try { db.close(); } catch { /* already closed */ }
+    },
+  };
+};