@abot-ai/socket 0.0.0-stage → 0.2.0

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;
+`;

package/src/notifications/notification-service.mjs

@@ -0,0 +1,147 @@
+import { NotificationStore } from './notification-store.mjs';
+import { NotificationOutbox } from './notification-outbox.mjs';
+import { closesApprovalNotifications, projectNotificationEvent } from './notification-projection.mjs';
+import { notificationInputError } from './notification-input.mjs';
+
+const PRESENCE_MS = 45_000;
+
+/** Notification lifecycle is independent of a selected runtime or a live mobile socket. */
+export class NotificationService {
+  constructor({ database, delivery, now = Date.now, onChanged = () => {} }) {
+    this.store = new NotificationStore({ database, now });
+    this.outbox = new NotificationOutbox({ database, now });
+    this.delivery = delivery;
+    this.now = now;
+    this.onChanged = onChanged;
+    this.presence = new Map();
+    this.closed = false;
+    this.pending = null;
+    this.active = null;
+  }
+
+  changed(deviceId) {
+    try { this.onChanged(deviceId); } catch { /* Invalidation is best effort; HTTP is canonical. */ }
+  }
+
+  observe(identity, body) {
+    let changed = false;
+    if (closesApprovalNotifications(body)) {
+      changed = this.store.closeApprovals(identity, body.type === 'event' ? body.approvalId : undefined);
+      if (this.active?.entry.notification.kind === 'approval_required' &&
+        this.active.entry.deviceId === identity.deviceId &&
+        this.active.entry.notification.runtimeId === identity.runtimeId &&
+        this.active.entry.notification.requestId === identity.requestId) this.active.controller.abort();
+    }
+    const projected = projectNotificationEvent(identity, body, this.now());
+    if (projected) {
+      const registration = this.store.registration(identity.deviceId);
+      const queue = this.delivery.configured && registration?.provider === this.delivery.mode;
+      const item = this.store.record(projected, queue);
+      if (item && queue) this.store.previews.attach(item, body.output);
+      changed = Boolean(item) || changed;
+    }
+    if (changed) this.changed(identity.deviceId);
+  }
+
+  list(deviceId, options) {
+    const registration = this.store.registration(deviceId);
+    return { version: 1, ...this.store.list(deviceId, options),
+      delivery: { mode: this.delivery.mode, configured: this.delivery.configured },
+      registration: { enabled: this.delivery.configured && registration?.provider === this.delivery.mode },
+      preview: this.store.previews.status(deviceId) };
+  }
+
+  markRead(deviceId, ids) {
+    if (this.active?.entry.deviceId === deviceId && ids.includes(this.active.entry.notification.id)) {
+      this.active.controller.abort();
+    }
+    if (this.store.markRead(deviceId, ids)) this.changed(deviceId);
+  }
+
+  updatePresence(deviceId, presence) {
+    if (!presence.foreground) { this.presence.delete(deviceId); return; }
+    this.presence.set(deviceId, { ...presence, expiresAt: this.now() + PRESENCE_MS });
+    // Advisory only: iOS may suspend before a background update is delivered.
+    // Only an explicit read acknowledgement can consume an unseen notification.
+  }
+
+  register(deviceId, registration) {
+    if (!this.delivery.configured || registration.provider !== this.delivery.mode) {
+      throw notificationInputError('push_unavailable', 409);
+    }
+    if (this.active?.entry.deviceId === deviceId) this.active.controller.abort();
+    if (!this.store.register(deviceId, registration)) throw notificationInputError('unauthorized', 401);
+  }
+
+  enablePreview(deviceId, key) {
+    const registration = this.store.registration(deviceId);
+    if (!this.delivery.configured || registration?.provider !== this.delivery.mode) {
+      throw notificationInputError('push_unavailable', 409);
+    }
+    if (this.active?.entry.deviceId === deviceId) this.active.controller.abort();
+    if (!this.store.previews.enable(deviceId, key)) throw notificationInputError('unauthorized', 401);
+  }
+
+  disablePreview(deviceId) {
+    if (this.active?.entry.deviceId === deviceId) this.active.controller.abort();
+    this.store.previews.disable(deviceId);
+  }
+
+  unregister(deviceId) {
+    if (this.active?.entry.deviceId === deviceId) this.active.controller.abort();
+    this.store.unregister(deviceId);
+  }
+
+  revoke(deviceId) {
+    if (this.active?.entry.deviceId === deviceId) this.active.controller.abort();
+    this.presence.delete(deviceId);
+    this.store.forgetDevice(deviceId);
+  }
+
+  start() {
+    if (this.timer || this.closed) return;
+    this.timer = setInterval(() => { void this.tick(); }, 1_000);
+    this.timer.unref();
+  }
+
+  tick() {
+    if (this.closed) return Promise.resolve();
+    if (this.pending) return this.pending;
+    this.pending = this.drain().catch(() => { /* Durable entries remain for a later bounded attempt. */ })
+      .finally(() => { this.pending = null; });
+    return this.pending;
+  }
+
+  async drain() {
+    this.store.prune();
+    for (const [deviceId, presence] of this.presence) {
+      if (presence.expiresAt <= this.now()) this.presence.delete(deviceId);
+    }
+    if (!this.delivery.configured) return;
+    for (let index = 0; index < 10 && !this.closed; index += 1) {
+      const entry = this.outbox.claim(this.delivery.mode);
+      if (!entry) return;
+      if (!this.outbox.canDeliver(entry)) continue;
+      const controller = new AbortController();
+      this.active = { entry, controller };
+      let result;
+      try {
+        result = await this.delivery.send({ registration: entry.registration, notification: entry.notification,
+          badge: this.store.counts(entry.deviceId).unreadCount }, controller.signal);
+      } catch { result = { status: 'retry' }; }
+      this.active = null;
+      if (controller.signal.aborted) { this.outbox.cancel(entry); continue; }
+      const status = ['delivered', 'invalid', 'discarded', 'retry'].includes(result?.status) ? result.status : 'retry';
+      if (status === 'invalid') this.store.unregister(entry.deviceId, entry.registration);
+      this.outbox.finish(entry, status);
+    }
+  }
+
+  async close() {
+    this.closed = true;
+    clearInterval(this.timer);
+    this.active?.controller.abort();
+    await this.pending;
+    this.presence.clear();
+  }
+}

package/src/notifications/notification-store.mjs

@@ -0,0 +1,132 @@
+import { randomUUID } from 'node:crypto';
+import { notificationCursor } from './notification-input.mjs';
+import { NotificationPreviewStore } from './notification-preview-store.mjs';
+
+const MAX_ITEMS_PER_DEVICE = 500;
+const SELECT_ITEM = `id, runtime_id AS runtimeId, session_id AS sessionId,
+  request_id AS requestId, kind, created_at AS createdAt, read_at AS readAt, expires_at AS expiresAt`;
+
+export class NotificationStore {
+  constructor({ database, now = Date.now }) {
+    this.database = database; this.now = now;
+    this.previews = new NotificationPreviewStore({ database, now });
+  }
+
+  hasDevice(deviceId) {
+    return Boolean(this.database.prepare('SELECT id FROM devices WHERE id = ? AND expires_at > ?')
+      .get(deviceId, this.now()));
+  }
+
+  record(event, queueDelivery) {
+    return this.database.transaction(() => {
+      const device = this.database.prepare('SELECT expires_at FROM devices WHERE id = ? AND expires_at > ?')
+        .get(event.deviceId, this.now());
+      if (!device) return null;
+      const item = { id: randomUUID(), ...event, readAt: null,
+        expiresAt: Math.min(event.expiresAt, device.expires_at) };
+      const added = this.database.prepare(`INSERT OR IGNORE INTO notifications
+        (id, device_id, runtime_id, session_id, request_id, kind, approval_id, created_at, read_at, expires_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(item.id, item.deviceId, item.runtimeId,
+        item.sessionId, item.requestId, item.kind, item.approvalId, item.createdAt, item.readAt, item.expiresAt);
+      if (!added.changes) return null;
+      if (queueDelivery) {
+        this.database.prepare('INSERT INTO notification_outbox(notification_id, next_at) VALUES (?, ?)')
+          .run(item.id, this.now());
+      }
+      this.database.prepare(`DELETE FROM notifications WHERE device_id = ? AND id IN (
+        SELECT id FROM notifications WHERE device_id = ? ORDER BY created_at DESC, id DESC LIMIT -1 OFFSET ?)`)
+        .run(item.deviceId, item.deviceId, MAX_ITEMS_PER_DEVICE);
+      return item;
+    });
+  }
+
+  list(deviceId, { limit = 50, before = null } = {}) {
+    this.prune();
+    const condition = before ? 'AND (created_at < ? OR (created_at = ? AND id < ?))' : '';
+    const parameters = before ? [deviceId, before.createdAt, before.createdAt, before.id, limit + 1] : [deviceId, limit + 1];
+    const rows = this.database.prepare(`SELECT ${SELECT_ITEM} FROM notifications WHERE device_id = ?
+      ${condition} ORDER BY created_at DESC, id DESC LIMIT ?`).all(...parameters);
+    const items = rows.slice(0, limit).map(row => ({ ...row }));
+    const counts = this.counts(deviceId);
+    return { items, nextCursor: rows.length > limit ? notificationCursor(items.at(-1)) : null, ...counts };
+  }
+
+  counts(deviceId) {
+    const rows = this.database.prepare(`SELECT runtime_id, session_id, COUNT(*) AS count FROM notifications
+      WHERE device_id = ? AND read_at IS NULL AND expires_at > ? GROUP BY runtime_id, session_id`).all(deviceId, this.now());
+    const unreadByRuntime = Object.create(null);
+    const unreadBySession = Object.create(null);
+    let unreadCount = 0;
+    for (const row of rows) {
+      unreadCount += row.count;
+      unreadByRuntime[row.runtime_id] = (unreadByRuntime[row.runtime_id] ?? 0) + row.count;
+      unreadBySession[row.runtime_id] ??= Object.create(null);
+      unreadBySession[row.runtime_id][row.session_id] = row.count;
+    }
+    return { unreadCount, unreadByRuntime, unreadBySession };
+  }
+
+  markRead(deviceId, ids) {
+    return this.database.transaction(() => {
+      const update = this.database.prepare('UPDATE notifications SET read_at = ? WHERE device_id = ? AND id = ? AND read_at IS NULL');
+      let changes = 0;
+      for (const id of ids) changes += update.run(this.now(), deviceId, id).changes;
+      this.removeReadDeliveries();
+      return changes > 0;
+    });
+  }
+
+  closeApprovals(identity, approvalId) {
+    const conditions = approvalId ? 'AND approval_id = ?' : '';
+    const params = [this.now(), identity.deviceId, identity.runtimeId, identity.requestId];
+    if (approvalId) params.push(approvalId);
+    const changed = this.database.prepare(`UPDATE notifications SET read_at = COALESCE(read_at, ?)
+      WHERE device_id = ? AND runtime_id = ? AND request_id = ? AND kind = 'approval_required' ${conditions}`)
+      .run(...params).changes;
+    this.removeReadDeliveries();
+    return changed > 0;
+  }
+
+  registration(deviceId) {
+    const row = this.database.prepare('SELECT registration FROM notification_registrations WHERE device_id = ?').get(deviceId);
+    return row ? JSON.parse(row.registration) : null;
+  }
+
+  register(deviceId, registration) {
+    if (!this.hasDevice(deviceId)) return false;
+    this.database.prepare(`INSERT INTO notification_registrations(device_id, provider, registration, updated_at)
+      VALUES (?, ?, ?, ?) ON CONFLICT(device_id) DO UPDATE SET provider = excluded.provider,
+      registration = excluded.registration, updated_at = excluded.updated_at`)
+      .run(deviceId, registration.provider, JSON.stringify(registration), this.now());
+    return true;
+  }
+
+  unregister(deviceId, expectedRegistration) {
+    this.database.transaction(() => {
+      if (expectedRegistration && JSON.stringify(this.registration(deviceId)) !== JSON.stringify(expectedRegistration)) return;
+      this.previews.removeKey(deviceId);
+      this.database.prepare('DELETE FROM notification_registrations WHERE device_id = ?').run(deviceId);
+      this.database.prepare(`DELETE FROM notification_outbox WHERE notification_id IN
+        (SELECT id FROM notifications WHERE device_id = ?)` ).run(deviceId);
+    });
+  }
+
+  removeReadDeliveries() {
+    this.database.prepare(`DELETE FROM notification_outbox WHERE notification_id IN
+      (SELECT id FROM notifications WHERE read_at IS NOT NULL)` ).run();
+  }
+
+  prune() {
+    this.database.prepare('DELETE FROM notifications WHERE expires_at <= ?').run(this.now());
+    this.database.prepare('DELETE FROM notifications WHERE NOT EXISTS (SELECT 1 FROM devices WHERE devices.id = notifications.device_id)').run();
+    this.database.prepare('DELETE FROM notification_registrations WHERE NOT EXISTS (SELECT 1 FROM devices WHERE devices.id = notification_registrations.device_id)').run();
+    this.database.prepare('DELETE FROM notification_registrations WHERE device_id IN (SELECT id FROM devices WHERE expires_at <= ?)').run(this.now());
+    this.database.prepare('DELETE FROM notifications WHERE device_id IN (SELECT id FROM devices WHERE expires_at <= ?)').run(this.now());
+    this.previews.prune();
+  }
+
+  forgetDevice(deviceId) {
+    this.unregister(deviceId);
+    this.database.prepare('DELETE FROM notifications WHERE device_id = ?').run(deviceId);
+  }
+}

