@abot-ai/socket 0.0.0-stage → 0.1.0

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); }
+}

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(); }
+}