@pleri/olam-cli 0.1.175 → 0.1.182

package/host-cp/src/redirect.mjs

@@ -0,0 +1,159 @@
+// redirect.mjs — Phase B3 (plan-chat-spa-supersedes-control-plane).
+//
+// 301 redirect layer that fronts host-cp's HTTP handler. Maps legacy
+// control-plane routes that get deleted in Phase B4 onto their canonical
+// successors so live URLs in operator history / bookmarks / Slack do not
+// 404 after the deletion lands.
+//
+// Redirect rules (allow-listed; closed set):
+//
+//   /plan/:id                  → no-op (falls through to SPA shell;
+//                                plan-chat-spa-side router handles the
+//                                resolver dispatch via useResolveId).
+//                                Implemented as a sentinel so callers
+//                                can short-circuit but the request
+//                                continues to static-serve.
+//   /world/:id                 → 301 /worlds?highlight=:id
+//   /sandbox/:id               → 301 /worlds?highlight=:id
+//   /session/:worldId/plan     → 301 /plan/:worldId
+//
+// EXPLICITLY NOT REDIRECTED (more-specific routes still owned by
+// control-plane until Phase E):
+//   /world/:id/editor          /world/:id/events
+//   /sandbox/:id/editor        /sandbox/:id/events
+//   /inbox/*                   /workspaces/*
+//   /repos                     /runbooks                /design
+//
+// Security (per plan-chat-spa-supersedes-control-plane.md K1 SEC-2):
+//   - Redirect targets are HARDCODED prefixes (`/plan/`, `/worlds`). No
+//     caller-supplied target is ever reflected into Location.
+//   - `:id` segment is validated against RESOLVE_ID_RE before any
+//     reflection into the Location header; invalid shapes → 400, not
+//     301. This kills open-redirect / response-splitting / header-
+//     injection vectors at the door.
+//   - `highlight=<id>` query param uses the SAME shape regex. We do not
+//     trust the inbound URL beyond the regex match (no decoding, no
+//     surrogate pair handling).
+//
+// Returns one of:
+//   { kind: 'redirect', status: 301, location: '<target>' }
+//   { kind: 'bad-request', status: 400, message: '<reason>' }
+//   { kind: 'passthrough' }   — caller continues normal request flow
+
+import { RESOLVE_ID_RE } from './resolver.mjs';
+
+/**
+ * Compute the redirect verdict for a given pathname. Pure function;
+ * does not consume the request body or write the response.
+ *
+ * @param {string} pathname - URL.pathname (no querystring, no hash)
+ * @returns {{ kind: 'redirect', status: 301, location: string }
+ *          | { kind: 'bad-request', status: 400, message: string }
+ *          | { kind: 'passthrough' }}
+ */
+export function evaluateRedirect(pathname) {
+  if (typeof pathname !== 'string' || pathname.length === 0) {
+    return { kind: 'passthrough' };
+  }
+
+  // /session/:worldId/plan → /plan/:worldId
+  // Match BEFORE the catch-all world rules so the `/session/...` prefix
+  // wins. The trailing `/plan` is fixed; only the worldId varies.
+  const sessionMatch = /^\/session\/([^/]+)\/plan\/?$/.exec(pathname);
+  if (sessionMatch) {
+    const worldId = sessionMatch[1];
+    if (!RESOLVE_ID_RE.test(worldId)) {
+      return {
+        kind: 'bad-request',
+        status: 400,
+        message: 'invalid worldId shape on /session/:worldId/plan',
+      };
+    }
+    return {
+      kind: 'redirect',
+      status: 301,
+      location: `/plan/${worldId}`,
+    };
+  }
+
+  // /design → / (Phase E2: the DesignSurface alpha placeholder is retired.
+  // Hardcoded target — no caller reflection. Exact-match only so /designfoo
+  // or /design/sub do not over-match into the redirect.)
+  if (pathname === '/design' || pathname === '/design/') {
+    return { kind: 'redirect', status: 301, location: '/' };
+  }
+
+  // /world/:id (catch-all, EXCLUDING /editor and /events sub-routes)
+  // /sandbox/:id (catch-all, EXCLUDING /editor and /events sub-routes)
+  const worldMatch = /^\/(world|sandbox)\/([^/]+)(\/.*)?$/.exec(pathname);
+  if (worldMatch) {
+    const [, , id, rest] = worldMatch;
+    // KEEP these — control-plane still owns them until Phase E.
+    if (rest === '/editor' || rest === '/events' ||
+        rest?.startsWith('/editor/') || rest?.startsWith('/events/')) {
+      return { kind: 'passthrough' };
+    }
+    if (!RESOLVE_ID_RE.test(id)) {
+      return {
+        kind: 'bad-request',
+        status: 400,
+        message: 'invalid id shape on /(world|sandbox)/:id',
+      };
+    }
+    return {
+      kind: 'redirect',
+      status: 301,
+      location: `/worlds?highlight=${encodeURIComponent(id)}`,
+    };
+  }
+
+  // /plan/:id is intentionally passthrough — the SPA shell serves it
+  // and the SPA-side router (with useResolveId) decides what to mount.
+  // We DO NOT emit a self-loop 301 here. Including the rule for
+  // completeness / future-proofing only.
+  // (No regex needed; the static-serve layer already handles /plan/*
+  // via SPA_PREFIX.)
+
+  return { kind: 'passthrough' };
+}
+
+/**
+ * Apply the redirect verdict to a node:http ServerResponse. Returns
+ * `true` when the response was written (caller must NOT continue);
+ * returns `false` when the caller should continue the normal request
+ * flow.
+ *
+ * @param {import('node:http').ServerResponse} res
+ * @param {ReturnType<typeof evaluateRedirect>} verdict
+ * @returns {boolean} true if response was sent, false to passthrough.
+ */
+export function applyRedirect(res, verdict) {
+  if (verdict.kind === 'passthrough') return false;
+
+  if (verdict.kind === 'redirect') {
+    res.writeHead(301, {
+      Location: verdict.location,
+      // Short cache so bookmarks update once but operator-local mistakes
+      // (typo'd URL) don't pin to a stale redirect forever.
+      'Cache-Control': 'public, max-age=300',
+      'Content-Type': 'text/plain; charset=utf-8',
+    });
+    res.end(`Moved permanently: ${verdict.location}\n`);
+    return true;
+  }
+
+  if (verdict.kind === 'bad-request') {
+    res.writeHead(400, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'Cache-Control': 'no-store',
+    });
+    res.end(JSON.stringify({
+      error: 'bad-request',
+      message: verdict.message,
+    }));
+    return true;
+  }
+
+  // Defensive: unknown verdict shape → fall through silently.
+  return false;
+}

