@abot-ai/socket 0.0.0-stage → 0.2.0

package/src/notifications/notification-delivery-payload.mjs

@@ -0,0 +1,45 @@
+import { validatedNotificationPreview } from './notification-preview-crypto.mjs';
+
+const TEXT = Object.freeze({
+  completed: 'Your response is ready.',
+  failed: 'Your request needs attention.',
+  approval_required: 'A request is waiting for your approval.',
+});
+
+export function notificationEnvelope(notification, badge, now) {
+  if (!notification || typeof notification.id !== 'string' || !/^[A-Za-z0-9_-]{16,128}$/.test(notification.id)) return null;
+  if (typeof notification.kind !== 'string' || !Object.hasOwn(TEXT, notification.kind)) return null;
+  if (!Number.isSafeInteger(notification.expiresAt) || notification.expiresAt <= now) return null;
+  if (!Number.isSafeInteger(badge) || badge < 0 || badge > 100_000) return null;
+  // The notification is only a hint. Destinations/content are loaded from the
+  // current authenticated server after the app opens, never trusted from push.
+  const envelope = {
+    notification: { title: 'ABot', body: TEXT[notification.kind] },
+    data: { notificationId: notification.id },
+    android: {
+      priority: 'HIGH',
+      ttl: `${Math.max(0, Math.floor(Math.min(notification.expiresAt - now, 7 * 86_400_000) / 1000))}s`,
+      notification: { channel_id: 'abot_updates', tag: notification.id,
+        notification_count: badge, default_sound: true },
+    },
+    apns: {
+      headers: { 'apns-push-type': 'alert', 'apns-priority': '10',
+        'apns-expiration': String(Math.floor(Math.min(notification.expiresAt, now + 7 * 86_400_000) / 1000)) },
+      payload: { aps: { badge, sound: 'default' } },
+    },
+  };
+  const preview = validatedNotificationPreview(notification.preview, notification, now);
+  if (preview) {
+    delete envelope.notification;
+    delete envelope.android.notification;
+    envelope.data = { notificationId: notification.id, abotPreview: JSON.stringify(preview),
+      abotKind: 'completed', abotExpiresAt: String(notification.expiresAt), abotBadge: String(badge) };
+    envelope.apns.payload.aps.alert = { title: 'ABot', body: TEXT.completed };
+    envelope.apns.payload.aps['mutable-content'] = 1;
+  }
+  return Buffer.byteLength(JSON.stringify(envelope), 'utf8') <= 4096 ? envelope : null;
+}
+
+export function isFcmDeviceToken(token) {
+  return typeof token === 'string' && /^[A-Za-z0-9_:.-]{16,4096}$/.test(token);
+}

package/src/notifications/notification-delivery.mjs

@@ -0,0 +1,43 @@
+import { createFcmNotificationDelivery } from './notification-delivery-fcm.mjs';
+import { createGatewayNotificationDelivery } from './notification-delivery-gateway.mjs';
+
+function hasOnlyDeliveryKeys(config, keys) {
+  return Object.keys(config).every((key) => keys.includes(key));
+}
+
+function isCanonicalGatewayOrigin(value) {
+  if (typeof value !== 'string' || value.length > 2048) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' && url.origin === value;
+  } catch { return false; }
+}
+
+/** Pure config validation: credentials are opened only when constructing a sender. */
+export function validateNotificationDeliveryConfiguration(config = { type: 'disabled' }) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('Invalid notification delivery configuration');
+  }
+  if (config.type === 'disabled' && hasOnlyDeliveryKeys(config, ['type'])) {
+    return { type: 'disabled' };
+  }
+  if (config.type === 'fcm' && hasOnlyDeliveryKeys(config, ['type', 'serviceAccountFile'])) {
+    const path = config.serviceAccountFile;
+    if (typeof path === 'string' && path.trim() && path.length <= 4096 && !/[\x00-\x1f\x7f]/.test(path)) {
+      return { type: 'fcm', serviceAccountFile: path };
+    }
+  }
+  if (config.type === 'gateway' && hasOnlyDeliveryKeys(config, ['type', 'gatewayOrigin']) &&
+      isCanonicalGatewayOrigin(config.gatewayOrigin)) {
+    return { type: 'gateway', gatewayOrigin: config.gatewayOrigin };
+  }
+  throw new Error('Invalid notification delivery configuration');
+}
+
+export function createNotificationDelivery(config, dependencies = {}) {
+  const validated = validateNotificationDeliveryConfiguration(config);
+  if (validated.type === 'fcm') return createFcmNotificationDelivery(validated, dependencies);
+  if (validated.type === 'gateway') return createGatewayNotificationDelivery(validated, dependencies);
+  return Object.freeze({ mode: 'disabled', configured: false,
+    send: async () => ({ status: 'retry' }) });
+}

