@calimero-network/mero-js 25.0.3 → 25.0.5

package/dist/index.cjs

@@ -836,6 +836,14 @@ function createRetryableMethod(method, retryOptions = {}) {
   };
 }
 
+// src/http-client/path-segment.ts
+function pathSegment(id) {
+  if (id === "" || id === "." || id === "..") {
+    throw new TypeError(`invalid request path segment: ${JSON.stringify(id)}`);
+  }
+  return encodeURIComponent(id);
+}
+
 // src/auth-api/auth-client.ts
 var AuthApiClient = class {
   constructor(httpClient) {
@@ -937,7 +945,7 @@ var AuthApiClient = class {
     return response.data;
   }
   async deleteRootKey(keyId) {
-    return this.httpClient.delete(`/admin/keys/${keyId}`);
+    return this.httpClient.delete(`/admin/keys/${pathSegment(keyId)}`);
   }
   // Client Management Endpoints
   async listClientKeys() {
@@ -954,18 +962,18 @@ var AuthApiClient = class {
   }
   async deleteClientKey(keyId, clientId) {
     return this.httpClient.delete(
-      `/admin/keys/${keyId}/clients/${clientId}`
+      `/admin/keys/${pathSegment(keyId)}/clients/${pathSegment(clientId)}`
     );
   }
   // Permission Management Endpoints
   async getKeyPermissions(keyId) {
     return this.httpClient.get(
-      `/admin/keys/${keyId}/permissions`
+      `/admin/keys/${pathSegment(keyId)}/permissions`
     );
   }
   async updateKeyPermissions(keyId, changes) {
     return this.httpClient.put(
-      `/admin/keys/${keyId}/permissions`,
+      `/admin/keys/${pathSegment(keyId)}/permissions`,
       { add: changes.add, remove: changes.remove }
     );
   }
@@ -1387,13 +1395,13 @@ var AdminApiClient = class {
     return unwrap(await this.httpClient.post("/admin-api/install-dev-application", request));
   }
   async uninstallApplication(appId) {
-    return unwrap(await this.httpClient.delete(`/admin-api/applications/${appId}`));
+    return unwrap(await this.httpClient.delete(`/admin-api/applications/${pathSegment(appId)}`));
   }
   async listApplications() {
     return unwrap(await this.httpClient.get("/admin-api/applications"));
   }
   async getApplication(appId) {
-    return unwrap(await this.httpClient.get(`/admin-api/applications/${appId}`));
+    return unwrap(await this.httpClient.get(`/admin-api/applications/${pathSegment(appId)}`));
   }
   /**
    * Installed-blob inventory for an application — one entry per locally installed
@@ -1402,7 +1410,7 @@ var AdminApiClient = class {
    */
   async listApplicationVersions(applicationId) {
     return unwrap(
-      await this.httpClient.get(`/admin-api/applications/${applicationId}/versions`)
+      await this.httpClient.get(`/admin-api/applications/${pathSegment(applicationId)}/versions`)
     );
   }
   /**
@@ -1413,7 +1421,7 @@ var AdminApiClient = class {
     const query = serviceName ? `?service_name=${encodeURIComponent(serviceName)}` : "";
     return unwrap(
       await this.httpClient.get(
-        `/admin-api/applications/${applicationId}/abi${query}`
+        `/admin-api/applications/${pathSegment(applicationId)}/abi${query}`
       )
     );
   }
@@ -1426,13 +1434,13 @@ var AdminApiClient = class {
   }
   async listPackageVersions(packageName) {
     const r = await this.httpClient.get(
-      `/admin-api/packages/${encodeURIComponent(packageName)}/versions`
+      `/admin-api/packages/${pathSegment(packageName)}/versions`
     );
     return r?.data ?? r;
   }
   async getLatestPackageVersion(packageName) {
     return this.httpClient.get(
-      `/admin-api/packages/${encodeURIComponent(packageName)}/latest`
+      `/admin-api/packages/${pathSegment(packageName)}/latest`
     );
   }
   // ---- Context Management ----
@@ -1441,43 +1449,43 @@ var AdminApiClient = class {
     return unwrap(await this.httpClient.post("/admin-api/contexts", body));
   }
   async deleteContext(contextId) {
-    return unwrap(await this.httpClient.delete(`/admin-api/contexts/${contextId}`));
+    return unwrap(await this.httpClient.delete(`/admin-api/contexts/${pathSegment(contextId)}`));
   }
   async getContexts() {
     return unwrap(await this.httpClient.get("/admin-api/contexts"));
   }
   async getContext(contextId) {
-    return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}`));
+    return unwrap(await this.httpClient.get(`/admin-api/contexts/${pathSegment(contextId)}`));
   }
   async getContextsForApplication(applicationId) {
-    return unwrap(await this.httpClient.get(`/admin-api/contexts/for-application/${applicationId}`));
+    return unwrap(await this.httpClient.get(`/admin-api/contexts/for-application/${pathSegment(applicationId)}`));
   }
   // ---- Context Identity ----
   async generateContextIdentity() {
     return unwrap(await this.httpClient.post("/admin-api/identity/context", {}));
   }
   async getContextIdentities(contextId) {
-    return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}/identities`));
+    return unwrap(await this.httpClient.get(`/admin-api/contexts/${pathSegment(contextId)}/identities`));
   }
   async getContextIdentitiesOwned(contextId) {
-    return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}/identities-owned`));
+    return unwrap(await this.httpClient.get(`/admin-api/contexts/${pathSegment(contextId)}/identities-owned`));
   }
   // ---- Context join (group membership) ----
   async joinContext(contextId) {
     return unwrap(
-      await this.httpClient.post(`/admin-api/contexts/${contextId}/join`, {})
+      await this.httpClient.post(`/admin-api/contexts/${pathSegment(contextId)}/join`, {})
     );
   }
   // ---- Context group / storage / sync ----
   async getContextGroup(contextId) {
-    return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}/group`));
+    return unwrap(await this.httpClient.get(`/admin-api/contexts/${pathSegment(contextId)}/group`));
   }
   async getContextStorage(contextId) {
-    return unwrap(await this.httpClient.get(`/admin-api/contexts/${contextId}/storage`));
+    return unwrap(await this.httpClient.get(`/admin-api/contexts/${pathSegment(contextId)}/storage`));
   }
   /** Sync one context, or every context when `contextId` is omitted. */
   async syncContext(contextId) {
-    const path = contextId ? `/admin-api/contexts/sync/${contextId}` : "/admin-api/contexts/sync";
+    const path = contextId ? `/admin-api/contexts/sync/${pathSegment(contextId)}` : "/admin-api/contexts/sync";
     await this.httpClient.post(path, {});
   }
   /**
@@ -1487,7 +1495,7 @@ var AdminApiClient = class {
    */
   async resyncContext(contextId, request = {}) {
     const r = await this.httpClient.post(
-      `/admin-api/contexts/${contextId}/resync`,
+      `/admin-api/contexts/${pathSegment(contextId)}/resync`,
       request
     );
     return r ?? { contextId, resyncStarted: true };
@@ -1501,10 +1509,10 @@ var AdminApiClient = class {
     );
   }
   async updateContextApplication(contextId, request) {
-    await this.httpClient.post(`/admin-api/contexts/${contextId}/application`, request);
+    await this.httpClient.post(`/admin-api/contexts/${pathSegment(contextId)}/application`, request);
   }
   async getContextsWithExecutorsForApplication(applicationId) {
-    const r = await this.httpClient.get(`/admin-api/contexts/with-executors/for-application/${applicationId}`);
+    const r = await this.httpClient.get(`/admin-api/contexts/with-executors/for-application/${pathSegment(applicationId)}`);
     if (Array.isArray(r)) return r;
     return r?.contexts ?? r?.data ?? [];
   }
@@ -1526,7 +1534,7 @@ var AdminApiClient = class {
   }
   async deleteBlob(blobId) {
     const body = await this.httpClient.delete(
-      `/admin-api/blobs/${blobId}`
+      `/admin-api/blobs/${pathSegment(blobId)}`
     );
     return { blobId: body.blob_id, deleted: body.deleted };
   }
@@ -1544,9 +1552,9 @@ var AdminApiClient = class {
    * side from drifting from the write side.
    */
   blobPath(blobId, options) {
-    if (!options?.contextId) return `/admin-api/blobs/${blobId}`;
+    if (!options?.contextId) return `/admin-api/blobs/${pathSegment(blobId)}`;
     const params = new URLSearchParams({ context_id: options.contextId });
-    return `/admin-api/blobs/${blobId}?${params.toString()}`;
+    return `/admin-api/blobs/${pathSegment(blobId)}?${params.toString()}`;
   }
   /**
    * Download a blob's raw bytes. `GET /admin-api/blobs/:id` streams the blob
@@ -1611,7 +1619,7 @@ var AdminApiClient = class {
   async lookupContextAlias(name) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/alias/lookup/context/${encodeURIComponent(name)}`,
+        `/admin-api/alias/lookup/context/${pathSegment(name)}`,
         {}
       )
     );
@@ -1619,7 +1627,7 @@ var AdminApiClient = class {
   async lookupApplicationAlias(name) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/alias/lookup/application/${encodeURIComponent(name)}`,
+        `/admin-api/alias/lookup/application/${pathSegment(name)}`,
         {}
       )
     );
@@ -1627,7 +1635,7 @@ var AdminApiClient = class {
   async deleteContextAlias(name) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/alias/delete/context/${encodeURIComponent(name)}`,
+        `/admin-api/alias/delete/context/${pathSegment(name)}`,
         {}
       )
     );
@@ -1635,7 +1643,7 @@ var AdminApiClient = class {
   async deleteApplicationAlias(name) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/alias/delete/application/${encodeURIComponent(name)}`,
+        `/admin-api/alias/delete/application/${pathSegment(name)}`,
         {}
       )
     );
@@ -1657,7 +1665,7 @@ var AdminApiClient = class {
   async lookupDeviceAlias(name) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/alias/lookup/device/${encodeURIComponent(name)}`,
+        `/admin-api/alias/lookup/device/${pathSegment(name)}`,
         {}
       )
     );
@@ -1665,7 +1673,7 @@ var AdminApiClient = class {
   async deleteDeviceAlias(name) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/alias/delete/device/${encodeURIComponent(name)}`,
+        `/admin-api/alias/delete/device/${pathSegment(name)}`,
         {}
       )
     );
@@ -1678,7 +1686,7 @@ var AdminApiClient = class {
     return unwrap(await this.httpClient.get("/admin-api/namespaces"));
   }
   async getNamespace(namespaceId) {
-    return unwrap(await this.httpClient.get(`/admin-api/namespaces/${namespaceId}`));
+    return unwrap(await this.httpClient.get(`/admin-api/namespaces/${pathSegment(namespaceId)}`));
   }
   /**
    * Who this node is — the account it writes as, the device it is, the key it
@@ -1743,7 +1751,7 @@ var AdminApiClient = class {
   async performIntent(contextId, request) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/contexts/${contextId}/intents`,
+        `/admin-api/contexts/${pathSegment(contextId)}/intents`,
         request
       )
     );
@@ -1760,7 +1768,7 @@ var AdminApiClient = class {
   async queryContext(contextId, request) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/contexts/${contextId}/query`,
+        `/admin-api/contexts/${pathSegment(contextId)}/query`,
         request
       )
     );
@@ -1789,12 +1797,12 @@ var AdminApiClient = class {
   async getIntentRelay(contextId) {
     return unwrap(
       await this.httpClient.get(
-        `/admin-api/contexts/${contextId}/intents`
+        `/admin-api/contexts/${pathSegment(contextId)}/intents`
       )
     );
   }
   async listNamespacesForApplication(applicationId) {
-    return unwrap(await this.httpClient.get(`/admin-api/namespaces/for-application/${applicationId}`));
+    return unwrap(await this.httpClient.get(`/admin-api/namespaces/for-application/${pathSegment(applicationId)}`));
   }
   async createNamespace(request) {
     return unwrap(
@@ -1803,7 +1811,7 @@ var AdminApiClient = class {
   }
   async deleteNamespace(namespaceId) {
     return unwrap(
-      await this.httpClient.request(`/admin-api/namespaces/${namespaceId}`, {
+      await this.httpClient.request(`/admin-api/namespaces/${pathSegment(namespaceId)}`, {
         method: "DELETE",
         body: "{}",
         headers: { "Content-Type": "application/json" }
@@ -1813,7 +1821,7 @@ var AdminApiClient = class {
   async createNamespaceInvitation(namespaceId, request) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/namespaces/${namespaceId}/invite`,
+        `/admin-api/namespaces/${pathSegment(namespaceId)}/invite`,
         request ?? {}
       )
     );
@@ -1838,7 +1846,7 @@ var AdminApiClient = class {
   async admitJoin(namespaceId, request) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/namespaces/${namespaceId}/admit`,
+        `/admin-api/namespaces/${pathSegment(namespaceId)}/admit`,
         request,
         { timeoutMs: 65e3 }
       )
@@ -1847,7 +1855,7 @@ var AdminApiClient = class {
   async joinNamespace(namespaceId, request) {
     const data = unwrap(
       await this.httpClient.post(
-        `/admin-api/namespaces/${namespaceId}/join`,
+        `/admin-api/namespaces/${pathSegment(namespaceId)}/join`,
         request,
         { timeoutMs: 65e3 }
       )
@@ -1894,13 +1902,13 @@ var AdminApiClient = class {
   async createGroupInNamespace(namespaceId, request) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/namespaces/${namespaceId}/groups`,
+        `/admin-api/namespaces/${pathSegment(namespaceId)}/groups`,
         request ?? {}
       )
     );
   }
   async listNamespaceGroups(namespaceId) {
-    return unwrap(await this.httpClient.get(`/admin-api/namespaces/${namespaceId}/groups`));
+    return unwrap(await this.httpClient.get(`/admin-api/namespaces/${pathSegment(namespaceId)}/groups`));
   }
   // ---- Account Devices & Pairing ----
   /**
@@ -1962,7 +1970,7 @@ var AdminApiClient = class {
   async relinkAccountDevice(deviceId, request) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/account/devices/${deviceId}/relink`,
+        `/admin-api/account/devices/${pathSegment(deviceId)}/relink`,
         request ?? {}
       )
     );
@@ -1977,7 +1985,7 @@ var AdminApiClient = class {
   async rescopeAccountDevice(deviceId, request) {
     return unwrap(
       await this.httpClient.put(
-        `/admin-api/account/devices/${encodeURIComponent(deviceId)}/scope`,
+        `/admin-api/account/devices/${pathSegment(deviceId)}/scope`,
         request
       )
     );
@@ -2028,7 +2036,7 @@ var AdminApiClient = class {
   async labelAccountDevice(deviceId, request) {
     return unwrap(
       await this.httpClient.put(
-        `/admin-api/account/devices/${encodeURIComponent(deviceId)}/label`,
+        `/admin-api/account/devices/${pathSegment(deviceId)}/label`,
         request
       )
     );
@@ -2092,7 +2100,7 @@ var AdminApiClient = class {
   async revokeAccountDevice(namespaceId, request) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/namespaces/${namespaceId}/account/revoke`,
+        `/admin-api/namespaces/${pathSegment(namespaceId)}/account/revoke`,
         request
       )
     );
@@ -2115,14 +2123,14 @@ var AdminApiClient = class {
   async linkAccountDevice(namespaceId, request) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/namespaces/${namespaceId}/account/link-device`,
+        `/admin-api/namespaces/${pathSegment(namespaceId)}/account/link-device`,
         request
       )
     );
   }
   // ---- Group Management ----
   async getGroupInfo(groupId) {
-    return unwrap(await this.httpClient.get(`/admin-api/groups/${groupId}`));
+    return unwrap(await this.httpClient.get(`/admin-api/groups/${pathSegment(groupId)}`));
   }
   /** Thin wrapper over {@link getGroupInfo}: returns the group's `defaultCapabilities` bitmask. */
   async getDefaultCapabilities(groupId) {
@@ -2134,7 +2142,7 @@ var AdminApiClient = class {
   }
   async deleteGroup(groupId) {
     return unwrap(
-      await this.httpClient.request(`/admin-api/groups/${groupId}`, {
+      await this.httpClient.request(`/admin-api/groups/${pathSegment(groupId)}`, {
         method: "DELETE",
         body: "{}",
         headers: { "Content-Type": "application/json" }
@@ -2143,7 +2151,7 @@ var AdminApiClient = class {
   }
   async listGroupMembers(groupId) {
     const response = await this.httpClient.get(
-      `/admin-api/groups/${groupId}/members`
+      `/admin-api/groups/${pathSegment(groupId)}/members`
     );
     if (!Array.isArray(response?.members)) {
       const safeId = String(groupId).replace(/[\r\n\t\s]/g, "").slice(0, 64);
@@ -2181,7 +2189,7 @@ var AdminApiClient = class {
     if (options?.offset !== void 0) params.set("offset", String(options.offset));
     if (options?.limit !== void 0) params.set("limit", String(options.limit));
     const query = params.toString();
-    const base = `/admin-api/groups/${encodeURIComponent(groupId)}/member-devices`;
+    const base = `/admin-api/groups/${pathSegment(groupId)}/member-devices`;
     const response = await this.httpClient.get(
       query ? `${base}?${query}` : base
     );
@@ -2233,7 +2241,7 @@ var AdminApiClient = class {
    *        hex (exactly 64). The node accepts either; the two never collide.
    */
   async getWarrantNonce(contextId, authorDeviceKey) {
-    const path = `/admin-api/contexts/${encodeURIComponent(contextId)}/warrant-nonce/${encodeURIComponent(authorDeviceKey)}`;
+    const path = `/admin-api/contexts/${pathSegment(contextId)}/warrant-nonce/${pathSegment(authorDeviceKey)}`;
     let raw;
     try {
       raw = await this.httpClient.get(path, { parse: "text" });
@@ -2273,7 +2281,7 @@ var AdminApiClient = class {
    *        value passed as `authorProof` to the relay client.
    */
   async getWarrantNonceAsAuthor(contextId, authorProof) {
-    const path = `/admin-api/contexts/${encodeURIComponent(contextId)}/warrant-nonce`;
+    const path = `/admin-api/contexts/${pathSegment(contextId)}/warrant-nonce`;
     let raw;
     try {
       raw = await this.httpClient.post(path, { authorProof }, { parse: "text" });
@@ -2295,7 +2303,7 @@ var AdminApiClient = class {
     if (options.offset !== void 0) params.set("offset", String(options.offset));
     if (options.limit !== void 0) params.set("limit", String(options.limit));
     const query = params.toString();
-    const path = `/admin-api/groups/${groupId}/member-devices${query ? `?${query}` : ""}`;
+    const path = `/admin-api/groups/${pathSegment(groupId)}/member-devices${query ? `?${query}` : ""}`;
     return this.httpClient.get(path);
   }
   /**
@@ -2306,19 +2314,19 @@ var AdminApiClient = class {
   async sealToAccount(groupId, account, request) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/groups/${groupId}/accounts/${account}/seal`,
+        `/admin-api/groups/${pathSegment(groupId)}/accounts/${pathSegment(account)}/seal`,
         request
       )
     );
   }
   async listGroupContexts(groupId) {
-    return unwrap(await this.httpClient.get(`/admin-api/groups/${groupId}/contexts`));
+    return unwrap(await this.httpClient.get(`/admin-api/groups/${pathSegment(groupId)}/contexts`));
   }
   async addGroupMembers(groupId, request) {
-    await this.httpClient.post(`/admin-api/groups/${groupId}/members`, request);
+    await this.httpClient.post(`/admin-api/groups/${pathSegment(groupId)}/members`, request);
   }
   async removeGroupMembers(groupId, request) {
-    await this.httpClient.post(`/admin-api/groups/${groupId}/members/remove`, request);
+    await this.httpClient.post(`/admin-api/groups/${pathSegment(groupId)}/members/remove`, request);
   }
   /**
    * `identity` is the member's ACCOUNT (64 hex), as returned by
@@ -2326,7 +2334,7 @@ var AdminApiClient = class {
    * 64 hex, so nothing but the source tells them apart.
    */
   async updateMemberRole(groupId, identity, request) {
-    await this.httpClient.put(`/admin-api/groups/${groupId}/members/${identity}/role`, request);
+    await this.httpClient.put(`/admin-api/groups/${pathSegment(groupId)}/members/${pathSegment(identity)}/role`, request);
   }
   /**
    * `identity` is the member's ACCOUNT (64 hex), as returned by
@@ -2336,7 +2344,7 @@ var AdminApiClient = class {
   async getMemberCapabilities(groupId, identity) {
     return unwrap(
       await this.httpClient.get(
-        `/admin-api/groups/${groupId}/members/${identity}/capabilities`
+        `/admin-api/groups/${pathSegment(groupId)}/members/${pathSegment(identity)}/capabilities`
       )
     );
   }
@@ -2346,10 +2354,10 @@ var AdminApiClient = class {
    * 64 hex, so nothing but the source tells them apart.
    */
   async setMemberCapabilities(groupId, identity, request) {
-    await this.httpClient.put(`/admin-api/groups/${groupId}/members/${identity}/capabilities`, request);
+    await this.httpClient.put(`/admin-api/groups/${pathSegment(groupId)}/members/${pathSegment(identity)}/capabilities`, request);
   }
   async setDefaultCapabilities(groupId, request) {
-    await this.httpClient.put(`/admin-api/groups/${groupId}/settings/default-capabilities`, request);
+    await this.httpClient.put(`/admin-api/groups/${pathSegment(groupId)}/settings/default-capabilities`, request);
   }
   /**
    * Make every member admitted to `groupId` from now on able to relay a
@@ -2431,13 +2439,13 @@ var AdminApiClient = class {
     return { changed: true, capabilities: next };
   }
   async setSubgroupVisibility(groupId, request) {
-    await this.httpClient.put(`/admin-api/groups/${groupId}/settings/subgroup-visibility`, request);
+    await this.httpClient.put(`/admin-api/groups/${pathSegment(groupId)}/settings/subgroup-visibility`, request);
   }
   async setTeeAdmissionPolicy(groupId, request) {
-    await this.httpClient.put(`/admin-api/groups/${groupId}/settings/tee-admission-policy`, request);
+    await this.httpClient.put(`/admin-api/groups/${pathSegment(groupId)}/settings/tee-admission-policy`, request);
   }
   async getTeeAdmissionPolicy(groupId) {
-    const response = await this.httpClient.get(`/admin-api/groups/${groupId}/settings/tee-admission-policy`);
+    const response = await this.httpClient.get(`/admin-api/groups/${pathSegment(groupId)}/settings/tee-admission-policy`);
     return response.data ?? response;
   }
   /**
@@ -2447,7 +2455,7 @@ var AdminApiClient = class {
    * route for this policy.
    */
   async setTeeAuthoringPolicy(groupId, request) {
-    await this.httpClient.put(`/admin-api/groups/${groupId}/settings/tee-authoring-policy`, request);
+    await this.httpClient.put(`/admin-api/groups/${pathSegment(groupId)}/settings/tee-authoring-policy`, request);
   }
   /**
    * Turns TEE authorship off in the namespace: every TEE loses its authority,
@@ -2459,7 +2467,7 @@ var AdminApiClient = class {
    * (`teeAuthoringPolicyOp([])`); omit it on a node that holds that root.
    */
   async disableTeeAuthoringPolicy(groupId, options = {}) {
-    const path = `/admin-api/groups/${groupId}/settings/tee-authoring-policy`;
+    const path = `/admin-api/groups/${pathSegment(groupId)}/settings/tee-authoring-policy`;
     if (options.rootProof === void 0) {
       await this.httpClient.delete(path);
       return;
@@ -2477,14 +2485,14 @@ var AdminApiClient = class {
    * {@link RootGuardedOpRequest}.
    */
   async transferOwnership(groupId, request) {
-    await this.httpClient.post(`/admin-api/groups/${groupId}/transfer-ownership`, request);
+    await this.httpClient.post(`/admin-api/groups/${pathSegment(groupId)}/transfer-ownership`, request);
   }
   /**
    * Repoint the namespace's admin pin at `newAdmin`, a member of its root.
    * Owner-only, with the owner account's root proof; see {@link RootGuardedOpRequest}.
    */
   async changeNamespaceAdmin(namespaceId, request) {
-    await this.httpClient.post(`/admin-api/namespaces/${namespaceId}/admin`, request);
+    await this.httpClient.post(`/admin-api/namespaces/${pathSegment(namespaceId)}/admin`, request);
   }
   /**
    * Delete a group through the owner-only path: it must hold no contexts, and
@@ -2492,20 +2500,20 @@ var AdminApiClient = class {
    * admin-level cascading delete.
    */
   async ownerDeleteGroup(groupId, request = {}) {
-    await this.httpClient.post(`/admin-api/groups/${groupId}/owner-delete`, request);
+    await this.httpClient.post(`/admin-api/groups/${pathSegment(groupId)}/owner-delete`, request);
   }
   // ---- Group / member / context metadata ----
   async setGroupMetadata(groupId, request) {
-    await this.httpClient.put(`/admin-api/groups/${groupId}/metadata`, request);
+    await this.httpClient.put(`/admin-api/groups/${pathSegment(groupId)}/metadata`, request);
   }
   async getGroupMetadata(groupId) {
     const response = await this.httpClient.get(
-      `/admin-api/groups/${groupId}/metadata`
+      `/admin-api/groups/${pathSegment(groupId)}/metadata`
     );
     return response?.data ?? null;
   }
   async setMemberMetadata(groupId, identity, request) {
-    await this.httpClient.put(`/admin-api/groups/${groupId}/members/${identity}/metadata`, request);
+    await this.httpClient.put(`/admin-api/groups/${pathSegment(groupId)}/members/${pathSegment(identity)}/metadata`, request);
   }
   /**
    * `identity` is the member's ACCOUNT (64 hex), as returned by
@@ -2514,28 +2522,28 @@ var AdminApiClient = class {
    */
   async getMemberMetadata(groupId, identity) {
     const response = await this.httpClient.get(
-      `/admin-api/groups/${groupId}/members/${identity}/metadata`
+      `/admin-api/groups/${pathSegment(groupId)}/members/${pathSegment(identity)}/metadata`
     );
     return response?.data ?? null;
   }
   async setContextMetadata(groupId, contextId, request) {
-    await this.httpClient.put(`/admin-api/groups/${groupId}/contexts/${contextId}/metadata`, request);
+    await this.httpClient.put(`/admin-api/groups/${pathSegment(groupId)}/contexts/${pathSegment(contextId)}/metadata`, request);
   }
   async getContextMetadata(groupId, contextId) {
     const response = await this.httpClient.get(
-      `/admin-api/groups/${groupId}/contexts/${contextId}/metadata`
+      `/admin-api/groups/${pathSegment(groupId)}/contexts/${pathSegment(contextId)}/metadata`
     );
     return response?.data ?? null;
   }
   async syncGroup(groupId) {
-    return unwrap(await this.httpClient.post(`/admin-api/groups/${groupId}/sync`, {}));
+    return unwrap(await this.httpClient.post(`/admin-api/groups/${pathSegment(groupId)}/sync`, {}));
   }
   async upgradeGroup(groupId, request) {
-    return unwrap(await this.httpClient.post(`/admin-api/groups/${groupId}/upgrade`, request));
+    return unwrap(await this.httpClient.post(`/admin-api/groups/${pathSegment(groupId)}/upgrade`, request));
   }
   async getGroupUpgradeStatus(groupId) {
     return unwrap(
-      await this.httpClient.get(`/admin-api/groups/${groupId}/upgrade/status`)
+      await this.httpClient.get(`/admin-api/groups/${pathSegment(groupId)}/upgrade/status`)
     );
   }
   /**
@@ -2544,43 +2552,41 @@ var AdminApiClient = class {
    * envelope to unwrap here (unlike most admin reads).
    */
   async getMigrationStatus(namespaceId) {
-    const id = encodeURIComponent(namespaceId);
-    return this.httpClient.get(`/admin-api/groups/${id}/migration-status`);
+    return this.httpClient.get(`/admin-api/groups/${pathSegment(namespaceId)}/migration-status`);
   }
   /** Per-group cascade-migration snapshots for a namespace. */
   async getCascadeStatus(namespaceId) {
-    const id = encodeURIComponent(namespaceId);
     return unwrap(
-      await this.httpClient.get(`/admin-api/groups/${id}/cascade-status`)
+      await this.httpClient.get(`/admin-api/groups/${pathSegment(namespaceId)}/cascade-status`)
     );
   }
   async retryGroupUpgrade(groupId) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/groups/${groupId}/upgrade/retry`,
+        `/admin-api/groups/${pathSegment(groupId)}/upgrade/retry`,
         {}
       )
     );
   }
   /** Move `childGroupId` under `request.newParentId`. */
   async reparentGroup(childGroupId, request) {
-    const r = await this.httpClient.post(`/admin-api/groups/${childGroupId}/reparent`, request);
+    const r = await this.httpClient.post(`/admin-api/groups/${pathSegment(childGroupId)}/reparent`, request);
     return r?.data ?? r;
   }
   async listSubgroups(groupId) {
     const response = await this.httpClient.get(
-      `/admin-api/groups/${groupId}/subgroups`
+      `/admin-api/groups/${pathSegment(groupId)}/subgroups`
     );
     return response.subgroups ?? response.data ?? [];
   }
   async detachContextFromGroup(groupId, contextId) {
-    await this.httpClient.post(`/admin-api/groups/${groupId}/contexts/${contextId}/remove`, {});
+    await this.httpClient.post(`/admin-api/groups/${pathSegment(groupId)}/contexts/${pathSegment(contextId)}/remove`, {});
   }
   // ---- Group Invitation & Join ----
   async createGroupInvitation(groupId, request) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/groups/${groupId}/invite`,
+        `/admin-api/groups/${pathSegment(groupId)}/invite`,
         request ?? {}
       )
     );
@@ -2593,7 +2599,7 @@ var AdminApiClient = class {
   async joinSubgroupInheritance(groupId) {
     return unwrap(
       await this.httpClient.post(
-        `/admin-api/groups/${groupId}/join-via-inheritance`,
+        `/admin-api/groups/${pathSegment(groupId)}/join-via-inheritance`,
         {}
       )
     );
@@ -2635,27 +2641,27 @@ var AdminApiClient = class {
   }
   /** Leave a group (POST /admin-api/groups/:group_id/leave). */
   async leaveGroup(groupId) {
-    await this.httpClient.post(`/admin-api/groups/${groupId}/leave`, {});
+    await this.httpClient.post(`/admin-api/groups/${pathSegment(groupId)}/leave`, {});
   }
   /** Leave a context (POST /admin-api/contexts/:context_id/leave). */
   async leaveContext(contextId) {
-    await this.httpClient.post(`/admin-api/contexts/${contextId}/leave`, {});
+    await this.httpClient.post(`/admin-api/contexts/${pathSegment(contextId)}/leave`, {});
   }
   /** Leave a namespace (POST /admin-api/namespaces/:namespace_id/leave). */
   async leaveNamespace(namespaceId) {
-    await this.httpClient.post(`/admin-api/namespaces/${namespaceId}/leave`, {});
+    await this.httpClient.post(`/admin-api/namespaces/${pathSegment(namespaceId)}/leave`, {});
   }
   /** Issue a group ownership proof (POST /admin-api/groups/:group_id/issue-ownership-proof). */
   async issueOwnershipProof(groupId, request) {
     return this.httpClient.post(
-      `/admin-api/groups/${groupId}/issue-ownership-proof`,
+      `/admin-api/groups/${pathSegment(groupId)}/issue-ownership-proof`,
       request
     );
   }
   /** Issue a namespace ownership proof (POST /admin-api/groups/:group_id/issue-namespace-ownership-proof). */
   async issueNamespaceOwnershipProof(groupId, request) {
     return this.httpClient.post(
-      `/admin-api/groups/${groupId}/issue-namespace-ownership-proof`,
+      `/admin-api/groups/${pathSegment(groupId)}/issue-namespace-ownership-proof`,
       request
     );
   }
@@ -2668,11 +2674,11 @@ var AdminApiClient = class {
    * 64 hex, so nothing but the source tells them apart.
    */
   async setMemberAutoFollow(groupId, identity, request) {
-    await this.httpClient.put(`/admin-api/groups/${groupId}/members/${identity}/auto-follow`, request);
+    await this.httpClient.put(`/admin-api/groups/${pathSegment(groupId)}/members/${pathSegment(identity)}/auto-follow`, request);
   }
   /** Abort a namespace migration (POST /admin-api/groups/:namespace_id/migration/abort). */
   async abortMigration(namespaceId) {
-    return this.httpClient.post(`/admin-api/groups/${namespaceId}/migration/abort`, {});
+    return this.httpClient.post(`/admin-api/groups/${pathSegment(namespaceId)}/migration/abort`, {});
   }
 };
 
@@ -8211,7 +8217,7 @@ var RelayClient = class {
   async describe(contextId) {
     const body = await this.json(
       "GET",
-      `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`
+      `/admin-api/contexts/${pathSegment(contextId)}/intents`
     );
     return body.data;
   }
@@ -8248,7 +8254,7 @@ var RelayClient = class {
     });
     const body = await this.json(
       "POST",
-      `/admin-api/contexts/${encodeURIComponent(contextId)}/intents`,
+      `/admin-api/contexts/${pathSegment(contextId)}/intents`,
       { method, argsJson, warrant, authorProof: this.config.authorProof }
     );
     return { rootHash: body.data.rootHash, returns: body.data.returns ?? null };
@@ -8262,7 +8268,7 @@ var RelayClient = class {
   async presenceIntent(contextId, body) {
     await this.jsonOnce(
       "POST",
-      `/admin-api/contexts/${encodeURIComponent(contextId)}/presence-intents`,
+      `/admin-api/contexts/${pathSegment(contextId)}/presence-intents`,
       body
     );
   }
@@ -8276,7 +8282,7 @@ var RelayClient = class {
     const query = opts.author ? `?author=${encodeURIComponent(opts.author)}` : "";
     const body = await this.json(
       "GET",
-      `/admin-api/groups/${encodeURIComponent(groupId)}/context-intents${query}`
+      `/admin-api/groups/${pathSegment(groupId)}/context-intents${query}`
     );
     return body.data;
   }
@@ -8340,7 +8346,7 @@ var RelayClient = class {
     });
     const body = await this.json(
       "POST",
-      `/admin-api/groups/${encodeURIComponent(input.groupId)}/context-intents`,
+      `/admin-api/groups/${pathSegment(input.groupId)}/context-intents`,
       { warrant, authorProof: this.config.authorProof, initArgs }
     );
     return {
@@ -8356,7 +8362,7 @@ var RelayClient = class {
   async describeGovernance(groupId) {
     const body = await this.json(
       "GET",
-      `/admin-api/groups/${encodeURIComponent(groupId)}/governance-intents`
+      `/admin-api/groups/${pathSegment(groupId)}/governance-intents`
     );
     return body.data;
   }
@@ -8488,7 +8494,7 @@ var RelayClient = class {
     return result;
   }
   async postGovernance(groupId, op, warrant) {
-    const body = await this.json("POST", `/admin-api/groups/${encodeURIComponent(groupId)}/governance-intents`, {
+    const body = await this.json("POST", `/admin-api/groups/${pathSegment(groupId)}/governance-intents`, {
       warrant,
       authorProof: this.config.authorProof,
       op: hex(op.bytes)
@@ -10191,15 +10197,70 @@ function base643(bytes) {
   return btoa(binary);
 }
 
+// src/cloud/link-state.ts
+var KEY2 = "calimero.cloud.link.pending";
+var STATE_PARAM = "link_state";
+var LIFETIME_MS = 10 * 60 * 1e3;
+var ACCOUNT_HEX = /^[0-9a-f]{64}$/;
+var MAX_PENDING = 20;
+function readPending(now) {
+  try {
+    const raw = localStorage.getItem(KEY2);
+    const pending = raw ? JSON.parse(raw) : {};
+    return Object.fromEntries(
+      Object.entries(pending).filter(
+        ([, p]) => p && typeof p.expiresAt === "number" && p.expiresAt > now
+      )
+    );
+  } catch {
+    return {};
+  }
+}
+function writePending(pending) {
+  try {
+    localStorage.setItem(KEY2, JSON.stringify(pending));
+  } catch {
+  }
+}
+function beginLinkState(account, returnTo) {
+  if (!ACCOUNT_HEX.test(account)) {
+    throw new Error("accountId must be 64 lowercase hex characters");
+  }
+  const url = new URL(returnTo);
+  const now = Date.now();
+  const pending = readPending(now);
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  const state = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(
+    ""
+  );
+  pending[state] = { account, expiresAt: now + LIFETIME_MS };
+  writePending(Object.fromEntries(Object.entries(pending).slice(-MAX_PENDING)));
+  url.searchParams.set(STATE_PARAM, state);
+  return url.toString();
+}
+function takeLinkState(search) {
+  const state = new URLSearchParams(search).get(STATE_PARAM);
+  const pending = readPending(Date.now());
+  if (!state || !Object.prototype.hasOwnProperty.call(pending, state))
+    return null;
+  const entry = pending[state];
+  delete pending[state];
+  writePending(pending);
+  return entry;
+}
+function withoutLinkState(search) {
+  const params = new URLSearchParams(search);
+  params.delete(STATE_PARAM);
+  const rest = params.toString();
+  return rest ? `?${rest}` : "";
+}
+
 // src/cloud/link-redirect.ts
 var DEFAULT_CLOUD_WEB_URL = "https://cloud.calimero.network";
 function cloudLinkUrl(options) {
-  if (!/^[0-9a-f]{64}$/.test(options.accountId)) {
-    throw new Error("accountId must be 64 lowercase hex characters");
-  }
   const url = new URL(options.cloudWebUrl ?? DEFAULT_CLOUD_WEB_URL);
   url.searchParams.set("link-account", options.accountId);
-  url.searchParams.set("callback-url", options.returnTo);
+  url.searchParams.set("callback-url", beginLinkState(options.accountId, options.returnTo));
   return url.toString();
 }
 function beginCloudLink(options) {
@@ -10210,6 +10271,7 @@ function readCloudLinkCallback(location2 = window.location) {
   const params = new URLSearchParams(location2.hash.replace(/^#/, ""));
   const error = params.get("error");
   if (error) {
+    takeLinkState(location2.search ?? "");
     stripFragment();
     throw new Error(
       error === "denied" ? "the account link was declined at the cloud" : `the cloud refused this link: ${error}`
@@ -10218,12 +10280,18 @@ function readCloudLinkCallback(location2 = window.location) {
   const grant = params.get("grant");
   const account = params.get("account");
   if (!grant || !account) return null;
+  if (takeLinkState(location2.search ?? "")?.account !== account) {
+    stripFragment();
+    throw new Error(
+      "this account link answers a request this browser did not make - start the link again from here"
+    );
+  }
   stripFragment();
   return { grant, account };
 }
 function stripFragment() {
   if (typeof history === "undefined" || !history.replaceState) return;
-  history.replaceState(null, "", location.pathname + location.search);
+  history.replaceState(null, "", location.pathname + withoutLinkState(location.search));
 }
 async function completeCloudLink(options) {
   const root = await resolveRoot(options.root);
@@ -10243,7 +10311,7 @@ async function completeCloudLink(options) {
 var DEVICE_PARAM = "enrol-device";
 var KEM_PARAM = "enrol-kem";
 var CALLBACK_PARAM = "callback-url";
-var STATE_PARAM = "state";
+var STATE_PARAM2 = "state";
 function deviceEnrolmentUrl(options) {
   assertHex(options.devicePublicKey, "devicePublicKey");
   assertHex(options.kemPublicKey, "kemPublicKey");
@@ -10253,7 +10321,7 @@ function deviceEnrolmentUrl(options) {
   url.searchParams.set(DEVICE_PARAM, options.devicePublicKey);
   url.searchParams.set(KEM_PARAM, options.kemPublicKey);
   url.searchParams.set(CALLBACK_PARAM, options.returnTo);
-  if (options.state) url.searchParams.set(STATE_PARAM, options.state);
+  if (options.state) url.searchParams.set(STATE_PARAM2, options.state);
   return url.toString();
 }
 function beginDeviceEnrolment(options) {
@@ -10420,7 +10488,7 @@ async function resolveRelayFromInvitation(input) {
     relayUrl: chosen.relayUrl,
     // The cloud's ready-made URL when it gave one, so the path is never rebuilt
     // from a guess; the fallback is the documented route on the same origin.
-    admitUrl: chosen.admitUrl ?? `${chosen.relayUrl.replace(/\/+$/, "")}/admin-api/namespaces/${input.namespaceId}/admit`,
+    admitUrl: chosen.admitUrl ?? `${chosen.relayUrl.replace(/\/+$/, "")}/admin-api/namespaces/${pathSegment(input.namespaceId)}/admit`,
     admitterAccount: chosen.account,
     peerId: chosen.peerId,
     writable: chosen.canExecute,
@@ -10658,7 +10726,7 @@ async function joinWithNode(input) {
     };
   }
   const body = { invitation: input.invitation, signedOp };
-  const url = input.admitUrl ?? `${origin(input.nodeUrl)}/admin-api/namespaces/${input.namespaceId}/admit`;
+  const url = input.admitUrl ?? `${origin(input.nodeUrl)}/admin-api/namespaces/${pathSegment(input.namespaceId)}/admit`;
   const doFetch = input.deps?.fetch ?? fetch;
   let response;
   try {
@@ -11351,7 +11419,6 @@ function joinOf(row) {
     reportedAt: typeof join.reported_at === "string" ? join.reported_at : null
   };
 }
-var ACCOUNT_HEX = /^[0-9a-f]{64}$/;
 function accountHexOrNull(value) {
   return typeof value === "string" && ACCOUNT_HEX.test(value) ? value : null;
 }
@@ -11571,7 +11638,7 @@ var CloudClient = class {
   async getNamespaceRelays(namespaceId) {
     const body = await this.request(
       "GET",
-      `/api/cloud/me/namespaces/${encodeURIComponent(namespaceId)}/relays`
+      `/api/cloud/me/namespaces/${pathSegment(namespaceId)}/relays`
     );
     return (body.relays ?? []).map((row) => {
       const relayUrl = row.relay_url ?? null;
@@ -11629,7 +11696,7 @@ var CloudClient = class {
    * a node holding the namespace, so there is no hosted admitter.
    */
   async getNamespaceRouting(namespaceId) {
-    const body = await this.request("GET", `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/admitters`, {
+    const body = await this.request("GET", `/api/cloud/namespaces/${pathSegment(namespaceId)}/admitters`, {
       anonymous: true,
       headers: await this.routingProof(namespaceId)
     });
@@ -11673,7 +11740,7 @@ var CloudClient = class {
    * challenge somewhere this client cannot reach the key.
    */
   async getRoutingChallenge(namespaceId) {
-    const body = await this.request("GET", `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/challenge`, {
+    const body = await this.request("GET", `/api/cloud/namespaces/${pathSegment(namespaceId)}/challenge`, {
       anonymous: true
     });
     return {
@@ -11704,7 +11771,7 @@ var CloudClient = class {
    * the account from the certificate and refuses a mismatch.
    */
   async getAccountRelaysChallenge(accountId) {
-    const body = await this.request("GET", `/api/cloud/accounts/${encodeURIComponent(accountId)}/challenge`, {
+    const body = await this.request("GET", `/api/cloud/accounts/${pathSegment(accountId)}/challenge`, {
       anonymous: true
     });
     return {
@@ -11740,7 +11807,7 @@ var CloudClient = class {
       );
     }
     const challenge = await this.getAccountRelaysChallenge(accountId);
-    const body = await this.request("GET", `/api/cloud/accounts/${encodeURIComponent(accountId)}/relays`, {
+    const body = await this.request("GET", `/api/cloud/accounts/${pathSegment(accountId)}/relays`, {
       anonymous: true,
       headers: await routingProofHeaders(challenge, this.routingCredential)
     });
@@ -11864,7 +11931,7 @@ var CloudClient = class {
     const body = options.admitterAddrs === void 0 ? {} : { admitter_addrs: [...options.admitterAddrs] };
     return this.request(
       "POST",
-      `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/enable-ha`,
+      `/api/cloud/namespaces/${pathSegment(namespaceId)}/enable-ha`,
       { body }
     );
   }
@@ -11877,7 +11944,7 @@ var CloudClient = class {
   async enableFoundedNamespaceHa(namespaceId, ownershipProof) {
     return this.request(
       "POST",
-      `/api/cloud/me/namespaces/${encodeURIComponent(namespaceId)}/enable-ha`,
+      `/api/cloud/me/namespaces/${pathSegment(namespaceId)}/enable-ha`,
       { body: { groups: [], ownership_proof: ownershipProof } }
     );
   }
@@ -11914,7 +11981,7 @@ var CloudClient = class {
     try {
       return await this.request(
         "POST",
-        `/api/cloud/accounts/${encodeURIComponent(account)}/namespaces/${encodeURIComponent(namespace)}/enable-ha`,
+        `/api/cloud/accounts/${pathSegment(account)}/namespaces/${pathSegment(namespace)}/enable-ha`,
         { body: { ownership_proof: proof }, anonymous: true }
       );
     } catch (err) {
@@ -11939,7 +12006,7 @@ var CloudClient = class {
   async disableNamespaceHa(namespaceId) {
     return this.request(
       "POST",
-      `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/disable-ha`,
+      `/api/cloud/namespaces/${pathSegment(namespaceId)}/disable-ha`,
       { body: {} }
     );
   }
@@ -12079,7 +12146,7 @@ var CloudClient = class {
     const portal = options.portalUrl.replace(/\/+$/, "");
     const query = new URLSearchParams({
       "link-account": options.accountId,
-      "callback-url": options.callbackUrl
+      "callback-url": beginLinkState(options.accountId, options.callbackUrl)
     });
     return { url: `${portal}/?${query.toString()}`, accountId: options.accountId };
   }
@@ -12089,14 +12156,19 @@ var CloudClient = class {
    * Returns `{}` when there is nothing to read, so it is safe to call on every
    * load — which is how a redirected app finds out it has been sent back.
    *
+   * A grant is only returned when it answers a handoff this browser began, for the
+   * account that handoff named; anything else comes back as
+   * `error: 'unexpected_callback'`, because the redirect URL can be forwarded.
+   *
    * @param href defaults to the current location, when there is one.
    */
   static readAccountLinkCallback(href) {
     const source = href ?? (typeof window === "undefined" ? "" : window.location.href);
     if (!source) return {};
     let hash;
+    let search;
     try {
-      hash = new URL(source).hash;
+      ({ hash, search } = new URL(source));
     } catch {
       return {};
     }
@@ -12105,6 +12177,10 @@ var CloudClient = class {
     const accountId = params.get("account");
     const error = params.get("error");
     const out = {};
+    if (error) takeLinkState(search);
+    if (grant && takeLinkState(search)?.account !== accountId) {
+      return { error: "unexpected_callback" };
+    }
     if (grant) out.grant = grant;
     if (accountId) out.accountId = accountId;
     if (error) out.error = error;