@netnodeag/kraftwerk 0.46.2 → 0.48.0

package/dist/cli/ui.js

@@ -4,7 +4,8 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import chalk from "chalk";
-import { absolutePath, resolveProject } from "../config.js";
+import { absolutePath, publicUrlFor, resolveProject } from "../config.js";
+import { startTunnel } from "./tunnel.js";
 import { selfCommand } from "../inspector/self-command.js";
 import { RESTART_EXIT_CODE, startInspector } from "../inspector/server.js";
 /**
@@ -49,7 +50,7 @@ function ensureBuilt() {
 }
 export async function runUi(cwd, opts) {
     if (process.env.KRAFTWERK_UI_SUPERVISED !== "1")
-        return superviseUi(opts);
+        return superviseUi(cwd, opts);
     const staticDir = ensureBuilt();
     const project = await resolveProject(cwd);
     const outputDir = opts.output ? absolutePath(opts.output, cwd) : project.outputDir;
@@ -58,6 +59,9 @@ export async function runUi(cwd, opts) {
     await startInspector({ outputDir, staticDir, port, projectRoot: project.root });
     console.log(`${chalk.green("✔")} Kraftwerk UI: ${chalk.cyan(`http://localhost:${port}`)} ` +
         chalk.dim(`(output: ${outputDir})`));
+    const publicUrl = publicUrlFor(project);
+    if (publicUrl)
+        console.log(`${chalk.green("✔")} Public URL: ${chalk.cyan(publicUrl)}`);
 }
 /**
  * Respawn loop around the real server. Spawns this same bin script via the
@@ -68,18 +72,23 @@ export async function runUi(cwd, opts) {
  * projects start` reports) takes the whole UI down; Ctrl-C signals the
  * foreground group and reaches both anyway.
  */
