@abot-ai/socket 0.0.0-stage → 0.2.0

package/src/config/config-validation.mjs

@@ -0,0 +1,41 @@
+import { validateRuntimeGrants } from '../auth/runtime-credentials.mjs';
+import { validateNotificationDeliveryConfiguration } from '../notifications/notification-delivery.mjs';
+
+function isCanonicalHttpsOrigin(value) {
+  if (typeof value !== 'string') return false;
+  try {
+    const origin = new URL(value);
+    return origin.protocol === 'https:' && origin.origin === value;
+  } catch { return false; }
+}
+
+/** Pure preflight: no listener, credentials or state are created here. */
+export function validateConfiguration(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('Invalid configuration');
+  }
+  if (!isCanonicalHttpsOrigin(config.publicOrigin)) {
+    throw new Error('Configure a canonical HTTPS publicOrigin');
+  }
+  const port = config.port ?? 8788;
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+    throw new Error('Invalid listener port');
+  }
+  if (typeof config.stateDirectory !== 'string' || !config.stateDirectory.trim() ||
+      config.stateDirectory.length > 4096 || /[\x00-\x1f\x7f]/.test(config.stateDirectory)) {
+    throw new Error('Configure a private stateDirectory');
+  }
+  if (Object.hasOwn(config, 'mail') || Object.hasOwn(config, 'allowedEmail')) {
+    throw new Error('Email configuration is unsupported; create a pairing installation');
+  }
+  const notifications = config.notifications ?? {};
+  if (!notifications || typeof notifications !== 'object' || Array.isArray(notifications) ||
+      Object.keys(notifications).some(key => key !== 'delivery')) {
+    throw new Error('Invalid notification configuration');
+  }
+  return {
+    publicOrigin: config.publicOrigin, port, stateDirectory: config.stateDirectory,
+    runtimeGrants: validateRuntimeGrants(config.runtimeGrants),
+    notifications: { delivery: validateNotificationDeliveryConfiguration(notifications.delivery) },
+  };
+}

package/src/config/config.mjs

