@calimero-network/mero-js 24.6.0 → 24.7.0

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 { attemptRelayNodeKey, knownRelays, markContextNonceSpent, readRelayMap, rememberRelay, } from './session.js';
+import { attemptRelayNodeKey, knownRelays, markContextNonceSpent, readRelayMap, relayTransportFetch, rememberRelay, } from './session.js';
 import { fetchRegistryBundles, selectLatestBundle } from './application-id.js';
 /**
  * A governance warrant's nonce, for one (relay, group): spent in a sliding
@@ -55,7 +55,11 @@ function initArgsOf(params) {
         return {};
     return JSON.parse(new TextDecoder().decode(Uint8Array.from(params)));
 }
-/** A relay client for these calls: the author's credential, whatever nonces the call needs. */
+/**
+ * A relay client for these calls: the author's credential, whatever nonces the
+ * call needs, and the relay's sealed transport unless the caller brings its own
+ * `fetch` (see `relayTransportFetch`).
+ */
 function client(s, relayUrl, nonces, fetch) {
     return new RelayClient({
         relayUrl,
@@ -63,7 +67,7 @@ function client(s, relayUrl, nonces, fetch) {
         authorProof: s.credential,
         deviceSecret: s.deviceSecret,
         nonces,
-        fetch,
+        fetch: fetch ?? relayTransportFetch(relayUrl),
     });
 }
 export async function createDelegatedContext(s, req, deps = {}) {
@@ -176,14 +180,21 @@ async function foundingExecutor(s, relay, fetch) {
     }
     return { executorAccount: described.executorAccount, executorKey };
 }
-/** The relay's pinned or attested node key; any failed attestation throws. */
+/**
+ * The relay's node key, attested now; any failed attestation throws.
+ *
+ * Never the pin alone: the relay founded through becomes the namespace's first
+ * TEE and holds its keys, so it is checked against the signed release on the
+ * day it is trusted with them, not on whichever day its key was pinned. A key
+ * pinned by hand therefore no longer stands in for an attestation here.
+ */
 async function attestedNodeKey(relay) {
-    const key = await attemptRelayNodeKey(relay);
+    const key = await attemptRelayNodeKey(relay, { fresh: true });
     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)");
+        : "the relay's attestation was refused, so founding through it is not possible: it is not a signed locked-read-only release");
 }
 /** 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/index.d.ts

@@ -5,7 +5,7 @@ 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, 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, } 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';

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, 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, } 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';

package/dist/account/session.d.ts

@@ -124,7 +124,21 @@ export type RelayNodeKeyAttempt = {
     kind: 'refused';
     error: unknown;
 };
-export declare function attemptRelayNodeKey(relayUrl: string): Promise<RelayNodeKeyAttempt>;
+/**
+ * The relay's node key: the pinned one, or else learned from the relay's TEE
+ * attestation (see mero-js `attestRelayNodeKey`) and pinned for next time.
+ *
+ * A mock quote proves nothing about hardware, so one is accepted only from a
+ * loopback relay — a local rig. A real one must be a signed release of the
+ * trusted profile ({@link relayQuoteVerifier}).
+ *
+ * `fresh` skips the pin and attests now, for a step that hands the relay
+ * something it keeps — founding a namespace through it. A pinned key was
+ * checked once, on some earlier day, against whatever answered then.
+ */
+export declare function attemptRelayNodeKey(relayUrl: string, options?: {
+    fresh?: boolean;
+}): Promise<RelayNodeKeyAttempt>;
 /**
  * The relay's node key: the pinned one, or else learned from the relay's TEE
  * attestation in one attempt; `null` when that attempt did not learn it, for
@@ -151,6 +165,14 @@ export declare const RELAY_NODE_KEY_RETRY_MS: readonly number[];
 export declare function learnRelayNodeKey(relayUrl: string, options?: {
     signal?: AbortSignal;
 }): Promise<string | null>;
+/** Forget every relay's sealed transport. For tests. */
+export declare function forgetRelaySealing(): void;
+/**
+ * The `fetch` a delegated session uses for `relayUrl`: sealed to its attested
+ * TD, one per relay so its session is shared. `undefined` for a loopback relay,
+ * a dev rig answering mock quotes, which keeps the global `fetch`.
+ */
+export declare function relayTransportFetch(relayUrl: string): typeof fetch | undefined;
 /** Forget what was learned about which methods read. For tests. */
 export declare function forgetMethodKinds(): void;
 /**

package/dist/account/session.js

@@ -14,7 +14,7 @@
  * the same application code in both.
  */
 import { attestRelayNodeKey, } from '../relay-attestation/index.js';
-import { cloudNodeReleaseUrl, createSignedReleaseVerifier, DEFAULT_RELEASE_MIRROR, fetchNodeRelease, fetchNodeReleaseVersion, } from '../sealed/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 { SseClient, } from '../events/index.js';
@@ -222,15 +222,6 @@ function isLoopback(relayUrl) {
         return false;
     }
 }
