@netnodeag/kraftwerk 0.76.0 → 0.78.0

package/dist/server/members.js

@@ -0,0 +1,117 @@
+import { createHash, randomBytes } from "node:crypto";
+import { CloudError, memberVerify } from "../core/cloud.js";
+import { machineLink, servedWorkspace } from "./cloud.js";
+/** The header the relay puts on a member session's requests (a client's own is dropped). */
+export const MEMBER_HEADER = "x-kraftwerk-member";
+const DEFAULT_TTL_MS = 5 * 60_000;
+let ttlMs = DEFAULT_TTL_MS;
+/** How long a verified answer counts as fresh — tests shorten it; no argument restores the default. */
+export function setMemberCacheTtl(ms) {
+    ttlMs = ms ?? DEFAULT_TTL_MS;
+}
+/** By sha256(token) + workspace: the cache keeps no token in the clear. */
+const cache = new Map();
+const inflight = new Map();
+/** Forget every cached answer (tests). */
+export function forgetMemberCache() {
+    cache.clear();
+}
+const keyOf = (token, workspaceId) => `${createHash("sha256").update(token).digest("hex")}\0${workspaceId}`;
+const ROLES = new Set(["owner", "member"]);
+function asMember(v) {
+    const o = (v ?? {});
+    if (typeof o.email !== "string" || typeof o.handle !== "string" || !ROLES.has(String(o.role)))
+        return null;
+    return { email: o.email, handle: o.handle, role: o.role };
+}
+/** Whether `token` is a member of `workspaceId`: the cache within its TTL, else the cloud. */
+export function verifyMember(token, workspaceId) {
+    const key = keyOf(token, workspaceId);
+    const hit = cache.get(key);
+    if (hit && Date.now() - hit.at < ttlMs)
+        return Promise.resolve({ ok: true, member: hit.member });
+    const running = inflight.get(key);
+    if (running)
+        return running;
+    const run = (async () => {
+        const stale = (why) => {
+            const kept = cache.get(key);
+            return kept ? { ok: true, member: kept.member, stale: true } : { ok: false, error: why, drop: false };
+        };
+        const link = machineLink();
+        if (!link)
+            return stale("this machine is not connected to the kraftwerk cloud — members cannot be verified");
+        try {
+            const member = asMember(await memberVerify(link.url, link.creds, token, workspaceId, link.version));
+            if (!member)
+                return stale("the cloud's answer about the member was not understood");
+            cache.set(key, { member, at: Date.now() });
+            return { ok: true, member };
+        }
+        catch (err) {
+            const status = err instanceof CloudError ? err.status : 0;
+            if (status === 401 || status === 403 || status === 404) {
+                cache.delete(key);
+                const why = status === 403 ? "this machine does not host that workspace" : "unknown or revoked member token";
+                return { ok: false, error: `${why}${err.message ? ` (${err.message})` : ""}`, drop: true };
+            }
+            return stale(`could not reach the kraftwerk cloud to verify the member: ${err.message}`);
+        }
+    })();
+    inflight.set(key, run);
+    void run.finally(() => inflight.delete(key));
+    return run;
+}
+const sessions = new Map();
+const WS_ID = /^ws_[A-Za-z0-9_-]{1,64}$/;
+/**
+ * A member's hello: verify the token for the workspace, find the workspace
+ * this daemon serves under that id, and open a session. Its id is what the
+ * relay tags the session's requests with.
+ */
+export async function openMemberSession(token, workspaceId) {
+    if (typeof token !== "string" || !token.startsWith("kwm_") || token.length > 512)
+        return { ok: false, error: "memberToken must be a kwm_… member token" };
+    if (typeof workspaceId !== "string" || !WS_ID.test(workspaceId))
+        return { ok: false, error: "workspaceId must be a ws_… workspace id" };
+    const v = await verifyMember(token, workspaceId);
+    if (!v.ok)
+        return { ok: false, error: v.error };
+    const ws = await servedWorkspace(workspaceId);
+    if (!ws)
+        return { ok: false, error: "this machine does not serve that workspace right now" };
+    const id = randomBytes(24).toString("base64url");
+    sessions.set(id, { token, workspaceId, slug: ws.slug, name: ws.name, member: v.member });
+    return { ok: true, id, member: v.member, workspace: { id: workspaceId, slug: ws.slug, name: ws.name } };
+}
+/** The session behind a request's tag, or undefined. */
+export function memberSession(id) {
+    const s = sessions.get(id);
+    return s ? { member: s.member, workspaceId: s.workspaceId, slug: s.slug } : undefined;
+}
+/**
+ * Before each of a session's requests: still a member? Within the TTL this
+ * is the cache; past it, the cloud (a cloud that cannot be reached keeps the
+ * cached answer). A refusal ends the session.
+ */
+export async function checkMemberSession(id) {
+    const s = sessions.get(id);
+    if (!s)
+        return { ok: false, error: "the member session ended", ended: true };
+    const v = await verifyMember(s.token, s.workspaceId);
+    if (!v.ok && v.drop) {
+        sessions.delete(id);
+        return { ok: false, error: v.error, ended: true };
+    }
+    if (!v.ok)
+        return { ok: false, error: v.error, ended: false };
+    s.member = v.member;
+    // The workspace may have been reopened under another slug meanwhile.
+    const ws = await servedWorkspace(s.workspaceId);
+    if (ws)
+        s.slug = ws.slug;
+    return { ok: true };
+}
+export function closeMemberSession(id) {
+    sessions.delete(id);
+}

