@synapse-sdk/client 0.3.6 → 0.3.7

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { defaultReconnectPolicy, exponentialPolicy, fixedPolicy, withMaxAttempts
 export { isTasksRefusal } from "./tasks.ts";
 export { setMoqDebug } from "./moq_log.ts";
 export type * from "./types.ts";
-export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport } from "./session.ts";
+export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport, namesRoot } from "./session.ts";
 export { replaceEqualDeep, shallowEqual } from "./util.ts";
 export { orderAfter, orderBefore, orderBetween, ulid } from "./scene.ts";
 export { derivedFrameKey, derivedFrameName, materializeFrames, materializeHardpoints, validateDerivedFrame, type MaterializeReport } from "./scene_frames.ts";

package/dist/index.js

@@ -4,7 +4,7 @@ export { Synapse, FIRST_CONNECT_GIVE_UP_MS } from "./synapse.js";
 export { defaultReconnectPolicy, exponentialPolicy, fixedPolicy, withMaxAttempts } from "./node.js";
 export { isTasksRefusal } from "./tasks.js";
 export { setMoqDebug } from "./moq_log.js";
-export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport } from "./session.js";
+export { brokerCertHelperUrl, discoverBrokerCertSha256, ensureWebTransport, namesRoot } from "./session.js";
 export { replaceEqualDeep, shallowEqual } from "./util.js";
 export { orderAfter, orderBefore, orderBetween, ulid } from "./scene.js";
 export { derivedFrameKey, derivedFrameName, materializeFrames, materializeHardpoints, validateDerivedFrame } from "./scene_frames.js";

package/dist/keyserver.d.ts

@@ -0,0 +1,37 @@
+import { SynapseError } from "@synapse-sdk/core";
+import type { Discovery, DiscoveryState, FetchToken } from "./types.ts";
+import type { Cell } from "./util.ts";
+/** The key server a node asks when `setAuth` names none. */
+export declare const DEFAULT_AUTH_URL = "https://e9e413af.synapse.build";
+/** The discovery value with no credential set, or just after `setAuth` (a new object each time: a change). */
+export declare const idleDiscovery: () => DiscoveryState;
+/** The refusal when no credential is set or the sign-in gives none. */
+export declare const notSignedIn: () => SynapseError;
+/** `GET /discover`'s body as the `Discovery` value; `undefined` when it does not have that shape. */
+export declare function discoveryOf(body: unknown): Discovery | undefined;
+/**
+ * One `setAuth(fetchToken, { authUrl })` of one node: the key server's client and the caches it fills. A new one at every
+ * `setAuth` (the old one's caches go with it). It writes the node's `discovery` value only while it is the node's
+ * current one (`current`), so an answer arriving after a `setAuth` changes nothing.
+ */
+export declare class Auth {
+    #private;
+    private readonly fetchToken;
+    private readonly discovery;
+    private readonly current;
+    constructor(fetchToken: FetchToken, authUrl: string, discovery: Cell<DiscoveryState>, current: (a: Auth) => boolean);
+    /** `GET /discover`, setting the value (`pending`, then `success` or `error`, the last data kept); one at a time: a call while one is out joins it. */
+    discover(): Promise<Discovery>;
+    /** The discover answer: the value's when it is `success` (`cached`), else fetched now. */
+    known(): Promise<{
+        discovery: Discovery;
+        cached: boolean;
+    }>;
+    /** The token for cluster `id`: the kept one while it does not expire within `FRESH_FOR_S` (`cached`), else `POST /clusters/{id}/token`, kept. */
+    clusterToken(id: string): Promise<{
+        token: string;
+        cached: boolean;
+    }>;
+    /** Forgets the token of cluster `id` (the relay refused it). */
+    dropToken(id: string): void;
+}

package/dist/keyserver.js

@@ -0,0 +1,146 @@
+// The key server for a signed-in person (PLAN v0.38 §3.3): what a node set with `setAuth` asks it, `GET /discover`
+// (the relay and the person's clusters with their runtimes) and `POST /clusters/{id}/token` (a cluster token), with
+// the person's credential fetched at each request and sent only in the `Authorization` header. Both answers are kept
+// in memory, per node, until the next `setAuth`: the discover answer as the node's `discovery` state value, the cluster
+// tokens by cluster id while fresh (`FRESH_FOR_S`). Nothing is written anywhere else; no token is ever put in a URL, an
+// error or a log line.
+import { SynapseError } from "@synapse-sdk/core";
+import { describeError } from "./session.js";
+import { FRESH_FOR_S, knownOfListed, label } from "./target.js";
+/** The key server a node asks when `setAuth` names none. */
+export const DEFAULT_AUTH_URL = "https://e9e413af.synapse.build";
+/** The discovery value with no credential set, or just after `setAuth` (a new object each time: a change). */
+export const idleDiscovery = () => ({ status: "idle" });
+/** The refusal when no credential is set or the sign-in gives none. */
+export const notSignedIn = () => new SynapseError("unauthorized", { message: "not signed in: sign in first", source: "sdk" });
+const isTable = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** An answer that is not what the key server says it sends: `connection_lost` (retried; never a caller's mistake). */
+const unreadable = (what) => new SynapseError("connection_lost", { message: `the key server's answer to ${what} could not be read`, source: "sdk" });
+/** `GET /discover`'s body as the `Discovery` value; `undefined` when it does not have that shape. */
+export function discoveryOf(body) {
+    if (!isTable(body) || typeof body.relay !== "string" || typeof body.user_id !== "string" || !Array.isArray(body.clusters))
+        return undefined;
+    const clusters = [];
+    for (const c of body.clusters) {
+        if (!isTable(c) || typeof c.id !== "string" || typeof c.name !== "string" || !isTable(c.owner) || !isTable(c.runtimes))
+            return undefined;
+        const o = c.owner;
+        if (typeof o.kind !== "string" || typeof o.id !== "string" || (o.slug !== undefined && o.slug !== null && typeof o.slug !== "string"))
+            return undefined;
+        const owner = typeof o.slug === "string" ? { kind: o.kind, id: o.id, slug: o.slug } : { kind: o.kind, id: o.id };
+        const runtimes = {};
+        for (const [name, id] of Object.entries(c.runtimes)) {
+            if (typeof id !== "string")
+                return undefined;
+            runtimes[name] = id;
+        }
+        const listed = { id: c.id, name: c.name, owner };
+        clusters.push({ ...listed, label: label(knownOfListed(listed)), runtimes });
+    }
+    return { relay: body.relay, userId: body.user_id, clusters };
+}
+/**
+ * One `setAuth(fetchToken, { authUrl })` of one node: the key server's client and the caches it fills. A new one at every
+ * `setAuth` (the old one's caches go with it). It writes the node's `discovery` value only while it is the node's
+ * current one (`current`), so an answer arriving after a `setAuth` changes nothing.
+ */
+export class Auth {
+    fetchToken;
+    discovery;
+    current;
+    #tokens = new Map();
+    #pending;
+    #authUrl;
+    constructor(fetchToken, authUrl, discovery, current) {
+        this.fetchToken = fetchToken;
+        this.discovery = discovery;
+        this.current = current;
+        this.#authUrl = authUrl.replace(/\/+$/, "");
+    }
+    #set(f) { if (this.current(this))
+        this.discovery.set(f(this.discovery.get())); }
+    /** `GET /discover`, setting the value (`pending`, then `success` or `error`, the last data kept); one at a time: a call while one is out joins it. */
+    discover() {
+        return this.#pending ??= (async () => {
+            this.#set(p => (p.data ? { status: "pending", data: p.data } : { status: "pending" }));
+            try {
+                const d = discoveryOf(await this.#request("GET", "/discover"));
+                if (!d)
+                    throw unreadable("discover");
+                this.#set(() => ({ status: "success", data: d }));
+                return d;
+            }
+            catch (e) {
+                const err = e instanceof SynapseError ? e : new SynapseError("internal", { message: describeError(e), source: "sdk" });
+                this.#set(p => (p.data ? { status: "error", data: p.data, error: err } : { status: "error", error: err }));
+                throw err;
+            }
+            finally {
+                this.#pending = undefined;
+            }
+        })();
+    }
+    /** The discover answer: the value's when it is `success` (`cached`), else fetched now. */
+    async known() {
+        const v = this.discovery.get();
+        if (this.current(this) && v.status === "success" && v.data)
+            return { discovery: v.data, cached: true };
+        return { discovery: await this.discover(), cached: false };
+    }
+    /** The token for cluster `id`: the kept one while it does not expire within `FRESH_FOR_S` (`cached`), else `POST /clusters/{id}/token`, kept. */
+    async clusterToken(id) {
+        const kept = this.#tokens.get(id);
+        if (kept && kept.exp > Math.floor(Date.now() / 1000) + FRESH_FOR_S)
+            return { token: kept.token, cached: true };
+        const body = await this.#request("POST", `/clusters/${encodeURIComponent(id)}/token`);
+        const exp = isTable(body) && typeof body.expires_at === "string" ? Date.parse(body.expires_at) : NaN;
+        if (!isTable(body) || typeof body.token !== "string" || body.token === "" || Number.isNaN(exp))
+            throw unreadable("a cluster token request");
+        this.#tokens.set(id, { token: body.token, exp: Math.floor(exp / 1000) });
+        return { token: body.token, cached: false };
+    }
+    /** Forgets the token of cluster `id` (the relay refused it). */
+    dropToken(id) { this.#tokens.delete(id); }
+    /**
+     * One request with the credential fetched now. The key server's answers (PLAN v0.38 §3.3.5): `401` `unauthorized`
+     * (and every cache dropped), `400`/`403`/`404` `invalid_input`, anything else not 2xx, or no answer, `connection_lost`;
+     * each with the key server's own sentence when it sent one.
+     */
+    async #request(method, path) {
+        let credential;
+        try {
+            credential = await this.fetchToken();
+        }
+        catch (e) {
+            throw new SynapseError("connection_lost", { message: `signing in gave no credential: ${describeError(e)}`, source: "sdk" });
+        }
+        if (!credential)
+            throw notSignedIn();
+        let res;
+        try {
+            res = await globalThis.fetch(`${this.#authUrl}${path}`, { method, headers: { Authorization: `Bearer ${credential}` } });
+        }
+        catch (e) {
+            throw new SynapseError("connection_lost", { message: `the key server could not be reached: ${describeError(e)}`, source: "transport" });
+        }
+        let body;
+        try {
+            body = JSON.parse(await res.text());
+        }
+        catch {
+            body = undefined;
+        }
+        if (res.ok)
+            return body;
+        const sentence = isTable(body) && typeof body.error === "string" && body.error !== "" ? body.error : `the key server answered ${res.status}`;
+        if (res.status === 401) {
+            const err = new SynapseError("unauthorized", { message: sentence, source: "sdk" });
+            this.#tokens.clear();
+            this.#set(p => (p.status === "success" ? { status: "error", data: p.data, error: err } : p));
+            throw err;
+        }
+        if (res.status === 400 || res.status === 403 || res.status === 404)
+            throw new SynapseError("invalid_input", { message: sentence, source: "sdk" });
+        throw new SynapseError("connection_lost", { message: sentence, source: "sdk" });
+    }
+}

