@calimero-network/mero-js 25.0.2 → 25.0.4

package/dist/account/account-admin.d.ts

@@ -29,10 +29,8 @@ export declare class NoRelayError extends Error {
  * cloud's routing, intersected with the invitation's signed admitters, so an
  * invitation the cloud routes to none of them can only fail in their hands.
  *
- * - `not-hosted` — the cloud serves the namespace on no node AND no relay is a
- *   member of it, so nothing admits a node-less claimant. A namespace with a
- *   relay in it is minted for even when the cloud routes it nowhere: the relay
- *   admits through its own `/admit`, and the invitation carries its address.
+ * - `not-hosted` - the cloud lists no node holding the namespace. A relay it
+ *   does not list cannot stand in: an address on the invitation is unsigned.
  * - `no-named-node` — the cloud's nodes are not among the admitters this
  *   invitation would name.
  */

package/dist/account/account-admin.js

@@ -26,17 +26,15 @@ export class NoRelayError extends Error {
  * cloud's routing, intersected with the invitation's signed admitters, so an
  * invitation the cloud routes to none of them can only fail in their hands.
  *
- * - `not-hosted` — the cloud serves the namespace on no node AND no relay is a
- *   member of it, so nothing admits a node-less claimant. A namespace with a
- *   relay in it is minted for even when the cloud routes it nowhere: the relay
- *   admits through its own `/admit`, and the invitation carries its address.
+ * - `not-hosted` - the cloud lists no node holding the namespace. A relay it
+ *   does not list cannot stand in: an address on the invitation is unsigned.
  * - `no-named-node` — the cloud's nodes are not among the admitters this
  *   invitation would name.
  */
 export class InvitationNotClaimableError extends Error {
     constructor(namespaceId, reason) {
         super(reason === 'not-hosted'
-            ? `nobody could claim an invitation to ${namespaceId} yet: the namespace is not hosted in the cloud and has no relay in it, so an invitee with no node has no relay to be admitted through. Link this account to your cloud user in the wallet and enable HA for the namespace, then invite.`
+            ? `nobody could claim an invitation to ${namespaceId} yet: the cloud lists no node holding the namespace, so an invitee with no node of their own has no relay to be admitted through.`
             : `nobody could claim an invitation to ${namespaceId}: the cloud routes to none of the relays or admins it would name as admitters`);
         this.namespaceId = namespaceId;
         this.reason = reason;
@@ -264,9 +262,6 @@ export function createAccountAdmin(input, deps = {}) {
             const relays = members
                 .filter((m) => m.role === 'RelayTee')
                 .map((m) => m.identity.toLowerCase());
-            // Where the claimant reaches an admitter when the cloud routes them to
-            // none: set only then, so a routed namespace stays the cloud's to route.
-            let admitterAddrs;
             if (routing) {
                 // Who the claimant's client will look for: the admitters this
                 // invitation names (the relays, else signGroupInvitation's admins).
@@ -281,19 +276,9 @@ export function createAccountAdmin(input, deps = {}) {
                     // Nothing learned: the claimant's own lookup will say what is wrong.
                 }
                 if (nodes !== null) {
-                    if (nodes.length === 0) {
-                        // The cloud routes a namespace only once its founder has linked
-                        // the account (HA). Unlinked, the namespace is still served by the
-                        // relay that founded it and serves this session, a RelayTee
-                        // member; its own `/admit` takes the join (measured on prod: 200,
-                        // where the cloud's lookup answered no nodes). The claimant's
-                        // client cannot find that relay through the cloud, so the
-                        // invitation says where it is.
-                        if (relays.length === 0 || !s.relayUrl)
-                            throw new InvitationNotClaimableError(namespaceId, 'not-hosted');
-                        admitterAddrs = [s.relayUrl];
-                    }
-                    else if (!nodes.some((n) => n.account !== null && named.has(n.account.toLowerCase()))) {
+                    if (nodes.length === 0)
+                        throw new InvitationNotClaimableError(namespaceId, 'not-hosted');
+                    if (!nodes.some((n) => n.account !== null && named.has(n.account.toLowerCase()))) {
                         throw new InvitationNotClaimableError(namespaceId, 'no-named-node');
                     }
                 }
@@ -303,7 +288,6 @@ export function createAccountAdmin(input, deps = {}) {
                 inviterAccount: s.account,
                 deviceSecret: s.deviceSecret,
                 ...(relays.length > 0 ? { admitters: relays } : {}),
-                ...(admitterAddrs ? { admitterAddrs } : {}),
                 members: members,
                 applicationId: info.targetApplicationId,
                 appKey: info.appKey,

package/dist/account/bootstrap-from-invitation.d.ts

@@ -20,16 +20,11 @@
  *
  * # Where the node URL comes from, in preference order
  *
- * 1. one passed in — an operator's, or one a future invitation carries. Core
- *    today emits only libp2p multiaddrs on an invitation (`resolve_admitter_addrs`)
- *    because a node cannot know the URL its admin API is proxied on, so there is
- *    nothing to read off the invitation yet and this is the seam for when there
- *    is;
+ * 1. one the caller passes in, such as an operator's or a local rig's;
  * 2. the cloud's `/api/cloud/namespaces/{ns}/admitters`, intersected with the
- *    invitation's signed `admitters` — see `resolveRelayFromInvitation`;
- * 3. an http(s) origin in the invitation's `admitter_addrs`, when the cloud
- *    routes the namespace to no node: the relay of a founder who never linked
- *    the account writes its own origin there when it mints.
+ *    invitation's signed `admitters`, see `resolveRelayFromInvitation`.
+ *
+ * Never from the invitation, signed or not: the inviter may be the attacker.
  *
  * # Nothing here is minted, weakened or worked around
  *
@@ -90,10 +85,8 @@ export interface BootstrapFromInvitationInput {
     /**
      * A node to present the join to, skipping the cloud lookup.
      *
-     * Use it when something already knows the node — an operator, a local rig, or
-     * an invitation that carries a claim URL once core emits one. Without it the
-     * cloud's admitters lookup answers, and the invitation's signed list is what
-     * narrows the answer.
+     * For a node the caller already knows (an operator's, a local rig); never one
+     * from the invitation. Without it the cloud's lookup answers, narrowed by the signed admitters.
      */
     readonly nodeUrl?: string;
     /** Point at a cloud other than the hosted manager. For local rigs. */

package/dist/account/bootstrap-from-invitation.js

@@ -20,16 +20,11 @@
  *
  * # Where the node URL comes from, in preference order
  *
- * 1. one passed in — an operator's, or one a future invitation carries. Core
- *    today emits only libp2p multiaddrs on an invitation (`resolve_admitter_addrs`)
- *    because a node cannot know the URL its admin API is proxied on, so there is
- *    nothing to read off the invitation yet and this is the seam for when there
- *    is;
+ * 1. one the caller passes in, such as an operator's or a local rig's;
  * 2. the cloud's `/api/cloud/namespaces/{ns}/admitters`, intersected with the
- *    invitation's signed `admitters` — see `resolveRelayFromInvitation`;
- * 3. an http(s) origin in the invitation's `admitter_addrs`, when the cloud
- *    routes the namespace to no node: the relay of a founder who never linked
- *    the account writes its own origin there when it mints.
+ *    invitation's signed `admitters`, see `resolveRelayFromInvitation`.
+ *
+ * Never from the invitation, signed or not: the inviter may be the attacker.
  *
  * # Nothing here is minted, weakened or worked around
  *
@@ -61,7 +56,6 @@ export async function bootstrapFromInvitation(input) {
             // separately: two sources for one fact is how an intersection ends up
             // being performed against the wrong list.
             admitters: input.invitation.invitation.admitters,
-            admitterAddrs: input.invitation.admitter_addrs,
             credential: input.credential.credential,
             deviceSecret: input.credential.deviceSecret,
             cloudBaseUrl: input.cloudBaseUrl,

package/dist/account/create-context.d.ts

@@ -89,7 +89,7 @@ export interface FoundedDelegatedNamespace {
     haError?: string;
 }
 /** What an app can tell a person whose account the cloud cannot place. */
-export declare const HA_ACCOUNT_NOT_LINKED_MESSAGE = "link this account to your cloud user in the wallet so invitees can find this namespace";
+export declare const HA_ACCOUNT_NOT_LINKED_MESSAGE = "link this account to your cloud user in the wallet so the cloud can host this namespace on its fleet";
 /**
  * What to tell a person for each refusal the cloud names, keyed by its code.
  * Every one leaves the namespace founded; only hosting was refused.

package/dist/account/create-context.js

@@ -197,7 +197,7 @@ async function attestedNodeKey(relay) {
         : "the relay's attestation was refused, so founding through it is not possible: it is not a signed locked-read-only release");
 }
 /** What an app can tell a person whose account the cloud cannot place. */
-export const HA_ACCOUNT_NOT_LINKED_MESSAGE = 'link this account to your cloud user in the wallet so invitees can find this namespace';
+export const HA_ACCOUNT_NOT_LINKED_MESSAGE = 'link this account to your cloud user in the wallet so the cloud can host this namespace on its fleet';
 /**
  * What to tell a person for each refusal the cloud names, keyed by its code.
  * Every one leaves the namespace founded; only hosting was refused.
@@ -226,9 +226,8 @@ function blockingNamespace(e) {
  * the namespace id) and the cloud bills the user it is linked to.
  *
  * Best-effort: the namespace exists whatever the cloud answers, so a refusal is
- * reported, never thrown. Without HA nothing in the cloud knows the namespace,
- * so an invitee cannot find its relay; hence the not-linked case gets a
- * sentence that says what to do.
+ * reported, never thrown. The cloud records the founding relay before its link
+ * gate, so invitees find the namespace either way; HA adds fleet hosting.
  */
 async function enableHaBestEffort(s, namespaceId, salt, relayUrl, deps) {
     try {

package/dist/account/join-with-node.d.ts

@@ -80,12 +80,8 @@ export interface JoinWithNodeInput {
     /**
      * The node to present the join to — its admin API origin.
      *
-     * The primary parameter, so all three sources of a node URL feed one method:
-     * one carried by the invitation (core emits only libp2p multiaddrs today —
-     * see `resolve_admitter_addrs`, a node cannot know the URL its admin API is
-     * proxied on — so this is the seam for when invitations carry a claim URL),
-     * one resolved from the cloud's `/admitters` lookup, and one an operator
-     * simply knows.
+     * Resolved from the cloud's `/admitters` lookup or supplied by the caller;
+     * never read off the invitation, signed or not: the inviter may be the attacker.
      */
     readonly nodeUrl: string;
     /**

package/dist/account/relay-from-invitation.d.ts

@@ -56,11 +56,8 @@ import { CloudClient } from '../cloud/index.js';
  *
  * - `admitters-lookup` — the cloud read itself failed (offline, 5xx, a refused
  *   routing proof). Nothing has been learned about the namespace.
- * - `no-nodes` — the read succeeded and the cloud lists nothing, and the
- *   invitation carries no http(s) address of an admitter either. The namespace
- *   has no fleet assignment, so there is no cloud node to admit through; the
- *   invitation's admitters are somebody's self-hosted or desktop node, which the
- *   cloud neither knows nor routes to.
+ * - `no-nodes` - the cloud lists no node to admit through. An address on the
+ *   invitation is not one: `admitter_addrs` is unsigned.
  * - `not-invited` — nodes serve the namespace, and the invitation names none of
  *   them. Terminal for this invitation: ask for a fresh one.
  * - `invited-unreachable` — a named node exists but cannot take a join now (no
@@ -78,13 +75,10 @@ export interface ResolvedInvitationRelay {
     readonly relayUrl: string;
     /** Where to POST the signed join — the cloud's own, never rebuilt when given. */
     readonly admitUrl: string;
-    /**
-     * The admitter's account: as the cloud reported it, or — for a relay the
-     * invitation itself named — the one admitter it names, when it names one.
-     */
+    /** The admitter's account, as the cloud reported it. */
     readonly admitterAccount: string | null;
-    /** The node's peer id as the cloud reported it; `null` for a relay the invitation named. */
-    readonly peerId: string | null;
+    /** The node's peer id, as the cloud reported it. */
+    readonly peerId: string;
     /**
      * Whether this node can also run delegated writes (`CAN_AUTHOR_ON_BEHALF`).
      *
@@ -95,11 +89,6 @@ export interface ResolvedInvitationRelay {
     readonly writable: boolean;
     /** Whether the chosen node's heartbeat for this namespace has lapsed. */
     readonly stale: boolean;
-    /**
-     * Who named this relay: the cloud's routing, or the invitation's own
-     * `admitter_addrs` when the cloud routed the namespace to no node.
-     */
-    readonly via: 'cloud' | 'invitation';
 }
 export interface RelayResolutionFailure {
     readonly ok: false;
@@ -120,15 +109,6 @@ export interface ResolveRelayFromInvitationInput {
      * here that means "nobody may admit", because an invitation cannot say that.
      */
     readonly admitters?: readonly string[];
-    /**
-     * The invitation's `admitter_addrs`: where its admitters are reached. Core
-     * emits libp2p multiaddrs here; an account minting through mero-react adds
-     * its relay's http(s) origin. Only the http(s) entries are of use to a
-     * browser, and only when the cloud routes the namespace to no node — the
-     * case of a namespace whose founder never linked the account, which the
-     * cloud does not route yet whose own relay admits.
-     */
-    readonly admitterAddrs?: readonly string[];
     /** The delegated credential — an `AccountProof<DeviceCert>`, hex. */
     readonly credential: string;
     /** The certified device's ed25519 signing secret, hex. */

package/dist/account/relay-from-invitation.js

@@ -64,21 +64,6 @@ export function normaliseAccount(account) {
     const bare = trimmed.startsWith('0x') ? trimmed.slice(2) : trimmed;
     return bare.length > 0 ? bare : null;
 }
-/** The http(s) origins among an invitation's admitter addresses, trailing slash dropped. */
-function httpAdmitterOrigins(addrs) {
-    const out = [];
-    for (const addr of addrs ?? []) {
-        try {
-            const url = new URL(addr);
-            if (url.protocol === 'http:' || url.protocol === 'https:')
-                out.push(addr.replace(/\/+$/, ''));
-        }
-        catch {
-            // A multiaddr, or nothing a browser can dial.
-        }
-    }
-    return out;
-}
 /** Whether the invitation's signed list names this node. */
 function isInvited(node, invited) {
     if (invited.size === 0)
@@ -121,28 +106,6 @@ export async function resolveRelayFromInvitation(input) {
         };
     }
     if (nodes.length === 0) {
-        // The cloud routes nothing, but the invitation may say where an admitter
-        // is: an account's relay writes its origin into `admitter_addrs` when it
-        // mints for a namespace the cloud does not host. The relay's `admit_join`
-        // re-verifies the invitation and its admitters, so nothing is loosened by
-        // knocking there; the account is the invitation's, when it names one.
-        const [relayUrl] = httpAdmitterOrigins(input.admitterAddrs);
-        if (relayUrl) {
-            const admitters = (input.admitters ?? []).map(normaliseAccount).filter((a) => a !== null);
-            return {
-                ok: true,
-                relayUrl,
-                admitUrl: `${relayUrl}/admin-api/namespaces/${input.namespaceId}/admit`,
-                admitterAccount: admitters.length === 1 ? admitters[0] : null,
-                peerId: null,
-                // The relay a founder's session runs through executes that founder's
-                // warrants, so it authors on behalf; the node's answer to the first
-                // write is the authoritative one, as for a cloud-routed node.
-                writable: true,
-                stale: false,
-                via: 'invitation',
-            };
-        }
         return {
             ok: false,
             step: 'no-nodes',
@@ -211,6 +174,5 @@ export async function resolveRelayFromInvitation(input) {
         // disagrees with trying it at all. Both mean the same thing to a caller:
         // this was attempted on advisory data, so if the admit fails that is why.
         stale: !chosen.fresh || advisory,
-        via: 'cloud',
     };
 }

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. */
@@ -624,9 +624,8 @@ export declare class CloudClient {
      * are answered together rather than across two endpoints — the per-context
      * read needs a context id a joiner does not yet have.
      *
-     * An empty `nodes` list is a state, not an error: a namespace with no fleet
-     * assignment has no cloud node, and the joiner must use one of the
-     * invitation's other admitters — another admin's node, or a self-hosted peer.
+     * An empty `nodes` list is a state, not an error: the cloud has no record of
+     * a node holding the namespace, so there is no hosted admitter.
      */
     getNamespaceRouting(namespaceId: string): Promise<CloudNamespaceRouting>;
     /**
@@ -877,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;
 }
@@ -404,9 +404,8 @@ export class CloudClient {
      * are answered together rather than across two endpoints — the per-context
      * read needs a context id a joiner does not yet have.
      *
-     * An empty `nodes` list is a state, not an error: a namespace with no fleet
-     * assignment has no cloud node, and the joiner must use one of the
-     * invitation's other admitters — another admin's node, or a self-hosted peer.
+     * An empty `nodes` list is a state, not an error: the cloud has no record of
+     * 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`, {
@@ -831,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 };
     }
@@ -841,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) {
@@ -848,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 {};
@@ -859,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}` : "";
+}