onbuzz 4.3.0 → 4.5.0

package/src/modules/widget/galleryStore.js

@@ -0,0 +1,324 @@
+/**
+ * Gallery Store — persistent, cross-session catalog of shared widget
+ * templates. Backed by a single JSON file in the user's Loxia home
+ * directory; loaded on first use, persisted on every write (debounced).
+ *
+ * Design choices:
+ *
+ *   - Frozen-at-share semantics. Each share creates a new, immutable
+ *     templateId. Re-sharing the same widget bumps a new templateId
+ *     (or version, see below) but never mutates an existing one. This
+ *     gives reproducibility — old chats keep rendering the version
+ *     they originally used.
+ *
+ *   - Versioned per-template. A second share of the same widget under
+ *     the same `kind`/`title` increments the template's `version`
+ *     integer. The frontend later shows an "upgrade available" badge
+ *     to consumers (Phase 4).
+ *
+ *   - Single user, single file. SQLite would be more robust but
+ *     overkill for a few-hundred-entry library. Sub-megabyte JSON is
+ *     fine. Atomic write via .tmp + rename to avoid corruption.
+ *
+ * Public API (used by widgetTool):
+ *
+ *   share(widget, { agentId, agentName, sessionId }) → templateId
+ *   unshare(templateId)
+ *   list({ tag, agentId? } = {})
+ *   get(templateId)
+ *   bumpRenderCount(templateId)         // metric for "popular" templates
+ *
+ * The actual file path is configurable so tests can use a temp dir.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const DEFAULT_FILE_PATH = path.join(os.homedir(), '.loxia', 'widget-gallery.json');
+
+const VERSION_SCHEMA = 1;
+
+function safeSlug(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+}
+
+/**
+ * Generate a templateId. Format: `<slugified-title>-<version>-<rand>`.
+ * Random suffix avoids collisions when two widgets share a title.
+ */
+function generateTemplateId(title, version) {
+  const slug = safeSlug(title) || 'widget';
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `${slug}-v${version}-${rand}`;
+}
+
+export class GalleryStore {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.filePath]  Custom JSON file path (tests override this).
+   * @param {number} [opts.persistDebounceMs=200]  Coalesce writes by this delay.
+   * @param {object} [opts.logger]
+   */
+  constructor(opts = {}) {
+    this.filePath = opts.filePath || DEFAULT_FILE_PATH;
+    this.persistDebounceMs = opts.persistDebounceMs ?? 200;
+    this.logger = opts.logger || { info() {}, warn() {}, error() {}, debug() {} };
+
+    /** @type {Map<string, GalleryEntry>} */
+    this._entries = new Map();
+    this._loaded = false;
+    this._loadPromise = null;
+    this._persistTimer = null;
+    this._persistInFlight = null;
+    // Monotonic sequence used as a stable tiebreaker when two entries
+    // share the same sharedAt millisecond (which happens easily in
+    // tests and on fast machines). Always increments; never persisted
+    // (insertion order from the file is used to seed it on load).
+    this._seq = 0;
+  }
+
+  /**
+   * Lazy load. Idempotent — subsequent calls return the same promise.
+   * Safe to call multiple times concurrently.
+   */
+  async load() {
+    if (this._loaded) return;
+    if (this._loadPromise) return this._loadPromise;
+    this._loadPromise = (async () => {
+      try {
+        const raw = await fs.readFile(this.filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        if (!data || typeof data !== 'object') throw new Error('not an object');
+        if (data.schema !== VERSION_SCHEMA) {
+          this.logger.warn('Gallery file has unexpected schema, ignoring', {
+            filePath: this.filePath, found: data.schema, expected: VERSION_SCHEMA,
+          });
+          this._entries = new Map();
+        } else if (Array.isArray(data.entries)) {
+          // Seed entries; preserve _seq if persisted, otherwise re-stamp
+          // in load order (newer entries get higher seq).
+          this._entries = new Map();
+          let maxSeq = 0;
+          for (const e of data.entries) {
+            if (typeof e._seq !== 'number') e._seq = ++this._seq;
+            else if (e._seq > maxSeq) maxSeq = e._seq;
+            this._entries.set(e.templateId, e);
+          }
+          if (maxSeq > this._seq) this._seq = maxSeq;
+        }
+      } catch (err) {
+        if (err.code !== 'ENOENT') {
+          // Treat parse/IO errors as "fresh start" — better than crashing.
+          this.logger.warn('Gallery load failed, starting empty', {
+            filePath: this.filePath, error: err.message,
+          });
+        }
+        this._entries = new Map();
+      }
+      this._loaded = true;
+    })();
+    return this._loadPromise;
+  }
+
+  /**
+   * Schedule a debounced persist. Multiple writes within the debounce
+   * window result in a single disk write.
+   */
+  _scheduleWrite() {
+    if (this._persistTimer) clearTimeout(this._persistTimer);
+    this._persistTimer = setTimeout(() => {
+      this._persistTimer = null;
+      this._persistInFlight = this._writeNow().catch(err => {
+        this.logger.error('Gallery persist failed', { error: err.message });
+      });
+    }, this.persistDebounceMs);
+  }
+
+  /**
+   * Awaitable — useful for tests and shutdown hooks.
+   */
+  async flush() {
+    if (this._persistTimer) {
+      clearTimeout(this._persistTimer);
+      this._persistTimer = null;
+      await this._writeNow();
+    }
+    if (this._persistInFlight) {
+      await this._persistInFlight;
+      this._persistInFlight = null;
+    }
+  }
+
+  async _writeNow() {
+    const dir = path.dirname(this.filePath);
+    try { await fs.mkdir(dir, { recursive: true }); } catch { /* race-tolerant */ }
+    const tmp = this.filePath + '.tmp';
+    const payload = JSON.stringify({
+      schema: VERSION_SCHEMA,
+      entries: Array.from(this._entries.values()),
+    }, null, 2);
+    await fs.writeFile(tmp, payload, 'utf-8');
+    await fs.rename(tmp, this.filePath);
+  }
+
+  /**
+   * Share a widget to the gallery. Each share creates a new template
+   * with a fresh templateId — there is no in-place mutation. If the
+   * agent has shared widgets with the same `title` before, the new
+   * entry's `version` is bumped (so consumers can detect "upgrade
+   * available" later).
+   *
+   * @param {object} widget         — full widget record from WidgetTool
+   * @param {object} ctx
+   * @param {string} ctx.agentId
+   * @param {string} [ctx.agentName]
+   * @param {string} [ctx.title]    — falls back to widget.widgetId
+   * @param {string[]} [ctx.tags]
+   * @returns {{templateId: string, version: number, entry: GalleryEntry}}
+   */
+  async share(widget, ctx = {}) {
+    if (!widget || !widget.content) {
+      throw new Error('share() requires a widget with content');
+    }
+    await this.load();
+    const title = (ctx.title || widget.widgetId || 'widget').toString().slice(0, 120);
+    const tags = Array.isArray(ctx.tags)
+      ? ctx.tags.map(t => String(t).slice(0, 32)).slice(0, 16)
+      : [];
+
+    // Compute the next version number for this (agentId, title) pair.
+    let nextVersion = 1;
+    for (const e of this._entries.values()) {
+      if (e.title === title && e.sharedBy?.agentId === ctx.agentId && e.version >= nextVersion) {
+        nextVersion = e.version + 1;
+      }
+    }
+
+    const templateId = generateTemplateId(title, nextVersion);
+    const entry = {
+      templateId,
+      version:        nextVersion,
+      title,
+      kind:           widget.kind,
+      content:        widget.content,
+      defaultProps:   widget.props || {},
+      phishingHits:   Array.isArray(widget.phishingHits) ? widget.phishingHits : [],
+      tags,
+      starred:        false,
+      sharedAt:       new Date().toISOString(),
+      _seq:           ++this._seq, // stable tiebreaker for sort
+      sharedBy: {
+        agentId:    ctx.agentId || null,
+        agentName:  ctx.agentName || null,
+        sessionId:  ctx.sessionId || null,
+      },
+      forkedFrom:     ctx.forkedFrom || null,
+      renderCount:    0,
+    };
+    this._entries.set(templateId, entry);
+    this._scheduleWrite();
+    return { templateId, version: nextVersion, entry };
+  }
+
+  /**
+   * Remove a template from the gallery. Idempotent — returns true if
+   * something was removed, false otherwise.
+   */
+  async unshare(templateId) {
+    if (!templateId) return false;
+    await this.load();
+    const ok = this._entries.delete(templateId);
+    if (ok) this._scheduleWrite();
+    return ok;
+  }
+
+  /** Fetch one entry by templateId, or null. */
+  async get(templateId) {
+    await this.load();
+    return this._entries.get(templateId) || null;
+  }
+
+  /**
+   * List entries with optional filtering by tag (any-match) and/or
+   * `agentId` (entries shared BY that agent).
+   */
+  async list({ tag, agentId } = {}) {
+    await this.load();
+    let entries = Array.from(this._entries.values());
+    if (tag) entries = entries.filter(e => e.tags?.includes(tag));
+    if (agentId) entries = entries.filter(e => e.sharedBy?.agentId === agentId);
+    // Newest first; _seq breaks ties when sharedAt is identical to the
+    // millisecond (common in tests, possible at speed in production).
+    entries.sort((a, b) => {
+      const t = (b.sharedAt || '').localeCompare(a.sharedAt || '');
+      if (t !== 0) return t;
+      return (b._seq || 0) - (a._seq || 0);
+    });
+    return entries;
+  }
+
+  /**
+   * Find the LATEST version of a logical template (by title + sharedBy
+   * agentId). Used by the upgrade-prompt machinery to answer "is there
+   * a newer version of the template I'm linked to?". `originTemplateId`
+   * is the consumer's currently-linked id.
+   */
+  async findLatestForOrigin(originTemplateId) {
+    await this.load();
+    const origin = this._entries.get(originTemplateId);
+    if (!origin) return null;
+    let latest = origin;
+    for (const e of this._entries.values()) {
+      if (e.title === origin.title
+        && e.sharedBy?.agentId === origin.sharedBy?.agentId
+        && e.version > latest.version) {
+        latest = e;
+      }
+    }
+    return latest;
+  }
+
+  async bumpRenderCount(templateId) {
+    await this.load();
+    const e = this._entries.get(templateId);
+    if (!e) return;
+    e.renderCount = (e.renderCount || 0) + 1;
+    this._scheduleWrite();
+  }
+
+  // ── Test/internal helpers — not part of the stable API ─────────────
+
+  /** Drop all entries and persist the empty file. Used in tests. */
+  async __clearForTests() {
+    await this.load();
+    this._entries.clear();
+    this._scheduleWrite();
+  }
+
+  /** Number of entries (no load — call load() first if you need it). */
+  get size() { return this._entries.size; }
+}
+
+/**
+ * @typedef {Object} GalleryEntry
+ * @property {string}   templateId
+ * @property {number}   version
+ * @property {string}   title
+ * @property {'html'|'jsx'|'webcomponent'} kind
+ * @property {string}   content
+ * @property {object}   defaultProps
+ * @property {string[]} phishingHits
+ * @property {string[]} tags
+ * @property {boolean}  starred
+ * @property {string}   sharedAt              — ISO
+ * @property {{agentId: string|null, agentName: string|null, sessionId: string|null}} sharedBy
+ * @property {string|null} forkedFrom         — templateId or null
+ * @property {number}   renderCount
+ */
+
+export default GalleryStore;

