@netnodeag/kraftwerk 0.77.0 → 0.78.1

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
@@ -42,7 +49,13 @@ export interface RelayStatus {
     since?: string;
 }
 export declare function readRelaySettings(): Promise<RelaySettings | null>;
-/** Turn the relay on or off (creating the machine's key on first use); `url` switches relays. */
+/**
+ * Turn the relay on or off (creating the machine's key on first use).
+ * `url` switches relays explicitly and sticks across off/on. Without it,
+ * turning ON re-derives the URL only while the stored one is the untouched
+ * default — a machine whose cloud is elsewhere (env, cloud.json) then
+ * relays through that cloud, while an explicit `--url` choice is kept.
+ */
 export declare function setRelay(enabled: boolean, url?: string): Promise<RelaySettings>;
 /**
  * The machine's key pair and secret, created (with the relay staying off)

package/dist/server/relay.js

@@ -5,7 +5,9 @@ import os from "node:os";
 import path from "node:path";
 import { daemonHandshake, exportKeyPair, generateKeyPair, importKeyPair, relayId, toBase64, fromBase64, fromBase64Url, } from "../client/relay.js";
 import { CLOUD_DEFAULT_URL } from "../config.js";
+import { machineCloud } from "../core/cloud.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 {
@@ -25,14 +27,22 @@ async function writeRelaySettings(s) {
     await fs.writeFile(tmp, JSON.stringify(s, null, 2), { mode: 0o600 });
     await fs.rename(tmp, file);
 }
-/** Turn the relay on or off (creating the machine's key on first use); `url` switches relays. */
+/**
+ * Turn the relay on or off (creating the machine's key on first use).
+ * `url` switches relays explicitly and sticks across off/on. Without it,
+ * turning ON re-derives the URL only while the stored one is the untouched
+ * default — a machine whose cloud is elsewhere (env, cloud.json) then
+ * relays through that cloud, while an explicit `--url` choice is kept.
+ */
 export async function setRelay(enabled, url) {
     let s = await readRelaySettings();
+    const follow = !url && enabled && (!s || s.url === CLOUD_DEFAULT_URL);
+    const effective = url ?? (follow ? (await machineCloud()).url : undefined);
     if (!s) {
         const pair = await exportKeyPair(await generateKeyPair());
-        s = { enabled, url: url || CLOUD_DEFAULT_URL, ...pair, secret: randomBytes(32).toString("base64url") };
+        s = { enabled, url: effective || CLOUD_DEFAULT_URL, ...pair, secret: randomBytes(32).toString("base64url") };
     }
-    s = { ...s, enabled, ...(url ? { url: url.replace(/\/+$/, "") } : {}) };
+    s = { ...s, enabled, ...(effective ? { url: effective.replace(/\/+$/, "") } : {}) };
     await writeRelaySettings(s);
     return s;
 }
@@ -55,7 +65,7 @@ export async function ensureRelayKeys() {
             throw err;
     }
     const pair = await exportKeyPair(await generateKeyPair());
-    const fresh = { enabled: false, url: CLOUD_DEFAULT_URL, ...pair, secret: randomBytes(32).toString("base64url") };
+    const fresh = { enabled: false, url: (await machineCloud()).url, ...pair, secret: randomBytes(32).toString("base64url") };
     await writeRelaySettings(fresh);
     return fresh;
 }
@@ -114,6 +124,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;
     };
@@ -125,9 +137,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" });
@@ -189,8 +204,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.js

@@ -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();

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,7 +1,7 @@
 {
   "name": "@netnodeag/kraftwerk",
-  "version": "0.77.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",
+  "version": "0.78.1",
+  "description": "Open-source agentic workspace for teams \u2014 where people and AI agents get work done together: agents (Claude Code, Codex, Pi), skills, shared knowledge, repeatable workflows, and deterministic verification",
   "keywords": [
     "agents",
     "workflow",