@calimero-network/mero-js 25.3.0 → 25.3.2

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.js

@@ -1,5 +1,7 @@
 import { isGroupMigrationEvent } from './group.js';
 import { AuthRevokedError, HTTPError } from '../http-client/index.js';
+import { carriesProof, refuseProofRedirect } from '../http-client/web-client.js';
+import { signedPath } from '../request-proof/authorizer.js';
 /**
  * `x-auth-error` reasons that mean the whole token family is gone, mirroring
  * the request path in `web-client.ts`. Anything else — `token_expired` above
@@ -143,13 +145,18 @@ export class SseClient {
         this.abortController = new AbortController();
         try {
             const url = `${this.baseUrl}/sse`;
+            const headers = {
+                ...(await this.authorize({ method: 'GET', path: signedPath(url) })),
+                'Accept': 'text/event-stream',
+            };
+            const proofAttached = carriesProof(headers);
             const response = await this.fetchImpl(url, {
-                headers: {
-                    ...(await this.authorize({ method: 'GET', path: new URL(url).pathname })),
-                    'Accept': 'text/event-stream',
-                },
+                headers,
                 signal: this.abortController.signal,
+                ...(proofAttached && { redirect: 'manual' }),
             });
+            if (proofAttached)
+                refuseProofRedirect(response, url);
             if (!response.ok) {
                 // Throw the same typed errors the request path throws. A bare
                 // `Error("SSE connection failed: 401")` forced callers to string-match
@@ -379,15 +386,20 @@ export class SseClient {
             // differ in key order, which fails as a refused credential rather than as
             // anything that names the real cause.
             const body = JSON.stringify({ id: this.sessionId, method, params });
+            const headers = {
+                ...(await this.authorize({ method: 'POST', path: signedPath(url), body })),
+                'Content-Type': 'application/json',
+            };
+            const proofAttached = carriesProof(headers);
             const response = await this.fetchImpl(url, {
                 method: 'POST',
-                headers: {
-                    ...(await this.authorize({ method: 'POST', path: new URL(url).pathname, body })),
-                    'Content-Type': 'application/json',
-                },
+                headers,
                 body,
                 signal: timeout.signal,
+                ...(proofAttached && { redirect: 'manual' }),
             });
+            if (proofAttached)
+                refuseProofRedirect(response, url);
             if (!response.ok) {
                 // The subscribe path used to report only the status. On the one failure
                 // that matters it is the whole of what the caller got: a revoked family

package/dist/http-client/http-types.d.ts

@@ -18,7 +18,7 @@ export interface Transport {
      */
     authorizeRequest?: (request: {
         method: string;
-        /** The path the node will see, query excluded. */
+        /** The path and query the node will see, as `signedPath` reads them. */
         path: string;
         body?: string | Uint8Array;
     }) => Promise<Record<string, string>>;

package/dist/http-client/web-client.d.ts

@@ -36,6 +36,13 @@ export declare class AuthRevokedError extends HTTPError {
     /** Value of the `x-auth-error` header, e.g. `token_reuse` or `token_revoked`. */
     reason: string, status: number, statusText: string, url: string, headers: Headers, bodyText?: string);
 }
