@calimero-network/mero-js 23.2.0 → 23.4.0

package/dist/index.d.ts

@@ -15,13 +15,15 @@ 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";
 export * from "./relay/index.js";
 export * from "./request-proof/index.js";
-export { signWarrant, intentHash, signCreationWarrant, parseCreationWarrant, creationInitHash, signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, createdSubgroupId, subgroupCreation, groupReparentedOp, groupDeletedOp, memberCapabilitySetOp, contextDetachedOp, subgroupVisibilitySetOp, groupMetadataSetOp, memberMetadataSetOp, contextMetadataSetOp, contextCapabilityGrantedOp, contextCapabilityRevokedOp, memberJoinedOpenOp, namespaceCreatedOp, defaultCapabilitiesSetOp, foundedNamespaceId, } from "./warrant/index.js";
+export { signWarrant, intentHash, signCreationWarrant, parseCreationWarrant, creationInitHash, signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, createdSubgroupId, subgroupCreation, groupReparentedOp, groupDeletedOp, memberCapabilitySetOp, contextDetachedOp, subgroupVisibilitySetOp, groupMetadataSetOp, memberMetadataSetOp, contextMetadataSetOp, contextCapabilityGrantedOp, contextCapabilityRevokedOp, memberJoinedOpenOp, namespaceCreatedOp, defaultCapabilitiesSetOp, targetApplicationSetOp, foundedNamespaceId, } from "./warrant/index.js";
 export { signerFromSecret, signerFromCryptoKey } from "./signer/index.js";
 export type { Signer } from "./signer/index.js";
 export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, createAccountRootSigner, accountRootSignerFromPhrase, signAccountLink, signAccountLogin, resolveRoot, resolveRootPair, } from "./account/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
@@ -34,7 +36,7 @@ export * from "./relay/index.js";
 // Request proofs — a caller's identity on the request itself, no session needed
 export * from "./request-proof/index.js";
 // Warrant signing — mint the author's consent for a relay to run one intent
-export { signWarrant, intentHash, signCreationWarrant, parseCreationWarrant, creationInitHash, signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, createdSubgroupId, subgroupCreation, groupReparentedOp, groupDeletedOp, memberCapabilitySetOp, contextDetachedOp, subgroupVisibilitySetOp, groupMetadataSetOp, memberMetadataSetOp, contextMetadataSetOp, contextCapabilityGrantedOp, contextCapabilityRevokedOp, memberJoinedOpenOp, namespaceCreatedOp, defaultCapabilitiesSetOp, foundedNamespaceId, } from "./warrant/index.js";
+export { signWarrant, intentHash, signCreationWarrant, parseCreationWarrant, creationInitHash, signGovernanceWarrant, parseGovernanceWarrant, governanceOpHash, memberAddedOp, memberRemovedOp, memberLeftOp, memberRoleSetOp, groupCreatedOp, createdSubgroupId, subgroupCreation, groupReparentedOp, groupDeletedOp, memberCapabilitySetOp, contextDetachedOp, subgroupVisibilitySetOp, groupMetadataSetOp, memberMetadataSetOp, contextMetadataSetOp, contextCapabilityGrantedOp, contextCapabilityRevokedOp, memberJoinedOpenOp, namespaceCreatedOp, defaultCapabilitiesSetOp, targetApplicationSetOp, foundedNamespaceId, } from "./warrant/index.js";
 // Who signs — a key's capability, separated from its material, so a
 // non-extractable key can be used wherever a hex secret could.
 export { signerFromSecret, signerFromCryptoKey } from "./signer/index.js";

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([
@@ -7405,6 +7409,7 @@ var GROUP_OP = {
   MemberRoleSet: 4,
   MemberCapabilitySet: 5,
   DefaultCapabilitiesSet: 6,
+  TargetApplicationSet: 7,
   ContextDetached: 9,
   SubgroupVisibilitySet: 10,
   GroupMetadataSet: 11,
@@ -7478,6 +7483,23 @@ async function createdSubgroupId(admin, parentId, restricted, salt) {
     ])
   );
 }
