@netnodeag/kraftwerk 0.64.0 → 0.66.0

package/dist/server/server.js

@@ -1,36 +1,28 @@
-import { existsSync, promises as fs } from "node:fs";
+import { promises as fs } from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import { setDefaultWorkspace, Workspace } from "../core/workspace.js";
-import { publicHostFor, resolveWorkspace, tunnelFor } from "../config.js";
-import { ACCESS_HEADER, verifyAccessToken } from "./access.js";
-import { cloudGoodbye, startCloudSync, stopCloudSync } from "./cloud.js";
-import { disposeAllBackends } from "../core/chat/sessions.js";
+import { cloudGoodbye, cloudGoodbyeAll, startCloudSync, stopCloudSync } from "./cloud.js";
+import { disposeAllBackends, disposeWorkspaceBackends } from "../core/chat/sessions.js";
 import { markWorkspaceStopped, registerInstance, registerWorkspace, unregisterInstance } from "../core/instances.js";
-import { startGitSync } from "../core/git.js";
-import { disposeAllDevs } from "../core/vibeables.js";
+import { startGitSync, stopGitSync } from "../core/git.js";
+import { disposeAllDevs, disposeWorkspaceDevs } from "../core/vibeables.js";
 import { proxyUpgrade, serveVibeable } from "./preview.js";
-import { startRoutineScheduler } from "../core/routines.js";
+import { startRoutineScheduler, stopRoutineScheduler } from "../core/routines.js";
+import { readWorkspaceDotenv } from "../core/env.js";
+import { closeWatches } from "./live.js";
+import { MACHINE_PATHS, runInHub } from "./hub-context.js";
 import { apiRouter } from "./api/index.js";
 import { serveSocket } from "./api/socket.js";
 import { acceptWebSocket } from "./ws.js";
 import { json } from "./api/router.js";
 import { MIME } from "./api/mime.js";
 import { getPkgVersion, RESTART_EXIT_CODE } from "./version.js";
+import { trustOf } from "./trust.js";
+import { targetOf } from "./target.js";
+import { isDir, resolveWorkspace, workspaceSlug } from "../config.js";
 export { RESTART_EXIT_CODE };
-/**
- * Interface to bind. Loopback by default: the UI is unauthenticated and its
- * chat runs coding agents against the repo, so it must not appear on the LAN
- * because someone started it on a laptop in a café. Inside a container the
- * default flips to all interfaces — loopback there would make the published
- * port unreachable while the in-container health check keeps passing, and
- * the port mapping (compose publishes to 127.0.0.1) is the boundary anyway.
- * KRAFTWERK_UI_HOST overrides either way.
- */
-const IN_CONTAINER = existsSync("/.dockerenv") || existsSync("/run/.containerenv");
-const INSPECTOR_HOST = process.env.KRAFTWERK_UI_HOST || (IN_CONTAINER ? "0.0.0.0" : "127.0.0.1");
-const LOOPBACK_NAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
-const LOOPBACK_BIND = LOOPBACK_NAMES.has(INSPECTOR_HOST);
+import { IN_CONTAINER, INSPECTOR_HOST, LOOPBACK_BIND, LOOPBACK_NAMES } from "./bind.js";
 /**
  * Whether the Host header names this server. A loopback bind alone does not
  * keep other sites out: a page on evil.example can re-point that name at
@@ -46,7 +38,7 @@ const LOOPBACK_BIND = LOOPBACK_NAMES.has(INSPECTOR_HOST);
  * browser only sends it after a CORS preflight, which this server never
  * answers, and a form post cannot set headers at all.
  */
