@calimero-network/mero-js 22.7.0 → 22.9.0

package/dist/transport/mero-client.js

@@ -0,0 +1,379 @@
+/**
+ * One client, two transports — chosen once, at construction.
+ *
+ * # The problem this exists for
+ *
+ * An app that wants to move from "the user has a node" to "the user has a key
+ * and a relay" had to rewrite itself, because the two write paths are different
+ * objects with different method shapes. That makes the transport a property of
+ * the *application source*, when it is really a property of the connection: the
+ * same screen, the same hook, the same `execute` call wants to work either way.
+ *
+ * `createMeroClient` takes the decision at construction and nowhere else. After
+ * that, `client.rpc.execute({ contextId, method, argsJson })` is the same call
+ * against a node and against a relay — same arguments, same return type. The
+ * node shape is the one both speak, because shipped apps already write it and
+ * the alternative would be a breaking change wearing an abstraction's clothes.
+ *
+ * # Defaulting to the node is a compatibility guarantee
+ *
+ * `createMeroClient({ baseUrl })` is `createMeroJs({ baseUrl })` with a facade
+ * in front. No `transport` field means `'node'`, so nothing an existing app
+ * does can accidentally select the relay.
+ *
+ * # Events work on both transports, given one input
+ *
+ * A relay is an ordinary node, so it serves `/sse` and `/ws` to a credential it
+ * issued, and a keyholder can obtain one by logging in with its account proof.
+ * `client.events` and `client.ws` are therefore the same call on both
+ * transports — provided the caller supplies the relay node's device signing
+ * key, which must be learned out of band and is the one thing that cannot be
+ * inferred. See `./relay-observer.ts` for why, and mdma #312 for the hosted
+ * case. Without it, {@link MeroClient.canSubscribe} is `false` and the
+ * accessors throw naming exactly that.
+ *
+ * # What is deliberately NOT unified
+ *
+ * Reads and admin. A relay serves exactly two routes to a caller with no
+ * credential — `GET` and `POST /admin-api/contexts/:id/intents` — and while a
+ * session obtained by logging in carries `context:query`, `sdk.admin` wants
+ * `admin`, which the `account_proof` provider does not grant and a keyholder
+ * should never ask for.
+ *
+ * So those accessors throw on a relay client, with a message naming what is
+ * missing, rather than returning something that quietly connects somewhere
+ * else. Falling back to "some node" would be the worst of the options: the app
+ * would observe a node it never chose, under a credential it never granted, and
+ * find out only when the two disagreed. `canSubscribe` and `transport` are
+ * there so an app can branch *before* touching any of it.
+ */
+import { MeroJs } from '../mero-js.js';
+import { RelayClient } from '../relay/relay-client.js';
+import { RelayTransport } from './relay-transport.js';
+import { RelayObserver, defaultAudience } from './relay-observer.js';
+import { createAdminApiClient, createAdminApiClientFromHttpClient } from '../admin-api/index.js';
+import { createHttpClient } from '../http-client/index.js';
+import { createProofAuthorizer } from '../request-proof/index.js';
+import { SseClient } from '../events/sse.js';
+/** Message shared by every node-only accessor, so the reason is stated once. */
+function relayHasNo(surface, why) {
+    return new Error(`this client was constructed with the relay transport, which has no ${surface}: ${why}. ` +
+        'Construct a node client (createMeroClient({ baseUrl })) for that surface — ' +
+        'nothing here will silently connect to a node you did not choose.');
+}
+/**
+ * The one thing a relay client can be missing, named precisely.
+ *
+ * Deliberately not the same message as {@link relayHasNo}: this is not "the
+ * relay transport has no such surface". The relay has the surface — it serves
+ * `/sse` and `/ws`, and the `account_proof` provider grants
+ * `context:subscribe`. What is missing is a single 32-byte value, and a caller
+ * who can obtain it needs to be told that, not told to go and build a node
+ * client.
+ */
+function missingNodeKey(surface) {
+    return new Error(`this relay-transport client cannot open ${surface}: it was given no relay node key. ` +
+        'A relay is an ordinary node and does serve /sse and /ws — but the login statement must be ' +
+        "signed against the node's device signing key, learned out of band (never read from the node, " +
+        'and never derived from its peerId). Pass it as `observe: { nodeKey }`. ' +
+        'For a cloud-hosted relay the cloud does not publish it yet — see mdma #312.');
+}
+/**
+ * Resolve an observe config against the relay client that will do the writing.
+ *
+ * Returns `null` for "no key, so no observation" — the single place that
+ * decision is made, so `canSubscribe`, `events` and `ws` cannot disagree about
+ * it. The signer and proof default to the relay's own: the same device that
+ * authors is the device that observes, and taking a second copy from the caller
+ * is how the two come to name different keys.
+ */
+function buildObserver(relay, observe) {
+    const nodeKey = observe?.nodeKey;
+    if (!nodeKey)
+        return null;
+    return new RelayObserver({
+        nodeUrl: observe?.nodeUrl ?? relay.relayUrl,
+        nodeKey,
+        accountProof: observe?.accountProof ?? relay.authorProof,
+        audience: observe?.audience ?? defaultAudience(),
+        signer: observe?.signer ? async () => observe.signer : () => relay.authorSigner(),
+        clientName: observe?.clientName,
+        ttlSeconds: observe?.ttlSeconds,
+        fetch: observe?.fetch,
+        timeoutMs: observe?.timeoutMs,
+    });
+}
+/**
+ * A connection whose transport was decided at construction.
+ *
+ * Everything reachable on a node client is reachable in exactly the shape
+ * `MeroJs` exposes it, by delegation rather than re-implementation — this adds
+ * no behaviour to the node path and cannot drift from it.
+ */
+export class MeroClient {
+    constructor(config) {
+        /** The relay's event session, or `null` on a node client / with no node key. */
+        this.relayObserver = null;
+        /** Admin reads against the relay, when a session or a proof was supplied. */
+        this.relayAdmin = null;
+        /**
+         * Events off the relay authenticated by a request proof, built lazily.
+         *
+         * Separate from {@link relayObserver} rather than a mode inside it: the
+         * observer's whole subject is a session addressed to a node key, and a proof
+         * has neither. Holding the authorizer instead of the client keeps construction
+         * free of the first signature.
+         */
+        this.proofAuthorizer = null;
+        this.relayUrl = null;
+        this.proofEvents = null;
+        if (config.transport === 'relay') {
+            this.transport = 'relay';
+            this.nodeClient = null;
+            const relay = config.relay instanceof RelayClient ? config.relay : new RelayClient(config.relay);
+            this.relayObserver = buildObserver(relay, config.observe);
+            this.rpcTransport = new RelayTransport(relay, this.relayObserver);
+            this.relayUrl = relay.relayUrl;
+            if (config.proof) {
+                this.proofAuthorizer = createProofAuthorizer(config.proof);
+            }
+            // A session wins where both are present. Not a preference between
+            // credentials but the node's own precedence: it answers a request carrying
+            // a token by that token and consults a proof only when there is none, so
+            // sending both would authenticate by the session anyway — and a client
+            // whose reads and whose events disagreed about which identity they ran as
+            // is the one outcome worth ruling out here.
+            if (config.session) {
+                const token = config.session;
+                this.relayAdmin = createAdminApiClient({
+                    baseUrl: relay.relayUrl,
+                    getAuthToken: typeof token === 'string' ? async () => token : token,
+                });
+            }
+            else if (this.proofAuthorizer) {
+                const authorizeRequest = this.proofAuthorizer;
+                this.relayAdmin = createAdminApiClientFromHttpClient(createHttpClient({
+                    fetch: (url, init) => globalThis.fetch(url, init),
+                    baseUrl: relay.relayUrl,
+                    authorizeRequest,
+                }), { baseUrl: relay.relayUrl });
+            }
+            return;
+        }
+        this.transport = 'node';
+        // `transport` is a marker this class reads and `MeroJs` has never seen.
+        // Stripped rather than passed through, so nothing downstream has to know
+        // that the field exists.
+        const { transport: _ignored, ...nodeConfig } = config;
+        this.nodeClient = new MeroJs(nodeConfig);
+        this.rpcTransport = this.nodeClient.rpc;
+    }
+    /**
+     * The write surface. Identical on both transports — this is the whole point.
+     *
+     * On a node this IS the `RpcClient` a `MeroJs` would have handed out, not a
+     * wrapper around it, so `client.rpc` and `client.node.rpc` are the same
+     * object.
+     */
+    get rpc() {
+        return this.rpcTransport;
+    }
+    /**
+     * Whether `events` / `ws` will work on this client.
+     *
+     * Always `true` on the node transport. On the relay transport it says whether
+     * a node key was supplied — the relay can be observed, but only by a caller
+     * who can name the key the login statement is signed against.
+     */
+    get canSubscribe() {
+        return this.rpcTransport.canSubscribe || this.proofAuthorizer !== null;
+    }
+    /** The underlying `MeroJs`. Node transport only. */
+    get node() {
+        if (!this.nodeClient) {
+            throw relayHasNo('node connection', 'it holds a signing key and a relay URL, not a node');
+        }
+        return this.nodeClient;
+    }
+    /** The underlying `RelayClient`, for `describe()`. Relay transport only. */
+    get relay() {
+        if (!(this.rpcTransport instanceof RelayTransport)) {
+            throw new Error('this client was constructed with the node transport and has no relay');
+        }
+        return this.rpcTransport.client;
+    }
+    /**
+     * Admin API. Node transport only.
+     *
+     * Two different things live behind this accessor today, and only one of them
+     * is genuinely unavailable through a relay.
+     *
+     * The **mutations** — `createNamespace`, `setMemberCapabilities`,
+     * `upgradeGroup` and the rest — are operator actions on somebody else's
+     * machine. A keyholder does not get those, and should not; admin is for
+     * admins.
+     *
+     * The **reads** are a different matter. `getContext`, `getContexts`,
+     * `getApplication`, `listNamespaces`, `getBlob` are an app asking what it is
+     * looking at, not an operator administering anything. They sit under
+     * `/admin-api/` for historical reasons, and a delegated session is refused
+     * them (measured: `403`, while the same session reads context state through
+     * `POST /contexts/{ctx}/query` and writes through `/intents` quite happily).
+     *
+     * So this is the one place where "the same code runs on both transports"
+     * does not hold yet, and it is a missing surface rather than a missing
+     * permission. A transport-independent read API is designed but not built; the
+     * throw below is deliberate until it exists, because the alternative — quietly
+     * reaching for a node the caller did not choose — is worse than a clear stop.
+     */
+    /**
+     * The admin surface.
+     *
+     * On a node client this is the node's own. On a relay client it exists only
+     * when a `session` was supplied, and it is **the relay's admin API
+     * authenticated as the account** — so the caller-scoped reads answer:
+     * `getContexts` and `listNamespaces` return this account's own, because
+     * `account_proof` grants `context:list-own` and `namespace:list-own`.
+     *
+     * Mutations are not filtered out here, deliberately. A delegated session does
+     * not carry the grants they require, so the node refuses them with a `403`
+     * that names the missing permission — which is a better answer than a
+     * client-side guess, and keeps the policy in the one place that owns it.
+     */
+    get admin() {
+        if (this.nodeClient)
+            return this.nodeClient.admin;
+        if (this.relayAdmin)
+            return this.relayAdmin;
+        throw new Error('this relay-transport client has no admin surface because it was given neither a `proof` ' +
+            'nor a `session`. A warrant authorises one intent and is not a credential for reading. ' +
+            'The caller-scoped reads (getContexts, listNamespaces) want one of the other two: pass ' +
+            '`proof: { credential, deviceSecret }` — the device cert you already hold, which needs ' +
+            'no login and no node key — or a `session` minted with `login()`. Context STATE reads ' +
+            'work through execute/query either way.');
+    }
+    /** Auth API. Node transport only — a relay issues no node credential. */
+    get auth() {
+        return this.node.auth;
+    }
+    /**
+     * SSE events — on **both** transports.
+     *
+     * On a relay client this is an `SseClient` against the relay node, fed by a
+     * session minted with the author's account proof. The session is minted
+     * lazily, on the first token the stream asks for, so reading this getter
+     * performs no network call.
+     *
+     * Throws only when the relay client was given no node key: the one input
+     * that cannot be inferred. See {@link missingNodeKey}.
+     */
+    get events() {
+        if (this.nodeClient)
+            return this.nodeClient.events;
+        if (this.relayObserver)
+            return this.relayObserver.events;
+        if (this.proofAuthorizer && this.relayUrl) {
+            // Built on first use and then kept: a second `SseClient` would open a
+            // second stream and split the subscriptions across two sessions, so the
+            // caller would see some of its events on an object it no longer holds.
+            this.proofEvents ?? (this.proofEvents = new SseClient({
+                baseUrl: this.relayUrl,
+                authorize: this.proofAuthorizer,
+            }));
+            return this.proofEvents;
+        }
+        throw missingNodeKey('SSE events');
+    }
+    /** WebSocket events, on both transports. @experimental — prefer `events`. */
+    get ws() {
+        if (this.nodeClient)
+            return this.nodeClient.ws;
+        if (this.relayObserver)
+            return this.relayObserver.ws;
+        if (this.proofAuthorizer) {
+            // Not a missing credential: a proof DOES open `/ws` — measured, `101`
+            // against a node built from core `aecba573b`. What is missing is a way to
+            // carry it, and that is the browser's. `WebSocket` cannot set a request
+            // header, and the guard reads the proof from a header only; the `?token=`
+            // query parameter this client uses for a session exists for exactly that
+            // reason and has no proof equivalent yet.
+            throw new Error('this client authenticates with a request proof, which cannot open a WebSocket from a ' +
+                "browser: `WebSocket` cannot set the X-Calimero-Proof header, and core's guard reads " +
+                'the proof from a header only (the ?token= query parameter is the session equivalent ' +
+                'and has no proof counterpart). Use `client.events` — SSE is fetch-based, carries the ' +
+                'header, and is the recommended transport anyway.');
+        }
+        throw missingNodeKey('WebSocket events');
+    }
+    /**
+     * Ephemeral presence. Node transport only.
+     *
+     * Not extended to the relay even though a logged-in session could reach both
+     * halves of it mechanically. Publishing resolves the author from an *owned
+     * context identity on the node*, and whether a delegated session has one has
+     * not been established — a presence client that silently published nothing,
+     * or published as the wrong identity, is worse than one that says it is not
+     * available. The read half is not lost: presence arrives on `client.events`
+     * like any other context event, and can be filtered there.
+     *
+     * The rejected alternative was to expose it over the relay session and let
+     * `set` fail at the node. That trades a clear construction-time answer for a
+     * runtime failure inside a UI that has already rendered.
+     */
+    get ephemeral() {
+        if (!this.nodeClient) {
+            throw relayHasNo('ephemeral presence', 'publishing resolves the author from an owned context identity on the node, which a delegated session is not known to have — read presence off `client.events` instead');
+        }
+        return this.nodeClient.ephemeral;
+    }
+    /**
+     * Calimero Cloud.
+     *
+     * Available on both transports, because it is neither: the cloud session is
+     * independent of the node credential and of the relay's signing key, and a
+     * relay-transport app still needs it to list namespaces and manage billing.
+     */
+    get cloud() {
+        if (!this.nodeClient) {
+            throw relayHasNo('bundled cloud client', 'a relay client is built from a cloud connection rather than owning one — reach it through the `cloud` field that `connectCloud` returns, or construct a `CloudClient` directly');
+        }
+        return this.nodeClient.cloud;
+    }
+    /**
+     * Release whatever the transport is holding.
+     *
+     * Safe on a relay client, where there is nothing open to close — a caller
+     * that tears down on unmount should not have to know which transport it got.
+     */
+    close() {
+        this.nodeClient?.close();
+        // The observer and the proof stream, not the relay: a relay client holds
+        // nothing open. Tearing down on unmount must not have to know which
+        // transport — or which credential — it got.
+        this.relayObserver?.close();
+        this.proofEvents?.close();
+    }
+}
+/**
+ * Build a client for the chosen transport. Node unless told otherwise.
+ *
+ * ```ts
+ * // unchanged, and still the default
+ * const client = createMeroClient({ baseUrl: 'http://localhost:2428' });
+ *
+ * // the same call sites, through a relay
+ * const client = createMeroClient({
+ *   transport: 'relay',
+ *   relay: connection.relay,
+ *   // the relay node's signing key, learned out of band — without it the
+ *   // client writes but does not observe
+ *   observe: { nodeKey },
+ * });
+ *
+ * await client.rpc.execute({ contextId, method: 'set', argsJson: { key, value } });
+ * if (client.canSubscribe) client.events.on('event', onEvent);
+ * ```
+ */
+export function createMeroClient(config) {
+    return new MeroClient(config);
+}

