@abot-ai/socket 0.0.0-stage → 0.1.0

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

package/src/notifications/notification-preview-crypto.mjs

@@ -0,0 +1,42 @@
+import { createCipheriv, randomBytes } from 'node:crypto';
+import { MAX_PREVIEW_BYTES } from './notification-preview-text.mjs';
+
+const MAX_AGE_MS = 7 * 86_400_000;
+const ENVELOPE_KEYS = ['v', 'keyId', 'nonce', 'ciphertext', 'expiresAt'];
+export function previewBase64Bytes(value, size, maximum = size) {
+  if (typeof value !== 'string' || value.length > Math.ceil(maximum * 4 / 3) || !/^[A-Za-z0-9_-]+$/.test(value)) return null;
+  const bytes = Buffer.from(value, 'base64url');
+  if (bytes.length < size || bytes.length > maximum || bytes.toString('base64url') !== value) return null;
+  return bytes;
+}
+
+export function hasPreviewKey(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value) &&
+    Object.keys(value).length === 2 && Object.keys(value).every(key => ['keyId', 'key'].includes(key)) &&
+    previewBase64Bytes(value.keyId, 16) && previewBase64Bytes(value.key, 32));
+}
+
+export function previewAdditionalData(keyId, notificationId, expiresAt) {
+  return Buffer.from(`ABot push preview v1\n${keyId}\n${notificationId}\n${expiresAt}`, 'utf8');
+}
+
+export function validatedNotificationPreview(value, notification, now) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  if (Object.keys(value).length !== ENVELOPE_KEYS.length || Object.keys(value).some(key => !ENVELOPE_KEYS.includes(key))) return null;
+  if (value.v !== 1 || notification?.kind !== 'completed') return null;
+  if (!Number.isSafeInteger(value.expiresAt) || value.expiresAt !== notification.expiresAt ||
+      value.expiresAt <= now || value.expiresAt > now + MAX_AGE_MS) return null;
+  if (!previewBase64Bytes(value.keyId, 16) || !previewBase64Bytes(value.nonce, 12) ||
+      !previewBase64Bytes(value.ciphertext, 17, MAX_PREVIEW_BYTES + 16)) return null;
+  return { v: 1, keyId: value.keyId, nonce: value.nonce, ciphertext: value.ciphertext, expiresAt: value.expiresAt };
+}
+
+export function sealNotificationPreview(keyId, key, notification, text, nonce = randomBytes(12)) {
+  if (!previewBase64Bytes(keyId, 16) || key.length !== 32 || nonce.length !== 12 || typeof text !== 'string' ||
+      !text || Buffer.byteLength(text, 'utf8') > MAX_PREVIEW_BYTES) throw new Error('Invalid notification preview');
+  const cipher = createCipheriv('aes-256-gcm', key, nonce);
+  cipher.setAAD(previewAdditionalData(keyId, notification.id, notification.expiresAt));
+  const ciphertext = Buffer.concat([cipher.update(text, 'utf8'), cipher.final(), cipher.getAuthTag()]);
+  return { v: 1, keyId, nonce: nonce.toString('base64url'), ciphertext: ciphertext.toString('base64url'),
+    expiresAt: notification.expiresAt };
+}

package/src/notifications/notification-preview-schema.mjs

@@ -0,0 +1,7 @@
+export const NOTIFICATION_PREVIEW_SCHEMA = `
+  CREATE TABLE notification_preview_keys (
+    device_id TEXT PRIMARY KEY REFERENCES devices(id) ON DELETE CASCADE,
+    key_id TEXT NOT NULL, key_bytes BLOB NOT NULL CHECK(length(key_bytes) = 32)
+  ) STRICT;
+  ALTER TABLE notification_outbox ADD COLUMN encrypted_preview TEXT;
+`;

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

@@ -0,0 +1,63 @@
+import { notificationPreviewText } from './notification-preview-text.mjs';
+import { sealNotificationPreview } from './notification-preview-crypto.mjs';
+
+/** Keys stay device-scoped; only ciphertext enters the delivery queue. */
+export class NotificationPreviewStore {
+  constructor({ database, now = Date.now }) { this.database = database; this.now = now; }
+
+  status(deviceId) {
+    const row = this.database.prepare(`SELECT p.key_id FROM notification_preview_keys p
+      JOIN devices d ON d.id = p.device_id JOIN notification_registrations r ON r.device_id = p.device_id
+      WHERE p.device_id = ? AND d.expires_at > ?`).get(deviceId, this.now());
+    return { supported: true, enabled: Boolean(row), keyId: row?.key_id ?? null };
+  }
+
+  enable(deviceId, value) {
+    return this.database.transaction(() => {
+      const registered = this.database.prepare(`SELECT d.id FROM devices d
+        JOIN notification_registrations r ON r.device_id = d.id WHERE d.id = ? AND d.expires_at > ?`)
+        .get(deviceId, this.now());
+      if (!registered) return false;
+      this.database.prepare(`INSERT INTO notification_preview_keys(device_id, key_id, key_bytes) VALUES (?, ?, ?)
+        ON CONFLICT(device_id) DO UPDATE SET key_id = excluded.key_id, key_bytes = excluded.key_bytes`)
+        .run(deviceId, value.keyId, Buffer.from(value.key, 'base64url'));
+      this.clearQueued(deviceId);
+      return true;
+    });
+  }
+
+  clearQueued(deviceId) {
+    this.database.prepare(`UPDATE notification_outbox SET encrypted_preview = NULL WHERE notification_id IN
+      (SELECT id FROM notifications WHERE device_id = ?)`).run(deviceId);
+  }
+
+  removeKey(deviceId) {
+    this.database.prepare('DELETE FROM notification_preview_keys WHERE device_id = ?').run(deviceId);
+    this.clearQueued(deviceId);
+  }
+
+  disable(deviceId) { this.database.transaction(() => this.removeKey(deviceId)); }
+
+  attach(item, output) {
+    if (item.kind !== 'completed') return;
+    try {
+      const key = this.database.prepare(`SELECT p.key_id, p.key_bytes FROM notification_preview_keys p
+        JOIN devices d ON d.id = p.device_id JOIN notification_registrations r ON r.device_id = p.device_id
+        WHERE p.device_id = ? AND d.expires_at > ?`).get(item.deviceId, this.now());
+      if (!key) return;
+      const text = notificationPreviewText(output);
+      if (!text) return;
+      const preview = sealNotificationPreview(key.key_id, Buffer.from(key.key_bytes), item, text);
+      this.database.prepare(`UPDATE notification_outbox SET encrypted_preview = ? WHERE notification_id = ?
+        AND EXISTS (SELECT 1 FROM notification_preview_keys WHERE device_id = ? AND key_id = ? AND key_bytes = ?)`)
+        .run(JSON.stringify(preview), item.id, item.deviceId, key.key_id, key.key_bytes);
+    } catch { /* The already-durable generic notification remains deliverable. */ }
+  }
+
+  prune() {
+    this.database.prepare(`DELETE FROM notification_preview_keys WHERE NOT EXISTS
+      (SELECT 1 FROM devices WHERE id = device_id AND expires_at > ?) OR NOT EXISTS
+      (SELECT 1 FROM notification_registrations r WHERE r.device_id = notification_preview_keys.device_id)`)
+      .run(this.now());
+  }
+}