package/host-cp/src/resolver.mjs

@@ -0,0 +1,121 @@
+// resolver.mjs — Phase A A1 (plan-chat-spa-supersedes-control-plane).
+//
+// Disambiguates a single opaque :id supplied on /plan/:id between
+//
+//   - a planning session (planning_sessions.session_id), or
+//   - a crystallized world (planning_artifacts.crystallized_world_id), or
+//   - unresolvable (returns {kind:'unresolved', canonical_id:null}).
+//
+// Used by plan-chat-spa's useResolveId hook (Phase A A2) so the SPA's
+// cold-open path can mount the correct surface without trusting the
+// id-shape (sentinel `sess_*` prefix is a hint, not authority — see
+// plan-chat-spa-supersedes-control-plane.md K1 SEC-1).
+//
+// Single SQL query (UNION ALL) so resolution costs one round-trip even
+// when the id misses both tables. Bearer auth + rate-limit live in the
+// HTTP handler in plan-chat-service.mjs; this helper is pool-pure for
+// unit testability.
+
+/**
+ * Validate the resolver :id shape. Mirrors plan-chat-service.mjs's
+ * SCOPE_ID_RE; tightened to 6-80 chars so an enumeration attacker can't
+ * grind through 1-5 char shapes.
+ */
+export const RESOLVE_ID_RE = /^[A-Za-z0-9._-]{6,80}$/;
+
+/**
+ * Resolve an opaque id against the chunks substrate.
+ *
+ * @param {{ query: (sql: string, params: unknown[]) => Promise<{ rows: unknown[] }> }} pool
+ *   A pg-shaped pool. Tests pass a stub; production passes pg.Pool.
+ * @param {string} id The candidate id.
+ * @returns {Promise<{ kind: 'session' | 'world' | 'unresolved', canonical_id: string | null }>}
+ */
+export async function resolveId(pool, id) {
+  if (typeof id !== 'string' || !RESOLVE_ID_RE.test(id)) {
+    return { kind: 'unresolved', canonical_id: null };
+  }
+
+  // Single round-trip. Both branches return the same shape
+  // (kind, canonical_id) so PG can UNION ALL them without coercion.
+  //
+  // Session branch wins on tie (LIMIT 1 + session ordered first) — a
+  // session id colliding with a world id is unlikely in practice
+  // (worldId is the random docker name; sessionId is uuid-shaped),
+  // but the deterministic ordering closes the K1 collision risk
+  // surfaced in pass 3 review.
+  const sql = `
+    SELECT kind, canonical_id FROM (
+      SELECT 'session' AS kind, session_id AS canonical_id, 1 AS rank
+        FROM planning_sessions
+        WHERE session_id = $1
+      UNION ALL
+      SELECT 'world' AS kind, crystallized_world_id AS canonical_id, 2 AS rank
+        FROM planning_artifacts
+        WHERE crystallized_world_id = $1
+    ) AS resolved
+    ORDER BY rank
+    LIMIT 1
+  `;
+
+  const result = await pool.query(sql, [id]);
+  const row = result.rows && result.rows[0];
+  if (!row) return { kind: 'unresolved', canonical_id: null };
+
+  // Pool stub-friendly: tolerate column names emerging from pg's
+  // case-insensitive identifier handling.
+  const kind = row.kind ?? row.KIND;
+  const canonical_id = row.canonical_id ?? row.CANONICAL_ID;
+  if (kind !== 'session' && kind !== 'world') {
+    return { kind: 'unresolved', canonical_id: null };
+  }
+  if (typeof canonical_id !== 'string' || canonical_id.length === 0) {
+    return { kind: 'unresolved', canonical_id: null };
+  }
+  return { kind, canonical_id };
+}
+
+/**
+ * Token-bucket rate limiter, per bearer principal. Closes the brute-
+ * force enumeration vector that bearer auth alone leaves open (an
+ * authenticated caller could otherwise grind through ids at
+ * line-rate).
+ *
+ * 60 req/min per bearer. Single-process in-memory map (one host-cp
+ * per host); a multi-instance deployment would need a shared store,
+ * but plan-chat-service is single-tenant single-host by design.
+ */
+export function createRateLimiter({
+  capacity = 60,
+  windowMs = 60_000,
+  now = () => Date.now(),
+} = {}) {
+  const buckets = new Map(); // key -> { tokens, lastRefill }
+
+  function take(key) {
+    const t = now();
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = { tokens: capacity, lastRefill: t };
+      buckets.set(key, bucket);
+    }
+    // Refill proportional to elapsed time.
+    const elapsed = t - bucket.lastRefill;
+    if (elapsed > 0) {
+      const refill = (elapsed / windowMs) * capacity;
+      bucket.tokens = Math.min(capacity, bucket.tokens + refill);
+      bucket.lastRefill = t;
+    }
+    if (bucket.tokens < 1) {
+      return { allowed: false, retryAfterMs: Math.ceil((1 - bucket.tokens) * (windowMs / capacity)) };
+    }
+    bucket.tokens -= 1;
+    return { allowed: true, retryAfterMs: 0 };
+  }
+
+  function reset() {
+    buckets.clear();
+  }
+
+  return { take, reset };
+}

