@calimero-network/mero-js 23.2.0 → 23.3.0

package/dist/index.d.ts

@@ -15,7 +15,9 @@ export { MeroClient, createMeroClient, RelayTransport, RelayObserver, defaultAud
 export type { MeroClientConfig, NodeTransportConfig, RelayTransportConfig, RelayObserveConfig, ExecuteTransport, ExecuteResult, TransportKind, } from './transport/index.js';
 export { SseClient, WsClient } from "./events/index.js";
 export type { SseEventData, WsEventData, AppVersionChangedEvent, GroupMembershipEventData, GroupMigrationEventData, MigrationStartedData, MigrationProgressData, CascadeProgressData, MigrationCompletedData, } from "./events/index.js";
-export { EphemeralClient, jsonCodec } from "./ephemeral/index.js";
+export { EphemeralClient, jsonCodec, subscribePresence } from "./ephemeral/index.js";
+export { RelayPresenceClient } from "./presence/relay-presence.js";
+export { presenceStatementBytes, stateHash, PRESENCE_DOMAIN } from "./presence/statement.js";
 export type { Codec, EphemeralEntry } from "./ephemeral/index.js";
 export * from "./cloud/index.js";
 export * from "./sealed/index.js";

package/dist/index.js

@@ -24,7 +24,9 @@ RelayObserver, defaultAudience, } from './transport/index.js';
 // Events (SSE / WebSocket)
 export { SseClient, WsClient } from "./events/index.js";
 // Ephemeral presence (cursors / typing / online)
-export { EphemeralClient, jsonCodec } from "./ephemeral/index.js";
+export { EphemeralClient, jsonCodec, subscribePresence } from "./ephemeral/index.js";
+export { RelayPresenceClient } from "./presence/relay-presence.js";
+export { presenceStatementBytes, stateHash, PRESENCE_DOMAIN } from "./presence/statement.js";
 // Cloud client — namespaces, relays, HA, and the cloud sign-in path
 export * from "./cloud/index.js";
 // Sealed transport — requests encrypted to a TEE node's attested key

package/dist/index.mjs

@@ -3292,28 +3292,32 @@ var EphemeralClient = class {
    * and zero mean different things). Returns an unsubscribe function.
    */
   subscribe(contextId, handler, codec = jsonCodec()) {
-    const listener = (event) => {
-      const e = event;
-      if (e.type !== "Ephemeral" || e.contextId !== contextId) return;
-      const data = e.data;
-      if (!data?.author) return;
-      const removed = Boolean(data.removed);
-      const entry = {
-        author: data.author,
-        state: removed || data.state === void 0 ? void 0 : codec.decode(data.state),
-        removed
-      };
-      if (data.ageMs !== void 0) entry.ageMs = data.ageMs;
-      handler(entry);
-    };
-    this.sse.on("event", listener);
-    void this.sse.connect().catch(() => void 0);
-    void this.sse.subscribe([contextId]).catch(() => void 0);
-    return () => {
-      this.sse.off("event", listener);
-    };
+    return subscribePresence(this.sse, contextId, handler, codec);
   }
 };
+function subscribePresence(sse, contextId, handler, codec = jsonCodec()) {
+  const listener = (event) => {
+    const e = event;
+    if (e.type !== "Ephemeral" || e.contextId !== contextId) return;
+    const data = e.data;
+    if (!data?.author) return;
+    const removed = Boolean(data.removed);
+    const entry = {
+      author: data.author,
+      state: removed || data.state === void 0 ? void 0 : codec.decode(data.state),
+      removed
+    };
+    if (data.ageMs !== void 0) entry.ageMs = data.ageMs;
+    if (data.account !== void 0) entry.account = data.account;
+    handler(entry);
+  };
+  sse.on("event", listener);
+  void sse.connect().catch(() => void 0);
+  void sse.subscribe([contextId]).catch(() => void 0);
+  return () => {
+    sse.off("event", listener);
+  };
+}
 
 // src/signer/signer.ts
 var PKCS8_ED25519_PREFIX2 = new Uint8Array([
@@ -7739,6 +7743,19 @@ var RelayClient = class {
     );
     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`.
    *
@@ -8040,6 +8057,7 @@ var RelayClient = class {
         text
       );
     }
+    if (response.status === 204) return void 0;
     return await response.json();
   }
 };
@@ -8467,6 +8485,121 @@ function signedPath(url) {
   return new URL(url).pathname;
 }
 
+// src/presence/statement.ts
+var PRESENCE_DOMAIN = new TextEncoder().encode("calimero/presence/1");
+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));
+}
+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)
+  );
+}
+
+// src/presence/relay-presence.ts
+var HEARTBEAT_MS = 2500;
+var RelayPresenceClient = class {
+  /**
+   * @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 = /* @__PURE__ */ new Map();
+    this.lastSeq = /* @__PURE__ */ new Map();
+    this.refused = /* @__PURE__ */ 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 = /* @__PURE__ */ 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;
+    this.timers.set(
+      contextId,
+      setInterval(() => void this.send(contextId, bytes).catch(() => void 0), 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 /* @__PURE__ */ 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 !== void 0) 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;
+      if (status === void 0 || status === 0 || status === 429 || status >= 500) return;
+      this.refused.add(contextId);
+      this.stop(contextId);
+      throw err;
+    }
+  }
+};
+
 // src/transport/mero-client.ts
 function relayHasNo(surface, why) {
   return new Error(
@@ -8510,6 +8643,7 @@ var MeroClient = class {
     this.proofAuthorizer = null;
     this.relayUrl = null;
     this.proofEvents = null;
+    this.relayPresence = null;
     if (config.transport === "relay") {
       this.transport = "relay";
       this.nodeClient = null;
@@ -8664,26 +8798,19 @@ var MeroClient = class {
   /**
    * 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 \u2014 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.
@@ -10899,9 +11026,11 @@ export {
   MeroJs,
   NODE_RELEASE_SIGNER,
   OWNER_OP_KIND,
+  PRESENCE_DOMAIN,
   REQUEST_PROOF_HEADER,
   RelayClient,
   RelayObserver,
+  RelayPresenceClient,
   RelayTransport,
   RpcClient,
   RpcError,
@@ -11021,6 +11150,7 @@ export {
   parseDeviceCredential,
   parseGovernanceWarrant,
   parseWarrantNonce,
+  presenceStatementBytes,
   probeNodeHealth,
   readCloudLinkCallback,
   readEnrolmentCallback,
@@ -11050,8 +11180,10 @@ export {
   signedPath,
   signerFromCryptoKey,
   signerFromSecret,
+  stateHash,
   subgroupCreation,
   subgroupVisibilitySetOp,
+  subscribePresence,
   teeAdmissionPolicyOp,
   teeAuthoringPolicyOp,
   teeReleaseAdmissionPolicyOp,