@@ -0,0 +1,57 @@
+import { openSync, closeSync, fstatSync, readSync, constants } from 'node:fs';
+import { validateConfiguration } from './config-validation.mjs';
+import { dirname, resolve } from 'node:path';
+
+const MAX_CONFIG_BYTES = 32_768;
+
+function selectEnvironmentValue(env, primary, legacy) {
+  const preferred = env[primary];
+  const fallback = env[legacy];
+  if (preferred && fallback && preferred !== fallback) {
+    throw new Error(`Conflicting ${primary} and ${legacy} settings`);
+  }
+  const value = preferred || fallback;
+  if (value !== undefined && typeof value !== 'string') {
+    throw new Error(`Invalid ${primary} setting`);
+  }
+  return value;
+}
+
+function isPrivateConfigurationFile(stat) {
+  if (!stat.isFile()) return false;
+  if (stat.size > MAX_CONFIG_BYTES) return false;
+  return (stat.mode & 0o077) === 0;
+}
+
+export function readPrivateConfiguration(path) {
+  let descriptor;
+  try {
+    descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    if (!isPrivateConfigurationFile(fstatSync(descriptor))) throw new Error();
+    const buffer = Buffer.alloc(MAX_CONFIG_BYTES + 1);
+    let bytes = 0;
+    while (bytes < buffer.length) {
+      const count = readSync(descriptor, buffer, bytes, buffer.length - bytes, null);
+      if (count === 0) break;
+      bytes += count;
+    }
+    if (bytes > MAX_CONFIG_BYTES) throw new Error();
+    return JSON.parse(buffer.toString('utf8', 0, bytes));
+  } catch {
+    // Filesystem and JSON errors may contain paths or configuration values.
+    throw new Error('Configuration must be a small private file with mode 0600 and valid JSON');
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}
+
+export function loadConfiguration(env = process.env) {
+  const path = selectEnvironmentValue(env, 'ABOT_SOCKET_CONFIG', 'SOCKET_V2_CONFIG');
+  if (!path) throw new Error('Set ABOT_SOCKET_CONFIG to a private JSON configuration file');
+  const config = validateConfiguration(readPrivateConfiguration(path));
+  const delivery = config.notifications.delivery;
+  if (delivery.type === 'fcm') {
+    delivery.serviceAccountFile = resolve(dirname(resolve(path)), delivery.serviceAccountFile);
+  }
+  return { ...config, stateDirectory: resolve(dirname(resolve(path)), config.stateDirectory) };
+}

package/src/deployment/deployment-command.mjs

@@ -0,0 +1,42 @@
+import { realpathSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { loadConfiguration } from '../config/config.mjs';
+import { writeDeploymentPlan } from './deployment-plan.mjs';
+
+const flags = new Map([['--output', 'output'], ['--proxy', 'proxy'], ['--user', 'username'],
+  ['--certificate', 'certificatePath'], ['--private-key', 'keyPath']]);
+
+export function parseDeploymentArguments(args) {
+  const result = {};
+  for (let i = 0; i < args.length; i += 2) {
+    const name = flags.get(args[i]);
+    const value = args[i + 1];
+    if (!name || Object.hasOwn(result, name) || !value || value.startsWith('--')) {
+      throw new Error('Invalid deployment options');
+    }
+    result[name] = value;
+  }
+  if (!result.output || !result.proxy) throw new Error('Deployment requires output and proxy selection');
+  result.output = resolve(result.output);
+  return result;
+}
+
+export function deploymentRuntimePaths() {
+  return { nodePath: realpathSync(process.execPath),
+    entryPath: fileURLToPath(new URL('../../bin/abot-socket.mjs', import.meta.url)) };
+}
+
+export function prepareDeployment(args, { env, out, platform = process.platform, username = userInfo().username }) {
+  const options = parseDeploymentArguments(args);
+  if (options.username && options.username !== username) {
+    throw new Error('Generate deployment files as the installation owner');
+  }
+  const config = loadConfiguration(env);
+  const output = writeDeploymentPlan({ ...options, ...deploymentRuntimePaths(), config,
+    configPath: resolve(env.ABOT_SOCKET_CONFIG || env.SOCKET_V2_CONFIG), platform, username });
+  out(`Deployment files prepared in ${JSON.stringify(options.output)}. Review the instructions before applying them.`);
+  out('No service, certificate, proxy configuration or package was installed.');
+  return output;
+}

package/src/deployment/deployment-input.mjs

@@ -0,0 +1,76 @@
+import { posix } from 'node:path';
+import { validateConfiguration } from '../config/config-validation.mjs';
+
+function requireLinuxPlatform(platform) {
+  if (platform !== 'linux') throw new Error('Deployment plans target Linux with systemd only');
+}
+
+function requireServiceUsername(username) {
+  if (typeof username !== 'string' || !/^[a-z_][a-z0-9_-]{0,31}$/.test(username)) {
+    throw new Error('Choose an unprivileged Linux service username');
+  }
+  if (username === 'root') throw new Error('The relay service must not run as root');
+  return username;
+}
+
+function requireDeploymentPath(value, label) {
+  // Spaces and percent signs are handled by each target syntax. Other shell,
+  // proxy-variable and control characters are deliberately unsupported.
+  if (typeof value !== 'string' || value.length > 4096 ||
+      !/^\/[A-Za-z0-9_./ %+-]+$/.test(value) || value === '/' ||
+      posix.normalize(value) !== value || value.endsWith('/')) {
+    throw new Error(`${label} requires an absolute normalized path containing letters, numbers, spaces, . _ - + or %`);
+  }
+  return value;
+}
+
+function requireProxyHost(origin) {
+  const labels = origin.hostname.split('.');
+  if (origin.hostname.length > 253 || labels.length < 2 ||
+      labels.some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))) {
+    throw new Error('HTTPS deployment requires a canonical DNS hostname');
+  }
+  if (labels.every((label) => /^\d+$/.test(label))) {
+    throw new Error('HTTPS deployment requires a DNS hostname, not an IP address');
+  }
+}
+
+function requireHttpsListenerPort(origin, relayPort) {
+  const port = origin.port ? Number(origin.port) : 443;
+  if (port < 1 || port > 65535) throw new Error('HTTPS requires a valid listener port');
+  if (port === relayPort) throw new Error('HTTPS and the private relay require different listener ports');
+  return port;
+}
+
+function requirePersistentServicePath(path) {
+  const temporaryRoots = ['/tmp', '/var/tmp', '/private/tmp', '/private/var/tmp'];
+  if (temporaryRoots.some((root) => path === root || path.startsWith(`${root}/`))) {
+    throw new Error('The system service requires persistent paths outside temporary storage');
+  }
+}
+
+export function validateDeploymentInput(options) {
+  requireLinuxPlatform(options.platform ?? 'linux');
+  const config = validateConfiguration(options.config);
+  const origin = new URL(config.publicOrigin);
+  requireProxyHost(origin);
+  const proxy = options.proxy ?? 'nginx';
+  if (!['nginx', 'apache', 'none'].includes(proxy)) throw new Error('Choose nginx, apache or none for the HTTPS plan');
+  const configPath = requireDeploymentPath(options.configPath, 'Configuration');
+  const statePath = requireDeploymentPath(posix.resolve(posix.dirname(configPath), config.stateDirectory), 'State directory');
+  const nodePath = requireDeploymentPath(options.nodePath, 'Node executable');
+  const entryPath = requireDeploymentPath(options.entryPath, 'Installed command');
+  for (const path of [configPath, statePath, nodePath, entryPath]) requirePersistentServicePath(path);
+  if (entryPath.includes('/_npx/')) throw new Error('Install the package persistently before preparing a service');
+  return {
+    config, configPath, statePath, nodePath, entryPath, proxy,
+    username: requireServiceUsername(options.username),
+    certificatePath: proxy === 'none' ? undefined : requireDeploymentPath(options.certificatePath, 'TLS certificate'),
+    keyPath: proxy === 'none' ? undefined : requireDeploymentPath(options.keyPath, 'TLS private key'),
+    hostname: origin.hostname, authority: origin.host,
+    httpsPort: requireHttpsListenerPort(origin, config.port),
+  };
+}
+
+export const systemdQuoted = (value) => `"${value.replaceAll('%', '%%')}"`;
+export const proxyQuoted = (value) => `"${value}"`;

