@calimero-network/mero-js 22.7.0 → 22.9.0

package/dist/transport/relay-observer.js

@@ -0,0 +1,173 @@
+/**
+ * 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 { login } from '../login/index.js';
+/** Re-login this long before the access token expires, so a reconnect is not racing it. */
+const EXPIRY_SKEW_MS = 30000;
+/**
+ * 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 function defaultAudience() {
+    const origin = globalThis.location?.origin;
+    return origin ? { kind: 'webOrigin', origin } : { kind: 'cli' };
+}
+/**
+ * Milliseconds-since-epoch at which a JWT expires, or `null` if unreadable.
+ *
+ * Deliberately `null` rather than a fallback guess. `mero-js.ts` has a similar
+ * helper that substitutes "an hour from now" when it cannot read `exp`, which
+ * is right for a token bundle that will be refreshed reactively on a 401 and
+ * wrong here: an unreadable lifetime must mean "mint a fresh session", not
+ * "assume an hour and let a dead token take the stream down".
+ */
+function jwtExpiryMs(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        let b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        while (b64.length % 4)
+            b64 += '=';
+        const payload = JSON.parse(atob(b64));
+        return typeof payload.exp === 'number' ? payload.exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 class RelayObserver {
+    constructor(config) {
+        this.session = null;
+        this.sessionExpiresAt = null;
+        /** In-flight login, so two surfaces asking at once mint one session, not two. */
+        this.pending = null;
+        this.sseClient = null;
+        this.wsClient = null;
+        this.config = config;
+    }
+    /** The node key this observer logs in with. Read for diagnostics. */
+    get nodeKey() {
+        return this.config.nodeKey;
+    }
+    /**
+     * 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.
+     */
+    async accessToken() {
+        const now = Date.now();
+        if (this.session &&
+            this.sessionExpiresAt !== null &&
+            this.sessionExpiresAt - EXPIRY_SKEW_MS > now) {
+            return this.session.accessToken;
+        }
+        if (!this.pending) {
+            this.pending = this.loginNow().finally(() => {
+                this.pending = null;
+            });
+        }
+        const session = await this.pending;
+        return session.accessToken;
+    }
+    async loginNow() {
+        const session = await login({
+            nodeUrl: this.config.nodeUrl,
+            node: this.config.nodeKey,
+            signer: await this.config.signer(),
+            accountProof: this.config.accountProof,
+            audience: this.config.audience,
+            clientName: this.config.clientName,
+            ttlSeconds: this.config.ttlSeconds,
+            fetch: this.config.fetch,
+            timeoutMs: this.config.timeoutMs,
+        });
+        this.session = session;
+        this.sessionExpiresAt = jwtExpiryMs(session.accessToken);
+        return session;
+    }
+    /**
+     * 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() {
+        if (!this.sseClient) {
+            this.sseClient = new SseClient({
+                baseUrl: this.config.nodeUrl,
+                getAuthToken: () => this.accessToken(),
+            });
+        }
+        return this.sseClient;
+    }
+    /** WebSocket events over the relay node. @experimental — prefer `events`. */
+    get ws() {
+        if (!this.wsClient) {
+            this.wsClient = new WsClient({
+                baseUrl: this.config.nodeUrl,
+                getAuthToken: () => this.accessToken(),
+            });
+        }
+        return this.wsClient;
+    }
+    /** Close whatever was opened. Never touches the relay's write path. */
+    close() {
+        this.sseClient?.close();
+        this.wsClient?.close();
+    }
+}

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

@@ -0,0 +1,73 @@
+/**
+ * The relay, wearing the node's `execute` shape.
+ *
+ * This is an adapter and nothing else: it owns no protocol, mints no warrant
+ * and holds no key. `RelayClient` does all of that and stays the place to look
+ * when a write is refused. What lives here is the two differences that stopped
+ * an app from swapping one for the other — named arguments instead of
+ * positional, and `T` instead of `IntentResult<T>`.
+ *
+ * The unwrap is the load-bearing part: `IntentResult<T>` becomes `T`, so a call
+ * site cannot tell which transport ran it.
+ *
+ * A method's `null` return is passed through as `null` rather than normalized
+ * to `undefined`. That looks like the less tidy choice and is the correct one:
+ * `RpcClient.execute` returns `result.output` verbatim, so a node method whose
+ * output is `null` already resolves to `null` today. Rewriting the relay's
+ * `null` would make the two transports disagree in exactly the case this
+ * adapter exists to make agree. The alternative — normalizing *both* sides to
+ * `undefined` — was rejected because it changes what shipped node call sites
+ * see, which is the one thing this work must not do.
+ *
+ * The `rootHash` the relay also reports is NOT discarded — it comes back from
+ * {@link RelayTransport.executeWithMetadata}.
+ */
+import type { ExecuteParams, MigrateMyEntriesSummary } from '../rpc/index.js';
+import type { RelayClient } from '../relay/relay-client.js';
+import type { ExecuteResult, ExecuteTransport, TransportKind } from './types.js';
+import type { RelayObserver } from './relay-observer.js';
+export declare class RelayTransport implements ExecuteTransport {
+    private readonly relay;
+    /**
+     * How this transport observes, or `null` when nobody supplied the relay
+     * node's signing key. Held here rather than on `MeroClient` so that
+     * {@link RelayTransport.canSubscribe} — which an app may read off
+     * `client.rpc` — answers about the thing it is actually asked about.
+     */
+    private readonly observer;
+    readonly kind: TransportKind;
+    constructor(relay: RelayClient, 
+    /**
+     * How this transport observes, or `null` when nobody supplied the relay
+     * node's signing key. Held here rather than on `MeroClient` so that
+     * {@link RelayTransport.canSubscribe} — which an app may read off
+     * `client.rpc` — answers about the thing it is actually asked about.
+     */
+    observer?: RelayObserver | null);
+    /**
+     * Whether this relay can be observed — a fact, not a constant.
+     *
+     * A relay IS a node: it serves `/auth/challenge`, `/auth/token`, `/sse` and
+     * `/ws`, and the `account_proof` provider grants `context:subscribe` by
+     * default. What decides the answer is therefore not the transport but whether
+     * a caller supplied the node's device signing key, which cannot be inferred
+     * from the node or from its `peerId`. See `./relay-observer.ts`.
+     */
+    get canSubscribe(): boolean;
+    /** The event session, or `null` when no node key was supplied. */
+    get events(): RelayObserver | null;
+    /** The underlying client, for `describe()` and anything else relay-specific. */
+    get client(): RelayClient;
+    execute<T = unknown>(params: ExecuteParams): Promise<T>;
+    executeWithMetadata<T = unknown>(params: ExecuteParams): Promise<ExecuteResult<T>>;
+    /**
+     * Both of these are plain context methods, so they work through a relay
+     * exactly as they do on a node — the warrant names `migrate_my_entries` and
+     * the delta is attributed to the author, which is precisely the identity the
+     * convert is scoped to. They are re-declared rather than inherited because
+     * `ExecuteTransport` is an interface, not a base class.
+     */
+    migrateMyEntries(contextId: string): Promise<MigrateMyEntriesSummary>;
+    /** Read-only count of the caller's entries still below the target schema. */
+    countMyPending(contextId: string): Promise<number>;
+}

package/dist/transport/relay-transport.js

@@ -0,0 +1,94 @@
+/**
+ * The relay, wearing the node's `execute` shape.
+ *
+ * This is an adapter and nothing else: it owns no protocol, mints no warrant
+ * and holds no key. `RelayClient` does all of that and stays the place to look
+ * when a write is refused. What lives here is the two differences that stopped
+ * an app from swapping one for the other — named arguments instead of
+ * positional, and `T` instead of `IntentResult<T>`.
+ *
+ * The unwrap is the load-bearing part: `IntentResult<T>` becomes `T`, so a call
+ * site cannot tell which transport ran it.
+ *
+ * A method's `null` return is passed through as `null` rather than normalized
+ * to `undefined`. That looks like the less tidy choice and is the correct one:
+ * `RpcClient.execute` returns `result.output` verbatim, so a node method whose
+ * output is `null` already resolves to `null` today. Rewriting the relay's
+ * `null` would make the two transports disagree in exactly the case this
+ * adapter exists to make agree. The alternative — normalizing *both* sides to
+ * `undefined` — was rejected because it changes what shipped node call sites
+ * see, which is the one thing this work must not do.
+ *
+ * The `rootHash` the relay also reports is NOT discarded — it comes back from
+ * {@link RelayTransport.executeWithMetadata}.
+ */
+export class RelayTransport {
+    constructor(relay, 
+    /**
+     * How this transport observes, or `null` when nobody supplied the relay
+     * node's signing key. Held here rather than on `MeroClient` so that
+     * {@link RelayTransport.canSubscribe} — which an app may read off
+     * `client.rpc` — answers about the thing it is actually asked about.
+     */
+    observer = null) {
+        this.relay = relay;
+        this.observer = observer;
+        this.kind = 'relay';
+    }
+    /**
+     * Whether this relay can be observed — a fact, not a constant.
+     *
+     * A relay IS a node: it serves `/auth/challenge`, `/auth/token`, `/sse` and
+     * `/ws`, and the `account_proof` provider grants `context:subscribe` by
+     * default. What decides the answer is therefore not the transport but whether
+     * a caller supplied the node's device signing key, which cannot be inferred
+     * from the node or from its `peerId`. See `./relay-observer.ts`.
+     */
+    get canSubscribe() {
+        return this.observer !== null;
+    }
+    /** The event session, or `null` when no node key was supplied. */
+    get events() {
+        return this.observer;
+    }
+    /** The underlying client, for `describe()` and anything else relay-specific. */
+    get client() {
+        return this.relay;
+    }
+    async execute(params) {
+        const { returns } = await this.executeWithMetadata(params);
+        return returns;
+    }
+    async executeWithMetadata(params) {
+        const result = await this.relay.execute(params.contextId, params.method, 
+        // The node defaults a missing `argsJson` to `{}`; matching that here keeps
+        // a zero-argument call identical on both transports rather than sending
+        // `undefined` and letting the relay's JSON body decide.
+        params.argsJson ?? {});
+        return {
+            // Verbatim. `RelayClient` has already normalized a missing `returns` to
+            // `null`, which is what a node reports for a null output — see the
+            // module note on why this is not rewritten to `undefined`.
+            returns: result.returns,
+            transport: 'relay',
+            rootHash: result.rootHash,
+        };
+    }
+    /**
+     * Both of these are plain context methods, so they work through a relay
+     * exactly as they do on a node — the warrant names `migrate_my_entries` and
+     * the delta is attributed to the author, which is precisely the identity the
+     * convert is scoped to. They are re-declared rather than inherited because
+     * `ExecuteTransport` is an interface, not a base class.
+     */
+    async migrateMyEntries(contextId) {
+        return this.execute({
+            contextId,
+            method: 'migrate_my_entries',
+        });
+    }
+    /** Read-only count of the caller's entries still below the target schema. */
+    async countMyPending(contextId) {
+        return this.execute({ contextId, method: 'count_my_pending' });
+    }
+}

package/dist/transport/types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * One call shape, two ways of getting there.
+ *
+ * # Why the node shape is the canonical one
+ *
+ * `RpcClient.execute({ contextId, method, argsJson })` is what every app in the
+ * fleet already writes, and `RelayClient.execute(contextId, method, argsJson)`
+ * is what the delegated path grew independently. They differ in *both* halves —
+ * positional vs. named arguments, and `T` vs. `IntentResult<T>`. A caller that
+ * wanted to switch transports therefore had to rewrite every call site, which
+ * makes the transport a property of the application rather than of the
+ * connection.
+ *
+ * This interface closes that by declaring the node's shape the contract and
+ * adapting the relay to it. The direction is deliberate and not symmetric:
+ * shipped code uses the node shape, so any other choice would be a breaking
+ * change dressed up as an abstraction.
+ *
+ * # Why subscription is not a method on this interface
+ *
+ * Not because a relay cannot be observed — it can; a relay is an ordinary node
+ * and a keyholder can log in to it (see `./relay-observer.ts`). It is because
+ * `RpcClient` satisfies this interface *as it already ships*, and `RpcClient`
+ * has never had a `subscribe`. Adding one would change the canonical shape,
+ * which is the single thing this work must not do.
+ *
+ * Observation therefore lives on `MeroClient` — `client.events`, `client.ws` —
+ * where it lives for a node client, and is the same call on both transports.
+ * {@link ExecuteTransport.canSubscribe} reports whether it will work, so an app
+ * can branch on data rather than on a thrown error.
+ */
+import type { ExecuteParams, MigrateMyEntriesSummary } from '../rpc/index.js';
+/** Which path a write takes. `'node'` is the default everywhere. */
+export type TransportKind = 'node' | 'relay';
+/**
+ * A method's return value plus whatever the transport knew about the write.
+ *
+ * The canonical `execute` returns `T` and nothing else, because that is what
+ * every existing call site expects. The relay, though, also learns the
+ * context's scope root after the run — the one cheap way to tell "this changed
+ * something" from "this was a no-op" — and discarding it to fit the node shape
+ * would lose information the node genuinely does not have.
+ *
+ * So it is carried here, on a second method, rather than on a mutable
+ * `lastIntent` accessor. That alternative was rejected on purpose: two
+ * `execute` calls in flight at once would race for the same slot, and the
+ * caller reading it has no way to tell whose answer it got.
+ */
+export interface ExecuteResult<T = unknown> {
+    /** Exactly what `execute` would have returned. */
+    returns: T;
+    /** Which transport ran it. */
+    transport: TransportKind;
+    /**
+     * The context's scope root after the run, hex — relay only.
+     *
+     * Absent on the node transport because JSON-RPC `execute` does not report it,
+     * not because it was dropped. `undefined` therefore means "unknown here", and
+     * must never be read as "nothing changed".
+     */
+    rootHash?: string;
+}
+/**
+ * The write surface an app codes against, whichever transport is underneath.
+ *
+ * `RpcClient` satisfies this as-is — that is the point of picking its shape —
+ * so an app already holding one is already holding an `ExecuteTransport`.
+ */
+export interface ExecuteTransport {
+    /** Which path this is. Useful for diagnostics and for feature-gating UI. */
+    readonly kind: TransportKind;
+    /**
+     * Whether this transport can observe events **as configured**.
+     *
+     * Always `true` on the node transport, which holds a credential on the node
+     * it is pointed at. On the relay transport it depends on whether the caller
+     * supplied the relay node's device signing key: the relay serves `/sse` and
+     * `/ws` like any node, but a login statement must be signed against a key
+     * learned out of band, and that key cannot be read from the node or derived
+     * from its `peerId`.
+     *
+     * Reported rather than attempted, so an app branches before it subscribes.
+     * `false` never means "try anyway and we'll connect to something else" —
+     * nothing here will silently pick a node the app did not choose.
+     */
+    readonly canSubscribe: boolean;
+    /** Run one method in one context. The canonical signature. */
+    execute<T = unknown>(params: ExecuteParams): Promise<T>;
+    /**
+     * The same call, with whatever the transport knows about the write.
+     *
+     * Use it when the extra metadata matters; `execute` stays the one an app
+     * reaches for, so that switching transports changes no call site.
+     */
+    executeWithMetadata<T = unknown>(params: ExecuteParams): Promise<ExecuteResult<T>>;
+    /** One-tap owner-driven convert. See `RpcClient.migrateMyEntries`. */
+    migrateMyEntries(contextId: string): Promise<MigrateMyEntriesSummary>;
+    /** Read-only count of the caller's entries still below the target schema. */
+    countMyPending(contextId: string): Promise<number>;
+}

package/dist/transport/types.js

@@ -0,0 +1,32 @@
+/**
+ * One call shape, two ways of getting there.
+ *
+ * # Why the node shape is the canonical one
+ *
+ * `RpcClient.execute({ contextId, method, argsJson })` is what every app in the
+ * fleet already writes, and `RelayClient.execute(contextId, method, argsJson)`
+ * is what the delegated path grew independently. They differ in *both* halves —
+ * positional vs. named arguments, and `T` vs. `IntentResult<T>`. A caller that
+ * wanted to switch transports therefore had to rewrite every call site, which
+ * makes the transport a property of the application rather than of the
+ * connection.
+ *
+ * This interface closes that by declaring the node's shape the contract and
+ * adapting the relay to it. The direction is deliberate and not symmetric:
+ * shipped code uses the node shape, so any other choice would be a breaking
+ * change dressed up as an abstraction.
+ *
+ * # Why subscription is not a method on this interface
+ *
+ * Not because a relay cannot be observed — it can; a relay is an ordinary node
+ * and a keyholder can log in to it (see `./relay-observer.ts`). It is because
+ * `RpcClient` satisfies this interface *as it already ships*, and `RpcClient`
+ * has never had a `subscribe`. Adding one would change the canonical shape,
+ * which is the single thing this work must not do.
+ *
+ * Observation therefore lives on `MeroClient` — `client.events`, `client.ws` —
+ * where it lives for a node client, and is the same call on both transports.
+ * {@link ExecuteTransport.canSubscribe} reports whether it will work, so an app
+ * can branch on data rather than on a thrown error.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calimero-network/mero-js",
-  "version": "22.7.0",
+  "version": "22.9.0",
   "description": "Pure JavaScript SDK for Calimero",
   "type": "module",
   "exports": {