package/src/notifications/notification-gateway-command.mjs

@@ -0,0 +1,48 @@
+import { dirname, resolve } from 'node:path';
+import { readPrivateConfiguration } from '../config/config.mjs';
+import { createFcmProvider } from './notification-delivery-fcm.mjs';
+import { createNotificationGateway } from './notification-gateway.mjs';
+
+/** The publisher runs this separate sender with its own identity and state. */
+export function loadNotificationGatewayConfiguration(path) {
+  if (typeof path !== 'string' || !path) throw new Error('Provide a private gateway configuration');
+  const config = readPrivateConfiguration(path);
+  if (!config || Array.isArray(config) || typeof config !== 'object' ||
+      Object.keys(config).some(key => !['publicOrigin', 'port', 'stateDirectory', 'serviceAccountFile'].includes(key))) {
+    throw new Error('Invalid push gateway configuration');
+  }
+  let origin;
+  try { origin = new URL(config.publicOrigin); } catch { /* Validated below. */ }
+  if (!origin || origin.protocol !== 'https:' || origin.origin !== config.publicOrigin) {
+    throw new Error('Gateway requires a canonical HTTPS origin');
+  }
+  const port = config.port ?? 8790;
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('Invalid gateway listener port');
+  const directory = dirname(resolve(path));
+  const privatePath = (value) => {
+    if (typeof value !== 'string' || !value.trim() || value.length > 4096 || /[\x00-\x1f\x7f]/.test(value)) {
+      throw new Error('Gateway requires private state and credential paths');
+    }
+    return resolve(directory, value);
+  };
+  return { publicOrigin: config.publicOrigin, port,
+    stateDirectory: privatePath(config.stateDirectory),
+    serviceAccountFile: privatePath(config.serviceAccountFile) };
+}
+
+export async function startConfiguredNotificationGateway(env, dependencies = {}) {
+  const path = env.ABOT_SOCKET_CONFIG || env.SOCKET_V2_CONFIG;
+  const config = loadNotificationGatewayConfiguration(path);
+  const provider = (dependencies.createProvider ?? createFcmProvider)({ serviceAccountFile: config.serviceAccountFile });
+  const gateway = (dependencies.createGateway ?? createNotificationGateway)({
+    stateDirectory: config.stateDirectory, publicOrigin: config.publicOrigin,
+    sendProviderEnvelope: (token, envelope, signal) => provider.sendEnvelope(token, envelope, signal),
+  });
+  try {
+    await gateway.listen(config.port);
+    return gateway;
+  } catch (error) {
+    await gateway.close();
+    throw error;
+  }
+}

package/src/notifications/notification-gateway-store.mjs

