@openchambery/relay-server 1.19.3-beta.8 → 1.19.3

package/DOCUMENTATION.md

@@ -41,6 +41,38 @@ openchamber-push-relay --host 127.0.0.1 --port 8788
 
 The Host maps the effective Relay `wss://`/`ws://` URL to the same host as `https://`/`http://` `/v1/push/send`. Set `OPENCHAMBER_PUSH_RELAY_URL` on the Host to override. After a Relay switch, the Host re-registers persisted tokens and binds them before the first send. iOS Live Activity uses the same Push origin: `POST /v1/push/register-live-activity-token`, `POST /v1/push/unregister-live-activity-token`, and `POST /v1/push/live-activity`. Each Live Activity APNs request authenticates with the Host signing key, uses topic `{bundleId}.push-type.liveactivity`, and carries only `aps.timestamp`, `aps.event`, `aps.content-state`, and optional `dismissal-date` / `stale-date`. Successful `end` deliveries delete the token binding.
 
+### Combined mode (single port)
+
+When `openchamber-relay` sees any non-empty `OPENCHAMBER_PUSH_RELAY_APNS_*` variable, it mounts Push HTTP on the same listener at `/v1/push/*`. Missing required APNs fields fail startup instead of silently skipping Push. With no such variables, Layer 1 does not load the Push module.
+
+Combined mode ignores `OPENCHAMBER_PUSH_RELAY_HOST` and `OPENCHAMBER_PUSH_RELAY_PORT`. Public `/healthz` and `/readyz` stay Layer 1. The standalone `openchamber-push-relay` entry is unchanged.
+
+```sh
+export OPENCHAMBER_PUSH_RELAY_APNS_KEY_ID='<apns-key-id>'
+export OPENCHAMBER_PUSH_RELAY_APNS_TEAM_ID='<apns-team-id>'
+export OPENCHAMBER_PUSH_RELAY_APNS_BUNDLE_ID=com.yee94.openchamber
+export OPENCHAMBER_PUSH_RELAY_APNS_P8_PATH=/etc/openchamber/AuthKey.p8
+export OPENCHAMBER_PUSH_RELAY_DATABASE_PATH=/var/lib/openchamber/push-relay.sqlite
+openchamber-relay --public-url wss://relay.example.com/ws
+```
+
+Minimal Compose environment:
+
+```yaml
+services:
+  relay:
+    image: openchamber-relay:<version>
+    environment:
+      OPENCHAMBER_RELAY_SERVER_PUBLIC_URL: wss://relay.example.com/ws
+      OPENCHAMBER_PUSH_RELAY_APNS_KEY_ID: ${OPENCHAMBER_PUSH_RELAY_APNS_KEY_ID}
+      OPENCHAMBER_PUSH_RELAY_APNS_TEAM_ID: ${OPENCHAMBER_PUSH_RELAY_APNS_TEAM_ID}
+      OPENCHAMBER_PUSH_RELAY_APNS_BUNDLE_ID: com.yee94.openchamber
+      OPENCHAMBER_PUSH_RELAY_APNS_P8_PATH: /run/secrets/apns_p8
+      OPENCHAMBER_PUSH_RELAY_DATABASE_PATH: /data/push-relay.sqlite
+    ports:
+      - "127.0.0.1:8787:8787"
+```
+
 ### Caddy
 
 ```caddyfile

package/README.md

@@ -59,6 +59,43 @@ openchamber-push-relay --host 127.0.0.1 --port 8788
 
 Keep Push on loopback behind the same TLS reverse proxy. Route only `/v1/push/*` to port 8788.
 
+### Combined mode (single port)
+
+`openchamber-relay` can mount Push on the same listener. If any `OPENCHAMBER_PUSH_RELAY_APNS_*` variable is non-empty, Layer 1 loads Push and serves `/v1/push/*` on the Relay port. Partial APNs configuration fails startup; it does not silently disable Push. With no APNs variables set, Layer 1 behavior is unchanged and Push is not loaded.
+
+In combined mode:
+
+- Push routes share the Relay port at `/v1/push/*`.
+- `/healthz` and `/readyz` remain Layer 1 endpoints.
+- `OPENCHAMBER_PUSH_RELAY_HOST` and `OPENCHAMBER_PUSH_RELAY_PORT` are ignored.
+- `openchamber-push-relay` is unchanged and remains the isolated two-process option.
+
+```sh
+export OPENCHAMBER_PUSH_RELAY_APNS_KEY_ID='<apns-key-id>'
+export OPENCHAMBER_PUSH_RELAY_APNS_TEAM_ID='<apns-team-id>'
+export OPENCHAMBER_PUSH_RELAY_APNS_BUNDLE_ID=com.yee94.openchamber
+export OPENCHAMBER_PUSH_RELAY_APNS_P8_PATH=/etc/openchamber/AuthKey.p8
+export OPENCHAMBER_PUSH_RELAY_DATABASE_PATH=/var/lib/openchamber/push-relay.sqlite
+openchamber-relay --public-url wss://relay.example.com/ws
+```
+
+Minimal Compose environment for combined mode:
+
+```yaml
+services:
+  relay:
+    image: openchamber-relay:<version>
+    environment:
+      OPENCHAMBER_RELAY_SERVER_PUBLIC_URL: wss://relay.example.com/ws
+      OPENCHAMBER_PUSH_RELAY_APNS_KEY_ID: ${OPENCHAMBER_PUSH_RELAY_APNS_KEY_ID}
+      OPENCHAMBER_PUSH_RELAY_APNS_TEAM_ID: ${OPENCHAMBER_PUSH_RELAY_APNS_TEAM_ID}
+      OPENCHAMBER_PUSH_RELAY_APNS_BUNDLE_ID: com.yee94.openchamber
+      OPENCHAMBER_PUSH_RELAY_APNS_P8_PATH: /run/secrets/apns_p8
+      OPENCHAMBER_PUSH_RELAY_DATABASE_PATH: /data/push-relay.sqlite
+    ports:
+      - "127.0.0.1:8787:8787"
+```
+
 OpenChamber Hosts do not need a separate Push URL when they already have a Relay URL. The effective `wss://` or `ws://` Relay URL maps to the same host as `https://` or `http://` `/v1/push/send` (register is `/v1/push/register-token`). Set `OPENCHAMBER_PUSH_RELAY_URL` on the Host to override that mapping. After a Relay switch, the Host re-registers persisted device tokens and binds them again before the first send.
 
 ### Build a standalone executable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openchambery/relay-server",
-  "version": "1.19.3-beta.8",
+  "version": "1.19.3",
   "description": "Self-hosted private relay server for OpenChamber",
   "private": false,
   "type": "module",
@@ -46,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 && 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",
+    "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 && node --check src/push/handler.js && node --check src/push/combined.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 && node --check src/push/handler.js && node --check src/push/combined.js",
     "build:standalone": "bun build --compile --outfile dist/openchamber-relay bin/openchamber-relay.js"
   },
   "dependencies": {

package/src/cli.js

@@ -71,6 +71,16 @@ export const buildRelayConfig = (parsed = {}, env = process.env) => {
 
 const helpText = 'Usage: openchamber-relay [--host HOST] [--port PORT] [--path PATH] [--public-url WS_URL] [--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`);
+const hasPushApnsEnv = (env) => {
+  for (const [key, value] of Object.entries(env ?? {})) {
+    if (key.startsWith('OPENCHAMBER_PUSH_RELAY_APNS_') && typeof value === 'string' && value.trim().length > 0) return true;
+  }
+  return false;
+};
+const loadCombinedPushMount = async () => {
+  // Computed specifier keeps bun --compile from bundling Push/SQLite into the Layer 1 binary.
+  return (await import(['.', 'push', 'combined.js'].join('/'))).createCombinedPushMount;
+};
 
 export const runRelayServerCli = 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';
@@ -87,15 +97,24 @@ export const runRelayServerCli = async (argv, dependencies = {}) => {
   let config;
   try { config = buildRelayConfig(parsed, processLike.env ?? {}); } catch (error) { respond({ status: 'error', error: error.message, message: error.message }, true); processLike.exitCode = 1; return 1; }
   try {
+    const env = processLike.env ?? {};
+    const createPushMount = dependencies.createPushMount ?? (
+      hasPushApnsEnv(env) ? await loadCombinedPushMount() : () => null
+    );
+    const mount = createPushMount(env, dependencies.pushMountDeps ?? {});
+    if (mount) config.requestHandler = mount.requestHandler;
     const relay = await (dependencies.start ?? startPrivateRelayServer)(config);
+    if (mount) await mount.start();
     const url = config.publicUrl ?? relay.wsUrl;
-    respond(json ? { status: 'ok', url, host: config.host, port: relay.address?.()?.port ?? config.port, path: config.path } : { message: `Relay listening at ${url}` });
+    respond(json ? { status: 'ok', url, host: config.host, port: relay.address?.()?.port ?? config.port, path: config.path, ...(mount ? { push: true } : {}) } : { message: `Relay listening at ${url}` });
+    if (mount && !json) respond({ message: 'Push relay mounted at /v1/push/*' });
     let stopping = false;
     const stop = async () => {
       if (stopping) return Promise.resolve();
       stopping = true;
       processLike.off?.('SIGINT', stop); processLike.off?.('SIGTERM', stop);
       try {
+        if (mount) await mount.stop();
         await relay.stop();
         processLike.exit?.(0);
       } catch {

package/src/push/combined.js

@@ -0,0 +1,34 @@
+import { buildPushRelayConfig, ENV_PREFIX } from './config.js';
+import { createPushRelayHandler } from './handler.js';
+
+const APNS_ENV_PREFIX = `${ENV_PREFIX}APNS_`;
+
+const hasPushApnsEnv = (env) => {
+  for (const [key, value] of Object.entries(env ?? {})) {
+    if (!key.startsWith(APNS_ENV_PREFIX)) continue;
+    if (typeof value === 'string' && value.trim().length > 0) return true;
+  }
+  return false;
+};
+
+export const createCombinedPushMount = (env = process.env, deps = {}) => {
+  if (!hasPushApnsEnv(env)) return null;
+  const config = buildPushRelayConfig({}, env);
+  // Combined mode ignores OPENCHAMBER_PUSH_RELAY_HOST / OPENCHAMBER_PUSH_RELAY_PORT;
+  // Push HTTP is mounted on the Layer 1 listener at /v1/push/* instead of opening its own port.
+  const handler = createPushRelayHandler({
+    databasePath: config.databasePath,
+    trustProxy: config.trustProxy,
+    limits: config.limits,
+    apns: config.apns,
+    apnsProvider: deps.apnsProvider,
+    clock: deps.clock,
+    claimHealthEndpoints: false,
+  });
+  return {
+    requestHandler: handler.handleRequest,
+    start: () => handler.activate(),
+    stop: () => handler.deactivate(),
+    getSnapshot: handler.getSnapshot,
+  };
+};

package/src/push/handler.js

@@ -0,0 +1,292 @@
+import { createApnsProvider } from './apns.js';
+import { normalizePushRelayOptions, resolvePushRelayClientIp } from './config.js';
+import { deriveServerId, verifyP1363 } from './crypto.js';
+import { createInFlightGate, createReplayGuard, createSlidingWindowLimiter, createWorkTracker } from './guard.js';
+import { JSON_BODY_BYTES, buildLiveActivityPayload, validateLiveActivityBody, validateLiveActivityRegisterBody, validateRegisterBody, validateSendBody } from './schema.js';
+import { createTokenStore } from './store.js';
+
+const WINDOW_MS = 60_000;
+const STOP_DEADLINE_MS = 5_500;
+
+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 drain = () => {
+    request.removeListener('data', onData);
+    request.resume();
+  };
+  const declared = Number(request.headers['content-length']);
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    tooLarge();
+    request.resume();
+    return;
+  }
+  const chunks = [];
+  let size = 0;
+  const onData = (chunk) => {
+    size += chunk.length;
+    if (size > maxBytes) {
+      drain();
+      tooLarge();
+      return;
+    }
+    chunks.push(chunk);
+  };
+  request.on('data', onData);
+  request.on('end', () => succeed(Buffer.concat(chunks)));
+  request.on('error', fail);
+});
+
+export const createPushRelayHandler = (options = {}) => {
+  const claimHealthEndpoints = options.claimHealthEndpoints !== false;
+  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;
+    if (state === 'stopping') 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 httpWork = createWorkTracker();
+  const reasons = { authRejected: 0, policyRejected: 0, limited: 0, replayRejected: 0 };
+  let stopPromise = null; let state = 'idle';
+  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 message = parsed.kind
+      ? `${parsed.ts}.${parsed.token}.${parsed.platform}.${parsed.kind}`
+      : `${parsed.ts}.${parsed.token}.${parsed.platform}`;
+    const authError = authenticate(parsed.publicKeyJwk, message, parsed.sig, parsed.ts);
+    if (authError) return { status: 401, body: { error: authError } };
+    const serverId = deriveServerId(parsed.publicKeyJwk);
+    const replayKey = `${parsed.kind ? 'register-live-activity' : 'register'}.${serverId}.${parsed.ts}.${parsed.sig.toString('base64url')}`;
+    if (replay.has(replayKey)) return { status: 200, body: { ok: true } };
+    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' } }; }
+    if (!replay.remember(replayKey)) { reasons.limited += 1; return { status: 429, body: { error: 'rate_limited' } }; }
+    tokens.upsert(parsed.token, serverId, parsed.platform, clock.now());
+    return { status: 200, body: { ok: true } };
+  };
+
+  const handleUnregisterLiveActivity = (parsed) => {
+    const authError = authenticate(parsed.publicKeyJwk, `${parsed.ts}.${parsed.token}.${parsed.platform}.${parsed.kind}`, parsed.sig, parsed.ts);
+    if (authError) return { status: 401, body: { error: authError } };
+    const serverId = deriveServerId(parsed.publicKeyJwk);
+    const replayKey = `unregister-live-activity.${serverId}.${parsed.ts}.${parsed.sig.toString('base64url')}`;
+    if (replay.has(replayKey)) return { status: 200, body: { ok: true } };
+    const tokens = liveStore();
+    const existing = tokens.get(parsed.token);
+    if (existing && existing.serverId !== serverId) { reasons.authRejected += 1; return { status: 401, body: { error: 'invalid_signature' } }; }
+    if (!replay.remember(replayKey)) { reasons.limited += 1; return { status: 429, body: { error: 'rate_limited' } }; }
+    if (existing) tokens.delete(parsed.token);
+    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 = `send.${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(acquired);
+      }
+    }));
+    return { status: 200, body: { results } };
+  };
+
+  const handleLiveActivity = async (parsed) => {
+    const sorted = [...parsed.tokens].sort();
+    const contentState = parsed.contentState;
+    const message = `${parsed.ts}.${sorted.join(',')}.${parsed.event}.${contentState.status}.${contentState.eventVersion}.${contentState.updatedAt}.${contentState.endedAt ?? ''}.${parsed.dismissalDate ?? ''}.${parsed.staleDate ?? ''}`;
+    const authError = authenticate(parsed.publicKeyJwk, message, parsed.sig, parsed.ts);
+    if (authError) return { status: 401, body: { error: authError } };
+    const serverId = deriveServerId(parsed.publicKeyJwk);
+    const replayKey = `live-activity.${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 payload = buildLiveActivityPayload({
+      event: parsed.event,
+      contentState,
+      dismissalDate: parsed.dismissalDate,
+      staleDate: parsed.staleDate,
+      timestamp: Math.floor(clock.now() / 1000),
+    });
+    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, pushType: 'liveactivity' });
+        if (outcome?.drop === true) {
+          tokens.delete(token);
+          return { token, ok: false, drop: true };
+        }
+        if (outcome?.ok === true && parsed.event === 'end') tokens.delete(token);
+        return { token, ok: outcome?.ok === true };
+      } catch {
+        return { token, ok: false };
+      } finally {
+        inFlight.release(acquired);
+      }
+    }));
+    return { status: 200, body: { results } };
+  };
+
+  const handleRequest = (request, response) => {
+    let pathname;
+    try { pathname = new URL(request.url ?? '/', 'http://push-relay').pathname; } catch {
+      if (!claimHealthEndpoints) return false;
+      response.writeHead(404); response.end(); return true;
+    }
+    if (!claimHealthEndpoints && !pathname.startsWith('/v1/push/')) return false;
+    const ready = pathname === '/readyz' && state === 'running';
+    const healthy = pathname === '/healthz';
+    if (claimHealthEndpoints && (healthy || ready) && (request.method === 'GET' || request.method === 'HEAD')) {
+      sendJson(response, 200, { status: 'ok' }, request.method);
+      return true;
+    }
+    const isRegister = pathname === '/v1/push/register-token';
+    const isRegisterLive = pathname === '/v1/push/register-live-activity-token';
+    const isUnregisterLive = pathname === '/v1/push/unregister-live-activity-token';
+    const isSend = pathname === '/v1/push/send';
+    const isLiveActivity = pathname === '/v1/push/live-activity';
+    if (request.method !== 'POST' || (!isRegister && !isRegisterLive && !isUnregisterLive && !isSend && !isLiveActivity) || state !== 'running') { response.writeHead(404); response.end(); return true; }
+    const ip = resolveClientIp(request);
+    const limiter = (isRegister || isRegisterLive || isUnregisterLive) ? registerIpLimit : sendIpLimit;
+    if (!limiter.allow(ip)) { reasons.limited += 1; sendJson(response, 429, { error: 'rate_limited' }); return true; }
+    const endHttp = httpWork.begin();
+    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)
+        : (isRegisterLive || isUnregisterLive) ? validateLiveActivityRegisterBody(body)
+          : isLiveActivity ? validateLiveActivityBody(body)
+            : validateSendBody(body);
+      if (parsed.error) {
+        reasons.policyRejected += 1;
+        sendJson(response, 400, { error: parsed.error });
+        return;
+      }
+      const result = (isRegister || isRegisterLive) ? handleRegister(parsed.value)
+        : isUnregisterLive ? handleUnregisterLiveActivity(parsed.value)
+          : isLiveActivity ? await handleLiveActivity(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' });
+    }).finally(endHttp);
+    return true;
+  };
+
+  const activate = () => {
+    if (state === 'running') return;
+    liveStore();
+    inFlight.reset();
+    httpWork.reset();
+    if (ownedApns && state === 'stopped') apns = openApns();
+    state = 'running';
+  };
+
+  const deactivate = () => {
+    if (stopPromise) return stopPromise;
+    if (state === 'idle' || state === 'stopped') { state = 'stopped'; return Promise.resolve(); }
+    state = 'stopping';
+    stopPromise = Promise.resolve().then(async () => {
+      inFlight.rejectWaiters();
+      replay.clear();
+      registerIpLimit.clear();
+      sendIpLimit.clear();
+      sendServerLimit.clear();
+      let deadlineTimer = null;
+      try {
+        const graceful = Promise.all([inFlight.whenIdle(), httpWork.whenIdle()]);
+        const deadline = new Promise((resolve) => {
+          deadlineTimer = clock.setTimeout(() => resolve('deadline'), STOP_DEADLINE_MS);
+        });
+        await Promise.race([graceful.then(() => 'graceful'), deadline]);
+      } finally {
+        if (deadlineTimer !== null) try { clock.clearTimeout(deadlineTimer); } catch { /* ignore */ }
+      }
+      try { apns.close?.(); } catch { /* ignore */ }
+      if (ownedStore) try { store.close(); } catch { /* ignore */ }
+      state = 'stopped';
+      stopPromise = null;
+    });
+    return stopPromise;
+  };
+
+  return {
+    handleRequest,
+    activate,
+    deactivate,
+    getSnapshot: snapshot,
+  };
+};

