@calimero-network/mero-js 27.2.0 → 27.4.0

package/README.md

@@ -59,7 +59,7 @@ Before it sends anything to a node, as core's Rust client does (`Measurements::R
 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.
+3. The quote is checked against Intel's collateral with `@phala/dcap-qvl`: the signature chain and the TCB status. The collateral comes from the cloud's mirror (`DEFAULT_COLLATERAL_MIRROR`), which browsers can read; it only carries Intel-signed items. `collateralSource: 'intel'` asks Intel's PCS (no CORS: not in browsers), `fetchCollateral` replaces the fetch, and `maxCollateralAgeDays` refuses collateral Intel issued longer ago.
 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.
@@ -75,7 +75,7 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 - **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, never from an app's frontend): `upgradeOrg`, `upgradeRun`, `retryUpgradeRun`, `approveRelease`, `approveOutbound`, `bindPublisher`, `upgradePublished`.
-- **Approvals from an app**: `appsReport`, `releaseRules`, `pendingApprovals`, then `requestConsent` / `openConsentPage` to send the user to the node's consent page, and `consentResult`. See [Ask your users to approve node images and app upgrades](https://calimero-network.github.io/mero-js/guides/user-approvals/).
+- **Approvals from an app**: `appsReport`, `releaseRules`, `pendingApprovals`, then `requestConsent` / `openConsentPage` to send the user to the node's consent page, and `consentResult`. Show the answer's `code` to the user before sending them to `url` (`openConsentPage`'s `confirm` hook); they should see the same code on the page (`confirmationCode(requestId)` checks it). See [Ask your users to approve node images and app upgrades](https://calimero-network.github.io/mero-js/guides/user-approvals/).
 - **Operator** (ops token): `opsApps`, `opsOrgs`, `setReleaseDeadline`, `liftReleaseDeadline`.
 - **Any route**: `get`, `post`, `put`, `delete`; `postConfirmed` and `deleteConfirmed` answer a `412 CONFIRM_REQUIRED` with a passkey.
 

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

@@ -234,7 +234,34 @@ export interface ConsentStarted {
     url: string;
     /** Unix seconds; a request lives 10 minutes. */
     expiresAt: number;
+    /**
+     * The confirmation code the consent page shows, `XXX-XXX`
+     * ({@link confirmationCode} of `requestId`). Show it to the person before
+     * sending them to `url`: the page they land on should show the same code,
+     * which tells them it is the page their request opened. Not a secret.
+     * Nodes older than the code leave it out.
+     */
+    code?: string;
 }
+/** How {@link CalimeroClient.openConsentPage} sends the person to the page. */
+export interface OpenConsentOptions {
+    /** Sends the browser to the page's `url`; by default `window.location.assign`. */
+    navigate?: (url: string) => void;
+    /**
+     * Runs after the node answers and before navigating, with the answer: show
+     * the person `started.code` here so they can check the page shows the same.
+     * Answer `false` and the page is not opened (the request stays on the node
+     * until it expires).
+     */
+    confirm?: (started: ConsentStarted) => boolean | Promise<boolean>;
+}
+/**
+ * The confirmation code the node's consent page shows for `requestId`: the
+ * first 30 bits of SHA-256 of its UTF-8 bytes, big-endian, as six Crockford
+ * base32 characters written `XXX-XXX` (core's consent page). Compare it with
+ * {@link ConsentStarted.code} to check the node's answer.
+ */
+export declare function confirmationCode(requestId: string): Promise<string>;
 export type ConsentStatus = 'pending' | 'approved' | 'declined';
 /** `GET /consent/{id}/result`. */
 export interface ConsentResult {

package/dist/cloud-v2/approvals.js

@@ -74,6 +74,24 @@ export function publisherBindingMessage(cluster, org, signerId, generation) {
 export function publisherBindingBytes(cluster, org, signerId, generation) {
     return new TextEncoder().encode(publisherBindingMessage(cluster, org, signerId, generation));
 }
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/**
+ * The confirmation code the node's consent page shows for `requestId`: the
+ * first 30 bits of SHA-256 of its UTF-8 bytes, big-endian, as six Crockford
+ * base32 characters written `XXX-XXX` (core's consent page). Compare it with
+ * {@link ConsentStarted.code} to check the node's answer.
+ */
+export async function confirmationCode(requestId) {
+    const h = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(requestId)));
+    const word = ((h[0] << 24) | (h[1] << 16) | (h[2] << 8) | h[3]) >>> 0;
+    let code = '';
+    for (let i = 0; i < 6; i++) {
+        if (i === 3)
+            code += '-';
+        code += CROCKFORD[(word >>> (27 - 5 * i)) & 31];
+    }
+    return code;
+}
 /**
  * What the consent page put on `returnTo` when it sent the person back, or
  * `null` when `href` carries none. A hint only (anyone can type a URL): confirm

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

@@ -45,11 +45,26 @@ export interface CloudReleasePolicy {
     /** 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.
+     * Intel's collateral for a quote. Defaults to `@phala/dcap-qvl`'s
+     * `getCollateral` from `collateralSource`.
      */
     fetchCollateral?: (quote: Uint8Array) => Promise<DcapCollateral>;
+    /**
+     * Where the default `fetchCollateral` gets Intel's collateral: a PCCS base
+     * URL (default {@link DEFAULT_COLLATERAL_MIRROR}, the cloud's mirror, which a
+     * browser on any origin can read), or `'intel'` for Intel's PCS itself (no
+     * CORS: not in browsers). Untrusted either way: every item is signed by
+     * Intel and verified up to Intel's root CA, which `@phala/dcap-qvl` carries.
+     */
+    collateralSource?: 'intel' | string;
+    /**
+     * Refuse collateral whose TCB info Intel issued more than this many days
+     * ago. Unset: only Intel's own `nextUpdate` (about 30 days out) bounds how
+     * old it may be. A mirror cannot forge collateral, but it can replay an
+     * older, still valid copy; this shortens that window. Too small a value
+     * refuses every node if Intel is slow to re-sign.
+     */
+    maxCollateralAgeDays?: number;
     /** Override the release signer (defaults to the mero-tee node release workflow). */
     identity?: string;
     issuer?: string;
@@ -87,5 +102,7 @@ export interface AttestationDoc {
  * 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`, refusing collateral older than `policy.maxCollateralAgeDays` (by its TCB info's `issueDate`). */
+export declare function freshCollateral(fetch: (quote: Uint8Array) => Promise<DcapCollateral>, policy: Pick<CloudReleasePolicy, 'maxCollateralAgeDays' | 'now'>): (quote: Uint8Array) => Promise<DcapCollateral>;
 /** 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

@@ -19,7 +19,7 @@
  * `allowMock`.
  */
 import { fromHex, hex } from '../crypto/internal.js';
-import { DEFAULT_RELEASE_MIRROR, cloudNodeReleaseUrl, compareReleaseVersions, fetchGithubNodeRelease, fetchNodeRelease, releaseVersion, trustSignedRelease, } from '../sealed/release.js';
+import { DEFAULT_COLLATERAL_MIRROR, 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. */
@@ -70,6 +70,37 @@ async function releaseFor(version, policy, fetchImpl) {
         return fetchGithubNodeRelease(version, { fetch: fetchImpl });
     return fetchNodeRelease(cloudNodeReleaseUrl(source ?? DEFAULT_RELEASE_MIRROR, version), { fetch: fetchImpl });
 }
+/** The collateral fetch a policy gets unless it brings its own: `@phala/dcap-qvl` against `collateralSource`. */
+function defaultCollateral(policy) {
+    const source = policy.collateralSource ?? DEFAULT_COLLATERAL_MIRROR;
+    if (source === 'intel') {
+        return async (quote) => (await dcap('getCollateralFromPcs'))(quote);
+    }
+    return async (quote) => (await dcap('getCollateral'))(source, quote);
+}
+/** `fetch`, refusing collateral older than `policy.maxCollateralAgeDays` (by its TCB info's `issueDate`). */
+export function freshCollateral(fetch, policy) {
+    const maxDays = policy.maxCollateralAgeDays;
+    if (maxDays === undefined)
+        return fetch;
+    return async (quote) => {
+        const collateral = await fetch(quote);
+        let issued;
+        try {
+            issued = Date.parse(JSON.parse(collateral.tcb_info).issueDate ?? '');
+        }
+        catch {
+            issued = Number.NaN;
+        }
+        if (!Number.isFinite(issued))
+            throw new Error("The quote's collateral names no TCB info issue date");
+        const ageDays = ((policy.now ?? Date.now)() - issued) / 86400000;
+        if (ageDays > maxDays) {
+            throw new Error(`The quote's collateral was issued ${Math.floor(ageDays)} days ago, more than the ${maxDays} this client accepts`);
+        }
+        return collateral;
+    };
+}
 /** 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.
@@ -82,8 +113,7 @@ async function verifyRelease(doc, args, policy, fetchImpl) {
         identity: policy.identity,
         issuer: policy.issuer,
     });
-    const fetchCollateral = policy.fetchCollateral ??
-        (async (quote) => (await dcap('getCollateralFromPcs'))(quote));
+    const fetchCollateral = freshCollateral(policy.fetchCollateral ?? defaultCollateral(policy), policy);
     const verifier = createQuoteVerifier({
         dcapVerify: policy.dcapVerify ?? (await dcap('verify')),
         fetchCollateral,

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

@@ -11,7 +11,7 @@
  */
 import { type AttestationDoc, type CloudPolicy } from './attestation.js';
 import { type PasskeyProvider } from './passkey.js';