+/** Whether `headers` carry a request proof, which must never follow a redirect. */
+export declare function carriesProof(headers: Record<string, string>): boolean;
+/**
+ * Throws when a proof-carrying request was answered with a redirect, which
+ * fetch reports as an opaque response with status 0 under redirect: 'manual'.
+ */
+export declare function refuseProofRedirect(response: Response, url: string): void;
 export declare class WebHttpClient implements HttpClient {
     private transport;
     private refreshTokenPromise;

package/dist/http-client/web-client.js

@@ -1,4 +1,6 @@
 import { combineSignals, createTimeoutSignal } from './signal-utils.js';
+import { signedPath } from '../request-proof/authorizer.js';
+import { REQUEST_PROOF_HEADER } from '../request-proof/request-proof.js';
 /**
  * `x-auth-error` reasons that mean the whole token family is gone.
  *
@@ -93,24 +95,36 @@ function headersToRecord(headers) {
     });
     return record;
 }
-// Web Standards HTTP client implementation
-/**
- * The path a node will verify a request signature against.
- *
- * `new URL` drops the query and keeps any prefix the base URL contributed,
- * which is exactly what reaches the server. The fallback covers a `url` that is
- * already relative — it cannot be parsed, and signing the whole string with its
- * query attached would be worse than signing the part before the `?`.
- */
-function pathForProof(url) {
+/** Runtimes disagree on sending a bare `?`, so the URL parser drops it once and
+ * the URL signed and the URL fetched are one string. */
+function withoutBareQuery(url) {
+    let parsed;
     try {
-        return new URL(url).pathname;
+        parsed = new URL(url, globalThis.location?.href);
     }
     catch {
-        const query = url.indexOf('?');
-        return query === -1 ? url : url.slice(0, query);
+        return url; // relative, with no page to resolve it against
     }
+    if (parsed.search === '')
+        parsed.search = '';
+    return parsed.href;
+}
+/** Whether `headers` carry a request proof, which must never follow a redirect. */
+export function carriesProof(headers) {
+    return Object.keys(headers).some((name) => name.toLowerCase() === REQUEST_PROOF_HEADER.toLowerCase());
 }
+/**
+ * Throws when a proof-carrying request was answered with a redirect, which
+ * fetch reports as an opaque response with status 0 under redirect: 'manual'.
+ */
+export function refuseProofRedirect(response, url) {
+    const redirected = response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400);
+    if (!redirected)
+        return;
+    // Status 0 marks a withheld response; its explanation is the body text.
+    throw new HTTPError(0, 'Redirect Not Followed', url, response.headers, `the node answered with a redirect; a request carrying ${REQUEST_PROOF_HEADER} is not followed to another location`);
+}
+// Web Standards HTTP client implementation
 export class WebHttpClient {
     constructor(transport) {
         this.transport = transport;
@@ -175,7 +189,7 @@ export class WebHttpClient {
     async makeRequest(path, init, retryCount = 0, requestStartTime) {
         // Maximum retry attempts to prevent infinite loops
         const MAX_RETRY_ATTEMPTS = 1;
-        const url = this.buildUrl(path);
+        const url = withoutBareQuery(this.buildUrl(path));
         // Track request start time for timeout calculation (only on first attempt)
         // Use per-request start time to avoid corruption from concurrent requests
         const startTime = requestStartTime ?? Date.now();
@@ -195,9 +209,7 @@ export class WebHttpClient {
         }
         const method = init?.method || 'GET';
         // A credential that commits to the request can only be produced here, where
-        // the method, the assembled path and the body are all known. The path comes
-        // from the URL rather than from `path`, because a base URL may carry a prefix
-        // (`…/admin-api`) that the node sees and a bare relative path would not sign.
+        // the method, the assembled path and query, and the body are all known.
         if (this.transport.authorizeRequest) {
             const body = init?.body;
             if (body !== undefined && typeof body !== 'string' && !(body instanceof Uint8Array)) {
@@ -207,7 +219,7 @@ export class WebHttpClient {
             }
             Object.assign(headersObj, await this.transport.authorizeRequest({
                 method,
-                path: new URL(url).pathname,
+                path: signedPath(url),
                 // Narrowed by the guard above; `BodyInit` is wider than what can be
                 // signed.
                 body: body,
@@ -281,24 +293,28 @@ export class WebHttpClient {
         // nor the body — and a proof commits to both. Signed AFTER the body is
         // settled above, so what is hashed is what is sent.
         //
-        // The path comes from the built URL's `pathname`, not from the `path`
-        // argument: that argument may carry a query string, and may be relative to
-        // a base URL that contributes its own prefix. The node verifies against the
-        // path it received, so the only safe source is the URL actually being
-        // fetched. A query string is deliberately not covered — core's `RequestSig`
-        // signs the path alone, and signing more here would fail every request.
+        // The path and query come from the built URL, not from the `path` argument,
+        // which may be relative to a base URL that contributes its own prefix.
         if (this.transport.getProof) {
             const proof = await this.transport.getProof({
                 method: requestInit.method ?? 'GET',
-                path: pathForProof(url),
+                path: signedPath(url),
                 body: requestInit.body,
             });
             if (proof) {
                 headersObj['X-Calimero-Proof'] = proof;
             }
         }
+        // fetch forwards custom headers across redirects, so a proof must never be
+        // sent anywhere but where it was signed for.
+        const proofAttached = carriesProof(headersObj);
+        if (proofAttached && requestInit.redirect !== 'error') {
+            requestInit.redirect = 'manual';
+        }
         try {
             const response = await this.transport.fetch(url, requestInit);
+            if (proofAttached)
+                refuseProofRedirect(response, url);
             if (!response.ok) {
                 const bodyText = await this.getBodyText(response);
                 const httpError = new HTTPError(response.status, response.statusText, url, response.headers, bodyText);