@pellux/goodvibes-tui 0.24.1 → 0.26.0

package/src/daemon/handlers/email/validation.ts

@@ -0,0 +1,147 @@
+// ---------------------------------------------------------------------------
+// Input validation, PII-safe digesting, and response shaping for the email
+// handler surface. Pure functions only (no I/O, no secrets).
+// ---------------------------------------------------------------------------
+
+import { createHash } from 'node:crypto';
+import { HandlerError } from '../errors.ts';
+import type { ImapEnvelopeSummary, ImapFullMessage } from './imap-connector.ts';
+
+export function asRecord(body: unknown): Record<string, unknown> {
+  if (typeof body !== 'object' || body === null) {
+    throw new HandlerError('Request body must be an object', 'EMAIL_BAD_INPUT', 400);
+  }
+  return body as Record<string, unknown>;
+}
+
+export function requireString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new HandlerError(`Field '${field}' is required`, 'EMAIL_BAD_INPUT', 400);
+  }
+  return value;
+}
+
+export function optionalString(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') {
+    throw new HandlerError(`Field '${field}' must be a string`, 'EMAIL_BAD_INPUT', 400);
+  }
+  return value;
+}
+
+/**
+ * Extract the addr-spec from an RFC 5322 name-addr ("Display <a@b>"). Reads the
+ * contents of the LAST <...> pair so a stray '<' inside a quoted display name
+ * does not corrupt the result.
+ */
+export function extractAddrSpec(entry: string): string {
+  const open = entry.lastIndexOf('<');
+  if (open !== -1) {
+    const close = entry.indexOf('>', open + 1);
+    if (close !== -1) return entry.slice(open + 1, close).trim();
+  }
+  return entry.trim();
+}
+
+export function validateEmailAddress(value: string, field: string): string {
+  const entries = value.split(',').map((s) => s.trim()).filter(Boolean);
+  if (entries.length === 0 || entries.some((e) => !/.+@.+\..+/.test(extractAddrSpec(e)))) {
+    throw new HandlerError(`Field '${field}' must be a valid email address`, 'EMAIL_BAD_INPUT', 400);
+  }
+  return value;
+}
+
+export function clampLimit(value: unknown): number {
+  if (value === undefined || value === null) return 10;
+  const n = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(n)) {
+    throw new HandlerError("Field 'limit' must be a number", 'EMAIL_BAD_INPUT', 400);
+  }
+  return Math.min(100, Math.max(1, Math.floor(n)));
+}
+
+export function validateIsoDate(value: unknown): string | undefined {
+  const str = optionalString(value, 'since');
+  if (str === undefined) return undefined;
+  if (Number.isNaN(new Date(str).getTime())) {
+    throw new HandlerError("Field 'since' must be an ISO-8601 date", 'EMAIL_BAD_INPUT', 400);
+  }
+  return str;
+}
+
+export function requireUid(value: unknown): number {
+  const n = typeof value === 'number' ? value : Number(value);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new HandlerError("Field 'uid' must be a positive integer", 'EMAIL_BAD_INPUT', 400);
+  }
+  return n;
+}
+
+/** Reduce an address to a stable, non-reversible digest for PII-safe logging. */
+export function addressDigest(address: string): string {
+  return createHash('sha256').update(address.toLowerCase().trim(), 'utf-8').digest('hex').slice(0, 16);
+}
+
+// ---------------------------------------------------------------------------
+// Response contracts (must match EMAIL_INBOX_MESSAGE_SCHEMA /
+// EMAIL_MESSAGE_DETAIL_SCHEMA / {uid,draftId} / {messageId,sentAt}).
+// ---------------------------------------------------------------------------
+
+export interface InboxListResponse {
+  messages: Array<{
+    uid: number;
+    from: string;
+    subject: string;
+    date: string;
+    unread: boolean;
+    bodyPreview: string;
+    messageId: string;
+  }>;
+  total: number;
+}
+
+export interface InboxReadResponse {
+  uid: number;
+  from: string;
+  subject: string;
+  date: string;
+  messageId: string;
+  bodyText: string;
+  bodyHtml?: string;
+  attachments?: Array<{ filename: string; contentType: string; sizeBytes: number }>;
+}
+
+export interface DraftCreateResponse {
+  uid: number;
+  draftId: string;
+}
+
+export interface SendResponse {
+  messageId: string;
+  sentAt: string;
+}
+
+export function toListMessage(m: ImapEnvelopeSummary): InboxListResponse['messages'][number] {
+  return {
+    uid: m.uid,
+    from: m.from,
+    subject: m.subject,
+    date: m.date,
+    unread: m.unread,
+    bodyPreview: m.bodyPreview,
+    messageId: m.messageId,
+  };
+}
+
+export function toReadMessage(m: ImapFullMessage): InboxReadResponse {
+  return {
+    uid: m.uid,
+    from: m.from,
+    subject: m.subject,
+    date: m.date,
+    messageId: m.messageId,
+    bodyText: m.bodyText,
+    ...(m.bodyHtml ? { bodyHtml: m.bodyHtml } : {}),
+    ...(m.attachments && m.attachments.length > 0 ? { attachments: m.attachments } : {}),
+  };
+}

