@calimero-network/mero-js 26.4.1 → 26.6.0

package/dist/account/index.d.ts

@@ -4,8 +4,8 @@ export { resolveRoot } from './account.js';
 export type { RootSource } from './account.js';
 export { resolveRootPair } from './account.js';
 export type { ResolvedRoot } from './account.js';
-export type { DelegatedCredential, DelegatedSession as DelegatedAccountSession, RelayMap, RelayNodeKeyAttempt } from './session.js';
-export { readDelegatedSession, saveDelegatedSession, clearDelegatedSession, readDelegatedCredential, saveDelegatedCredential, clearDelegatedCredential, persistedNonces, markContextNonceSpent, pinRelayNodeKey, readPinnedRelayNodeKey, attemptRelayNodeKey, resolveRelayNodeKey, learnRelayNodeKey, RELAY_NODE_KEY_RETRY_MS, forgetMethodKinds, forgetRelaySealing, relayTransportFetch, buildDelegatedClient, readRelayMap, rememberRelay, relayForContext, carryExecutorAccount, knownRelays, listDelegatedContexts, listDelegatedNamespaces, } from './session.js';
+export type { DelegatedCredential, DelegatedSession as DelegatedAccountSession, RelayMap, RelayNodeKeyAttempt, RelayListingFailure } from './session.js';
+export { readDelegatedSession, saveDelegatedSession, clearDelegatedSession, readDelegatedCredential, saveDelegatedCredential, clearDelegatedCredential, persistedNonces, markContextNonceSpent, pinRelayNodeKey, readPinnedRelayNodeKey, attemptRelayNodeKey, resolveRelayNodeKey, learnRelayNodeKey, RELAY_NODE_KEY_RETRY_MS, forgetMethodKinds, forgetRelaySealing, relayTransportFetch, buildDelegatedClient, readRelayMap, rememberRelay, relayForContext, carryExecutorAccount, knownRelays, listDelegatedContexts, listDelegatedNamespaces, RelaysUnavailableError, } from './session.js';
 export { resolveRelayFromInvitation, normaliseAccount } from './relay-from-invitation.js';
 export type { RelayResolutionStep, RelayResolutionFailure, ResolvedInvitationRelay, ResolveRelayResult, ResolveRelayFromInvitationInput, } from './relay-from-invitation.js';
 export { joinWithNode } from './join-with-node.js';