package/src/pairing/pairing-qr-payload.mjs

@@ -0,0 +1,32 @@
+/** Public format for an operator-issued, short-lived pairing QR. Never a URL. */
+export const PAIRING_QR_TYPE = 'abot-pairing';
+export const PAIRING_QR_VERSION = 1;
+
+function hasCanonicalPairingOrigin(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; }
+}
+
+function hasPairingCredentials(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  if (!hasCanonicalPairingOrigin(value.serverUrl)) return false;
+  if (typeof value.pairingId !== 'string' || !/^[A-Za-z0-9_-]{32}$/.test(value.pairingId)) return false;
+  if (typeof value.code !== 'string' || !/^\d{6}$/.test(value.code)) return false;
+  return Number.isSafeInteger(value.expiresAt) && value.expiresAt > 0;
+}
+
+export function pairingQrPayload(pairing) {
+  if (!hasPairingCredentials(pairing)) throw new Error('Invalid pairing QR details');
+  // Explicit selection keeps runtime tokens and future operator-only fields out.
+  return JSON.stringify({
+    type: PAIRING_QR_TYPE,
+    version: PAIRING_QR_VERSION,
+    serverUrl: pairing.serverUrl,
+    pairingId: pairing.pairingId,
+    code: pairing.code,
+    expiresAt: pairing.expiresAt,
+  });
+}

