@calimero-network/mero-js 23.2.0 → 23.3.0

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

@@ -0,0 +1,56 @@
+/**
+ * An account's ephemeral presence, through its relay.
+ *
+ * A node publishes and heartbeats its own presence; an account has no node, so
+ * this client signs each update with the device key, posts it to the relay's
+ * `presence-intents`, and resends the last state every 2.5 s until
+ * `set(contextId, null)` or `close()`. The relay checks the update and seals
+ * and gossips it; other members verify the device's signature and certificate
+ * themselves, so the relay cannot invent or alter an account's presence.
+ */
+import type { SseClient } from '../events/index.js';
+import type { Codec, EphemeralEntry } from '../ephemeral/types.js';
+import type { RelayClient } from '../relay/relay-client.js';
+type PresenceRelay = Pick<RelayClient, 'authorProof' | 'authorSigner' | 'presenceIntent'>;
+export declare class RelayPresenceClient {
+    private readonly relay;
+    private readonly events;
+    private readonly heartbeatMs;
+    private readonly now;
+    private readonly timers;
+    private readonly lastSeq;
+    private readonly refused;
+    /**
+     * Bumped by every `set` and `close`, per context. A `set` installs its
+     * resends only if nothing newer happened while its first send was in flight,
+     * so a retract (or a newer state) can never be overtaken by an older one.
+     */
+    private readonly generation;
+    /**
+     * @param opts.events the relay's event stream, asked for only on `subscribe`:
+     *   publishing needs none, so a client with no node key can still publish.
+     */
+    constructor(opts: {
+        relay: PresenceRelay;
+        events: () => SseClient;
+        heartbeatMs?: number;
+        now?: () => number;
+    });
+    /**
+     * Set this account's presence in `contextId`, or retract it with `null`.
+     * Throws when the relay refuses this first send for good (a 4xx other than
+     * 429), which also stops the resends. A rate limit, a network failure or a
+     * 5xx is not thrown: the next resend covers it.
+     */
+    set<T>(contextId: string, state: T | null, codec?: Codec<T>): Promise<void>;
+    subscribe<T>(contextId: string, handler: (entry: EphemeralEntry<T>) => void, codec?: Codec<T>): () => void;
+    /** Stop every resend. Entries expire on the relay and its peers within 7 s. */
+    close(): void;
+    /** Stop the context's resends and invalidate any `set` still in flight. */
+    private bump;
+    private stop;
+    /** Wall-clock seeded and strictly rising, so a relay restart never sees an old seq. */
+    private nextSeq;
+    private send;
+}
+export {};

package/dist/presence/relay-presence.js