@@ -0,0 +1,159 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { assertSameDatabaseFile, prepareAuthenticationDatabase } from '../auth/auth-storage-path.mjs';
+
+const APPLICATION_ID = 0x41424757;
+const SECRET = /^[A-Za-z0-9_-]{43}$/;
+const secret = () => randomBytes(32).toString('base64url');
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const failure = (code, status = 400) => Object.assign(new Error(code), { code, status });
+
+function matchesCredential(value, expected) {
+  if (typeof value !== 'string' || !SECRET.test(value) || !expected) return false;
+  return timingSafeEqual(Buffer.from(digest(value), 'hex'), Buffer.from(expected, 'hex'));
+}
+
+/** Isolated gateway state. Never point this at a Socket authentication directory. */
+export class NotificationGatewayStore {
+  constructor({ stateDirectory, now = Date.now }) {
+    this.now = now;
+    const prepared = prepareAuthenticationDatabase(stateDirectory);
+    this.db = new DatabaseSync(prepared.path);
+    try {
+      assertSameDatabaseFile(stateDirectory, prepared);
+      this.db.exec('PRAGMA busy_timeout=5000; PRAGMA foreign_keys=ON; PRAGMA temp_store=MEMORY; PRAGMA secure_delete=ON;');
+      if (this.db.prepare('PRAGMA journal_mode').get().journal_mode !== 'delete') throw new Error();
+      this.transaction(() => this.initialize());
+      this.db.exec('PRAGMA synchronous=FULL;');
+      assertSameDatabaseFile(stateDirectory, prepared);
+    } catch {
+      this.db.close();
+      throw new Error('Gateway requires its own private state directory with a recognized database');
+    }
+  }
+
+  initialize() {
+    const id = this.db.prepare('PRAGMA application_id').get().application_id;
+    const version = this.db.prepare('PRAGMA user_version').get().user_version;
+    if (id === APPLICATION_ID && version === 1) return;
+    const objects = this.db.prepare("SELECT name FROM sqlite_schema WHERE name NOT LIKE 'sqlite_%'").all();
+    if (id || version || objects.length) throw new Error();
+    this.db.exec(`
+      CREATE TABLE gateway_challenges (
+        id TEXT PRIMARY KEY, token TEXT NOT NULL, token_hash TEXT NOT NULL,
+        proof_hash TEXT NOT NULL, expires_at INTEGER NOT NULL, attempts INTEGER NOT NULL
+      ) STRICT;
+      CREATE TABLE gateway_token_attempts (token_hash TEXT PRIMARY KEY, attempted_at INTEGER NOT NULL) STRICT;
+      CREATE TABLE gateway_endpoints (
+        id TEXT PRIMARY KEY, token TEXT NOT NULL, token_hash TEXT NOT NULL UNIQUE,
+        send_hash TEXT NOT NULL, manage_hash TEXT NOT NULL, expires_at INTEGER NOT NULL
+      ) STRICT;
+      CREATE TABLE gateway_deliveries (
+        endpoint_id TEXT NOT NULL REFERENCES gateway_endpoints(id) ON DELETE CASCADE,
+        notification_id TEXT NOT NULL, done INTEGER NOT NULL, lease_until INTEGER NOT NULL,
+        expires_at INTEGER NOT NULL, PRIMARY KEY(endpoint_id, notification_id)
+      ) STRICT;
+      PRAGMA application_id=${APPLICATION_ID}; PRAGMA user_version=1;
+    `);
+  }
+
+  transaction(operation) {
+    this.db.exec('BEGIN IMMEDIATE');
+    try { const result = operation(); this.db.exec('COMMIT'); return result; }
+    catch (error) { this.db.exec('ROLLBACK'); throw error; }
+  }
+
+  prune() {
+    const now = this.now();
+    this.db.prepare('DELETE FROM gateway_challenges WHERE expires_at<=?').run(now);
+    this.db.prepare('DELETE FROM gateway_token_attempts WHERE attempted_at<=?').run(now - 120_000);
+    this.db.prepare('DELETE FROM gateway_endpoints WHERE expires_at<=?').run(now);
+    this.db.prepare('DELETE FROM gateway_deliveries WHERE expires_at<=?').run(now);
+  }
+
+  createChallenge(token) {
+    return this.transaction(() => {
+      this.prune();
+      const tokenHash = digest(token);
+      if (this.db.prepare('SELECT 1 FROM gateway_token_attempts WHERE token_hash=?').get(tokenHash)) {
+        throw failure('rate_limited', 429);
+      }
+      const count = this.db.prepare('SELECT count(*) AS total FROM gateway_challenges').get().total;
+      if (count >= 128) throw failure('capacity', 503);
+      const challengeId = secret(); const proof = secret(); const expiresAt = this.now() + 120_000;
+      this.db.prepare('INSERT INTO gateway_token_attempts VALUES (?, ?)').run(tokenHash, this.now());
+      this.db.prepare('INSERT INTO gateway_challenges VALUES (?, ?, ?, ?, ?, 0)')
+        .run(challengeId, token, tokenHash, digest(proof), expiresAt);
+      return { challengeId, proof, expiresAt };
+    });
+  }
+
+  removeChallenge(id) { this.db.prepare('DELETE FROM gateway_challenges WHERE id=?').run(id); }
+
+  confirm(challengeId, proof) {
+    return this.transaction(() => {
+      this.prune();
+      const challenge = this.db.prepare('SELECT * FROM gateway_challenges WHERE id=?').get(challengeId);
+      if (!challenge) return null;
+      if (!matchesCredential(proof, challenge.proof_hash)) {
+        if (challenge.attempts >= 4) this.removeChallenge(challengeId);
+        else this.db.prepare('UPDATE gateway_challenges SET attempts=attempts+1 WHERE id=?').run(challengeId);
+        return null;
+      }
+      const existing = this.db.prepare('SELECT id FROM gateway_endpoints WHERE token_hash=?').get(challenge.token_hash);
+      const count = this.db.prepare('SELECT count(*) AS total FROM gateway_endpoints').get().total;
+      if (!existing && count >= 1024) throw failure('capacity', 503);
+      const endpointId = secret(); const sendToken = secret(); const manageToken = secret();
+      const expiresAt = this.now() + 30 * 86_400_000;
+      // Only a successfully proven replacement rotates an existing target grant.
+      if (existing) this.db.prepare('DELETE FROM gateway_endpoints WHERE id=?').run(existing.id);
+      this.db.prepare('INSERT INTO gateway_endpoints VALUES (?, ?, ?, ?, ?, ?)')
+        .run(endpointId, challenge.token, challenge.token_hash, digest(sendToken), digest(manageToken), expiresAt);
+      this.removeChallenge(challengeId);
+      return { endpointId, sendToken, manageToken, expiresAt };
+    });
+  }
+
+  authorize(endpointId, credential, management = false) {
+    const endpoint = this.db.prepare('SELECT * FROM gateway_endpoints WHERE id=? AND expires_at>?')
+      .get(endpointId, this.now());
+    if (!endpoint || !matchesCredential(credential, management ? endpoint.manage_hash : endpoint.send_hash)) return null;
+    return { id: endpoint.id, token: endpoint.token, expiresAt: endpoint.expires_at };
+  }
+
+  revoke(endpointId, manageToken) {
+    if (!this.authorize(endpointId, manageToken, true)) return false;
+    this.db.prepare('DELETE FROM gateway_endpoints WHERE id=?').run(endpointId);
+    return true;
+  }
+
+  removeInvalidEndpoint(endpointId) { this.db.prepare('DELETE FROM gateway_endpoints WHERE id=?').run(endpointId); }
+
+  claimDelivery(endpointId, notificationId, expiresAt) {
+    return this.transaction(() => {
+      this.prune();
+      const prior = this.db.prepare('SELECT * FROM gateway_deliveries WHERE endpoint_id=? AND notification_id=?')
+        .get(endpointId, notificationId);
+      if (prior?.done) return 'done';
+      if (prior?.lease_until > this.now()) return 'busy';
+      const count = this.db.prepare('SELECT count(*) AS total FROM gateway_deliveries').get().total;
+      if (!prior && count >= 20_000) throw failure('capacity', 503);
+      this.db.prepare(`INSERT INTO gateway_deliveries VALUES (?, ?, 0, ?, ?)
+        ON CONFLICT(endpoint_id,notification_id) DO UPDATE SET lease_until=excluded.lease_until`)
+        .run(endpointId, notificationId, this.now() + 15_000, expiresAt);
+      return 'send';
+    });
+  }
+
+  finishDelivery(endpointId, notificationId, delivered) {
+    if (delivered) {
+      this.db.prepare('UPDATE gateway_deliveries SET done=1,lease_until=0 WHERE endpoint_id=? AND notification_id=?')
+        .run(endpointId, notificationId);
+      return;
+    }
+    this.db.prepare('DELETE FROM gateway_deliveries WHERE endpoint_id=? AND notification_id=? AND done=0')
+      .run(endpointId, notificationId);
+  }
+
+  close() { this.db.close(); }
+}

