rcf-lite 0.28.4 → 0.29.0

package/src/view/test-host/embed-client.js

@@ -0,0 +1,121 @@
+// Wespa host fixture client (viewer UI refresh PR 9; TAC-4134).
+// Served at /test-host.js by the viewer's dev server when --test-host
+// is on (RCF_VIEW_TEST_HOST=1 equivalent). Wires three fixture
+// behaviours:
+//   - Theme toggle: posts { type: "rcf-view-theme", theme } to the
+//     iframe.contentWindow, targeting window.location.origin so a
+//     cross-origin receiver would refuse the message. Does not read
+//     event.origin itself; the viewer does, and the fixture READS the
+//     iframe's data-theme attribute as evidence.
+//   - Sidebar drag: a 6px handle on the sidebar's right edge sets
+//     --wespa-sidebar-width on the <main> grid; clamped to 64..400 px
+//     live.
+//   - Collapse/Expand: snaps the sidebar between 64 px (collapsed) and
+//     200 px (expanded) and toggles the .collapsed class.
+//
+// Does NOT persist theme or sidebar width to localStorage (ADR-4136):
+// a passing run has to flip the iframe through postMessage, which is
+// the invariant the fixture pins.
+//
+// Classic (non-module) browser script so the fixture page carries no
+// inline <script> and the embed-client is a plain <script src>.
+
+(function () {
+  var SIDEBAR_MIN = 64;
+  var SIDEBAR_EXPANDED = 200;
+  var SIDEBAR_MAX = 400;
+
+  function iframe() {
+    return document.getElementById('rcf-test-host-iframe');
+  }
+
+  function postThemeToIframe(theme) {
+    var el = iframe();
+    if (!el || !el.contentWindow) return;
+    try {
+      el.contentWindow.postMessage(
+        { type: 'rcf-view-theme', theme: theme },
+        window.location.origin,
+      );
+    } catch (e) { /* swallow */ }
+  }
+
+  function wireThemeToggle() {
+    var buttons = Array.prototype.slice.call(
+      document.querySelectorAll('[data-rcf-host-theme]'),
+    );
+    if (buttons.length === 0) return;
+    buttons.forEach(function (btn) {
+      btn.addEventListener('click', function () {
+        var theme = btn.getAttribute('data-rcf-host-theme');
+        if (theme !== 'light' && theme !== 'dark') return;
+        buttons.forEach(function (b) {
+          b.setAttribute('aria-pressed', b === btn ? 'true' : 'false');
+        });
+        postThemeToIframe(theme);
+      });
+    });
+  }
+
+  function setSidebarWidth(px) {
+    var shell = document.querySelector('main.wespa-shell');
+    if (!shell) return;
+    var clamped = Math.max(SIDEBAR_MIN, Math.min(SIDEBAR_MAX, Math.round(px)));
+    shell.style.setProperty('--wespa-sidebar-width', clamped + 'px');
+    var aside = document.querySelector('[data-rcf-host-sidebar]');
+    if (aside) {
+      if (clamped <= SIDEBAR_MIN) aside.classList.add('collapsed');
+      else aside.classList.remove('collapsed');
+    }
+  }
+
+  function wireSidebarDrag() {
+    var handle = document.querySelector('[data-rcf-host-sidebar-drag]');
+    var aside = document.querySelector('[data-rcf-host-sidebar]');
+    if (!handle || !aside) return;
+    var dragging = false;
+    handle.addEventListener('mousedown', function (ev) {
+      dragging = true;
+      handle.classList.add('dragging');
+      ev.preventDefault();
+    });
+    document.addEventListener('mousemove', function (ev) {
+      if (!dragging) return;
+      var rect = aside.getBoundingClientRect();
+      setSidebarWidth(ev.clientX - rect.left);
+    });
+    document.addEventListener('mouseup', function () {
+      if (!dragging) return;
+      dragging = false;
+      handle.classList.remove('dragging');
+    });
+  }
+
+  function wireSidebarToggle() {
+    var btn = document.querySelector('[data-rcf-host-sidebar-toggle]');
+    var aside = document.querySelector('[data-rcf-host-sidebar]');
+    if (!btn || !aside) return;
+    btn.addEventListener('click', function () {
+      if (aside.classList.contains('collapsed')) {
+        setSidebarWidth(SIDEBAR_EXPANDED);
+        btn.textContent = 'Collapse';
+      } else {
+        setSidebarWidth(SIDEBAR_MIN);
+        btn.textContent = 'Expand';
+      }
+    });
+  }
+
+  function boot() {
+    setSidebarWidth(SIDEBAR_EXPANDED);
+    wireThemeToggle();
+    wireSidebarDrag();
+    wireSidebarToggle();
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', boot);
+  } else {
+    boot();
+  }
+})();