package/src/pairing/pairing-qr.mjs

@@ -0,0 +1,42 @@
+import qrcode from 'qrcode-generator';
+import { pairingQrPayload } from './pairing-qr-payload.mjs';
+
+const QUIET_MODULES = 4;
+const BLACK_ON_WHITE = '\u001b[30;47m';
+const RESET = '\u001b[0m';
+
+function fitsTerminal(width, columns) {
+  // Leave one column free: some terminals wrap immediately at the last column.
+  return Number.isInteger(columns) && columns > width;
+}
+
+function isDarkModule(qr, row, column) {
+  const size = qr.getModuleCount();
+  if (row < 0 || column < 0 || row >= size || column >= size) return false;
+  return qr.isDark(row, column);
+}
+
+function halfBlock(top, bottom) {
+  if (top && bottom) return '█';
+  if (top) return '▀';
+  if (bottom) return '▄';
+  return ' ';
+}
+
+/** Fixed black/white terminal QR, independent of the operator's terminal theme. */
+export function renderPairingQr(pairing, { columns = 80 } = {}) {
+  const qr = qrcode(0, 'M');
+  qr.addData(pairingQrPayload(pairing), 'Byte');
+  qr.make();
+  const size = qr.getModuleCount();
+  if (!fitsTerminal(size + QUIET_MODULES * 2, columns)) return null;
+  const lines = [];
+  for (let row = -QUIET_MODULES; row < size + QUIET_MODULES; row += 2) {
+    let line = '';
+    for (let column = -QUIET_MODULES; column < size + QUIET_MODULES; column++) {
+      line += halfBlock(isDarkModule(qr, row, column), isDarkModule(qr, row + 1, column));
+    }
+    lines.push(`${BLACK_ON_WHITE}${line}${RESET}`);
+  }
+  return lines.join('\n');
+}