package/src/notifications/notification-preview-text.mjs

@@ -0,0 +1,20 @@
+export const MAX_PREVIEW_BYTES = 1024;
+const SOURCE_PREFIX = 8192;
+const UNSAFE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu;
+
+/** A bounded display excerpt, never a transcript or a claim to redact secrets. */
+export function notificationPreviewText(output) {
+  if (typeof output !== 'string') return null;
+  const clean = [...output.slice(0, SOURCE_PREFIX).replace(/\r\n?/gu, '\n').replace(UNSAFE, '')]
+    .filter(char => { const code = char.codePointAt(0); return code < 0xd800 || code > 0xdfff; }).join('').trim();
+  if (!clean) return null;
+  const truncated = output.length > SOURCE_PREFIX || Buffer.byteLength(clean, 'utf8') > MAX_PREVIEW_BYTES;
+  if (!truncated) return clean;
+  let text = ''; let bytes = 0;
+  for (const char of clean) {
+    const length = Buffer.byteLength(char, 'utf8');
+    if (bytes + length > MAX_PREVIEW_BYTES - 3) break;
+    text += char; bytes += length;
+  }
+  return `${text.trimEnd()}…`;
+}

package/src/notifications/notification-projection.mjs

@@ -0,0 +1,20 @@
+export const NOTIFICATION_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+export const APPROVAL_NOTIFICATION_MS = 5 * 60 * 1000;
+
+/** Select only final results and live approval requests, never token/progress text. */
+export function projectNotificationEvent(identity, body, now) {
+  if (body.type === 'completed' || body.type === 'failed') {
+    return { ...identity, kind: body.type, approvalId: '', createdAt: now,
+      expiresAt: now + NOTIFICATION_RETENTION_MS };
+  }
+  if (body.type !== 'event' || body.name !== 'tool.approval.required') return null;
+  if (typeof body.approvalId !== 'string' || !body.approvalId || body.approvalId.length > 512) return null;
+  return { ...identity, kind: 'approval_required', approvalId: body.approvalId,
+    createdAt: now, expiresAt: now + APPROVAL_NOTIFICATION_MS };
+}
+
+export function closesApprovalNotifications(body) {
+  if (body.type === 'completed' || body.type === 'failed') return true;
+  if (body.type !== 'event' || !['tool.approval.granted', 'tool.approval.rejected'].includes(body.name)) return false;
+  return typeof body.approvalId === 'string' && body.approvalId.length > 0 && body.approvalId.length <= 512;
+}

package/src/notifications/notification-schema.mjs

@@ -0,0 +1,22 @@
+/** Metadata only: conversation content and authentication credentials never enter this ledger. */
+export const NOTIFICATION_SCHEMA = `
+  CREATE TABLE notifications (
+    id TEXT PRIMARY KEY, device_id TEXT NOT NULL REFERENCES devices(id) ON DELETE CASCADE,
+    runtime_id TEXT NOT NULL, session_id TEXT NOT NULL, request_id TEXT NOT NULL,
+    kind TEXT NOT NULL CHECK (kind IN ('completed', 'failed', 'approval_required')),
+    approval_id TEXT NOT NULL DEFAULT '', created_at INTEGER NOT NULL,
+    read_at INTEGER, expires_at INTEGER NOT NULL,
+    UNIQUE(device_id, runtime_id, request_id, kind, approval_id)
+  ) STRICT;
+  CREATE INDEX notifications_device_time ON notifications(device_id, created_at DESC, id DESC);
+  CREATE INDEX notifications_expiry ON notifications(expires_at);
+  CREATE TABLE notification_registrations (
+    device_id TEXT PRIMARY KEY REFERENCES devices(id) ON DELETE CASCADE,
+    provider TEXT NOT NULL CHECK (provider IN ('fcm', 'gateway')),
+    registration TEXT NOT NULL, updated_at INTEGER NOT NULL
+  ) STRICT;
+  CREATE TABLE notification_outbox (
+    notification_id TEXT PRIMARY KEY REFERENCES notifications(id) ON DELETE CASCADE,
+    attempts INTEGER NOT NULL DEFAULT 0, next_at INTEGER NOT NULL
+  ) STRICT;
+`;