package/src/view/test-host/fixture.js

@@ -0,0 +1,183 @@
+// Wespa host fixture (viewer UI refresh PR 9; TAC-4134, ADR-4136).
+// Served by the viewer's own dev server at /test-host.html when
+// --test-host is passed (or RCF_VIEW_TEST_HOST=1 is set); 404 otherwise
+// so wespa's reverse-proxy allow-list is unaffected. Mimics the wespa
+// shell: a 56px header carrying a Light/Dark toggle, a resizable
+// sidebar (64px collapsed, 200-400px expanded, user-resizable live via
+// a drag handle), a content pane carrying a single iframe pointed at
+// the viewer root ("./?embed=1&theme=light" resolves to "/?..."
+// because the fixture lives at the root path, not under /test-host/).
+// The fixture carries no inline script; its client-side wiring lives
+// at /test-host.js (served as a snapshotted asset at startup; see
+// server/index.js).
+//
+// The fixture does not persist theme to localStorage: a passing run
+// has to flip the iframe through the postMessage path, which is the
+// invariant ADR-4136 pins. The host never reads event.origin itself
+// (the viewer does); the host only READS the iframe's data-theme and
+// data-embed attributes as evidence.
+
+/**
+ * Return the fixture HTML string. Pure function, no I/O.
+ *
+ * @returns {string}
+ */
+export function renderTestHostPage() {
+  return `<!DOCTYPE html>
+<html lang="en-GB" data-rcf-test-host="wespa">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Wespa host fixture - rcf-lite viewer embed proof</title>
+  <style>
+    html, body { height: 100%; margin: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, sans-serif;
+      display: grid;
+      grid-template-rows: 56px 1fr;
+      background: #0e1116;
+      color: #c9d1d9;
+    }
+    header.wespa-header {
+      height: 56px;
+      display: flex;
+      align-items: center;
+      gap: 1rem;
+      padding: 0 1rem;
+      background: #161b22;
+      border-bottom: 1px solid #30363d;
+      box-sizing: border-box;
+    }
+    header.wespa-header .wespa-brand {
+      font-weight: 700;
+      font-size: 0.95rem;
+      letter-spacing: -0.01em;
+    }
+    header.wespa-header .wespa-brand-sub {
+      color: #8b949e;
+      font-size: 0.85rem;
+      margin-left: 0.5rem;
+    }
+    header.wespa-header .wespa-theme-toggle {
+      margin-left: auto;
+      display: inline-flex;
+      align-items: center;
+      gap: 0.3rem;
+      font-size: 0.85rem;
+    }
+    header.wespa-header .wespa-theme-toggle button {
+      appearance: none;
+      border: 1px solid #30363d;
+      background: #0e1116;
+      color: #c9d1d9;
+      padding: 0.25rem 0.65rem;
+      border-radius: 6px;
+      cursor: pointer;
+      font-family: inherit;
+      font-size: 0.85rem;
+    }
+    header.wespa-header .wespa-theme-toggle button[aria-pressed="true"] {
+      background: #1f6feb;
+      border-color: #1f6feb;
+      color: #ffffff;
+      font-weight: 600;
+    }
+    main.wespa-shell {
+      display: grid;
+      grid-template-columns: var(--wespa-sidebar-width, 200px) 1fr;
+      overflow: hidden;
+    }
+    aside.wespa-sidebar {
+      background: #161b22;
+      border-right: 1px solid #30363d;
+      position: relative;
+      overflow: hidden;
+      display: flex;
+      flex-direction: column;
+    }
+    aside.wespa-sidebar .wespa-sidebar-head {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 0.5rem 0.75rem;
+      border-bottom: 1px solid #30363d;
+    }
+    aside.wespa-sidebar .wespa-sidebar-head button {
+      appearance: none;
+      border: 1px solid #30363d;
+      background: #0e1116;
+      color: #c9d1d9;
+      padding: 0.2rem 0.5rem;
+      border-radius: 6px;
+      cursor: pointer;
+      font-family: inherit;
+      font-size: 0.75rem;
+    }
+    aside.wespa-sidebar .wespa-sidebar-items {
+      flex: 1;
+      overflow: auto;
+      padding: 0.5rem;
+      color: #8b949e;
+      font-size: 0.85rem;
+    }
+    aside.wespa-sidebar .wespa-sidebar-items p { margin: 0 0 0.5rem; }
+    aside.wespa-sidebar.collapsed .wespa-sidebar-items { display: none; }
+    aside.wespa-sidebar .wespa-sidebar-drag {
+      position: absolute;
+      top: 0;
+      right: 0;
+      bottom: 0;
+      width: 6px;
+      cursor: col-resize;
+      background: transparent;
+    }
+    aside.wespa-sidebar .wespa-sidebar-drag:hover,
+    aside.wespa-sidebar .wespa-sidebar-drag.dragging {
+      background: #1f6feb;
+    }
+    section.wespa-content {
+      position: relative;
+      overflow: hidden;
+      background: #0e1116;
+    }
+    iframe.wespa-iframe {
+      border: 0;
+      width: 100%;
+      height: 100%;
+      display: block;
+      background: #ffffff;
+    }
+  </style>
+</head>
+<body>
+  <header class="wespa-header">
+    <span class="wespa-brand">Wespa</span>
+    <span class="wespa-brand-sub">rcf-lite viewer embed proof</span>
+    <div class="wespa-theme-toggle" role="group" aria-label="Iframe theme">
+      <span>Theme</span>
+      <button type="button" data-rcf-host-theme="light" aria-pressed="true">Light</button>
+      <button type="button" data-rcf-host-theme="dark" aria-pressed="false">Dark</button>
+    </div>
+  </header>
+  <main class="wespa-shell">
+    <aside class="wespa-sidebar" data-rcf-host-sidebar>
+      <div class="wespa-sidebar-head">
+        <span>Projects</span>
+        <button type="button" data-rcf-host-sidebar-toggle>Collapse</button>
+      </div>
+      <div class="wespa-sidebar-items">
+        <p>rcf-lite</p>
+        <p>wespa</p>
+        <p>design docs</p>
+      </div>
+      <div class="wespa-sidebar-drag" data-rcf-host-sidebar-drag title="Drag to resize"></div>
+    </aside>
+    <section class="wespa-content">
+      <iframe class="wespa-iframe" id="rcf-test-host-iframe" title="rcf-lite viewer" src="./?embed=1&amp;theme=light"></iframe>
+    </section>
+  </main>
+  <script src="./test-host.js" defer></script>
+</body>
+</html>
+`;
+}