package/src/notifications/notification-gateway.mjs

@@ -0,0 +1,181 @@
+import { createServer } from 'node:http';
+import { bearerToken, jsonResponse, readJson, sameAuthority, trustedClientAddress, WindowLimiter } from '../transport/transport-limits.mjs';
+import { validatedNotificationPreview } from './notification-preview-crypto.mjs';
+import { NotificationGatewayStore } from './notification-gateway-store.mjs';
+import { isFcmDeviceToken, notificationEnvelope } from './notification-delivery-payload.mjs';
+
+const IDENTIFIER = /^[A-Za-z0-9_-]{16,128}$/;
+const SECRET = /^[A-Za-z0-9_-]{43}$/;
+const failure = (code, status = 400) => Object.assign(new Error(code), { code, status });
+const isSecret = (value) => typeof value === 'string' && SECRET.test(value);
+const isIdentifier = (value) => typeof value === 'string' && IDENTIFIER.test(value);
+
+function hasExactKeys(body, keys) {
+  return Object.keys(body).length === keys.length && Object.keys(body).every((key) => keys.includes(key));
+}
+
+function canonicalOrigin(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol === 'https:' && url.origin === value) return url;
+  } catch { /* Reject malformed origins without exposing them. */ }
+  throw new Error('Gateway requires a canonical HTTPS publicOrigin');
+}
+
+/** Separate trusted sender process. This is not the user's chat relay. */
+export function createNotificationGateway({ stateDirectory, publicOrigin, sendProviderEnvelope, now = Date.now }) {
+  const origin = canonicalOrigin(publicOrigin);
+  if (typeof sendProviderEnvelope !== 'function') throw new Error('Gateway requires a notification provider');
+  const store = new NotificationGatewayStore({ stateDirectory, now });
+  const shutdown = new AbortController();
+  const sources = new WindowLimiter({ limit: 120, windowMs: 60_000, now });
+  const enrollment = new WindowLimiter({ limit: 5, windowMs: 60 * 60_000, now });
+  const enrollmentTotal = new WindowLimiter({ limit: 1000, windowMs: 86_400_000, capacity: 1, now });
+  const endpointRate = new WindowLimiter({ limit: 30, windowMs: 60_000, now });
+  const activeDeliveries = new Map();
+  const activeHandlers = new Set();
+
+  async function sendEnvelope(token, envelope, signal = shutdown.signal) {
+    const deadline = new AbortController();
+    const combined = AbortSignal.any([signal, deadline.signal]);
+    const timer = setTimeout(() => deadline.abort(), 10_000);
+    let onAbort;
+    try {
+      if (combined.aborted) return { status: 'retry' };
+      const interrupted = new Promise((resolve) => {
+        onAbort = () => resolve({ status: 'retry' });
+        combined.addEventListener('abort', onAbort, { once: true });
+      });
+      return await Promise.race([sendProviderEnvelope(token, envelope, combined), interrupted]);
+    } catch { return { status: 'retry' }; }
+    finally {
+      clearTimeout(timer);
+      if (onAbort) combined.removeEventListener('abort', onAbort);
+    }
+  }
+
+  async function enroll(body, sourceId) {
+    if (!hasExactKeys(body, ['token']) || !isFcmDeviceToken(body.token)) throw failure('invalid_request');
+    if (!enrollment.allow(sourceId) || !enrollmentTotal.allow('gateway')) throw failure('rate_limited', 429);
+    const challenge = store.createChallenge(body.token);
+    const result = await sendEnvelope(body.token, {
+      data: { abotPushChallenge: challenge.challengeId, proof: challenge.proof },
+      android: { priority: 'NORMAL',
+        ttl: `${Math.max(0, Math.floor((challenge.expiresAt - now()) / 1000))}s` },
+      apns: { headers: { 'apns-push-type': 'background', 'apns-priority': '5',
+        'apns-expiration': String(Math.floor(challenge.expiresAt / 1000)) },
+      payload: { aps: { 'content-available': 1 } } },
+    });
+    if (result.status !== 'delivered') {
+      store.removeChallenge(challenge.challengeId);
+      throw failure('provider_unavailable', 503);
+    }
+    return { challengeId: challenge.challengeId, expiresAt: challenge.expiresAt };
+  }
+
+  function confirm(body) {
+    if (!hasExactKeys(body, ['challengeId', 'proof']) || !isSecret(body.challengeId) || !isSecret(body.proof)) {
+      throw failure('invalid_request');
+    }
+    const grant = store.confirm(body.challengeId, body.proof);
+    if (!grant) throw failure('unauthorized', 401);
+    return grant;
+  }
+
+  async function deliver(body, credential) {
+    const keys = ['endpointId', 'notificationId', 'kind', 'expiresAt', 'badge'];
+    if (Object.hasOwn(body, 'preview')) keys.push('preview');
+    if (!hasExactKeys(body, keys) ||
+        !isSecret(body.endpointId) || !isIdentifier(body.notificationId)) throw failure('invalid_request');
+    const endpoint = store.authorize(body.endpointId, credential);
+    if (!endpoint) throw failure('unauthorized', 401);
+    const notification = { id: body.notificationId, kind: body.kind, expiresAt: body.expiresAt };
+    if (body.expiresAt > now() + 7 * 86_400_000) throw failure('invalid_request');
+    if (Object.hasOwn(body, 'preview')) {
+      notification.preview = validatedNotificationPreview(body.preview, notification, now());
+      if (!notification.preview) throw failure('invalid_request');
+    }
+    const envelope = notificationEnvelope(notification, body.badge, now());
+    if (!envelope) throw failure('invalid_request');
+    if (!endpointRate.allow(endpoint.id)) throw failure('rate_limited', 429);
+    const claim = store.claimDelivery(endpoint.id, notification.id, notification.expiresAt);
+    if (claim === 'done') return { ok: true };
+    if (claim === 'busy') throw failure('delivery_pending', 503);
+    const controller = new AbortController();
+    const signal = AbortSignal.any([controller.signal, shutdown.signal]);
+    const deliveryKey = `${endpoint.id}:${notification.id}`;
+    activeDeliveries.set(deliveryKey, { endpointId: endpoint.id, controller });
+    let result;
+    try { result = await sendEnvelope(endpoint.token, envelope, signal); }
+    finally { activeDeliveries.delete(deliveryKey); }
+    if (result.status === 'invalid') {
+      store.removeInvalidEndpoint(endpoint.id);
+      throw failure('endpoint_unavailable', 410);
+    }
+    store.finishDelivery(endpoint.id, notification.id, result.status === 'delivered');
+    if (result.status !== 'delivered') throw failure('provider_unavailable', 503);
+    return { ok: true };
+  }
+
+  function revoke(body, credential) {
+    if (!hasExactKeys(body, ['endpointId']) || !isSecret(body.endpointId)) throw failure('invalid_request');
+    if (!store.revoke(body.endpointId, credential)) throw failure('unauthorized', 401);
+    for (const delivery of activeDeliveries.values()) {
+      if (delivery.endpointId === body.endpointId) delivery.controller.abort();
+    }
+    return { ok: true };
+  }
+
+  async function handleRequest(req, res) {
+    try {
+      if (shutdown.signal.aborted) throw failure('unavailable', 503);
+      if (!sameAuthority(req, origin) || req.headers['x-forwarded-proto'] !== 'https') throw failure('forbidden', 403);
+      const sourceId = trustedClientAddress(req);
+      if (!sourceId) throw failure('forbidden', 403);
+      if (!sources.allow(sourceId)) throw failure('rate_limited', 429);
+      if (req.method === 'GET' && req.url === '/health') return jsonResponse(res, 200, { ok: true });
+      if (req.method !== 'POST') throw failure('not_found', 404);
+      const body = await readJson(req, 8192);
+      if (req.url === '/v1/enroll') return jsonResponse(res, 200, await enroll(body, sourceId));
+      if (req.url === '/v1/confirm') return jsonResponse(res, 200, confirm(body));
+      if (req.url === '/v1/deliver') return jsonResponse(res, 200, await deliver(body, bearerToken(req)));
+      if (req.url === '/v1/revoke') return jsonResponse(res, 200, revoke(body, bearerToken(req)));
+      throw failure('not_found', 404);
+    } catch (error) {
+      const status = [400, 401, 403, 404, 410, 413, 415, 429, 503].includes(error.status) ? error.status : 500;
+      const code = status === 500 ? 'internal_error' : error.code;
+      if (!res.headersSent && !res.destroyed) jsonResponse(res, status, { error: code });
+    }
+  }
+
+  function handler(req, res) {
+    const operation = handleRequest(req, res);
+    activeHandlers.add(operation);
+    void operation.finally(() => activeHandlers.delete(operation));
+    return operation;
+  }
+
+  const server = createServer(handler);
+  server.requestTimeout = 15_000; server.headersTimeout = 5_000;
+  server.keepAliveTimeout = 5_000; server.maxHeadersCount = 32; server.maxConnections = 32;
+  const sweep = setInterval(() => {
+    store.prune(); sources.prune(); enrollment.prune(); enrollmentTotal.prune(); endpointRate.prune();
+  }, 30_000);
+  sweep.unref();
+  let closed = false;
+  return {
+    handler,
+    listen: (port = 8789) => new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, '127.0.0.1', () => { server.off('error', reject); resolve(server.address()); });
+    }),
+    close: () => new Promise((resolve) => {
+      if (closed) { resolve(); return; }
+      closed = true; clearInterval(sweep); shutdown.abort();
+      server.closeAllConnections();
+      server.close(() => {
+        void Promise.allSettled([...activeHandlers]).then(() => { store.close(); resolve(); });
+      });
+    }),
+  };
+}