+function borshString2(value, what) {
+  if (value.length === 0) throw new Error(`${what} must not be empty`);
+  const bytes = new TextEncoder().encode(value);
+  return concat(u32le(bytes.length), bytes);
+}
+function targetApplicationSetOp(input) {
+  return {
+    kind: "group",
+    bytes: concat(
+      tag(GROUP_OP.TargetApplicationSet),
+      CLEARED_HASH,
+      fromHex(input.applicationId, "applicationId", 32),
+      borshString2(input.package, "package"),
+      borshString2(input.version, "version")
+    )
+  };
+}
 function defaultCapabilitiesSetOp(capabilities) {
   if (!Number.isInteger(capabilities) || capabilities < 0 || capabilities > 4294967295) {
     throw new Error(`capabilities must be a u32 bit mask, got ${String(capabilities)}`);
@@ -7739,6 +7761,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`.
    *
@@ -7919,6 +7954,7 @@ var RelayClient = class {
       salt
     });
     const capabilitiesOp = input.defaultCapabilities === void 0 ? void 0 : defaultCapabilitiesSetOp(input.defaultCapabilities);
+    const applicationOp = input.application ? targetApplicationSetOp(input.application) : void 0;
     const signer = await this.authorSigner();
     const nonce2 = await this.config.nonces.next();
     const ttl = this.config.ttlSeconds ?? DEFAULT_TTL_SECONDS;
@@ -7938,17 +7974,25 @@ var RelayClient = class {
       teeEnabled: data.teeEnabled ?? false,
       ...data.teeError ? { teeError: data.teeError } : {}
     };
-    if (!capabilitiesOp) return founded;
-    try {
-      await this.govern({ groupId: founded.namespaceId, op: capabilitiesOp });
-      return { ...founded, defaultCapabilitiesSet: true };
-    } catch (err) {
-      return {
-        ...founded,
-        defaultCapabilitiesSet: false,
-        defaultCapabilitiesError: err instanceof Error ? err.message : String(err)
-      };
+    let result = founded;
+    const message = (err) => err instanceof Error ? err.message : String(err);
+    if (applicationOp) {
+      try {
+        await this.govern({ groupId: founded.namespaceId, op: applicationOp });
+        result = { ...result, applicationSet: true };
+      } catch (err) {
+        result = { ...result, applicationSet: false, applicationError: message(err) };
+      }
+    }
+    if (capabilitiesOp) {
+      try {
+        await this.govern({ groupId: founded.namespaceId, op: capabilitiesOp });
+        result = { ...result, defaultCapabilitiesSet: true };
+      } catch (err) {
+        result = { ...result, defaultCapabilitiesSet: false, defaultCapabilitiesError: message(err) };
+      }
     }
+    return result;
   }
   async postGovernance(groupId, op, warrant) {
     const body = await this.json("POST", `/admin-api/groups/${encodeURIComponent(groupId)}/governance-intents`, {
@@ -8040,6 +8084,7 @@ var RelayClient = class {
         text
       );
     }
+    if (response.status === 204) return void 0;
     return await response.json();
   }
 };
@@ -8467,6 +8512,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 +8670,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 +8825,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.
@@ -10488,7 +10642,7 @@ function optionalBytes32(value, label2) {
   }
   return concat(new Uint8Array([1]), new Uint8Array(value));
 }
-function borshString2(value) {
+function borshString3(value) {
   const bytes = new TextEncoder().encode(value);
   return concat(u32le(bytes.length), bytes);
 }
@@ -10502,7 +10656,7 @@ function encodeSignedInvitation(signed) {
     // ...then the enclosing SignedGroupOpenInvitation, in declaration order.
     // `inviter_account` sits between the signature and the addresses; putting it
     // anywhere else still encodes 32 bytes and still verifies as nothing.
-    borshString2(signed.inviter_signature),
+    borshString3(signed.inviter_signature),
     signed.inviter_account ? concat(new Uint8Array([1]), fromHex(signed.inviter_account, "inviter_account", 32)) : new Uint8Array([0]),
     // A `Vec<String>`, so each entry is a bare borsh string. This carried an
     // enum until core dropped the URL variant, and an enum writes a
@@ -10510,7 +10664,7 @@ function encodeSignedInvitation(signed) {
     // every following byte and fail as `invalid invitation signature`, pointing
     // nowhere near this line.
     u32le(admitterAddrs.length),
-    ...admitterAddrs.map(borshString2),
+    ...admitterAddrs.map(borshString3),
     optionalBytes32(signed.application_id, "application_id"),
     // Borsh order follows core's field order, where this is `bytecode_id`; the
     // JSON key is `app_key`, a rename covering both directions that core pins in
@@ -10583,12 +10737,12 @@ var te = new TextEncoder();
 function tag2(byte) {
   return new Uint8Array([byte]);
 }
-function borshString3(value) {
+function borshString4(value) {
   const bytes = te.encode(value);
   return concat(u32le(bytes.length), bytes);
 }
 function borshStrings(values) {
-  return concat(u32le(values.length), ...values.map(borshString3));
+  return concat(u32le(values.length), ...values.map(borshString4));
 }
 function borshBool(value) {
   return tag2(value ? 1 : 0);
@@ -10642,7 +10796,7 @@ function teeAdmissionPolicyOp(input) {
   };
 }
 function teeReleaseAdmissionPolicyOp(input) {
-  const minRelease = input.minReleaseVersion === void 0 ? tag2(0) : concat(tag2(1), borshString3(input.minReleaseVersion));
+  const minRelease = input.minReleaseVersion === void 0 ? tag2(0) : concat(tag2(1), borshString4(input.minReleaseVersion));
   return {
     kind: "teeReleaseAdmissionPolicy",
     plane: "group",
@@ -10899,9 +11053,11 @@ export {
   MeroJs,
   NODE_RELEASE_SIGNER,
   OWNER_OP_KIND,
+  PRESENCE_DOMAIN,
   REQUEST_PROOF_HEADER,
   RelayClient,
   RelayObserver,
+  RelayPresenceClient,
   RelayTransport,
   RpcClient,
   RpcError,
@@ -11021,6 +11177,7 @@ export {
   parseDeviceCredential,
   parseGovernanceWarrant,
   parseWarrantNonce,
+  presenceStatementBytes,
   probeNodeHealth,
   readCloudLinkCallback,
   readEnrolmentCallback,
@@ -11050,8 +11207,11 @@ export {
   signedPath,
   signerFromCryptoKey,
   signerFromSecret,
+  stateHash,
   subgroupCreation,
   subgroupVisibilitySetOp,
+  subscribePresence,
+  targetApplicationSetOp,
   teeAdmissionPolicyOp,
   teeAuthoringPolicyOp,
   teeReleaseAdmissionPolicyOp,