-/**
- * The relay's node key: the pinned one, or else learned from the relay's TEE
- * attestation (see mero-js `attestRelayNodeKey`) and pinned for next time.
- *
- * A mock quote proves nothing about hardware, so one is accepted only from a
- * loopback relay — a local rig. A real quote needs signature and measurement
- * verification this client does not do yet, so a real relay still needs its
- * key pinned; `null` then, and admin reads and events stay off.
- */
 /** The one relay image trusted: no shell, so nobody reads the TD. */
 const TRUSTED_RELAY_PROFILE = 'locked-read-only';
 /**
@@ -342,8 +333,20 @@ function relayQuoteVerifier(relayUrl, fetchRelay) {
     };
     return Object.assign(verify, { includeCollateral: true });
 }
-export async function attemptRelayNodeKey(relayUrl) {
-    const pinned = readPinnedRelayNodeKey(relayUrl);
+/**
+ * The relay's node key: the pinned one, or else learned from the relay's TEE
+ * attestation (see mero-js `attestRelayNodeKey`) and pinned for next time.
+ *
+ * A mock quote proves nothing about hardware, so one is accepted only from a
+ * loopback relay — a local rig. A real one must be a signed release of the
+ * trusted profile ({@link relayQuoteVerifier}).
+ *
+ * `fresh` skips the pin and attests now, for a step that hands the relay
+ * something it keeps — founding a namespace through it. A pinned key was
+ * checked once, on some earlier day, against whatever answered then.
+ */
+export async function attemptRelayNodeKey(relayUrl, options = {}) {
+    const pinned = options.fresh ? null : readPinnedRelayNodeKey(relayUrl);
     if (pinned)
         return { kind: 'learned', nodeKey: pinned };
     const marked = { failure: null };
@@ -435,6 +438,82 @@ function jwtExpiryMs(token) {
         return null;
     }
 }
+// ------------------------------------------------------------------- sealing
+//
+// Everything a delegated session sends a hosted relay is sealed to the relay's
+// attested TD (mero-js `createAttestedSealedFetch`), so TLS that ends at the
+// relay's ingress, and whoever holds its certificate, reads none of it: not the
+// login, not the token, not a query or its result, not an event.
+//
+// A relay whose node leaves auth to its proxy, and has no
+// `[server.sealed] forward_auth`, cannot guard a logged-in route inside the
+// envelope and answers `403 sealed_route_unguarded` from inside it. Only then
+// does a request go out plain, as it always did before sealing: that answer is
+// sealed under the session, so nobody on the way can forge it to force the
+// downgrade. Anything else that goes wrong, an attestation refused or a relay
+// that does not answer, fails the request; it never falls back.
+const sealedFetches = new Map();
+/** Forget every relay's sealed transport. For tests. */
+export function forgetRelaySealing() {
+    sealedFetches.clear();
+}
+/** Whether a sealed answer is the TD saying it cannot guard this route sealed. */
+async function isUnguardedRefusal(response) {
+    if (response.status !== 403)
+        return false;
+    try {
+        const body = (await response.clone().json());
+        return body.error?.code === 'sealed_route_unguarded';
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether `request` needs a session the relay's proxy checks: a token, or a login. */
+function needsSession(request) {
+    return request.headers.has('authorization') || new URL(request.url).pathname.startsWith('/auth/');
+}
+function sealedRelayFetch(relayUrl) {
+    const plain = (input, init) => globalThis.fetch(input, init);
+    const sealed = createAttestedSealedFetch({
+        baseUrl: relayUrl,
+        verify: relayQuoteVerifier(relayUrl, plain),
+        fetch: plain,
+    });
+    // Set once the TD has said it cannot guard a logged-in call: those go plain
+    // straight away instead of paying a refused round trip each.
+    let unguarded = false;
+    return async (input, init) => {
+        const request = new Request(input, init);
+        if (unguarded && needsSession(request))
+            return plain(request);
+        const response = await sealed(request.clone());
+        if (!(await isUnguardedRefusal(response)))
+            return response;
+        if (!unguarded) {
+            unguarded = true;
+            console.warn(`[mero-js] ${relayOrigin(relayUrl)} cannot guard logged-in calls sealed (no forward_auth); ` +
+                'they go over its TLS until it does');
+        }
+        return plain(request);
+    };
+}
+/**
+ * The `fetch` a delegated session uses for `relayUrl`: sealed to its attested
+ * TD, one per relay so its session is shared. `undefined` for a loopback relay,
+ * a dev rig answering mock quotes, which keeps the global `fetch`.
+ */
+export function relayTransportFetch(relayUrl) {
+    if (isLoopback(relayUrl))
+        return undefined;
+    const origin = relayOrigin(relayUrl);
+    let found = sealedFetches.get(origin);
+    if (!found) {
+        found = sealedRelayFetch(relayUrl);
+        sealedFetches.set(origin, found);
+    }
+    return found;
+}
 /**
  * A lazily minted `account_proof` session on the relay.
  *
@@ -455,6 +534,8 @@ function relaySession(s, nodeKey) {
         if (!inflight) {
             inflight = login({
                 nodeUrl: s.relayUrl,
+                // Sealed: the token is the session, and the TLS ends outside the TD.
+                fetch: relayTransportFetch(s.relayUrl),
                 node: nodeKey,
                 deviceSecret: s.deviceSecret,
                 accountProof: s.credential,
@@ -610,6 +691,9 @@ _contextId) {
     const nodeKey = readPinnedRelayNodeKey(s.relayUrl);
     const client = createMeroClient({
         transport: 'relay',
+        // Every request sealed to the relay's attested TD: intents, admin reads,
+        // queries, the login and events (see `relayTransportFetch`).
+        fetch: relayTransportFetch(s.relayUrl),
         relay: {
             relayUrl: s.relayUrl,
             authorAccount: s.account,

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

@@ -1896,6 +1896,8 @@ export interface AdminApiClientConfig {
     baseUrl: string;
     getAuthToken?: () => Promise<string | undefined>;
     timeoutMs?: number;
+    /** Fetch every request goes through. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
 }
 /** A join signed by its subject, handed to an admitter to publish. */
 export interface AdmitJoinRequest {