package/src/deployment/deployment-plan.mjs

@@ -0,0 +1,62 @@
+import * as fs from 'node:fs';
+import { join, resolve } from 'node:path';
+import { validateDeploymentInput } from './deployment-input.mjs';
+import { deploymentCommands, renderApacheProxy, renderNginxProxy, renderSystemdService } from './deployment-templates.mjs';
+
+export function renderDeploymentPlan(options) {
+  const input = validateDeploymentInput(options);
+  const notes = [
+    'This is a reviewable Linux deployment plan. No service, proxy, certificate or system setting has been changed.',
+    'Run the listed commands manually from the generated directory, one at a time; stop if any command fails.',
+    'Inspect existing destination files before copying; these sample commands are for a new installation, not an automatic update.',
+    `The existing unprivileged service user must be ${input.username} and must own the private configuration and state directory.`,
+    'The service user needs execute/read access to the installed Node and package paths. Do not use an npx cache path.',
+    'State must already exist with mode 0700, and its database/configuration files must remain 0600. Persistent writes are limited to that directory.',
+    'TLS certificate/key files, DNS and firewall access must be configured separately. This plan never requests or copies a private key.',
+    'Use a local direct HTTPS proxy. CDN or additional proxy chains require a separately reviewed trusted-client-IP policy.',
+    'Keep request bodies, pairing details and Authorization headers out of proxy logs; review inherited logging settings.',
+    'Regenerate the plan if the Node executable, package installation or private configuration location changes.',
+    'After service and HTTPS checks pass, run the pairing command for fresh credentials; these files contain no pairing code.',
+  ];
+  if (input.proxy === 'apache') notes.push(
+    'The Apache command paths target Debian/Ubuntu. Other distributions require their local module/site and service commands.',
+    'Apache requires version 2.4.47+ and an existing Listen directive for the HTTPS port; do not add a duplicate listener.',
+  );
+  if (input.proxy === 'none') notes.push(
+    'No proxy configuration was generated. Your existing HTTPS proxy must satisfy the documented Host, trusted-IP and WebSocket forwarding contract.',
+  );
+  const commands = deploymentCommands(input.proxy);
+  const files = {
+    'abot-socket.service': renderSystemdService(input),
+    'DEPLOYMENT.txt': [...notes, '', 'Review and run individually:', ...commands, ''].join('\n'),
+  };
+  if (input.proxy === 'nginx') files['nginx.conf'] = renderNginxProxy(input);
+  if (input.proxy === 'apache') files['apache.conf'] = renderApacheProxy(input);
+  return { files, notes, commands };
+}
+
+/** Only writes a new operator-selected directory. Never executes plan commands. */
+export function writeDeploymentPlan({ output, ...options }, io = fs) {
+  if (typeof output !== 'string' || !output.trim()) throw new Error('Choose a new deployment output directory');
+  const plan = renderDeploymentPlan(options);
+  const directory = resolve(output);
+  io.mkdirSync(directory, { mode: 0o700 });
+  const created = [];
+  try {
+    for (const [name, content] of Object.entries(plan.files)) {
+      const path = join(directory, name);
+      const descriptor = io.openSync(path, 'wx', 0o600);
+      created.push(path);
+      try { io.writeFileSync(descriptor, content); } finally { io.closeSync(descriptor); }
+    }
+  } catch (error) {
+    const failures = [];
+    for (const path of created.reverse()) {
+      try { io.unlinkSync(path); } catch (failure) { failures.push(failure); }
+    }
+    try { io.rmdirSync(directory); } catch (failure) { failures.push(failure); }
+    if (failures.length) throw new AggregateError([error, ...failures], 'Deployment write failed and cleanup was incomplete');
+    throw error;
+  }
+  return { directory, ...plan };
+}