package/src/push/server.js

@@ -1,258 +1,25 @@
 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, createWorkTracker } from './guard.js';
-import { JSON_BODY_BYTES, buildLiveActivityPayload, validateLiveActivityBody, validateLiveActivityRegisterBody, validateRegisterBody, validateSendBody } from './schema.js';
-import { createTokenStore } from './store.js';
+import { normalizePushRelayOptions, formatPushRelayUrl } from './config.js';
+import { createPushRelayHandler } from './handler.js';
 
-const WINDOW_MS = 60_000;
 const STOP_DEADLINE_MS = 5_500;
 
-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 drain = () => {
-    request.removeListener('data', onData);
-    request.resume();
-  };
-  const declared = Number(request.headers['content-length']);
-  if (Number.isFinite(declared) && declared > maxBytes) {
-    tooLarge();
-    request.resume();
-    return;
-  }
-  const chunks = [];
-  let size = 0;
-  const onData = (chunk) => {
-    size += chunk.length;
-    if (size > maxBytes) {
-      drain();
-      tooLarge();
-      return;
-    }
-    chunks.push(chunk);
-  };
-  request.on('data', onData);
-  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;
-    if (state === 'stopping') 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 httpWork = createWorkTracker();
-  const reasons = { authRejected: 0, policyRejected: 0, limited: 0, replayRejected: 0 };
+  const handler = createPushRelayHandler({ ...options, claimHealthEndpoints: true });
   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 message = parsed.kind
