@calimero-network/mero-js 23.1.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([
@@ -6274,6 +6278,19 @@ var CloudClient = class {
       { body }
     );
   }
+  /**
+   * Enable HA for a namespace this ACCOUNT founded through a relay, with the
+   * founder's claim (`signAccountOwnershipClaim`) instead of a node's
+   * ownership proof: a nodeless account holds no node that could issue one.
+   * The login must be linked to that account.
+   */
+  async enableFoundedNamespaceHa(namespaceId, ownershipProof) {
+    return this.request(
+      "POST",
+      `/api/cloud/me/namespaces/${encodeURIComponent(namespaceId)}/enable-ha`,
+      { body: { groups: [], ownership_proof: ownershipProof } }
+    );
+  }
   /**
    * Stop hosting a claimed namespace.
    *
@@ -7726,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`.
    *
@@ -8027,6 +8057,7 @@ var RelayClient = class {
         text
       );
     }
+    if (response.status === 204) return void 0;
     return await response.json();
   }
 };
@@ -8454,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(
@@ -8497,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;
@@ -8651,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.
@@ -8975,8 +9115,8 @@ async function hkdf2(chainingKey, inputKeyMaterial) {
   return [first, second];
 }
 function base64UrlDecode(value) {
-  const base643 = value.replace(/-/g, "+").replace(/_/g, "/");
-  const binary = atob(base643 + "=".repeat((4 - base643.length % 4) % 4));
+  const base644 = value.replace(/-/g, "+").replace(/_/g, "/");
+  const binary = atob(base644 + "=".repeat((4 - base644.length % 4) % 4));
   return Uint8Array.from(binary, (char) => char.charCodeAt(0));
 }
 
@@ -9632,6 +9772,43 @@ function assertSafeReturnTo(returnTo) {
   );
 }
 
+// src/cloud/account-ownership.ts
+var DOMAIN = new TextEncoder().encode("calimero.mdma.account-ownership-claim.v1\0");
+var DEFAULT_TTL_MS = 6e4;
+var MAX_TTL_MS = 5 * 6e4;
+function base643(bytes) {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+var hex32 = (value, what) => {
+  if (!/^[0-9a-fA-F]{64}$/.test(value)) throw new Error(`${what} must be 64 hex characters`);
+  return value.toLowerCase();
+};
+async function signAccountOwnershipClaim(input) {
+  const ttl = input.ttlMs ?? DEFAULT_TTL_MS;
+  if (!(ttl > 0 && ttl <= MAX_TTL_MS)) throw new Error(`ttlMs must be in (0, ${MAX_TTL_MS}]`);
+  if (!input.subject) throw new Error("subject must be the cloud login email");
+  const signer = await resolveSigner(input.deviceSecret, input.signer, "deviceSecret");
+  const issued = (input.now ?? Date.now)();
+  const nonce2 = Array.from(crypto.getRandomValues(new Uint8Array(16)), (b) => b.toString(16).padStart(2, "0")).join("");
+  const payload = new TextEncoder().encode(
+    JSON.stringify({
+      v: 1,
+      audience: "mdma:enable-ha-namespace",
+      group_id: hex32(input.namespaceId, "namespaceId"),
+      account_id: hex32(input.accountId, "accountId"),
+      salt: hex32(input.salt, "salt"),
+      subject: input.subject,
+      nonce: nonce2,
+      issued_at_ms: issued,
+      expires_at_ms: issued + ttl
+    })
+  );
+  const signature = await signer.sign(concat(DOMAIN, payload));
+  return { kind: "account", credential: input.credential, signed_payload: base643(payload), signature: base643(signature) };
+}
+
 // src/sealed/verify.ts
 var MEASUREMENT_HEX = /^[0-9a-f]{96}$/;
 var REGISTERS = ["mrtd", "rtmr0", "rtmr1", "rtmr2", "rtmr3"];
@@ -10849,9 +11026,11 @@ export {
   MeroJs,
   NODE_RELEASE_SIGNER,
   OWNER_OP_KIND,
+  PRESENCE_DOMAIN,
   REQUEST_PROOF_HEADER,
   RelayClient,
   RelayObserver,
+  RelayPresenceClient,
   RelayTransport,
   RpcClient,
   RpcError,
@@ -10971,6 +11150,7 @@ export {
   parseDeviceCredential,
   parseGovernanceWarrant,
   parseWarrantNonce,
+  presenceStatementBytes,
   probeNodeHealth,
   readCloudLinkCallback,
   readEnrolmentCallback,
@@ -10984,6 +11164,7 @@ export {
   shouldRetain,
   signAccountLink,
   signAccountLogin,
+  signAccountOwnershipClaim,
   signCreationWarrant,
   signDeviceCert,
   signDeviceScope,
@@ -10999,8 +11180,10 @@ export {
   signedPath,
   signerFromCryptoKey,
   signerFromSecret,
+  stateHash,
   subgroupCreation,
   subgroupVisibilitySetOp,
+  subscribePresence,
   teeAdmissionPolicyOp,
   teeAuthoringPolicyOp,
   teeReleaseAdmissionPolicyOp,