package/dist/node.d.ts

@@ -1,6 +1,7 @@
 import { SynapseError, type ClientType, type ErrorBody, type Identity, type TimeDomain } from "@synapse-sdk/core";
+import { Auth } from "./keyserver.ts";
 import { Session, type Dial, type SessionKnobs } from "./session.ts";
-import type { ConnectOptions, ConnectTarget, ConnectionState, Notice, ReconnectPolicy } from "./types.ts";
+import type { ConnectOptions, ConnectTarget, ConnectionState, DiscoveryState, FetchToken, Notice, ReconnectPolicy } from "./types.ts";
 import { Cell, type Deferred } from "./util.ts";
 /** `initial × 2^(attempt−1)` capped at `max`, times an equal jitter U(0.5, 1); never gives up. */
 export declare function exponentialPolicy(initialMs: number, maxMs: number): ReconnectPolicy;
@@ -108,6 +109,13 @@ export declare class Node {
     readonly projectNotices: Set<(n: Notice) => void>;
     /** Resolves once the node has ended for good: `close()`, and nothing else. */
     readonly ended: Deferred<void>;
+    /**
+     * The signed-in person's key server (`setAuth`), asked when a target named by name is dialed (PLAN v0.38 §3.2);
+     * `undefined`: nobody is signed in. Read at each attempt, never by a live session: signing out ends no session.
+     */
+    auth: Auth | undefined;
+    /** The key server's answer about the signed-in person, kept by `auth` (`node.discovery`). */
+    readonly discovery: Cell<DiscoveryState>;
     epochs: number;
     reconnects: number;
     callsSent: number;
@@ -118,6 +126,8 @@ export declare class Node {
         finalDom?: Promise<TimeDomain>;
     });
     get isEnded(): boolean;
+    /** `setAuth`: a new key-server client for `fetchToken` (none: signed out); what the previous one kept is forgotten and `discovery` is `idle` again. */
+    setAuth(fetchToken: FetchToken | undefined, authUrl: string): void;
     get isConnected(): boolean;
     /** Whether the node rests `failed` on target `generation` (a `failed` of an older target, not yet replaced by the loop, is not this target's). */
     failedOn(generation: number): boolean;
@@ -161,6 +171,13 @@ export declare class Node {
     /** Starts the loop (once the time domain is final). `first` is a `connect()` call's reply. `signals`: close on SIGINT/SIGTERM (Bun/Node). */
     run(stand: Stand, first: Reply | undefined, signals: boolean): void;
 }