-function hostAllowed(req, { publicHost }) {
+function hostAllowed(req) {
     if (!LOOPBACK_BIND)
         return true;
     if (forwardedHost(req))
@@ -55,33 +47,7 @@ function hostAllowed(req, { publicHost }) {
     if (!host)
         return true;
     const name = hostnameOf(host);
-    return LOOPBACK_NAMES.has(name) || name.endsWith(".localhost") || (!!publicHost && name === publicHost);
-}
-/** Whether the browser addressed the public hostname (directly or, via a proxy, in X-Forwarded-Host). */
-function viaPublicHost(req, { publicHost }) {
-    if (!publicHost)
-        return false;
-    const host = forwardedHost(req) || req.headers.host;
-    return !!host && hostnameOf(host) === publicHost;
-}
-/**
- * The Access gate: a request that arrived via the public hostname must
- * carry a valid Cloudflare Access token when `tunnel.access` is configured.
- * Requests addressed to a loopback name are the operator's own browser on
- * this machine and pass; bound to loopback, only the tunnel (or a local
- * proxy) can deliver the public name in the first place. Returns the reason
- * to refuse, or undefined to proceed.
- */
-async function accessRefusal(req, gate) {
-    const { access } = gate;
-    if (!access || !viaPublicHost(req, gate))
-        return undefined;
-    const raw = req.headers[ACCESS_HEADER];
-    const token = Array.isArray(raw) ? raw[0] : raw;
-    if (!token)
-        return "Cloudflare Access token missing";
-    const result = await verifyAccessToken(token, access);
-    return result.ok ? undefined : `Cloudflare Access token refused: ${result.reason}`;
+    return LOOPBACK_NAMES.has(name) || name.endsWith(".localhost");
 }
 /** First X-Forwarded-Host value, or undefined when no proxy set one. */
 function forwardedHost(req) {
@@ -155,91 +121,289 @@ async function serveStatic(res, staticDir, pathname) {
     });
     res.end(buf);
 }
-/** Start the server; resolves once it listens. Runs until the process ends. */
-export async function startInspector(opts) {
-    // Every request, timer and listener below runs in this workspace (see workspace.ts).
-    const ws = setDefaultWorkspace(new Workspace({ outputDir: opts.outputDir, root: opts.root }));
-    // Read once: like the port, the public hostname takes effect on restart.
-    const project = await resolveWorkspace(ws.root).catch(() => null);
-    // This server's own: several servers in one process each guard their own workspace.
-    const gate = { publicHost: (project && publicHostFor(project)) ?? "", access: project ? tunnelFor(project)?.access : undefined };
-    ws.run(() => {
-        startRoutineScheduler();
-        startGitSync();
+/** Other peers count as this machine inside a container (the port mapping is the boundary) or when asked to — the behaviour before devices. */
+const TRUST_NETWORK = IN_CONTAINER || process.env.KRAFTWERK_UI_TRUST_NETWORK === "1";
+/** Every request pairs, this machine's too — behind a local reverse proxy that does not send X-Forwarded-* headers. */
+const REQUIRE_PAIRING = process.env.KRAFTWERK_UI_REQUIRE_PAIRING === "1";
+const hubs = new Set();
+let exitHandlers = false;
+/** Every hub of this process lets go of its workspaces — on SIGINT/SIGTERM and exit (sync parts only there). */
+function installExitHandlers() {
+    if (exitHandlers)
+        return;
+    exitHandlers = true;
+    // Something still running for a workspace that was closed (a late callback) finds its state gone and throws
+    // "workspace closed". That must not take the other workspaces down with it; anything else still crashes, as by default.
+    const closedOnly = (err) => err instanceof Error && err.message === "workspace closed";
+    process.on("unhandledRejection", (err) => {
+        if (closedOnly(err))
+            return;
+        throw err;
+    });
+    process.on("uncaughtException", (err) => {
+        if (closedOnly(err))
+            return;
+        console.error(err);
+        process.exit(1);
     });
-    // Chat agent subprocesses must die with the server — signals bypass
-    // "exit" handlers, so hook the signals themselves.
+    // Chat agent subprocesses must die with the server — signals bypass "exit" handlers, so hook the signals themselves.
     for (const sig of ["SIGINT", "SIGTERM"]) {
         process.once(sig, () => {
             disposeAllBackends();
             disposeAllDevs();
-            unregisterInstance();
+            // Stamp first: unregistering forgets which workspaces this process served.
             markWorkspaceStopped();
-            // The cloud goodbye is bounded (cloudGoodbye) and a no-op without cloud:, so the exit stays prompt.
-            void cloudGoodbye().finally(() => process.exit(sig === "SIGINT" ? 130 : 143));
+            unregisterInstance();
+            // The cloud goodbye is bounded and a no-op without cloud:, so the exit stays prompt.
+            void cloudGoodbyeAll().finally(() => process.exit(sig === "SIGINT" ? 130 : 143));
         });
     }
     process.once("exit", (code) => {
         disposeAllBackends();
         disposeAllDevs();
-        unregisterInstance();
-        // A self-restart (new version) is not a stop — the project stays "running".
+        // A self-restart (new version) is not a stop — the workspaces stay "running".
         if (code !== RESTART_EXIT_CODE)
             markWorkspaceStopped();
+        unregisterInstance();
+    });
+}
+const listen = (server, port) => new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, INSPECTOR_HOST, () => {
+        server.off("error", reject);
+        const addr = server.address();
+        resolve(typeof addr === "object" && addr ? addr.port : port);
     });
-    const server = http.createServer((req, res) => ws.run(() => serve(req, res)));
-    const serve = async (req, res) => {
+});
+/** A small page at a daemon's own address: the open workspaces, each a link. */
+function hubPage(res, open) {
+    const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+    const rows = open.length
+        ? open.map((o) => `<li><a href="${esc(o.url)}/">${esc(o.name)}</a> <code>${esc(o.slug)}</code></li>`).join("")
+        : "<li>No workspace is open. Run <code>kraftwerk ui</code> in a workspace folder.</li>";
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+    res.end(`<!doctype html><meta charset="utf-8"><title>kraftwerk</title><style>body{font:15px/1.6 system-ui,sans-serif;max-width:640px;margin:48px auto;padding:0 16px;color:#1b1b1f}code{color:#46464f}</style><h1>kraftwerk</h1><ul>${rows}</ul>`);
+}
+export async function startHub(opts) {
+    const trustOpts = { trustLoopback: opts.trustLoopback !== false && !REQUIRE_PAIRING, trustNetwork: TRUST_NETWORK };
+    const bySlug = new Map();
+    const aliasServers = new Map();
+    /** The workspace reached without a slug on the hub's own port (standalone: the one it serves). */
+    let fallback;
+    /** Open sockets and the workspace each was opened for: closing that workspace closes them. */
+    const sockets = new Set();
+    const version = await getPkgVersion();
+    installExitHandlers();
+    /** Which open workspace a request is for: its slug, else the port it came in on, else the default. */
+    const pick = (target, portDefault) => target.slug !== undefined ? bySlug.get(target.slug) : portDefault;
+    const handler = (portDefault) => async (req, res) => {
         try {
-            const url = new URL(req.url ?? "/", "http://localhost");
-            if (!hostAllowed(req, gate))
+            if (!hostAllowed(req))
                 return json(res, { error: "unexpected Host header" }, 421);
-            const refusal = await accessRefusal(req, gate);
-            if (refusal)
-                return json(res, { error: refusal }, 401);
+            const target = targetOf(req, new URL(req.url ?? "/", "http://localhost"));
+            const open = pick(target, portDefault());
+            if (target.slug !== undefined && !open)
+                return json(res, { error: `no workspace "${target.slug}" here` }, 404);
+            const { url } = target;
+            const trust = await trustOf(req, url, trustOpts);
+            const run = (fn) => runInHub(hub, () => (open ? open.ws.run(fn) : fn()));
             if (url.pathname.startsWith("/api/")) {
                 const method = req.method ?? "GET";
                 if (method !== "GET" && method !== "HEAD" && !sameOrigin(req))
-                    json(res, { error: "cross-origin request refused" }, 403);
-                else
-                    await apiRouter.handle(req, res, url);
+                    return json(res, { error: "cross-origin request refused" }, 403);
+                if (!open && !MACHINE_PATHS.test(url.pathname)) {
+                    return json(res, { error: "name a workspace: <slug>.localhost or /w/<slug>/", workspaces: [...bySlug.keys()] }, 404);
+                }
+                return await run(() => apiRouter.handle(req, res, url, trust));
+            }
+            // /vibeables/<slug>/… is an app's own files, served for the preview pane — workspace data, so not for unpaired callers.
+            if (url.pathname === "/vibeables" || url.pathname.startsWith("/vibeables/")) {
+                if (trust.kind === "none")
+                    return json(res, { error: "pair this device first", pair: true }, 401);
+                if (!open)
+                    return json(res, { error: "name a workspace: <slug>.localhost or /w/<slug>/" }, 404);
+                return await run(() => serveVibeable(req, res, url));
             }
-            // /vibeables/<slug>/… is an app's own files, served for the preview pane.
-            else if (url.pathname === "/vibeables" || url.pathname.startsWith("/vibeables/"))
-                await serveVibeable(req, res, url);
-            else
-                await serveStatic(res, opts.staticDir, url.pathname);
+            // A daemon's own address lists its workspaces; anywhere else, the web UI's shell (public: an unpaired browser needs it to pair).
+            if (!open && (url.pathname === "/" || url.pathname === "/index.html"))
+                return hubPage(res, [...bySlug.values()]);
+            await serveStatic(res, opts.staticDir, url.pathname);
         }
         catch (err) {
             json(res, { error: err.message }, 500);
         }
     };
     // WebSocket upgrades: the control plane's socket (/api/ws), and a vibeable's dev server (HMR).
-    server.on("upgrade", (req, socket, head) => {
-        if (!hostAllowed(req, gate))
+    const upgrade = (portDefault) => (req, socket, head) => {
+        if (!hostAllowed(req))
             return void socket.destroy();
-        ws.run(() => accessRefusal(req, gate).then(async (refusal) => {
-            if (refusal)
-                return void socket.destroy();
-            if (new URL(req.url ?? "/", "http://localhost").pathname !== "/api/ws")
-                return proxyUpgrade(req, socket, head);
+        (async () => {
+            const target = targetOf(req, new URL(req.url ?? "/", "http://localhost"));
+            const open = pick(target, portDefault());
+            if (target.slug !== undefined && !open)
+                return void socket.end("HTTP/1.1 404 Not Found\r\nconnection: close\r\n\r\n");
+            const { url } = target;
+            const trust = await trustOf(req, url, trustOpts, true);
+            if (trust.kind === "none")
+                return void socket.end("HTTP/1.1 401 Unauthorized\r\nconnection: close\r\n\r\n");
+            if (url.pathname !== "/api/ws") {
+                if (!open)
+                    return void socket.destroy();
+                // The dev server's HMR socket: what it sees is the path without the workspace prefix.
+                req.url = url.pathname + url.search;
+                return runInHub(hub, () => open.ws.run(() => proxyUpgrade(req, socket, head)));
+            }
             // A socket is not covered by CORS: a page from another site could open one, so the Origin must be ours.
             if (!sameOrigin(req))
                 return void socket.end("HTTP/1.1 403 Forbidden\r\nconnection: close\r\n\r\n");
             const conn = acceptWebSocket(req, socket, head);
-            if (conn)
-                serveSocket(conn, ws, await getPkgVersion());
-        }, () => socket.destroy()));
+            if (!conn)
+                return;
+            // The connection's workspace is the one it was opened for; a message may name another (`ws`).
+            // Looked up per message: a workspace closed meanwhile is not served, a reopened one is the new one.
+            const own = open?.slug;
+            const resolve = (slug) => bySlug.get(slug ?? own ?? "")?.ws;
+            const entry = { slug: own, close: () => conn.close(4404, "workspace closed") };
+            sockets.add(entry);
+            conn.onClose(() => sockets.delete(entry));
+            runInHub(hub, () => serveSocket(conn, resolve, version, trust, () => trustOf(req, url, trustOpts, true), hub));
+        })().catch(() => socket.destroy());
+    };
+    const server = http.createServer(handler(() => fallback));
+    server.on("upgrade", upgrade(() => fallback));
+    const port = await listen(server, opts.port);
+    server.once("close", () => {
+        for (const s of aliasServers.values())
+            s.close();
     });
-    return new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.once("close", stopCloudSync);
-        server.listen(opts.port, INSPECTOR_HOST, () => ws.run(() => {
-            const addr = server.address();
-            const port = typeof addr === "object" && addr ? addr.port : opts.port;
-            void registerInstance(port, ws.root);
-            void registerWorkspace(ws.root);
-            void getPkgVersion().then((v) => startCloudSync(port, v));
-            resolve(server);
+    const hub = {
+        server,
+        port,
+        daemon: !!opts.daemon,
+        list: () => [...bySlug.values()],
+        // One open or close at a time: two overlapping opens of a root (the daemon reopening while `kraftwerk ui`
+        // asks, two clicks) must find each other, not make two copies of the workspace.
+        open: (root, o = {}) => serial(() => openNow(root, o)),
+        close: (root) => serial(() => closeNow(root)),
+        async stop() {
+            // Closing for good, not one by one: what was open stays noted for the next start.
+            const notify = opts.onChange;
+            opts.onChange = undefined;
+            for (const o of [...bySlug.values()])
+                await hub.close(o.root);
+            opts.onChange = notify;
+            hubs.delete(hub);
+            // A connected browser tab (its socket, a keep-alive connection) must not hold the stop open.
+            for (const s of [...sockets])
+                s.close();
+            const closing = new Promise((r) => server.close(() => r()));
+            server.closeAllConnections();
+            for (const s of aliasServers.values())
+                s.closeAllConnections();
+            await closing;
+        },
+    };
+    let lock = Promise.resolve();
+    function serial(fn) {
+        const run = lock.then(fn, fn);
+        lock = run.catch(() => { });
+        return run;
+    }
+    /** Tell the daemon what is open; a failure there is reported, the workspace stays as it is. */
+    async function noteChange() {
+        try {
+            await opts.onChange?.(hub);
+        }
+        catch (err) {
+            console.error(`kraftwerk: could not note the open workspaces: ${err.message}`);
+        }
+    }
+    async function openNow(root, o) {
+        // A folder that is gone (or a kraftwerk.yml that does not parse) is refused, not served as an empty workspace.
+        if (!(await isDir(path.resolve(root))))
+            throw new Error(`no such folder: ${root}`);
+        const ws0 = await resolveWorkspace(root);
+        const abs = ws0.root;
+        const already = [...bySlug.values()].find((x) => x.root === abs);
+        if (already)
+            return already;
+        const slug = workspaceSlug(ws0);
+        const clash = bySlug.get(slug);
+        if (clash)
+            throw new Error(`slug "${slug}" is already served for ${clash.root} — set \`slug:\` in one of the two kraftwerk.yml files`);
+        const ws = new Workspace({ outputDir: o.outputDir ?? ws0.outputDir, root: abs, slug, env: readWorkspaceDotenv(abs) });
+        const name = ws0.config.name ?? path.basename(abs);
+        const entry = { slug, root: abs, name, ws, url: opts.daemon ? `http://${slug}.localhost:${port}` : `http://localhost:${port}` };
+        // A daemon also listens on the workspace's own port, so its old address keeps working — when that port is free.
+        const own = ws0.config.port;
+        if (opts.daemon && own && own !== port) {
+            const alias = http.createServer(handler(() => entry));
+            alias.on("upgrade", upgrade(() => entry));
+            try {
+                entry.aliasPort = await listen(alias, own);
+                aliasServers.set(abs, alias);
+            }
+            catch {
+                alias.close();
+            }
+        }
+        bySlug.set(slug, entry);
+        if (!opts.daemon)
+            fallback ??= entry;
+        runInHub(hub, () => ws.run(() => {
+            startRoutineScheduler();
+            startGitSync();
+            // Best-effort, in the background: none of them may hold up (or, failing, break) the open.
+            void registerInstance(entry.aliasPort ?? port, abs, opts.daemon ? { hub: true, slug, url: entry.url } : {}).catch(() => { });
+            void registerWorkspace(abs).catch(() => { });
+            void startCloudSync(entry.url, version).catch(() => { });
         }));
-    });
+        await noteChange();
+        return entry;
+    }
+    async function closeNow(root) {
+        const abs = path.resolve(root);
+        const entry = [...bySlug.values()].find((x) => x.root === abs);
+        if (!entry)
+            return false;
+        bySlug.delete(entry.slug);
+        if (fallback === entry)
+            fallback = undefined;
+        for (const s of [...sockets])
+            if (s.slug === entry.slug)
+                s.close();
+        const alias = aliasServers.get(abs);
+        alias?.close();
+        alias?.closeAllConnections();
+        aliasServers.delete(abs);
+        await runInHub(hub, () => entry.ws.run(async () => {
+            stopRoutineScheduler();
+            stopGitSync();
+            closeWatches();
+            disposeWorkspaceBackends();
+            disposeWorkspaceDevs();
+            await cloudGoodbye();
+            stopCloudSync();
+        }));
+        unregisterInstance(abs);
+        markWorkspaceStopped(abs);
+        entry.ws.close();
+        await noteChange();
+        return true;
+    }
+    hubs.add(hub);
+    return hub;
+}
+/**
+ * A standalone server for one workspace (`kraftwerk ui`, tests): a hub
+ * serving it as its default, reached with or without its slug. Resolves
+ * once it listens.
+ */
+export async function startInspector(opts) {
+    const hub = await startHub({ port: opts.port, staticDir: opts.staticDir, trustLoopback: opts.trustLoopback });
+    const open = await hub.open(opts.root ?? path.dirname(path.resolve(opts.outputDir)), { outputDir: opts.outputDir });
+    // Code that runs outside any request (the CLI side of this process) still finds its workspace.
+    setDefaultWorkspace(open.ws);
+    hub.server.once("close", () => void hub.stop());
+    return hub.server;
 }

package/dist/server/target.d.ts

@@ -0,0 +1,20 @@
+import type http from "node:http";
+/**
+ * Which workspace a request is for. A workspace is addressed by its slug
+ * (see workspaceSlug in config.ts), never by a port:
+ *
+ * - `<slug>.localhost[:port]` — the browser's form on this machine: every
+ *   workspace its own origin, no setup (browsers resolve *.localhost here);
+ * - `/w/<slug>/…` — the path form, one origin for all (where a host name per
+ *   workspace is not available); the prefix is stripped before routing;
+ * - neither — the server's own workspace (a port per workspace, as before).
+ *
+ * The socket names it per message instead (`ws`), see api/socket.ts.
+ */
+export interface Target {
+    /** The slug the request named, if it named one. */
+    slug?: string;
+    /** The request's URL without the `/w/<slug>` prefix. */
+    url: URL;
+}
+export declare function targetOf(req: http.IncomingMessage, url: URL): Target;

package/dist/server/target.js

@@ -0,0 +1,18 @@
+const PATH = /^\/w\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(\/.*)?$/;
+export function targetOf(req, url) {
+    const m = PATH.exec(url.pathname);
+    if (m) {
+        const rest = new URL(url.href);
+        rest.pathname = m[2] ?? "/";
+        return { slug: m[1], url: rest };
+    }
+    const host = req.headers.host ?? "";
+    let name = "";
+    try {
+        name = new URL(`http://${host}`).hostname;
+    }
+    catch { }
+    const label = name.endsWith(".localhost") ? name.slice(0, -".localhost".length) : "";
+    // One label only: a.b.localhost names no workspace.
+    return label && !label.includes(".") ? { slug: label, url } : { url };
+}

package/dist/server/trust.d.ts

@@ -0,0 +1,41 @@
+import type http from "node:http";
+import { type Device } from "../core/devices.js";
+/**
+ * Who is asking. Every request and socket gets one of:
+ *
+ * - `local`: this machine — a loopback peer that addresses a loopback name
+ *   (localhost, 127.0.0.1, ::1) and was not forwarded by a proxy. Everything,
+ *   device management included. The name matters: a page in this machine's
+ *   browser can point its own domain at 127.0.0.1 (DNS rebinding), and its
+ *   requests then come from loopback with Host evil.example — not local. A
+ *   reverse proxy on this machine also connects from loopback; it says so in
+ *   X-Forwarded-For/-Host/-Proto (a proxy that sends none of them must not be
+ *   used — or set KRAFTWERK_UI_REQUIRE_PAIRING=1, which makes every request
+ *   pair). Inside a container — where the published port mapping is the
+ *   boundary — and with KRAFTWERK_UI_TRUST_NETWORK=1, other peers count as
+ *   local too (the behaviour before devices existed).
+ * - `device`: a paired device's token — `Authorization: Bearer` (apps),
+ *   the `kw_device` cookie (a phone's browser, set on pairing), or `?token=`
+ *   on the socket for runtimes whose WebSocket cannot send headers.
+ * - `none`: anyone else. Gets the web UI's shell (to show the pairing
+ *   screen), the protocol description and the pairing route — nothing else.
+ */
+export type Trust = {
+    kind: "local";
+} | {
+    kind: "device";
+    device: Device;
+} | {
+    kind: "none";
+};
+export declare const DEVICE_COOKIE = "kw_device";
+/** The device token a request carries, if any. `?token=` only counts where asked (the socket). */
+export declare function tokenOf(req: http.IncomingMessage, url: URL, allowQuery: boolean): string | undefined;
+export interface TrustOptions {
+    /** A loopback peer is this machine (default). Off, every request needs a token — for tests and hardened setups. */
+    trustLoopback: boolean;
+    /** Non-loopback peers count as local: a container behind its port mapping, or KRAFTWERK_UI_TRUST_NETWORK=1. */
+    trustNetwork: boolean;
+}
+/** The request's trust: this machine (or a trusted network), else a paired device's token, else none. */
+export declare function trustOf(req: http.IncomingMessage, url: URL, opts: TrustOptions, allowQueryToken?: boolean): Promise<Trust>;

package/dist/server/trust.js

@@ -0,0 +1,42 @@
+import { deviceForToken } from "../core/devices.js";
+export const DEVICE_COOKIE = "kw_device";
+const LOOPBACK_PEER = /^(127\.|::1$|::ffff:127\.)/;
+const LOOPBACK_NAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+/** The Host names a loopback name, and no proxy forwarded the request. */
+function addressedLocally(req) {
+    if (req.headers["x-forwarded-for"] || req.headers["x-forwarded-host"] || req.headers["x-forwarded-proto"] || req.headers.forwarded)
+        return false;
+    const host = req.headers.host;
+    if (!host)
+        return false;
+    let name;
+    try {
+        name = new URL(`http://${host}`).hostname;
+    }
+    catch {
+        return false;
+    }
+    return LOOPBACK_NAMES.has(name) || name.endsWith(".localhost");
+}
+/** The device token a request carries, if any. `?token=` only counts where asked (the socket). */
+export function tokenOf(req, url, allowQuery) {
+    const auth = req.headers.authorization;
+    if (auth?.startsWith("Bearer "))
+        return auth.slice(7).trim();
+    const cookie = req.headers.cookie
+        ?.split(";")
+        .map((c) => c.trim())
+        .find((c) => c.startsWith(`${DEVICE_COOKIE}=`));
+    if (cookie)
+        return decodeURIComponent(cookie.slice(DEVICE_COOKIE.length + 1));
+    return allowQuery ? (url.searchParams.get("token") ?? undefined) : undefined;
+}
+/** The request's trust: this machine (or a trusted network), else a paired device's token, else none. */
+export async function trustOf(req, url, opts, allowQueryToken = false) {
+    const peer = req.socket.remoteAddress ?? "";
+    if ((opts.trustLoopback && LOOPBACK_PEER.test(peer) && addressedLocally(req)) || (opts.trustNetwork && !LOOPBACK_PEER.test(peer)))
+        return { kind: "local" };
+    const token = tokenOf(req, url, allowQueryToken);
+    const device = token ? await deviceForToken(token) : null;
+    return device ? { kind: "device", device } : { kind: "none" };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netnodeag/kraftwerk",
-  "version": "0.64.0",
+  "version": "0.66.0",
   "description": "Open-source agentic workspace for teams — where people and AI agents get work done together: agents (Claude Code, Codex, Pi), skills, shared knowledge, repeatable workflows, and deterministic verification",
   "keywords": [
     "agents",

package/schema/kraftwerk.schema.json

@@ -10,6 +10,11 @@
       "type": "string",
       "description": "Display name of the project (\"environment\"), shown in the inspector header and browser tab"
     },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$",
+      "description": "This workspace's address on this machine (<slug>.localhost, /w/<slug>/). Unique per machine. Default: the folder name. Unlike name, it changes only when you mean to move the workspace."
+    },
     "icon": {
       "type": "string",
       "description": "Emoji used as the inspector favicon (browser-tab icon), e.g. \"⚡\""
@@ -161,57 +166,13 @@
         }
       }
     },
-    "public": {
-      "type": "string",
-      "description": "Hostname the inspector is reached at through a tunnel or reverse proxy, e.g. \"https://kw.example.com\". The loopback bind then answers requests carrying that Host even without X-Forwarded-Host (cloudflared sends none)."
-    },
-    "tunnel": {
-      "type": [
-        "object",
-        "null"
-      ],
-      "additionalProperties": false,
-      "description": "Cloudflare Tunnel run by `kraftwerk ui` next to the inspector, so the loopback bind is reachable at `public` without an open port. Needs `public`. Absent = feature off, a bare `tunnel:` = on with defaults.",
-      "properties": {
-        "enabled": {
-          "type": "boolean",
-          "description": "Turn the feature off while keeping the config. Default: true when this block exists"
-        },
-        "name": {
-          "type": "string",
-          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
-          "description": "Name of a locally-managed tunnel (`cloudflared tunnel create <name>` + `cloudflared tunnel route dns <name> <public host>`); cloudflared routes everything to the inspector port. Absent: a dashboard-managed tunnel whose token is read from the TUNNEL_TOKEN environment variable"
-        },
-        "access": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": [
-            "team",
-            "aud"
-          ],
-          "description": "Verify the Cloudflare Access token (Cf-Access-Jwt-Assertion) on every request that arrives via `public`. Recommended: the UI has no login of its own, and with this a removed Access policy fails closed",
-          "properties": {
-            "team": {
-              "type": "string",
-              "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?$",
-              "description": "Zero Trust team name: the subdomain of https://<team>.cloudflareaccess.com"
-            },
-            "aud": {
-              "type": "string",
-              "pattern": "^[a-fA-F0-9]{64}$",
-              "description": "Application Audience (AUD) tag of the Access application, shown on its overview page in the Zero Trust dashboard"
-            }
-          }
-        }
-      }
-    },
     "cloud": {
       "type": [
         "object",
         "null"
       ],
       "additionalProperties": false,
-      "description": "kraftwerk cloud manager — ~/.kraftwerk made reachable over the internet. ON BY DEFAULT: every `kraftwerk ui` registers on start and heartbeats while it runs (name, icon, colour, root, machine, version, public URL, agent and channel roster). `enabled: false` opts out. No credential belongs here: the cloud hands the instance its identity and a claim code (Settings → Cloud), and an unattended server uses KRAFTWERK_CLOUD_TOKEN in .env.",
+      "description": "kraftwerk cloud manager — ~/.kraftwerk made reachable over the internet. ON BY DEFAULT: every `kraftwerk ui` registers on start and heartbeats while it runs (name, icon, colour, root, machine, version, agent and channel roster). `enabled: false` opts out. No credential belongs here: the cloud hands the instance its identity and a claim code (Settings → Cloud), and an unattended server uses KRAFTWERK_CLOUD_TOKEN in .env.",
       "properties": {
         "enabled": {
           "type": "boolean",
@@ -230,4 +191,4 @@
       }
     }
   }
-}\n
+}