-import { type AppsReport, type ConsentRequest, type ConsentResult, type ConsentStarted, type OpsAppsReport, type OpsOrgsReport, type PageOptions, type PendingApprovals, type PublisherBindingInfo, type PublisherProof, type ReleaseRules } from './approvals.js';
+import { type AppsReport, type ConsentRequest, type ConsentResult, type ConsentStarted, type OpenConsentOptions, type OpsAppsReport, type OpsOrgsReport, type PageOptions, type PendingApprovals, type PublisherBindingInfo, type PublisherProof, type ReleaseRules } from './approvals.js';
 export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 export type { Committed } from './errors.js';
 export interface CalimeroSession {
@@ -505,11 +505,16 @@ export declare class CalimeroClient {
     requestConsent(request: ConsentRequest): Promise<ConsentStarted>;
     /**
      * {@link requestConsent}, then send the browser to the consent page
-     * (`navigate`, by default `window.location.assign`). Answers the request
-     * once `navigate` returns: with a popup (`url => window.open(url)`), poll it
-     * with {@link waitForConsent}.
+     * (`navigate`, by default `window.location.assign`). Pass `navigate` itself
+     * or {@link OpenConsentOptions}, whose `confirm` runs first with the node's
+     * answer so the app can show the person its `code`; when it answers `false`
+     * the page is not opened. When the node sends a `code` that is not
+     * {@link confirmationCode} of `requestId`, it throws `CalimeroError`
+     * (`CONSENT_CODE_MISMATCH`) and does not navigate. Answers the request
+     * once `navigate` returns (or `confirm` declines): with a popup
+     * (`url => window.open(url)`), poll it with {@link waitForConsent}.
      */
-    openConsentPage(request: ConsentRequest, navigate?: (url: string) => void): Promise<ConsentStarted>;
+    openConsentPage(request: ConsentRequest, navigateOrOptions?: ((url: string) => void) | OpenConsentOptions): Promise<ConsentStarted>;
     /** The decision on a consent request (any node answers, for the account that asked). */
     consentResult(requestId: string): Promise<ConsentResult>;
     /**

package/dist/cloud-v2/client.js

@@ -13,7 +13,7 @@ import { SealedTransportError, createSealedFetch } from '../sealed/sealed.js';
 import { fetchAttestedKey } from './attestation.js';
 import { CalimeroError, ConfirmCancelled, ConfirmRequired, LoginRequired, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 import { b64url, fromB64url } from './passkey.js';
-import { pageQuery, pendingApprovalsFrom, } from './approvals.js';
+import { confirmationCode, pageQuery, pendingApprovalsFrom, } from './approvals.js';
 export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 /** One URL path segment, so an id cannot reach another route. */
 function seg(value) {
@@ -781,17 +781,37 @@ export class CalimeroClient {
     }
     /**
      * {@link requestConsent}, then send the browser to the consent page
-     * (`navigate`, by default `window.location.assign`). Answers the request
-     * once `navigate` returns: with a popup (`url => window.open(url)`), poll it
-     * with {@link waitForConsent}.
+     * (`navigate`, by default `window.location.assign`). Pass `navigate` itself
+     * or {@link OpenConsentOptions}, whose `confirm` runs first with the node's
+     * answer so the app can show the person its `code`; when it answers `false`
+     * the page is not opened. When the node sends a `code` that is not
+     * {@link confirmationCode} of `requestId`, it throws `CalimeroError`
+     * (`CONSENT_CODE_MISMATCH`) and does not navigate. Answers the request
+     * once `navigate` returns (or `confirm` declines): with a popup
+     * (`url => window.open(url)`), poll it with {@link waitForConsent}.
      */
-    async openConsentPage(request, navigate = (url) => {
-        const w = globalThis.window;
-        if (!w)
-            throw new Error('no window to open the consent page in; pass `navigate`');
-        w.location.assign(url);
-    }) {
+    async openConsentPage(request, navigateOrOptions = {}) {
+        const options = typeof navigateOrOptions === 'function' ? { navigate: navigateOrOptions } : navigateOrOptions;
+        const navigate = options.navigate ??
+            ((url) => {
+                const w = globalThis.window;
+                if (!w)
+                    throw new Error('no window to open the consent page in; pass `navigate`');
+                w.location.assign(url);
+            });
         const started = await this.requestConsent(request);
+        if (started.code !== undefined) {
+            const expected = await confirmationCode(started.requestId);
+            if (started.code !== expected) {
+                throw new CalimeroError(200, 'CONSENT_CODE_MISMATCH', 'the consent page code does not match the request', {
+                    requestId: started.requestId,
+                    code: started.code,
+                    expected,
+                });
+            }
+        }
+        if (options.confirm && !(await options.confirm(started)))
+            return started;
         navigate(started.url);
         return started;
     }

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

@@ -2,11 +2,11 @@ export { CalimeroClient } from './client.js';
 export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 export type { Committed } from './errors.js';
 export type { AppInfo, BlobInfo, CallResult, CalimeroClientOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.js';
-export { claimedRelease, fetchAttestedKey, MOCK_QUOTE_HEADER } from './attestation.js';
+export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from './attestation.js';
 export type { AttestationDoc, CloudPolicy, CloudReleasePolicy } from './attestation.js';
 export { browserPasskey, b64url, fromB64url } from './passkey.js';
 export type { AssertionJSON, PasskeyProvider, RegistrationJSON } from './passkey.js';
-export { MAX_REPORT_PAGE, RELEASE_VERIFIER, compareVersions, consentReturn, pageQuery, pendingApprovalsFrom, publisherBindingBytes, publisherBindingMessage, releaseConsent, releaseNotesUrl, stalledBy, upgradeConsent, verifyReleaseUrl, withdrawConsent, } from './approvals.js';
-export type { ActorKind, AppsReport, Authority, ClusterRelease, ConsentReleaseModel, ConsentRequest, ConsentResult, ConsentScope, ConsentStarted, ConsentStatus, Governance, LastUpgrade, OpsAppsReport, OpsOrgsReport, PageOptions, PendingApprovals, PendingRelease, PendingUpgrade, PublisherBindingInfo, PublisherProof, ReleaseDeadline, ReleaseRules, ReportScope, ReportedApp, ReportedBundle, ReportedRelease, ReportedReplica, UpgradeAuthority, } from './approvals.js';
+export { MAX_REPORT_PAGE, RELEASE_VERIFIER, compareVersions, confirmationCode, consentReturn, pageQuery, pendingApprovalsFrom, publisherBindingBytes, publisherBindingMessage, releaseConsent, releaseNotesUrl, stalledBy, upgradeConsent, verifyReleaseUrl, withdrawConsent, } from './approvals.js';
+export type { ActorKind, AppsReport, Authority, ClusterRelease, ConsentReleaseModel, ConsentRequest, ConsentResult, ConsentScope, ConsentStarted, ConsentStatus, OpenConsentOptions, Governance, LastUpgrade, OpsAppsReport, OpsOrgsReport, PageOptions, PendingApprovals, PendingRelease, PendingUpgrade, PublisherBindingInfo, PublisherProof, ReleaseDeadline, ReleaseRules, ReportScope, ReportedApp, ReportedBundle, ReportedRelease, ReportedReplica, UpgradeAuthority, } from './approvals.js';
 export { DEFAULT_ORG_CAPABILITIES, ORG_CAPABILITIES, orgCapabilities } from './capabilities.js';
 export type { OrgCapability } from './capabilities.js';

package/dist/cloud-v2/index.js

@@ -1,6 +1,6 @@
 export { CalimeroClient } from './client.js';
 export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
-export { claimedRelease, fetchAttestedKey, MOCK_QUOTE_HEADER } from './attestation.js';
+export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from './attestation.js';
 export { browserPasskey, b64url, fromB64url } from './passkey.js';
-export { MAX_REPORT_PAGE, RELEASE_VERIFIER, compareVersions, consentReturn, pageQuery, pendingApprovalsFrom, publisherBindingBytes, publisherBindingMessage, releaseConsent, releaseNotesUrl, stalledBy, upgradeConsent, verifyReleaseUrl, withdrawConsent, } from './approvals.js';
+export { MAX_REPORT_PAGE, RELEASE_VERIFIER, compareVersions, confirmationCode, consentReturn, pageQuery, pendingApprovalsFrom, publisherBindingBytes, publisherBindingMessage, releaseConsent, releaseNotesUrl, stalledBy, upgradeConsent, verifyReleaseUrl, withdrawConsent, } from './approvals.js';
 export { DEFAULT_ORG_CAPABILITIES, ORG_CAPABILITIES, orgCapabilities } from './capabilities.js';