@@ -20,5 +20,7 @@ export { applicationIdForBundle, fetchRegistryBundles, resolveApplicationIdFromR
 export type { RegistryBundle, ResolvedApplication } from './application-id.js';
 export { createAccountAdmin, InvitationNotClaimableError, NoRelayError, NotForAccountError, } from './account-admin.js';
 export type { AccountAdminDeps } from './account-admin.js';
+export { RelayLoginError } from './relay-login-error.js';
+export type { RelayLoginFailureKind } from './relay-login-error.js';
 export { createNodeAdmin } from './node-admin.js';
 export type { NodeAdminDeps } from './node-admin.js';

package/dist/account/index.js

@@ -2,7 +2,7 @@
 export { generateAccountRoot, accountRootFromPhrase, accountRootFromSecret, createAccountRootSigner, accountRootSignerFromPhrase, signAccountLink, signAccountLogin, } from './account.js';
 export { resolveRoot } from './account.js';
 export { resolveRootPair } from './account.js';
-export { readDelegatedSession, saveDelegatedSession, clearDelegatedSession, readDelegatedCredential, saveDelegatedCredential, clearDelegatedCredential, persistedNonces, markContextNonceSpent, pinRelayNodeKey, readPinnedRelayNodeKey, attemptRelayNodeKey, resolveRelayNodeKey, learnRelayNodeKey, RELAY_NODE_KEY_RETRY_MS, forgetMethodKinds, forgetRelaySealing, relayTransportFetch, buildDelegatedClient, readRelayMap, rememberRelay, relayForContext, carryExecutorAccount, knownRelays, listDelegatedContexts, listDelegatedNamespaces, } from './session.js';
+export { readDelegatedSession, saveDelegatedSession, clearDelegatedSession, readDelegatedCredential, saveDelegatedCredential, clearDelegatedCredential, persistedNonces, markContextNonceSpent, pinRelayNodeKey, readPinnedRelayNodeKey, attemptRelayNodeKey, resolveRelayNodeKey, learnRelayNodeKey, RELAY_NODE_KEY_RETRY_MS, forgetMethodKinds, forgetRelaySealing, relayTransportFetch, buildDelegatedClient, readRelayMap, rememberRelay, relayForContext, carryExecutorAccount, knownRelays, listDelegatedContexts, listDelegatedNamespaces, RelaysUnavailableError, } from './session.js';
 export { resolveRelayFromInvitation, normaliseAccount } from './relay-from-invitation.js';
 export { joinWithNode } from './join-with-node.js';
 export { bootstrapFromInvitation } from './bootstrap-from-invitation.js';
@@ -11,4 +11,5 @@ export { createDelegatedContext, createDelegatedPrivateContext, foundDelegatedNa
 export { governGroup, governRoot, namespaceOfGroup, rememberGroupNamespace } from './govern.js';
 export { applicationIdForBundle, fetchRegistryBundles, resolveApplicationIdFromRegistry, selectLatestBundle, } from './application-id.js';
 export { createAccountAdmin, InvitationNotClaimableError, NoRelayError, NotForAccountError, } from './account-admin.js';
+export { RelayLoginError } from './relay-login-error.js';
 export { createNodeAdmin } from './node-admin.js';

package/dist/account/relay-login-error.d.ts

@@ -0,0 +1,32 @@
+import { RequestAuthError } from '../http-client/web-client.js';
+/**
+ * Why a relay login failed, as far as it decides what the app does next.
+ *
+ * - `signed-out` — the relay answered and refused the credential (401 or 403):
+ *   it expired or was revoked, and signing in again is the way forward.
+ * - `unavailable` — the login never got an answer about the credential: the
+ *   relay could not be reached (DNS, TLS, offline, a timeout), or it failed
+ *   with a 5xx, or answered something else. Trying again later may work.
+ */
+export type RelayLoginFailureKind = 'signed-out' | 'unavailable';
+/**
+ * The relay session a request needed could not be minted.
+ *
+ * Thrown by the admin requests of a delegated client (`client.admin.*`) in
+ * place of sending them without a token, so the caller sees the login's own
+ * failure rather than the node's 401 for the unauthenticated request — or, for
+ * a relay that is down, the same transport error a second time. Nothing is
+ * remembered: the next request logs in again.
+ */
+export declare class RelayLoginError extends RequestAuthError {
+    name: string;
+    readonly relayUrl: string;
+    /** The login's own failure: an `HTTPError` (status 0 for no response) or what it threw. */
+    readonly cause: unknown;
+    readonly kind: RelayLoginFailureKind;
+    /** The HTTP status the login answered, 0 when no response arrived; undefined when not an HTTP failure. */
+    readonly loginStatus: number | undefined;
+    constructor(relayUrl: string, cause: unknown);
+}
+/** `signed-out` for a login answered 401/403, `unavailable` for anything else. */
+export declare function relayLoginFailureKind(cause: unknown): RelayLoginFailureKind;

package/dist/account/relay-login-error.js

@@ -0,0 +1,34 @@
+import { RequestAuthError } from '../http-client/web-client.js';
+/**
+ * The relay session a request needed could not be minted.
+ *
+ * Thrown by the admin requests of a delegated client (`client.admin.*`) in
+ * place of sending them without a token, so the caller sees the login's own
+ * failure rather than the node's 401 for the unauthenticated request — or, for
+ * a relay that is down, the same transport error a second time. Nothing is
+ * remembered: the next request logs in again.
+ */
+export class RelayLoginError extends RequestAuthError {
+    constructor(relayUrl, cause) {
+        const kind = relayLoginFailureKind(cause);
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(kind === 'signed-out'
+            ? `the relay ${relayUrl} refused this device's credential (${detail}); sign in again`
+            : `could not log in to the relay ${relayUrl}: ${detail}`);
+        this.name = 'RelayLoginError';
+        this.cause = cause;
+        this.relayUrl = relayUrl;
+        this.kind = kind;
+        this.loginStatus = loginStatusOf(cause);
+    }
+}
+/** `signed-out` for a login answered 401/403, `unavailable` for anything else. */
+export function relayLoginFailureKind(cause) {
+    const status = loginStatusOf(cause);
+    return status === 401 || status === 403 ? 'signed-out' : 'unavailable';
+}
+/** The status a login failure carries (`HTTPError.status`), if any. */
+function loginStatusOf(cause) {
+    const status = cause?.status;
+    return typeof status === 'number' && Number.isFinite(status) ? status : undefined;
+}

package/dist/account/session.d.ts

@@ -209,6 +209,36 @@ export declare function relayForContext(account: string, contextId: string): str
 export declare function carryExecutorAccount(prev: DelegatedSession | null, next: DelegatedSession): DelegatedSession;
 /** Every relay this account is known to use: the session's, and each in the map. */
 export declare function knownRelays(s: DelegatedSession): string[];
+/**
+ * Thrown by {@link listDelegatedContexts} and {@link listDelegatedNamespaces}
+ * when the account knows relays and **none** of them answered.
+ *
+ * One relay down is skipped, as before: the others still answer for what they
+ * serve. Every relay down is different. Returning `[]` then reads as "a member
+ * of nothing", and an app renders an empty account, with no error, for what is
+ * really "could not ask". A relay whose hostname no longer resolves (a node
+ * rebuilt or deleted in the cloud) did exactly that.
+ */
+/**
+ * Why one relay did not answer a listing.
+ *
+ * `refused`: its attestation did not verify (an untrusted image, a release
+ * below the floor). Asking again cannot change that, and it may be worth a
+ * closer look. `unavailable`: something on the way did not answer, or the
+ * relay refused the request itself; trying again later may.
+ */
+export interface RelayListingFailure {
+    relayUrl: string;
+    kind: 'refused' | 'unavailable';
+    error: unknown;
+}
+export declare class RelaysUnavailableError extends Error {
+    readonly failures: readonly RelayListingFailure[];
+    readonly relays: readonly string[];
+    constructor(failures: readonly RelayListingFailure[]);
+    /** Every relay refused its attestation: retrying will not help. */
+    get refused(): boolean;
+}
 type ListedContext = Awaited<ReturnType<MeroClient['admin']['getContexts']>>['contexts'][number];
 /**
  * This account's contexts on every relay it knows, each tagged with the relay
@@ -216,7 +246,8 @@ type ListedContext = Awaited<ReturnType<MeroClient['admin']['getContexts']>>['co
  *
  * Each relay answers only for itself and only for this caller, so the union is
  * exactly the account's contexts across relays. A relay that cannot be reached
- * or logged in to is skipped (its contexts simply do not appear), not fatal.
+ * or logged in to is skipped (its contexts simply do not appear), not fatal,
+ * unless it is every relay: then {@link RelaysUnavailableError}.
  */
 export declare function listDelegatedContexts(s: DelegatedSession): Promise<Array<ListedContext & {
     relayUrl: string;
@@ -226,7 +257,8 @@ type ListedNamespace = Awaited<ReturnType<MeroClient['admin']['listNamespaces']>
  * This account's namespaces on every relay it knows, each tagged with the relay
  * that listed it and recorded as that namespace's relay. Same rules as
  * {@link listDelegatedContexts}: each relay answers for itself and this caller
- * only (`namespace:list-own`); an unreachable relay is skipped.
+ * only (`namespace:list-own`); an unreachable relay is skipped, and every
+ * relay unreachable is {@link RelaysUnavailableError}.
  */
 export declare function listDelegatedNamespaces(s: DelegatedSession): Promise<Array<ListedNamespace & {
     relayUrl: string;

package/dist/account/session.js

@@ -17,6 +17,7 @@ import { attestRelayNodeKey, } from '../relay-attestation/index.js';
 import { cloudNodeReleaseUrl, createAttestedSealedFetch, createSignedReleaseVerifier, DEFAULT_RELEASE_MIRROR, fetchNodeRelease, fetchNodeReleaseVersion, } from '../sealed/index.js';
 import { createMeroClient, defaultAudience, } from '../transport/index.js';
 import { login, } from '../login/index.js';
+import { RelayLoginError } from './relay-login-error.js';
 import { SseClient, } from '../events/index.js';
 /** Where the per-tab record lives. */
 const KEY = 'calimero.delegated.connection';
@@ -517,9 +518,12 @@ export function relayTransportFetch(relayUrl) {
  * A hosted relay's `/admin-api/` sits behind the node's forward-auth, which
  * knows no request proof — it answers a Bearer token or 401. Logging in with
  * the device certificate is how a keyholder gets that token. Minted on first
- * use and re-minted once it has expired. On failure it yields `undefined`, the
- * admin request then goes out unauthenticated and the node's 401 is what the
- * caller sees; the next call tries to log in again.
+ * use and re-minted once it has expired. On failure it throws a
+ * {@link RelayLoginError}, which the HTTP client lets through instead of sending
+ * the admin request unauthenticated: the caller sees why the login failed —
+ * `signed-out` for a refused credential, `unavailable` for a relay that did not
+ * answer — rather than the node's 401 or the same transport error twice.
+ * Nothing is cached on failure, so the next call tries to log in again.
  */
 function relaySession(s, nodeKey) {
     let token = null;
@@ -543,9 +547,8 @@ function relaySession(s, nodeKey) {
                 return token;
             })
                 .catch((e) => {
-                console.warn('[mero-js] relay login failed', e);
                 token = null;
-                return undefined;
+                throw new RelayLoginError(s.relayUrl, e);
             })
                 .finally(() => {
                 inflight = null;
@@ -804,24 +807,56 @@ export function knownRelays(s) {
         .map(relayOrigin);
     return [...new Set(all)];
 }
+export class RelaysUnavailableError extends Error {
+    constructor(failures) {
+        super(`none of this account's relays answered: ${failures.map((f) => `${f.relayUrl} (${f.kind})`).join(', ')}`);
+        this.failures = failures;
+        this.name = 'RelaysUnavailableError';
+        this.relays = failures.map((f) => f.relayUrl);
+    }
+    /** Every relay refused its attestation: retrying will not help. */
+    get refused() {
+        return this.failures.every((f) => f.kind === 'refused');
+    }
+}
+/**
+ * One relay's client for a listing, or the failure that stopped it. The key's
+ * own outcome is kept, so a refused attestation is not reported as a relay
+ * that merely did not answer.
+ */
+async function listingClient(s, relayUrl) {
+    const key = await attemptRelayNodeKey(relayUrl);
+    if (key.kind !== 'learned') {
+        console.warn('[mero-js] could not learn the relay node key from its attestation', key.error);
+        return { failure: { relayUrl, kind: key.kind, error: key.error } };
+    }
+    const client = buildDelegatedClient({ ...s, relayUrl }, null);
+    if (!client)
+        return { failure: { relayUrl, kind: 'unavailable', error: new Error(`no client for ${relayUrl}`) } };
+    return { client };
+}
 /**
  * This account's contexts on every relay it knows, each tagged with the relay
  * that listed it — and that relay recorded as the one serving it.
  *
  * Each relay answers only for itself and only for this caller, so the union is
  * exactly the account's contexts across relays. A relay that cannot be reached
- * or logged in to is skipped (its contexts simply do not appear), not fatal.
+ * or logged in to is skipped (its contexts simply do not appear), not fatal,
+ * unless it is every relay: then {@link RelaysUnavailableError}.
  */
 export async function listDelegatedContexts(s) {
     const out = [];
     const map = readRelayMap(s.account);
-    for (const relayUrl of knownRelays(s)) {
+    const relays = knownRelays(s);
+    const failures = [];
+    for (const relayUrl of relays) {
+        const got = await listingClient(s, relayUrl);
+        if ('failure' in got) {
+            failures.push(got.failure);
+            continue;
+        }
+        const { client } = got;
         try {
-            if (!(await resolveRelayNodeKey(relayUrl)))
-                continue;
-            const client = buildDelegatedClient({ ...s, relayUrl }, null);
-            if (!client)
-                continue;
             const { contexts } = await client.admin.getContexts();
             for (const c of contexts ?? []) {
                 out.push({ ...c, relayUrl });
@@ -829,30 +864,37 @@ export async function listDelegatedContexts(s) {
             }
         }
         catch (e) {
+            failures.push({ relayUrl, kind: 'unavailable', error: e });
             console.warn(`[mero-js] could not list contexts on ${relayUrl}`, e);
         }
     }
     writeRelayMap(s.account, map);
+    if (relays.length > 0 && failures.length === relays.length)
+        throw new RelaysUnavailableError(failures);
     return out;
 }
 /**
  * This account's namespaces on every relay it knows, each tagged with the relay
  * that listed it and recorded as that namespace's relay. Same rules as
  * {@link listDelegatedContexts}: each relay answers for itself and this caller
- * only (`namespace:list-own`); an unreachable relay is skipped.
+ * only (`namespace:list-own`); an unreachable relay is skipped, and every
+ * relay unreachable is {@link RelaysUnavailableError}.
  */
 export async function listDelegatedNamespaces(s) {
     var _a, _b;
     const out = [];
     const seen = new Set();
     const map = readRelayMap(s.account);
-    for (const relayUrl of knownRelays(s)) {
+    const relays = knownRelays(s);
+    const failures = [];
+    for (const relayUrl of relays) {
+        const got = await listingClient(s, relayUrl);
+        if ('failure' in got) {
+            failures.push(got.failure);
+            continue;
+        }
+        const { client } = got;
         try {
-            if (!(await resolveRelayNodeKey(relayUrl)))
-                continue;
-            const client = buildDelegatedClient({ ...s, relayUrl }, null);
-            if (!client)
-                continue;
             for (const ns of await client.admin.listNamespaces()) {
                 if (seen.has(ns.namespaceId))
                     continue;
@@ -862,9 +904,12 @@ export async function listDelegatedNamespaces(s) {
             }
         }
         catch (e) {
+            failures.push({ relayUrl, kind: 'unavailable', error: e });
             console.warn(`[mero-js] could not list namespaces on ${relayUrl}`, e);
         }
     }
     writeRelayMap(s.account, map);
+    if (relays.length > 0 && failures.length === relays.length)
+        throw new RelaysUnavailableError(failures);
     return out;
 }

package/dist/admin-api/redeem-invitation.js

@@ -16,6 +16,7 @@
 // the request resolving, and the namespace being listed. Either one is enough,
 // which matters because either one can be missing.
 import { classifyError, messageOf } from '../errors/classify.js';
+import { RelayLoginError } from '../account/relay-login-error.js';
 /** Whether an outcome means the invitation is finished with. */
 export function isSettled(outcome) {
     return outcome.status !== 'failed' || !outcome.retryable;
@@ -111,6 +112,11 @@ const FINAL_FROM_TEXT = new Set(['already-used', 'removed']);
  * invitation, and a 404 is not specific enough to throw a link away on.
  */
 function classifyJoinFailure(err, message) {
+    // The join never left: the relay session it needed could not be minted. Says
+    // nothing about the invitation, which is kept for after a sign-in or a retry.
+    if (err instanceof RelayLoginError) {
+        return { reason: err.kind === 'signed-out' ? 'signed-out' : 'node-unreachable', retryable: true };
+    }
     const { kind, status } = classifyError(err);
     const fromText = reasonFromMessage(message);
     // A code is the node naming the refusal itself: nothing below can know better.

package/dist/errors/classify.js

@@ -1,16 +1,4 @@
-// ── What a failed request means, in terms a caller can act on ────────────────
-//
-// Core rc.56 onwards (calimero-network/core#4151 to #4164) answers a refused
-// admin request with the status that names the refusal: a malformed body is a
-// 400, a caller the node will not serve a 403, a missing resource a 404, a
-// state the request contradicts (an expired invitation, a removed member) a
-// 409, an oversized upload a 413, and a request the node cannot serve *yet*
-// (no member online to hand over a group key) a 503. Before that, every one of
-// them was a bare 500 and the only way to tell them apart was to match text.
-//
-// Every caller asks the same two questions of such an error: what kind of
-// failure is this, and would doing it again later help? This answers both once,
-// so apps stop keeping their own copies of the status table.
+import { RelayLoginError } from '../account/relay-login-error.js';
 const RETRYABLE = {
     invalid: false,
     // The session, not the request: signing in again and repeating it works.
@@ -106,6 +94,14 @@ export function messageOf(err, fallback = 'Request failed') {
  * own status-0 `HTTPError`.
  */
 export function classifyError(err) {
+    // A relay login that failed before the request was sent: its own status is
+    // about the login, so it is read by what it means for the request — a
+    // refused credential is this client's session, anything else the relay's.
+    if (err instanceof RelayLoginError) {
+        const status = err.loginStatus;
+        const kind = err.kind === 'signed-out' ? 'unauthorized' : status ? kindForStatus(status) : 'unreachable';
+        return { kind, status, retryable: RETRYABLE[kind], message: messageOf(err) };
+    }
     const status = statusOf(err);
     let kind;
     if (status !== undefined) {

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

@@ -1,6 +1,6 @@
 export * from './http-types.js';
 export * from './api-response.js';
-export { WebHttpClient, HTTPError, AuthRevokedError } from './web-client.js';
+export { WebHttpClient, HTTPError, AuthRevokedError, RequestAuthError } from './web-client.js';
 export { createHttpClient, createBrowserHttpClient, createNodeHttpClient, createUniversalHttpClient, } from './http-factory.js';
 export { withRetry, createRetryableMethod } from './retry.js';
 export type { RetryOptions } from './retry.js';

package/dist/http-client/index.js

@@ -2,7 +2,7 @@
 export * from './http-types.js';
 export * from './api-response.js';
 // Web Standards HTTP client implementation
-export { WebHttpClient, HTTPError, AuthRevokedError } from './web-client.js';
+export { WebHttpClient, HTTPError, AuthRevokedError, RequestAuthError } from './web-client.js';
 // Factory functions for easy client creation
 export { createHttpClient, createBrowserHttpClient, createNodeHttpClient, createUniversalHttpClient, } from './http-factory.js';
 // Retry functionality

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

@@ -36,6 +36,19 @@ 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);
 }
+/**
+ * A failure of a transport's `getAuthToken` that must stop the request.
+ *
+ * Any other error from `getAuthToken` is ignored and the request goes out
+ * without a token, which is right for a credential that is merely absent. This
+ * one says the credential could not be obtained at all — the login it needed
+ * was refused, or never reached the server — so sending the request anyway
+ * would only trade the real cause for the server's 401, or for the same
+ * transport error a second time. Thrown as is from the request.
+ */
+export declare class RequestAuthError extends Error {
+    name: string;
+}
 /** Whether `headers` carry a request proof, which must never follow a redirect. */
 export declare function carriesProof(headers: Record<string, string>): boolean;
 /**

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

@@ -87,6 +87,22 @@ export class AuthRevokedError extends HTTPError {
         this.message = `Authentication revoked (${reason}): HTTP ${status} ${statusText}`;
     }
 }
+/**
+ * A failure of a transport's `getAuthToken` that must stop the request.
+ *
+ * Any other error from `getAuthToken` is ignored and the request goes out
+ * without a token, which is right for a credential that is merely absent. This
+ * one says the credential could not be obtained at all — the login it needed
+ * was refused, or never reached the server — so sending the request anyway
+ * would only trade the real cause for the server's 401, or for the same
+ * transport error a second time. Thrown as is from the request.
+ */
+export class RequestAuthError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'RequestAuthError';
+    }
+}
 // Helper function to convert Headers to Record
 function headersToRecord(headers) {
     const record = {};
@@ -477,7 +493,10 @@ export class WebHttpClient {
                 }
             }
             catch (error) {
-                // Ignore auth token errors
+                // A credential that could not be obtained stops the request; any other
+                // failure leaves it unauthenticated, as before.
+                if (error instanceof RequestAuthError)
+                    throw error;
             }
         }
         // Add init headers