@calimero-network/mero-js 25.0.3 → 25.0.4

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,7 @@
 import { signAccountHaClaim } from './account-ownership.js';
 import { resolveRoot, resolveRootPair, signAccountLink, signAccountLogin, } from '../account/index.js';
 import { HTTPError } from '../http-client/web-client.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 +88,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;
 }
@@ -830,7 +830,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 +840,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 +851,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 +863,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}` : "";
+}