@calimero-network/mero-js 29.14.0 → 29.16.0

package/dist/runtime/index.d.ts

@@ -0,0 +1,10 @@
+export { DEFAULT_RETRY, NodeTransport, directoryTransport, newIdempotencyKey, queryString, refusal, retryDelayMs, routePath, sseFrames, } from './transport.js';
+export type { CalimeroSession, CloudEvent, CloudRetryOptions, DirectorySource, HttpMethod, NodeTransportOptions, QueryValue, RequestOptions, Transport, } from './transport.js';
+export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from '../cloud-v2/attestation.js';
+export type { AttestationDoc, CloudPolicy, CloudReleasePolicy } from '../cloud-v2/attestation.js';
+export { DEFAULT_DIRECTORY, DirectoryError } from '../cloud-v2/directory.js';
+export type { DirectoryFailure } from '../cloud-v2/directory.js';
+export { browserPasskey, b64url, fromB64url } from '../cloud-v2/passkey.js';
+export type { AssertionJSON, PasskeyCreateOptions, PasskeyGetOptions, PasskeyProvider, PasskeyUserVerification, RegistrationJSON, } from '../cloud-v2/passkey.js';
+export * from '../cloud-v2/errors.js';
+export * from '../sealed/index.js';

package/dist/runtime/index.js

@@ -0,0 +1,21 @@
+// The mero-js runtime (`@calimero-network/mero-js/runtime`): everything a
+// route layer sends through, and nothing that is a route.
+//
+// `Transport.request(method, path, options)` reaches one node route over the
+// attested, sealed channel with the credential held now; the runtime handles
+// attestation, sealing, the session and its refresh, `421 WRONG_NODE` moves,
+// D70 retries, the `412 CONFIRM_REQUIRED` passkey step-up, error mapping and
+// server-sent events. `CalimeroClient` (the package root) is the hand-written
+// route layer on top; `client.transport` is its runtime, which a generated
+// route layer can share.
+export { DEFAULT_RETRY, NodeTransport, directoryTransport, newIdempotencyKey, queryString, refusal, retryDelayMs, routePath, sseFrames, } from './transport.js';
+// Attestation: what a node must prove before anything is sealed to it.
+export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from '../cloud-v2/attestation.js';
+// The node directory a cluster's node list is read from.
+export { DEFAULT_DIRECTORY, DirectoryError } from '../cloud-v2/directory.js';
+// Passkeys (WebAuthn) for the step-up and the ceremonies.
+export { browserPasskey, b64url, fromB64url } from '../cloud-v2/passkey.js';
+// A refusal as a typed error.
+export * from '../cloud-v2/errors.js';
+// The sealed channel and the quote and release checks under it.
+export * from '../sealed/index.js';

package/dist/runtime/transport.d.ts