-async function superviseUi(opts) {
+async function superviseUi(cwd, opts) {
     const { cmd, args } = selfCommand([
         "ui",
         ...(opts.port ? ["--port", opts.port] : []),
         ...(opts.output ? ["--output", opts.output] : []),
     ]);
+    // The tunnel lives with the supervisor, not the server: a self-restart
+    // (new version) swaps the server process and the tunnel stays up.
+    const project = await resolveProject(cwd).catch(() => null);
+    const tunnel = project ? startTunnel(project, opts.port ? Number(opts.port) : (project.config.port ?? 1981)) : undefined;
     for (;;) {
         const child = spawn(cmd, args, {
             stdio: "inherit",
             env: { ...process.env, KRAFTWERK_UI_SUPERVISED: "1" },
         });
         const forward = (sig) => () => {
+            tunnel?.stop();
             child.kill(sig);
         };
         const handlers = { SIGTERM: forward("SIGTERM"), SIGINT: forward("SIGINT") };
@@ -91,6 +100,7 @@ async function superviseUi(opts) {
         process.off("SIGTERM", handlers.SIGTERM);
         process.off("SIGINT", handlers.SIGINT);
         if (result.code !== RESTART_EXIT_CODE) {
+            tunnel?.stop();
             // A signal-killed server is not a clean exit — say so in the exit code
             // (128 + signal, the shell convention) so callers can tell.
             if (result.signal)

package/dist/config.d.ts

@@ -30,6 +30,12 @@
  *     root: kraftwerk-data/repos   # where clones land, relative to the file. Default: repos
  *   vibeables:                 # small apps built live in a chat, rendered in the inspector (absent = off, bare key = on)
  *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
+ *   public: https://kw.example.com   # hostname the inspector is reached at through a tunnel or reverse proxy
+ *   tunnel:                    # Cloudflare Tunnel run by `kraftwerk ui` (absent = off, bare key = on)
+ *     name: kraftwerk          # locally-managed tunnel (cloudflared tunnel create); absent: TUNNEL_TOKEN env, dashboard-managed
+ *     access:                  # verify the Cloudflare Access login on every request that arrives via `public`
+ *       team: acme             # Zero Trust team name (https://<team>.cloudflareaccess.com)
+ *       aud: 4714c135…         # Application Audience tag of the Access application
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export declare const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -96,6 +102,47 @@ export interface VibeablesConfig {
 export declare const VIBEABLES_DEFAULT_ROOT = "kraftwerk-data/vibeables";
 /** Absolute vibeables root when the feature is on, undefined otherwise. */
 export declare function vibeablesRootFor(project: Project): string | undefined;
+/**
+ * Cloudflare Access in front of the public hostname. Access puts a login
+ * page on the hostname at Cloudflare's edge and hands the origin a signed
+ * JWT per request (Cf-Access-Jwt-Assertion). With this block the inspector
+ * verifies that token itself, so a removed or misconfigured Access policy
+ * fails closed instead of exposing the UI, which has no login of its own.
+ */
+export interface AccessConfig {
+    /** Zero Trust team name: the subdomain of https://<team>.cloudflareaccess.com */
+    team: string;
+    /** Application Audience (AUD) tag of the Access application, from its overview page. */
+    aud: string;
+}
+/**
+ * Cloudflare Tunnel: `kraftwerk ui` runs cloudflared next to the inspector
+ * so the loopback bind is reachable at `public` without an open port. The
+ * tunnel itself is created once with cloudflared (or in the Zero Trust
+ * dashboard); this block only says which one to run.
+ */
+export interface TunnelConfig {
+    /** false keeps the block but turns the feature off. Default: true. */
+    enabled?: boolean;
+    /**
+     * 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 comes from the TUNNEL_TOKEN environment variable and whose
+     * route to http://localhost:<port> is configured in the dashboard.
+     */
+    name?: string;
+    /** Verify the Cloudflare Access token on every request that arrives via `public`. */
+    access?: AccessConfig;
+}
+/** The public hostname (lowercase, no port) when `public` is set, undefined otherwise. */
+export declare function publicHostFor(project: Project): string | undefined;
+/** The public origin ("https://kw.example.com") when `public` is set, undefined otherwise. */
+export declare function publicUrlFor(project: Project): string | undefined;
+/** The tunnel block when the feature is on, undefined otherwise. */
+export declare function tunnelFor(project: Project): TunnelConfig | undefined;
+/** "kw.example.com" or "https://kw.example.com[:port]" → its URL; undefined when it is neither. */
+export declare function parsePublic(value: string): URL | undefined;
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export declare function ignoreEntryFor(projectRoot: string, dir: string): string | undefined;
 /** True when .gitignore text already covers the entry (with or without a leading or trailing slash). */
@@ -136,6 +183,14 @@ export interface ProjectConfig {
     repos?: ReposConfig;
     /** Vibeables: apps built live in a chat. Absent = off. */
     vibeables?: VibeablesConfig;
+    /**
+     * 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).
+     */
+    public?: string;
+    /** Cloudflare Tunnel run alongside the inspector. Absent = off. */
+    tunnel?: TunnelConfig;
 }
 export interface Project {
     /** Absolute project root the CLI operates on. */

package/dist/config.js

@@ -34,6 +34,12 @@ import { parse } from "yaml";
  *     root: kraftwerk-data/repos   # where clones land, relative to the file. Default: repos
  *   vibeables:                 # small apps built live in a chat, rendered in the inspector (absent = off, bare key = on)
  *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
+ *   public: https://kw.example.com   # hostname the inspector is reached at through a tunnel or reverse proxy
+ *   tunnel:                    # Cloudflare Tunnel run by `kraftwerk ui` (absent = off, bare key = on)
+ *     name: kraftwerk          # locally-managed tunnel (cloudflared tunnel create); absent: TUNNEL_TOKEN env, dashboard-managed
+ *     access:                  # verify the Cloudflare Access login on every request that arrives via `public`
+ *       team: acme             # Zero Trust team name (https://<team>.cloudflareaccess.com)
+ *       aud: 4714c135…         # Application Audience tag of the Access application
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -78,6 +84,34 @@ export function vibeablesRootFor(project) {
         return undefined;
     return path.resolve(project.root, v.root ?? VIBEABLES_DEFAULT_ROOT);
 }
+/** The public hostname (lowercase, no port) when `public` is set, undefined otherwise. */
+export function publicHostFor(project) {
+    return project.config.public ? parsePublic(project.config.public)?.hostname : undefined;
+}
+/** The public origin ("https://kw.example.com") when `public` is set, undefined otherwise. */
+export function publicUrlFor(project) {
+    return project.config.public ? parsePublic(project.config.public)?.origin : undefined;
+}
+/** The tunnel block when the feature is on, undefined otherwise. */
+export function tunnelFor(project) {
+    const t = project.config.tunnel;
+    if (!t || t.enabled === false)
+        return undefined;
+    return t;
+}
+/** "kw.example.com" or "https://kw.example.com[:port]" → its URL; undefined when it is neither. */
+export function parsePublic(value) {
+    const text = value.trim();
+    try {
+        const url = new URL(/^https?:\/\//i.test(text) ? text : `https://${text}`);
+        if (!url.hostname || url.pathname !== "/" || url.search || url.hash || url.username)
+            return undefined;
+        return url;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export function ignoreEntryFor(projectRoot, dir) {
     const rel = path.relative(projectRoot, path.resolve(projectRoot, dir)).split(path.sep).join("/");
@@ -153,7 +187,7 @@ export async function resolveProject(cwd) {
     const root = gitFallback ?? start;
     return { root, config: {}, outputDir: path.join(root, "output") };
 }
-const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables"];
+const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "public", "tunnel"];
 async function loadConfig(configPath) {
     let raw;
     try {
@@ -204,12 +238,64 @@ async function loadConfig(configPath) {
                 config[key] = {};
             validateRootBlock(configPath, "vibeables", config[key]);
         }
+        else if (key === "public") {
+            if (typeof config[key] !== "string" || !parsePublic(config[key])) {
+                throw new Error(`${path.basename(configPath)}: public must be a hostname or https URL like "https://kw.example.com"`);
+            }
+        }
+        else if (key === "tunnel") {
+            if (config[key] === null)
+                config[key] = {};
+            validateTunnel(configPath, config[key]);
+        }
         else if (typeof config[key] !== "string") {
             throw new Error(`${path.basename(configPath)}: ${key} must be a string`);
         }
     }
+    const tunnel = config.tunnel;
+    if (tunnel && tunnel.enabled !== false && !config.public) {
+        throw new Error(`${path.basename(configPath)}: tunnel needs public: the hostname the tunnel routes to`);
+    }
     return config;
 }
+/** tunnel: { enabled?, name?, access?: { team, aud } } */
+function validateTunnel(configPath, value) {
+    const file = path.basename(configPath);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${file}: tunnel must be a mapping (enabled, name, access)`);
+    }
+    const t = value;
+    for (const key of Object.keys(t)) {
+        if (!["enabled", "name", "access"].includes(key)) {
+            throw new Error(`${file}: tunnel.${key} is unknown (allowed: enabled, name, access)`);
+        }
+    }
+    if (t.enabled !== undefined && typeof t.enabled !== "boolean") {
+        throw new Error(`${file}: tunnel.enabled must be true or false`);
+    }
+    // The name is handed to cloudflared as a positional argument.
+    if (t.name !== undefined && (typeof t.name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(t.name))) {
+        throw new Error(`${file}: tunnel.name must be a plain tunnel name (letters, digits, ".", "_", "-")`);
+    }
+    if (t.access !== undefined) {
+        if (typeof t.access !== "object" || t.access === null || Array.isArray(t.access)) {
+            throw new Error(`${file}: tunnel.access must be a mapping (team, aud)`);
+        }
+        const a = t.access;
+        for (const key of Object.keys(a)) {
+            if (!["team", "aud"].includes(key)) {
+                throw new Error(`${file}: tunnel.access.${key} is unknown (allowed: team, aud)`);
+            }
+        }
+        // The team becomes a hostname (<team>.cloudflareaccess.com).
+        if (typeof a.team !== "string" || !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/i.test(a.team)) {
+            throw new Error(`${file}: tunnel.access.team must be the Zero Trust team name (the subdomain of cloudflareaccess.com)`);
+        }
+        if (typeof a.aud !== "string" || !/^[a-f0-9]{64}$/i.test(a.aud)) {
+            throw new Error(`${file}: tunnel.access.aud must be the 64-character Application Audience tag`);
+        }
+    }
+}
 function validateSwitcher(configPath, value) {
     const file = path.basename(configPath);
     if (!Array.isArray(value)) {

package/dist/dotenv.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The project's `.env`: KEY=VALUE lines next to kraftwerk.yml, loaded into
+ * this process at CLI start (a commander preAction hook in kraftwerk.ts),
+ * so every kraftwerk process sees them and everything it spawns inherits
+ * them — the inspector, the chat agents and routines, workflow runs, the
+ * tunnel (TUNNEL_TOKEN), `requires:` checks.
+ *
+ * A variable already set in the shell wins over the file, the dotenv
+ * convention, with one exception that makes restarts work: a value this
+ * process inherited from an earlier kraftwerk process that itself took it
+ * from a `.env` is not a shell setting. Those keys are listed in
+ * KRAFTWERK_DOTENV_KEYS by whoever injected them, so a restarted server
+ * (the `kraftwerk ui` supervisor respawns it with its own environment)
+ * re-reads the file and applies changed values, and a project launched
+ * from another workspace's inspector drops that workspace's variables
+ * instead of running with them.
+ *
+ * Never synced: `.env` is on the workspace git's deny list (git.ts) and in
+ * the .gitignore `kraftwerk init` writes.
+ */
+export declare const DOTENV_FILE = ".env";
+export declare const DOTENV_MARKER = "KRAFTWERK_DOTENV_KEYS";
+/** Parse dotenv text: comments, `export ` prefixes, single/double quotes, `\n` in double quotes. */
+export declare function parseDotenv(text: string): Record<string, string>;
+export interface DotenvResult {
+    /** Absolute path of the file, undefined when the project has none. */
+    file?: string;
+    /** Keys set from the file. */
+    applied: string[];
+    /** Keys in the file left alone because the shell had set them. */
+    kept: string[];
+    /** Keys an earlier kraftwerk process had injected that this file no longer has. */
+    removed: string[];
+}
+/**
+ * Apply `<root>/.env` to process.env (see the module comment for the
+ * precedence). Idempotent: a second call re-applies the same keys. Without
+ * a file it still drops keys an earlier process injected.
+ */
+export declare function applyDotenv(root: string): Promise<DotenvResult>;

package/dist/dotenv.js

@@ -0,0 +1,84 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * The project's `.env`: KEY=VALUE lines next to kraftwerk.yml, loaded into
+ * this process at CLI start (a commander preAction hook in kraftwerk.ts),
+ * so every kraftwerk process sees them and everything it spawns inherits
+ * them — the inspector, the chat agents and routines, workflow runs, the
+ * tunnel (TUNNEL_TOKEN), `requires:` checks.
+ *
+ * A variable already set in the shell wins over the file, the dotenv
+ * convention, with one exception that makes restarts work: a value this
+ * process inherited from an earlier kraftwerk process that itself took it
+ * from a `.env` is not a shell setting. Those keys are listed in
+ * KRAFTWERK_DOTENV_KEYS by whoever injected them, so a restarted server
+ * (the `kraftwerk ui` supervisor respawns it with its own environment)
+ * re-reads the file and applies changed values, and a project launched
+ * from another workspace's inspector drops that workspace's variables
+ * instead of running with them.
+ *
+ * Never synced: `.env` is on the workspace git's deny list (git.ts) and in
+ * the .gitignore `kraftwerk init` writes.
+ */
+export const DOTENV_FILE = ".env";
+export const DOTENV_MARKER = "KRAFTWERK_DOTENV_KEYS";
+const KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Parse dotenv text: comments, `export ` prefixes, single/double quotes, `\n` in double quotes. */
+export function parseDotenv(text) {
+    const out = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq < 0)
+            continue;
+        const key = line.slice(0, eq).trim().replace(/^export\s+/, "");
+        if (!KEY.test(key))
+            continue;
+        let value = line.slice(eq + 1).trim();
+        if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+            value = value.slice(1, -1).replace(/\\n/g, "\n").replace(/\\t/g, "\t").replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+        }
+        else if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+            value = value.slice(1, -1);
+        }
+        else {
+            // An unquoted value ends at a comment: `PORT=1981 # inspector`.
+            value = value.replace(/\s+#.*$/, "").trim();
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Apply `<root>/.env` to process.env (see the module comment for the
+ * precedence). Idempotent: a second call re-applies the same keys. Without
+ * a file it still drops keys an earlier process injected.
+ */
+export async function applyDotenv(root) {
+    const file = path.join(root, DOTENV_FILE);
+    const text = await readFile(file, "utf8").catch(() => undefined);
+    const parsed = text === undefined ? {} : parseDotenv(text);
+    const injected = new Set((process.env[DOTENV_MARKER] ?? "").split(",").filter(Boolean));
+    const applied = [];
+    const kept = [];
+    for (const [key, value] of Object.entries(parsed)) {
+        // An empty shell value is as good as unset (`requires:` treats it so too).
+        if (!process.env[key] || injected.has(key)) {
+            process.env[key] = value;
+            applied.push(key);
+        }
+        else {
+            kept.push(key);
+        }
+    }
+    const removed = [...injected].filter((key) => !(key in parsed));
+    for (const key of removed)
+        delete process.env[key];
+    if (applied.length > 0)
+        process.env[DOTENV_MARKER] = applied.join(",");
+    else
+        delete process.env[DOTENV_MARKER];
+    return { file: text === undefined ? undefined : file, applied, kept, removed };
+}

package/dist/inspector/access.d.ts

@@ -0,0 +1,32 @@
+import type { AccessConfig } from "../config.js";
+/**
+ * Cloudflare Access token verification for requests that arrive via the
+ * public hostname. Access authenticates the browser at Cloudflare's edge and
+ * forwards a signed JWT per request in Cf-Access-Jwt-Assertion; the signing
+ * keys are public at https://<team>.cloudflareaccess.com/cdn-cgi/access/certs.
+ * Verifying the token here means the inspector, which has no login of its
+ * own, does not have to trust that the policy in the dashboard still exists.
+ *
+ * Dependency-free: RS256 over node:crypto. Keys are cached per team and
+ * refetched when a token names an unknown key id (rotation), at most once
+ * per REFETCH_INTERVAL so a flood of bogus tokens cannot hammer Cloudflare.
+ */
+export declare const ACCESS_HEADER = "cf-access-jwt-assertion";
+export type AccessResult = {
+    ok: true;
+    email?: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Team domain Access issues tokens for. Tests override the certs location. */
+export declare function teamDomain(team: string): string;
+/**
+ * Verify one Access token against the team's keys, the application's
+ * audience and the clock. Returns a reason instead of throwing so the
+ * caller can answer 401 with it; a certs fetch failure is a reason too
+ * (fail closed).
+ */
+export declare function verifyAccessToken(token: string, access: AccessConfig): Promise<AccessResult>;
+/** Forget cached keys (tests). */
+export declare function resetAccessKeys(): void;

package/dist/inspector/access.js

@@ -0,0 +1,121 @@
+import { createPublicKey, verify as verifySignature } from "node:crypto";
+/**
+ * Cloudflare Access token verification for requests that arrive via the
+ * public hostname. Access authenticates the browser at Cloudflare's edge and
+ * forwards a signed JWT per request in Cf-Access-Jwt-Assertion; the signing
+ * keys are public at https://<team>.cloudflareaccess.com/cdn-cgi/access/certs.
+ * Verifying the token here means the inspector, which has no login of its
+ * own, does not have to trust that the policy in the dashboard still exists.
+ *
+ * Dependency-free: RS256 over node:crypto. Keys are cached per team and
+ * refetched when a token names an unknown key id (rotation), at most once
+ * per REFETCH_INTERVAL so a flood of bogus tokens cannot hammer Cloudflare.
+ */
+export const ACCESS_HEADER = "cf-access-jwt-assertion";
+const KEY_TTL = 60 * 60 * 1000;
+const REFETCH_INTERVAL = 10 * 1000;
+const FETCH_TIMEOUT = 5_000;
+const cache = new Map();
+/** Team domain Access issues tokens for. Tests override the certs location. */
+export function teamDomain(team) {
+    return `https://${team}.cloudflareaccess.com`;
+}
+function certsUrl(team) {
+    return process.env.KRAFTWERK_ACCESS_CERTS_URL || `${teamDomain(team)}/cdn-cgi/access/certs`;
+}
+async function fetchKeys(team) {
+    const res = await fetch(certsUrl(team), { signal: AbortSignal.timeout(FETCH_TIMEOUT) });
+    if (!res.ok)
+        throw new Error(`certs endpoint answered ${res.status}`);
+    const body = (await res.json());
+    const keys = new Map();
+    for (const jwk of body.keys ?? []) {
+        if (typeof jwk.kid !== "string" || jwk.kty !== "RSA")
+            continue;
+        try {
+            keys.set(jwk.kid, createPublicKey({ key: jwk, format: "jwk" }));
+        }
+        catch {
+            // One malformed key must not take the rest down.
+        }
+    }
+    return keys;
+}
+async function keyFor(team, kid) {
+    const now = Date.now();
+    let entry = cache.get(team);
+    if (!entry || now - entry.fetchedAt > KEY_TTL) {
+        entry = { keys: await fetchKeys(team), fetchedAt: now, missedAt: 0 };
+        cache.set(team, entry);
+    }
+    const hit = entry.keys.get(kid);
+    if (hit)
+        return hit;
+    if (now - entry.missedAt < REFETCH_INTERVAL)
+        return undefined;
+    entry.missedAt = now;
+    entry.keys = await fetchKeys(team);
+    entry.fetchedAt = now;
+    return entry.keys.get(kid);
+}
+function decodeSegment(seg) {
+    try {
+        const parsed = JSON.parse(Buffer.from(seg, "base64url").toString("utf8"));
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Verify one Access token against the team's keys, the application's
+ * audience and the clock. Returns a reason instead of throwing so the
+ * caller can answer 401 with it; a certs fetch failure is a reason too
+ * (fail closed).
+ */
+export async function verifyAccessToken(token, access) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return { ok: false, reason: "malformed token" };
+    const [h, p, s] = parts;
+    const header = decodeSegment(h);
+    const payload = decodeSegment(p);
+    if (!header || !payload)
+        return { ok: false, reason: "malformed token" };
+    if (header.alg !== "RS256" || typeof header.kid !== "string")
+        return { ok: false, reason: "unsupported token" };
+    let key;
+    try {
+        key = await keyFor(access.team, header.kid);
+    }
+    catch (err) {
+        return { ok: false, reason: `cannot fetch Access keys: ${err.message}` };
+    }
+    if (!key)
+        return { ok: false, reason: "unknown signing key" };
+    let valid = false;
+    try {
+        valid = verifySignature("RSA-SHA256", Buffer.from(`${h}.${p}`), key, Buffer.from(s, "base64url"));
+    }
+    catch {
+        valid = false;
+    }
+    if (!valid)
+        return { ok: false, reason: "bad signature" };
+    if (payload.iss !== teamDomain(access.team))
+        return { ok: false, reason: "wrong issuer" };
+    const aud = payload.aud;
+    const audOk = Array.isArray(aud) ? aud.includes(access.aud) : aud === access.aud;
+    if (!audOk)
+        return { ok: false, reason: "wrong audience" };
+    const now = Math.floor(Date.now() / 1000);
+    if (typeof payload.exp !== "number" || payload.exp <= now)
+        return { ok: false, reason: "token expired" };
+    if (typeof payload.nbf === "number" && payload.nbf > now)
+        return { ok: false, reason: "token not yet valid" };
+    return { ok: true, email: typeof payload.email === "string" ? payload.email : undefined };
+}
+/** Forget cached keys (tests). */
+export function resetAccessKeys() {
+    cache.clear();
+}

package/dist/inspector/server.js

@@ -3,7 +3,8 @@ import http from "node:http";
 import path from "node:path";
 import { attachmentPath, saveAttachment } from "./chat/store.js";
 import { setOutputDir, setProjectRoot, getOutputDir, getProjectRoot } from "./context.js";
-import { resolveProject } from "../config.js";
+import { publicHostFor, publicUrlFor, resolveProject, tunnelFor } from "../config.js";
+import { ACCESS_HEADER, verifyAccessToken } from "./access.js";
 import { listRuns, getRun, readRunFile, deleteRun } from "./runs.js";
 import { canSelfUpdate, startUpdate, updateStatus } from "./update.js";
 import { listWorkflows, getWorkflow } from "./workflows.js";
@@ -99,6 +100,16 @@ 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);
+/**
+ * The hostname from kraftwerk.yml `public`, when set: the name a tunnel or
+ * reverse proxy delivers as Host. A Cloudflare Tunnel forwards the
+ * browser's Host untouched and sets no X-Forwarded-Host, so without this
+ * the loopback bind would refuse every request that came through it. A
+ * rebinding page cannot exploit it: the name is one the operator owns.
+ */
+let publicHost = "";
+/** Access verification for requests arriving via the public hostname (kraftwerk.yml `tunnel.access`). */
+let access;
 /**
  * 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
@@ -123,7 +134,32 @@ function hostAllowed(req) {
     if (!host)
         return true;
     const name = hostnameOf(host);
-    return LOOPBACK_NAMES.has(name) || name.endsWith(".localhost");
+    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) {
+    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) {
+    if (!access || !viaPublicHost(req))
+        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}`;
 }
 /** First X-Forwarded-Host value, or undefined when no proxy set one. */
 function forwardedHost(req) {
@@ -348,6 +384,7 @@ async function handleApi(req, res, url) {
             git: (project?.config.git && project.config.git.enabled !== false) === true,
             repos: (project?.config.repos && project.config.repos.enabled !== false) === true,
             vibeables: (project?.config.vibeables && project.config.vibeables.enabled !== false) === true,
+            publicUrl: (project && publicUrlFor(project)) ?? "",
             switcher,
         });
     }
@@ -1181,10 +1218,14 @@ async function serveStatic(res, staticDir, pathname) {
     res.end(buf);
 }
 /** Start the server; resolves once it listens. Runs until the process ends. */
-export function startInspector(opts) {
+export async function startInspector(opts) {
     setOutputDir(opts.outputDir);
     if (opts.projectRoot)
         setProjectRoot(opts.projectRoot);
+    // Read once: like the port, the public hostname takes effect on restart.
+    const project = await resolveProject(getProjectRoot()).catch(() => null);
+    publicHost = (project && publicHostFor(project)) ?? "";
+    access = project ? tunnelFor(project)?.access : undefined;
     startRoutineScheduler();
     startGitSync();
     // Chat agent subprocesses must die with the server — signals bypass
@@ -1211,6 +1252,9 @@ export function startInspector(opts) {
             const url = new URL(req.url ?? "/", "http://localhost");
             if (!hostAllowed(req))
                 return json(res, { error: "unexpected Host header" }, 421);
+            const refusal = await accessRefusal(req);
+            if (refusal)
+                return json(res, { error: refusal }, 401);
             if (url.pathname.startsWith("/api/"))
                 await handleApi(req, res, url);
             // /vibeables/<slug>/… is an app's own files, served for the preview pane.
@@ -1227,7 +1271,7 @@ export function startInspector(opts) {
     server.on("upgrade", (req, socket, head) => {
         if (!hostAllowed(req))
             return void socket.destroy();
-        proxyUpgrade(req, socket, head);
+        accessRefusal(req).then((refusal) => (refusal ? socket.destroy() : proxyUpgrade(req, socket, head)), () => socket.destroy());
     });
     return new Promise((resolve, reject) => {
         server.once("error", reject);