@synapse-sdk/client 0.3.6 → 0.3.8

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, ProjectListing, 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. */
@@ -108,6 +133,11 @@ export declare class Synapse implements AsyncDisposable {
      * resolves once the demoted session is connected.
      */
     leaveProject(): Promise<ProjectSnapshot>;
+    /**
+     * `synapse/project/list {}`: every project the runtime has, sorted by id: what each names (`name` when it has one,
+     * `scene_id`, `store_id`, whether it is the active one), or why it cannot be read (`error`). Changes nothing.
+     */
+    listProjects(): Promise<ProjectListing>;
     /**
      * The robot's task declarations, what runs (`status`), what the runtime can run (`catalog`), and the verbs; the same
      * object for the node's life. Each handle opens on its first touch and is the node's own (`node.close()` ends it).

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(); }
@@ -319,6 +355,11 @@ export class Synapse {
      * resolves once the demoted session is connected.
      */
     leaveProject() { return this.#projectCall("leave", {}); }
+    /**
+     * `synapse/project/list {}`: every project the runtime has, sorted by id: what each names (`name` when it has one,
+     * `scene_id`, `store_id`, whether it is the active one), or why it cannot be read (`error`). Changes nothing.
+     */
+    listProjects() { return this.call("synapse/project/list", {}).result; }
     // -------------------------------------------------------------------------------- tasks
     #tasks;
     /**

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;
+    }
+}