package/src/view/test-host/lints.js

@@ -0,0 +1,220 @@
+// Three embedding lints (viewer UI refresh PR 9; TAC-4134, ADR-4136).
+// Pure assertions each caller composes into whatever test harness it
+// owns; test/view/wespa-host-fixture.test.js is the suite caller.
+//
+// (1) assertFramingHeaders(response)
+//     Refuses on X-Frame-Options, on CSP frame-ancestors that forbids
+//     same-origin, or on any header the viewer sets that would block
+//     wespa's same-origin iframe mount. The viewer today sets neither,
+//     so a passing run proves the browser accepts the iframe.
+//
+// (2) assertNoTargetTop(renderedHtml)
+//     Greps the server-rendered HTML for target="_top" and target='_top'
+//     and refuses on any match. Dex's contract (section 9) bans
+//     target="_top" links so a legitimate in-iframe navigation never
+//     breaks the embedding host out of its box.
+//
+// (3) assertLocalStorageNamespace(sourceTreeRoot)
+//     Walks every .js file under sourceTreeRoot/src/view (excluding
+//     vendored and .min.js) and asserts every localStorage.* and shared
+//     storage.* call site uses a key literal starting with
+//     "rcf-view:v1:" (or references STORAGE_NS declared equal to that
+//     prefix). Dex's contract (section 9) requires the viewer namespace
+//     every localStorage key because the viewer shares localStorage
+//     with the wespa SPA.
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+
+const STORAGE_NS = 'rcf-view:v1:';
+
+/**
+ * @param {{ headers: Headers | Record<string, string> | Map<string, string> }} response
+ * @returns {{ ok: true, headers: { xFrameOptions: null, csp: string | null } } | { ok: false, reason: string }}
+ */
+export function assertFramingHeaders(response) {
+  const headers = response && response.headers;
+  if (!headers) return { ok: false, reason: 'no headers on response' };
+  const get = pickHeaderGetter(headers);
+  const xFrameOptions = get('x-frame-options');
+  if (xFrameOptions !== null && xFrameOptions !== undefined && String(xFrameOptions).trim() !== '') {
+    return { ok: false, reason: `X-Frame-Options present: ${xFrameOptions}` };
+  }
+  const csp = get('content-security-policy');
+  if (csp) {
+    const directive = parseCspFrameAncestors(String(csp));
+    if (directive !== null && !directive.allowsSameOrigin) {
+      return { ok: false, reason: `CSP frame-ancestors forbids same-origin: ${directive.raw}` };
+    }
+  }
+  return { ok: true, headers: { xFrameOptions: null, csp: csp ?? null } };
+}
+
+/**
+ * @param {string} renderedHtml
+ * @returns {{ ok: true, count: 0 } | { ok: false, count: number, matches: string[] }}
+ */
+export function assertNoTargetTop(renderedHtml) {
+  if (typeof renderedHtml !== 'string') {
+    return { ok: false, count: 1, matches: ['non-string input'] };
+  }
+  const matches = [];
+  const re = /target\s*=\s*(?:"_top"|'_top'|_top\b)/gi;
+  let m;
+  while ((m = re.exec(renderedHtml)) !== null) {
+    matches.push(m[0]);
+  }
+  if (matches.length === 0) return { ok: true, count: 0 };
+  return { ok: false, count: matches.length, matches };
+}
+
+/**
+ * @param {string} sourceTreeRoot - absolute path to the package root
+ *   (e.g. packages/rcf-lite). The lint walks sourceTreeRoot/src/view.
+ * @returns {Promise<{ ok: true, scanned: number } | { ok: false, violations: Array<{ file: string, line: number, snippet: string, key: string }> }>}
+ */
+export async function assertLocalStorageNamespace(sourceTreeRoot) {
+  const viewRoot = join(sourceTreeRoot, 'src', 'view');
+  const files = await listJsFiles(viewRoot);
+  const violations = [];
+  for (const file of files) {
+    const text = await readFile(file, 'utf8');
+    const re = /(?:localStorage|storage|sessionStorage)\s*\.\s*(?:setItem|getItem|removeItem)\s*\(\s*([^,)]+)/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+      const argExpr = m[1].trim();
+      const key = resolveKeyLiteral(argExpr, text);
+      if (key === null) continue;
+      if (!key.startsWith(STORAGE_NS)) {
+        const line = text.slice(0, m.index).split('\n').length;
+        violations.push({ file, line, snippet: m[0], key });
+      }
+    }
+  }
+  if (violations.length > 0) return { ok: false, violations };
+  return { ok: true, scanned: files.length };
+}
+
+/**
+ * Pick a case-insensitive header getter that works whether headers is
+ * a Headers object, a Map, or a plain record.
+ *
+ * @param {Headers | Map<string, string> | Record<string, string>} headers
+ * @returns {(name: string) => string | null | undefined}
+ */
+function pickHeaderGetter(headers) {
+  if (typeof headers.get === 'function') return (name) => headers.get(name);
+  const map = /** @type {Record<string, string>} */ (headers);
+  return (name) => {
+    for (const k of Object.keys(map)) {
+      if (k.toLowerCase() === name.toLowerCase()) return map[k];
+    }
+    return null;
+  };
+}
+
+/**
+ * Parse a CSP header string for a frame-ancestors directive. If the
+ * directive is present, return `{ allowsSameOrigin, raw }` where
+ * allowsSameOrigin is true if the directive contains 'self',
+ * window.location.origin, or '*'. Null if the directive is absent (no
+ * opinion on framing).
+ *
+ * @param {string} csp
+ * @returns {{ allowsSameOrigin: boolean, raw: string } | null}
+ */
+function parseCspFrameAncestors(csp) {
+  const parts = csp.split(';');
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!/^frame-ancestors\b/i.test(trimmed)) continue;
+    const value = trimmed.slice('frame-ancestors'.length).trim();
+    if (value.length === 0) return { allowsSameOrigin: false, raw: trimmed };
+    const tokens = value.split(/\s+/);
+    const allowsSameOrigin = tokens.some((t) => (
+      t === "'self'" || t === '*' || /^https?:\/\//i.test(t)
+    ));
+    return { allowsSameOrigin, raw: trimmed };
+  }
+  return null;
+}
+
+/**
+ * Resolve a storage key argument expression to its literal string if
+ * possible. Returns null when the key is dynamic (we only lint literals,
+ * since a dynamic key already has to be composed from a literal prefix
+ * further up the file to pin the namespace).
+ *
+ * Accepts:
+ *   - "rcf-view:v1:openDetails"
+ *   - 'rcf-view:v1:openDetails'
+ *   - STORAGE_OPEN            -> resolves if `var STORAGE_OPEN = STORAGE_NS + 'openDetails';` or similar
+ *   - STORAGE_NS + 'something'
+ *
+ * @param {string} argExpr - the trimmed argument expression as source
+ * @param {string} fileText - the full file text (for const resolution)
+ * @returns {string | null}
+ */
+function resolveKeyLiteral(argExpr, fileText) {
+  const strLit = argExpr.match(/^(['"`])((?:\\.|(?!\1).)*)\1/);
+  if (strLit) return strLit[2];
+  const addLit = argExpr.match(/^([A-Z_][A-Z0-9_]*)\s*\+\s*(['"`])((?:\\.|(?!\2).)*)\2/);
+  if (addLit) {
+    const base = resolveIdentifier(addLit[1], fileText);
+    if (base === null) return null;
+    return base + addLit[3];
+  }
+  const ident = argExpr.match(/^([A-Z_][A-Z0-9_]*)$/);
+  if (ident) {
+    return resolveIdentifier(ident[1], fileText);
+  }
+  return null;
+}
+
+/**
+ * Resolve a module-level `var X = '...';` or `var X = Y + '...';`
+ * declaration to its literal string.
+ *
+ * @param {string} name
+ * @param {string} fileText
+ * @returns {string | null}
+ */
+function resolveIdentifier(name, fileText) {
+  const re = new RegExp(`(?:var|let|const)\\s+${name}\\s*=\\s*([^;\\n]+)[;\\n]`);
+  const m = fileText.match(re);
+  if (!m) return null;
+  return resolveKeyLiteral(m[1].trim(), fileText);
+}
+
+/**
+ * Walk a directory recursively and return every `.js` file path, excluding
+ * `vendored/` subtrees and `.min.js` artefacts.
+ *
+ * @param {string} dir
+ * @returns {Promise<string[]>}
+ */
+async function listJsFiles(dir) {
+  const out = [];
+  async function walk(d) {
+    let entries;
+    try {
+      entries = await readdir(d, { withFileTypes: true });
+    } catch (err) {
+      if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return;
+      throw err;
+    }
+    for (const e of entries) {
+      const full = join(d, e.name);
+      if (e.isDirectory()) {
+        if (e.name === 'vendored') continue;
+        await walk(full);
+      } else if (e.isFile()) {
+        if (extname(e.name) !== '.js') continue;
+        if (e.name.endsWith('.min.js')) continue;
+        out.push(full);
+      }
+    }
+  }
+  await walk(dir);
+  return out;
+}