package/dist/server/relay.d.ts

@@ -5,7 +5,14 @@ import type { PushMessage } from "./push.js";
  * it, and every request that comes through answered by this daemon's own
  * server — as a request from a network device, never as this machine. So a
  * client needs a paired device's token (or pairs with a code) exactly as on
- * the LAN.
+ * the LAN. Every request is marked `x-kraftwerk-relay: 1`, so a paired
+ * device over the relay counts as a remote caller (trust.ts).
+ *
+ * Or a channel is a remote member's: its first sealed message is
+ * {t:"auth", memberToken, workspaceId} (see members.ts for the answer and
+ * the cache). From then on every request of the channel carries the
+ * session's tag (members.ts MEMBER_HEADER) and is re-checked against the
+ * cache first; a membership the cloud revoked closes the channel.
  *
  * Machine settings live in ~/.kraftwerk/relay.json (owner-only): whether
  * the relay is on, which relay, the machine's key pair, and the secret the
@@ -44,6 +51,19 @@ export interface RelayStatus {
 export declare function readRelaySettings(): Promise<RelaySettings | null>;
 /** Turn the relay on or off (creating the machine's key on first use); `url` switches relays. */
 export declare function setRelay(enabled: boolean, url?: string): Promise<RelaySettings>;
+/**
+ * The machine's key pair and secret, created (with the relay staying off)
+ * when relay.json is missing: the daemon's first start, `kraftwerk login`.
+ * The cloud knows the machine by the same id and secret the relay does; a
+ * damaged file is refused, never overwritten (it holds the id).
+ */
+export declare function ensureRelayKeys(): Promise<RelaySettings>;
+/** The machine's id (its relay id), public key and secret: what the cloud knows it by. */
+export declare function machineCredentials(): Promise<{
+    id: string;
+    key: string;
+    secret: string;
+}>;
 /** wss://host/api/relay/<role> for a cloud URL. */
 export declare const relayEndpoint: (cloudUrl: string, role: "server" | "client") => string;
 /**

package/dist/server/relay.js

@@ -3,9 +3,10 @@ import { promises as fs } from "node:fs";
 import http from "node:http";
 import os from "node:os";
 import path from "node:path";
-import { daemonHandshake, exportKeyPair, generateKeyPair, importKeyPair, relayId, toBase64, fromBase64, } from "../client/relay.js";
+import { daemonHandshake, exportKeyPair, generateKeyPair, importKeyPair, relayId, toBase64, fromBase64, fromBase64Url, } from "../client/relay.js";
 import { CLOUD_DEFAULT_URL } from "../config.js";
 import { dropPushToken } from "../core/devices.js";
+import { checkMemberSession, closeMemberSession, MEMBER_HEADER, openMemberSession } from "./members.js";
 const settingsFile = () => path.join(os.homedir(), ".kraftwerk", "relay.json");
 export async function readRelaySettings() {
     try {
@@ -36,6 +37,34 @@ export async function setRelay(enabled, url) {
     await writeRelaySettings(s);
     return s;
 }
+/**
+ * The machine's key pair and secret, created (with the relay staying off)
+ * when relay.json is missing: the daemon's first start, `kraftwerk login`.
+ * The cloud knows the machine by the same id and secret the relay does; a
+ * damaged file is refused, never overwritten (it holds the id).
+ */
+export async function ensureRelayKeys() {
+    const s = await readRelaySettings();
+    if (s)
+        return s;
+    try {
+        await fs.access(settingsFile());
+        throw new Error(`${settingsFile()} is damaged — fix it or remove it (removing gives this machine a new id)`);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    const pair = await exportKeyPair(await generateKeyPair());
+    const fresh = { enabled: false, url: CLOUD_DEFAULT_URL, ...pair, secret: randomBytes(32).toString("base64url") };
+    await writeRelaySettings(fresh);
+    return fresh;
+}
+/** The machine's id (its relay id), public key and secret: what the cloud knows it by. */
+export async function machineCredentials() {
+    const s = await ensureRelayKeys();
+    return { id: await relayId(fromBase64Url(s.publicKey)), key: s.publicKey, secret: s.secret };
+}
 /** wss://host/api/relay/<role> for a cloud URL. */
 export const relayEndpoint = (cloudUrl, role) => `${cloudUrl.replace(/\/+$/, "").replace(/^http/, "ws")}/api/relay/${role}`;
 /**
@@ -86,6 +115,8 @@ export async function startRelay(opts) {
             return;
         for (const r of conn.inflight.values())
             r.destroy();
+        if (conn.member)
+            closeMemberSession(conn.member);
         conns.delete(c);
         status.clients = conns.size;
     };
@@ -97,9 +128,12 @@ export async function startRelay(opts) {
     /** One tunnelled request, answered by this daemon's own server as a network device's request. */
     const forward = (c, conn, req) => {
         const headers = {};
+        // x-kraftwerk-* are the daemon's own marks (relay, member session): never the client's to set.
         for (const [k, v] of Object.entries(req.headers ?? {}))
-            if (!DROP_REQUEST.has(k.toLowerCase()))
+            if (!DROP_REQUEST.has(k.toLowerCase()) && !k.toLowerCase().startsWith("x-kraftwerk-"))
                 headers[k.toLowerCase()] = String(v);
+        if (conn.member)
+            headers[MEMBER_HEADER] = conn.member;
         const clientHost = typeof req.headers?.host === "string" && /^[A-Za-z0-9.:[\]-]+$/.test(req.headers.host) ? req.headers.host : "relay.invalid";
         // Marked as forwarded: trust.ts never takes a forwarded request for this machine, whatever its peer address.
         Object.assign(headers, { host: `127.0.0.1:${opts.port}`, "x-forwarded-for": "relay", "x-forwarded-host": clientHost, "x-forwarded-proto": "https", "x-kraftwerk-relay": "1" });
@@ -161,8 +195,45 @@ export async function startRelay(opts) {
             dropConn(c);
             return;
         }
-        if (msg.t === "req" && typeof msg.id === "number")
+        if (msg.t === "auth") {
+            if (conn.member || conn.used) {
+                await reply(c, conn, { t: "auth", ok: false, error: "authenticate once, before the first request" });
+                return;
+            }
+            const r = await openMemberSession(msg.memberToken, msg.workspaceId).catch((err) => ({ ok: false, error: err.message }));
+            if (!conns.has(c)) {
+                if (r.ok)
+                    closeMemberSession(r.id);
+                return;
+            }
+            if (!r.ok) {
+                log(`relay: member refused — ${r.error}`);
+                await reply(c, conn, { t: "auth", ok: false, error: r.error });
+                send({ t: "close", c, reason: r.error.slice(0, 100) });
+                dropConn(c);
+                return;
+            }
+            conn.member = r.id;
+            await reply(c, conn, { t: "auth", ok: true, member: r.member, workspace: r.workspace });
+            return;
+        }
+        if (msg.t === "req" && typeof msg.id === "number") {
+            conn.used = true;
+            if (conn.member) {
+                // Past the cache's TTL this asks the cloud again; a revoked membership ends the channel.
+                const check = await checkMemberSession(conn.member);
+                if (!check.ok) {
+                    await reply(c, conn, { t: "fail", id: msg.id, error: check.error });
+                    if (check.ended) {
+                        log(`relay: member session dropped — ${check.error}`);
+                        send({ t: "close", c, reason: check.error.slice(0, 100) });
+                        dropConn(c);
+                    }
+                    return;
+                }
+            }
             forward(c, conn, msg);
+        }
         else if (msg.t === "abort") {
             const r = conn.inflight.get(msg.id);
             conn.inflight.delete(msg.id);

package/dist/server/server.d.ts

@@ -34,8 +34,9 @@ export interface OpenWorkspace {
  * a standalone `kraftwerk ui` exactly one — its default, also reached
  * without a slug, as before. Each open workspace runs in its own Workspace
  * (core/workspace.ts) with its own .env, background jobs (routines, git
- * sync, cloud), registry entry and live state; closing one ends all of that
- * and leaves the others running.
+ * sync), registry entry and live state; closing one ends all of that
+ * and leaves the others running. The daemon's hub also carries the
+ * machine's cloud record (server/cloud.ts), which lists the open workspaces.
  */
 export interface Hub {
     readonly server: http.Server;

package/dist/server/server.js

@@ -3,7 +3,7 @@ import http from "node:http";
 import net from "node:net";
 import path from "node:path";
 import { setDefaultWorkspace, Workspace } from "../core/workspace.js";
-import { cloudGoodbye, cloudGoodbyeAll, startCloudSync, stopCloudSync } from "./cloud.js";
+import { stopMachineCloud } from "./cloud.js";
 import { disposeAllBackends, disposeWorkspaceBackends } from "../core/chat/sessions.js";
 import { markWorkspaceStopped, registerInstance, registerWorkspace, unregisterInstance } from "../core/instances.js";
 import { startGitSync, stopGitSync } from "../core/git.js";
@@ -156,8 +156,8 @@ function installExitHandlers() {
             // Stamp first: unregistering forgets which workspaces this process served.
             markWorkspaceStopped();
             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));
+            // The machine's cloud goodbye is bounded and a no-op outside the daemon, so the exit stays prompt.
+            void stopMachineCloud().finally(() => process.exit(sig === "SIGINT" ? 130 : 143));
         });
     }
     process.once("exit", (code) => {
@@ -258,6 +258,10 @@ export async function startHub(opts) {
                 return json(res, { error: `no workspace "${target.slug}" here` }, 404);
             const { url } = target;
             const trust = await trustOf(req, url, trustOpts);
+            // A member session (members.ts) reaches its one workspace and nothing else: not another, not the hub page.
+            if (trust.kind === "member" && open?.slug !== trust.slug) {
+                return json(res, { error: `a member session reaches only its workspace — /w/${trust.slug}/…` }, 403);
+            }
             const run = (fn) => runInHub(hub, () => (open ? open.ws.run(fn) : fn()));
             if (url.pathname.startsWith("/api/")) {
                 const method = req.method ?? "GET";
@@ -298,6 +302,9 @@ export async function startHub(opts) {
             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");
+            // A socket may name any workspace per message; a member session's scope is per request, so it gets none.
+            if (trust.kind === "member")
+                return void socket.end("HTTP/1.1 403 Forbidden\r\nconnection: close\r\n\r\n");
             if (url.pathname !== "/api/ws") {
                 if (!open)
                     return void socket.destroy();
@@ -345,6 +352,9 @@ export async function startHub(opts) {
                 await hub.close(o.root);
             opts.onChange = notify;
             hubs.delete(hub);
+            // The daemon's machine client (started by `kraftwerk daemon`) says goodbye with the hub it reports.
+            if (opts.daemon)
+                await stopMachineCloud(hub);
             // A connected browser tab (its socket, a keep-alive connection) must not hold the stop open.
             for (const s of [...sockets])
                 s.close();
@@ -408,7 +418,6 @@ export async function startHub(opts) {
             // Best-effort, in the background: none of them may hold up (or, failing, break) the open.
             entry.registered = 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;
@@ -434,8 +443,6 @@ export async function startHub(opts) {
             closeWatches();
             disposeWorkspaceBackends();
             disposeWorkspaceDevs();
-            await cloudGoodbye();
-            stopCloudSync();
         }));
         await entry.registered;
         unregisterInstance(abs);

package/dist/server/trust.d.ts

@@ -1,5 +1,6 @@
 import type http from "node:http";
 import { type Device } from "../core/devices.js";
+import { type Member } from "./members.js";
 /**
  * Who is asking. Every request and socket gets one of:
  *
@@ -17,6 +18,13 @@ import { type Device } from "../core/devices.js";
  * - `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.
+ *   `relay`: the request came through the relay (server/relay.ts marks
+ *   it) — a remote caller, who does not see private routines' chats.
+ * - `member`: a remote member of ONE workspace, over the relay: the relay
+ *   verified their member token with the cloud (server/members.ts) and
+ *   tags each request with the session's random id, which only this
+ *   process knows. Scoped to that workspace: server.ts refuses every other
+ *   address, router.ts every machine-level route.
  * - `none`: anyone else. Gets the web UI's shell (to show the pairing
  *   screen), the protocol description and the pairing route — nothing else.
  */
@@ -25,9 +33,17 @@ export type Trust = {
 } | {
     kind: "device";
     device: Device;
+    relay?: true;
+} | {
+    kind: "member";
+    member: Member;
+    workspaceId: string;
+    slug: string;
 } | {
     kind: "none";
 };
+/** A caller from afar: a member session, or a paired device over the relay. Private routines' chats are not theirs to see. */
+export declare const remoteCaller: (t: Trust) => boolean;
 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;

package/dist/server/trust.js

@@ -1,4 +1,7 @@
 import { deviceForToken } from "../core/devices.js";
+import { MEMBER_HEADER, memberSession } from "./members.js";
+/** A caller from afar: a member session, or a paired device over the relay. Private routines' chats are not theirs to see. */
+export const remoteCaller = (t) => t.kind === "member" || (t.kind === "device" && t.relay === true);
 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]"]);
@@ -34,9 +37,17 @@ export function tokenOf(req, url, allowQuery) {
 /** 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 ?? "";
+    // A member session's tag wins over anything else the request says: its scope must hold whatever token rides along.
+    const tag = req.headers[MEMBER_HEADER];
+    if (typeof tag === "string" && tag) {
+        const s = memberSession(tag);
+        return s ? { kind: "member", member: s.member, workspaceId: s.workspaceId, slug: s.slug } : { kind: "none" };
+    }
     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" };
+    if (!device)
+        return { kind: "none" };
+    return req.headers["x-kraftwerk-relay"] === "1" ? { kind: "device", device, relay: true } : { kind: "device", device };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netnodeag/kraftwerk",
-  "version": "0.76.0",
+  "version": "0.78.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

@@ -177,21 +177,21 @@
         "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, 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: the daemon registers this MACHINE (its relay id) once, and the workspaces it serves ride along. This block only vetoes: `enabled: false` leaves this workspace out of the machine's record. The machine's switch and the cloud's origin are ~/.kraftwerk/cloud.json (`kraftwerk cloud on|off`) and KRAFTWERK_CLOUD_URL; `kraftwerk login` claims the machine.",
       "properties": {
         "enabled": {
           "type": "boolean",
-          "description": "false opts out of the cloud. Default: true"
+          "description": "false leaves this workspace out of the machine's cloud record. Default: true"
         },
         "url": {
           "type": "string",
           "pattern": "^https?://",
-          "description": "Origin of the cloud manager. Default: https://srv.kraftwerk-cloud.netnode.cloud (the KRAFTWERK_CLOUD_URL environment variable wins; \"off\" disables)"
+          "description": "Deprecated: the cloud's origin is the machine's (~/.kraftwerk/cloud.json, KRAFTWERK_CLOUD_URL). Still used, with a warning, when the machine names none."
         },
         "interval": {
           "type": "integer",
           "minimum": 1,
-          "description": "Seconds between heartbeats. Default: 60 (the cloud may raise it)"
+          "description": "Deprecated and ignored: the cloud sets the heartbeat interval."
         }
       }
     }