package/src/notifications/notification-http.mjs

@@ -0,0 +1,39 @@
+import { jsonResponse, readJson } from '../transport/transport-limits.mjs';
+import { notificationListOptions, notificationPresence, notificationReadIds, notificationRegistration, notificationPreviewKey } from './notification-input.mjs';
+
+/** Authenticated device identity comes from the caller, never from request fields. */
+export async function handleNotificationHttp(req, res, { principal, notifications, runtimeGrants }) {
+  const url = new URL(req.url, 'https://socket.invalid');
+  const path = url.pathname;
+  if (req.method === 'GET' && path === '/v2/notifications') {
+    jsonResponse(res, 200, notifications.list(principal.sessionId, notificationListOptions(url.searchParams)));
+    return true;
+  }
+  if (url.search) return false;
+  if (req.method === 'POST' && path === '/v2/notifications/read') {
+    notifications.markRead(principal.sessionId, notificationReadIds(await readJson(req)));
+    jsonResponse(res, 200, { ok: true }); return true;
+  }
+  if (req.method === 'POST' && path === '/v2/notifications/presence') {
+    const value = notificationPresence(await readJson(req), runtimeGrants.map(grant => grant.runtimeId));
+    notifications.updatePresence(principal.sessionId, value);
+    jsonResponse(res, 200, { ok: true }); return true;
+  }
+  if (req.method === 'PUT' && path === '/v2/notifications/push/preview') {
+    notifications.enablePreview(principal.sessionId, notificationPreviewKey(await readJson(req, 512)));
+    jsonResponse(res, 200, { ok: true }); return true;
+  }
+  if (req.method === 'DELETE' && path === '/v2/notifications/push/preview') {
+    notifications.disablePreview(principal.sessionId);
+    jsonResponse(res, 200, { ok: true }); return true;
+  }
+  if (req.method === 'PUT' && path === '/v2/notifications/push') {
+    notifications.register(principal.sessionId, notificationRegistration(await readJson(req, 8192)));
+    jsonResponse(res, 200, { ok: true }); return true;
+  }
+  if (req.method === 'DELETE' && path === '/v2/notifications/push') {
+    notifications.unregister(principal.sessionId);
+    jsonResponse(res, 200, { ok: true }); return true;
+  }
+  return false;
+}

