@calimero-network/mero-js 25.0.3 → 25.0.5

package/dist/auth-api/auth-client.js

@@ -1,3 +1,4 @@
+import { pathSegment } from '../http-client/path-segment.js';
 export class AuthApiClient {
     constructor(httpClient) {
         this.httpClient = httpClient;
@@ -89,7 +90,7 @@ export class AuthApiClient {
         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() {
@@ -103,14 +104,14 @@ export class AuthApiClient {
         return this.httpClient.post('/admin/client-key', request);
     }
     async deleteClientKey(keyId, clientId) {
-        return this.httpClient.delete(`/admin/keys/${keyId}/clients/${clientId}`);
+        return this.httpClient.delete(`/admin/keys/${pathSegment(keyId)}/clients/${pathSegment(clientId)}`);
     }
     // Permission Management Endpoints
     async getKeyPermissions(keyId) {
-        return this.httpClient.get(`/admin/keys/${keyId}/permissions`);
+        return this.httpClient.get(`/admin/keys/${pathSegment(keyId)}/permissions`);
     }
     async updateKeyPermissions(keyId, changes) {
         // Core expects an { add, remove } delta, not a { permissions } replacement.
-        return this.httpClient.put(`/admin/keys/${keyId}/permissions`, { add: changes.add, remove: changes.remove });
+        return this.httpClient.put(`/admin/keys/${pathSegment(keyId)}/permissions`, { add: changes.add, remove: changes.remove });
     }
 }

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

@@ -383,7 +383,7 @@ export interface AccountLinkCallback {
     grant?: string;
     /** The account the grant is for, as the portal echoed it. */
     accountId?: string;
-    /** `'denied'` when the person cancelled. Absent on success. */
+    /** `'denied'` when the person cancelled, `'unexpected_callback'` for a grant this browser never asked for. */
     error?: string;
 }
 /** A single-use challenge for an account root to sign itself in with. */
@@ -876,6 +876,10 @@ export declare class CloudClient {
      * 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?: string): AccountLinkCallback;

package/dist/cloud/cloud-client.js

@@ -27,6 +27,8 @@
 import { signAccountHaClaim } from './account-ownership.js';
 import { resolveRoot, resolveRootPair, signAccountLink, signAccountLogin, } from '../account/index.js';
 import { HTTPError } from '../http-client/web-client.js';
+import { pathSegment } from '../http-client/path-segment.js';
+import { ACCOUNT_HEX, beginLinkState, takeLinkState } from './link-state.js';
 import { routingProofHeaders, } from './routing-proof.js';
 /**
  * The hosted cloud's **API** when a caller names no other.
@@ -87,7 +89,6 @@ function joinOf(row) {
         reportedAt: typeof join.reported_at === 'string' ? join.reported_at : null,
     };
 }
-const ACCOUNT_HEX = /^[0-9a-f]{64}$/;
 function accountHexOrNull(value) {
     return typeof value === 'string' && ACCOUNT_HEX.test(value) ? value : null;
 }
@@ -352,7 +353,7 @@ export class CloudClient {
      * monotonic sequence on it.
      */
     async getNamespaceRelays(namespaceId) {
-        const body = await this.request('GET', `/api/cloud/me/namespaces/${encodeURIComponent(namespaceId)}/relays`);
+        const body = await this.request('GET', `/api/cloud/me/namespaces/${pathSegment(namespaceId)}/relays`);
         return (body.relays ?? []).map((row) => {
             const relayUrl = row.relay_url ?? null;
             const executorAccount = row.executor_account ?? null;
@@ -408,7 +409,7 @@ export class CloudClient {
      * 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),
         });
@@ -449,7 +450,7 @@ export class CloudClient {
      * 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 {
@@ -481,7 +482,7 @@ export class CloudClient {
      * 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 {
@@ -516,7 +517,7 @@ export class CloudClient {
                 'certificate and its signing secret, since this read is proven by the device, not by a session.');
         }
         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),
         });
@@ -633,7 +634,7 @@ export class CloudClient {
         const body = options.admitterAddrs === undefined
             ? {}
             : { admitter_addrs: [...options.admitterAddrs] };
-        return this.request('POST', `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/enable-ha`, { body });
+        return this.request('POST', `/api/cloud/namespaces/${pathSegment(namespaceId)}/enable-ha`, { body });
     }
     /**
      * Enable HA for a namespace this ACCOUNT founded through a relay, with the
@@ -642,7 +643,7 @@ export class CloudClient {
      * 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 } });
+        return this.request('POST', `/api/cloud/me/namespaces/${pathSegment(namespaceId)}/enable-ha`, { body: { groups: [], ownership_proof: ownershipProof } });
     }
     /**
      * Enable HA for a namespace this account founded, with **no cloud session**.
@@ -677,7 +678,7 @@ export class CloudClient {
         const account = options.accountId.toLowerCase();
         const namespace = options.namespaceId.toLowerCase();
         try {
-            return await this.request('POST', `/api/cloud/accounts/${encodeURIComponent(account)}/namespaces/${encodeURIComponent(namespace)}/enable-ha`, { body: { ownership_proof: proof }, anonymous: true });
+            return await this.request('POST', `/api/cloud/accounts/${pathSegment(account)}/namespaces/${pathSegment(namespace)}/enable-ha`, { body: { ownership_proof: proof }, anonymous: true });
         }
         catch (err) {
             if (err instanceof HTTPError && ACCOUNT_HA_REFUSALS[err.status]) {
@@ -699,7 +700,7 @@ export class CloudClient {
      * billing flip.
      */
     async disableNamespaceHa(namespaceId) {
-        return this.request('POST', `/api/cloud/namespaces/${encodeURIComponent(namespaceId)}/disable-ha`, { body: {} });
+        return this.request('POST', `/api/cloud/namespaces/${pathSegment(namespaceId)}/disable-ha`, { body: {} });
     }
     /**
      * The node assigned to the signed-in user, or `null`.
@@ -830,7 +831,7 @@ export class CloudClient {
         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 };
     }
@@ -840,6 +841,10 @@ export class CloudClient {
      * 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) {
@@ -847,8 +852,9 @@ export class CloudClient {
         if (!source)
             return {};
         let hash;
+        let search;
         try {
-            hash = new URL(source).hash;
+            ({ hash, search } = new URL(source));
         }
         catch {
             return {};
@@ -858,6 +864,11 @@ export class CloudClient {
         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)

package/dist/cloud/link-redirect.d.ts

@@ -45,7 +45,7 @@ export interface BeginCloudLinkOptions {
     /** The cloud's web origin. Defaults to the hosted one. */
     cloudWebUrl?: string;
 }
-/** The consent URL to send a person to. */
+/** The consent URL to send a person to. Remembers the link so the callback can be matched. */
 export declare function cloudLinkUrl(options: BeginCloudLinkOptions): string;
 /** Send the person to the cloud to consent. Does not return. */
 export declare function beginCloudLink(options: BeginCloudLinkOptions): never;
@@ -59,11 +59,12 @@ export interface CloudLinkCallback {
  * Read a grant out of the current URL fragment, and strip it.
  *
  * Returns `null` when this is an ordinary page load, so a caller can run it
- * unconditionally at startup. Throws when the person declined, because that is
- * an outcome the app has to show rather than a state to wait in.
+ * unconditionally at startup. Throws when declined or when this browser did not
+ * begin the link.
  */
 export declare function readCloudLinkCallback(location?: {
     hash: string;
+    search?: string;
 }): CloudLinkCallback | null;
 export interface CompleteCloudLinkOptions extends CloudLinkCallback {
     /** The account root — a 64-hex secret, or a Signer over a key you cannot read. */

package/dist/cloud/link-redirect.js

@@ -32,16 +32,14 @@
  */
 import { CloudClient } from './cloud-client.js';
 import { resolveRoot } from '../account/account.js';
+import { beginLinkState, takeLinkState, withoutLinkState } from './link-state.js';
 /** Where the consent screen lives. The web app, not the manager API. */
 const DEFAULT_CLOUD_WEB_URL = 'https://cloud.calimero.network';
-/** The consent URL to send a person to. */
+/** The consent URL to send a person to. Remembers the link so the callback can be matched. */
 export 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();
 }
 /** Send the person to the cloud to consent. Does not return. */
@@ -55,13 +53,14 @@ export function beginCloudLink(options) {
  * Read a grant out of the current URL fragment, and strip it.
  *
  * Returns `null` when this is an ordinary page load, so a caller can run it
- * unconditionally at startup. Throws when the person declined, because that is
- * an outcome the app has to show rather than a state to wait in.
+ * unconditionally at startup. Throws when declined or when this browser did not
+ * begin the link.
  */
 export function readCloudLinkCallback(location = window.location) {
     const params = new URLSearchParams(location.hash.replace(/^#/, ''));
     const error = params.get('error');
     if (error) {
+        takeLinkState(location.search ?? '');
         stripFragment();
         throw new Error(error === 'denied'
             ? 'the account link was declined at the cloud'
@@ -71,6 +70,10 @@ export function readCloudLinkCallback(location = window.location) {
     const account = params.get('account');
     if (!grant || !account)
         return null;
+    if (takeLinkState(location.search ?? '')?.account !== account) {
+        stripFragment();
+        throw new Error('this account link answers a request this browser did not make - start the link again from here');
+    }
     // Consumed once. Leaving it in the bar means a reload replays a spent grant
     // and reports a confusing failure instead of the link that already worked.
     stripFragment();
@@ -79,7 +82,7 @@ export function readCloudLinkCallback(location = window.location) {
 function stripFragment() {
     if (typeof history === 'undefined' || !history.replaceState)
         return;
-    history.replaceState(null, '', location.pathname + location.search);
+    history.replaceState(null, '', location.pathname + withoutLinkState(location.search));
 }
 /**
  * Spend the grant: sign it with the root and hand it back to the cloud.

package/dist/cloud/link-state.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Links this browser began, so a callback can be matched to one. `localStorage`,
+ * not `sessionStorage`: consent opens in a `noopener` tab with empty session storage.
+ */
+export declare const ACCOUNT_HEX: RegExp;
+/** Remember a link for `account` and return `returnTo` carrying its state. */
+export declare function beginLinkState(account: string, returnTo: string): string;
+/** Removes and returns the link a callback answers, or null when this browser did not begin it. */
+export declare function takeLinkState(search: string): {
+    account: string;
+} | null;
+/** The query with the link state removed, for rewriting the address bar. */
+export declare function withoutLinkState(search: string): string;

package/dist/cloud/link-state.js

@@ -0,0 +1,60 @@
+/**
+ * Links this browser began, so a callback can be matched to one. `localStorage`,
+ * not `sessionStorage`: consent opens in a `noopener` tab with empty session storage.
+ */
+const KEY = "calimero.cloud.link.pending";
+const STATE_PARAM = "link_state";
+const LIFETIME_MS = 10 * 60 * 1000; // a grant lives 5 minutes, plus time to consent
+export const ACCOUNT_HEX = /^[0-9a-f]{64}$/;
+const MAX_PENDING = 20; // bounds storage when a page builds a consent URL on every render
+function readPending(now) {
+    try {
+        const raw = localStorage.getItem(KEY);
+        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(KEY, JSON.stringify(pending));
+    }
+    catch {
+        // Storage blocked: the link cannot be matched later and fails closed.
+    }
+}
+/** Remember a link for `account` and return `returnTo` carrying its state. */
+export 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();
+}
+/** Removes and returns the link a callback answers, or null when this browser did not begin it. */
+export 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;
+}
+/** The query with the link state removed, for rewriting the address bar. */
+export function withoutLinkState(search) {
+    const params = new URLSearchParams(search);
+    params.delete(STATE_PARAM);
+    const rest = params.toString();
+    return rest ? `?${rest}` : "";
+}

package/dist/http-client/path-segment.d.ts

@@ -0,0 +1 @@
+export declare function pathSegment(id: string): string;

package/dist/http-client/path-segment.js

@@ -0,0 +1,8 @@
+// encodeURIComponent leaves "." and ".." intact and URL parsers collapse them,
+// so those (and the empty id, which names the collection route) are refused.
+export function pathSegment(id) {
+    if (id === '' || id === '.' || id === '..') {
+        throw new TypeError(`invalid request path segment: ${JSON.stringify(id)}`);
+    }
+    return encodeURIComponent(id);
+}