@netnodeag/kraftwerk 0.76.0 → 0.77.0

package/dist/server/cloud.d.ts

@@ -1,53 +1,85 @@
+import { type CloudUrlSource } from "../core/cloud.js";
 /**
- * The cloud manager client: kraftwerk.yml `cloud:` makes this instance
- * register with the kraftwerk cloud when the inspector starts and heartbeat
- * while it runs — the same record ~/.kraftwerk/instances holds locally,
- * kept on a server so an admin (and, with an account token, the user)
- * sees every instance across machines.
+ * The machine client: the daemon registers THIS MACHINE with the kraftwerk
+ * cloud once and heartbeats while it runs; the workspaces it serves ride
+ * along as children of that record (see core/cloud.ts for the contract and
+ * the settings). One per process, and only the daemon starts it
+ * (startMachineCloud from `kraftwerk daemon`): a standalone `kraftwerk ui`
+ * and test fixtures never talk to the cloud.
  *
- * Identity: the first registration hands out an id + secret, stored under
- * ~/.kraftwerk/cloud/<hash(url, root)>.json and presented on every later
- * call, so a restart updates the record instead of creating a new one.
- * When the cloud does not recognise the id (data reset) it hands out a
- * fresh one and the file is rewritten.
- *
- * Everything is best-effort: a cloud that is down never affects the UI.
- * The status is reported in /api/meta so the UI can show it.
+ *   start      ensure the machine key (relay.json, relay stays off), drop the
+ *              retired per-workspace identities (~/.kraftwerk/cloud/), and,
+ *              unless cloud.json or KRAFTWERK_CLOUD_URL=off says no, register
+ *              — anonymous: the answer carries a claim code until someone
+ *              claims the machine (`kraftwerk login`, or the code in the UI)
+ *   heartbeat  every `interval` the cloud asked for; the workspace list rides
+ *              along whenever it changed (opened, closed, vetoed, claimed).
+ *              A claim made in the cloud arrives in the answer
+ *   privacy    while unclaimed, entries carry name/slug/ws-id only — no
+ *              roots; once claimed, roots too
+ *   recovery   a cloud that no longer knows the machine (data reset) gets a
+ *              fresh registration; a cloud that is down is retried at the
+ *              same cadence and never affects the UI
+ *   goodbye    on shutdown (bounded), and when `kraftwerk cloud off` reaches
+ *              the running daemon
  */
 export type CloudState = "off" | "connecting" | "connected" | "error";
 export interface CloudStatus {
     url: string;
     state: CloudState;
-    /** Last error message while connecting or heartbeating. */
+    /** Why it is off, when it is. */
+    reason?: string;
+    /** Where the URL came from (env, cloud.json, a deprecated kraftwerk.yml cloud.url, the default). */
+    source?: CloudUrlSource;
+    /** Last error message while registering or heartbeating. */
     error?: string;
-    /** Instance id in the cloud once registered. */
+    /** The machine's id in the cloud (its relay id). */
     id?: string;
-    /** Email of the linked kraftwerk account, when a token was presented and accepted. */
+    /** This machine's handle@machine. */
+    machine?: string;
+    /** Email of the account that claimed the machine; null while unclaimed. */
     account?: string | null;
-    /** Effective seconds between heartbeats (the cloud may raise the configured one). */
+    /** Effective seconds between heartbeats (what the cloud asked for). */
     interval?: number;
+    /** Last successful register or heartbeat. */
     lastSeen?: string;
-    /** XXXX-XXXX the user types into the cloud UI to claim this instance; null once claimed. */
+    /** XXXX-XXXX that claims this machine in the cloud; null once claimed. */
     claimCode?: string | null;
-    /** The cloud page that claims this instance after sign-in. */
+    /** The cloud page that claims this machine after sign-in. */
     claimUrl?: string | null;
+    /** Workspaces reported (vetoed ones left out). */
+    workspaces?: number;
 }
+/** What the daemon serves right now. */
+export type WorkspaceSource = () => Array<{
+    root: string;
+    slug: string;
+    name: string;
+}>;
 export declare const cloudStatus: () => CloudStatus;
 /**
- * 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 declare function startMachineCloud(opts: {
+    version: string;
+    workspaces: WorkspaceSource;
+    owner?: unknown;
+}): Promise<CloudStatus>;
+/**
+ * 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 declare function startCloudSync(url: string, version: string): Promise<void>;
-/** Stop the heartbeat loop (server close, tests). */
-export declare function stopCloudSync(): void;
+export declare function applyMachineCloud(): Promise<CloudStatus>;
+/** A round now (the CLI's `login` waits for a claim): registers when needed, else heartbeats. */
+export declare function syncMachineCloud(): Promise<CloudStatus>;
+/** Release the claim (`kraftwerk logout`): the cloud hands out a fresh claim code. */
+export declare function unlinkMachineCloud(): Promise<CloudStatus>;
 /**
- * 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 declare function cloudGoodbye(): Promise<void>;
-/** Every served workspace: stop its heartbeat (the server closes). */
-export declare function stopAllCloudSync(): void;
-/** Every served workspace says goodbye, in parallel (still bounded per workspace). */
-export declare function cloudGoodbyeAll(): Promise<void>;
+export declare function stopMachineCloud(owner?: unknown): Promise<void>;

package/dist/server/cloud.js

@@ -1,232 +1,251 @@
-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, retiredCloudDir, unknownMachine, } from "../core/cloud.js";
+import { identityString, readIdentity } from "../core/identity.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: "",
+    /** 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
-}
-/** 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 };
+    return { list, ymlUrls };
 }
-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) : {};
+const claimed = () => typeof m.status.account === "string" && m.status.account.length > 0;
+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;
+        // 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);
     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 } : {}) });
+        m.reported = now;
+        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;
-    }
-    // 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;
+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();
-}
-/** 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;
+    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.
+ * 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 cloudGoodbye() {
-    const c = client();
-    stopCloudSync();
-    if (!c.identity || c.status.state === "off" || !c.status.url)
-        return;
-    try {
-        await post(`${c.status.url}/api/instances/goodbye`, c.identity, GOODBYE_TIMEOUT_MS);
+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 = "";
+        });
     }
-    catch { }
+    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;
 }
-/** Every served workspace: stop its heartbeat (the server closes). */
-export function stopAllCloudSync() {
-    for (const [ws] of client.entries())
-        ws.run(stopCloudSync);
+/** 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.status = { ...m.status, account: null, claimCode: r.claimCode ?? null, claimUrl: claimUrlFor(m.status.url, r.claimCode) };
+        return m.status;
+    });
 }
-/** 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)));
+/**
+ * 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 stopMachineCloud(owner) {
+    if (!m.started || (owner !== undefined && owner !== m.owner))
+        return;
+    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(() => { });
 }

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/relay.d.ts

@@ -44,6 +44,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;
 /**