@calimero-network/mero-js 25.3.1 → 25.3.3

package/README.md

@@ -210,10 +210,10 @@ import {
 } from '@calimero-network/mero-js';
 
 // 1. Enrol: the wallet certifies a device key this app generated and keeps.
-//    (first visit)  beginDeviceEnrolment({ walletUrl, devicePublicKey, kemPublicKey, returnTo, state });
+//    (first visit)  beginDeviceEnrolment({ walletUrl, devicePublicKey, kemPublicKey, returnTo });
 //    (on return)
-const callback = readEnrolmentCallback(window.location.href);
-const enrolled = await completeDeviceEnrolment({ ...callback, expectState: state });
+const callback = readEnrolmentCallback(); // null on an ordinary load
+const enrolled = await completeDeviceEnrolment({ ...callback, devicePublicKey, kemPublicKey });
 let session: DelegatedAccountSession = {
   account: enrolled.account, credential: enrolled.credential, deviceSecret, relayUrl: null,
 };

package/dist/auth/index.d.ts

@@ -14,12 +14,21 @@ export interface AuthLoginOptions {
     registryUrl?: string;
     packageVersion?: string;
 }
+export interface ParseAuthCallbackOptions {
+    /**
+     * Accept tokens this browser did not ask for, for a host that injects them itself
+     * (Calimero Desktop). Anyone who can open the page can then choose the session.
+     */
+    allowUnsolicited?: boolean;
+}
 /**
  * Parse an auth callback URL hash fragment.
- * Returns null if access_token is missing.
+ * Returns null if access_token is missing, or if the callback does not answer a
+ * login begun here with {@link buildAuthLoginUrl} (single use, expires).
  */
-export declare function parseAuthCallback(url: string): AuthCallbackResult | null;
+export declare function parseAuthCallback(url: string, options?: ParseAuthCallbackOptions): AuthCallbackResult | null;
 /**
  * Build the auth login URL for redirecting users to the node's auth page.
+ * Remembers the login so {@link parseAuthCallback} can match the callback to it.
  */
 export declare function buildAuthLoginUrl(nodeUrl: string, opts: AuthLoginOptions): string;

package/dist/auth/index.js

@@ -1,8 +1,12 @@
+import { beginState, takeState } from '../cloud/link-state.js';
+const PENDING_KEY = 'calimero.auth.login.pending';
+const STATE_PARAM = 'auth_state';
 /**
  * Parse an auth callback URL hash fragment.
- * Returns null if access_token is missing.
+ * Returns null if access_token is missing, or if the callback does not answer a
+ * login begun here with {@link buildAuthLoginUrl} (single use, expires).
  */
