@netnodeag/kraftwerk 0.76.0 → 0.78.0

package/dist/server/cloud.js

@@ -1,232 +1,326 @@
-import { createHash } from "node:crypto";
 import { promises as fs } from "node:fs";
 import os from "node:os";
-import path from "node:path";
-import { cloudFor, resolveWorkspace } from "../config.js";
-import { workspaceRoot } from "../core/context.js";
-import { perWorkspace, workspaceOpen } from "../core/workspace.js";
-import { listAgents, toSummary } from "../core/agents.js";
-import { listChannels, toChannelSummary } from "../core/channels.js";
-import { tildify } from "../core/instances.js";
-const claimUrlFor = (url, code) => (code ? `${url}/claim/${encodeURIComponent(code)}` : null);
-const REQUEST_TIMEOUT_MS = 8_000;
-const GOODBYE_TIMEOUT_MS = 800;
-/** The client's state, one per workspace: each served workspace registers and heartbeats on its own. */
-const client = perWorkspace(() => ({
-    status: { url: "", state: "off" },
-    identity: null,
+import { resolveWorkspace } from "../config.js";
+import { claimUrlFor, machineCloud, machineGoodbye, machineHeartbeat, machineRegister, machineUnlink, MAX_REPORTED_ROUTINES, retiredCloudDir, unknownMachine, workspaceInvite, } from "../core/cloud.js";
+import { identityString, readIdentity } from "../core/identity.js";
+import { routineReport } from "../core/routines.js";
+import { machineCredentials } from "./relay.js";
+const DEFAULT_INTERVAL = 60;
+const STANDALONE = { url: "", state: "off", reason: "only the daemon registers this machine with the cloud (`kraftwerk daemon start`)" };
+const m = {
+    status: { ...STANDALONE },
+    creds: null,
+    registered: false,
     timer: null,
-    stopped: false,
-    lastRoster: "",
-    /** Where this workspace is reached on this machine, as the cloud lists it. */
-    selfUrl: "",
-    selfVersion: "",
-    startedAt: new Date().toISOString(),
-}));
-export const cloudStatus = () => client().status;
-const cloudDir = () => path.join(os.homedir(), ".kraftwerk", "cloud");
-const identityFile = (url, root) => path.join(cloudDir(), `${createHash("sha1").update(`${url}\n${root}`).digest("hex").slice(0, 16)}.json`);
-async function readIdentity(file) {
-    try {
-        const rec = JSON.parse(await fs.readFile(file, "utf8"));
-        return typeof rec.id === "string" && typeof rec.secret === "string" ? { id: rec.id, secret: rec.secret } : null;
-    }
-    catch {
-        return null;
-    }
+    started: false,
+    owner: null,
+    source: (() => []),
+    version: "",
+    /** The workspace list the cloud last acknowledged, as JSON: sent again only when it differs. */
+    reported: "",
+    /** The routine report the cloud last took, as JSON (claimed only; "" sends it again). */
+    routines: "",
+    /** One round at a time: a timer tick, a sync from the CLI and a workspace change never overlap. */
+    lock: Promise.resolve(),
+    warned: new Set(),
+};
+function serial(fn) {
+    const run = m.lock.then(fn, fn);
+    m.lock = run.catch(() => { });
+    return run;
 }
-async function writeIdentity(file, url, root, id) {
-    try {
-        await fs.mkdir(cloudDir(), { recursive: true });
-        await fs.writeFile(file, JSON.stringify({ ...id, url, root, updatedAt: new Date().toISOString() }), { mode: 0o600 });
+export const cloudStatus = () => m.status;
+/** The open workspaces as the cloud lists them: vetoed ones left out, roots only once claimed. */
+async function entries(withRoots) {
+    const list = [];
+    const ymlUrls = [];
+    for (const o of m.source()) {
+        const ws = await resolveWorkspace(o.root).catch(() => null);
+        const c = ws?.config.cloud;
+        if (c?.enabled === false)
+            continue;
+        if (c?.url)
+            ymlUrls.push(c.url.replace(/\/+$/, ""));
+        list.push({ ...(ws?.config.id ? { id: ws.config.id } : {}), name: o.name, slug: o.slug, ...(withRoots ? { root: o.root } : {}) });
     }
-    catch { } // best-effort — the next start registers again
+    return { list, ymlUrls };
 }
-/** The agents and channels of this workspace, as the cloud lists them. */
-async function roster() {
-    const [agents, channels] = await Promise.all([
-        listAgents().then((l) => l.map(toSummary)).catch(() => []),
-        listChannels().then((l) => l.map(toChannelSummary)).catch(() => []),
-    ]);
-    return { agents, channels };
+const claimed = () => typeof m.status.account === "string" && m.status.account.length > 0;
+/** The routines that ran here, per served workspace with a ws_ id (vetoed ones left out), capped. */
+async function routineEntries() {
+    const out = [];
+    for (const o of m.source()) {
+        const ws = await resolveWorkspace(o.root).catch(() => null);
+        const id = ws?.config.id;
+        if (!id || ws.config.cloud?.enabled === false || !o.ws)
+            continue;
+        // A workspace closing meanwhile throws "workspace closed": it simply reports nothing.
+        const run = o.ws.run.bind(o.ws);
+        const ran = await Promise.resolve()
+            .then(() => run(() => routineReport()))
+            .catch(() => []);
+        for (const r of ran)
+            out.push({ workspaceId: id, ...r });
+        if (out.length >= MAX_REPORTED_ROUTINES)
+            break;
+    }
+    return out.slice(0, MAX_REPORTED_ROUTINES);
 }
-async function post(url, body, timeout = REQUEST_TIMEOUT_MS) {
-    const c = client();
-    const r = await fetch(url, {
-        method: "POST",
-        headers: { "content-type": "application/json", "user-agent": `kraftwerk/${c.selfVersion}` },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(timeout),
-    });
-    const text = await r.text();
-    let data;
-    try {
-        data = text ? JSON.parse(text) : {};
+function warnYml(cloud, ymlUrls) {
+    if (!ymlUrls.length)
+        return;
+    const key = `${cloud.source}:${ymlUrls[0]}`;
+    if (m.warned.has(key))
+        return;
+    m.warned.add(key);
+    if (cloud.source === "kraftwerk.yml") {
+        console.warn(`⚠ kraftwerk.yml cloud.url is deprecated — the cloud is the machine's now: \`kraftwerk cloud on --url ${cloud.url}\` (using ${cloud.url} for now)`);
     }
-    catch {
-        throw new Error(`${r.status} from ${url}: not JSON`);
+    else {
+        console.warn(`⚠ kraftwerk.yml cloud.url (${ymlUrls[0]}) is ignored: the machine's cloud is ${cloud.url} (${cloud.source}); remove it from kraftwerk.yml`);
     }
-    if (!r.ok)
-        throw new Error(data.error ?? `${r.status} from ${url}`);
-    return data;
 }
-/** Register (or re-register) this instance. Returns false when the cloud refused or is unreachable. */
 async function register() {
-    const c = client();
-    const project = await resolveWorkspace(workspaceRoot()).catch(() => null);
-    const cloud = project ? cloudFor(project) : undefined;
-    if (!project || !cloud)
+    const { list, ymlUrls } = await entries(false);
+    const cloud = await machineCloud(ymlUrls);
+    warnYml(cloud, ymlUrls);
+    if (!cloud.enabled) {
+        m.status = { url: cloud.url, state: "off", source: cloud.source, ...(cloud.reason ? { reason: cloud.reason } : {}) };
         return false;
-    const file = identityFile(cloud.url, project.root);
-    c.identity ??= await readIdentity(file);
-    const { agents, channels } = await roster();
-    c.lastRoster = JSON.stringify({ agents, channels });
-    const body = {
-        ...(c.identity ?? {}),
-        name: project.config.name ?? path.basename(project.root),
-        icon: project.config.icon ?? "",
-        color: project.config.color ?? "",
-        root: project.root,
-        rootLabel: tildify(project.root),
-        hostname: os.hostname(),
-        platform: `${process.platform}-${process.arch}`,
-        version: c.selfVersion,
-        url: c.selfUrl,
-        // Part of the cloud's register contract; always "" since the Cloudflare Tunnel was removed (0.65).
-        publicUrl: "",
-        agents,
-        channels,
-        interval: cloud.interval,
-        startedAt: c.startedAt,
-        ...(cloud.token ? { accountToken: cloud.token } : {}),
-    };
+    }
+    const identity = await readIdentity();
     try {
-        const r = await post(`${cloud.url}/api/instances/register`, body);
-        if (!c.identity || c.identity.id !== r.id || c.identity.secret !== r.secret) {
-            c.identity = { id: r.id, secret: r.secret };
-            await writeIdentity(file, cloud.url, project.root, c.identity);
-        }
-        c.status = {
-            url: cloud.url, state: "connected", id: r.id, account: r.account, interval: r.interval, lastSeen: new Date().toISOString(),
-            claimCode: r.claimCode ?? null, claimUrl: claimUrlFor(cloud.url, r.claimCode),
+        m.creds ??= await machineCredentials();
+    }
+    catch (err) {
+        m.status = { url: cloud.url, source: cloud.source, state: "error", error: err.message };
+        return false;
+    }
+    const base = { url: cloud.url, source: cloud.source, id: m.creds.id, machine: identityString(identity) };
+    if (m.status.state === "off" || m.status.url !== cloud.url)
+        m.status = { ...base, state: "connecting" };
+    try {
+        const r = await machineRegister(cloud.url, m.creds, {
+            name: identity.machine,
+            handle: identity.handle,
+            hostname: os.hostname(),
+            platform: `${process.platform}-${process.arch}`,
+            version: m.version,
+        }, list);
+        m.registered = true;
+        m.routines = "";
+        // An unclaimed register carries no roots: the list counts as reported only when that is all the cloud should know.
+        m.reported = r.account ? "" : JSON.stringify(list);
+        m.status = {
+            ...base, state: "connected", account: r.account ?? null, interval: r.interval || DEFAULT_INTERVAL, lastSeen: new Date().toISOString(),
+            claimCode: r.claimCode ?? null, claimUrl: claimUrlFor(cloud.url, r.claimCode), workspaces: list.length,
         };
+        // Already claimed: the roots follow at once.
+        if (claimed())
+            await heartbeat();
         return true;
     }
     catch (err) {
-        c.status = { url: cloud.url, state: "error", error: err.message, ...(c.identity ? { id: c.identity.id } : {}) };
+        m.registered = false;
+        m.status = { ...m.status, ...base, state: "error", error: err.message };
         return false;
     }
 }
 async function heartbeat() {
-    const c = client();
-    if (!c.identity || c.status.state === "off")
+    if (!m.creds || !m.registered)
         return;
-    const { agents, channels } = await roster();
-    const rosterNow = JSON.stringify({ agents, channels });
-    const body = {
-        ...c.identity,
-        version: c.selfVersion,
-        ...(rosterNow !== c.lastRoster ? { agents, channels } : {}),
-    };
+    const wasClaimed = claimed();
+    const { list } = await entries(wasClaimed);
+    const now = JSON.stringify(list);
+    // Routines only while claimed; unclaimed, the next claim sends them afresh.
+    const routines = wasClaimed ? await routineEntries() : null;
+    const ran = routines ? JSON.stringify(routines) : "";
     try {
-        const r = await post(`${c.status.url}/api/instances/heartbeat`, body);
-        c.lastRoster = rosterNow;
-        c.status = {
-            ...c.status, state: "connected", error: undefined, interval: r.interval, lastSeen: new Date().toISOString(),
+        const r = await machineHeartbeat(m.status.url, m.creds, {
+            version: m.version,
+            ...(now !== m.reported ? { workspaces: list } : {}),
+            ...(routines && ran !== m.routines ? { routines } : {}),
+        });
+        m.reported = now;
+        m.routines = ran;
+        m.status = {
+            ...m.status, state: "connected", error: undefined, interval: r.interval || m.status.interval || DEFAULT_INTERVAL, lastSeen: new Date().toISOString(),
             ...(r.account !== undefined ? { account: r.account } : {}),
-            ...(r.claimCode !== undefined ? { claimCode: r.claimCode, claimUrl: claimUrlFor(c.status.url, r.claimCode) } : {}),
+            ...(r.claimCode !== undefined ? { claimCode: r.claimCode, claimUrl: claimUrlFor(m.status.url, r.claimCode) } : {}),
+            workspaces: list.length,
         };
+        // Just claimed: the roots go out now, not a whole interval later.
+        if (!wasClaimed && claimed())
+            await heartbeat();
     }
     catch (err) {
-        const message = err.message;
-        c.status = { ...c.status, state: "error", error: message };
-        // An unknown identity (the cloud lost it) is fixed by registering again, which hands out a new one.
-        if (/unknown instance|wrong instance secret|id and secret required/.test(message)) {
-            c.identity = null;
-            // Not after a goodbye: a stopped client registers nothing again.
-            if (!c.stopped && workspaceOpen())
+        m.status = { ...m.status, state: "error", error: err.message };
+        if (unknownMachine(err)) {
+            m.registered = false;
+            if (m.started)
                 await register();
         }
     }
 }
-/** Schedule the next tick after the effective interval; a failed cloud is retried at the same cadence. */
+/** One round: register when not registered, else heartbeat. */
+const round = () => serial(async () => {
+    if (!m.started)
+        return;
+    if (m.registered)
+        await heartbeat();
+    else
+        await register();
+});
 function schedule() {
-    const c = client();
-    if (c.stopped)
+    if (m.timer)
+        clearTimeout(m.timer);
+    m.timer = null;
+    if (!m.started || m.status.state === "off")
         return;
-    const seconds = c.status.interval && c.status.interval > 0 ? c.status.interval : 60;
-    c.timer = setTimeout(async () => {
-        // Stopped (or the workspace closed) while this timer waited, or while the call below ran: no next round.
-        if (c.stopped || !workspaceOpen())
-            return;
-        if (c.status.state === "connected" || c.status.state === "error") {
-            if (c.identity)
-                await heartbeat();
-            else
-                await register();
-        }
-        if (!c.stopped && workspaceOpen())
-            schedule();
+    const seconds = m.status.interval && m.status.interval > 0 ? m.status.interval : DEFAULT_INTERVAL;
+    m.timer = setTimeout(async () => {
+        m.timer = null;
+        await round();
+        schedule();
     }, seconds * 1000);
-    c.timer.unref();
+    m.timer.unref();
 }
 /**
- * Start the client once the inspector listens. Resolves after the first
- * registration attempt (success or not); the heartbeat loop runs on its
- * own afterwards.
+ * Start the machine client (the daemon, once its workspaces are open).
+ * Resolves after the first registration attempt; the heartbeat runs on its
+ * own afterwards. A second start in the same process is ignored.
  */
-export async function startCloudSync(url, version) {
-    const c = client();
-    c.selfUrl = url;
-    c.selfVersion = version;
-    c.stopped = false;
-    const project = await resolveWorkspace(workspaceRoot()).catch(() => null);
-    const cloud = project ? cloudFor(project) : undefined;
-    if (!cloud) {
-        c.status = { url: "", state: "off" };
-        return;
+export async function startMachineCloud(opts) {
+    if (m.started)
+        return m.status;
+    m.started = true;
+    m.owner = opts.owner ?? null;
+    m.source = opts.workspaces;
+    m.version = opts.version;
+    m.status = { url: "", state: "off" };
+    // The per-workspace identities of before (one record per workspace) are retired with the machine record.
+    await fs.rm(retiredCloudDir(), { recursive: true, force: true }).catch(() => { });
+    // The machine's id exists from the daemon's first start on, with the relay still off.
+    m.creds = await machineCredentials().catch(() => null);
+    await serial(register);
+    schedule();
+    return m.status;
+}
+/**
+ * Settings changed (`kraftwerk cloud on|off`, a URL): turn the client on or
+ * off to match; off says goodbye first. Without a started client (a
+ * standalone server) nothing happens.
+ */
+export async function applyMachineCloud() {
+    if (!m.started)
+        return m.status;
+    const cloud = await machineCloud((await entries(false)).ymlUrls);
+    if (!cloud.enabled || (m.registered && cloud.url !== m.status.url)) {
+        await serial(async () => {
+            if (m.registered && m.creds)
+                await machineGoodbye(m.status.url, m.creds, m.version).catch(() => { });
+            m.registered = false;
+            m.reported = "";
+        });
     }
-    // The workspace may close (or the client stop) while this waits: then it does not register or schedule at all.
-    if (c.stopped || !workspaceOpen())
-        return;
-    c.status = { url: cloud.url, state: "connecting", interval: cloud.interval };
-    await register();
-    if (c.stopped || !workspaceOpen())
-        return;
-    // Until the cloud answers, retry at the configured cadence; once it does, at what it asked for.
-    if (c.status.state !== "connected")
-        c.status.interval = cloud.interval;
+    if (!cloud.enabled) {
+        if (m.timer)
+            clearTimeout(m.timer);
+        m.timer = null;
+        m.status = { url: cloud.url, state: "off", source: cloud.source, ...(cloud.reason ? { reason: cloud.reason } : {}) };
+        return m.status;
+    }
+    if (!m.registered)
+        await serial(register);
+    schedule();
+    return m.status;
+}
+/** A round now (the CLI's `login` waits for a claim): registers when needed, else heartbeats. */
+export async function syncMachineCloud() {
+    if (!m.started)
+        return m.status;
+    if (m.status.state === "off")
+        return applyMachineCloud();
+    await round();
     schedule();
+    return m.status;
 }
-/** Stop the heartbeat loop (server close, tests). */
-export function stopCloudSync() {
-    const c = client();
-    c.stopped = true;
-    if (c.timer)
-        clearTimeout(c.timer);
-    c.timer = null;
+/** Release the claim (`kraftwerk logout`): the cloud hands out a fresh claim code. */
+export async function unlinkMachineCloud() {
+    if (!m.started || m.status.state === "off")
+        return m.status;
+    return serial(async () => {
+        if (!m.registered)
+            await register();
+        if (!m.creds || !m.registered)
+            throw new Error(m.status.error ?? "not registered with the cloud");
+        const r = await machineUnlink(m.status.url, m.creds, m.version);
+        // The next heartbeat sends the list again — without roots now.
+        m.reported = "";
+        m.routines = "";
+        m.status = { ...m.status, account: null, claimCode: r.claimCode ?? null, claimUrl: claimUrlFor(m.status.url, r.claimCode) };
+        return m.status;
+    });
 }
 /**
- * Tell the cloud we are going away, so the record flips to "stopped" now
- * instead of after the grace period. Bounded: an exit handler waits for
- * this, and a slow cloud must not hold the process.
+ * Stop the client and tell the cloud the machine is going away (bounded:
+ * an exit handler waits for this). `owner`: only the client that owner
+ * started (a hub stopping in a test leaves another's alone).
  */
-export async function cloudGoodbye() {
-    const c = client();
-    stopCloudSync();
-    if (!c.identity || c.status.state === "off" || !c.status.url)
+export async function stopMachineCloud(owner) {
+    if (!m.started || (owner !== undefined && owner !== m.owner))
         return;
-    try {
-        await post(`${c.status.url}/api/instances/goodbye`, c.identity, GOODBYE_TIMEOUT_MS);
-    }
-    catch { }
+    m.started = false;
+    if (m.timer)
+        clearTimeout(m.timer);
+    m.timer = null;
+    const { creds, registered } = m;
+    const url = m.status.url;
+    m.registered = false;
+    m.reported = "";
+    m.status = { ...STANDALONE };
+    if (registered && creds && url)
+        await machineGoodbye(url, creds, m.version).catch(() => { });
+}
+/**
+ * What member verification needs (server/members.ts): the cloud's origin,
+ * this machine's credentials. Null when no machine client runs (a
+ * standalone server, the cloud turned off).
+ */
+export function machineLink() {
+    if (!m.started || m.status.state === "off" || !m.creds || !m.status.url)
+        return null;
+    return { url: m.status.url, creds: m.creds, version: m.version };
 }
-/** Every served workspace: stop its heartbeat (the server closes). */
-export function stopAllCloudSync() {
-    for (const [ws] of client.entries())
-        ws.run(stopCloudSync);
+/** The served workspace whose kraftwerk.yml `id` is `id` (vetoed ones not), or null. */
+export async function servedWorkspace(id) {
+    for (const o of m.source()) {
+        const ws = await resolveWorkspace(o.root).catch(() => null);
+        if (ws?.config.id === id && ws.config.cloud?.enabled !== false)
+            return { slug: o.slug, name: o.name, root: o.root };
+    }
+    return null;
 }
-/** Every served workspace says goodbye, in parallel (still bounded per workspace). */
-export async function cloudGoodbyeAll() {
-    await Promise.all(client.entries().map(([ws]) => ws.run(cloudGoodbye)));
+/**
+ * An invite to a served workspace (`kraftwerk invite`): the cloud's machine
+ * path, so only a claimed machine that reports the workspace gets one.
+ * `which` is the workspace's slug or root.
+ */
+export async function createWorkspaceInvite(which, role) {
+    const o = m.source().find((x) => (which.root && x.root === which.root) || (which.slug && x.slug === which.slug));
+    if (!o)
+        throw new Error(`the daemon does not serve ${which.slug ? `"${which.slug}"` : which.root} — open it first (\`kraftwerk ui\` in its folder)`);
+    const ws = await resolveWorkspace(o.root);
+    if (ws.config.cloud?.enabled === false)
+        throw new Error(`${o.slug} is left out of the cloud (cloud.enabled: false in kraftwerk.yml)`);
+    const id = ws.config.id;
+    if (!id)
+        throw new Error(`${o.slug} has no workspace id (ws_…) in kraftwerk.yml — run \`kraftwerk doctor --fix\``);
+    const link = machineLink();
+    if (!link)
+        throw new Error(m.status.reason ? `the cloud is off: ${m.status.reason}` : "this machine is not connected to the kraftwerk cloud — `kraftwerk daemon start`");
+    if (!claimed())
+        throw new Error("this machine is not claimed — run `kraftwerk login` first");
+    const invite = await workspaceInvite(link.url, link.creds, id, role, link.version);
+    return { ...invite, workspace: { id, slug: o.slug, name: o.name } };
 }

package/dist/server/hub-context.d.ts

@@ -1,7 +1,7 @@
 import type { Hub } from "./server.js";
 export declare const runInHub: <T>(hub: Hub, fn: () => T) => T;
 export declare function currentHub(): Hub;
-/** API paths that need no workspace: the machine's own (the hub, devices and pairing, the protocol, the socket). */
+/** API paths that need no workspace: the machine's own (the hub, devices and pairing, the cloud record, the protocol, the socket). */
 export declare const MACHINE_PATHS: RegExp;
 /** Route names callable over the socket without a workspace. */
 export declare const MACHINE_ROUTES: RegExp;

package/dist/server/hub-context.js

@@ -12,7 +12,7 @@ export function currentHub() {
         throw new Error("no hub here");
     return hub;
 }
-/** API paths that need no workspace: the machine's own (the hub, devices and pairing, the protocol, the socket). */
-export const MACHINE_PATHS = /^\/api\/(hub(\/|$)|pair$|devices(\/|$)|protocol$|ws$)/;
+/** API paths that need no workspace: the machine's own (the hub, devices and pairing, the cloud record, the protocol, the socket). */
+export const MACHINE_PATHS = /^\/api\/(hub(\/|$)|pair$|devices(\/|$)|cloud(\/|$)|protocol$|ws$)/;
 /** Route names callable over the socket without a workspace. */
-export const MACHINE_ROUTES = /^(hub|devices|protocol)\./;
+export const MACHINE_ROUTES = /^(hub|devices|cloud|protocol)\./;

package/dist/server/members.d.ts

@@ -0,0 +1,87 @@
+import { type MemberVerdict } from "../core/cloud.js";
+/**
+ * Remote members: people who joined a workspace by invite in the cloud and
+ * have no clone of it. They hold a workspace-scoped member token (`kwm_…`)
+ * and reach the workspace through the relay: their app opens the encrypted
+ * channel (server/relay.ts) and, as its first sealed message, presents
+ *
+ *   → {t:"auth", memberToken: "kwm_…", workspaceId: "ws_…"}
+ *   ← {t:"auth", ok: true, member: {email, handle, role}, workspace: {id, slug, name}}
+ *   ← {t:"auth", ok: false, error}                      and the channel closes
+ *
+ * instead of a paired device's token. This daemon asks the cloud
+ * (/api/members/verify, with the machine's credentials) and caches the
+ * answer per (token, workspace) for five minutes — short, because revoking
+ * a member kills their tokens in the cloud at once, and the cache is all
+ * that keeps them in until it expires:
+ *
+ *   fresh        within the TTL the cache answers, the cloud is not asked
+ *   expired      a live session re-verifies lazily with its next request
+ *   unreachable  the cloud down, a 5xx, no machine client: a cached entry is
+ *                KEPT and used (stale); without one the session is refused
+ *   revoked      404 (unknown or revoked token) or 403 (this machine does not
+ *                host the workspace) drops the entry, and the session with it
+ *
+ * A session is scoped to that one workspace: the relay tags each of its
+ * requests with the session's random id (MEMBER_HEADER), which only this
+ * process knows, and trust.ts turns the tag into `member` trust; server.ts
+ * and router.ts refuse everything outside the workspace. Paired devices are
+ * untouched — machine-wide, as before.
+ */
+export type Member = MemberVerdict;
+/** The header the relay puts on a member session's requests (a client's own is dropped). */
+export declare const MEMBER_HEADER = "x-kraftwerk-member";
+/** How long a verified answer counts as fresh — tests shorten it; no argument restores the default. */
+export declare function setMemberCacheTtl(ms?: number): void;
+/** Forget every cached answer (tests). */
+export declare function forgetMemberCache(): void;
+export type Verdict = {
+    ok: true;
+    member: Member;
+    stale?: true;
+}
+/** `drop`: the cloud said no (the session ends); otherwise it could not be asked. */
+ | {
+    ok: false;
+    error: string;
+    drop: boolean;
+};
+/** Whether `token` is a member of `workspaceId`: the cache within its TTL, else the cloud. */
+export declare function verifyMember(token: string, workspaceId: string): Promise<Verdict>;
+/**
+ * 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 declare function openMemberSession(token: unknown, workspaceId: unknown): Promise<{
+    ok: true;
+    id: string;
+    member: Member;
+    workspace: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+} | {
+    ok: false;
+    error: string;
+}>;
+/** The session behind a request's tag, or undefined. */
+export declare function memberSession(id: string): {
+    member: Member;
+    workspaceId: string;
+    slug: string;
+} | 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 declare function checkMemberSession(id: string): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    ended: boolean;
+}>;
+export declare function closeMemberSession(id: string): void;