package/host-cp/src/router.mjs

@@ -0,0 +1,168 @@
+// host-cp request router.
+//
+// Replaces the long linear `if (url.pathname === ...)` dispatch chain in
+// server.mjs with an ordered route table. The table is walked in
+// registration order, so route PRECEDENCE is preserved exactly as it was
+// in the original if-ladder: the first matching route wins, later routes
+// are never consulted once a match handles the request.
+//
+// Why a table and not a framework:
+//   - host-cp ships with no external HTTP framework (no express/fastify);
+//     this matches the existing zero-dep style.
+//   - The table is a plain data structure, so it is importable + unit
+//     testable WITHOUT booting server.mjs (which spawns docker-events,
+//     the auth poller, and the worlds.db reconciler at import time).
+//   - A route is now a table entry instead of a `return` buried in a
+//     1700-line ladder. That kills the silent route-shadowing class: a
+//     misplaced `return` can no longer swallow a later route, and the
+//     full set of routes is enumerable (see `router.routes()`).
+//
+// Behavior-preservation contract (load-bearing — see
+// __tests__/router.test.mjs):
+//   1. Walk order == registration order == original source order.
+//   2. A route MATCHES when its matcher returns a truthy match value AND
+//      (no method filter OR the method matches). The matcher receives
+//      ({ pathname, method, url }) and returns either a boolean or, for
+//      regex routes, the RegExpMatchArray (truthy) so the handler can read
+//      capture groups.
+//   3. The FIRST matching route is invoked and dispatch STOPS — identical
+//      to `if (cond) { ...; return; }`. The handler owns the response.
+//   4. A route whose path matches but whose METHOD does not is SKIPPED,
+//      and the walk continues — identical to the original
+//      `if (pathMatch && req.method === 'X')` blocks, where a path hit
+//      with the wrong method fell through to the next `if`.
+//   5. If no route matches, dispatch returns `false` so the caller runs
+//      its terminal 404 — identical to the original fall-through.
+//
+// The router does NOT add auth, body parsing, or any middleware semantics.
+// Those stay exactly where they were in server.mjs (pre-auth routes, the
+// auth gate, the plan-chat bypass) — the router only models the part of
+// the chain that was a flat sequence of `if` blocks.
+
+/**
+ * @typedef {object} RouteContext
+ * @property {string} pathname  url.pathname
+ * @property {string} method    req.method (already normalized by node to uppercase)
+ * @property {URL} url          parsed request URL
+ */
+
+/**
+ * A matcher decides whether a route applies to a request, ignoring method.
+ * Returning a non-boolean truthy value (e.g. a RegExpMatchArray) is
+ * forwarded to the handler as `ctx.match` so regex routes can read groups.
+ *
+ * @typedef {(ctx: RouteContext) => (boolean | RegExpMatchArray | null | undefined)} RouteMatcher
+ */
+
+/**
+ * A handler receives the node req/res plus the parsed url, the matched
+ * value (for regex routes), and is responsible for writing the response.
+ * It mirrors the body of an original `if` block. Return value is ignored;
+ * matching alone terminates dispatch (preserving the `if ... return`
+ * semantics where reaching the block always handled the request).
+ *
+ * @typedef {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse, ctx: RouteContext & { match: any }) => unknown | Promise<unknown>} RouteHandler
+ */
+
+/**
+ * @typedef {object} Route
+ * @property {string} name              human label for diagnostics / tests
+ * @property {string[] | null} methods  allowed methods, or null for "any method"
+ * @property {RouteMatcher} match
+ * @property {RouteHandler} handler
+ */
+
+/**
+ * Create an ordered router. Routes are matched in the order they are
+ * registered — register in the SAME order the original if-ladder ran.
+ */
+export function createRouter() {
+  /** @type {Route[]} */
+  const routes = [];
+
+  /**
+   * Register a route. Returns the router for chaining.
+   *
+   * @param {object} spec
+   * @param {string} spec.name
+   * @param {string | string[] | null} [spec.method]  single method, list, or null/omitted for any
+   * @param {string} [spec.path]    exact pathname match (mutually exclusive with prefix/match)
+   * @param {string} [spec.prefix]  pathname.startsWith(prefix) match
+   * @param {RegExp} [spec.pattern] pathname.match(pattern) — match value passed to handler
+   * @param {RouteMatcher} [spec.match]  custom matcher (overrides path/prefix/pattern)
+   * @param {RouteHandler} spec.handler
+   */
+  function register(spec) {
+    const { name, method, path, prefix, pattern } = spec;
+    const handler = spec.handler;
+    if (typeof handler !== 'function') {
+      throw new TypeError(`route "${name}" requires a handler function`);
+    }
+
+    /** @type {string[] | null} */
+    let methods = null;
+    if (Array.isArray(method)) methods = method.slice();
+    else if (typeof method === 'string') methods = [method];
+    // method omitted or null → any method
+
+    /** @type {RouteMatcher} */
+    let match;
+    if (typeof spec.match === 'function') {
+      match = spec.match;
+    } else if (typeof path === 'string') {
+      match = (ctx) => ctx.pathname === path;
+    } else if (typeof prefix === 'string') {
+      match = (ctx) => ctx.pathname.startsWith(prefix);
+    } else if (pattern instanceof RegExp) {
+      match = (ctx) => ctx.pathname.match(pattern);
+    } else {
+      throw new TypeError(
+        `route "${name}" requires one of: path, prefix, pattern, or match`,
+      );
+    }
+
+    routes.push({ name, methods, match, handler });
+    return api;
+  }
+
+  /**
+   * Walk the table in registration order. Invokes the first route whose
+   * matcher is truthy AND whose method filter admits the request, then
+   * stops. A path-match with a non-admitted method is skipped (the walk
+   * continues), preserving the original `if (pathMatch && method===X)`
+   * fall-through.
+   *
+   * @param {import('node:http').IncomingMessage} req
+   * @param {import('node:http').ServerResponse} res
+   * @param {URL} url
+   * @returns {Promise<boolean>} true if a route handled the request, false to fall through to 404
+   */
+  async function dispatch(req, res, url) {
+    const ctx = { pathname: url.pathname, method: req.method ?? 'GET', url };
+    for (const route of routes) {
+      const matched = route.match(ctx);
+      if (!matched) continue;
+      // Path matched. Now gate on method — a mismatch is a SKIP, not a
+      // 405, exactly mirroring the original if-ladder fall-through.
+      if (route.methods !== null && !route.methods.includes(ctx.method)) {
+        continue;
+      }
+      await route.handler(req, res, { ...ctx, match: matched });
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Enumerate registered routes (name + methods + matcher kind) for
+   * diagnostics, audits, and tests. Pure read of the table.
+   *
+   * @returns {Array<{ name: string, methods: string[] | null }>}
+   */
+  function list() {
+    return routes.map((r) => ({ name: r.name, methods: r.methods }));
+  }
+
+  const api = { register, dispatch, list, get size() { return routes.length; } };
+  return api;
+}

package/host-cp/src/serve-only-config.mjs

@@ -0,0 +1,85 @@
+// serve-only-config.mjs — host-cp SERVE-ONLY mode gate (Phase A of
+// host-cp-gke-serve-only-mode).
+//
+// host-cp normally runs as a local operator sidecar coupled to the host's
+// docker daemon + operator-repo + gh-config. On a managed GKE cluster those
+// host-couplings are absent: host-cp only serves plan-chat-spa + the
+// host-native `/api/*` surface; world orchestration runs elsewhere.
+//
+// `OLAM_HOST_CP_SERVE_ONLY=true` switches host-cp into that degraded shape:
+//   - no docker transport connect, no world discovery
+//   - no PlanOrchestrator docker wiring, no pr-merge-poller docker/repo deps
+//   - world-orchestration routes (`/api/world/*`) return a structured 503
+//   - version-status degrades to 'unknown' (no operator-repo)
+//
+// The flag defaults OFF — the local docker/k3d FULL mode is byte-for-byte
+// unchanged. This module is a tiny pure seam so the gate decision can be
+// unit-tested WITHOUT booting server.mjs (which connects docker + binds a
+// port at module load and therefore can't be imported in a test).
+//
+// ONE coarse flag — no granular per-subsystem toggles (plan S1 / YAGNI).
+
+/**
+ * Decide whether host-cp runs in SERVE-ONLY mode.
+ *
+ * Strict `=== 'true'` parse (mirrors the HOST_CP_MODE env-flag convention
+ * in server.mjs): only the literal string `'true'` enables it. Any other
+ * value — unset, `'1'`, `'false'`, `''`, `'TRUE'` — keeps FULL mode so the
+ * default stays OFF and operators can't half-enable it by accident.
+ *
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ *   Environment to read `OLAM_HOST_CP_SERVE_ONLY` from. Defaults to
+ *   `process.env`.
+ * @returns {boolean} `true` when serve-only mode is active.
+ */
+export function isServeOnly(env = process.env) {
+  return env?.OLAM_HOST_CP_SERVE_ONLY === 'true';
+}
+
+/**
+ * Structured 503 body for world-orchestration routes that are unavailable
+ * in serve-only mode. Reuses the host-cp `/api/*` JSON-error shape
+ * (`{ error, message }`) so SPA error handling treats it uniformly.
+ *
+ * @type {{ error: 'orchestration_unavailable', message: string }}
+ */
+export const ORCHESTRATION_UNAVAILABLE = Object.freeze({
+  error: 'orchestration_unavailable',
+  message:
+    'host-cp is in serve-only mode (managed cluster); world orchestration runs elsewhere',
+});
+
+/**
+ * True when `pathname` (+ `method`) is a world-ORCHESTRATION route that must
+ * degrade to a structured 503 in serve-only mode. The surface is wider than
+ * the singular `/api/world/` proxy: it also covers the plural `/api/worlds/`
+ * per-world mutation/read routes (e.g. `POST /api/worlds/<id>/tunnels` which
+ * spawns a real cloudflare tunnel, `DELETE /api/worlds/<id>` which destroys a
+ * world), world creation (`POST /api/worlds`), and the CLI `/v1/worlds/`
+ * routes. Without this breadth a serve-only host-cp on a shared cluster would
+ * execute tunnel/destroy mutations — the opposite of honest degradation.
+ * (CP3 finding: the singular-only guard let POST /api/worlds/<id>/tunnels
+ * open a live public tunnel in serve-only.)
+ *
+ * Deliberately NOT orchestration: `GET`/`HEAD /api/worlds` (the bare LIST
+ * endpoint) — it returns an empty array in serve-only, which is honest.
+ *
+ * @param {unknown} pathname  URL.pathname (no querystring).
+ * @param {string} [method]   HTTP method (defaults 'GET').
+ * @returns {boolean}
+ */
+export function isOrchestrationRoute(pathname, method = 'GET') {
+  if (typeof pathname !== 'string') return false;
+  // Singular /api/world/<id>/... — the per-world CP proxy + /progress.
+  if (pathname.startsWith('/api/world/')) return true;
+  // CLI per-world routes (olam status/logs <world>).
+  if (pathname.startsWith('/v1/worlds/')) return true;
+  // Plural /api/worlds:
+  //   bare LIST (GET/HEAD /api/worlds) → honest [] in serve-only, NOT blocked.
+  //   create (POST /api/worlds) + any per-world subpath (/api/worlds/<id>...) → 503.
+  if (pathname === '/api/worlds') {
+    return method !== 'GET' && method !== 'HEAD';
+  }
+  if (/^\/api\/worlds\/[^/?#]+/.test(pathname)) return true;
+  return false;
+}