@@ -0,0 +1,311 @@
+/**
+ * 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 { type CloudPolicy } from '../cloud-v2/attestation.js';
+import { CalimeroError } from '../cloud-v2/errors.js';
+import { type PasskeyProvider, type PasskeyUserVerification } from '../cloud-v2/passkey.js';
+/** A signed-in session: what sign-up, sign-in and a refresh answer. */
+export interface CalimeroSession {
+    accountId: string;
+    sessionToken: string;
+    expiresAt: number;
+    refreshToken: string;
+}
+/** One server-sent event: `data` parsed as JSON when it is. */
+export interface CloudEvent {
+    id: string;
+    kind: string;
+    data: unknown;
+}
+/**
+ * How a call or a view is sent again while the node is unavailable (D70): with
+ * the same key, after a backoff that starts at `baseDelayMs` and doubles up to
+ * `maxDelayMs`, no jitter, at most `retries` times. The defaults are the Rust
+ * client's: 6 retries, 200 ms doubling, at most 2 s (about 9 s in all, past a
+ * leader election).
+ */
+export interface CloudRetryOptions {
+    /** Retries after the first attempt. Default 6. */
+    retries?: number;
+    /** The first backoff; each retry doubles it. Default 200 ms. */
+    baseDelayMs?: number;
+    /** The longest backoff. Default 2 s. */
+    maxDelayMs?: number;
+}
+export declare const DEFAULT_RETRY: {
+    readonly retries: 6;
+    readonly baseDelayMs: 200;
+    readonly maxDelayMs: 2000;
+};
+/** The backoff before retry `retry` (0 for the first): `baseDelayMs` doubling, at most `maxDelayMs`. */
+export declare function retryDelayMs(retry: number, options: {
+    baseDelayMs: number;
+    maxDelayMs: number;
+}): number;
+/** The HTTP methods the node's routes use. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** A query parameter's value; `undefined` and `null` leave it out, an array repeats it. */
+export type QueryValue = string | number | boolean | null | undefined;
+/** What a request carries beyond its method and path. */
+export interface RequestOptions {
+    /** Query parameters, appended to the path (encoded here). */
+    query?: Record<string, QueryValue | QueryValue[]>;
+    /** A JSON body. */
+    body?: unknown;
+    /** A raw body instead of JSON (a bundle, a package, a blob). */
+    bytes?: Uint8Array;
+    /** The raw body's content type. Default `application/wasm`. */
+    contentType?: string;
+    /**
+     * Answers a `412 CONFIRM_REQUIRED`: the passkey asserts over the node's
+     * challenge and the same JSON body is sent again with `confirm`. Without
+     * one the `412` reaches the caller as {@link ConfirmRequired}.
+     */
+    passkey?: PasskeyProvider;
+    /** The user verification the step-up asks for when the node names none. Default `required`. */
+    userVerification?: PasskeyUserVerification;
+    /**
+     * D70 retries for a call or a view: `true` sends it again while the node
+     * answers `503` or cannot be reached, then fails over to the next node;
+     * `'once'` sends it exactly once (a confirmed attempt, whose challenge is
+     * single-use). Only for a JSON body that carries its own idempotency key,
+     * or a read.
+     */
+    retry?: boolean | 'once';
+    /** Aborts the request (and a stream), and the step-up's passkey prompt. */
+    signal?: AbortSignal;
+    /** Aborts only the step-up's passkey prompt, not the requests around it. Default `signal`. */
+    promptSignal?: AbortSignal;
+}
+/**
+ * What a route layer calls. Every method sends through the attested, sealed
+ * channel of the node in use, with the credential held now. A refusal (any
+ * status other than 2xx) is thrown as a typed {@link CalimeroError}
+ * ({@link errorFrom}); a transport failure as the error that caused it.
+ */
+export interface Transport {
+    /** The response to `method path`, status 2xx; its body is not read. */
+    request(method: HttpMethod, path: string, options?: RequestOptions): Promise<Response>;
+    /** {@link request}'s JSON body (`{}` for an empty one). */
+    json<T = Record<string, unknown>>(method: HttpMethod, path: string, options?: RequestOptions): Promise<T>;
+    /** A server-sent event stream on `GET path`, until the stream ends or `signal` aborts. */
+    events(path: string, options?: Pick<RequestOptions, 'query' | 'signal'>): AsyncGenerator<CloudEvent>;
+}
+/** How {@link NodeTransport} reaches a cluster's nodes. */
+export interface NodeTransportOptions {
+    /** One node of the cluster: the one the transport talks to first. */
+    baseUrl: string;
+    /** Other nodes of the same cluster, in the order to move to them. */
+    nodes?: string[];
+    /** What every node must attest to before anything is sent to it. */
+    policy: CloudPolicy;
+    /** Fetch that carries attestation and envelopes. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** How calls and views retry a 503 or a failed connection. */
+    retry?: CloudRetryOptions;
+}
+/** Where a transport whose nodes came from the directory re-reads its node list. */
+export interface DirectorySource {
+    directory: string;
+    cluster: string;
+    zone: string | undefined;
+    random: () => number;
+    /** When the listing is due to be read again (ms since the epoch). */
+    due: number;
+    /** The re-read under way, if any. */
+    reading?: Promise<void>;
+}
+/** Read a refused response's body and map it ({@link errorFrom}). */
+export declare function refusal(response: Response): Promise<CalimeroError>;
+/** Server-sent event frames from a response body: `{ id, kind, data }` each, `data` parsed as JSON when it is. */
+export declare function sseFrames(body: ReadableStream<Uint8Array>): AsyncGenerator<CloudEvent>;
+/**
+ * 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 declare function newIdempotencyKey(): string;
+/**
+ * `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 declare function routePath(template: string, params?: Record<string, string | number>): string;
+/** `query` as a search string (`?a=1&b=2`), or `''` when it sets nothing. */
+export declare function queryString(query: RequestOptions['query']): string;
+/**
+ * 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 declare class NodeTransport implements Transport {
+    /** Every node this transport may use, `baseUrl` first (or as the directory last ordered them). */
+    private nodeUrls;
+    /** The one in use: an index into {@link nodeUrls}. */
+    private at;
+    /** A sealed fetch per node, each attesting its own node on first use. */
+    private readonly channels;
+    private readonly policy;
+    /** The unsealed fetch, for the one route served in the clear (`/attestation`). */
+    readonly raw: typeof fetch;
+    private auth;
+    private current;
+    /** The refresh under way, which every request that needs one shares. */
+    private refreshing;
+    private readonly retry;
+    /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
+    private readonly networkFailures;
+    /** The directory the node list came from, if it came from one. */
+    private source;
+    constructor(options: NodeTransportOptions);
+    /** Re-read the node list from `source` when it is due, and after a failover. */
+    useDirectory(source: DirectorySource): void;
+    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` or a failover moved on. */
+    get nodeUrl(): string;
+    /** Every node this transport may use, in the order it moves through them. */
+    get nodes(): string[];
+    /** Authenticate every request with an API key. */
+    useApiKey(key: string): void;
+    /** Authenticate every request with `session`, refreshed when a node answers `401` to it. */
+    useSession(session: CalimeroSession): void;
+    /** Drop the credential: no request after this carries it. */
+    signOut(): void;
+    get session(): CalimeroSession | undefined;
+    /** The sealed channel to `url`, attested under the policy before its first request. */
+    private channel;
+    /**
+     * 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.
+     */
+    private moveOn;
+    /**
+     * 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.
+     */
+    private failOver;
+    /**
+     * 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.
+     */
+    private reread;
+    /**
+     * Send one request to the node in use, with the credential held now, and
+     * answer the response, whatever its status. {@link send} judges it.
+     */
+    private once;
+    /**
+     * {@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.
+     */
+    private send;
+    /** Whether a `401` to a request sent with `token` is one a refresh may answer. */
+    private mayRefresh;
+    /**
+     * A fresh session in place of the one `token` belonged to: by the refresh
+     * another request already made, or by one this request starts.
+     */
+    private renew;
+    private read;
+    /**
+     * {@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).
+     */
+    private retried;
+    /**
+     * One JSON request, retried as `options.retry` says. The confirmed attempt
+     * of a step-up (`body.confirm` set) goes out exactly once.
+     */
+    private attempt;
+    /**
+     * {@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}.
+     */
+    private confirmed;
+    request(method: HttpMethod, path: string, options?: RequestOptions): Promise<Response>;
+    json<T = Record<string, unknown>>(method: HttpMethod, path: string, options?: RequestOptions): Promise<T>;
+    events(path: string, options?: Pick<RequestOptions, 'query' | 'signal'>): AsyncGenerator<CloudEvent>;
+    /**
+     * `GET path` in the clear, from the node in use: only for the route a node
+     * serves unsealed (`attestation`), and never with the credential.
+     */
+    unsealed(path: string, options?: Pick<RequestOptions, 'query'>): Promise<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(): Promise<CalimeroSession>;
+    private exchangeRefresh;
+}
+/**
+ * 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 declare function directoryTransport(options: {
+    cluster: string;
+    policy: CloudPolicy;
+    directory: string;
+    zone?: string;
+    fetch?: typeof fetch;
+    retry?: CloudRetryOptions;
+    random?: () => number;
+}): Promise<NodeTransport>;