package/src/modules/widget/index.js

@@ -0,0 +1,38 @@
+/**
+ * Widget module — public API.
+ *
+ * This is the ONLY file outside the module that core code imports from.
+ * The module owns: the widgetTool, the runtime bundle, the HTTP routes,
+ * the schema, and the phishing scanner. Nothing else.
+ *
+ * Core integration is two lines:
+ *
+ *   // src/index.js
+ *   if (!widgetModule.isDisabled()) {
+ *     await this.toolsRegistry.registerTool(widgetModule.WidgetTool);
+ *   }
+ *
+ *   // src/interfaces/webServer.js
+ *   widgetModule.registerRoutes(this.app, this.orchestrator);
+ *
+ * Removing the feature = delete this directory + those two lines.
+ * See also: LOXIA_DISABLE_WIDGETS=1 env flag below (zero-source disable).
+ */
+
+import { WidgetTool } from './widgetTool.js';
+import { registerRoutes } from './routes.js';
+
+export { WidgetTool, registerRoutes };
+
+/**
+ * Feature flag — when truthy, the module declines all registration.
+ * Core files use `isDisabled()` so they can skip registering the tool +
+ * routes without needing to know whether this file is on disk. Cheap way
+ * to ship a kill-switch in production AND a clean seam for test suites.
+ */
+export function isDisabled() {
+  return process.env.LOXIA_DISABLE_WIDGETS === '1'
+      || process.env.LOXIA_DISABLE_WIDGETS === 'true';
+}
+
+export default { WidgetTool, registerRoutes, isDisabled };