package/dist/transport/relay-observer.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Reading from the relay — because a relay is a node.
+ *
+ * # What was wrong with "a relay-transport client cannot observe"
+ *
+ * The first version of this transport reported `canSubscribe === false` for
+ * every relay, on the reasoning that a relay serves only `GET`/`POST
+ * /admin-api/contexts/:id/intents`. That is true of the *unauthenticated*
+ * surface, and it is the wrong conclusion: a relay is an ordinary node that
+ * happens to also run intents for other people. The same origin serves
+ * `/auth/challenge`, `/auth/token`, `/sse` and `/ws`, and a keyholder holding
+ * an `AccountProof<DeviceCert>` can log in to it with {@link login} — the
+ * `account_proof` provider grants exactly `context:intent`, `context:query`,
+ * `context:subscribe`. Subscribe is in the provider's own default grant, not
+ * something extra that has to be asked for, and a delegated write on such a
+ * session was observed arriving as a `StateMutation` frame whose `newRoot`
+ * matched the write's `rootHash`.
+ *
+ * So the gap was never "a relay cannot be observed". It is exactly one missing
+ * input.
+ *
+ * # The one missing input, and why it is not filled in from somewhere
+ *
+ * {@link login} requires the node's device signing key as a *separately
+ * supplied* parameter. It is not read out of the challenge response on purpose:
+ * a value learned from the party you are about to authenticate to lets whoever
+ * answered choose what your device signs a statement about. That is the whole
+ * attack the parameter exists to stop.
+ *
+ * For a self-hosted relay the operator can hand the key over out of band, and
+ * this module works today. For a cloud-hosted relay, `CloudRelay` carries
+ * `peerId`, `relayUrl`, `executorAccount`, `status` and `authorshipReady` —
+ * and no node key. `peerId` is a libp2p identity and is **not** a substitute:
+ * signing a statement about a libp2p peer id would be signing about a different
+ * key than the one the node authenticates with. That is filed upstream as mdma
+ * #312; until it lands, the hosted case has no key and reports
+ * `canSubscribe === false` rather than pretending.
+ *
+ * Nothing here invents a key, and nothing here falls back to "some other node".
+ */
+import { SseClient } from '../events/sse.js';
+import { WsClient } from '../events/ws.js';
+import { type Audience } from '../login/index.js';
+import type { Signer } from '../signer/signer.js';
+/**
+ * How a relay-transport client observes the relay node.
+ *
+ * Every field but {@link RelayObserveConfig.nodeKey} has a correct default
+ * taken from the `RelayClient` already configured — the author's proof, its
+ * signer and the relay's own URL are the same values a login needs, and asking
+ * for a second copy is how two copies come to disagree.
+ */
+export interface RelayObserveConfig {
+    /**
+     * The relay node's ed25519 device signing key, hex (32 bytes), **as this
+     * client pinned it**.
+     *
+     * Learn it out of band: from the operator of a self-hosted relay, or from a
+     * certificate you already trust. Never from the node itself — see the module
+     * note.
+     *
+     * `null` / `undefined` is a first-class answer meaning "nobody told me", and
+     * it is what the hosted path passes today (mdma #312). It makes
+     * `canSubscribe` false; it never makes the client guess.
+     */
+    nodeKey?: string | null;
+    /**
+     * The client surface the session is bound to.
+     *
+     * Defaults to this runtime's honest self-description: the browser's own
+     * `location.origin`, or `{ kind: 'cli' }` where there is no browser. Passing
+     * something else is for a client that knows better — a signed native app
+     * naming its code-signing identity, say. A wrong audience fails the login
+     * loudly rather than quietly widening anything.
+     */
+    audience?: Audience;
+    /** The node to log in to. Defaults to the relay's own URL — they are the same node. */
+    nodeUrl?: string;
+    /** The author's `AccountProof<DeviceCert>`, hex. Defaults to the relay client's. */
+    accountProof?: string;
+    /** The device signer. Defaults to the relay client's — the same device authors and observes. */
+    signer?: Signer;
+    /** How this client names itself to the node. Defaults to the audience's own spelling. */
+    clientName?: string;
+    /** Seconds the login statement stays valid. Defaults to `login`'s own default. */
+    ttlSeconds?: number;
+    /** Injected for tests and non-browser runtimes. */
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/** What {@link RelayObserver} needs once the defaults have been resolved. */
+export interface ResolvedObserveConfig {
+    nodeUrl: string;
+    nodeKey: string;
+    accountProof: string;
+    audience: Audience;
+    signer: () => Promise<Signer>;
+    clientName?: string;
+    ttlSeconds?: number;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * This runtime's honest self-description, used when no audience is given.
+ *
+ * The origin is taken verbatim from the browser rather than normalized: the
+ * node compares it byte for byte, and two spellings of one origin would mean a
+ * client that disagrees with itself about which surface a token was for.
+ */
+export declare function defaultAudience(): Audience;
+/**
+ * A node session over the relay, and the event clients it feeds.
+ *
+ * The session is minted lazily, on the first thing that actually needs a token.
+ * That is not an optimization: `client.events` is a *getter*, so constructing a
+ * client would otherwise have to perform two HTTP calls and a signature before
+ * anyone had asked to observe anything.
+ */
+export declare class RelayObserver {
+    private readonly config;
+    private session;
+    private sessionExpiresAt;
+    /** In-flight login, so two surfaces asking at once mint one session, not two. */
+    private pending;
+    private sseClient;
+    private wsClient;
+    constructor(config: ResolvedObserveConfig);
+    /** The node key this observer logs in with. Read for diagnostics. */
+    get nodeKey(): string;
+    /**
+     * A usable access token, logging in if there is not one.
+     *
+     * Re-mints once the current token is within {@link EXPIRY_SKEW_MS} of
+     * expiring, and on every call when the token's lifetime cannot be read —
+     * reconnects are backed off, so an extra handshake costs far less than a
+     * stream that silently stops. The refresh token is *held* but not spent:
+     * rotating it is tracked in #87/#88 and a second login is correct in the
+     * meantime, where re-presenting an unrotated refresh token would not be.
+     */
+    accessToken(): Promise<string>;
+    private loginNow;
+    /**
+     * SSE events over the relay node — the same `SseClient` a node client hands
+     * out, constructed the same way, so nothing downstream can tell which
+     * transport produced it.
+     */
+    get events(): SseClient;
+    /** WebSocket events over the relay node. @experimental — prefer `events`. */
+    get ws(): WsClient;
+    /** Close whatever was opened. Never touches the relay's write path. */
+    close(): void;
+}