package/src/daemon/handlers/email/write-handlers.ts

@@ -0,0 +1,133 @@
+// ---------------------------------------------------------------------------
+// Write handlers: email.draft.create + email.send.
+//
+// email.draft.create is access:admin (no body.confirm in the SDK contract);
+// email.send is dangerous:true and confirmation-gated — index.ts registers it
+// with { confirm: true }, so the register wrapper enforces body.confirm===true
+// AND explicitUserRequest before this handler runs.
+//
+// Recipients are validated, sender/recipient addresses are reduced to a digest
+// before logging (PII strip), and draft bodies are encrypted at rest by the
+// runtime before persistence. No secret or raw address is echoed into a
+// response. No descriptor or schema is authored here.
+// ---------------------------------------------------------------------------
+
+import type { CatalogHandlerEntry, TypedHandler } from '../register.ts';
+import type { EmailRuntime } from './runtime.ts';
+import { buildRfc5322Message, generateMessageId } from './smtp-connector.ts';
+import {
+  asRecord,
+  requireString,
+  optionalString,
+  validateEmailAddress,
+  addressDigest,
+  type DraftCreateResponse,
+  type SendResponse,
+} from './validation.ts';
+
+interface DraftCreateBody {
+  to?: unknown;
+  subject?: unknown;
+  body?: unknown;
+  inReplyTo?: unknown;
+  references?: unknown;
+}
+
+interface SendBody {
+  to?: unknown;
+  subject?: unknown;
+  body?: unknown;
+  inReplyTo?: unknown;
+  confirm?: unknown;
+}
+
+function draftCreateHandler(runtime: EmailRuntime): TypedHandler<DraftCreateBody, DraftCreateResponse> {
+  return async ({ body }) => {
+    const input = asRecord(body);
+    const to = validateEmailAddress(requireString(input.to, 'to'), 'to');
+    const subject = requireString(input.subject, 'subject');
+    const draftBody = requireString(input.body, 'body');
+    const inReplyTo = optionalString(input.inReplyTo, 'inReplyTo');
+    const references = optionalString(input.references, 'references');
+
+    const from = await runtime.smtpFrom();
+    const messageId = generateMessageId(from);
+    const raw = buildRfc5322Message({
+      from,
+      to,
+      subject,
+      body: draftBody,
+      messageId,
+      date: new Date(),
+      ...(inReplyTo ? { inReplyTo } : {}),
+      ...(references ? { references } : {}),
+    });
+    const appended = await runtime.withImap((imap) => imap.appendDraft(raw));
+
+    const now = new Date().toISOString();
+    const draftId = messageId.replace(/[<>]/g, '');
+    await runtime.persistDraft({
+      id: draftId,
+      to,
+      subject,
+      plaintextBody: draftBody,
+      status: 'draft',
+      createdAt: now,
+      updatedAt: now,
+      metadata: { uid: appended.uid, mailbox: appended.mailbox, messageId },
+    });
+
+    runtime.logger.info('email.draft.create', {
+      uid: appended.uid,
+      draftId,
+      recipient: addressDigest(to),
+    });
+    return { uid: appended.uid, draftId };
+  };
+}
+
+function sendHandler(runtime: EmailRuntime): TypedHandler<SendBody, SendResponse> {
+  return async ({ body }) => {
+    const input = asRecord(body);
+    const to = validateEmailAddress(requireString(input.to, 'to'), 'to');
+    const subject = requireString(input.subject, 'subject');
+    const sendBody = requireString(input.body, 'body');
+    const inReplyTo = optionalString(input.inReplyTo, 'inReplyTo');
+
+    const smtp = await runtime.openSmtp();
+    let result: SendResponse;
+    try {
+      result = await smtp.send({
+        to,
+        subject,
+        body: sendBody,
+        ...(inReplyTo ? { inReplyTo } : {}),
+      });
+    } finally {
+      await smtp.close();
+    }
+    runtime.logger.info('email.send', {
+      messageId: result.messageId,
+      sentAt: result.sentAt,
+      recipient: addressDigest(to),
+    });
+    return result;
+  };
+}
+
+/** Build the write-handler catalog entries bound to the shared runtime. */
+export function buildWriteHandlerEntries(runtime: EmailRuntime): CatalogHandlerEntry[] {
+  return [
+    {
+      id: 'email.draft.create',
+      handler: draftCreateHandler(runtime) as TypedHandler<unknown, unknown>,
+    },
+    {
+      id: 'email.send',
+      handler: sendHandler(runtime) as TypedHandler<unknown, unknown>,
+      // dangerous:true SDK method — require explicit confirmation (body.confirm
+      // === true AND explicitUserRequest) via the register wrapper.
+      options: { confirm: true },
+    },
+  ];
+}

