@calimero-network/mero-js 29.15.0 → 29.16.0

package/dist/runtime/transport.js

@@ -0,0 +1,576 @@
+/**
+ * The runtime every route of a Calimero node is sent through: the part of
+ * this client that is not a route.
+ *
+ * A route layer (the hand-written {@link CalimeroClient} today; one generated
+ * from the node's OpenAPI document later) knows a method, a path and what the
+ * route takes and answers. Everything else is here, behind one call,
+ * {@link Transport.request}:
+ *
+ * - the sealed channel to each node, opened only after the node's attestation
+ *   passed the caller's policy (`../sealed`, `../cloud-v2/attestation`);
+ * - the credential (an API key or a session), and the session's refresh when a
+ *   node answers `401` to it;
+ * - moving to another node of the cluster on `421 WRONG_NODE`, and failing
+ *   over when one stays unavailable to a call or a view (D70 retries);
+ * - the `412 CONFIRM_REQUIRED` step-up: the passkey's assertion over the
+ *   node's challenge, sent with the same body again;
+ * - error mapping (a refusal is a typed {@link CalimeroError}) and
+ *   server-sent event decoding.
+ *
+ * Paths are relative to the node (`apps/{app}/intents`, a leading `/` is
+ * dropped); {@link routePath} fills a path template with encoded segments.
+ */
+import { SealedTransportError, createSealedFetch } from '../sealed/sealed.js';
+import { fetchAttestedKey } from '../cloud-v2/attestation.js';
+import { orderNodes, readDirectory } from '../cloud-v2/directory.js';
+import { CalimeroError, ConfirmCancelled, ConfirmPromptBlocked, ConfirmRequired, LoginRequired, UnavailableError, WrongNode, errorFrom, } from '../cloud-v2/errors.js';
+import { b64url, fromB64url } from '../cloud-v2/passkey.js';
+export const DEFAULT_RETRY = { retries: 6, baseDelayMs: 200, maxDelayMs: 2000 };
+/** The backoff before retry `retry` (0 for the first): `baseDelayMs` doubling, at most `maxDelayMs`. */
+export function retryDelayMs(retry, options) {
+    return Math.min(options.baseDelayMs * 2 ** retry, options.maxDelayMs);
+}
+/**
+ * The user verification a confirmation asks the passkey for: what the node's
+ * `412` details name, if it names one WebAuthn knows, else `fallback` (the
+ * flow's own requirement: `required` for a step-up, which the node takes only
+ * with the user verified; `preferred` for the sign-up confirmation, which it
+ * takes with the user present).
+ */
+function userVerificationOf(named, fallback) {
+    return named === 'required' || named === 'preferred' || named === 'discouraged' ? named : fallback;
+}
+/**
+ * What a failed confirmation prompt means to the caller. The browser or a
+ * password manager refusing to show the prompt (the page not focused because
+ * an extension's popup still holds focus, or another prompt still open) is
+ * {@link ConfirmPromptBlocked}; the user dismissing it (`NotAllowedError`, or
+ * `AbortError` when it was aborted) is {@link ConfirmCancelled}; anything
+ * else is a real failure, passed through.
+ */
+function promptFailure(error) {
+    const e = error;
+    const name = e?.name;
+    const message = typeof e?.message === 'string' ? e.message : '';
+    if (name === 'InvalidStateError' || /not focused|already pending/i.test(message)) {
+        return new ConfirmPromptBlocked(error);
+    }
+    if (name === 'NotAllowedError' || name === 'AbortError')
+        return new ConfirmCancelled(error);
+    return error;
+}
+/**
+ * The node refuses an envelope past its 64 MiB sealed cap with `413` in the
+ * clear, before opening it, so the refusal arrives as the transport's. To the
+ * caller it is the API's `TOO_LARGE`, as the Rust client reports it.
+ */
+function sealedError(error) {
+    if (error instanceof SealedTransportError && error.status === 413) {
+        return errorFrom(413, {
+            error: 'TOO_LARGE',
+            message: error.message.replace(/^Sealed request refused: /, ''),
+        });
+    }
+    return error;
+}
+/** Read a refused response's body and map it ({@link errorFrom}). */
+export async function refusal(response) {
+    const text = await response.text().catch(() => '');
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        body = { message: text };
+    }
+    return errorFrom(response.status, body, response.headers.get('retry-after'));
+}
+/** Server-sent event frames from a response body: `{ id, kind, data }` each, `data` parsed as JSON when it is. */
+export async function* sseFrames(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            return;
+        buffer += decoder.decode(value, { stream: true });
+        let cut;
+        while ((cut = buffer.indexOf('\n\n')) >= 0) {
+            const frame = buffer.slice(0, cut);
+            buffer = buffer.slice(cut + 2);
+            let id = '';
+            let kind = '';
+            let data = '';
+            for (const line of frame.split('\n')) {
+                if (line.startsWith('id:'))
+                    id = line.slice(3).trim();
+                else if (line.startsWith('event:'))
+                    kind = line.slice(6).trim();
+                else if (line.startsWith('data:'))
+                    data += line.slice(5).trim();
+            }
+            if (!kind && !data)
+                continue;
+            let parsed = data;
+            try {
+                parsed = JSON.parse(data);
+            }
+            catch {
+                /* plain text */
+            }
+            yield { id, kind, data: parsed };
+        }
+    }
+}
+/**
+ * A key for a call the caller gave none, made once so every retry shares it:
+ * `node:c-` and 16 random bytes in base64url without padding, as the Rust
+ * client mints it. It only has to outlive this client's own retries, so it
+ * takes the node's short-lived class: a key starting `node:` is kept 10
+ * minutes, a caller's own key 24 hours.
+ * `getRandomValues`, not `randomUUID`, which a page outside a secure context lacks.
+ */
+export function newIdempotencyKey() {
+    return `node:c-${b64url(crypto.getRandomValues(new Uint8Array(16)))}`;
+}
+/**
+ * `template` (`apps/{app}/blobs/{id}`) with each `{name}` replaced by
+ * `params[name]`, encoded as one path segment so an id cannot reach another
+ * route. A name `params` lacks throws.
+ */
+export function routePath(template, params = {}) {
+    return template.replace(/\{([^}]+)\}/g, (_, name) => {
+        const value = params[name];
+        if (value === undefined)
+            throw new Error(`no value for path parameter ${name} of ${template}`);
+        return encodeURIComponent(String(value));
+    });
+}
+/** `query` as a search string (`?a=1&b=2`), or `''` when it sets nothing. */
+export function queryString(query) {
+    if (!query)
+        return '';
+    const search = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+        for (const one of Array.isArray(value) ? value : [value]) {
+            if (one !== undefined && one !== null)
+                search.append(name, String(one));
+        }
+    }
+    const text = search.toString();
+    return text ? `?${text}` : '';
+}
+/**
+ * The ceremonies that mint a session, which {@link NodeTransport} never
+ * repeats by itself: a sign-in or sign-up is started again by its caller (with
+ * the passkey), and a refresh moves through the nodes in
+ * {@link NodeTransport.refresh}. A node answers them `421 WRONG_NODE` before
+ * it spends the challenge or the refresh token (core #4774).
+ */
+function ceremony(path) {
+    return path === 'auth/refresh' || path.startsWith('auth/passkey/') || RECOVERY_CEREMONIES.has(path);
+}
+/** The signed-out halves of an account recovery: a `401` there is the code's, not a session's. */
+const RECOVERY_CEREMONIES = new Set(['auth/recovery/begin', 'auth/recovery/start', 'auth/recovery/finish']);
+/** The route path a request names: no leading `/`. */
+function relative(path) {
+    return path.replace(/^\/+/, '');
+}
+/**
+ * The {@link Transport} to one Calimero cluster: its nodes, each attested
+ * under one policy before its first request, the credential, and the session's
+ * refresh. {@link CalimeroClient} is built on one (`client.transport`); a
+ * generated route layer takes one too.
+ */
+export class NodeTransport {
+    constructor(options) {
+        /** The one in use: an index into {@link nodeUrls}. */
+        this.at = 0;
+        /** A sealed fetch per node, each attesting its own node on first use. */
+        this.channels = new Map();
+        /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
+        this.networkFailures = new WeakSet();
+        const trim = (url) => url.replace(/\/+$/, '');
+        this.nodeUrls = [...new Set([options.baseUrl, ...(options.nodes ?? [])].map(trim))];
+        this.policy = options.policy;
+        this.retry = { ...DEFAULT_RETRY, ...options.retry };
+        const given = options.fetch ?? ((input, init) => fetch(input, init));
+        // `fetch` rejects with a `TypeError` when it gets no answer: the connection
+        // was refused, reset or dropped before the response. The sealed fetch passes
+        // that rejection on unchanged, so it is recognised here, at its source, and
+        // not by its type alone (a bad URL is a `TypeError` too, and is not retried).
+        const raw = async (input, init) => {
+            try {
+                return await given(input, init);
+            }
+            catch (error) {
+                if (error instanceof TypeError)
+                    this.networkFailures.add(error);
+                throw error;
+            }
+        };
+        this.raw = raw;
+    }
+    /** Re-read the node list from `source` when it is due, and after a failover. */
+    useDirectory(source) {
+        this.source = source;
+    }
+    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` or a failover moved on. */
+    get nodeUrl() {
+        return this.nodeUrls[this.at];
+    }
+    /** Every node this transport may use, in the order it moves through them. */
+    get nodes() {
+        return [...this.nodeUrls];
+    }
+    /** Authenticate every request with an API key. */
+    useApiKey(key) {
+        this.auth = key;
+        this.current = undefined;
+    }
+    /** Authenticate every request with `session`, refreshed when a node answers `401` to it. */
+    useSession(session) {
+        this.auth = session.sessionToken;
+        this.current = session;
+    }
+    /** Drop the credential: no request after this carries it. */
+    signOut() {
+        this.auth = undefined;
+        this.current = undefined;
+    }
+    get session() {
+        return this.current;
+    }
+    /** The sealed channel to `url`, attested under the policy before its first request. */
+    channel(url) {
+        let sealed = this.channels.get(url);
+        if (!sealed) {
+            sealed = createSealedFetch({
+                baseUrl: url,
+                transportPublicKey: () => fetchAttestedKey(url, this.policy, this.raw),
+                fetch: this.raw,
+            });
+            this.channels.set(url, sealed);
+        }
+        return sealed;
+    }
+    /**
+     * Move on from node `from` (the one that answered `421 WRONG_NODE`) to the
+     * next one. False when there is no other. A request that saw the same node
+     * refuse after another request moved on already does not move again.
+     */
+    moveOn(from) {
+        if (this.nodeUrls.length < 2)
+            return false;
+        if (this.nodeUrl === from)
+            this.at = (this.at + 1) % this.nodeUrls.length;
+        return true;
+    }
+    /**
+     * Fail over from node `from`, where a request's retries ran out, to the next
+     * node it has not `tried`. False when it has tried them all. A request whose
+     * node another request moved away from already goes to that node, if untried.
+     */
+    failOver(from, tried) {
+        if (this.nodeUrl !== from && !tried.has(this.nodeUrl))
+            return true;
+        const count = this.nodeUrls.length;
+        for (let step = 1; step < count; step++) {
+            const next = (this.at + step) % count;
+            if (!tried.has(this.nodeUrls[next])) {
+                this.at = next;
+                this.reread();
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Read the node list again from the directory, in the background: the node
+     * in use stays first, then the directory's order; a node no longer listed is
+     * dropped. A failed read is ignored. One read at a time.
+     */
+    reread() {
+        const source = this.source;
+        if (!source || source.reading)
+            return;
+        source.reading = readDirectory(source.directory, source.cluster, this.raw)
+            .then((listing) => {
+            const current = this.nodeUrl;
+            const listed = orderNodes(listing.nodes, source.zone, source.random);
+            this.nodeUrls = [current, ...listed.filter((url) => url !== current)];
+            this.at = 0;
+            source.due = Date.now() + listing.refreshAfterSeconds * 1000;
+        })
+            .catch(() => undefined)
+            .finally(() => {
+            source.reading = undefined;
+        });
+    }
+    /**
+     * Send one request to the node in use, with the credential held now, and
+     * answer the response, whatever its status. {@link send} judges it.
+     */
+    async once(method, path, options) {
+        const headers = {};
+        if (this.auth)
+            headers.authorization = `Bearer ${this.auth}`;
+        let payload;
+        if (options.bytes) {
+            headers['content-type'] = options.contentType ?? 'application/wasm';
+            payload = options.bytes;
+        }
+        else if (options.body !== undefined) {
+            headers['content-type'] = 'application/json';
+            payload = JSON.stringify(options.body);
+        }
+        if (this.source && Date.now() >= this.source.due)
+            this.reread();
+        const url = this.nodeUrl;
+        try {
+            return await this.channel(url)(`${url}/${path}${queryString(options.query)}`, {
+                method,
+                headers,
+                body: payload,
+                signal: options.signal,
+            });
+        }
+        catch (error) {
+            throw sealedError(error);
+        }
+    }
+    /**
+     * {@link once}, answering what a lost issuing node or a node on the wrong
+     * release does to a session: a successful response, or the refusal as a
+     * typed error ({@link errorFrom}).
+     *
+     * - `401 UNAUTHENTICATED` to a request that carried a session: the node that
+     *   signed the session may be gone, replaced, or out of reach of the node
+     *   asked, which any node of the cluster answers with a refresh. The
+     *   transport refreshes once, shared by every request that needs it at the
+     *   same time ({@link refresh}), and repeats the request once. A refresh that
+     *   is refused surfaces as {@link LoginRequired}.
+     * - `421 WRONG_NODE`: this node's release may not serve the account. The
+     *   transport moves to the next node it knows and repeats the request once;
+     *   with none, the {@link WrongNode} reaches the caller.
+     *
+     * Repeating is safe even for a request that is not idempotent: the node
+     * answers `401` and `421` when it judges the credential, before it reads what
+     * the request asks, so the first attempt ran nothing. The exceptions are the
+     * ceremonies that mint a session ({@link ceremony}), never repeated here.
+     */
+    async send(method, path, options) {
+        let refreshed = false;
+        let moved = false;
+        for (;;) {
+            const [token, at] = [this.auth, this.nodeUrl];
+            const response = await this.once(method, path, options);
+            if (response.ok)
+                return response;
+            const error = await refusal(response);
+            if (error instanceof WrongNode && !moved) {
+                moved = true;
+                if (this.moveOn(at) && !ceremony(path))
+                    continue;
+            }
+            else if (error instanceof LoginRequired && !refreshed && this.mayRefresh(token, path)) {
+                refreshed = true;
+                await this.renew(token);
+                continue;
+            }
+            throw error;
+        }
+    }
+    /** Whether a `401` to a request sent with `token` is one a refresh may answer. */
+    mayRefresh(token, path) {
+        return token !== undefined && this.current !== undefined && !ceremony(path);
+    }
+    /**
+     * A fresh session in place of the one `token` belonged to: by the refresh
+     * another request already made, or by one this request starts.
+     */
+    async renew(token) {
+        if (this.auth !== token)
+            return;
+        await this.refresh();
+    }
+    async read(method, path, options) {
+        const response = await this.send(method, path, options);
+        const text = await response.text();
+        return (text ? JSON.parse(text) : {});
+    }
+    /**
+     * {@link read} for a call or a view (D70): while the node answers 503 or
+     * cannot be reached, the same request, with the same idempotency key, is sent
+     * again after {@link retryDelayMs} (or the pause the node asked for, if
+     * longer), at most `retries` times. Every other answer is final.
+     *
+     * When a node's retries run out, the request fails over to the next node the
+     * transport knows and its retries start again there, with the same key: the
+     * key is kept in the app's replicated log, so the cluster answers it once
+     * whichever node it reaches. Each node is tried once per request. The last
+     * failure surfaces as {@link UnavailableError}: the node's 503, or reason
+     * `network` for a connection that failed, whose `committed` is `'unknown'`.
+     *
+     * `once` sends the request exactly once, to the node in use (a confirmed
+     * attempt, whose challenge is single-use).
+     */
+    async retried(method, path, options, once) {
+        const retries = once ? 0 : this.retry.retries;
+        const tried = new Set();
+        for (;;) {
+            let unavailable;
+            let node = this.nodeUrl;
+            for (let attempt = 0;; attempt++) {
+                node = this.nodeUrl;
+                tried.add(node);
+                try {
+                    return await this.read(method, path, options);
+                }
+                catch (error) {
+                    if (error instanceof UnavailableError)
+                        unavailable = error;
+                    else if (error instanceof TypeError && this.networkFailures.has(error)) {
+                        unavailable = new UnavailableError('NETWORK', `the node could not be reached: ${error.message}`, {}, undefined, error);
+                    }
+                    else
+                        throw error;
+                }
+                if (attempt >= retries)
+                    break;
+                const backoff = retryDelayMs(attempt, this.retry);
+                await new Promise((resolve) => setTimeout(resolve, Math.max(backoff, (unavailable.retryAfter ?? 0) * 1000)));
+            }
+            if (once || !this.failOver(node, tried))
+                throw unavailable;
+        }
+    }
+    /**
+     * One JSON request, retried as `options.retry` says. The confirmed attempt
+     * of a step-up (`body.confirm` set) goes out exactly once.
+     */
+    attempt(method, path, options) {
+        if (!options.retry)
+            return this.read(method, path, options);
+        const confirming = options.body?.confirm !== undefined;
+        return this.retried(method, path, options, options.retry === 'once' || confirming);
+    }
+    /**
+     * {@link attempt}, answering a `412 CONFIRM_REQUIRED` with `passkey`'s
+     * assertion over the node's challenge: the same body again, with `confirm`.
+     * Without a passkey the `412` reaches the caller as {@link ConfirmRequired}.
+     */
+    async confirmed(method, path, options) {
+        const { passkey } = options;
+        const signal = options.promptSignal ?? options.signal;
+        try {
+            return await this.attempt(method, path, options);
+        }
+        catch (error) {
+            if (!(error instanceof ConfirmRequired) || !passkey)
+                throw error;
+            const d = error.details;
+            let assertion;
+            try {
+                // A step-up is taken only with the user verified (PIN or biometric);
+                // `preferred` lets a password manager skip it, and the node then
+                // refuses. Only the sign-up confirmation passes `preferred`. A
+                // requirement the node names itself wins.
+                assertion = await passkey.get(fromB64url(d.challenge), d.rpId, d.allowCredentials, {
+                    userVerification: userVerificationOf(d.userVerification, options.userVerification ?? 'required'),
+                    ...(signal ? { signal } : {}),
+                });
+            }
+            catch (declined) {
+                throw promptFailure(declined);
+            }
+            const body = { ...options.body, confirm: { challengeId: d.challengeId, assertion } };
+            return this.attempt(method, path, { ...options, body });
+        }
+    }
+    request(method, path, options = {}) {
+        return this.send(method, relative(path), options);
+    }
+    json(method, path, options = {}) {
+        return this.confirmed(method, relative(path), options);
+    }
+    async *events(path, options = {}) {
+        const response = await this.send('GET', relative(path), options);
+        if (!response.body)
+            throw new CalimeroError(response.status, 'EVENTS', 'the event stream has no body');
+        yield* sseFrames(response.body);
+    }
+    /**
+     * `GET path` in the clear, from the node in use: only for the route a node
+     * serves unsealed (`attestation`), and never with the credential.
+     */
+    async unsealed(path, options = {}) {
+        const response = await this.raw(`${this.nodeUrl}/${relative(path)}${queryString(options.query)}`);
+        if (!response.ok)
+            throw await refusal(response);
+        return response;
+    }
+    /**
+     * Swap the refresh token for a new session, on whichever node the transport
+     * uses: any node of the cluster takes it. A refresh token is used once, so
+     * requests made while one refresh is under way share it rather than sending
+     * the same token again (which would revoke the session).
+     */
+    refresh() {
+        if (!this.refreshing) {
+            const pending = this.exchangeRefresh();
+            this.refreshing = pending;
+            const clear = () => {
+                if (this.refreshing === pending)
+                    this.refreshing = undefined;
+            };
+            pending.then(clear, clear);
+        }
+        return this.refreshing;
+    }
+    async exchangeRefresh() {
+        const current = this.current;
+        if (!current)
+            throw new Error('no session to refresh');
+        let session;
+        // A node that may not serve the account answers `421 WRONG_NODE` before it
+        // spends the refresh token (core #4774), so the same token goes to the next
+        // node (`send` moved there already): once per node, at most.
+        for (let tried = 1; session === undefined; tried++) {
+            try {
+                session = await this.json('POST', 'auth/refresh', { body: { refreshToken: current.refreshToken } });
+            }
+            catch (error) {
+                if (!(error instanceof WrongNode) || tried >= this.nodeUrls.length)
+                    throw error;
+            }
+        }
+        // A sign-in or another session taken while this one was refreshing wins.
+        if (this.current === current)
+            this.useSession(session);
+        return session;
+    }
+}
+/**
+ * A {@link NodeTransport} to the cluster named `cluster`, its node list read
+ * from the node directory (`directory`), those in `zone` first, each group in
+ * weighted-random order, and read again in the background after a failover
+ * and once the listing's `refreshAfterSeconds` passed.
+ */
+export async function directoryTransport(options) {
+    const random = options.random ?? Math.random;
+    const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+    const listing = await readDirectory(options.directory, options.cluster, fetcher);
+    const [baseUrl, ...nodes] = orderNodes(listing.nodes, options.zone, random);
+    const transport = new NodeTransport({ baseUrl, nodes, policy: options.policy, fetch: options.fetch, retry: options.retry });
+    transport.useDirectory({
+        directory: options.directory,
+        cluster: options.cluster,
+        zone: options.zone,
+        random,
+        due: Date.now() + listing.refreshAfterSeconds * 1000,
+    });
+    return transport;
+}

package/dist/runtime.browser.mjs

@@ -0,0 +1,67 @@
+// Generated by scripts/runtime-entries.mjs: the runtime, from the package bundle.
+export {
+  AppError,
+  ArgsTooLarge,
+  BadOrigin,
+  CalimeroError,
+  ClusterNotUpgraded,
+  ConfirmCancelled,
+  ConfirmPromptBlocked,
+  ConfirmRequired,
+  ConsentStale,
+  DEFAULT_COLLATERAL_MIRROR,
+  DEFAULT_DIRECTORY,
+  DEFAULT_RELEASE_MIRROR,
+  DEFAULT_RETRY,
+  DirectoryError,
+  GITHUB_RELEASES,
+  HANDSHAKE_PATH,
+  IdempotencyMismatch,
+  LoginRequired,
+  MOCK_QUOTE_HEADER,
+  NODE_RELEASE_SIGNER,
+  NodeTransport,
+  NotFound,
+  NotServing,
+  OriginNotRegistered,
+  OriginTaken,
+  PRODUCTION_PROFILE,
+  PasskeyUnknownHere,
+  QuotaExceeded,
+  RecoveryNotReady,
+  ReleaseDeadlineError,
+  RuntimeTooOld,
+  SEALED_CONTENT_TYPE,
+  SEALED_PATH,
+  SealedTransportError,
+  SignUpRefused,
+  StaleTransportKeyError,
+  TrapError,
+  UnavailableError,
+  WrongNode,
+  WrongRecoveryCode,
+  b64url,
+  browserPasskey,
+  claimedRelease,
+  cloudNodeReleaseUrl,
+  createQuoteVerifier,
+  createSealedFetch,
+  createSignedReleaseVerifier,
+  directoryTransport,
+  errorFrom,
+  fetchAttestedKey,
+  fetchGithubNodeRelease,
+  fetchNodeRelease,
+  freshCollateral,
+  fromB64url,
+  newIdempotencyKey,
+  queryString,
+  refusal,
+  retryDelayMs,
+  routePath,
+  sseFrames,
+  transportKeyBinding,
+  trustSignedRelease,
+  trustedMeasurementsFromReleases,
+  verifySignedNodeRelease,
+} from './index.browser.mjs';