@calimero-network/mero-js 23.5.0 → 23.6.0

package/dist/cloud/account-ownership.d.ts

@@ -37,7 +37,15 @@ export interface AccountOwnershipClaimInput extends AccountClaimBase {
  * Input for {@link signAccountHaClaim}: the same as the session claim, minus
  * `subject` — there is no login to bind it to.
  */
-export type AccountHaClaimInput = AccountClaimBase;
+export interface AccountHaClaimInput extends AccountClaimBase {
+    /**
+     * The relay that founded the namespace (the delegated session's `relayUrl`).
+     * Signed into the claim so nobody forwarding it can swap it: the cloud
+     * resolves it to one of its own fleet relays and hands that relay's
+     * addresses to the fleet node as its admitter. Leave it out when unknown.
+     */
+    relayUrl?: string;
+}
 /** The audience of the session route's claim (`/api/cloud/me/...`). */
 export declare const ACCOUNT_OWNERSHIP_AUDIENCE = "mdma:enable-ha-namespace";
 /** The audience of the anonymous account route's claim (`/api/cloud/accounts/...`). */

package/dist/cloud/account-ownership.js

@@ -19,6 +19,8 @@ const DOMAIN = new TextEncoder().encode('calimero.mdma.account-ownership-claim.v
 /** What the cloud accepts; it caps a claim's lifetime at five minutes. */
 const DEFAULT_TTL_MS = 60000;
 const MAX_TTL_MS = 5 * 60000;
+/** The cloud's limit on `relay_url`. */
+const MAX_RELAY_URL = 1024;
 /** The audience of the session route's claim (`/api/cloud/me/...`). */
 export const ACCOUNT_OWNERSHIP_AUDIENCE = 'mdma:enable-ha-namespace';
 /** The audience of the anonymous account route's claim (`/api/cloud/accounts/...`). */
@@ -39,7 +41,10 @@ const hex32 = (value, what) => {
  * session claim keeps its exact field order and the account claim has no
  * `subject` key at all (not a null one: the cloud tells the two apart by it).
  */
-async function signClaim(input, audience, subject) {
+async function signClaim(input, audience, subject, relayUrl) {
+    if (relayUrl !== undefined && !(relayUrl.length > 0 && relayUrl.length <= MAX_RELAY_URL)) {
+        throw new Error(`relayUrl must be a non-empty string of at most ${MAX_RELAY_URL} characters`);
+    }
     const ttl = input.ttlMs ?? DEFAULT_TTL_MS;
     if (!(ttl > 0 && ttl <= MAX_TTL_MS))
         throw new Error(`ttlMs must be in (0, ${MAX_TTL_MS}]`);
@@ -59,6 +64,7 @@ async function signClaim(input, audience, subject) {
         nonce,
         issued_at_ms: issued,
         expires_at_ms: issued + ttl,
+        ...(relayUrl === undefined ? {} : { relay_url: relayUrl }),
     }));
     const signature = await signer.sign(concat(DOMAIN, payload));
     return { kind: 'account', credential: input.credential, signed_payload: base64(payload), signature: base64(signature) };
@@ -77,5 +83,5 @@ export async function signAccountOwnershipClaim(input) {
  * through the account's wallet link instead.
  */
 export async function signAccountHaClaim(input) {
-    return signClaim(input, ACCOUNT_HA_AUDIENCE, undefined);
+    return signClaim(input, ACCOUNT_HA_AUDIENCE, undefined, input.relayUrl);
 }

package/dist/cloud/cloud-client.d.ts

@@ -381,9 +381,15 @@ export interface EnableHaAsAccountOptions {
     signer?: Signer;
     /** The claim's lifetime in ms; default one minute, at most five. */
     ttlMs?: number;
+    /**
+     * The relay that founded the namespace (the delegated session's `relayUrl`).
+     * The cloud gives that relay to the fleet node as its admitter; without it
+     * the node has to find the relay by discovery.
+     */
+    relayUrl?: string;
 }
 /**
- * The cloud's two refusals of {@link CloudClient.enableHaAsAccount} that a
+ * The cloud's refusals of {@link CloudClient.enableHaAsAccount} that a
  * person can do something about. Both are `409`s with `{"error": code}`.
  *
  * Extends {@link HTTPError}, so `instanceof HTTPError` handling still catches it.
@@ -414,6 +420,32 @@ export declare class AccountLinkedToSeveralUsersError extends AccountHaRefusedEr
     name: string;
     static readonly CODE = "account_linked_to_several_users";
 }
+/**
+ * `ha_request_pending` (409): another namespace of this account is waiting for
+ * its first fleet node to be admitted. The route allows one at a time; it
+ * clears once that node is admitted, or by disabling HA on it from a cloud
+ * session. The claim was not spent.
+ */
+export declare class HaRequestPendingError extends AccountHaRefusedError {
+    name: string;
+    static readonly CODE = "ha_request_pending";
+}
+/**
+ * `unknown_relay` (422): the cloud runs no relay at `relayUrl`. The claim was
+ * not spent.
+ */
+export declare class UnknownRelayError extends AccountHaRefusedError {
+    name: string;
+    static readonly CODE = "unknown_relay";
+}
+/**
+ * `relay_not_dialable` (422): the relay is the cloud's but has not reported
+ * its addresses yet. The claim was not spent; retrying later can succeed.
+ */
+export declare class RelayNotDialableError extends AccountHaRefusedError {
+    name: string;
+    static readonly CODE = "relay_not_dialable";
+}
 export declare class CloudClient {
     private baseUrl;
     private session;

package/dist/cloud/cloud-client.js

@@ -67,7 +67,7 @@ export function pickExecutingRelay(relays) {
     return (relays.find((r) => r.canExecute && r.relayUrl !== null && r.executorAccount !== null) ?? null);
 }
 /**
- * The cloud's two refusals of {@link CloudClient.enableHaAsAccount} that a
+ * The cloud's refusals of {@link CloudClient.enableHaAsAccount} that a
  * person can do something about. Both are `409`s with `{"error": code}`.
  *
  * Extends {@link HTTPError}, so `instanceof HTTPError` handling still catches it.
@@ -105,6 +105,45 @@ export class AccountLinkedToSeveralUsersError extends AccountHaRefusedError {
     }
 }
 AccountLinkedToSeveralUsersError.CODE = 'account_linked_to_several_users';
+/**
+ * `ha_request_pending` (409): another namespace of this account is waiting for
+ * its first fleet node to be admitted. The route allows one at a time; it
+ * clears once that node is admitted, or by disabling HA on it from a cloud
+ * session. The claim was not spent.
+ */
+export class HaRequestPendingError extends AccountHaRefusedError {
+    constructor() {
+        super(...arguments);
+        this.name = 'HaRequestPendingError';
+    }
+}
+HaRequestPendingError.CODE = 'ha_request_pending';
+/**
+ * `unknown_relay` (422): the cloud runs no relay at `relayUrl`. The claim was
+ * not spent.
+ */
+export class UnknownRelayError extends AccountHaRefusedError {
+    constructor() {
+        super(...arguments);
+        this.name = 'UnknownRelayError';
+    }
+}
+UnknownRelayError.CODE = 'unknown_relay';
+/**
+ * `relay_not_dialable` (422): the relay is the cloud's but has not reported
+ * its addresses yet. The claim was not spent; retrying later can succeed.
+ */
+export class RelayNotDialableError extends AccountHaRefusedError {
+    constructor() {
+        super(...arguments);
+        this.name = 'RelayNotDialableError';
+    }
+}
+RelayNotDialableError.CODE = 'relay_not_dialable';
+const ACCOUNT_HA_REFUSALS = {
+    409: [AccountNotLinkedError, AccountLinkedToSeveralUsersError, HaRequestPendingError],
+    422: [UnknownRelayError, RelayNotDialableError],
+};
 /**
  * The `error` code of a 409 body. Accepts `{"error": code}` (the contract) and
  * FastAPI's `{"detail": code}` / `{"detail": {"error": code}}`, so how the
@@ -598,6 +637,7 @@ export class CloudClient {
             deviceSecret: options.deviceSecret,
             signer: options.signer,
             ttlMs: options.ttlMs,
+            relayUrl: options.relayUrl,
         });
         // The path carries the ids as the claim does — lowercase hex — so a caller
         // that kept them uppercase does not address a different resource.
@@ -607,13 +647,9 @@ export class CloudClient {
             return await this.request('POST', `/api/cloud/accounts/${encodeURIComponent(account)}/namespaces/${encodeURIComponent(namespace)}/enable-ha`, { body: { ownership_proof: proof }, anonymous: true });
         }
         catch (err) {
-            if (err instanceof HTTPError && err.status === 409) {
+            if (err instanceof HTTPError && ACCOUNT_HA_REFUSALS[err.status]) {
                 const code = conflictCode(err.bodyText);
-                const Typed = code === AccountNotLinkedError.CODE
-                    ? AccountNotLinkedError
-                    : code === AccountLinkedToSeveralUsersError.CODE
-                        ? AccountLinkedToSeveralUsersError
-                        : undefined;
+                const Typed = ACCOUNT_HA_REFUSALS[err.status].find((t) => t.CODE === code);
                 if (Typed && code) {
                     throw new Typed(code, err.status, err.statusText, err.url, err.headers, err.bodyText);
                 }

package/dist/cloud/index.d.ts

@@ -1,4 +1,4 @@
-export { CloudClient, admitterAddrsFromNetworkStatus, AccountHaRefusedError, AccountNotLinkedError, AccountLinkedToSeveralUsersError, } from './cloud-client.js';
+export { CloudClient, admitterAddrsFromNetworkStatus, AccountHaRefusedError, AccountNotLinkedError, AccountLinkedToSeveralUsersError, HaRequestPendingError, UnknownRelayError, RelayNotDialableError, } from './cloud-client.js';
 export type { CloudClientConfig, CloudSession, CloudNamespace, CloudRelay, CloudAccountRelay, CloudNamespaceNode, CloudNamespaceRouting, CloudMachine, CloudMachineNamespace, CloudLinkedAccount, CloudLinkedAccounts, CloudAccountLink, AccountLinkChallenge, AccountLinkProof, AccountLinkHandoff, AccountLinkCallback, AccountLoginChallenge, AccountLoginProof, EnableHAOptions, DisableHAOptions, EnableHaAsAccountOptions, } from './cloud-client.js';
 export { connectCloud, connectCloudWithAccount } from './connect.js';
 export type { ConnectCloudOptions, ConnectCloudWithAccountOptions, CloudConnection, } from './connect.js';

package/dist/cloud/index.js

@@ -1,4 +1,4 @@
-export { CloudClient, admitterAddrsFromNetworkStatus, AccountHaRefusedError, AccountNotLinkedError, AccountLinkedToSeveralUsersError, } from './cloud-client.js';
+export { CloudClient, admitterAddrsFromNetworkStatus, AccountHaRefusedError, AccountNotLinkedError, AccountLinkedToSeveralUsersError, HaRequestPendingError, UnknownRelayError, RelayNotDialableError, } from './cloud-client.js';
 export { connectCloud, connectCloudWithAccount } from './connect.js';
 export { signRoutingChallenge, routingProofHeaders } from './routing-proof.js';
 // Linking an account to a cloud login from a browser — the redirect half the