package/src/notifications/notification-input.mjs

@@ -0,0 +1,82 @@
+import { isRelayId } from '../relay/relay-runtime-registration.mjs';
+import { hasPreviewKey } from './notification-preview-crypto.mjs';
+
+export function notificationInputError(code = 'invalid_request', status = 400) {
+  return Object.assign(new Error(code), { code, status });
+}
+
+function exactRecord(value, allowed) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw notificationInputError();
+  if (Object.keys(value).some(key => !allowed.includes(key))) throw notificationInputError();
+}
+
+export function notificationReadIds(value) {
+  exactRecord(value, ['ids']);
+  if (!Array.isArray(value.ids) || value.ids.length > 100 || !value.ids.every(isRelayId)) {
+    throw notificationInputError();
+  }
+  return [...new Set(value.ids)];
+}
+
+export function notificationPresence(value, allowedRuntimeIds) {
+  exactRecord(value, ['foreground', 'runtimeId', 'sessionId']);
+  if (typeof value.foreground !== 'boolean') throw notificationInputError();
+  for (const key of ['runtimeId', 'sessionId']) {
+    if (value[key] !== undefined && !isRelayId(value[key])) throw notificationInputError();
+  }
+  if (value.sessionId !== undefined && value.runtimeId === undefined) throw notificationInputError();
+  if (value.runtimeId !== undefined && !allowedRuntimeIds.includes(value.runtimeId)) {
+    throw notificationInputError('forbidden', 403);
+  }
+  return value.foreground ? { ...value } : { foreground: false };
+}
+
+function boundedCredential(value, maxLength) {
+  return typeof value === 'string' && value.length > 0 && value.length <= maxLength &&
+    !/[\s\x00-\x1f\x7f]/u.test(value);
+}
+
+export function notificationRegistration(value) {
+  if (value?.provider === 'fcm') {
+    exactRecord(value, ['provider', 'token']);
+    if (!boundedCredential(value.token, 4096)) throw notificationInputError();
+    return { provider: 'fcm', token: value.token };
+  }
+  if (value?.provider === 'gateway') {
+    exactRecord(value, ['provider', 'endpointId', 'sendToken']);
+    if (!boundedCredential(value.endpointId, 256) || !boundedCredential(value.sendToken, 2048)) {
+      throw notificationInputError();
+    }
+    return { provider: 'gateway', endpointId: value.endpointId, sendToken: value.sendToken };
+  }
+  throw notificationInputError();
+}
+
+export function notificationPreviewKey(value) {
+  if (!hasPreviewKey(value)) throw notificationInputError();
+  return { keyId: value.keyId, key: value.key };
+}
+
+export function notificationListOptions(params) {
+  const keys = [...params.keys()];
+  if (new Set(keys).size !== keys.length || keys.some(key => !['limit', 'before'].includes(key))) {
+    throw notificationInputError();
+  }
+  const limitValue = params.get('limit') ?? '50';
+  if (!/^\d{1,3}$/.test(limitValue)) throw notificationInputError();
+  const limit = Number(limitValue);
+  if (limit < 1 || limit > 100) throw notificationInputError();
+  const cursor = params.get('before');
+  if (cursor === null) return { limit, before: null };
+  if (!/^[A-Za-z0-9_-]{1,512}$/.test(cursor)) throw notificationInputError();
+  try {
+    const value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    if (!Array.isArray(value) || value.length !== 2 || !Number.isSafeInteger(value[0]) ||
+      value[0] < 0 || !isRelayId(value[1])) throw new Error();
+    return { limit, before: { createdAt: value[0], id: value[1] } };
+  } catch { throw notificationInputError(); }
+}
+
+export function notificationCursor(item) {
+  return Buffer.from(JSON.stringify([item.createdAt, item.id])).toString('base64url');
+}