package/src/deployment/deployment-templates.mjs

@@ -0,0 +1,109 @@
+import { posix } from 'node:path';
+import { proxyQuoted, systemdQuoted } from './deployment-input.mjs';
+
+export function renderSystemdService(input) {
+  return `[Unit]
+Description=ABot Socket relay
+After=network.target
+
+[Service]
+Type=simple
+User=${input.username}
+WorkingDirectory=${systemdQuoted(posix.dirname(input.configPath))}
+ExecStart=${systemdQuoted(input.nodePath)} ${systemdQuoted(input.entryPath)} start --config ${systemdQuoted(input.configPath)}
+Restart=on-failure
+RestartSec=5s
+UMask=0077
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ReadWritePaths=${systemdQuoted(input.statePath)}
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+export function renderNginxProxy(input) {
+  return `# Include inside nginx's http context. Existing TLS files are required.
+# Review global real_ip/CDN configuration before using this direct-proxy plan.
+server {
+    listen ${input.httpsPort} ssl;
+    server_name ${input.hostname};
+    ssl_certificate ${proxyQuoted(input.certificatePath)};
+    ssl_certificate_key ${proxyQuoted(input.keyPath)};
+    ssl_protocols TLSv1.2 TLSv1.3;
+    client_max_body_size 4k;
+    client_body_timeout 15s;
+    access_log off;
+
+    location / {
+        proxy_pass http://127.0.0.1:${input.config.port};
+        proxy_http_version 1.1;
+        # Preserve the real authority, including any explicit port. The relay
+        # rejects an unknown Host; never replace it with a configured constant.
+        proxy_set_header Host $http_host;
+        proxy_set_header Origin $http_origin;
+        proxy_set_header Authorization $http_authorization;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Socket-Client-IP $remote_addr;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_connect_timeout 5s;
+        proxy_read_timeout 90s;
+        proxy_send_timeout 90s;
+        proxy_buffering off;
+    }
+}
+`;
+}
+
+export function renderApacheProxy(input) {
+  return `# Apache 2.4.47+; enable ssl, headers, proxy and proxy_http modules.
+# Add a matching Listen directive only if this HTTPS port is not already active.
+# This direct-proxy plan uses the actual connection peer, not forwarded headers.
+<VirtualHost *:${input.httpsPort}>
+    ServerName ${input.authority}
+    SSLEngine on
+    SSLCertificateFile ${proxyQuoted(input.certificatePath)}
+    SSLCertificateKeyFile ${proxyQuoted(input.keyPath)}
+    SSLProtocol -all +TLSv1.2 +TLSv1.3
+    ProxyRequests Off
+    ProxyPreserveHost On
+    ProxyTimeout 90
+    LimitRequestBody 4096
+
+    RequestHeader unset X-Forwarded-Proto
+    RequestHeader set X-Forwarded-Proto "https"
+    RequestHeader unset X-Socket-Client-IP
+    RequestHeader set X-Socket-Client-IP "expr=%{CONN_REMOTE_ADDR}"
+    # Host, Authorization and Origin are forwarded unchanged. Unknown Host
+    # values reach the relay unchanged and are rejected by its authority check.
+    ProxyPass "/" "http://127.0.0.1:${input.config.port}/" upgrade=websocket connectiontimeout=5 timeout=90
+    ProxyPassReverse "/" "http://127.0.0.1:${input.config.port}/"
+</VirtualHost>
+`;
+}
+
+export function deploymentCommands(proxy) {
+  const commands = [
+    'sudo install -m 0644 -- ./abot-socket.service /etc/systemd/system/abot-socket.service',
+    'sudo systemctl daemon-reload',
+    'sudo systemctl enable --now abot-socket.service',
+  ];
+  if (proxy === 'none') return commands;
+  if (proxy === 'nginx') return [...commands,
+    'sudo install -m 0644 -- ./nginx.conf /etc/nginx/conf.d/abot-socket.conf',
+    'sudo nginx -t',
+    'sudo systemctl reload nginx',
+  ];
+  return [...commands,
+    'sudo install -m 0644 -- ./apache.conf /etc/apache2/sites-available/abot-socket.conf',
+    'sudo a2enmod ssl headers proxy proxy_http',
+    'sudo a2ensite abot-socket.conf',
+    'sudo apachectl configtest',
+    'sudo systemctl reload apache2',
+  ];
+}

package/src/main.mjs

@@ -0,0 +1,26 @@
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { loadConfiguration } from './config/config.mjs';
+import { createSocketServer } from './transport/server.mjs';
+
+export async function startConfiguredServer(env = process.env) {
+  const config = loadConfiguration(env);
+  const app = createSocketServer(config);
+  try { await app.listen(config.port); }
+  catch (error) { await app.close(); throw error; }
+  return app;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  try {
+    const app = await startConfiguredServer();
+    console.log('ABot Socket listening on loopback behind the configured HTTPS reverse proxy.');
+    const stop = () => { void app.close(); };
+    process.once('SIGTERM', stop);
+    process.once('SIGINT', stop);
+  } catch {
+    // Configuration/provider errors can contain secrets; never print them here.
+    console.error('ABot Socket could not start. Check private configuration, state permissions and listener availability.');
+    process.exitCode = 1;
+  }
+}

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

@@ -0,0 +1,48 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from 'node:fs';
+import { createPrivateKey } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+
+const MAX_CREDENTIAL_BYTES = 32 * 1024;
+
+function isPrivateCredentialFile(stat) {
+  if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_CREDENTIAL_BYTES) return false;
+  if ((stat.mode & 0o7777) !== 0o600) return false;
+  return typeof process.getuid === 'function' && stat.uid === process.getuid();
+}
+
+function parseServiceAccount(json) {
+  if (!json || json.type !== 'service_account') throw new Error();
+  if (typeof json.project_id !== 'string' || !/^[a-z][a-z0-9-]{4,61}[a-z0-9]$/.test(json.project_id)) throw new Error();
+  if (typeof json.client_email !== 'string' || json.client_email.length > 254 ||
+      !/^[A-Za-z0-9._-]+@[a-z0-9-]+\.iam\.gserviceaccount\.com$/.test(json.client_email)) throw new Error();
+  if (typeof json.private_key !== 'string' || json.private_key.length > 16 * 1024) throw new Error();
+  const key = createPrivateKey(json.private_key);
+  if (key.asymmetricKeyType !== 'rsa' || key.asymmetricKeyDetails?.modulusLength < 2048) throw new Error();
+  return { projectId: json.project_id, clientEmail: json.client_email, key };
+}
+
+/** Never use token_uri or any URL from a credential file as a network destination. */
+export function loadFcmServiceAccount(path) {
+  let descriptor;
+  try {
+    if (!isAbsolute(path)) throw new Error();
+    descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const before = fstatSync(descriptor);
+    if (!isPrivateCredentialFile(before)) throw new Error();
+    const buffer = Buffer.alloc(MAX_CREDENTIAL_BYTES + 1);
+    let bytes = 0;
+    while (bytes < buffer.length) {
+      const count = readSync(descriptor, buffer, bytes, buffer.length - bytes, null);
+      if (count === 0) break;
+      bytes += count;
+    }
+    if (bytes > MAX_CREDENTIAL_BYTES) throw new Error();
+    const after = fstatSync(descriptor);
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || bytes !== before.size) throw new Error();
+    return parseServiceAccount(JSON.parse(buffer.toString('utf8', 0, bytes)));
+  } catch {
+    throw new Error('FCM credentials require a valid private service-account file owned by this user with mode 0600');
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+}

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

@@ -0,0 +1,100 @@
+import { sign } from 'node:crypto';
+import { loadFcmServiceAccount } from './notification-delivery-credentials.mjs';
+import { postNotificationRequest } from './notification-delivery-http.mjs';
+import { isFcmDeviceToken, notificationEnvelope } from './notification-delivery-payload.mjs';
+
+const OAUTH_URL = 'https://oauth2.googleapis.com/token';
+const FCM_SCOPE = 'https://www.googleapis.com/auth/firebase.messaging';
+const encode = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
+
+function createAssertion(account, now) {
+  const iat = Math.floor(now / 1000);
+  const body = `${encode({ alg: 'RS256', typ: 'JWT' })}.${encode({
+    iss: account.clientEmail, scope: FCM_SCOPE, aud: OAUTH_URL, iat, exp: iat + 3600,
+  })}`;
+  return `${body}.${sign('RSA-SHA256', Buffer.from(body), account.key).toString('base64url')}`;
+}
+
+function hasInvalidDeviceResponse(response) {
+  if (response.status !== 404) return false;
+  const details = response.json?.error?.details;
+  if (!Array.isArray(details)) return false;
+  return details.some((detail) => detail?.['@type'] === 'type.googleapis.com/google.firebase.fcm.v1.FcmError' &&
+    detail.errorCode === 'UNREGISTERED');
+}
+
+function hasExpiredEnvelope(envelope, now) {
+  const expiry = Number(envelope?.apns?.headers?.['apns-expiration']);
+  return Number.isSafeInteger(expiry) && expiry > 0 && expiry <= Math.floor(now / 1000);
+}
+
+function envelopeForDispatch(envelope, now) {
+  if (!envelope.android) return envelope;
+  const expiry = Number(envelope.apns?.headers?.['apns-expiration']);
+  if (!Number.isSafeInteger(expiry) || expiry <= 0) return envelope;
+  return { ...envelope, android: { ...envelope.android,
+    ttl: `${Math.max(0, expiry - Math.floor(now / 1000))}s` } };
+}
+
+/** Trusted gateway/socket code supplies a bounded, projected envelope. */
+export function createFcmProvider(config, dependencies = {}) {
+  const account = loadFcmServiceAccount(config.serviceAccountFile);
+  const now = dependencies.now ?? Date.now;
+  const endpoint = `https://fcm.googleapis.com/v1/projects/${account.projectId}/messages:send`;
+  let cachedToken;
+  let tokenExpiresAt = 0;
+
+  async function authorization(signal) {
+    if (cachedToken && tokenExpiresAt > now() + 60_000) return cachedToken;
+    const response = await postNotificationRequest(OAUTH_URL, {
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+        assertion: createAssertion(account, now()) }).toString(),
+    }, signal, dependencies);
+    const token = response.json?.access_token;
+    const duration = response.json?.expires_in;
+    if (!response.ok || typeof token !== 'string' || !/^[\x21-\x7e]{1,8192}$/.test(token) ||
+        !Number.isSafeInteger(duration) || duration < 1 || duration > 3600) throw new Error();
+    cachedToken = token;
+    tokenExpiresAt = now() + duration * 1000;
+    return token;
+  }
+
+  return Object.freeze({
+    async sendEnvelope(deviceToken, envelope, signal) {
+      if (!isFcmDeviceToken(deviceToken)) return { status: 'invalid' };
+      try {
+        if (!envelope || typeof envelope !== 'object' || Buffer.byteLength(JSON.stringify(envelope), 'utf8') > 4096) {
+          return { status: 'discarded' };
+        }
+        if (hasExpiredEnvelope(envelope, now())) return { status: 'discarded' };
+        const token = await authorization(signal);
+        if (signal?.aborted) return { status: 'retry' };
+        if (hasExpiredEnvelope(envelope, now())) return { status: 'discarded' };
+        const response = await postNotificationRequest(endpoint, {
+          headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ message: { ...envelopeForDispatch(envelope, now()), token: deviceToken } }),
+        }, signal, dependencies);
+        if (response.status === 401) { cachedToken = undefined; tokenExpiresAt = 0; }
+        if (hasInvalidDeviceResponse(response)) return { status: 'invalid' };
+        if (response.ok && typeof response.json?.name === 'string' && response.json.name.startsWith('projects/')) {
+          return { status: 'delivered' };
+        }
+        return { status: 'retry' };
+      } catch { return { status: 'retry' }; }
+    },
+  });
+}
+
+export function createFcmNotificationDelivery(config, dependencies = {}) {
+  const provider = createFcmProvider(config, dependencies);
+  const now = dependencies.now ?? Date.now;
+  return Object.freeze({ mode: 'fcm', configured: true,
+    async send({ registration, notification, badge }, signal) {
+      if (registration?.provider !== 'fcm') return { status: 'invalid' };
+      const envelope = notificationEnvelope(notification, badge, now());
+      if (!envelope) return { status: 'discarded' };
+      return provider.sendEnvelope(registration.token, envelope, signal);
+    },
+  });
+}

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

