@calimero-network/mero-js 24.1.2 → 24.2.0

package/dist/account/create-context.d.ts

@@ -63,10 +63,8 @@ export declare function createDelegatedPrivateContext(s: DelegatedSession, req:
  * TEE relay admits itself as its first TEE), so contexts can be created in it
  * through the same relay straight away.
  *
- * The relay's executor account cannot be asked about a namespace that does
- * not exist yet, so it is the session's `executorAccount` when the app named
- * one, else learned from a namespace the account already has on that relay. A
- * brand-new account with neither is told how to get one.
+ * The relay's executor account and key cannot be asked about a namespace that
+ * does not exist yet; see {@link foundingExecutor} for where they come from.
  */
 export declare function foundDelegatedNamespace(s: DelegatedSession, req?: {
     readonly defaultCapabilities?: number;

package/dist/account/create-context.js

@@ -13,7 +13,7 @@
 import { AccountHaRefusedError, AccountNotLinkedError, CloudClient, } from '../cloud/index.js';
 import { memberAddedOp, subgroupCreation, } from '../warrant/index.js';
 import { RelayClient, } from '../relay/index.js';
-import { knownRelays, markContextNonceSpent, readRelayMap, rememberRelay } from './session.js';
+import { attemptRelayNodeKey, knownRelays, markContextNonceSpent, readRelayMap, rememberRelay, } from './session.js';
 import { fetchRegistryBundles, selectLatestBundle } from './application-id.js';
 /**
  * A governance warrant's nonce, for one (relay, group): spent in a sliding
@@ -115,29 +115,20 @@ export async function createDelegatedPrivateContext(s, req, deps = {}) {
  * TEE relay admits itself as its first TEE), so contexts can be created in it
  * through the same relay straight away.
  *
- * The relay's executor account cannot be asked about a namespace that does
- * not exist yet, so it is the session's `executorAccount` when the app named
- * one, else learned from a namespace the account already has on that relay. A
- * brand-new account with neither is told how to get one.
+ * The relay's executor account and key cannot be asked about a namespace that
+ * does not exist yet; see {@link foundingExecutor} for where they come from.
  */
 export async function foundDelegatedNamespace(s, req = {}, deps = {}) {
     const relays = knownRelays(s).map((u) => u.replace(/\/+$/, ''));
     const relay = relays[0];
     if (!relay)
         throw new Error('no relay is known for this account, so there is nowhere to found a namespace');
-    const known = Object.entries(readRelayMap(s.account).namespaces).find(([, url]) => url.replace(/\/+$/, '') === relay)?.[0];
-    // The session's relay may come with its account (the cloud names it), which
-    // is all founding needs; otherwise it is learned from a namespace on it.
-    const named = s.executorAccount && s.relayUrl && s.relayUrl.replace(/\/+$/, '') === relay ? s.executorAccount : null;
-    if (!named && !known) {
-        throw new Error("the executor account of this relay is not known: join a namespace on it first, or connect with the relay's executor account (the cloud shows it beside the relay)");
-    }
-    const executorAccount = named ?? (await client(s, relay, governanceNonce(relay, known), deps.fetch).describeGovernance(known)).executorAccount;
+    const executor = await foundingExecutor(s, relay, deps.fetch);
     // The founding warrant and, with a default mask, a second one are both spent
     // in the NEW namespace's window, which is empty: any rising pair will do.
     let next = BigInt(Date.now());
     const founded = await client(s, relay, { next: async () => next++ }, deps.fetch).foundNamespace({
-        executorAccount,
+        executor,
         ...(req.defaultCapabilities !== undefined ? { defaultCapabilities: req.defaultCapabilities } : {}),
         ...(req.application ? { application: req.application } : {}),
     });
@@ -165,6 +156,35 @@ export async function foundDelegatedNamespace(s, req = {}, deps = {}) {
         };
     return { namespaceId: founded.namespaceId, teeEnabled: founded.teeEnabled, ...ha };
 }
+/**
+ * The relay's pinned or attested node key, which is the key it signs with, and
+ * its account: the session's (the cloud names it), else a remembered namespace's.
+ */
+async function foundingExecutor(s, relay, fetch) {
+    const named = s.executorAccount && s.relayUrl?.replace(/\/+$/, '') === relay ? s.executorAccount : null;
+    if (named)
+        return { executorAccount: named, executorKey: await attestedNodeKey(relay) };
+    const known = Object.entries(readRelayMap(s.account).namespaces).find(([, url]) => url.replace(/\/+$/, '') === relay)?.[0];
+    if (!known) {
+        throw new Error("the executor account of this relay is not known: join a namespace on it first, or connect with the relay's executor account (the cloud shows it beside the relay)");
+    }
+    const executorKey = await attestedNodeKey(relay);
+    // Discovery is unauthenticated: it may name the account, never the key.
+    const described = await client(s, relay, governanceNonce(relay, known), fetch).describeGovernance(known);
+    if (described.executorKey?.toLowerCase() !== executorKey) {
+        throw new Error(`the relay's discovery names signing key ${described.executorKey}, not the relay's node key ${executorKey}: refusing to found through it`);
+    }
+    return { executorAccount: described.executorAccount, executorKey };
+}
+/** The relay's pinned or attested node key; any failed attestation throws. */
+async function attestedNodeKey(relay) {
+    const key = await attemptRelayNodeKey(relay);
+    if (key.kind === 'learned')
+        return key.nodeKey;
+    throw new Error(key.kind === 'unavailable'
+        ? "the relay's signing key could not be learned: its attestation did not answer, try again"
+        : "the relay's attestation was refused, so founding through it is not possible (only a key from its operator, pinned with pinRelayNodeKey, can stand in)");
+}
 /** What an app can tell a person whose account the cloud cannot place. */
 export const HA_ACCOUNT_NOT_LINKED_MESSAGE = 'link this account to your cloud user in the wallet so invitees can find this namespace';
 /**

package/dist/account/session.d.ts

@@ -47,8 +47,9 @@ export interface DelegatedSession extends DelegatedCredential {
      * The relay's executor account, hex, when the app knows it — the cloud's
      * machine page names it beside the relay's address.
      *
-     * Founding a namespace through a relay names the relay's account in the
-     * warrant, and a namespace that does not exist yet cannot be asked for it.
+     * Founding a namespace through a relay names the relay's account (and its
+     * node key) in the warrant, and a namespace that does not exist yet cannot be
+     * asked for them.
      * Without this the account learns it from a namespace it is already in, so a
      * brand-new account would have to join one first; with it, the account founds
      * on `relayUrl` directly.

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

@@ -231,12 +231,12 @@ export declare class AdminApiClient {
      * anything.
      *
      * The two facts {@link performIntent} needs and a client cannot derive: whose
-     * account goes in the warrant's `executor`, and whether this node holds
-     * `CAN_AUTHOR_ON_BEHALF` on the owning group. `canAuthorOnBehalf: false` comes
-     * back as an answer rather than an error — it is the default state of every
-     * context — so a caller can say "an admin of `groupId` must grant it to
-     * `executorAccount`" instead of presenting a warrant that will be refused
-     * after the author has spent a nonce on it.
+     * account and key go in the warrant's `executor` and `executor_key`, and
+     * whether this node holds `CAN_AUTHOR_ON_BEHALF` on the owning group.
+     * `canAuthorOnBehalf: false` comes back as an answer rather than an error, as
+     * it is the default state of every context, so a caller can say "an admin of
+     * `groupId` must grant it to `executorAccount`" instead of presenting a
+     * warrant that will be refused after the author has spent a nonce on it.
      *
      * `404` means the context belongs to no group, or this node holds no account
      * yet; either way it can be named as no warrant's executor.

package/dist/admin-api/admin-client.js

@@ -563,12 +563,12 @@ export class AdminApiClient {
      * anything.
      *
      * The two facts {@link performIntent} needs and a client cannot derive: whose
-     * account goes in the warrant's `executor`, and whether this node holds
-     * `CAN_AUTHOR_ON_BEHALF` on the owning group. `canAuthorOnBehalf: false` comes
-     * back as an answer rather than an error — it is the default state of every
-     * context — so a caller can say "an admin of `groupId` must grant it to
-     * `executorAccount`" instead of presenting a warrant that will be refused
-     * after the author has spent a nonce on it.
+     * account and key go in the warrant's `executor` and `executor_key`, and
+     * whether this node holds `CAN_AUTHOR_ON_BEHALF` on the owning group.
+     * `canAuthorOnBehalf: false` comes back as an answer rather than an error, as
+     * it is the default state of every context, so a caller can say "an admin of
+     * `groupId` must grant it to `executorAccount`" instead of presenting a
+     * warrant that will be refused after the author has spent a nonce on it.
      *
      * `404` means the context belongs to no group, or this node holds no account
      * yet; either way it can be named as no warrant's executor.

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

@@ -435,9 +435,8 @@ export interface PerformIntentRequest {
      * Hex-encoded borsh of the author's `AccountProof<DeviceCert>`, proving the
      * key that signed the warrant is a device of the account it names.
      *
-     * Only the author's own half. The node attaches its own credential, so a
-     * caller never learns which of the node's processes runs the intent — and a
-     * re-key on its side does not void a warrant already issued.
+     * Only the author's own half. The node attaches its own credential, which must
+     * match the `executor` and `executor_key` the warrant names.
      */
     authorProof: string;
 }
@@ -477,22 +476,22 @@ export interface PerformIntentResponseData {
  * warrant, not after being refused one.
  *
  * Every input to a warrant is something the author already holds except two:
- * whose name goes in `executor`, and whether that node may act here at all. Both
- * belong to the node, so both are answered here, on the path the intent will be
- * presented to.
+ * whose account and key go in `executor` and `executor_key`, and whether that
+ * node may act here at all. Both belong to the node, so both are answered here,
+ * on the path the intent will be presented to.
  *
  * Reading it first is what lets a client fail before signing. A warrant spends a
  * nonce from a monotonic per-device sequence, and one naming the wrong executor
  * is unspendable — the number is gone and the write never happened.
  */
 export interface IntentRelayInfo {
+    /** The account a warrant for this node must name as its `executor`, 64 hex. */
+    executorAccount: string;
     /**
-     * The account a warrant for this node must name as its `executor`, 64 hex.
-     *
-     * An account, not the node's signing key: one of its processes re-keying must
-     * not void warrants already issued to it.
+     * The signing key a warrant for this node must name as its `executor_key`, 64
+     * hex: the one device that may spend it. A re-key voids unspent warrants.
      */
-    executorAccount: string;
+    executorKey: string;
     /**
      * Whether this node holds `CAN_AUTHOR_ON_BEHALF` on the group owning the
      * context.