+/**
+ * Dials `dial`, a target named as the CLI names it, through the key server of `auth` (`resolveViaKeyserver`), with `open`.
+ * When the relay refuses (`unauthorized`) a cluster token that came from the cache, that token is dropped, one is asked
+ * again and dialed once more within this attempt (a token the relay stopped taking before its expiry costs one request,
+ * not a `failed`); a second refusal is the attempt's. A token given as such is dialed as it is.
+ */
+export declare function dialByName<T>(dial: Dial, auth: Auth, open: (at: Dial) => Promise<T>): Promise<T>;
 /** Resolves the identity a node declares (`resolve_identity`): a missing name is minted, a `web`/`hmi` node without a `user_id` mints one. */
 export declare function resolveIdentity(o: {
     type: ClientType;
@@ -168,7 +185,12 @@ export declare function resolveIdentity(o: {
     userId?: string;
     credential?: string;
 }): Identity;
-/** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
+/**
+ * Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). A url that is not a URL is a
+ * target as the CLI names it (`infra-1@devel`): its grammar is checked now, and it is resolved at every attempt (through
+ * the key server when a person is signed in, else from the CLI's files); with neither (a browser, nobody signed in) it is
+ * refused at once.
+ */
 export declare function resolveTarget(node: Node, t: ConnectTarget): Dial;
 /** A given broker url that is not a URL is the caller's mistake: `invalid_input`. */
 export declare function checkUrl(url: string): void;

package/dist/node.js

@@ -8,6 +8,8 @@
 // the handles replay when told.
 import { ClockSync, SynapseError, calibrateMonotonicClock, defaultDomId, isValidClientName, mintName, mintUserId, nowUs } from "@synapse-sdk/core";
 import { closeOnSignals, forgetOnSignals } from "./signals.js";
+import { BROWSER_REFUSAL, canReadFiles, isUrl, parseTargetStrict, resolveStr, resolveViaKeyserver } from "./target.js";
+import { Auth, idleDiscovery } from "./keyserver.js";
 import { Session, closeError, defaultMaxDatagram, discoverBrokerCertSha256, makeDial, openSession, urlOrEndpoint } from "./session.js";
 import { startOn } from "./calls.js";
 import { AsyncQueue, Cell, deferred } from "./util.js";
@@ -84,6 +86,13 @@ export class Node {
     /** The loop's mailbox: unbounded, so no `close()` or target change is ever dropped. */
     #commands = new AsyncQueue(Infinity);
     #monitors = new Set();
+    /**
+     * The signed-in person's key server (`setAuth`), asked when a target named by name is dialed (PLAN v0.38 §3.2);
+     * `undefined`: nobody is signed in. Read at each attempt, never by a live session: signing out ends no session.
+     */
+    auth;
+    /** The key server's answer about the signed-in person, kept by `auth` (`node.discovery`). */
+    discovery = new Cell(idleDiscovery());
     epochs = 0;
     reconnects = 0;
     callsSent = 0;
@@ -98,6 +107,11 @@ export class Node {
         this.prepared = opts.finalDom ? opts.finalDom.then(d => { this.dom = d; }) : Promise.resolve();
     }
     get isEnded() { return this.#endedFlag; }
+    /** `setAuth`: a new key-server client for `fetchToken` (none: signed out); what the previous one kept is forgotten and `discovery` is `idle` again. */
+    setAuth(fetchToken, authUrl) {
+        this.auth = fetchToken ? new Auth(fetchToken, authUrl, this.discovery, a => this.auth === a) : undefined;
+        this.discovery.set(idleDiscovery());
+    }
     get isConnected() { return this.link.get().status === "connected"; }
     /** Whether the node rests `failed` on target `generation` (a `failed` of an older target, not yet replaced by the loop, is not this target's). */
     failedOn(generation) { const l = this.link.get(); return l.status === "failed" && l.generation === generation; }
@@ -328,9 +342,19 @@ async function runLoop(node, commands, stand, first) {
                 if (ac.signal.aborted)
                     return { kind: "opened", result: new SynapseError("canceled", "superseded") };
                 try {
-                    // The pin: given, else discovered per attempt (a restarted dev broker has a fresh certificate), else unpinned.
-                    const cert = dial.cert ?? await discoverBrokerCertSha256(dial.url, { signal: ac.signal });
-                    return { kind: "opened", result: await openSession(node.knobs, { ...dial, cert }, node.dom.id, ac.signal) };
+                    const open = async (at) => {
+                        // The pin: given, else discovered per attempt (a restarted dev broker has a fresh certificate), else unpinned.
+                        const cert = at.cert ?? await discoverBrokerCertSha256(at.url, { signal: ac.signal });
+                        return openSession(node.knobs, { ...at, cert }, node.dom.id, ac.signal);
+                    };
+                    // A URL is dialed as it is. A target named as the CLI names it is resolved now, by one source chosen per attempt
+                    // (PLAN v0.38 §3.2): the key server when a person is signed in (`setAuth`), else the CLI's files (a token the
+                    // CLI refreshed since the last attempt is this attempt's). A token given as such wins.
+                    const auth = node.auth;
+                    const session = isUrl(dial.url) ? await open(dial)
+                        : auth ? await dialByName(dial, auth, open)
+                            : await resolveStr(dial.url).then(r => open({ ...dial, url: r.url, token: dial.token ?? r.token }));
+                    return { kind: "opened", result: session };
                 }
                 catch (e) {
                     return { kind: "opened", result: e instanceof SynapseError ? e : new SynapseError("connection_lost", { message: String(e), cause: e }) };
@@ -476,6 +500,26 @@ async function runLoop(node, commands, stand, first) {
         }
     }
 }
+/**
+ * Dials `dial`, a target named as the CLI names it, through the key server of `auth` (`resolveViaKeyserver`), with `open`.
+ * When the relay refuses (`unauthorized`) a cluster token that came from the cache, that token is dropped, one is asked
+ * again and dialed once more within this attempt (a token the relay stopped taking before its expiry costs one request,
+ * not a `failed`); a second refusal is the attempt's. A token given as such is dialed as it is.
+ */
+export async function dialByName(dial, auth, open) {
+    const r = await resolveViaKeyserver(dial.url, auth);
+    const at = { ...dial, url: r.url, token: dial.token ?? r.token };
+    try {
+        return await open(at);
+    }
+    catch (e) {
+        if (!(e instanceof SynapseError) || e.code !== "unauthorized" || dial.token !== undefined || !r.cached || r.cluster === undefined)
+            throw e;
+        auth.dropToken(r.cluster);
+        const { token } = await auth.clusterToken(r.cluster);
+        return open({ ...at, token });
+    }
+}
 /** Ends session `s`: the node stops naming it (handles are told, the status is true from that instant), then the session is torn down (calls failed, tasks awaited, close sent). */
 async function teardown(node, s, next) {
     node.setLink(next);
@@ -495,9 +539,25 @@ export function resolveIdentity(o) {
         id.credential = o.credential;
     return id;
 }
-/** Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). */
+/**
+ * Resolves a `ConnectTarget` against the node's current identity (fields left out are kept). A url that is not a URL is a
+ * target as the CLI names it (`infra-1@devel`): its grammar is checked now, and it is resolved at every attempt (through
+ * the key server when a person is signed in, else from the CLI's files); with neither (a browser, nobody signed in) it is
+ * refused at once.
+ */
 export function resolveTarget(node, t) {
-    checkUrl(t.url);
+    if (isUrl(t.url))
+        checkUrl(t.url);
+    else {
+        if (!node.auth && !canReadFiles())
+            throw new SynapseError("invalid_input", { message: BROWSER_REFUSAL, source: "sdk" });
+        try {
+            parseTargetStrict(t.url);
+        }
+        catch (e) {
+            throw new SynapseError("invalid_input", { message: `${e instanceof Error ? e.message : String(e)}, or a URL`, source: "sdk" });
+        }
+    }
     const cur = node.target.get().identity;
     if (t.name !== undefined && !isValidClientName(t.name))
         throw new SynapseError("invalid_input", `name ${JSON.stringify(t.name)} is not [a-z0-9_-]{1,64}`);

package/dist/session.d.ts

@@ -89,14 +89,24 @@ export declare function describeError(e: unknown): string;
  * GOAWAY looks like one).
  */
 export declare function closeError(err: Error | null): SynapseError;
-/** `https://host:port/<root>` → `http://host:port/certificate.sha256`, the broker's plain-HTTP helper. */
+/**
+ * `https://host[:port]` → `http://host:port/certificate.sha256`, the runtime's plain-HTTP helper on the
+ * runtime's own port (443 when the URL names none, as the Rust SDK). Before 2026-10-17 the default
+ * port was lost and a relay URL was asked on port 80, which no relay answers: a 2 s stall per attempt.
+ */
 export declare function brokerCertHelperUrl(brokerUrl: string): string;
+/** Whether `url` names a root (`/runtimes/<id>`, `/cluster/<c>/runtimes/<id>`): a relay, a deployment with a real certificate, never asked for a pin (`withRoot` makes the same split). */
+export declare function namesRoot(url: string): boolean;
 /**
  * The runtime's URL when the caller gave none: `SYNAPSE_ENDPOINT` (Bun/Node; the runtime sets it for every task it starts).
  * A browser has no environment: there, as with neither, `invalid_input`.
  */
 export declare function urlOrEndpoint(url: string | undefined): string;
-/** The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node), then the helper, then `undefined` = unpinned. Per attempt. */
+/**
+ * The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node); else, for a
+ * runtime URL (no path: a self-signed certificate, pinned), its helper; a URL that names a root (a relay) is
+ * never asked and connects unpinned, against the system's roots. `undefined` = unpinned. Per attempt.
+ */
 export declare function discoverBrokerCertSha256(brokerUrl: string, opts?: {
     timeoutMs?: number;
     signal?: AbortSignal;

package/dist/session.js

@@ -332,8 +332,20 @@ export function closeError(err) {
         return new SynapseError("unauthorized", { message: text.trim(), source: "broker", cause: err });
     return new SynapseError("connection_lost", { message: text.trim() || err.name, source: "transport", cause: err });
 }
-/** `https://host:port/<root>` → `http://host:port/certificate.sha256`, the broker's plain-HTTP helper. */
-export function brokerCertHelperUrl(brokerUrl) { const u = new URL(brokerUrl); return `http://${u.host}/certificate.sha256`; }
+/**
+ * `https://host[:port]` → `http://host:port/certificate.sha256`, the runtime's plain-HTTP helper on the
+ * runtime's own port (443 when the URL names none, as the Rust SDK). Before 2026-10-17 the default
+ * port was lost and a relay URL was asked on port 80, which no relay answers: a 2 s stall per attempt.
+ */
+export function brokerCertHelperUrl(brokerUrl) { const u = new URL(brokerUrl); return `http://${u.hostname}:${u.port || (u.protocol === "http:" ? "80" : "443")}/certificate.sha256`; }
+/** Whether `url` names a root (`/runtimes/<id>`, `/cluster/<c>/runtimes/<id>`): a relay, a deployment with a real certificate, never asked for a pin (`withRoot` makes the same split). */
+export function namesRoot(url) { try {
+    const p = new URL(url).pathname;
+    return p !== "" && p !== "/";
+}
+catch {
+    return false;
+} }
 /**
  * The runtime's URL when the caller gave none: `SYNAPSE_ENDPOINT` (Bun/Node; the runtime sets it for every task it starts).
  * A browser has no environment: there, as with neither, `invalid_input`.
@@ -347,22 +359,35 @@ export function urlOrEndpoint(url) {
     throw new SynapseError("invalid_input", { message: "no url given and SYNAPSE_ENDPOINT is not set", source: "sdk" });
 }
 const SHA256_HEX = /^[0-9a-f]{64}$/i;
-/** The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node), then the helper, then `undefined` = unpinned. Per attempt. */
+/**
+ * The certificate pin when the caller gave none (SDK §13): `SYNAPSE_BROKER_CERT_SHA256` (Bun/Node); else, for a
+ * runtime URL (no path: a self-signed certificate, pinned), its helper; a URL that names a root (a relay) is
+ * never asked and connects unpinned, against the system's roots. `undefined` = unpinned. Per attempt.
+ */
 export async function discoverBrokerCertSha256(brokerUrl, opts = {}) {
     const env = globalThis.process?.env?.SYNAPSE_BROKER_CERT_SHA256?.trim();
     if (env)
         return env;
-    const signal = opts.signal ? AbortSignal.any([opts.signal, AbortSignal.timeout(opts.timeoutMs ?? 2000)]) : AbortSignal.timeout(opts.timeoutMs ?? 2000);
-    try {
-        const res = await fetch(brokerCertHelperUrl(brokerUrl), { signal });
-        if (!res.ok)
-            return undefined;
-        const text = (await res.text()).trim();
-        return SHA256_HEX.test(text) ? text : undefined;
-    }
-    catch {
+    if (namesRoot(brokerUrl))
         return undefined;
-    }
+    const timeoutMs = opts.timeoutMs ?? 2000;
+    const signal = opts.signal ? AbortSignal.any([opts.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+    const fetched = (async () => {
+        try {
+            const res = await fetch(brokerCertHelperUrl(brokerUrl), { signal });
+            if (!res.ok)
+                return undefined;
+            const text = (await res.text()).trim();
+            return SHA256_HEX.test(text) ? text : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    // Bun does not abort a connect that gets no answer (measured 2026-10-17: a filtered port hung the dial for
+    // good); the race bounds the wait whatever the runtime does with the signal.
+    const r = await withTimeout(fetched, timeoutMs);
+    return r === TIMEOUT ? undefined : r;
 }
 /**
  * `token_from_url`: `url` without its `jwt=` query parameters, and the last non-empty one (as the relays

package/dist/synapse.d.ts

@@ -2,7 +2,7 @@ import { type Age, type ErrorBody, type ProjectSnapshot, type ServiceContract, t
 import { Node } from "./node.ts";
 import { StoreHandleImpl } from "./store.ts";
 import { type Warn } from "./topics.ts";
-import type { CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Envelope, Info, Metrics, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, Tasks, View, ViewOptions } from "./types.ts";
+import type { CallOptions, Catalog, ConnectOptions, ConnectTarget, ConnectionState, Discovery, DiscoveryState, Envelope, FetchToken, Info, Metrics, Publisher, Registration, Run, ServeHandler, ServeOptions, SceneHandle, StoreHandle, StoreOptions, SubscribeOptions, Subscription, Tasks, View, ViewOptions } from "./types.ts";
 import { type StateValue } from "./util.ts";
 export { FIRST_CONNECT_GIVE_UP_MS } from "./node.ts";
 export declare class Synapse implements AsyncDisposable {
@@ -15,7 +15,8 @@ export declare class Synapse implements AsyncDisposable {
      */
     constructor(opts: ConnectOptions);
     /**
-     * Connects the node to `target` (a string is the url), the one connect verb: the first connect, and how an HMI moves
+     * Connects the node to `target` (a string is the url: a URL, or in Bun/Node a target such as `"infra-1@devel"`, see
+     * `ConnectTarget.url`), the one connect verb: the first connect, and how an HMI moves
      * from one robot's runtime to another. The current session, if any, is torn down before `target` is dialed; every
      * handle re-binds to the new session as across a reconnect. Identity fields `target` leaves out keep the node's.
      *
@@ -41,6 +42,30 @@ export declare class Synapse implements AsyncDisposable {
      * resolves quietly). Resolves once the session is gone; already `idle`: at once. `not_connected` once the node has ended.
      */
     disconnect(): Promise<void>;
+    /**
+     * Signs a person in for connecting by name (`connect("infra-1@devel")`) through the key server: `fetchToken` gives the
+     * person's credential and is called each time the key server is asked (never kept); `authUrl` is the key server
+     * (default `https://e9e413af.synapse.build`; an `http://` one is taken as it is, for a key server on your own machine while
+     * developing, never in production: the credential travels in the header). `setAuth(undefined)` signs out. Either way,
+     * what the node kept from the key server (your clusters, the cluster tokens) is forgotten and `discovery` is `idle` again.
+     *
+     * A live session is never touched: the sign-in is read only when the node dials, so signing out ends nothing now, and
+     * the next dial of a target named by name fails `unauthorized` (`failed`). With a person signed in, a target named by
+     * name is resolved through the key server also in Bun/Node, instead of the CLI's files. Call it before `connect()`.
+     */
+    setAuth(fetchToken: FetchToken | undefined, opts?: {
+        authUrl?: string;
+    }): void;
+    /**
+     * Asks the key server for the signed-in person's clusters and their runtimes, sets `discovery` from the answer and
+     * resolves with it; one request at a time (a call while one is out joins it). Rejects `unauthorized` when nobody is
+     * signed in (`setAuth`; `discovery` stays `idle`) or the key server does not take the sign-in, `invalid_input` when it
+     * refuses the request, `connection_lost` when it cannot be reached or is busy (its sentence when it gave one). Without
+     * a sign-in it does not read the CLI's files.
+     */
+    discover(): Promise<Discovery>;
+    /** What the key server said about the signed-in person (`discover()`), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. Connecting by name reads the same answer. */
+    readonly discovery: StateValue<DiscoveryState>;
     /** The node's engine (the SDK's own modules and tests use it). */
     get node(): Node;
     /** Where the node stands (`ConnectionState`), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. */

package/dist/synapse.js

@@ -5,6 +5,7 @@
 import { SynapseError, ageOf, fecSymbolSizeFor, isServiceContract, nowUs, resolveTopic, serviceName, } from "@synapse-sdk/core";
 import { failedRun, startOn } from "./calls.js";
 import { Node, createNode, endpointDial, resolveTarget } from "./node.js";
+import { DEFAULT_AUTH_URL, notSignedIn } from "./keyserver.js";
 import { ServiceRegistration } from "./serve.js";
 import { openScene } from "./scene.js";
 import { Namespace, StoreHandleImpl, attachStore, openStore } from "./store.js";
@@ -25,18 +26,21 @@ function descKey(d) {
     return JSON.stringify({ delivery: d.delivery, content_type: d.content_type, schema_hash: d.schema_hash ?? null, fec: d.fec ?? null });
 }
 /**
- * A fact of the node as a state value (`node.status`, `node.catalog`, `node.project`): `read` is the fact now, the same
- * object while it is unchanged. It changes with the node's link and, while connected, with the current session's values
- * that `watched` names; a callback is rebound to the new session's values on every link change.
+ * A fact of the node as a state value (`node.status`, `node.catalog`, `node.project`, `node.discovery`): `read` is the fact
+ * now, the same object while it is unchanged. It changes with the node's link, with the node's own values `kept` names,
+ * and, while connected, with the current session's values that `watched` names; a callback is rebound to the new
+ * session's values on every link change.
  */
 class NodeCell {
     node;
     read;
     watched;
-    constructor(node, read, watched) {
+    kept;
+    constructor(node, read, watched, kept = []) {
         this.node = node;
         this.read = read;
         this.watched = watched;
+        this.kept = kept;
     }
     get() { return this.read(); }
     /** `cb` with the value on each change of what it is read from; returns the remover. */
@@ -51,7 +55,9 @@ class NodeCell {
         };
         bind();
         const unLink = this.node.link.subscribe(() => { bind(); listener(); });
-        return () => { unLink(); for (const u of un)
+        const unKept = this.kept.map(c => c.subscribe(listener));
+        return () => { unLink(); for (const u of unKept)
+            u(); for (const u of un)
             u(); };
     }
     /** The value after its next change; once the node ends, the value then, whether or not it changed (nothing will change any more). */
@@ -104,9 +110,11 @@ export class Synapse {
             return lastCatalog;
         }, s => [s.topics, s.services]);
         this.project = new NodeCell(n, () => n.currentSession()?.project.get(), s => [s.project]);
+        this.discovery = new NodeCell(n, () => n.discovery.get(), () => [], [n.discovery]);
     }
     /**
-     * Connects the node to `target` (a string is the url), the one connect verb: the first connect, and how an HMI moves
+     * Connects the node to `target` (a string is the url: a URL, or in Bun/Node a target such as `"infra-1@devel"`, see
+     * `ConnectTarget.url`), the one connect verb: the first connect, and how an HMI moves
      * from one robot's runtime to another. The current session, if any, is torn down before `target` is dialed; every
      * handle re-binds to the new session as across a reconnect. Identity fields `target` leaves out keep the node's.
      *
@@ -149,6 +157,34 @@ export class Synapse {
      * resolves quietly). Resolves once the session is gone; already `idle`: at once. `not_connected` once the node has ended.
      */
     disconnect() { return this.#node.declare(undefined); }
+    // -------------------------------------------------------------------------------- sign-in
+    /**
+     * Signs a person in for connecting by name (`connect("infra-1@devel")`) through the key server: `fetchToken` gives the
+     * person's credential and is called each time the key server is asked (never kept); `authUrl` is the key server
+     * (default `https://e9e413af.synapse.build`; an `http://` one is taken as it is, for a key server on your own machine while
+     * developing, never in production: the credential travels in the header). `setAuth(undefined)` signs out. Either way,
+     * what the node kept from the key server (your clusters, the cluster tokens) is forgotten and `discovery` is `idle` again.
+     *
+     * A live session is never touched: the sign-in is read only when the node dials, so signing out ends nothing now, and
+     * the next dial of a target named by name fails `unauthorized` (`failed`). With a person signed in, a target named by
+     * name is resolved through the key server also in Bun/Node, instead of the CLI's files. Call it before `connect()`.
+     */
+    setAuth(fetchToken, opts = {}) { this.#node.setAuth(fetchToken, opts.authUrl ?? DEFAULT_AUTH_URL); }
+    /**
+     * Asks the key server for the signed-in person's clusters and their runtimes, sets `discovery` from the answer and
+     * resolves with it; one request at a time (a call while one is out joins it). Rejects `unauthorized` when nobody is
+     * signed in (`setAuth`; `discovery` stays `idle`) or the key server does not take the sign-in, `invalid_input` when it
+     * refuses the request, `connection_lost` when it cannot be reached or is busy (its sentence when it gave one). Without
+     * a sign-in it does not read the CLI's files.
+     */
+    discover() {
+        const auth = this.#node.auth;
+        const p = auth ? auth.discover() : Promise.reject(notSignedIn());
+        p.catch(() => { });
+        return p;
+    }
+    /** What the key server said about the signed-in person (`discover()`), a state value: `get()` now, `onChange` for each change, `changed()` for the next one, `watch()` for each one in a loop. Connecting by name reads the same answer. */
+    discovery;
     /** The node's engine (the SDK's own modules and tests use it). */
     get node() { return this.#node; }
     #session() { return this.#node.currentSession(); }

package/dist/target.d.ts

@@ -0,0 +1,113 @@
+import type { Auth } from "./keyserver.ts";
+/** What `-t local` means: the runtime on this machine, dialed directly. */
+export declare const LOCAL = "local";
+/** The runtime on this machine. */
+export declare const LOCAL_URL = "https://localhost:4470";
+/** A token is treated as expired when it expires within this many seconds (`target.rs` `FRESH_FOR_S`). */
+export declare const FRESH_FOR_S: number;
+/** Whether `s` is a URL (a scheme and `://`); anything else given as a url is a target. */
+export declare function isUrl(s: string): boolean;
+/** A runtime id or a cluster id: a UUID in its canonical lowercase text. */
+export declare function isId(s: string): boolean;
+/** A runtime name: `[a-z0-9_-]{1,64}`, and never a runtime id. */
+export declare function validName(s: string): boolean;
+/** A cluster name: lowercase letters, digits and `-`, at most 63, not starting with `-`, not `none`. */
+export declare function validClusterName(s: string): boolean;
+/** One cluster as cluster.toml keeps it (`[cluster.<id>]`). */
+export interface Cluster {
+    name: string;
+    /** The org's slug (or id, without a slug), or the user id of a person's own cluster. */
+    owner: string;
+    /** `user` (a person's own cluster) or `org`. */
+    kind: string;
+    /** The relay, `https://host[:port]`. */
+    relay: string;
+    /** The file holding the token for this cluster (absent after `cluster logout`). */
+    token?: string;
+    /** The cluster's runtimes as the key server last gave them (name → runtime id). */
+    runtimes: Record<string, string>;
+}
+/** cluster.toml. */
+export interface ClusterFile {
+    keyserver?: string;
+    /** The id of the cluster a runtime name without `@<cluster>` is looked up in. */
+    default?: string;
+    default_runtime?: string;
+    /** Cluster id → what this machine keeps of it. */
+    cluster: Record<string, Cluster>;
+}
+/** A cluster as the resolution rule sees it. */
+export interface Known {
+    id: string;
+    name: string;
+    owner: string;
+    personal: boolean;
+}
+/** How people name it: `name` (yours) or `owner/name` (an org's). */
+export declare function label(k: Known): string;
+/** A cluster named in a target: `<name>` or `<owner>/<name>`. */
+export interface ClusterRef {
+    owner?: string;
+    name: string;
+}
+export declare function parseClusterRef(s: string): ClusterRef;
+/**
+ * The resolution rule: the cluster `r` names among `known`. `<owner>/<name>`: that org's cluster of that name.
+ * `<name>`: your own cluster of that name, else the one org cluster of that name; two or more such org clusters
+ * are an error naming each one's qualified form. `undefined`: no cluster by that reference.
+ */
+export declare function pick(known: readonly Known[], r: ClusterRef): Known | undefined;
+/** A runtime named in a target: `local`, or `<runtime>[@<cluster>]`. */
+export type Target = {
+    kind: "local";
+} | {
+    kind: "runtime";
+    runtime: string;
+    cluster?: string;
+};
+export declare function parseTarget(s: string): Target;
+/** `parseTarget`, and the runtime a name or a runtime id and the cluster a cluster reference. */
+export declare function parseTargetStrict(s: string): Target;
+/** Where to dial and with which token. */
+export interface Resolved {
+    url: string;
+    token: string | undefined;
+    label: string;
+}
+/** The refusal of a target string where nobody is signed in (`setAuth`) and the CLI's files cannot be read (a browser). */
+export declare const BROWSER_REFUSAL = "connect by name needs a signed-in person (setAuth) or the CLI's files on this machine; or pass the relay URL and a token";
+/** Whether this is Bun/Node, where the CLI's files can be read. */
+export declare function canReadFiles(): boolean;
+/** cluster.toml's text, the file at `path`; a file that keeps clusters by name (not by id) is refused. */
+export declare function parseClusterFile(text: string, path: string): Promise<ClusterFile>;
+/** A cluster as the key server lists it (`GET /discover`): yours when its owner is a user; an organization's by its slug, or its id without one. */
+export declare function knownOfListed(c: {
+    id: string;
+    name: string;
+    owner: {
+        kind: string;
+        id: string;
+        slug?: string;
+    };
+}): Known;
+/** The `exp` claim (seconds since the epoch) of a token, read from its payload without checking it. */
+export declare function tokenExp(jwt: string): number | undefined;
+/**
+ * The target string `s` as the CLI's `-t` reads it, from `$HOME/.synapse/cluster.toml` and the tokens beside it,
+ * reading only: the cluster by `pick` (`@<cluster>`) or the default one; the runtime id from the file (a runtime id
+ * is taken as it is); the token the file names for the cluster while it is fresh, else this machine's own token for
+ * that runtime. A miss is `invalid_input`, a missing or expired token `unauthorized`, each naming the CLI command
+ * that fixes it. Read anew at every call (a token the CLI refreshed is the next dial's).
+ */
+export declare function resolveStr(s: string): Promise<Resolved>;
+/**
+ * The target string `s` resolved through the key server for the signed-in person of `auth` (PLAN v0.38 §3.3): the grammar
+ * and `pick` as `resolveStr`; the cluster among your clusters (the discover answer the node keeps, else asked now), the
+ * runtime id from its runtimes (a runtime id is taken as it is), the relay from the answer, the cluster's token (kept while
+ * fresh, else asked now). A miss in a kept answer asks the key server once more (a runtime enrolled since), then is
+ * `invalid_input`. `cluster` and `cached` tell the dial which token to drop if the relay refuses a kept one; `local` has neither.
+ */
+export declare function resolveViaKeyserver(s: string, auth: Auth): Promise<Resolved & {
+    cluster: string | undefined;
+    cached: boolean;
+}>;

package/dist/target.js

@@ -0,0 +1,377 @@
+// Targets (D 2026-10-19): a runtime named the way the CLI's `-t` names it (`infra-1@devel`, `infra-1` in the
+// default cluster, `arm@medatech/devel`, `local`), turned into the relay URL and token to dial with, from the
+// files the CLI keeps on this machine: `~/.synapse/cluster.toml` and, beside it, `tokens/<cluster id>/*.jwt`.
+// This is `crates/synapse-client/src/target.rs` line for line (the grammar, `pick`, the freshness margin, the
+// URL, the error sentences); the CLI owns the files and the key server, this module only reads. Bun/Node
+// only: the file system is imported lazily, so a browser bundle carries no Node import.
+// Or (PLAN v0.38 §3.2), for a node with a signed-in person (`setAuth`), from the key server: the same grammar, the same
+// `pick`, the relay and the runtime from its discover answer, the token for the cluster from it (`resolveViaKeyserver`).
+// With neither, a target string is refused at `connect()` (`BROWSER_REFUSAL`).
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { SynapseError } from "@synapse-sdk/core";
+/** What `-t local` means: the runtime on this machine, dialed directly. */
+export const LOCAL = "local";
+/** The runtime on this machine. */
+export const LOCAL_URL = "https://localhost:4470";
+/** A token is treated as expired when it expires within this many seconds (`target.rs` `FRESH_FOR_S`). */
+export const FRESH_FOR_S = 5 * 60;
+/** What a file an older synapse wrote is told. */
+const UPDATE = "run synapse login to update the file";
+/** The `kind` kept for an org's cluster (anything else is a person's own). */
+const ORG = "org";
+/** Whether `s` is a URL (a scheme and `://`); anything else given as a url is a target. */
+export function isUrl(s) { return /^[a-z][a-z0-9+.-]*:\/\//i.test(s); }
+/** Rust's `{:?}` of a string, as the error sentences quote it. */
+const q = (s) => JSON.stringify(s);
+/** A runtime id or a cluster id: a UUID in its canonical lowercase text. */
+export function isId(s) { return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(s); }
+/** A runtime name: `[a-z0-9_-]{1,64}`, and never a runtime id. */
+export function validName(s) { return /^[a-z0-9_-]{1,64}$/.test(s) && !isId(s); }
+/** A cluster name: lowercase letters, digits and `-`, at most 63, not starting with `-`, not `none`. */
+export function validClusterName(s) { return s !== "none" && /^[a-z0-9-]{1,63}$/.test(s) && !s.startsWith("-"); }
+/** How people name it: `name` (yours) or `owner/name` (an org's). */
+export function label(k) { return k.personal ? k.name : `${k.owner}/${k.name}`; }
+export function parseClusterRef(s) {
+    const i = s.indexOf("/");
+    const owner = i >= 0 ? s.slice(0, i) : undefined;
+    const name = i >= 0 ? s.slice(i + 1) : s;
+    if (!validClusterName(name))
+        throw new Error(`a cluster is <name> or <org>/<name>, the name lowercase letters, digits and '-' (and not \`none\`); got ${q(s)}`);
+    if (owner !== undefined && !/^[A-Za-z0-9_-]+$/.test(owner))
+        throw new Error(`a cluster is <name> or <org>/<name>, the org its slug or id; got ${q(s)}`);
+    return owner === undefined ? { name } : { owner, name };
+}
+const refText = (r) => r.owner === undefined ? r.name : `${r.owner}/${r.name}`;
+/**
+ * The resolution rule: the cluster `r` names among `known`. `<owner>/<name>`: that org's cluster of that name.
+ * `<name>`: your own cluster of that name, else the one org cluster of that name; two or more such org clusters
+ * are an error naming each one's qualified form. `undefined`: no cluster by that reference.
+ */
+export function pick(known, r) {
+    const named = known.filter(k => k.name === r.name);
+    if (r.owner !== undefined)
+        return named.find(k => !k.personal && k.owner === r.owner);
+    const mine = named.find(k => k.personal);
+    if (mine)
+        return mine;
+    if (named.length <= 1)
+        return named[0];
+    const forms = named.map(label);
+    const last = forms.pop();
+    throw new Error(`more than one cluster is named ${q(r.name)}: say ${forms.join(", ")} or ${last}`);
+}
+export function parseTarget(s) {
+    if (s === LOCAL)
+        return { kind: "local" };
+    const i = s.indexOf("@");
+    const runtime = i >= 0 ? s.slice(0, i) : s;
+    const cluster = i >= 0 ? s.slice(i + 1) : undefined;
+    if (runtime === "" || cluster === "")
+        throw new Error(`a runtime is <name>[@<cluster>] or local, got ${q(s)}`);
+    return cluster === undefined ? { kind: "runtime", runtime } : { kind: "runtime", runtime, cluster };
+}
+/** `parseTarget`, and the runtime a name or a runtime id and the cluster a cluster reference. */
+export function parseTargetStrict(s) {
+    const t = parseTarget(s);
+    if (t.kind === "runtime") {
+        if (!validName(t.runtime) && !isId(t.runtime))
+            throw new Error(`a runtime is <name>[@<cluster>] or local, the name [a-z0-9_-]{1,64} or a runtime id; got ${q(s)}`);
+        if (t.cluster !== undefined)
+            parseClusterRef(t.cluster);
+    }
+    return t;
+}
+/** The refusal of a target string where nobody is signed in (`setAuth`) and the CLI's files cannot be read (a browser). */
+export const BROWSER_REFUSAL = "connect by name needs a signed-in person (setAuth) or the CLI's files on this machine; or pass the relay URL and a token";
+/** Whether this is Bun/Node, where the CLI's files can be read. */
+export function canReadFiles() {
+    const p = globalThis.process;
+    return typeof p?.versions?.node === "string";
+}
+const invalid = (e) => e instanceof SynapseError ? e : new SynapseError("invalid_input", { message: e instanceof Error ? e.message : String(e), source: "sdk" });
+let io;
+/** The file system, imported on first use (never at the top: a browser bundle must not see Node modules). */
+function loadIo() {
+    return io ??= (async () => {
+        // Specifiers in variables: bundlers leave them alone (the same as `ensureWebTransport`).
+        const [fsSpec, osSpec, pathSpec] = ["node:fs/promises", "node:os", "node:path"];
+        const fs = (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ fsSpec)));
+        const os = (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ osSpec)));
+        const path = (await import(__rewriteRelativeImportExtension(/* @vite-ignore */ pathSpec)));
+        return {
+            readFile: p => fs.readFile(p, "utf8"),
+            isFile: p => fs.stat(p).then(s => s.isFile(), () => false),
+            homedir: () => os.homedir(),
+            join: (...parts) => path.join(...parts),
+            dirname: p => path.dirname(p),
+        };
+    })().catch((e) => { io = undefined; throw new SynapseError("invalid_input", { message: BROWSER_REFUSAL, source: "sdk", cause: e }); });
+}
+/** Where cluster.toml is: `$HOME/.synapse/cluster.toml` (`$HOME` read now, as Rust does; the OS's home without it). */
+function defaultPath(io) {
+    const env = globalThis.process?.env?.HOME;
+    const home = env || io.homedir();
+    if (!home)
+        throw new Error("HOME is not set");
+    return io.join(home, ".synapse/cluster.toml");
+}
+/** Where token `name` of cluster `id` is kept: `tokens/<id>/<name>.jwt` next to cluster.toml at `config`. */
+function tokenFile(io, config, id, name) { return io.join(io.dirname(config), "tokens", id, `${name}.jwt`); }
+const isTable = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Date);
+/** Whether `raw` keeps clusters by name, as the synapse before cluster ids did. */
+function oldStyle(raw) {
+    const named = isTable(raw.cluster) && Object.keys(raw.cluster).some(k => !isId(k));
+    return named || (typeof raw.default === "string" && !isId(raw.default));
+}
+/** The shape check Rust's `deny_unknown_fields` structs make. */
+function schema(raw) {
+    const known = (t, keys) => { for (const k of Object.keys(t))
+        if (!keys.includes(k))
+            throw new Error(`unknown field \`${k}\`, expected one of ${keys.map(k => `\`${k}\``).join(", ")}`); };
+    const str = (t, k, need) => {
+        const v = t[k];
+        if (v === undefined) {
+            if (need)
+                throw new Error(`missing field \`${k}\``);
+            return undefined;
+        }
+        if (typeof v !== "string")
+            throw new Error(`invalid type for \`${k}\`, expected a string`);
+        return v;
+    };
+    known(raw, ["keyserver", "default", "default_runtime", "cluster"]);
+    const file = { cluster: {} };
+    for (const k of ["keyserver", "default", "default_runtime"]) {
+        const v = str(raw, k, false);
+        if (v !== undefined)
+            file[k] = v;
+    }
+    if (raw.cluster !== undefined && !isTable(raw.cluster))
+        throw new Error("invalid type for `cluster`, expected a table");
+    for (const [id, c] of Object.entries(raw.cluster ?? {})) {
+        if (!isTable(c))
+            throw new Error(`invalid type for \`cluster.${id}\`, expected a table`);
+        known(c, ["name", "owner", "kind", "relay", "token", "runtimes"]);
+        const entry = { name: str(c, "name", true), owner: str(c, "owner", true), kind: str(c, "kind", true), relay: str(c, "relay", true), runtimes: {} };
+        const token = str(c, "token", false);
+        if (token !== undefined)
+            entry.token = token;
+        if (c.runtimes !== undefined) {
+            if (!isTable(c.runtimes))
+                throw new Error("invalid type for `runtimes`, expected a table");
+            for (const r of Object.keys(c.runtimes))
+                entry.runtimes[r] = str(c.runtimes, r, true);
+        }
+        file.cluster[id] = entry;
+    }
+    return file;
+}
+/** cluster.toml's text, the file at `path`; a file that keeps clusters by name (not by id) is refused. */
+export async function parseClusterFile(text, path) {
+    const { parse } = await import("smol-toml");
+    let raw;
+    try {
+        raw = parse(text);
+    }
+    catch (e) {
+        throw new Error(`${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (oldStyle(raw))
+        throw new Error(`${path} names clusters as an older synapse did; ${UPDATE}`);
+    try {
+        return schema(raw);
+    }
+    catch (e) {
+        throw new Error(`${path} (a key from an older synapse? ${UPDATE}): ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+async function loadClusterFile(io, path) {
+    let text;
+    try {
+        text = await io.readFile(path);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return { cluster: {} };
+        throw new Error(`reading ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return parseClusterFile(text, path);
+}
+/** `clusters` in id order (Rust's `BTreeMap`: the order the ambiguity error lists them in), from cluster.toml or the key server. */
+function knownOf(clusters) {
+    return [...clusters].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+/** The clusters `file` keeps. */
+function knownOfFile(file) { return knownOf(Object.keys(file.cluster).map(id => knownId(file, id))); }
+/** A cluster as the key server lists it (`GET /discover`): yours when its owner is a user; an organization's by its slug, or its id without one. */
+export function knownOfListed(c) {
+    return { id: c.id, name: c.name, owner: c.owner.slug ?? c.owner.id, personal: c.owner.kind === "user" };
+}
+function knownId(file, id) {
+    const c = file.cluster[id];
+    return c && { id, name: c.name, owner: c.owner, personal: c.kind !== ORG };
+}
+// ------------------------------------------------------------------------------------ tokens
+/** The `exp` claim (seconds since the epoch) of a token, read from its payload without checking it. */
+export function tokenExp(jwt) {
+    const payload = jwt.trim().split(".")[1];
+    if (payload === undefined)
+        return undefined;
+    const b64 = payload.replace(/=+$/, "");
+    if (!/^[A-Za-z0-9_-]*$/.test(b64) || b64.length % 4 === 1)
+        return undefined;
+    try {
+        const bin = atob(b64.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - b64.length % 4) % 4));
+        const claims = JSON.parse(new TextDecoder().decode(Uint8Array.from(bin, ch => ch.charCodeAt(0))));
+        const exp = isTable(claims) ? claims.exp : undefined;
+        return typeof exp === "number" && Number.isInteger(exp) && exp >= 0 ? exp : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The token at `path` when it is there and does not expire within `FRESH_FOR_S` (a token without `exp` never expires). */
+async function freshToken(io, path) {
+    let token;
+    try {
+        token = (await io.readFile(path)).trim();
+    }
+    catch {
+        return undefined;
+    }
+    if (token === "")
+        return undefined;
+    const exp = tokenExp(token);
+    return exp !== undefined && exp <= Math.floor(Date.now() / 1000) + FRESH_FOR_S ? undefined : token;
+}
+// ------------------------------------------------------------------------------------ resolve
+/**
+ * The target string `s` as the CLI's `-t` reads it, from `$HOME/.synapse/cluster.toml` and the tokens beside it,
+ * reading only: the cluster by `pick` (`@<cluster>`) or the default one; the runtime id from the file (a runtime id
+ * is taken as it is); the token the file names for the cluster while it is fresh, else this machine's own token for
+ * that runtime. A miss is `invalid_input`, a missing or expired token `unauthorized`, each naming the CLI command
+ * that fixes it. Read anew at every call (a token the CLI refreshed is the next dial's).
+ */
+export async function resolveStr(s) {
+    let target;
+    try {
+        target = parseTargetStrict(s);
+    }
+    catch (e) {
+        throw invalid(e);
+    }
+    if (target.kind === "local")
+        return local();
+    if (!canReadFiles())
+        throw new SynapseError("invalid_input", { message: BROWSER_REFUSAL, source: "sdk" });
+    const fsio = await loadIo();
+    let config, file;
+    try {
+        config = defaultPath(fsio);
+        file = await loadClusterFile(fsio, config);
+    }
+    catch (e) {
+        throw invalid(e);
+    }
+    const { runtime } = target;
+    let cluster;
+    try {
+        if (target.cluster !== undefined) {
+            const r = parseClusterRef(target.cluster);
+            const k = pick(knownOfFile(file), r);
+            if (!k)
+                throw new Error(`cluster ${refText(r)} is not known on this machine: run synapse cluster login ${refText(r)} (synapse login first)`);
+            cluster = k;
+        }
+        else {
+            const k = file.default === undefined ? undefined : knownId(file, file.default);
+            if (!k)
+                throw new Error("no cluster chosen: synapse cluster login <cluster> first");
+            cluster = k;
+        }
+    }
+    catch (e) {
+        throw invalid(e);
+    }
+    const lbl = label(cluster);
+    const entry = file.cluster[cluster.id];
+    const id = isId(runtime) ? runtime : entry.runtimes[runtime];
+    if (id === undefined)
+        throw invalid(`no runtime named ${q(runtime)} is known on this machine in cluster ${lbl}: run synapse cluster runtime list ${lbl}`);
+    const devicePath = tokenFile(fsio, config, cluster.id, runtime);
+    const device = validName(runtime) && await fsio.isFile(devicePath) ? devicePath : undefined;
+    const token = (entry.token !== undefined ? await freshToken(fsio, entry.token) : undefined) ?? (device !== undefined ? await freshToken(fsio, device) : undefined);
+    if (token === undefined) {
+        const fix = device !== undefined ? `run synapse cluster login ${lbl}, or synapse runtime init again on this machine` : `run synapse cluster login ${lbl}`;
+        const why = entry.token !== undefined ? `the token for cluster ${lbl} on this machine has expired or is gone` : `logged out of cluster ${lbl}`;
+        throw new SynapseError("unauthorized", { message: `${why}: ${fix}`, source: "sdk" });
+    }
+    let url;
+    try {
+        url = new URL(entry.relay);
+    }
+    catch (e) {
+        throw invalid(`the relay of cluster ${lbl} is not a URL: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    url.pathname = `/cluster/${cluster.id}/runtimes/${id}`;
+    return { url: url.toString(), token, label: `${runtime}@${lbl}` };
+}
+function local() { return { url: LOCAL_URL, token: undefined, label: LOCAL }; }
+/**
+ * The target string `s` resolved through the key server for the signed-in person of `auth` (PLAN v0.38 §3.3): the grammar
+ * and `pick` as `resolveStr`; the cluster among your clusters (the discover answer the node keeps, else asked now), the
+ * runtime id from its runtimes (a runtime id is taken as it is), the relay from the answer, the cluster's token (kept while
+ * fresh, else asked now). A miss in a kept answer asks the key server once more (a runtime enrolled since), then is
+ * `invalid_input`. `cluster` and `cached` tell the dial which token to drop if the relay refuses a kept one; `local` has neither.
+ */
+export async function resolveViaKeyserver(s, auth) {
+    let target;
+    try {
+        target = parseTargetStrict(s);
+    }
+    catch (e) {
+        throw invalid(e);
+    }
+    if (target.kind === "local")
+        return { ...local(), cluster: undefined, cached: false };
+    const { runtime } = target;
+    if (target.cluster === undefined)
+        throw invalid(`say which of your clusters: ${runtime}@<cluster>`);
+    const ref = parseClusterRef(target.cluster);
+    let { discovery, cached } = await auth.known();
+    for (;;) {
+        let k;
+        try {
+            k = pick(knownOf(discovery.clusters.map(knownOfListed)), ref);
+        }
+        catch (e) {
+            throw invalid(e);
+        }
+        const c = k && discovery.clusters.find(c => c.id === k.id);
+        const id = c && (isId(runtime) ? runtime : c.runtimes[runtime]);
+        if (k && c && id !== undefined) {
+            const { token, cached: tokenCached } = await auth.clusterToken(c.id);
+            const lbl = label(k);
+            let url;
+            try {
+                url = new URL(discovery.relay);
+            }
+            catch (e) {
+                throw invalid(`the relay the key server named is not a URL: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            url.pathname = `/cluster/${c.id}/runtimes/${id}`;
+            return { url: url.toString(), token, label: `${runtime}@${lbl}`, cluster: c.id, cached: tokenCached };
+        }
+        if (!cached)
+            throw invalid(k ? `nothing named ${q(runtime)} in your cluster ${label(k)}` : `nothing named ${refText(ref)} in your clusters`);
+        discovery = await auth.discover();
+        cached = false;
+    }
+}

package/dist/types.d.ts

@@ -41,6 +41,18 @@ export interface ConnectTarget {
     /**
      * The runtime, `https://host:4470` (the path to dial is learned from the runtime at every attempt). Through a relay: the relay with
      * the runtime's path, `https://<relay>/cluster/<cluster>/runtimes/<runtime_id>`, and `token`. A `jwt=` in the URL is taken as the token.
+     *
+     * Or, in Bun/Node, a target as the CLI's `-t` names it (anything without `<scheme>://`): `"infra-1@devel"` (runtime `infra-1`
+     * of cluster `devel`), `"infra-1"` (in the default cluster), `"arm@medatech/devel"` (an org's cluster, by its slug). The relay
+     * URL and the token come from the CLI's files on this machine (`~/.synapse/cluster.toml` and the tokens beside it), read again
+     * at every attempt, so a token the CLI refreshed is used on the next reconnect (`token` given here wins). The SDK only reads
+     * those files: `synapse login` and `synapse cluster login <cluster>` first. A name this machine does not know is
+     * `invalid_input`, a missing or expired token `unauthorized`, each naming the CLI command that fixes it.
+     *
+     * With a person signed in (`node.setAuth`), in a browser or in Bun/Node, the same names are resolved through the key
+     * server instead, from your clusters: `"infra-1@devel"`, `"arm@medatech/devel"` (the cluster is always named). A name
+     * not in your clusters is `invalid_input`; nobody signed in, or a sign-in the key server does not take, `unauthorized`.
+     * In a browser with nobody signed in, a name is refused at once (`invalid_input`): sign in, or pass the relay URL and a token.
      */
     url: string;
     /** The type to declare there; left out keeps the node's current one. */
@@ -51,7 +63,7 @@ export interface ConnectTarget {
     userId?: string;
     /** The credential to present there; left out keeps the node's current one. Never printed. */
     credential?: string;
-    /** Pin of *this* broker's self-signed certificate (SHA-256 hex). Absent: `SYNAPSE_BROKER_CERT_SHA256`, then the broker's helper, then unpinned (per attempt). */
+    /** Pin of *this* runtime's self-signed certificate (SHA-256 hex). Absent: `SYNAPSE_BROKER_CERT_SHA256`, then, for a runtime URL (no path), its helper; a URL naming a root (a relay) connects unpinned against the system's roots (per attempt). */
     brokerCertSha256?: string;
     /** The relay token for *this* target; left out = no token (a token for another runtime would be refused). Never printed. */
     token?: string;
@@ -85,6 +97,42 @@ export type ConnectionState = {
     status: "failed";
     error: SynapseError;
 };
+/**
+ * Gives the signed-in person's credential for the key server, fetched each time the node asks it (`setAuth`);
+ * `null` or `undefined` means nobody is signed in.
+ */
+export type FetchToken = () => Promise<string | null | undefined>;
+/** The key server's answer about the signed-in person (`node.discover()`): the relay to dial and your clusters with their runtimes. */
+export interface Discovery {
+    /** The relay a runtime of these clusters is dialed through. */
+    relay: string;
+    /** The signed-in person. */
+    userId: string;
+    /** Your clusters: your own, and those of the organizations you belong to. */
+    clusters: {
+        id: string;
+        name: string;
+        /** Who owns it: `kind` `user` (yours) or `org`, its `id`, and the organization's `slug` when it has one. */
+        owner: {
+            kind: string;
+            id: string;
+            slug?: string;
+        };
+        /** How `connect()` names it: `name` for yours, `<slug>/<name>` (or `<org id>/<name>`) for an organization's: `"infra-1@" + label`. */
+        label: string;
+        /** Its runtimes, name → runtime id. */
+        runtimes: Record<string, string>;
+    }[];
+}
+/**
+ * `node.discovery`: `idle` with nobody signed in (or just after `setAuth`), `pending` while the key server is asked,
+ * `success` with the answer, `error` with why it failed (`data` still holds the last answer, if there was one).
+ */
+export interface DiscoveryState {
+    status: "idle" | "pending" | "success" | "error";
+    data?: Discovery;
+    error?: SynapseError;
+}
 /** This node's identity and the current session's hello facts; empty strings between sessions. */
 export interface Info {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapse-sdk/client",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Synapse SDK client: connect a node to the runtime; topics, services, calls, store, video.",
   "type": "module",
   "sideEffects": false,
@@ -14,8 +14,9 @@
     "dist"
   ],
   "dependencies": {
-    "@synapse-sdk/core": "0.3.6",
-    "@moq/net": "0.4.2"
+    "@synapse-sdk/core": "0.3.7",
+    "@moq/net": "0.4.2",
+    "smol-toml": "1.9.0"
   },
   "peerDependencies": {
     "@moq/web-transport": "0.1.5"