@@ -0,0 +1,107 @@
+import { hex } from '../crypto/internal.js';
+import { jsonCodec, subscribePresence } from '../ephemeral/index.js';
+import { presenceStatementBytes } from './statement.js';
+/** The node's own heartbeat interval, so a relayed entry never outlives the 7 s TTL. */
+const HEARTBEAT_MS = 2500;
+export class RelayPresenceClient {
+    /**
+     * @param opts.events the relay's event stream, asked for only on `subscribe`:
+     *   publishing needs none, so a client with no node key can still publish.
+     */
+    constructor(opts) {
+        this.timers = new Map();
+        this.lastSeq = new Map();
+        this.refused = new Set();
+        /**
+         * Bumped by every `set` and `close`, per context. A `set` installs its
+         * resends only if nothing newer happened while its first send was in flight,
+         * so a retract (or a newer state) can never be overtaken by an older one.
+         */
+        this.generation = new Map();
+        this.relay = opts.relay;
+        this.events = opts.events;
+        this.heartbeatMs = opts.heartbeatMs ?? HEARTBEAT_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * Set this account's presence in `contextId`, or retract it with `null`.
+     * Throws when the relay refuses this first send for good (a 4xx other than
+     * 429), which also stops the resends. A rate limit, a network failure or a
+     * 5xx is not thrown: the next resend covers it.
+     */
+    async set(contextId, state, codec = jsonCodec()) {
+        const generation = this.bump(contextId);
+        this.refused.delete(contextId);
+        const bytes = state === null ? null : new Uint8Array(codec.encode(state));
+        await this.send(contextId, bytes);
+        if (bytes === null || this.refused.has(contextId))
+            return;
+        if (this.generation.get(contextId) !== generation)
+            return; // a newer set or close won
+        this.timers.set(contextId, setInterval(() => void this.send(contextId, bytes).catch(() => undefined), this.heartbeatMs));
+    }
+    subscribe(contextId, handler, codec = jsonCodec()) {
+        return subscribePresence(this.events(), contextId, handler, codec);
+    }
+    /** Stop every resend. Entries expire on the relay and its peers within 7 s. */
+    close() {
+        for (const contextId of new Set([...this.timers.keys(), ...this.generation.keys()])) {
+            this.bump(contextId);
+        }
+    }
+    /** Stop the context's resends and invalidate any `set` still in flight. */
+    bump(contextId) {
+        this.stop(contextId);
+        const next = (this.generation.get(contextId) ?? 0) + 1;
+        this.generation.set(contextId, next);
+        return next;
+    }
+    stop(contextId) {
+        const timer = this.timers.get(contextId);
+        if (timer !== undefined)
+            clearInterval(timer);
+        this.timers.delete(contextId);
+    }
+    /** Wall-clock seeded and strictly rising, so a relay restart never sees an old seq. */
+    nextSeq(contextId) {
+        const seq = Math.max(this.now(), (this.lastSeq.get(contextId) ?? 0) + 1);
+        this.lastSeq.set(contextId, seq);
+        return seq;
+    }
+    async send(contextId, state) {
+        if (this.refused.has(contextId))
+            return;
+        const signer = await this.relay.authorSigner();
+        const seq = this.nextSeq(contextId);
+        const sentAtMs = this.now();
+        const statement = await presenceStatementBytes({
+            contextId,
+            author: signer.publicKey,
+            seq: BigInt(seq),
+            sentAtMs: BigInt(sentAtMs),
+            state,
+        });
+        const signature = hex(await signer.sign(statement));
+        try {
+            await this.relay.presenceIntent(contextId, {
+                state: state === null ? null : hex(state),
+                seq,
+                sentAtMs,
+                signature,
+                authorProof: this.relay.authorProof,
+            });
+        }
+        catch (err) {
+            const status = err.status;
+            // Rate limited, a network failure, or the relay unable right now (5xx,
+            // e.g. no current key mid-rotation): the next resend covers it.
+            if (status === undefined || status === 0 || status === 429 || status >= 500)
+                return;
+            // Any other refusal (403: not a member or revoked; 400: malformed or a
+            // clock outside the relay's window) cannot be fixed by resending.
+            this.refused.add(contextId);
+            this.stop(contextId);
+            throw err;
+        }
+    }
+}

package/dist/presence/statement.d.ts

@@ -0,0 +1,12 @@
+/** core's `PRESENCE_DOMAIN`: part of the signed bytes. */
+export declare const PRESENCE_DOMAIN: Uint8Array;
+/** `sha256(borsh(Option<Vec<u8>>))`: `None` is `[0]`, `Some(v)` is `[1] ‖ u32le(len) ‖ v`. */
+export declare function stateHash(state: Uint8Array | null): Promise<Uint8Array>;
+/** What the device key signs, raw: domain ‖ context ‖ author ‖ seq ‖ sentAtMs ‖ stateHash. */
+export declare function presenceStatementBytes(input: {
+    contextId: string;
+    author: string;
+    seq: bigint;
+    sentAtMs: bigint;
+    state: Uint8Array | null;
+}): Promise<Uint8Array>;

package/dist/presence/statement.js

@@ -0,0 +1,17 @@
+/**
+ * The bytes a device signs for one presence update: the borsh of core's
+ * `PresenceStatement` (`calimero_node_primitives::presence`). Pinned to core's
+ * vector in `statement.test.ts`, so the two encoders cannot drift.
+ */
+import { concat, fromHex, u32le, u64le } from '../crypto/internal.js';
+/** core's `PRESENCE_DOMAIN`: part of the signed bytes. */
+export const PRESENCE_DOMAIN = new TextEncoder().encode('calimero/presence/1');
+/** `sha256(borsh(Option<Vec<u8>>))`: `None` is `[0]`, `Some(v)` is `[1] ‖ u32le(len) ‖ v`. */
+export async function stateHash(state) {
+    const borsh = state === null ? new Uint8Array([0]) : concat(new Uint8Array([1]), u32le(state.length), state);
+    return new Uint8Array(await crypto.subtle.digest('SHA-256', borsh));
+}
+/** What the device key signs, raw: domain ‖ context ‖ author ‖ seq ‖ sentAtMs ‖ stateHash. */
+export async function presenceStatementBytes(input) {
+    return concat(PRESENCE_DOMAIN, fromHex(input.contextId, 'contextId', 32), fromHex(input.author, 'author', 32), u64le(input.seq), u64le(input.sentAtMs), await stateHash(input.state));
+}

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

@@ -324,6 +324,19 @@ export declare class RelayClient {
      * apply. Nothing accumulates and nothing is reusable.
      */
     execute<T = unknown>(contextId: string, method: string, argsJson?: unknown): Promise<IntentResult<T>>;
+    /**
+     * Publish one presence statement through the relay (`presence-intents`).
+     *
+     * Not retried on 429: presence resends every 2.5 s anyway, and a retry would
+     * only queue behind the next resend. A refusal throws with its `status`.
+     */
+    presenceIntent(contextId: string, body: {
+        state: string | null;
+        seq: number;
+        sentAtMs: number;
+        signature: string;
+        authorProof: string;
+    }): Promise<void>;
     /**
      * Ask the relay what it can do about creating contexts in `groupId`.
      *

package/dist/relay/relay-client.js

@@ -169,6 +169,15 @@ export class RelayClient {
         const body = await this.json('POST', `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`, { method, argsJson, warrant, authorProof: this.config.authorProof });
         return { rootHash: body.data.rootHash, returns: body.data.returns ?? null };
     }
+    /**
+     * Publish one presence statement through the relay (`presence-intents`).
+     *
+     * Not retried on 429: presence resends every 2.5 s anyway, and a retry would
+     * only queue behind the next resend. A refusal throws with its `status`.
+     */
+    async presenceIntent(contextId, body) {
+        await this.jsonOnce('POST', `/admin-api/contexts/${encodeURIComponent(contextId)}/presence-intents`, body);
+    }
     /**
      * Ask the relay what it can do about creating contexts in `groupId`.
      *
@@ -466,6 +475,9 @@ export class RelayClient {
             }
             throw new HTTPError(response.status, response.statusText, `${this.baseUrl}${path}`, response.headers, text);
         }
+        // `presence-intents` answers an accepted update with no body.
+        if (response.status === 204)
+            return undefined;
         return (await response.json());
     }
 }

package/dist/transport/mero-client.d.ts

@@ -59,6 +59,7 @@ import { SseClient } from '../events/sse.js';
 import type { AuthApiClient } from '../auth-api/index.js';
 import type { WsClient } from '../events/ws.js';
 import type { EphemeralClient } from '../ephemeral/index.js';
+import { RelayPresenceClient } from '../presence/relay-presence.js';
 import type { CloudClient } from '../cloud/cloud-client.js';
 /** The node transport: everything `createMeroJs` takes, plus an explicit opt-in. */
 export interface NodeTransportConfig extends MeroJsConfig {
@@ -155,6 +156,7 @@ export declare class MeroClient {
     private readonly proofAuthorizer;
     private readonly relayUrl;
     private proofEvents;
+    private relayPresence;
     constructor(config: MeroClientConfig);
     /**
      * The write surface. Identical on both transports — this is the whole point.
@@ -234,19 +236,16 @@ export declare class MeroClient {
     /**
      * 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.
+     * On a relay client this is an account's presence client
+     * ({@link RelayPresenceClient}): `set` signs each update with the device key
+     * and posts it to the relay's `presence-intents`, resending every 2.5 s, and
+     * `subscribe` reads the relay's event stream. The relay checks and forwards
+     * the update; other members verify the device's signature and certificate
+     * themselves, so it can drop or delay an account's presence but not invent or
+     * alter it. Only `subscribe` needs the relay's node key (for the event
+     * stream), so publishing works on any relay client.
      */
-    get ephemeral(): EphemeralClient;
+    get ephemeral(): EphemeralClient | RelayPresenceClient;
     /**
      * Calimero Cloud.
      *

package/dist/transport/mero-client.js

@@ -55,6 +55,7 @@ import { createAdminApiClient, createAdminApiClientFromHttpClient } from '../adm
 import { createHttpClient } from '../http-client/index.js';
 import { createProofAuthorizer } from '../request-proof/index.js';
 import { SseClient } from '../events/sse.js';
+import { RelayPresenceClient } from '../presence/relay-presence.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}. ` +
@@ -127,6 +128,7 @@ export class MeroClient {
         this.proofAuthorizer = null;
         this.relayUrl = null;
         this.proofEvents = null;
+        this.relayPresence = null;
         if (config.transport === 'relay') {
             this.transport = 'relay';
             this.nodeClient = null;
@@ -308,23 +310,20 @@ export class MeroClient {
     /**
      * 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.
+     * On a relay client this is an account's presence client
+     * ({@link RelayPresenceClient}): `set` signs each update with the device key
+     * and posts it to the relay's `presence-intents`, resending every 2.5 s, and
+     * `subscribe` reads the relay's event stream. The relay checks and forwards
+     * the update; other members verify the device's signature and certificate
+     * themselves, so it can drop or delay an account's presence but not invent or
+     * alter it. Only `subscribe` needs the relay's node key (for the event
+     * stream), so publishing works on any relay client.
      */
     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;
+        if (this.nodeClient)
+            return this.nodeClient.ephemeral;
+        this.relayPresence ?? (this.relayPresence = new RelayPresenceClient({ relay: this.relay, events: () => this.events }));
+        return this.relayPresence;
     }
     /**
      * Calimero Cloud.

package/package.json

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