package/src/modules/widget/phishingScanner.js

@@ -0,0 +1,47 @@
+/**
+ * Lightweight phishing-shape detector for agent-generated widget content.
+ *
+ * NOT a security boundary — the sandbox iframe is. This scanner is a
+ * soft UX nudge: when the content asks for credentials or identity data,
+ * the frontend bumps the user through a stronger confirmation modal
+ * before rendering. It trades off false positives (cheap: one extra
+ * click) against missing obvious credential-harvesting shapes.
+ *
+ * Shared between backend (so we can flag at tool-receive time and log)
+ * and frontend (so the modal copy can reference the matched phrase).
+ */
+
+const KEYWORDS = [
+  // Credentials
+  'password', 'passphrase', 'passcode', 'pwd',
+  'login', 'log in', 'sign in', 'signin',
+  // Second factor / verification
+  'otp', 'one-time code', 'one time code',
+  '2fa', 'two factor', 'two-factor',
+  'verify your identity', 'verify identity',
+  'confirm your identity',
+  // Financial
+  'credit card', 'cvv', 'card number',
+  'ssn', 'social security',
+  'bank account', 'routing number',
+  // Common phishing cover stories
+  'account suspended', 'unusual activity',
+  'verify account', 'reset your password',
+];
+
+/**
+ * Scan content for phishing-shape keywords. Returns a list of matched
+ * keywords (empty when clean).
+ *
+ * @param {string} content — raw HTML or JSX source the agent submitted
+ * @returns {string[]}
+ */
+export function scanForPhishingKeywords(content) {
+  if (typeof content !== 'string' || !content) return [];
+  const haystack = content.toLowerCase();
+  const hits = [];
+  for (const needle of KEYWORDS) {
+    if (haystack.includes(needle)) hits.push(needle);
+  }
+  return hits;
+}