@@ -0,0 +1,36 @@
+import { postNotificationRequest } from './notification-delivery-http.mjs';
+import { notificationEnvelope } from './notification-delivery-payload.mjs';
+import { validatedNotificationPreview } from './notification-preview-crypto.mjs';
+
+function hasGatewayRegistration(registration) {
+  if (registration?.provider !== 'gateway') return false;
+  if (!/^[A-Za-z0-9_-]{16,128}$/.test(registration.endpointId ?? '')) return false;
+  return /^[A-Za-z0-9_-]{32,512}$/.test(registration.sendToken ?? '');
+}
+
+function hasInvalidGatewayRecipient(response) {
+  if (response.status === 401 && response.json?.error === 'unauthorized') return true;
+  return response.status === 410 && response.json?.error === 'endpoint_unavailable';
+}
+
+export function createGatewayNotificationDelivery(config, dependencies = {}) {
+  const now = dependencies.now ?? Date.now;
+  const endpoint = `${config.gatewayOrigin}/v1/deliver`;
+  return Object.freeze({ mode: 'gateway', configured: true,
+    async send({ registration, notification, badge }, signal) {
+      if (!hasGatewayRegistration(registration)) return { status: 'invalid' };
+      if (!notificationEnvelope(notification, badge, now())) return { status: 'discarded' };
+      const preview = validatedNotificationPreview(notification.preview, notification, now());
+      try {
+        const response = await postNotificationRequest(endpoint, {
+          headers: { Authorization: `Bearer ${registration.sendToken}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ endpointId: registration.endpointId, notificationId: notification.id,
+            kind: notification.kind, expiresAt: notification.expiresAt, badge, ...(preview ? { preview } : {}) }),
+        }, signal, dependencies);
+        if (hasInvalidGatewayRecipient(response)) return { status: 'invalid' };
+        if (response.ok && response.json?.ok === true) return { status: 'delivered' };
+        return { status: 'retry' };
+      } catch { return { status: 'retry' }; }
+    },
+  });
+}

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

@@ -0,0 +1,53 @@
+const MAX_RESPONSE_BYTES = 16 * 1024;
+
+function abortFailure() { return new Error('Notification delivery interrupted'); }
+
+function waitForResponse(promise, signal) {
+  if (signal.aborted) return Promise.reject(abortFailure());
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(abortFailure());
+    signal.addEventListener('abort', abort, { once: true });
+    Promise.resolve(promise).then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+  });
+}
+
+async function readBoundedJson(response, signal) {
+  const declared = Number(response.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) throw new Error();
+  if (!response.body) return null;
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { value, done } = await waitForResponse(reader.read(), signal);
+      if (done) break;
+      size += value.byteLength;
+      if (size > MAX_RESPONSE_BYTES) throw new Error();
+      chunks.push(Buffer.from(value));
+    }
+    if (!size) return null;
+    return JSON.parse(Buffer.concat(chunks, size).toString('utf8'));
+  } finally {
+    void reader.cancel().catch(() => {});
+  }
+}
+
+/** Destination is constructed by an adapter, never from a mobile registration. */
+export async function postNotificationRequest(url, init, signal,
+  { fetchImpl = globalThis.fetch, timeoutMs = 8_000 } = {}) {
+  const timeout = new AbortController();
+  const combined = signal ? AbortSignal.any([signal, timeout.signal]) : timeout.signal;
+  const deadline = setTimeout(() => timeout.abort(), Math.min(Math.max(timeoutMs, 1), 10_000));
+  try {
+    if (combined.aborted) throw abortFailure();
+    const response = await waitForResponse(fetchImpl(url, { ...init,
+      method: 'POST', redirect: 'error', signal: combined }), combined);
+    if (response.status >= 300 && response.status < 400) throw new Error();
+    const json = await readBoundedJson(response, combined);
+    return { status: response.status, ok: response.ok, json };
+  } catch {
+    timeout.abort();
+    throw new Error('Notification provider unavailable');
+  } finally { clearTimeout(deadline); }
+}