package/src/protocol/approval-protocol.mjs

@@ -0,0 +1,39 @@
+import { MAX_TEXT_BYTES, approvalId, boolean, fail, id, integer, optional, string } from './protocol-validation.mjs';
+
+export const APPROVAL_FIELDS = Object.freeze({
+  'request.approvals.request': ['sessionId', 'requestId'],
+  'request.approval.decide.request': ['sessionId', 'requestId', 'approvalId', 'approved', 'reason',
+    'generation', 'waitId', 'revision', 'commandId'],
+});
+
+export const APPROVAL_RESPONSES = Object.freeze({
+  'request.approvals.request': 'request.approvals.response',
+  'request.approval.decide.request': 'request.approval.decide.response',
+});
+
+const WAIT_FIELDS = ['generation', 'waitId', 'revision', 'commandId'];
+
+export function isApprovalCommand(type) {
+  return typeof type === 'string' && Object.hasOwn(APPROVAL_FIELDS, type);
+}
+
+export function durableApprovalMode(value) {
+  if (value !== 'durable_v1') fail();
+  return value;
+}
+
+/** Validate transport input only; current approval state and decisions belong to the runtime. */
+export function normalizeApprovalCommand(value) {
+  const result = { type: value.type, sessionId: id(value.sessionId), requestId: id(value.requestId) };
+  if (value.type === 'request.approvals.request') return result;
+  result.approvalId = approvalId(value.approvalId);
+  result.approved = boolean(value.approved);
+  optional(value, result, 'reason', reason => string(reason, MAX_TEXT_BYTES, { controls: true }));
+  if (!WAIT_FIELDS.some(key => Object.hasOwn(value, key))) return result;
+  if (!WAIT_FIELDS.every(key => Object.hasOwn(value, key))) fail();
+  result.generation = id(value.generation);
+  result.waitId = id(value.waitId);
+  result.revision = integer(value.revision);
+  result.commandId = id(value.commandId);
+  return result;
+}