@calimero-network/mero-js 26.2.1 → 26.2.2

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

@@ -383,6 +383,10 @@ export interface AccountLinkCallback {
     grant?: string;
     /** The account the grant is for, as the portal echoed it. */
     accountId?: string;
+    /** The cloud login that consented. Show it before spending: anyone holding the handoff URL could have answered it. */
+    login?: string;
+    /** This browser's secret for the grant. Pass it to {@link CloudClient.linkAccountWithGrant}. */
+    verifier?: string;
     /** `'denied'` when the person cancelled, `'unexpected_callback'` for a grant this browser never asked for. */
     error?: string;
 }
@@ -869,7 +873,7 @@ export declare class CloudClient {
         accountId: string;
         /** Where to come back to. */
         callbackUrl: string;
-    }): AccountLinkHandoff;
+    }): Promise<AccountLinkHandoff>;
     /**
      * Read the portal's answer out of a callback URL's fragment.
      *
@@ -893,8 +897,9 @@ export declare class CloudClient {
      *
      * The signature is an ordinary account-link signature with the grant as the
      * nonce, so the same {@link signAccountLink} every other link path uses signs
-     * this one. Both halves are required: a grant without the key links nothing,
-     * which is what makes it safe to carry through a browser redirect.
+     * this one. The grant is bound to the verifier of the browser that asked for
+     * it, and is refused here, before the root signs, unless it carries that
+     * verifier's challenge and names this root's account.
      *
      * A `403` means the grant was bad, expired, already spent, or signed by a key
      * that names a different account; `409` that the account belongs to another
@@ -902,6 +907,8 @@ export declare class CloudClient {
      */
     linkAccountWithGrant(options: {
         grant: string;
+        /** The verifier {@link readAccountLinkCallback} returned with the grant. */
+        verifier: string;
         /** The root of the account the grant names, 64 hex. */
         rootSecret?: string;
         /**

package/dist/cloud/cloud-client.js

@@ -28,7 +28,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 { pathSegment } from '../http-client/path-segment.js';
-import { ACCOUNT_HEX, beginLinkState, takeLinkState } from './link-state.js';
+import { ACCOUNT_HEX, VERIFIER_HEX, beginLinkState, linkChallenge, linkGrantClaims, takeLinkVerifier, } from './link-state.js';
 import { routingProofHeaders, } from './routing-proof.js';
 /**
  * The hosted cloud's **API** when a caller names no other.
@@ -827,11 +827,13 @@ export class CloudClient {
      * Static, so it needs no client and no session: there is nothing to
      * authenticate as yet.
      */
-    static accountLinkHandoff(options) {
+    static async accountLinkHandoff(options) {
         const portal = options.portalUrl.replace(/\/+$/, '');
+        const { callbackUrl, challenge } = await beginLinkState(options.accountId, options.callbackUrl);
         const query = new URLSearchParams({
             'link-account': options.accountId,
-            'callback-url': beginLinkState(options.accountId, options.callbackUrl),
+            challenge,
+            'callback-url': callbackUrl,
         });
         return { url: `${portal}/?${query.toString()}`, accountId: options.accountId };
     }
@@ -865,12 +867,16 @@ export class CloudClient {
         const error = params.get('error');
         const out = {};
         if (error)
-            takeLinkState(search);
-        if (grant && takeLinkState(search)?.account !== accountId) {
-            return { error: 'unexpected_callback' };
-        }
-        if (grant)
+            takeLinkVerifier(search, null);
+        if (grant) {
+            const verifier = takeLinkVerifier(search, accountId);
+            const claims = linkGrantClaims(grant);
+            if (!verifier || claims?.account !== accountId)
+                return { error: 'unexpected_callback' };
             out.grant = grant;
+            out.login = claims.login;
+            out.verifier = verifier;
+        }
         if (accountId)
             out.accountId = accountId;
         if (error)
@@ -887,18 +893,31 @@ export class CloudClient {
      *
      * The signature is an ordinary account-link signature with the grant as the
      * nonce, so the same {@link signAccountLink} every other link path uses signs
-     * this one. Both halves are required: a grant without the key links nothing,
-     * which is what makes it safe to carry through a browser redirect.
+     * this one. The grant is bound to the verifier of the browser that asked for
+     * it, and is refused here, before the root signs, unless it carries that
+     * verifier's challenge and names this root's account.
      *
      * A `403` means the grant was bad, expired, already spent, or signed by a key
      * that names a different account; `409` that the account belongs to another
      * login; `402` that the plan is full.
      */
     async linkAccountWithGrant(options) {
+        if (typeof options.verifier !== 'string' || !VERIFIER_HEX.test(options.verifier)) {
+            throw new Error('no verifier for this grant - start the link again from this browser');
+        }
+        const claims = linkGrantClaims(options.grant);
+        if (claims?.challenge !== (await linkChallenge(options.verifier))) {
+            throw new Error('this grant was not issued to this link request - start the link again from this browser');
+        }
         const { signer, publicKey, accountId } = await resolveRootPair(options.rootSecret, options.signer);
+        if (claims.account !== accountId) {
+            throw new Error(`this grant is for account ${claims.account}, but the root here derives ` +
+                `${accountId} - it was minted for a different account`);
+        }
         const body = await this.request('POST', '/api/cloud/accounts/link', {
             body: {
                 grant: options.grant,
+                verifier: options.verifier,
                 root_public_key: publicKey,
                 signature: await signAccountLink({
                     signer,

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

@@ -8,19 +8,21 @@
  * signature, which only the holder can make. Neither side can do it alone.
  *
  * The cloud already implements its half: send a person to
- * `?link-account=<id>&callback-url=<url>`, it shows a consent screen and
- * redirects back with a **grant** — that login's sealed consent to link one
- * named account. This module is the missing other half, and it is deliberately
- * small: send them there, then spend what comes back.
+ * `?link-account=<id>&challenge=<sha256(verifier)>&callback-url=<url>`, it
+ * shows a consent screen and redirects back with a **grant** — that login's
+ * sealed consent to link one named account. This module is the missing other
+ * half, and it is deliberately small: send them there, then spend what comes
+ * back.
  *
  * ## Why a grant rather than a session
  *
- * A grant is spendable by anyone holding the account's root, and by nobody
- * else. That is what lets the page complete the link while holding **no cloud
- * session at all** — and it is why a wallet should never be handed one. A
- * session token is a credential for everything that login can do; a grant is a
- * credential for exactly one link, to exactly one account, sealed at the moment
- * the person read the id on screen and agreed to it.
+ * A grant is spendable only with the account's root and the verifier this
+ * browser kept when it began the link. That is what lets the page complete the
+ * link while holding **no cloud session at all** - and it is why a wallet
+ * should never be handed one. A session token is a credential for everything
+ * that login can do; a grant is a credential for exactly one link, to exactly
+ * one account, sealed at the moment the person read the id on screen and
+ * agreed to it.
  *
  * ## The account id is chosen by us and read by them
  *
@@ -45,15 +47,22 @@ export interface BeginCloudLinkOptions {
     /** The cloud's web origin. Defaults to the hosted one. */
     cloudWebUrl?: string;
 }
-/** The consent URL to send a person to. Remembers the link so the callback can be matched. */
-export declare function cloudLinkUrl(options: BeginCloudLinkOptions): string;
+/**
+ * The consent URL to send a person to. Remembers the link, and the verifier its
+ * grant will be bound to, so only this browser can match the callback and spend it.
+ */
+export declare function cloudLinkUrl(options: BeginCloudLinkOptions): Promise<string>;
 /** Send the person to the cloud to consent. Does not return. */
-export declare function beginCloudLink(options: BeginCloudLinkOptions): never;
+export declare function beginCloudLink(options: BeginCloudLinkOptions): Promise<never>;
 /** What came back in the fragment, if anything. */
 export interface CloudLinkCallback {
     grant: string;
     /** The account the cloud sealed into the grant. */
     account: string;
+    /** The cloud login that consented. Show it before spending: anyone holding the consent URL could have answered it. */
+    login: string;
+    /** This browser's secret for the grant, kept from the redirect. Spend it with the grant. */
+    verifier: string;
 }
 /**
  * Read a grant out of the current URL fragment, and strip it.

package/dist/cloud/link-redirect.js

@@ -8,19 +8,21 @@
  * signature, which only the holder can make. Neither side can do it alone.
  *
  * The cloud already implements its half: send a person to
- * `?link-account=<id>&callback-url=<url>`, it shows a consent screen and
- * redirects back with a **grant** — that login's sealed consent to link one
- * named account. This module is the missing other half, and it is deliberately
- * small: send them there, then spend what comes back.
+ * `?link-account=<id>&challenge=<sha256(verifier)>&callback-url=<url>`, it
+ * shows a consent screen and redirects back with a **grant** — that login's
+ * sealed consent to link one named account. This module is the missing other
+ * half, and it is deliberately small: send them there, then spend what comes
+ * back.
  *
  * ## Why a grant rather than a session
  *
- * A grant is spendable by anyone holding the account's root, and by nobody
- * else. That is what lets the page complete the link while holding **no cloud
- * session at all** — and it is why a wallet should never be handed one. A
- * session token is a credential for everything that login can do; a grant is a
- * credential for exactly one link, to exactly one account, sealed at the moment
- * the person read the id on screen and agreed to it.
+ * A grant is spendable only with the account's root and the verifier this
+ * browser kept when it began the link. That is what lets the page complete the
+ * link while holding **no cloud session at all** - and it is why a wallet
+ * should never be handed one. A session token is a credential for everything
+ * that login can do; a grant is a credential for exactly one link, to exactly
+ * one account, sealed at the moment the person read the id on screen and
+ * agreed to it.
  *
  * ## The account id is chosen by us and read by them
  *
@@ -32,19 +34,24 @@
  */
 import { CloudClient } from './cloud-client.js';
 import { resolveRoot } from '../account/account.js';
-import { beginLinkState, takeLinkState, withoutLinkState } from './link-state.js';
+import { beginLinkState, linkGrantClaims, takeLinkVerifier, 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. Remembers the link so the callback can be matched. */
-export function cloudLinkUrl(options) {
+/**
+ * The consent URL to send a person to. Remembers the link, and the verifier its
+ * grant will be bound to, so only this browser can match the callback and spend it.
+ */
+export async function cloudLinkUrl(options) {
     const url = new URL(options.cloudWebUrl ?? DEFAULT_CLOUD_WEB_URL);
+    const { callbackUrl, challenge } = await beginLinkState(options.accountId, options.returnTo);
     url.searchParams.set('link-account', options.accountId);
-    url.searchParams.set('callback-url', beginLinkState(options.accountId, options.returnTo));
+    url.searchParams.set('challenge', challenge);
+    url.searchParams.set('callback-url', callbackUrl);
     return url.toString();
 }
 /** Send the person to the cloud to consent. Does not return. */
-export function beginCloudLink(options) {
-    window.location.assign(cloudLinkUrl(options));
+export async function beginCloudLink(options) {
+    window.location.assign(await cloudLinkUrl(options));
     // `assign` does not stop execution, and a caller that kept going would act on
     // a page already being replaced.
     throw new Error('redirecting to the cloud to authorise this link');
@@ -60,7 +67,7 @@ export function readCloudLinkCallback(location = window.location) {
     const params = new URLSearchParams(location.hash.replace(/^#/, ''));
     const error = params.get('error');
     if (error) {
-        takeLinkState(location.search ?? '');
+        takeLinkVerifier(location.search ?? '', null);
         stripFragment();
         throw new Error(error === 'denied'
             ? 'the account link was declined at the cloud'
@@ -70,14 +77,16 @@ export function readCloudLinkCallback(location = window.location) {
     const account = params.get('account');
     if (!grant || !account)
         return null;
-    if (takeLinkState(location.search ?? '')?.account !== account) {
+    const verifier = takeLinkVerifier(location.search ?? '', account);
+    const claims = linkGrantClaims(grant);
+    if (!verifier || claims?.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();
-    return { grant, account };
+    return { grant, account, login: claims.login, verifier };
 }
 function stripFragment() {
     if (typeof history === 'undefined' || !history.replaceState)
@@ -104,5 +113,9 @@ export async function completeCloudLink(options) {
         cloudBaseUrl: options.cloudBaseUrl,
         fetch: options.fetch,
     });
-    return cloud.linkAccountWithGrant({ grant: options.grant, signer: root.signer });
+    return cloud.linkAccountWithGrant({
+        grant: options.grant,
+        verifier: options.verifier,
+        signer: root.signer,
+    });
 }

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

@@ -3,15 +3,34 @@
  * not `sessionStorage`: consent opens in a `noopener` tab with empty session storage.
  */
 export declare const ACCOUNT_HEX: RegExp;
+export declare const VERIFIER_HEX: RegExp;
 /** Remember `payload` in the `key` store under a fresh random state, and return the state. */
 export declare function beginState<T extends object>(key: string, payload: T): string;
 /** Removes and returns what `state` was begun with, or null when this browser did not begin it. */
 export declare function takeState<T extends object>(key: string, state: string | null | undefined): T | null;
-/** 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): {
+/** What a link grant claims, read without its seal, which only the cloud can check. */
+export interface LinkGrantClaims {
+    /** The cloud login that consented. */
+    login: string;
     account: string;
-} | null;
+    challenge: string;
+}
+/** The challenge a verifier commits to: sha256 of its bytes, hex. */
+export declare function linkChallenge(verifier: string): Promise<string>;
+/**
+ * Remember a link for `account` under a fresh verifier. Returns `returnTo`
+ * carrying its state, and the challenge to send the cloud in place of the verifier.
+ */
+export declare function beginLinkState(account: string, returnTo: string): Promise<{
+    callbackUrl: string;
+    challenge: string;
+}>;
+/**
+ * Removes the link a callback answers and returns its verifier, or null when
+ * this browser did not begin a link for `account` with this state.
+ */
+export declare function takeLinkVerifier(search: string, account: string | null): string | null;
+/** The claims of a link grant, or null when `grant` is not one. */
+export declare function linkGrantClaims(grant: string): LinkGrantClaims | 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

@@ -2,11 +2,15 @@
  * Redirects this browser began, so a callback can be matched to one. `localStorage`,
  * not `sessionStorage`: consent opens in a `noopener` tab with empty session storage.
  */
+import { hex } from "../crypto/internal.js";
 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
+const VERIFIER_BYTES = 32; // the cloud refuses any other length
+export const VERIFIER_HEX = /^[0-9a-f]{64}$/;
+const LINK_GRANT_USE = "account-link-grant";
 function readPending(key, now) {
     try {
         const raw = localStorage.getItem(key);
@@ -29,8 +33,7 @@ function writePending(key, pending) {
 export function beginState(key, payload) {
     const now = Date.now();
     const pending = readPending(key, now);
-    const bytes = crypto.getRandomValues(new Uint8Array(16));
-    const state = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+    const state = hex(crypto.getRandomValues(new Uint8Array(16)));
     pending[state] = { ...payload, expiresAt: now + LIFETIME_MS };
     writePending(key, Object.fromEntries(Object.entries(pending).slice(-MAX_PENDING)));
     return state;
@@ -45,18 +48,52 @@ export function takeState(key, state) {
     writePending(key, pending);
     return entry;
 }
-/** Remember a link for `account` and return `returnTo` carrying its state. */
-export function beginLinkState(account, returnTo) {
+/** The challenge a verifier commits to: sha256 of its bytes, hex. */
+export async function linkChallenge(verifier) {
+    const bytes = Uint8Array.from(verifier.match(/../g) ?? [], (b) => parseInt(b, 16));
+    return hex(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)));
+}
+/**
+ * Remember a link for `account` under a fresh verifier. Returns `returnTo`
+ * carrying its state, and the challenge to send the cloud in place of the verifier.
+ */
+export async function beginLinkState(account, returnTo) {
     if (!ACCOUNT_HEX.test(account)) {
         throw new Error("accountId must be 64 lowercase hex characters");
     }
     const url = new URL(returnTo);
-    url.searchParams.set(STATE_PARAM, beginState(KEY, { account }));
-    return url.toString();
+    const verifier = hex(crypto.getRandomValues(new Uint8Array(VERIFIER_BYTES)));
+    const challenge = await linkChallenge(verifier);
+    url.searchParams.set(STATE_PARAM, beginState(KEY, { account, verifier }));
+    return { callbackUrl: url.toString(), challenge };
+}
+/**
+ * Removes the link a callback answers and returns its verifier, or null when
+ * this browser did not begin a link for `account` with this state.
+ */
+export function takeLinkVerifier(search, account) {
+    const pending = takeState(KEY, new URLSearchParams(search).get(STATE_PARAM));
+    if (!pending || pending.account !== account)
+        return null;
+    return typeof pending.verifier === "string" && VERIFIER_HEX.test(pending.verifier)
+        ? pending.verifier
+        : null;
 }
-/** Removes and returns the link a callback answers, or null when this browser did not begin it. */
-export function takeLinkState(search) {
-    return takeState(KEY, new URLSearchParams(search).get(STATE_PARAM));
+/** The claims of a link grant, or null when `grant` is not one. */
+export function linkGrantClaims(grant) {
+    try {
+        const body = grant.split(".")[0].replace(/-/g, "+").replace(/_/g, "/");
+        const claims = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(body), (c) => c.charCodeAt(0))));
+        const { use, sub, acc, chal } = claims;
+        if (use !== LINK_GRANT_USE)
+            return null;
+        if (typeof sub !== "string" || typeof acc !== "string" || typeof chal !== "string")
+            return null;
+        return { login: sub, account: acc, challenge: chal };
+    }
+    catch {
+        return null;
+    }
 }
 /** The query with the link state removed, for rewriting the address bar. */
 export function withoutLinkState(search) {