package/src/notifications/notification-outbox.mjs

@@ -0,0 +1,60 @@
+import { validatedNotificationPreview } from './notification-preview-crypto.mjs';
+
+const MAX_ATTEMPTS = 5;
+const CLAIM_MS = 30_000;
+
+/** Durable bounded retries for already-recorded events; never executes a runtime request. */
+export class NotificationOutbox {
+  constructor({ database, now = Date.now }) { this.database = database; this.now = now; }
+
+  claim(provider) {
+    return this.database.transaction(() => {
+      this.database.prepare('DELETE FROM notification_outbox WHERE attempts >= ?').run(MAX_ATTEMPTS);
+      const row = this.database.prepare(`SELECT n.id, n.device_id AS deviceId, n.runtime_id AS runtimeId,
+        n.session_id AS sessionId, n.request_id AS requestId, n.kind, n.created_at AS createdAt,
+        n.read_at AS readAt, n.expires_at AS expiresAt, o.attempts, o.encrypted_preview, r.registration
+        FROM notification_outbox o JOIN notifications n ON n.id = o.notification_id
+        JOIN devices d ON d.id = n.device_id JOIN notification_registrations r ON r.device_id = n.device_id
+        WHERE o.next_at <= ? AND n.read_at IS NULL AND n.expires_at > ? AND d.expires_at > ?
+        AND r.provider = ? ORDER BY o.next_at, n.created_at, n.id LIMIT 1`)
+        .get(this.now(), this.now(), this.now(), provider);
+      if (!row) return null;
+      this.database.prepare('UPDATE notification_outbox SET attempts = attempts + 1, next_at = ? WHERE notification_id = ?')
+        .run(this.now() + CLAIM_MS, row.id);
+      const { deviceId, registration, attempts, encrypted_preview: encodedPreview, ...notification } = row;
+      if (encodedPreview) {
+        try {
+          const preview = validatedNotificationPreview(JSON.parse(encodedPreview), notification, this.now());
+          if (preview) notification.preview = preview;
+        } catch { /* Corrupt previews fall back to the generic notification. */ }
+      }
+      return { deviceId, registration: JSON.parse(registration), attempts: attempts + 1, notification, encodedPreview };
+    });
+  }
+
+  canDeliver(entry) {
+    const row = this.database.prepare(`SELECT r.registration, o.encrypted_preview FROM notification_outbox o
+      JOIN notifications n ON n.id = o.notification_id JOIN devices d ON d.id = n.device_id
+      JOIN notification_registrations r ON r.device_id = n.device_id
+      WHERE n.id = ? AND n.device_id = ? AND n.read_at IS NULL AND n.expires_at > ? AND d.expires_at > ?`)
+      .get(entry.notification.id, entry.deviceId, this.now(), this.now());
+    return row?.registration === JSON.stringify(entry.registration) && row.encrypted_preview === entry.encodedPreview;
+  }
+
+  cancel(entry) {
+    // A cancelled send spends no attempt and cannot recreate a read/revoked item.
+    this.database.prepare(`UPDATE notification_outbox SET attempts = MAX(0, attempts - 1), next_at = ?
+      WHERE notification_id = ? AND attempts = ?`)
+      .run(this.now() + CLAIM_MS, entry.notification.id, entry.attempts);
+  }
+
+  finish(entry, status) {
+    if (['delivered', 'invalid', 'discarded'].includes(status) || entry.attempts >= MAX_ATTEMPTS) {
+      this.database.prepare('DELETE FROM notification_outbox WHERE notification_id = ?').run(entry.notification.id);
+      return;
+    }
+    const backoff = Math.min(600_000, 30_000 * 2 ** (entry.attempts - 1));
+    this.database.prepare('UPDATE notification_outbox SET next_at = ? WHERE notification_id = ?')
+      .run(this.now() + backoff, entry.notification.id);
+  }
+}