@calimero-network/mero-js 23.5.0 → 23.7.0

package/dist/admin-api/admin-types.d.ts

@@ -1714,6 +1714,20 @@ export interface IssueOwnershipProofResponseData {
     signedPayload: string;
     /** Base64 64-byte ed25519 signature. */
     signature: string;
+    /**
+     * Namespace proofs only: what the namespace id was derived from. Not signed;
+     * the id commits to it. With {@link credential}, it is what lets the cloud
+     * check that the signer is a node of the account that FOUNDED the namespace
+     * (mdma refuses a namespace proof without both). Absent on nodes that predate
+     * it, and on context proofs.
+     */
+    founding?: NamespaceFounding;
+    /**
+     * Namespace proofs only: hex borsh `AccountProof<DeviceCert>` — the node's join
+     * credential, whose account root certifies `signerPublicKey`. See
+     * {@link founding}.
+     */
+    credential?: string;
 }
 export interface CreateGroupInvitationRequest {
     expirationTimestamp?: number;

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;
@@ -624,7 +656,11 @@ export declare class CloudClient {
      * Pass merod's response object straight through. The cloud accepts core's
      * `signerPublicKey`/`signedPayload` casing as well as snake_case, so there is
      * no re-keying step — and getting that wrong used to surface as a `422`
-     * naming three missing fields.
+     * naming three missing fields. Passing it whole also carries the `founding`
+     * and `credential` merod attaches: the cloud accepts a namespace proof only
+     * from a node of the account that founded the namespace, checked with those
+     * two, and only when that account is linked to this login. A node that
+     * predates them, or an admin that did not found the namespace, gets a `422`.
      *
      * Idempotent for the same account. A namespace already claimed by someone
      * else is a `409`; a replayed proof nonce is a `403`.

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
@@ -528,7 +567,11 @@ export class CloudClient {
      * Pass merod's response object straight through. The cloud accepts core's
      * `signerPublicKey`/`signedPayload` casing as well as snake_case, so there is
      * no re-keying step — and getting that wrong used to surface as a `422`
-     * naming three missing fields.
+     * naming three missing fields. Passing it whole also carries the `founding`
+     * and `credential` merod attaches: the cloud accepts a namespace proof only
+     * from a node of the account that founded the namespace, checked with those
+     * two, and only when that account is linked to this login. A node that
+     * predates them, or an admin that did not found the namespace, gets a `422`.
      *
      * Idempotent for the same account. A namespace already claimed by someone
      * else is a `409`; a replayed proof nonce is a `403`.
@@ -598,6 +641,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 +651,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