package/src/daemon/handlers/errors.ts

@@ -0,0 +1,18 @@
+/**
+ * Error type for daemon handler execution. Carries a stable machine `code`
+ * and an HTTP `status` so the control-plane dispatcher can map failures to
+ * wire responses without leaking implementation detail.
+ */
+export class HandlerError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly status: number,
+  ) {
+    super(message);
+    this.name = 'HandlerError';
+  }
+}
+
+/** Code emitted when a confirmation-gated method is invoked without explicit user confirmation. */
+export const REQUIRE_CONFIRM = 'REQUIRE_CONFIRM';

package/src/daemon/handlers/inbox/cursor-store.ts

@@ -0,0 +1,290 @@
+// ---------------------------------------------------------------------------
+// Persistent cursor + item store for the inbound feed.
+//
+// Backed by HandlerSqliteStore (sql.js WASM) at
+//   {wd}/.goodvibes/tui/operator/inbox.sqlite
+//
+// Two tables:
+//   items(id PK, provider, kind, fromDigest, subjectPreview, bodyPreview,
+//         routeId, receivedAt INT, unread INT)
+//   cursors(provider PK, nextSince INT)
+//
+// Dedup is by items.id (upsert). nextSince advances monotonically per provider
+// = max(receivedAt) ever seen. Triage metadata is NOT persisted here: it is
+// applied downstream at the triage overlay layer (triage/integration.ts) over a
+// separate store, so this feed store carries only the raw inbound fields.
+// ---------------------------------------------------------------------------
+
+import { HandlerSqliteStore } from '../sqlite-store.ts';
+import type { InboundChannelItem } from './provider-adapter.ts';
+
+const SCHEMA: string[] = [
+  `CREATE TABLE IF NOT EXISTS items (
+     id TEXT PRIMARY KEY,
+     provider TEXT NOT NULL,
+     kind TEXT NOT NULL,
+     fromDigest TEXT NOT NULL,
+     subjectPreview TEXT NOT NULL,
+     bodyPreview TEXT NOT NULL,
+     routeId TEXT,
+     receivedAt INTEGER NOT NULL,
+     unread INTEGER NOT NULL
+   )`,
+  `CREATE INDEX IF NOT EXISTS idx_items_provider_received
+     ON items(provider, receivedAt)`,
+  `CREATE INDEX IF NOT EXISTS idx_items_received
+     ON items(receivedAt)`,
+  `CREATE TABLE IF NOT EXISTS cursors (
+     provider TEXT PRIMARY KEY,
+     nextSince INTEGER NOT NULL
+   )`,
+];
+
+interface ItemRow {
+  id: string;
+  provider: string;
+  kind: string;
+  fromDigest: string;
+  subjectPreview: string;
+  bodyPreview: string;
+  routeId: string | null;
+  receivedAt: number;
+  unread: number;
+}
+
+export interface InboxQuery {
+  providers?: readonly string[];
+  since?: number;
+  /** Max items returned across the whole query. */
+  limit: number;
+}
+
+export class InboxCursorStore {
+  private readonly store: HandlerSqliteStore;
+  private dirty = false;
+
+  constructor(workingDirectory: string, fileName = 'inbox.sqlite') {
+    this.store = new HandlerSqliteStore({
+      workingDirectory,
+      fileName,
+      schema: SCHEMA,
+    });
+  }
+
+  get dbPath(): string {
+    return this.store.dbPath;
+  }
+
+  async init(): Promise<void> {
+    await this.store.init();
+  }
+
+  /**
+   * Insert/refresh items, deduping by id. On conflict the mutable feed fields
+   * (unread, previews, routeId, receivedAt) are updated in place.
+   * Returns the number of NEW (previously unseen) items.
+   */
+  upsertItems(items: readonly InboundChannelItem[]): number {
+    if (items.length === 0) return 0;
+    let inserted = 0;
+    // Only the ids in THIS batch can collide, so probe for exactly those rather
+    // than loading the whole table — bounds the lookup to the poll size instead
+    // of growing O(n) with the (unbounded) feed.
+    const batchIds = [...new Set(items.map((i) => i.id))];
+    const placeholders = batchIds.map(() => '?').join(', ');
+    const existing = new Set(
+      this.store
+        .all<{ id: string }>(
+          `SELECT id FROM items WHERE id IN (${placeholders})`,
+          batchIds,
+        )
+        .map((r) => r.id),
+    );
+    // Track ids seen within this batch so a duplicate id in a single poll is
+    // counted (and inserted) once, not once per occurrence.
+    const seen = new Set<string>();
+    this.store.transaction(() => {
+      for (const item of items) {
+        const isNew = !existing.has(item.id) && !seen.has(item.id);
+        if (isNew) inserted += 1;
+        seen.add(item.id);
+        this.store.run(
+          `INSERT INTO items
+             (id, provider, kind, fromDigest, subjectPreview, bodyPreview,
+              routeId, receivedAt, unread)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(id) DO UPDATE SET
+             provider = excluded.provider,
+             kind = excluded.kind,
+             fromDigest = excluded.fromDigest,
+             subjectPreview = excluded.subjectPreview,
+             bodyPreview = excluded.bodyPreview,
+             routeId = COALESCE(excluded.routeId, items.routeId),
+             receivedAt = excluded.receivedAt,
+             unread = excluded.unread`,
+          [
+            item.id,
+            item.provider,
+            item.kind,
+            item.fromDigest,
+            item.subjectPreview,
+            item.bodyPreview,
+            item.routeId ?? null,
+            item.receivedAt,
+            item.unread ? 1 : 0,
+          ],
+        );
+      }
+    });
+    this.dirty = true;
+    return inserted;
+  }
+
+  /**
+   * Advance a provider's cursor monotonically. The stored value is always the
+   * max of the current value and the supplied candidate.
+   */
+  advanceCursor(provider: string, candidate: number): void {
+    if (!Number.isFinite(candidate)) return;
+    const current = this.getCursor(provider);
+    const next = Math.max(current, Math.floor(candidate));
+    if (next === current && current !== 0) return;
+    this.store.run(
+      `INSERT INTO cursors (provider, nextSince) VALUES (?, ?)
+       ON CONFLICT(provider) DO UPDATE SET
+         nextSince = MAX(cursors.nextSince, excluded.nextSince)`,
+      [provider, next],
+    );
+    this.dirty = true;
+  }
+
+  /** Current cursor for a provider (0 when unset). */
+  getCursor(provider: string): number {
+    const row = this.store.get<{ nextSince: number }>(
+      'SELECT nextSince FROM cursors WHERE provider = ?',
+      [provider],
+    );
+    return row ? Number(row.nextSince) : 0;
+  }
+
+  /**
+   * Read items for the feed, filtered by provider set + since, newest first,
+   * capped at limit. Maps SQLite rows back to the internal item shape.
+   */
+  listItems(query: InboxQuery): InboundChannelItem[] {
+    const clauses: string[] = [];
+    const params: (string | number)[] = [];
+    if (query.providers && query.providers.length > 0) {
+      const placeholders = query.providers.map(() => '?').join(', ');
+      clauses.push(`provider IN (${placeholders})`);
+      params.push(...query.providers);
+    }
+    if (typeof query.since === 'number' && Number.isFinite(query.since)) {
+      clauses.push('receivedAt > ?');
+      params.push(Math.floor(query.since));
+    }
+    const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+    const limit = Math.max(0, Math.floor(query.limit));
+    params.push(limit);
+    const rows = this.store.all<ItemRow>(
+      `SELECT id, provider, kind, fromDigest, subjectPreview, bodyPreview,
+              routeId, receivedAt, unread
+         FROM items ${where}
+         ORDER BY receivedAt DESC, id ASC
+         LIMIT ?`,
+      params,
+    );
+    return rows.map(rowToItem);
+  }
+
+  /** Highest receivedAt across the (optionally provider-filtered) feed, or 0. */
+  maxReceivedAt(providers?: readonly string[]): number {
+    let where = '';
+    const params: (string | number)[] = [];
+    if (providers && providers.length > 0) {
+      const placeholders = providers.map(() => '?').join(', ');
+      where = `WHERE provider IN (${placeholders})`;
+      params.push(...providers);
+    }
+    const row = this.store.get<{ maxReceived: number | null }>(
+      `SELECT MAX(receivedAt) AS maxReceived FROM items ${where}`,
+      params,
+    );
+    return row && row.maxReceived != null ? Number(row.maxReceived) : 0;
+  }
+
+  /** Total count of items across the (optional) provider set. */
+  countItems(providers?: readonly string[]): number {
+    let where = '';
+    const params: (string | number)[] = [];
+    if (providers && providers.length > 0) {
+      const placeholders = providers.map(() => '?').join(', ');
+      where = `WHERE provider IN (${placeholders})`;
+      params.push(...providers);
+    }
+    const row = this.store.get<{ n: number }>(
+      `SELECT COUNT(*) AS n FROM items ${where}`,
+      params,
+    );
+    return row ? Number(row.n) : 0;
+  }
+
+  /**
+   * Retention: delete items strictly older than `cutoff` (Unix ms), optionally
+   * scoped to a provider set. Returns the number of rows removed. Cursors are
+   * left untouched so already-consumed watermarks never regress. A non-finite
+   * cutoff is a no-op (prevents an accidental whole-table wipe).
+   */
+  pruneOlderThan(cutoff: number, providers?: readonly string[]): number {
+    if (!Number.isFinite(cutoff)) return 0;
+    const clauses = ['receivedAt < ?'];
+    const params: (string | number)[] = [Math.floor(cutoff)];
+    if (providers && providers.length > 0) {
+      const placeholders = providers.map(() => '?').join(', ');
+      clauses.push(`provider IN (${placeholders})`);
+      params.push(...providers);
+    }
+    const before = this.countItems(providers);
+    this.store.run(`DELETE FROM items WHERE ${clauses.join(' AND ')}`, params);
+    const removed = before - this.countItems(providers);
+    if (removed > 0) this.dirty = true;
+    return removed;
+  }
+
+  /** Persist to disk if anything changed since the last flush. */
+  async flush(): Promise<void> {
+    if (!this.dirty) return;
+    await this.store.save();
+    this.dirty = false;
+  }
+
+  /** Flush (best-effort) then close the underlying database. */
+  async close(): Promise<void> {
+    try {
+      await this.flush();
+    } finally {
+      this.store.close();
+    }
+  }
+}
+
+function rowToItem(row: ItemRow): InboundChannelItem {
+  const item: InboundChannelItem = {
+    id: row.id,
+    provider: row.provider,
+    kind: normalizeKind(row.kind),
+    fromDigest: row.fromDigest,
+    subjectPreview: row.subjectPreview,
+    bodyPreview: row.bodyPreview,
+    receivedAt: Number(row.receivedAt),
+    unread: Number(row.unread) !== 0,
+  };
+  if (row.routeId != null) item.routeId = row.routeId;
+  return item;
+}
+
+function normalizeKind(value: string): InboundChannelItem['kind'] {
+  return value === 'dm' || value === 'thread' || value === 'mention' || value === 'reaction'
+    ? value
+    : 'dm';
+}