@abstractframework/continuum 0.3.2 → 0.5.0

package/README.md

@@ -72,7 +72,11 @@ abstractcontinuum
 ```
 
 Open `http://localhost:3002` and sign in with a gateway user and token (the
-connection badge at the bottom of the sidebar). The token is exchanged
+connection badge at the bottom of the sidebar). When your gateway manages
+Continuum (the gateway console's **Apps** screen), open it from there
+instead: the gateway serves it at `/apps/continuum/` on its own port, so a
+remote or headless machine needs one port and one tunnel for the console and
+every app. The token is exchanged
 server-side for an HttpOnly session cookie and never stored in the browser.
 
 The server is configured with launch flags or saved settings (full list in
@@ -85,8 +89,9 @@ abstractcontinuum config get                   # every setting and where it come
 ```
 
 - `--port` (default `3002`), `--host` (default `127.0.0.1`)
-- `--gateway-url` — the gateway this deployment talks to (default
-  `http://127.0.0.1:8080`)
+- `--gateway-url` (aliases `--gateway`, `--url`) — the gateway this
+  deployment talks to (default: the gateway installed on this computer, from
+  `~/.abstractframework/gateway.json`, else `http://127.0.0.1:8080`)
 - `--hub-url` / `--hub-seat` / `--hub-token-file` — the agora hub, your seat
   and its key for the Team page. The hub seat is also on the Settings page.
 
@@ -98,15 +103,43 @@ To point the Board at a project, or to enable executions, see
 Before exposing the console beyond localhost, read
 [docs/security.md](docs/security.md): a signed-in user can redeploy services.
 
+## Responsive layout
+
+Continuum works in a desktop window of any size, on a tablet and on a phone,
+in portrait and landscape. The layout follows the window as you resize it.
+
+| Window width | Layout |
+| --- | --- |
+| 1440 px and wider | Sidebar docked; the Team page shows channels, thread and an open panel side by side; board lanes use the full width |
+| 1024 to 1439 px | Sidebar docked; on the Team page an open panel (Members, Files, …) sits beside the thread and the channel list steps aside |
+| 768 to 1023 px (tablets, narrow windows) | The sidebar becomes a menu: open it with the button at the left of the header |
+| Below 768 px (phones) | One pane at a time: pick a channel, message or report to open it, and use **← Channels** or **← Back to the list** to return |
+
+On phones and in short landscape windows:
+
+- **Team**: the thread keeps the screen, with one bar holding **← Channels**,
+  the channel name and **More**. **More** shows the filters, search, sort,
+  channel actions and the Assistant / Members / Files / Leaderboard / Desk
+  panels. The message box takes the width and Send is an icon button.
+- **Backlog**: each item is a card (title first, actions underneath).
+- **Executions and Inbox**: the list, then the selected item.
+- **Dialogs** (New task, Execute, file viewer) open as sheets from the bottom
+  of the screen with their buttons always visible, above the on-screen
+  keyboard.
+
+On touch screens, buttons, rows and tabs are at least 44 px tall, form fields
+use 16 px text, and messages, reports and specs use the 14 px reading size.
+Escape closes the top dialog or drawer; it never closes the work-item drawer
+while you are typing or editing the spec.
+
 ## Develop from source
 
-The source build resolves the shared UI kit (`@abstractframework/ui-kit`,
+The shared UI kit (`@abstractframework/ui-kit`,
 `@abstractframework/panel-chat`) and the session proxy
-(`@abstractframework/app-server`) from a sibling
-[AbstractUIC](https://github.com/lpalbou/AbstractUIC) checkout:
+(`@abstractframework/app-server`) are regular npm dependencies, so a plain
+clone builds:
 
 ```bash
-git clone https://github.com/lpalbou/AbstractUIC.git abstractuic
 git clone https://github.com/lpalbou/AbstractContinuum.git abstractcontinuum
 cd abstractcontinuum
 npm install
@@ -128,6 +161,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow.
 - [docs/conventions.md](docs/conventions.md) — the work-item grammar the Board reads
 - [docs/security.md](docs/security.md) — trust model (read before deploying)
 - [docs/faq.md](docs/faq.md) / [docs/troubleshooting.md](docs/troubleshooting.md)
+- [Responsive layout](#responsive-layout) — tablets, phones and window sizes
 - [CHANGELOG.md](CHANGELOG.md) — release history
 - [CONTRIBUTING.md](CONTRIBUTING.md) — development workflow
 

package/bin/cli.js

@@ -6,23 +6,26 @@
  * shared app-origin session proxy (first-party cookies + CSRF; tokens never
  * in URLs) — the same @abstractframework/app-server module the observer,
  * flow, and code apps converge on.
+ *
+ * Mountable under the gateway at /apps/continuum/ (the kit's mount
+ * contract): every response announces `X-AbstractFramework-App:
+ * continuum; mount=1`, the page gets `<base href="<base path>/">` and
+ * `base_path`, and every "is this the operator's own computer?" check reads
+ * the kit's requestContext (bin/request_gate.js). Served at `/` on its own
+ * port it works exactly as before.
  */
 
-import * as http from 'http';
-import { readFileSync, existsSync, statSync } from 'fs';
-import { join, extname, dirname } from 'path';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { createGatewaySessionProxy } from '@abstractframework/app-server';
-import { createHubProxy } from './hub_proxy.js';
+import { createContinuumServer } from './server.js';
 import {
   SETTINGS,
   SOURCE_WORDS,
   apply_session_proxy_gates,
   createLiveSettings,
-  createSettingsRoute,
   default_settings_path,
   display_value,
-  expand_home,
   parse_args,
   read_settings_file,
   resolve_settings,
@@ -53,6 +56,10 @@ function help_text() {
     const def = spec.type === 'bool' ? 'off' : spec.default === '' ? 'none' : String(spec.default);
     lines.push(col(left, spec.help));
     lines.push(`${' '.repeat(32)}default ${def}; setting ${spec.key}`);
+    if (spec.key === 'gateway_url') {
+      lines.push(`${' '.repeat(32)}also --gateway <url>, --url <url>; with none set, the gateway`);
+      lines.push(`${' '.repeat(32)}installed on this computer (~/.abstractframework/gateway.json)`);
+    }
     if (spec.key === 'hub_token') {
       lines.push(col('--hub-token-file <path>', 'read the hub token from a file (never printed)'));
       lines.push(`${' '.repeat(32)}setting hub_token`);
@@ -159,169 +166,18 @@ const PORT = AT_START.port.value;
 // binds are an explicit deployment choice (--host).
 const HOST = AT_START.host.value;
 const DEFAULT_GATEWAY_URL = AT_START.gateway_url.value;
-
 // The session proxy reads its hardening gates from the environment only;
 // hand it the resolved values (flag > setting > environment > default).
 apply_session_proxy_gates(AT_START, process.env);
 
-const MIME_TYPES = {
-  '.html': 'text/html',
-  '.js': 'application/javascript',
-  '.css': 'text/css',
-  '.json': 'application/json',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.ico': 'image/x-icon',
-  '.webmanifest': 'application/manifest+json',
-};
-
-function getMimeType(filePath) {
-  const ext = extname(filePath).toLowerCase();
-  return MIME_TYPES[ext] || 'application/octet-stream';
-}
-
-// Content-Security-Policy for the app document (security adversary P1
-// 2026-07-16): untrusted markdown (channel files, messages, attachments)
-// renders in this app, and standard markdown allows remote images — a
-// crafted ![](https://attacker/beacon.png) would beacon the operator's IP
-// and read-timing to an external host the moment a preview opens. img-src
-// 'self' data: kills that class app-wide. script-src 'self' is a backstop
-// belt (the renderer already cannot emit script). ws:/wss: are needed
-// because 'self' does not reliably cover scheme-different WebSocket dials;
-// only our own bundle can open sockets (script-src), so this stays tight.
-const CSP = [
-  "default-src 'self'",
-  "script-src 'self'",
-  "style-src 'self' 'unsafe-inline'", // React style={} attributes
-  "img-src 'self' data:",
-  "font-src 'self' data:",
-  "connect-src 'self' ws: wss:",
-  "object-src 'none'",
-  "base-uri 'self'",
-  "form-action 'self'",
-  "frame-ancestors 'none'",
-].join('; ');
-
-function serveFile(res, filePath) {
-  try {
-    if (!existsSync(filePath) || !statSync(filePath).isFile()) {
-      return false;
-    }
-    const content = readFileSync(filePath);
-    const mime = getMimeType(filePath);
-    const headers = {
-      'Content-Type': mime,
-      'Cache-Control': 'no-cache',
-      'X-Content-Type-Options': 'nosniff',
-    };
-    // CSP is a document policy — attach it where a document loads.
-    if (mime === 'text/html') headers['Content-Security-Policy'] = CSP;
-    res.writeHead(200, headers);
-    res.end(content);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// Cookies abstractcontinuum_gateway_* and header x-abstractcontinuum-csrf
-// derive from appId.
-const gatewaySessionProxy = createGatewaySessionProxy({
-  appId: 'abstractcontinuum',
-  defaultGatewayUrl: DEFAULT_GATEWAY_URL,
-});
-
-// Team page transport: /api/hub/* forwards an allowlisted hub API subset
-// with the OPERATOR seat's key attached server-side (proposal c1692,
-// agency contract c1696 — authorship stays the operator's own).
-// Every hub setting is a getter: a seat saved on the Settings page or with
-// `abstractcontinuum config set` applies without a restart.
-const hubProxy = createHubProxy({
-  hubUrl: () => settings.value('hub_url'),
-  seat: () => settings.value('hub_seat'),
-  keysPath: () => expand_home(settings.value('hub_keys')),
-  token: () => settings.value('hub_token'),
-  allowRemote: () => settings.value('hub_allow_remote'),
-});
-
-// The Settings page's door to this server's own settings (hub seat).
-const settingsRoute = createSettingsRoute({ live: settings });
-
-const server = http.createServer((req, res) => {
-  // Parse against a FIXED base: a malformed Host header (e.g. "a b") makes
-  // new URL throw synchronously, which would kill the whole process from
-  // one bad request (adversarial P1 2026-07-13). The host plays no role in
-  // routing here — only the pathname does.
-  let pathname = '/';
-  let search = '';
-  try {
-    const u = new URL(req.url, 'http://local');
-    pathname = u.pathname;
-    search = u.search;
-  } catch {
-    res.writeHead(400);
-    res.end('Bad Request');
-    return;
-  }
-
-  if (settingsRoute.handle(req, res, pathname)) {
-    return;
-  }
-
-  if (hubProxy.handle(req, res, pathname, search)) {
-    return;
-  }
-
-  if (gatewaySessionProxy.handle(req, res, pathname)) {
-    return;
-  }
-
-  if (pathname.includes('..')) {
-    res.writeHead(400);
-    res.end('Bad Request');
-    return;
-  }
-
-  if (pathname === '/' || pathname === '') {
-    pathname = '/index.html';
-  }
-
-  const filePath = join(DIST_DIR, pathname);
-  if (serveFile(res, filePath)) return;
-  if (serveFile(res, filePath + '.html')) return;
-
-  // SPA fallback
-  if (serveFile(res, join(DIST_DIR, 'index.html'))) return;
-
-  res.writeHead(404);
-  res.end('Not Found');
-});
-
-// Live hub updates: relay browser WebSockets to the hub with the seat key
-// attached server-side (operator c2240 — realtime, not 5s polling).
-server.on('upgrade', (req, socket, head) => {
-  // F7 (dm-99 tail): a raw upgrade socket with no 'error' listener is a
-  // process-killer (browser aborts mid-handshake raise uncaught 'error');
-  // and a rejected relay promise without .catch is an unhandled rejection.
-  socket.on('error', () => {
-    try { socket.destroy(); } catch { /* already gone */ }
-  });
-  void hubProxy.handleUpgrade(req, socket, head).then((handled) => {
-    if (!handled) socket.destroy();
-  }).catch(() => {
-    try { socket.destroy(); } catch { /* already gone */ }
-  });
-});
+const server = createContinuumServer({ settings, distDir: DIST_DIR });
 
 server.listen(PORT, HOST, () => {
   const seat = AT_START.hub_seat;
   console.log(`
 AbstractContinuum is running.
   Local:    http://localhost:${PORT}
-  Gateway:  ${DEFAULT_GATEWAY_URL}
+  Gateway:  ${DEFAULT_GATEWAY_URL} (${SOURCE_WORDS[AT_START.gateway_url.source]})
   Hub seat: ${seat.value} (${SOURCE_WORDS[seat.source]})
   Settings: ${SETTINGS_PATH}
 `);

package/bin/hub_proxy.js

@@ -20,6 +20,11 @@
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import { APP_IDENTITY_HEADER, MountRequestError, identityHeaderValue, rejectUpgrade } from '@abstractframework/app-server';
+import { request_gate } from './request_gate.js';
+
+/** The gateway catalog id this server announces (`/apps/continuum/`). */
+export const APP_ID = 'continuum';
 
 /** Console version for the hub's X-Agora-Client handshake (read once at
  *  boot; "0.0.0" only if package.json is unreadable — the header's job is
@@ -190,30 +195,6 @@ const HUB_ROUTES = [
   { method: 'DELETE', re: /^\/channels\/[A-Za-z0-9_.:-]+\/reputation\/[A-Za-z0-9_.-]+$/ },
 ];
 
-/**
- * Cross-origin refusal (adversary P0, 2026-07-15): the loopback peer gate
- * defends against REMOTE peers, but the browser itself is a loopback peer —
- * a hostile page the operator visits can fire cross-origin fetches and
- * WebSocket handshakes at this proxy (WS handshakes skip CORS preflight
- * entirely), and the seat key rides server-side. Rule: when the browser
- * declares an Origin, it must match the Host the request was addressed to;
- * absent Origin (curl, scripts, same-origin GET navigations) passes — a
- * browser NEVER omits Origin on cross-origin fetch/WS, so the vector this
- * closes cannot dodge the check.
- */
-function origin_allowed(req) {
-  const origin = String((req.headers && req.headers.origin) || '').trim();
-  if (!origin) return true;
-  let parsed;
-  try {
-    parsed = new URL(origin);
-  } catch {
-    return false;
-  }
-  const host = String((req.headers && req.headers.host) || '').trim().toLowerCase();
-  return Boolean(host) && parsed.host.toLowerCase() === host;
-}
-
 function read_seat_key(keys_path, hub_url, seat, token) {
   // An explicit token (--hub-token / --hub-token-file / the hub_token
   // setting, resolved by bin/settings.js) wins over the key store.
@@ -427,13 +408,20 @@ export function createHubProxy(opts) {
       socket.on('error', () => {
         try { socket.destroy(); } catch { /* already gone */ }
       });
+      // Same gate as the HTTP surface (the BROWSER's address, which behind
+      // the gateway is the forwarded one), PLUS the origin gate against the
+      // host the browser addressed — WS handshakes have no CORS preflight,
+      // so without it any page the operator visits could open this relay
+      // and read/write as the operator seat (adversary P0).
+      let gate;
+      try {
+        gate = request_gate(req);
+      } catch (e) {
+        if (!(e instanceof MountRequestError)) throw e;
+        rejectUpgrade(socket, e.status, e.message);
+        return true;
+      }
       try {
-        // Same unforgeable peer gate as the HTTP surface, PLUS the origin
-        // gate — WS handshakes have no CORS preflight, so without it any
-        // page the operator visits could open this relay and read/write
-        // as the operator seat (adversary P0).
-        const peer = String(req.socket && req.socket.remoteAddress ? req.socket.remoteAddress : '');
-        const loopback = peer === '127.0.0.1' || peer === '::1' || peer === '::ffff:127.0.0.1' || peer === '';
         const allow_remote = cfg().allow_remote;
         const seat_key = key();
         let WebSocketServer, WebSocket;
@@ -443,7 +431,15 @@ export function createHubProxy(opts) {
           socket.destroy();
           return true;
         }
-        if ((!loopback && !allow_remote) || !seat_key || !origin_allowed(req)) {
+        if (!gate.loopback && !allow_remote) {
+          rejectUpgrade(socket, 403, 'The hub relay answers this computer only (it authors as the operator seat).');
+          return true;
+        }
+        if (!gate.same_origin) {
+          rejectUpgrade(socket, 403, 'Cross-origin WebSocket to the hub relay refused.');
+          return true;
+        }
+        if (!seat_key) {
           socket.destroy();
           return true;
         }
@@ -451,7 +447,13 @@ export function createHubProxy(opts) {
         // one side of a string-pipe relay ships RSV1 frames the other side
         // never negotiated (live find: browsers/ws clients offer it by
         // default and the pipe corrupts).
-        if (!this._wss) this._wss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+        if (!this._wss) {
+          this._wss = new WebSocketServer({ noServer: true, perMessageDeflate: false });
+          // The 101 announces the app like every other response
+          // (X-AbstractFramework-App: continuum; mount=1).
+          const identity = `${APP_IDENTITY_HEADER}: ${identityHeaderValue(APP_ID)}`;
+          this._wss.on('headers', (headers) => headers.push(identity));
+        }
         const hub_ws_url = cfg().hub_url.replace(/^http/, 'ws') + '/ws';
         const upstream = new WebSocket(hub_ws_url, {
           headers: { Authorization: `Bearer ${seat_key}` },
@@ -532,24 +534,31 @@ export function createHubProxy(opts) {
     handle(req, res, pathname, search) {
       if (!pathname.startsWith('/api/hub/') && pathname !== '/api/hub/meta') return false;
 
-      // Socket-peer gate (entity's c1768 class, applied at the mount): this
-      // proxy authors hub messages AS THE OPERATOR, so a non-loopback peer
-      // reaching it could forge the operator's authorship. Gate on the
-      // connection's REAL peer (unforgeable), never a client-controlled
-      // header. The default 127.0.0.1 bind already prevents remote peers;
-      // this is defense-in-depth if HOST is widened deliberately.
-      const peer = String(req.socket && req.socket.remoteAddress ? req.socket.remoteAddress : '');
-      const loopback = peer === '127.0.0.1' || peer === '::1' || peer === '::ffff:127.0.0.1' || peer === '';
+      // Client gate (entity's c1768 class, applied at the mount): this
+      // proxy authors hub messages AS THE OPERATOR, so a browser on another
+      // machine could forge the operator's authorship. The client is the
+      // kit's requestContext answer (bin/request_gate.js): the socket peer,
+      // or behind the gateway's /apps/continuum/ (a loopback peer) the
+      // address the gateway forwarded — never a header from anyone else.
+      let gate;
+      try {
+        gate = request_gate(req);
+      } catch (e) {
+        if (!(e instanceof MountRequestError)) throw e;
+        res.writeHead(e.status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'bad_request', detail: e.message }));
+        return true;
+      }
       const allow_remote = cfg().allow_remote;
-      if (!loopback && !allow_remote) {
+      if (!gate.loopback && !allow_remote) {
         res.writeHead(403, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'hub_proxy_non_loopback', detail: `Hub proxy refuses non-loopback peer ${peer} (it authors as the operator seat). Start Continuum with --hub-allow-remote only behind a trusted front.` }));
+        res.end(JSON.stringify({ error: 'hub_proxy_non_loopback', detail: `Hub proxy refuses a browser on another machine (${gate.ctx.clientAddress}): it authors as the operator seat. Start Continuum with --hub-allow-remote only behind a trusted front.` }));
         return true;
       }
       // Cross-origin browser requests are refused even from loopback: the
       // browser is a loopback peer, and a hostile page can fire simple
       // POSTs (no preflight) at this surface. Origin-vs-Host is the gate.
-      if (!origin_allowed(req)) {
+      if (!gate.same_origin) {
         res.writeHead(403, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'hub_proxy_cross_origin', detail: 'Cross-origin requests to the hub proxy are refused (the proxy authors as the operator seat).' }));
         return true;

package/bin/request_gate.js

@@ -0,0 +1,43 @@
+/**
+ * "Is this request from this computer, and from this app's own page?" —
+ * the ONE answer every app-local privileged route uses (the hub proxy,
+ * which authors as the operator's seat, and the Settings route, which
+ * steers it).
+ *
+ * Both questions go through @abstractframework/app-server's
+ * `requestContext(req)`: behind the gateway's `/apps/continuum/` the socket
+ * peer is ALWAYS loopback (the gateway), so the socket address says nothing
+ * about the browser. The kit believes the gateway's X-Forwarded-For /
+ * X-Forwarded-Host only from a loopback peer, and answers the browser's
+ * address and the host the browser addressed.
+ *
+ *   - loopback: the BROWSER runs on this computer (`clientIsLoopback`).
+ *   - same_origin: a declared Origin names the host the browser addressed
+ *     (the forwarded host behind the gateway, else the Host header). An
+ *     absent Origin passes: a browser never omits it on a cross-origin
+ *     fetch or WebSocket handshake, so the vector this closes cannot dodge
+ *     the check.
+ *
+ * Throws MountRequestError (status 400) for a malformed forwarded header or
+ * an unknown socket peer; callers refuse the request.
+ */
+
+import { requestContext } from '@abstractframework/app-server';
+
+export function request_gate(req) {
+  const ctx = requestContext(req);
+  return { ctx, loopback: ctx.clientIsLoopback, same_origin: origin_matches(req, ctx.host) };
+}
+
+function origin_matches(req, host) {
+  const origin = String((req.headers && req.headers.origin) || '').trim();
+  if (!origin) return true;
+  let parsed;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    return false;
+  }
+  const want = String(host || '').trim().toLowerCase();
+  return Boolean(want) && parsed.host.toLowerCase() === want;
+}