-export function parseAuthCallback(url) {
+export function parseAuthCallback(url, options = {}) {
     try {
         const hashIndex = url.indexOf('#');
         if (hashIndex === -1)
@@ -12,6 +16,10 @@ export function parseAuthCallback(url) {
         const accessToken = params.get('access_token');
         if (!accessToken)
             return null;
+        if (!options.allowUnsolicited && !takeState(PENDING_KEY, stateOf(url, hashIndex))) {
+            console.warn('[mero-js] ignoring auth callback tokens: they answer no login begun in this browser');
+            return null;
+        }
         return {
             accessToken,
             refreshToken: params.get('refresh_token') ?? '',
@@ -25,12 +33,21 @@ export function parseAuthCallback(url) {
         return null;
     }
 }
+function stateOf(url, hashIndex) {
+    const queryIndex = url.indexOf('?');
+    if (queryIndex === -1 || queryIndex > hashIndex)
+        return null;
+    return new URLSearchParams(url.substring(queryIndex + 1, hashIndex)).get(STATE_PARAM);
+}
 /**
  * Build the auth login URL for redirecting users to the node's auth page.
+ * Remembers the login so {@link parseAuthCallback} can match the callback to it.
  */
 export function buildAuthLoginUrl(nodeUrl, opts) {
+    const callback = new URL(opts.callbackUrl);
+    callback.searchParams.set(STATE_PARAM, beginState(PENDING_KEY, {}));
     const params = new URLSearchParams();
-    params.set('callback-url', opts.callbackUrl);
+    params.set('callback-url', callback.toString());
     if (opts.permissions && opts.permissions.length > 0) {
         params.set('permissions', opts.permissions.join(','));
     }

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

@@ -44,9 +44,10 @@
  * {@link completeDeviceEnrolment} does all three and throws on any of them,
  * before the caller has anything to store. What none of them establish is that
  * the account is the *person's* — anyone can mint a root offline and certify
- * any public key with it. That is what {@link DeviceEnrolmentOptions.state}
- * narrows: it proves the answer belongs to the request this app started, rather
- * than to a link someone sent.
+ * any public key with it, and a device key is public once enrolled. That is
+ * what the state narrows: {@link deviceEnrolmentUrl} remembers each request, and
+ * {@link completeDeviceEnrolment} refuses an answer to a request this browser did
+ * not start, rather than to a link someone sent.
  */
 import { type DeviceCredential } from '../device-cert/index.js';
 export interface DeviceEnrolmentOptions {
@@ -72,17 +73,6 @@ export interface DeviceEnrolmentOptions {
      * localhost — see {@link assertSafeReturnTo}.
      */
     returnTo: string;
-    /**
-     * An opaque value echoed back unchanged, to be compared on return.
-     *
-     * Optional, and worth setting: without it, any link that lands on the app's
-     * callback with a well-formed fragment enrols an account of the sender's
-     * choosing, and everything the app then does is filed under it. Store it
-     * where the round trip survives but another origin cannot read it —
-     * `sessionStorage` — and pass it to {@link completeDeviceEnrolment} as
-     * `expectState`.
-     */
-    state?: string;
 }
 /**
  * The URL to send a person to.
@@ -90,6 +80,9 @@ export interface DeviceEnrolmentOptions {
  * Built rather than documented as a string so the parameter names live in one
  * place: a wallet and an app that disagree about them fail as a blank consent
  * screen, which looks like an outage rather than a contract mismatch.
+ *
+ * Remembers the request under a fresh state the wallet echoes back, so
+ * {@link completeDeviceEnrolment} can match the answer to it.
  */
 export declare function deviceEnrolmentUrl(options: DeviceEnrolmentOptions): string;
 /** Send the person to the wallet to approve this device. Does not return. */
@@ -102,7 +95,7 @@ export interface DeviceEnrolmentCallback {
     account: string;
     /** The device id the wallet minted, 64 hex. */
     device: string;
-    /** Whatever {@link DeviceEnrolmentOptions.state} was sent, if any. */
+    /** The state the wallet echoed back from {@link deviceEnrolmentUrl}. */
     state?: string;
 }
 /**
@@ -131,15 +124,6 @@ export interface CompleteDeviceEnrolmentOptions extends DeviceEnrolmentCallback
     devicePublicKey: string;
     /** The delivery key asked about, 64 hex. Checked when supplied. */
     kemPublicKey?: string;
-    /**
-     * The {@link DeviceEnrolmentOptions.state} this app sent, if it sent one.
-     *
-     * Supplied and mismatched is a refusal. Not supplied is accepted — an app may
-     * legitimately have none to compare against, having been reloaded — and the
-     * gap is documented rather than closed here, because forcing it would break
-     * the app whose session storage the reload cleared.
-     */
-    expectState?: string;
 }
 /** A device this app may now sign as. */
 export interface EnrolledDevice {
@@ -160,6 +144,8 @@ export interface EnrolledDevice {
  * deliberate: the cheap local comparisons first, so a fragment aimed at the
  * wrong app is rejected without a signature verification, and the message names
  * what disagreed rather than reporting "invalid credential".
+ *
+ * The state is spent on the first call, so an answer is accepted at most once.
  */
 export declare function completeDeviceEnrolment(options: CompleteDeviceEnrolmentOptions): Promise<EnrolledDevice>;
 /**

package/dist/cloud/enrol-redirect.js

@@ -44,22 +44,28 @@
  * {@link completeDeviceEnrolment} does all three and throws on any of them,
  * before the caller has anything to store. What none of them establish is that
  * the account is the *person's* — anyone can mint a root offline and certify
- * any public key with it. That is what {@link DeviceEnrolmentOptions.state}
- * narrows: it proves the answer belongs to the request this app started, rather
- * than to a link someone sent.
+ * any public key with it, and a device key is public once enrolled. That is
+ * what the state narrows: {@link deviceEnrolmentUrl} remembers each request, and
+ * {@link completeDeviceEnrolment} refuses an answer to a request this browser did
+ * not start, rather than to a link someone sent.
  */
 import { verifyDeviceCredential, } from '../device-cert/index.js';
+import { beginState, takeState } from './link-state.js';
 /** Query parameters the wallet reads. Mirrors the cloud's `link-account` shape. */
 const DEVICE_PARAM = 'enrol-device';
 const KEM_PARAM = 'enrol-kem';
 const CALLBACK_PARAM = 'callback-url';
 const STATE_PARAM = 'state';
+const PENDING_KEY = 'calimero.device.enrol.pending';
 /**
  * The URL to send a person to.
  *
  * Built rather than documented as a string so the parameter names live in one
  * place: a wallet and an app that disagree about them fail as a blank consent
  * screen, which looks like an outage rather than a contract mismatch.
+ *
+ * Remembers the request under a fresh state the wallet echoes back, so
+ * {@link completeDeviceEnrolment} can match the answer to it.
  */
 export function deviceEnrolmentUrl(options) {
     assertHex(options.devicePublicKey, 'devicePublicKey');
@@ -70,8 +76,7 @@ export 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);
+    url.searchParams.set(STATE_PARAM, beginState(PENDING_KEY, {}));
     return url.toString();
 }
 /** Send the person to the wallet to approve this device. Does not return. */
@@ -97,6 +102,7 @@ export function readEnrolmentCallback(location = window.location) {
     const params = new URLSearchParams(location.hash.replace(/^#/, ''));
     const error = params.get('error');
     if (error) {
+        takeState(PENDING_KEY, params.get(STATE_PARAM));
         stripFragment();
         throw new Error(error === 'denied' || error === 'cancelled'
             ? 'the device was not approved at the wallet'
@@ -127,11 +133,13 @@ function stripFragment() {
  * deliberate: the cheap local comparisons first, so a fragment aimed at the
  * wrong app is rejected without a signature verification, and the message names
  * what disagreed rather than reporting "invalid credential".
+ *
+ * The state is spent on the first call, so an answer is accepted at most once.
  */
 export async function completeDeviceEnrolment(options) {
-    if (options.expectState !== undefined && options.expectState !== options.state) {
-        throw new Error('this enrolment answers a request this app did not make — the state it ' +
-            'carries is not the one sent');
+    if (!takeState(PENDING_KEY, options.state)) {
+        throw new Error('this enrolment answers a request this app did not make - start the ' +
+            'enrolment again from here');
     }
     const certificate = await verifyDeviceCredential(options.credential);
     if (certificate.signPublicKey !== normaliseHex(options.devicePublicKey)) {

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

@@ -1,8 +1,12 @@
 /**
- * Links this browser began, so a callback can be matched to one. `localStorage`,
+ * 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.
  */
 export declare const ACCOUNT_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. */

package/dist/cloud/link-state.js

@@ -1,5 +1,5 @@
 /**
- * Links this browser began, so a callback can be matched to one. `localStorage`,
+ * 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.
  */
 const KEY = "calimero.cloud.link.pending";
@@ -7,9 +7,9 @@ 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) {
+function readPending(key, now) {
     try {
-        const raw = localStorage.getItem(KEY);
+        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));
     }
@@ -17,39 +17,46 @@ function readPending(now) {
         return {};
     }
 }
-function writePending(pending) {
+function writePending(key, pending) {
     try {
-        localStorage.setItem(KEY, JSON.stringify(pending));
+        localStorage.setItem(key, JSON.stringify(pending));
     }
     catch {
-        // Storage blocked: the link cannot be matched later and fails closed.
+        // Storage blocked: the redirect cannot be matched later and fails closed.
     }
 }
+/** Remember `payload` in the `key` store under a fresh random state, and return the state. */
+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("");
+    pending[state] = { ...payload, expiresAt: now + LIFETIME_MS };
+    writePending(key, Object.fromEntries(Object.entries(pending).slice(-MAX_PENDING)));
+    return state;
+}
+/** Removes and returns what `state` was begun with, or null when this browser did not begin it. */
+export function takeState(key, state) {
+    const pending = readPending(key, Date.now());
+    if (!state || !Object.prototype.hasOwnProperty.call(pending, state))
+        return null;
+    const entry = pending[state];
+    delete pending[state];
+    writePending(key, pending);
+    return entry;
+}
 /** 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);
+    url.searchParams.set(STATE_PARAM, beginState(KEY, { account }));
     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;
+    return takeState(KEY, new URLSearchParams(search).get(STATE_PARAM));
 }
 /** The query with the link state removed, for rewriting the address bar. */
 export function withoutLinkState(search) {

package/dist/events/sse.d.ts

@@ -91,6 +91,14 @@ export declare class SseClient {
     onMigrationEvent(handler: (e: GroupMigrationEventData) => void): () => void;
     private emit;
     connect(): Promise<void>;
+    /**
+     * Whether `controller`'s connection is no longer the one this client holds:
+     * closed, or replaced by a later connect. Its abort lands asynchronously,
+     * after a `close()` + `connect()` has already cleared `closed`, so `closed`
+     * alone cannot tell; reporting it, and reconnecting for it, would abort the
+     * live connection, whose own abort would do the same, without end.
+     */
+    private superseded;
     private readStream;
     private handleMessage;
     subscribe(idsOrOpts: string[] | {

package/dist/events/sse.js

@@ -142,7 +142,8 @@ export class SseClient {
             return;
         }
         this.closed = false;
-        this.abortController = new AbortController();
+        const controller = new AbortController();
+        this.abortController = controller;
         try {
             const url = `${this.baseUrl}/sse`;
             const headers = {
@@ -152,7 +153,7 @@ export class SseClient {
             const proofAttached = carriesProof(headers);
             const response = await this.fetchImpl(url, {
                 headers,
-                signal: this.abortController.signal,
+                signal: controller.signal,
                 ...(proofAttached && { redirect: 'manual' }),
             });
             if (proofAttached)
@@ -174,8 +175,8 @@ export class SseClient {
             if (!response.body) {
                 throw new Error('SSE response has no body');
             }
-            this.readStream(response.body).catch((err) => {
-                if (this.closed)
+            this.readStream(response.body, controller).catch((err) => {
+                if (this.superseded(controller))
                     return;
                 const error = err instanceof Error ? err : new Error(String(err));
                 this.emit('error', error);
@@ -183,7 +184,7 @@ export class SseClient {
             });
         }
         catch (err) {
-            if (this.closed)
+            if (this.superseded(controller))
                 return;
             const error = err instanceof Error ? err : new Error(String(err));
             this.emit('error', error);
@@ -195,7 +196,17 @@ export class SseClient {
             this.scheduleReconnect();
         }
     }
-    async readStream(body) {
+    /**
+     * Whether `controller`'s connection is no longer the one this client holds:
+     * closed, or replaced by a later connect. Its abort lands asynchronously,
+     * after a `close()` + `connect()` has already cleared `closed`, so `closed`
+     * alone cannot tell; reporting it, and reconnecting for it, would abort the
+     * live connection, whose own abort would do the same, without end.
+     */
+    superseded(controller) {
+        return this.closed || controller.signal.aborted || this.abortController !== controller;
+    }
+    async readStream(body, controller) {
         const reader = body.getReader();
         const decoder = new TextDecoder();
         let buffer = '';
@@ -227,13 +238,13 @@ export class SseClient {
             }
         }
         catch (err) {
-            if (this.closed)
+            if (this.superseded(controller))
                 return;
             const error = err instanceof Error ? err : new Error(String(err));
             this.emit('error', error);
         }
         // Stream ended, reconnect
-        if (!this.closed) {
+        if (!this.superseded(controller)) {
             this.scheduleReconnect();
         }
     }