-      ? `${parsed.ts}.${parsed.token}.${parsed.platform}.${parsed.kind}`
-      : `${parsed.ts}.${parsed.token}.${parsed.platform}`;
-    const authError = authenticate(parsed.publicKeyJwk, message, parsed.sig, parsed.ts);
-    if (authError) return { status: 401, body: { error: authError } };
-    const serverId = deriveServerId(parsed.publicKeyJwk);
-    const replayKey = `${parsed.kind ? 'register-live-activity' : 'register'}.${serverId}.${parsed.ts}.${parsed.sig.toString('base64url')}`;
-    if (replay.has(replayKey)) return { status: 200, body: { ok: true } };
-    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' } }; }
-    if (!replay.remember(replayKey)) { reasons.limited += 1; return { status: 429, body: { error: 'rate_limited' } }; }
-    tokens.upsert(parsed.token, serverId, parsed.platform, clock.now());
-    return { status: 200, body: { ok: true } };
-  };
-
-  const handleUnregisterLiveActivity = (parsed) => {
-    const authError = authenticate(parsed.publicKeyJwk, `${parsed.ts}.${parsed.token}.${parsed.platform}.${parsed.kind}`, parsed.sig, parsed.ts);
-    if (authError) return { status: 401, body: { error: authError } };
-    const serverId = deriveServerId(parsed.publicKeyJwk);
-    const replayKey = `unregister-live-activity.${serverId}.${parsed.ts}.${parsed.sig.toString('base64url')}`;
-    if (replay.has(replayKey)) return { status: 200, body: { ok: true } };
-    const tokens = liveStore();
-    const existing = tokens.get(parsed.token);
-    if (existing && existing.serverId !== serverId) { reasons.authRejected += 1; return { status: 401, body: { error: 'invalid_signature' } }; }
-    if (!replay.remember(replayKey)) { reasons.limited += 1; return { status: 429, body: { error: 'rate_limited' } }; }
-    if (existing) tokens.delete(parsed.token);
-    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 = `send.${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(acquired);
-      }
-    }));
-    return { status: 200, body: { results } };
-  };
-
-  const handleLiveActivity = async (parsed) => {
-    const sorted = [...parsed.tokens].sort();
-    const contentState = parsed.contentState;
-    const message = `${parsed.ts}.${sorted.join(',')}.${parsed.event}.${contentState.status}.${contentState.eventVersion}.${contentState.updatedAt}.${contentState.endedAt ?? ''}.${parsed.dismissalDate ?? ''}.${parsed.staleDate ?? ''}`;
-    const authError = authenticate(parsed.publicKeyJwk, message, parsed.sig, parsed.ts);
-    if (authError) return { status: 401, body: { error: authError } };
-    const serverId = deriveServerId(parsed.publicKeyJwk);
-    const replayKey = `live-activity.${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 payload = buildLiveActivityPayload({
-      event: parsed.event,
-      contentState,
-      dismissalDate: parsed.dismissalDate,
-      staleDate: parsed.staleDate,
-      timestamp: Math.floor(clock.now() / 1000),
-    });
-    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, pushType: 'liveactivity' });
-        if (outcome?.drop === true) {
-          tokens.delete(token);
-          return { token, ok: false, drop: true };
-        }
-        if (outcome?.ok === true && parsed.event === 'end') tokens.delete(token);
-        return { token, ok: outcome?.ok === true };
-      } catch {
-        return { token, ok: false };
-      } finally {
-        inFlight.release(acquired);
-      }
-    }));
-    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 isRegisterLive = pathname === '/v1/push/register-live-activity-token';
-    const isUnregisterLive = pathname === '/v1/push/unregister-live-activity-token';
-    const isSend = pathname === '/v1/push/send';
-    const isLiveActivity = pathname === '/v1/push/live-activity';
-    if (request.method !== 'POST' || (!isRegister && !isRegisterLive && !isUnregisterLive && !isSend && !isLiveActivity) || state !== 'running') { response.writeHead(404); response.end(); return; }
-    const ip = resolveClientIp(request);
-    const limiter = (isRegister || isRegisterLive || isUnregisterLive) ? registerIpLimit : sendIpLimit;
-    if (!limiter.allow(ip)) { reasons.limited += 1; sendJson(response, 429, { error: 'rate_limited' }); return; }
-    const endHttp = httpWork.begin();
-    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)
-        : (isRegisterLive || isUnregisterLive) ? validateLiveActivityRegisterBody(body)
-          : isLiveActivity ? validateLiveActivityBody(body)
-            : validateSendBody(body);
-      if (parsed.error) {
-        reasons.policyRejected += 1;
-        sendJson(response, 400, { error: parsed.error });
-        return;
-      }
-      const result = (isRegister || isRegisterLive) ? handleRegister(parsed.value)
-        : isUnregisterLive ? handleUnregisterLiveActivity(parsed.value)
-          : isLiveActivity ? await handleLiveActivity(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' });
-    }).finally(endHttp);
-  };
 
   const start = () => {
     if (state === 'running') return Promise.resolve();
     if (state === 'stopping') return stopPromise.then(() => start());
     if (startPromise) return startPromise;
-    liveStore();
-    inFlight.reset();
-    httpWork.reset();
-    if (ownedApns && state === 'stopped') apns = openApns();
     state = 'starting';
     const localGeneration = ++generation;
-    const localServer = http.createServer(onRequest);
+    const localServer = http.createServer((request, response) => {
+      handler.handleRequest(request, response);
+    });
     server = localServer;
     startPromise = new Promise((resolve, rejectStart) => {
       const failStart = (error) => {
@@ -264,6 +31,7 @@ export const createPushRelayServer = (options = {}) => {
       const ready = () => {
         localServer.off('error', failStart);
         if (localGeneration !== generation || state !== 'starting') return;
+        handler.activate();
         state = 'running';
         resolve();
       };
@@ -290,11 +58,6 @@ export const createPushRelayServer = (options = {}) => {
     generation += 1;
     const localServer = server;
     stopPromise = Promise.resolve().then(async () => {
-      inFlight.rejectWaiters();
-      replay.clear();
-      registerIpLimit.clear();
-      sendIpLimit.clear();
-      sendServerLimit.clear();
       let deadlineTimer = null;
       try {
         const closed = new Promise((resolve) => {
@@ -302,22 +65,19 @@ export const createPushRelayServer = (options = {}) => {
           localServer.close(() => resolve());
           try { localServer.closeIdleConnections?.(); } catch { /* ignore */ }
         });
-        const httpIdle = httpWork.whenIdle().then(() => {
-          try { localServer?.closeIdleConnections?.(); } catch { /* ignore */ }
-        });
-        const graceful = Promise.all([closed, inFlight.whenIdle(), httpIdle]);
+        const deactivated = handler.deactivate();
+        const graceful = Promise.all([closed, deactivated]);
         const deadline = new Promise((resolve) => {
           deadlineTimer = clock.setTimeout(() => resolve('deadline'), STOP_DEADLINE_MS);
         });
         const winner = await Promise.race([graceful.then(() => 'graceful'), deadline]);
         if (winner === 'deadline') {
           try { localServer?.closeAllConnections?.(); } catch { /* ignore */ }
+          await deactivated;
         }
       } finally {
         if (deadlineTimer !== null) try { clock.clearTimeout(deadlineTimer); } catch { /* ignore */ }
       }
-      try { apns.close?.(); } catch { /* ignore */ }
-      if (ownedStore) try { store.close(); } catch { /* ignore */ }
       if (server === localServer) { server = null; state = 'stopped'; }
       stopPromise = null;
     });
@@ -332,7 +92,7 @@ export const createPushRelayServer = (options = {}) => {
       const address = server?.address();
       return address && typeof address === 'object' ? formatPushRelayUrl(config.host, address.port) : null;
     },
-    getSnapshot: snapshot,
+    getSnapshot: () => ({ ...handler.getSnapshot(), state }),
   };
 };