@calimero-network/mero-js 26.11.0 → 27.0.1

package/README.md

@@ -1,21 +1,20 @@
-# Mero.js — Pure JavaScript SDK for Calimero
+# Mero.js — the JavaScript client for Calimero 1.0
 
-A lightweight, universal JavaScript/TypeScript SDK for [Calimero](https://calimero-network.github.io/core/).
-Authenticate to a node, drive the admin API, execute WASM methods over JSON-RPC,
-and stream real-time events — from the browser, Node, Deno, Bun, or edge
-runtimes. Zero runtime dependencies; built entirely on Web Platform APIs
-(`fetch`, `WebSocket`, `AbortController`).
+The JavaScript/TypeScript client for [Calimero](https://calimero-network.github.io/core/)
+1.0, the confidential cloud. `CalimeroClient` verifies a node's TDX attestation,
+seals every request to it end to end (Noise NK, `calimero/sealed-http/v2`), signs
+people in with WebAuthn passkeys and machines with API keys, and calls apps that
+each run on their own replicated log. It runs in the browser and Node 18+, and is
+byte-compatible with core's `calimero-sealed` and `calimero-client`.
 
-## Documentation
+> **Version 27 is the Calimero 1.0 client only.** The v1 SDK for merod 0.x nodes
+> (`MeroJs`, the admin and auth API clients, JSON-RPC, contexts and namespaces)
+> is in 26.x. See [Migrating from v1](https://calimero-network.github.io/mero-js/reference/migrating-from-v1/).
 
-Full documentation is published at
-**<https://calimero-network.github.io/mero-js/>** — quickstart, guides, and the
-complete API reference (`MeroJs`, admin API, auth API, RPC, events, cloud,
-capabilities, and the error model). The source lives under [`docs/`](docs/).
+## Documentation
 
-> **Not React?** This is a framework-agnostic SDK. React bindings live in the
-> separate [`@calimero-network/mero-react`](https://github.com/calimero-network/mero-react)
-> package.
+**<https://calimero-network.github.io/mero-js/>**: quickstart, guides, and the
+reference for every method and the route it calls. The source is under [`docs/`](docs/).
 
 ## Installation
 
@@ -23,309 +22,95 @@ capabilities, and the error model). The source lives under [`docs/`](docs/).
 npm install @calimero-network/mero-js
 ```
 
-Requires Node.js 18+ (native `fetch`) or any modern browser. The package ships
-ESM, CommonJS, and a minified browser build, is side-effect-free (tree-shakeable),
-and includes its own TypeScript declarations.
+The package ships ESM, CommonJS and a minified browser build with its own
+TypeScript declarations. Its one dependency, `@phala/dcap-qvl`, verifies TDX
+quotes and is loaded on first use.
 
 ## Quick start
 
-```typescript
-import { createMeroJs, HTTPError, RpcError } from '@calimero-network/mero-js';
-
-const sdk = createMeroJs({
-  baseUrl: 'http://localhost:2528',
-  // timeoutMs defaults to 10000; pass a tokenStore to persist auth
-});
-
-// Authenticate (username/password against the node's auth service)
-await sdk.authenticate({ username: 'dev', password: 'dev' });
-
-// Admin API — list this node's contexts
-const { contexts } = await sdk.admin.getContexts(); // ContextWithGroup[]
-console.log(`found ${contexts.length} contexts`);
-
-// Execute a context method over JSON-RPC
-try {
-  const value = await sdk.rpc.execute<string>({
-    contextId: contexts[0].id,
-    method: 'get_value',
-    argsJson: { key: 'greeting' },
-  });
-  console.log(value);
-} catch (err) {
-  if (err instanceof RpcError) console.error(`contract error ${err.code}: ${err.message}`);
-  else if (err instanceof HTTPError) console.error(`HTTP ${err.status}: ${err.statusText}`);
-  else throw err;
-}
-
-// Stream real-time context events (SSE)
-sdk.events.on('event', (e) => console.log(e.contextId, e.type, e.data));
-await sdk.events.connect();
-await sdk.events.subscribe([contexts[0].id]);
-
-// Tear down open connections when done
-sdk.close();
-```
-
-`sdk.auth`, `sdk.admin`, `sdk.rpc`, `sdk.events` (SSE) and `sdk.ws` (experimental
-WebSocket) are all reachable from the one `MeroJs` instance. See the
-[quickstart](https://calimero-network.github.io/mero-js/get-started/quickstart/)
-and [authentication guide](https://calimero-network.github.io/mero-js/get-started/authentication/)
-for token persistence and the refresh lifecycle.
-
-## Error model
-
-Every failure surfaces as a typed error:
-
-- **`HTTPError`** — a non-2xx response. Network failures, timeouts, and
-  cancellations are also wrapped as `HTTPError` with **`status: 0`** (the
-  underlying `AbortError`/`TimeoutError` is not propagated).
-- **`AuthRevokedError`** (extends `HTTPError`) — the refresh token was reused or
-  revoked; the session is over. The SDK has already cleared its tokens.
-- **`RpcError`** — the WASM contract returned a JSON-RPC error (`code`, `message`,
-  optional `type`/`data`).
-
-`classifyError(err)` turns any of these into `{ kind, retryable, message }`.
-`kind` is read off the status (`'conflict'` for a 409, `'unavailable'` for a
-503, `'unreachable'` for status 0, and so on). `retryable` says whether the same
-request could work later. `message` is the node's own words. To follow an
-invitation, use `sdk.admin.redeemInvitation`: a join that failed but landed
-comes back as `already-member` rather than as an error.
-
-`401`s are handled internally: the SDK refreshes the token and retries once, so
-you only see a `401` if the refresh itself fails. Full details in the
-[error model reference](https://calimero-network.github.io/mero-js/reference/error-model/).
-
-## Writing without a node
-
-The quickstart above assumes you have a node and a credential on it. A browser
-tab, a phone, or an agent has neither — the runtime cannot compile the app's WASM
-against materialized state, and never received the scope key that seals the
-deltas. So there is a second connection shape: sign in to **Calimero Cloud**, and
-write through an attested TEE **relay** using
-[delegated execution](https://calimero-network.github.io/core/protocol/delegated-authorship/).
-
-You sign a *warrant* locally — your consent for one specific intent, once — the
-relay runs the method as **your** principal, and the resulting change is
-attributed to your account and device. Your signing key never leaves the
-process; only signatures do.
-
-```typescript
-import { connectCloud } from '@calimero-network/mero-js';
-
-const connection = await connectCloud({
-  googleIdToken,        // or a stored sessionToken
-  authorAccount,        // your account, hex
-  authorProof,          // your AccountProof<DeviceCert>, hex borsh
-  deviceSecret,         // your device's ed25519 seed, hex — never transmitted
-});
+```ts
+import { CalimeroClient, browserPasskey } from '@calimero-network/mero-js';
 
-const { rootHash, returns } = await connection.execute(contextId, 'set', {
-  key: 'greeting',
-  value: 'hello',
+const client = new CalimeroClient({
+  baseUrl: 'https://eu1.cloud.calimero.network',
+  // Trust the signed mero-tee release the node names, from this one up.
+  policy: { release: { minReleaseVersion: '2.3.109' } },
 });
-```
-
-`connectCloud` replaces the **node-URL prompt**, not the authentication: it asks
-the cloud which namespaces the account owns and which relay serves them, then
-builds the relay client. `sdk.cloud` exposes the same cloud API from an existing
-`MeroJs` instance for apps that have both a node and a cloud account, and
-`RelayClient` is available directly for a relay you were told about out of band.
-
-One precondition is not yours to satisfy: the node must relay. A fleet node
-admitted as a `RelayTee` (the namespace's TEE admission policy set with
-`mode: 'relay'`) relays by role; a `ReadOnlyTee` is a replica and never relays;
-and a node too old to report a role needs an admin of the namespace to grant it
-`CAN_AUTHOR_ON_BEHALF`. `connectCloud` picks a relay on the cloud's `canExecute`,
-which folds that rule in, and otherwise throws saying which of those is missing —
-naming the account that needs the grant when that is the fix.
-
-A keyholder can also **create** a context through a relay:
-`relay.createContext({ groupId, applicationId, initArgs })` signs a creation
-warrant (checked against *your* `CAN_CREATE_CONTEXT`, not the relay's) and
-returns the new `contextId`.
-
-And it can **govern** through one: `relay.govern({ groupId, op })` signs a
-governance warrant over one op, such as `memberAddedOp(account, 'Member')` or
-`groupCreatedOp({ ... })`, and every peer applies it under *your* rights.
-
-See the [cloud client](https://calimero-network.github.io/mero-js/reference/cloud/),
-[relay client](https://calimero-network.github.io/mero-js/reference/relay/) and
-[connectCloud](https://calimero-network.github.io/mero-js/reference/connect-cloud/)
-references — including why a warrant nonce must never restart.
-
-## Account (delegated) layer
-
-`connectCloud` is the shape for an account that already belongs somewhere. The
-account layer is everything around it for an account that owns nothing yet: it
-has a device the wallet certified and no relay, and it has to found a namespace
-or be invited into one before it can write. It is framework-free — plain TS over
-`sessionStorage`/`localStorage` — and `@calimero-network/mero-react` re-exports
-every name below unchanged (its hooks are built on it), so an app may import
-them from either package.
-
-- **Session** — `DelegatedCredential` (what the wallet certified: account,
-  certificate, device secret) and `DelegatedAccountSession` (that plus the relay
-  to write through, `null` until the account is a member of something).
-  `readDelegatedSession` / `saveDelegatedSession` / `clearDelegatedSession`,
-  `readDelegatedCredential` / `saveDelegatedCredential` /
-  `clearDelegatedCredential`; `readRelayMap`, `rememberRelay`,
-  `relayForContext`, `knownRelays`, `listDelegatedContexts`,
-  `listDelegatedNamespaces`, `carryExecutorAccount`.
-- **The relay's node key** — `learnRelayNodeKey` (attests the relay: its signed
-  mero-tee release from the cloud mirror, Intel's chain, every register; retries
-  the transport, refuses a bad quote), `attemptRelayNodeKey`,
-  `resolveRelayNodeKey`, `pinRelayNodeKey`, `readPinnedRelayNodeKey`,
-  `RELAY_NODE_KEY_RETRY_MS`. `@phala/dcap-qvl` is loaded on the first real quote
-  and is external to the bundles: a consumer that never meets a real relay never
-  downloads the verifier.
-- **Client** — `buildDelegatedClient(session, contextId)`: a `MeroClient` over
-  the relay transport, or `null` while there is no relay (a logged-in state, not
-  a broken one). `forgetMethodKinds`, `persistedNonces`, `markContextNonceSpent`.
-- **Admin, one shape on both transports** — `createAccountAdmin({ session,
-  read, app })` returns an `AdminApiClient` whose writes are governance and
-  creation warrants signed by the account and whose reads go through the relay;
-  `createNodeAdmin({ admin, app })` is the same `AdminApiClient` for a node, with
-  `createNamespace` installing the package first. Refusals: `NoRelayError`,
-  `NotForAccountError`, `InvitationNotClaimableError`.
-- **Founding and creating** — `foundDelegatedNamespace`,
-  `createDelegatedContext`, `createDelegatedPrivateContext`,
-  `delegatedGovernance`, `governGroup`, `governRoot`, `namespaceOfGroup`,
-  `rememberGroupNamespace`; `HA_REFUSAL_MESSAGES`,
-  `HA_ACCOUNT_NOT_LINKED_MESSAGE` for the cloud's HA answers.
-- **Which application** — `applicationIdForBundle`, `selectLatestBundle`,
-  `fetchRegistryBundles`, `resolveApplicationIdFromRegistry`,
-  `latestPublishedVersion` (the registry's answer for a package).
-- **Joining from an invitation** — `resolveRelayFromInvitation` (which relay
-  admits, from the invitation's signed admitters and the cloud), `joinWithNode`,
-  `bootstrapFromInvitation` (both steps, as a result rather than a throw),
-  `joinAsAccount` (the same, switching the session onto the relay that admitted),
-  `normaliseAccount`.
-
-```typescript
-import {
-  beginDeviceEnrolment, readEnrolmentCallback, completeDeviceEnrolment,
-  saveDelegatedSession, learnRelayNodeKey, pinRelayNodeKey, buildDelegatedClient,
-  createAccountAdmin, joinAsAccount, resolveApplicationIdFromRegistry, type DelegatedAccountSession,
-} from '@calimero-network/mero-js';
-
-// 1. Enrol: the wallet certifies a device key this app generated and keeps.
-//    (first visit)  beginDeviceEnrolment({ walletUrl, devicePublicKey, kemPublicKey, returnTo });
-//    (on return)
-const callback = readEnrolmentCallback(); // null on an ordinary load
-const enrolled = await completeDeviceEnrolment({ ...callback, devicePublicKey, kemPublicKey });
-let session: DelegatedAccountSession = {
-  account: enrolled.account, credential: enrolled.credential, deviceSecret, relayUrl: null,
-};
-saveDelegatedSession(session);
-
-// 2. Found a namespace, or join one. A new account has no relay; either gives it one.
-const registryUrl = 'https://apps.calimero.network';
-const app = await resolveApplicationIdFromRegistry(registryUrl, 'com.example.kv');
-const admin = createAccountAdmin(
-  { session, read: null, app: { packageName: 'com.example.kv', packageVersion: app.version, registryUrl } },
-  { join: (namespaceId, invitation) => joinAsAccount(session, namespaceId, invitation, {
-      onJoined: (next) => { session = next; saveDelegatedSession(next); },
-    }) },
-);
-const { namespaceId } = await admin.createNamespace({ applicationId: app.applicationId, name: 'my-notes' });
-//   or:  await admin.joinNamespace(namespaceId, { invitation });
 
-// 3. Attest the relay before trusting a session on it, then write through it.
-const nodeKey = await learnRelayNodeKey(session.relayUrl!);
-if (nodeKey) pinRelayNodeKey(session.relayUrl!, nodeKey);
-const client = buildDelegatedClient(session, null)!;
-const { contextId } = await admin.createContext({ groupId: namespaceId, applicationId: app.applicationId, serviceName: 'kv' });
-await client.execute(contextId, 'set', { key: 'greeting', value: 'hello' });
+await client.signUp(browserPasskey(), 'alice'); // or signIn(browserPasskey())
+await client.installPackage('com.example.kv', '1.0.0'); // signed .mpk from the registry
+const app = await client.createApp('kv', { package: 'com.example.kv', version: '1.0.0' }, { confirmMethods: ['clear'] });
 
-// 4. Invite another account; they claim it with `admin.joinNamespace` on their side.
-const { invitation } = await admin.createNamespaceInvitation(namespaceId);
+await client.call(app, 'set', { key: 'a', value: '1' });
+const { result } = await client.view(app, 'get', { key: 'a' });
+await client.callConfirmed(app, 'clear', {}, browserPasskey()); // passkey consent
+for await (const event of client.events(app)) console.log(event);
+await client.upgradeApp(app, { version: '1.1.0' }, browserPasskey()); // the owner approves
 ```
 
-`createNamespace` founds through the relay and enables HA on the cloud for the
-account; `createContext` signs a creation warrant naming the bundle service it
-is for; `createNamespaceInvitation` names the relays that admit, so an invitee
-with no node of their own can be admitted by one of them. The `read` client is
-`null` until the relay's node key is attested, which is why the session is
-built in that order.
+A development cluster (`merod local`, `merod run --dev`) sends mock quotes,
+which pass only with `policy: { allowMock: true }`. Nothing is read from the
+environment.
 
-## Private agents
+## What the client checks
 
-A private agent runs in a TDX VM (mero-tee's agent image) that several owners' agents share, each named by an agent id. Its gate proves which image runs and takes each agent's secrets only sealed to it, from its owner. These functions are that owner's side; whoever relays the requests (mdma included) sees only quotes and ciphertext.
+Before it sends anything to a node, as core's Rust client does (`Measurements::Release`):
 
-```ts
-import { verify as dcapVerify, getCollateral } from '@phala/dcap-qvl';
-import {
-  agentQuoteVerifier, attestAgent, generateOwnerKey, provisionAgent, releaseAgent, verifySignedAgentPolicy,
-} from '@calimero-network/mero-js';
-
-// The mero-kms release's agent allowlist, checked against its Sigstore signature.
-const policy = await verifySignedAgentPolicy(policyJson, bundleJson, { profile: 'locked-read-only' });
-const verifier = agentQuoteVerifier(policy, { dcapVerify, fetchCollateral: (quote) => getCollateral(PCCS_URL, quote) });
-
-const owner = await generateOwnerKey(); // keep owner.secret: only it can change or release the agent
-const agent = await attestAgent({ gateUrl, agentId: 'a-1f2e', verifier });
-await provisionAgent({ gateUrl, agent, ownerSecret: owner.secret, verifier, secrets: { NEAR_AI_API_KEY: key } });
-// later: await releaseAgent({ gateUrl, agent: await attestAgent({ gateUrl, agentId, verifier }), ownerSecret, verifier });
-```
+1. The node names the mero-tee release it runs. A release below `minReleaseVersion` is refused before anything is fetched.
+2. The release's `published-mrtds.json` is fetched and its Sigstore signature is checked against the mero-tee node release workflow.
+   By default it comes from the `cloud.calimero.network` mirror; `releaseSource: 'github'` reads the GitHub release instead (Node only: GitHub sends no CORS headers).
+3. The quote is checked against Intel's collateral with `@phala/dcap-qvl` (Intel's PCS unless you give `fetchCollateral`): the signature chain and the TCB status.
+4. A debug TD is refused.
+5. The registers must be the release's `locked-read-only` image; a debug profile is trusted only with `allowDebugProfile`.
+6. The quote's report data binds the client's nonce and the transport key the sealed channel opens to.
 
-- `attestAgent` returns the agent's keys only once its quote verifies: genuine, from an image in the policy, not a debug TD, for your nonce, and committing to the agent id asked about and to the keys the gate names.
-- `provisionAgent` refuses an agent another key claimed before sending anything. The first bundle for an unclaimed agent claims it for your key, and a fresh quote must then name your key as owner.
-- Secrets are sealed with RFC 9180 HPKE in Auth mode (X25519, HKDF-SHA256, ChaCha20-Poly1305) to the gate's in-memory key, for that agent id only.
-- `releaseAgent` stops the agent and erases its slot; a fresh quote must name no owner.
+Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 
-## Lower-level HTTP client
+## The API
 
-If you need raw HTTP against a node (without the `MeroJs` facade), the SDK
-exports composable clients — `createBrowserHttpClient`, `createNodeHttpClient`,
-`createUniversalHttpClient`, `createHttpClient` — plus `withRetry`,
-`combineSignals`, and `createTimeoutSignal`:
+- **Credentials**: `signUp`, `signIn`, `refresh`, `signOut`, `signOutEverywhere`, `useSession`, `useApiKey`, `me`, `usage`, `addPasskey`, `labelPasskey`, `removePasskey`, `createApiKey`, `listApiKeys`, `revokeApiKey`.
+- **Packages**: `installPackage`, `uploadPackage`, `packages`, `package`, `uninstallPackage`; `uploadBundle` (raw WASM, development clusters only).
+- **Apps**: `createApp`, `listApps`, `getApp`, `deleteApp`, `setAccess`, `setAppMetadata`, `appStorage`, `appAbi`, `upgradeApp`, `transferApp`.
+- **Calls**: `call`, `callConfirmed`, `view`, `events`. A call always carries an idempotency key, and is sent again with it while the node answers `503`.
+- **Blobs and presence**: `uploadBlob`, `downloadBlob`, `listBlobs`, `blobInfo`, `deleteBlob`; `publishPresence`, `presence`, `presenceStream`.
+- **Organizations**: `createOrg`, `getOrg`, `deleteOrg`, `setOrgMetadata`, `setMember`, `removeMember`, `setMemberMetadata`, `setCapabilities` (`ORG_CAPABILITIES`), teams, `invite`, `redeemInvite`.
+- **Owner decisions** (passkey approval): `upgradeOrg`, `upgradeRun`, `retryUpgradeRun`, `approveRelease`, `approveOutbound`.
+- **Any route**: `get`, `post`, `put`, `delete`; `postConfirmed` and `deleteConfirmed` answer a `412 CONFIRM_REQUIRED` with a passkey.
 
-```typescript
-import { createBrowserHttpClient } from '@calimero-network/mero-js';
+Refusals are typed (`LoginRequired`, `NotFound`, `ConfirmRequired`, `ConfirmCancelled`,
+`ArgsTooLarge`, `IdempotencyMismatch`, `AppError`, `TrapError`, `UnavailableError`),
+all extending `CalimeroError` with the node's `status` and `code`. See the
+[error model](https://calimero-network.github.io/mero-js/reference/error-model/).
 
-const http = createBrowserHttpClient({
-  baseUrl: 'https://node.example.com',
-  getAuthToken: async () => localStorage.getItem('access_token') ?? undefined,
-});
-
-const data = await http.get<{ message: string }>('/api/hello');
-```
-
-Methods (`get`/`post`/`put`/`delete`/`patch`/`head`/`request`) return parsed data
-directly and support per-call `{ signal, timeoutMs, parse }`. See the
-[HTTP transport guide](https://calimero-network.github.io/mero-js/guides/http-transport/)
-for options, parsing rules, retries, and cancellation.
+The pieces it is built from are exported too: the sealed transport
+(`createSealedFetch`), quote and signed-release verification
+(`createQuoteVerifier`, `createSignedReleaseVerifier`, `trustSignedRelease`), and
+the client for mero-tee's private agent gate (`attestAgent`, `provisionAgent`,
+`releaseAgent`).
 
 ## Development
 
 ```bash
 pnpm install
 pnpm build
-pnpm test        # unit tests (mocked, fast)
+pnpm test:unit   # unit tests, against a stand-in node over a real sealed channel
 pnpm lint
 pnpm typecheck
+pnpm typecheck:consumer
 ```
 
-### Testing & the contract gate
-
-The SDK mirrors core's HTTP wire types by hand, so two layers guard against drift:
+The cluster tests (`tests/cloud-v2`) start three `merod run --dev` nodes and
+run the client against them:
 
-- **Unit tests** (`pnpm test`) — mocked, fast, cover the client logic.
-- **E2E** (`pnpm test:e2e`) — runs the real SDK against a live `merod`. Point it
-  at a node and provide credentials:
-  ```bash
-  NODE_URL=http://localhost:2528 MERO_E2E_USER=dev MERO_E2E_PASS=dev pnpm test:e2e
-  ```
-  In CI this runs both against a released `merod` (this repo) and against a
-  PR-built `merod` (core's `sdk-e2e`).
+```bash
+MEROD_BINARY=/path/to/merod KV_STORE_WASM=/path/to/kv_store.wasm pnpm test:cloud-v2
+```
 
-The e2e records every request as `METHOD /path` (see `tests/e2e/coverage-recorder.ts`).
-Core's route-coverage gate is **method-aware**: it fails if any admin route *or
-verb* ships without an SDK test — so e.g. `GET /blobs/:id` can't hide behind
-`DELETE /blobs/:id`. When you add an SDK method for a new endpoint, exercise it in
-the e2e (the sweep in `tests/e2e/coverage-sweep.test.ts` is the catch-all) so
-coverage stays complete.
+Without the variables they use `../core/target/debug/merod` and
+`../core/target/wasm32-unknown-unknown/app-release/kv_store.wasm` from a sibling
+core checkout. `scripts/download-released-merod.sh` fetches the newest released
+1.0 `merod` and its kv-store fixture, which is what CI runs them against; core's
+`e2e.yml` runs the same suite against core's own tree.
 
 ## License
 

package/dist/cloud-v2/attestation.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The check every cloud client runs before it sends anything: the node's quote
+ * must be genuine (or, in development, an explicitly allowed mock), from an
+ * image this client trusts, and its report data must bind this nonce, the
+ * expected app and the transport key the sealed channel will be opened to.
+ *
+ * Report data, as core's `calimero-cloud-client::attest` builds it:
+ * `nonce(32) || SHA-256("calimero.tee-attest.transport-key.v1" | app_hash | transport_key)`.
+ *
+ * A real quote is judged as the Rust client judges it (`attest::verify` with
+ * `Measurements::Release`): the node names the mero-tee release it runs; that
+ * release must be at least `minReleaseVersion`; its `published-mrtds.json` is
+ * fetched and its Sigstore signature checked against the node release workflow;
+ * the quote's signature chain and TCB status are checked against Intel's
+ * collateral (fetched here: the node sends none, and cannot forge it); the TD
+ * must not be a debug TD; and its registers must be the release's image for the
+ * trusted profile, `locked-read-only` unless a debug profile is explicitly
+ * allowed. Nothing here reads the environment: mock quotes pass only with
+ * `allowMock`.
+ */
+import { type SignedNodeRelease } from '../sealed/release.js';
+import { type VerifyTransportQuote } from '../sealed/sealed.js';
+import { type DcapCollateral, type DcapVerify } from '../sealed/verify.js';
+/** The mock quote format development clusters use. */
+export declare const MOCK_QUOTE_HEADER = "MOCK_TDX_QUOTE_V1";
+/** How the signed release a node names is trusted (core's `Measurements::Release`). */
+export interface CloudReleasePolicy {
+    /**
+     * The oldest mero-tee release trusted, e.g. `2.3.109`. Required: every
+     * release ever signed stays validly signed, so without a floor a node could
+     * name an old release with a flaw since fixed.
+     */
+    minReleaseVersion: string;
+    /** The image profile trusted; defaults to `locked-read-only`. */
+    profile?: string;
+    /** Trust a debug profile. Its image is readable by the operator: testing only. */
+    allowDebugProfile?: boolean;
+    /**
+     * Where the release's signed measurements come from: `'github'` (the release
+     * assets, what core's Rust client reads; no CORS, so not in browsers), the
+     * base URL of a mirror (default {@link DEFAULT_RELEASE_MIRROR}), or a function.
+     * Untrusted either way: the Sigstore signature is checked here.
+     */
+    releaseSource?: 'github' | string | ((version: string) => Promise<SignedNodeRelease>);
+    /** DCAP verification; defaults to `verify` from `@phala/dcap-qvl`, loaded on first use. */
+    dcapVerify?: DcapVerify;
+    /**
+     * Intel's collateral for a quote; defaults to `@phala/dcap-qvl`'s
+     * `getCollateralFromPcs` (Intel's PCS). Point it at a PCCS a browser can reach
+     * if Intel's does not answer the page.
+     */
+    fetchCollateral?: (quote: Uint8Array) => Promise<DcapCollateral>;
+    /** Override the release signer (defaults to the mero-tee node release workflow). */
+    identity?: string;
+    issuer?: string;
+    /** The current time in milliseconds; defaults to `Date.now`. For tests. */
+    now?: () => number;
+}
+export interface CloudPolicy {
+    /** Accept mock quotes. Development clusters only; never set from the environment. */
+    allowMock?: boolean;
+    /** Trust real quotes from the signed release the node runs. */
+    release?: CloudReleasePolicy;
+    /**
+     * Verify a real quote yourself instead (e.g. `createQuoteVerifier` with
+     * pinned measurements). Takes precedence over `release`.
+     */
+    verifyQuote?: VerifyTransportQuote;
+    /** The app bundle hash (hex) the quote must bind, when talking to one app. */
+    appHash?: string;
+}
+export interface AttestationDoc {
+    quote: string;
+    transportKey: string;
+    appHash: string;
+    nonce: string;
+    release: {
+        version: string;
+        profile: string;
+    };
+    cluster: string;
+    node: number;
+    mock: boolean;
+}
+/**
+ * The release a node names, checked against the floor before anything is
+ * fetched. Accepts `2.3.109` and the tag form `mero-tee-v2.3.109`.
+ */
+export declare function claimedRelease(doc: Pick<AttestationDoc, 'release'>, minReleaseVersion: string): string;
+/** Fetch the node's attestation and return its transport key once it checks out. */
+export declare function fetchAttestedKey(baseUrl: string, policy: CloudPolicy, fetchImpl?: typeof fetch): Promise<Uint8Array>;

package/dist/cloud-v2/attestation.js

@@ -0,0 +1,135 @@
+/**
+ * The check every cloud client runs before it sends anything: the node's quote
+ * must be genuine (or, in development, an explicitly allowed mock), from an
+ * image this client trusts, and its report data must bind this nonce, the
+ * expected app and the transport key the sealed channel will be opened to.
+ *
+ * Report data, as core's `calimero-cloud-client::attest` builds it:
+ * `nonce(32) || SHA-256("calimero.tee-attest.transport-key.v1" | app_hash | transport_key)`.
+ *
+ * A real quote is judged as the Rust client judges it (`attest::verify` with
+ * `Measurements::Release`): the node names the mero-tee release it runs; that
+ * release must be at least `minReleaseVersion`; its `published-mrtds.json` is
+ * fetched and its Sigstore signature checked against the node release workflow;
+ * the quote's signature chain and TCB status are checked against Intel's
+ * collateral (fetched here: the node sends none, and cannot forge it); the TD
+ * must not be a debug TD; and its registers must be the release's image for the
+ * trusted profile, `locked-read-only` unless a debug profile is explicitly
+ * allowed. Nothing here reads the environment: mock quotes pass only with
+ * `allowMock`.
+ */
+import { fromHex, hex } from '../crypto/internal.js';
+import { DEFAULT_RELEASE_MIRROR, cloudNodeReleaseUrl, compareReleaseVersions, fetchGithubNodeRelease, fetchNodeRelease, releaseVersion, trustSignedRelease, } from '../sealed/release.js';
+import { transportKeyBinding } from '../sealed/sealed.js';
+import { PRODUCTION_PROFILE, createQuoteVerifier } from '../sealed/verify.js';
+/** The mock quote format development clusters use. */
+export const MOCK_QUOTE_HEADER = 'MOCK_TDX_QUOTE_V1';
+function base64ToBytes(b64) {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function equal(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+let dcapModule;
+/** A function out of `@phala/dcap-qvl`, whatever shape the bundler gave the (CommonJS) module. */
+async function dcap(name) {
+    dcapModule ?? (dcapModule = import('@phala/dcap-qvl'));
+    const ns = await dcapModule;
+    const f = typeof ns[name] === 'function' ? ns[name] : ns.default?.[name];
+    if (typeof f !== 'function')
+        throw new TypeError(`@phala/dcap-qvl loaded without ${name}`);
+    return f;
+}
+/**
+ * The release a node names, checked against the floor before anything is
+ * fetched. Accepts `2.3.109` and the tag form `mero-tee-v2.3.109`.
+ */
+export function claimedRelease(doc, minReleaseVersion) {
+    const floor = releaseVersion(minReleaseVersion, 'minReleaseVersion');
+    const raw = String(doc.release?.version ?? '').trim().replace(/^mero-tee-v/, '').replace(/^v/, '');
+    const version = releaseVersion(raw, 'The release the node names');
+    if (compareReleaseVersions(version, floor) < 0) {
+        throw new Error(`mero-tee release ${version} is older than the minimum ${floor}`);
+    }
+    return version;
+}
+async function releaseFor(version, policy, fetchImpl) {
+    const source = policy.releaseSource;
+    if (typeof source === 'function')
+        return source(version);
+    if (source === 'github')
+        return fetchGithubNodeRelease(version, { fetch: fetchImpl });
+    return fetchNodeRelease(cloudNodeReleaseUrl(source ?? DEFAULT_RELEASE_MIRROR, version), { fetch: fetchImpl });
+}
+/** Judge a real quote as core's `Measurements::Release` does. */
+async function verifyRelease(doc, args, policy, fetchImpl) {
+    // Refuse what no release could admit before reaching for the network.
+    const version = claimedRelease(doc, policy.minReleaseVersion);
+    const trusted = await trustSignedRelease({
+        release: await releaseFor(version, policy, fetchImpl),
+        profile: policy.profile ?? PRODUCTION_PROFILE,
+        allowDebugProfile: policy.allowDebugProfile,
+        minReleaseVersion: policy.minReleaseVersion,
+        identity: policy.identity,
+        issuer: policy.issuer,
+    });
+    const fetchCollateral = policy.fetchCollateral ??
+        (async (quote) => (await dcap('getCollateralFromPcs'))(quote));
+    const verifier = createQuoteVerifier({
+        dcapVerify: policy.dcapVerify ?? (await dcap('verify')),
+        fetchCollateral,
+        now: policy.now,
+        ...trusted,
+    });
+    return verifier(args);
+}
+/** Fetch the node's attestation and return its transport key once it checks out. */
+export async function fetchAttestedKey(baseUrl, policy, fetchImpl = (input, init) => fetch(input, init)) {
+    const nonce = hex(crypto.getRandomValues(new Uint8Array(32)));
+    const url = new URL(`${baseUrl.replace(/\/+$/, '')}/attestation`);
+    url.searchParams.set('nonce', nonce);
+    if (policy.appHash)
+        url.searchParams.set('appHash', policy.appHash);
+    const response = await fetchImpl(url.toString());
+    if (!response.ok)
+        throw new Error(`The node refused to attest: HTTP ${response.status}`);
+    const doc = (await response.json());
+    const transportKey = fromHex(doc.transportKey, 'transportKey', 32);
+    const inner = policy.appHash ? fromHex(policy.appHash, 'appHash', 32) : new Uint8Array(32);
+    const suffix = await transportKeyBinding(inner, transportKey);
+    const quote = base64ToBytes(doc.quote);
+    const header = new TextEncoder().encode(MOCK_QUOTE_HEADER);
+    if (equal(quote.slice(0, header.length), header)) {
+        if (!policy.allowMock) {
+            throw new Error('mock quote refused: this client only trusts real TEEs');
+        }
+        const report = quote.slice(header.length, header.length + 64);
+        if (!equal(report.slice(0, 32), fromHex(nonce, 'nonce', 32)) || !equal(report.slice(32), suffix)) {
+            throw new Error('the quote does not bind this transport key, app and nonce');
+        }
+        return transportKey;
+    }
+    const args = { quoteB64: doc.quote, nonce, reportDataSuffix: hex(suffix) };
+    let ok;
+    if (policy.verifyQuote) {
+        ok = await policy.verifyQuote(args);
+    }
+    else if (policy.release) {
+        ok = await verifyRelease(doc, args, policy.release, fetchImpl);
+    }
+    else {
+        throw new Error('real quote refused: this client trusts no TD image (set policy.release)');
+    }
+    if (!ok)
+        throw new Error('The attestation did not verify, so its transport key is not trusted');
+    return transportKey;
+}