@calimero-network/mero-js 29.5.0 → 29.6.0

package/README.md

@@ -99,7 +99,7 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 
 - **Credentials**: `signUp` (with an `invite`, on a cluster that takes new accounts by invite; `signUpPolicy` reads which), `signIn`, `refresh`, `signOut`, `signOutEverywhere`, `useSession`, `useApiKey`, `me`, `usage`, `addPasskey`, `labelPasskey`, `removePasskey`, `createApiKey`, `listApiKeys`, `revokeApiKey`. Adding or removing a passkey and creating an API key are approved with a passkey the account already has.
 - **Account recovery** (core #4844): `createRecoveryCode`, `removeRecoveryCode` (passkey-approved; the code is shown once), then signed out `startAccountRecovery(code, passkey)` and, 72 hours later, `finishAccountRecovery(passkey, accountId?)`; a passkey the account still has cancels in between (`cancelAccountRecovery`; `me()` shows `recoveryCode` and `recoveryPending`).
-- **Package origins**: `packageOrigins.list`, `packageOrigins.add`, `packageOrigins.remove`. A package's managers register the web origins of a frontend they host themselves (approved with a passkey); `signUp` and `signIn` on such a page send its origin, sign for that origin's relying-party id, and open a session bound to the package (`me()` answers its `app` and `origin`). An unregistered origin is refused with `OriginNotRegistered`.
+- **Package origins**: `packageOrigins.list`, `packageOrigins.add`, `packageOrigins.remove`. A package's managers register the web origins of a frontend they host themselves (approved with a passkey); `signUp` and `signIn` on such a page send its origin, sign for that origin's relying-party id, and open a session bound to the package (`me()` answers its `app` and `origin`). An unregistered origin is refused with `OriginNotRegistered`. `packageOrigins.add(pkg, origin, passkey, { served: true })` registers a custom domain: the cluster also serves the package's frontend there from its signed bundle (`https://host`, no port; the passkey's consent names `served: true`); `list` answers `served` on each origin, and the extra refusals are `NotServing` (the cluster serves no frontends), `ClusterNotUpgraded` (a node is on an older release), `QuotaExceeded` (4 served per package, 64 per cluster) and `OriginTaken` (held with the other `served`).
 - **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`, then to the next node.
@@ -107,7 +107,7 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 - **Organizations**: `createOrg`, `getOrg`, `deleteOrg`, `setOrgMetadata`, `setMember`, `removeMember`, `setMemberMetadata`, `setCapabilities` (`ORG_CAPABILITIES`), teams, `invite`, `redeemInvite`, recovery (`setRecoveryKey`, `startRecovery`, `cancelRecovery`, `finishRecovery`; `newRecoverySeed`, `recoveryPublicKey`). Setting or removing a member or team member, capabilities and invites are approved with the caller's passkey; redeeming an invite is not.
 - **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`. 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`.
+- **Operator** (ops token): `opsApps`, `opsOrgs`, `opsServedOrigins` (every custom domain the log holds, by package label), `setReleaseDeadline`, `liftReleaseDeadline`.
 - **Any route**: `get`, `post`, `put`, `delete`; `postConfirmed` and `deleteConfirmed` answer a `412 CONFIRM_REQUIRED` with a passkey.
 
 Refusals are typed (`LoginRequired`, `WrongNode`, `NotFound`, `ConfirmRequired`, `ConfirmCancelled`,

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

@@ -331,6 +331,12 @@ export interface PackageOrigin {
     /** The account that registered it. */
     addedBy: string;
     addedAt: string | number;
+    /**
+     * The cluster serves the package's frontend on this origin too (a custom
+     * domain, from its signed bundle). Absent (`false`) from a node that
+     * predates served origins.
+     */
+    served?: boolean;
 }
 /** What registering an origin answers. */
 export interface PackageOriginAdded extends PackageOrigin {
@@ -356,9 +362,21 @@ export interface PackageOrigins {
      * caller as {@link ConfirmRequired}). `rpId` defaults to the node's choice
      * for the origin (its host). Refusals: {@link BadOrigin} (`BAD_ORIGIN`,
      * `BAD_RP_ID`), {@link OriginTaken}, {@link QuotaExceeded}.
+     *
+     * `served: true` makes it a custom domain: the cluster also serves the
+     * package's frontend on it (`https://host`, no port; never a name under the
+     * apps domain or the cluster's rp-id), and the consent the passkey signs
+     * names it (`{ origin, rpId, served: true }`). Further refusals:
+     * {@link NotServing} (the cluster serves no frontends),
+     * {@link ClusterNotUpgraded} (a node of the cluster is on an older release),
+     * {@link QuotaExceeded} for the served limits (4 per package, 64 per
+     * cluster), {@link OriginTaken} when the origin is held with the other
+     * `served` (remove it first). Serving it to browsers also needs the
+     * certificate and route Calimero Cloud sets up for the domain.
      */
     add(pkg: string, origin: string, passkey?: PasskeyProvider, options?: {
         rpId?: string;
+        served?: boolean;
     }): Promise<PackageOriginAdded>;
     /**
      * Remove `origin` from `pkg`, approved with `passkey` (`__remove_origin`).
@@ -366,6 +384,22 @@ export interface PackageOrigins {
      */
     remove(pkg: string, origin: string, passkey?: PasskeyProvider): Promise<PackageOriginRemoved>;
 }
+/** One served origin (custom domain) of the cluster, as `GET /ops/served-origins` lists it. */
+export interface ServedOrigin {
+    /** `https://host`. */
+    origin: string;
+    /** The origin's host, the name a certificate and a route are for. */
+    host: string;
+    /** The package's app-host label (`{label}.{apps domain}`); the listing names no package. */
+    label: string;
+    addedAt: string;
+}
+/** `GET /ops/served-origins`: every served origin the cluster's log holds. Operator token. */
+export interface ServedOrigins {
+    /** This node had caught up with the system leader. */
+    fresh: boolean;
+    origins: ServedOrigin[];
+}
 /**
  * Where a sign-up or sign-in says it runs. By default the page's origin
  * (`window.location.origin`) when it is not the origin of a node the client
@@ -1035,6 +1069,12 @@ export declare class CalimeroClient {
     opsApps(page?: PageOptions): Promise<OpsAppsReport>;
     /** `GET /ops/orgs`: each organization's approved releases. Operator token. */
     opsOrgs(page?: PageOptions): Promise<OpsOrgsReport>;
+    /**
+     * `GET /ops/served-origins`: every served origin (custom domain) the
+     * cluster's log holds, with its package's label and no package name or
+     * account. Operator token.
+     */
+    opsServedOrigins(): Promise<ServedOrigins>;
     /**
      * Announce when work on images older than `version` ends: from `after` on,
      * a scope that has not approved it (or newer) starts no new work. Operator

package/dist/cloud-v2/client.js

@@ -200,7 +200,14 @@ export class CalimeroClient {
                 const { origins } = await this.get(`package-origins/${seg(pkg)}`);
                 return origins ?? [];
             },
-            add: (pkg, origin, passkey, options = {}) => this.confirmed('POST', `package-origins/${seg(pkg)}`, options.rpId === undefined ? { origin } : { origin, rpId: options.rpId }, passkey),
+            add: (pkg, origin, passkey, options = {}) => this.confirmed('POST', `package-origins/${seg(pkg)}`, 
+            // Only the fields set: the node refuses unknown ones, and one that
+            // predates served origins takes a plain add unchanged.
+            {
+                origin,
+                ...(options.rpId === undefined ? {} : { rpId: options.rpId }),
+                ...(options.served ? { served: true } : {}),
+            }, passkey),
             remove: (pkg, origin, passkey) => this.confirmed('DELETE', `package-origins/${seg(pkg)}`, { origin }, passkey),
         };
         const trim = (url) => url.replace(/\/+$/, '');
@@ -1241,6 +1248,14 @@ export class CalimeroClient {
     opsOrgs(page = {}) {
         return this.get(`ops/orgs${pageQuery(page)}`);
     }
+    /**
+     * `GET /ops/served-origins`: every served origin (custom domain) the
+     * cluster's log holds, with its package's label and no package name or
+     * account. Operator token.
+     */
+    opsServedOrigins() {
+        return this.get('ops/served-origins');
+    }
     /**
      * Announce when work on images older than `version` ends: from `after` on,
      * a scope that has not approved it (or newer) starts no new work. Operator

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

@@ -117,15 +117,40 @@ export declare class OriginNotRegistered extends CalimeroError {
  * `400 BAD_ORIGIN` or `400 BAD_RP_ID`: the node does not accept the origin a
  * package's manager tried to register (it must be a bare web origin,
  * `scheme://host[:port]`), or the relying-party id given for it (which must
- * fit the origin's host). `code` says which.
+ * fit the origin's host). `code` says which. A served origin (`served: true`)
+ * must also be `https://host` with no port, and not a name under the
+ * cluster's apps domain or its rp-id.
  */
 export declare class BadOrigin extends CalimeroError {
     constructor(code: 'BAD_ORIGIN' | 'BAD_RP_ID', message: string, details?: Record<string, unknown>);
 }
-/** `409 ORIGIN_TAKEN`: the origin is registered already (for this package or another). */
+/**
+ * `409 ORIGIN_TAKEN`: the origin is registered already (for another package,
+ * or for this one with the other `served`: remove it first), or it is one of
+ * the cluster's own (a node's API host, a cluster origin, a frontend it
+ * serves).
+ */
 export declare class OriginTaken extends CalimeroError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * `400 NOT_SERVING`: a served origin (a custom domain, `served: true`) was
+ * asked of a cluster that serves no frontends (merod without
+ * `--apps-domain`). Register the origin unserved, or use a cluster that
+ * serves them.
+ */
+export declare class NotServing extends CalimeroError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * `409 CLUSTER_NOT_UPGRADED`: the change needs every node of the cluster
+ * (replicas, voters and learners) on the node's release or later, and one
+ * is not yet; for instance adding a served origin. Retry once the cluster is
+ * upgraded.
+ */
+export declare class ClusterNotUpgraded extends CalimeroError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
 /**
  * `409 RECOVERY_NOT_READY`: a recovery (an account's or an organization's)
  * may finish only once its 72-hour delay has passed. `readyAt` is when it may
@@ -164,7 +189,10 @@ export declare class SignUpRefused extends CalimeroError {
     readonly reason: SignUpRefusal;
     constructor(message: string, details?: Record<string, unknown>);
 }
-/** `429 QUOTA_EXCEEDED`: the caller holds as many of something (origins, blobs, ...) as it may. */
+/**
+ * `429 QUOTA_EXCEEDED`: the caller holds as many of something (origins,
+ * served origins per package or per cluster, blobs, ...) as it may.
+ */
 export declare class QuotaExceeded extends CalimeroError {
     constructor(message: string, details?: Record<string, unknown>);
 }

package/dist/cloud-v2/errors.js

@@ -150,7 +150,9 @@ export class OriginNotRegistered extends CalimeroError {
  * `400 BAD_ORIGIN` or `400 BAD_RP_ID`: the node does not accept the origin a
  * package's manager tried to register (it must be a bare web origin,
  * `scheme://host[:port]`), or the relying-party id given for it (which must
- * fit the origin's host). `code` says which.
+ * fit the origin's host). `code` says which. A served origin (`served: true`)
+ * must also be `https://host` with no port, and not a name under the
+ * cluster's apps domain or its rp-id.
  */
 export class BadOrigin extends CalimeroError {
     constructor(code, message, details = {}) {
@@ -158,13 +160,42 @@ export class BadOrigin extends CalimeroError {
         this.name = 'BadOrigin';
     }
 }
-/** `409 ORIGIN_TAKEN`: the origin is registered already (for this package or another). */
+/**
+ * `409 ORIGIN_TAKEN`: the origin is registered already (for another package,
+ * or for this one with the other `served`: remove it first), or it is one of
+ * the cluster's own (a node's API host, a cluster origin, a frontend it
+ * serves).
+ */
 export class OriginTaken extends CalimeroError {
     constructor(message, details = {}) {
         super(409, 'ORIGIN_TAKEN', message, details);
         this.name = 'OriginTaken';
     }
 }
+/**
+ * `400 NOT_SERVING`: a served origin (a custom domain, `served: true`) was
+ * asked of a cluster that serves no frontends (merod without
+ * `--apps-domain`). Register the origin unserved, or use a cluster that
+ * serves them.
+ */
+export class NotServing extends CalimeroError {
+    constructor(message, details = {}) {
+        super(400, 'NOT_SERVING', message, details);
+        this.name = 'NotServing';
+    }
+}
+/**
+ * `409 CLUSTER_NOT_UPGRADED`: the change needs every node of the cluster
+ * (replicas, voters and learners) on the node's release or later, and one
+ * is not yet; for instance adding a served origin. Retry once the cluster is
+ * upgraded.
+ */
+export class ClusterNotUpgraded extends CalimeroError {
+    constructor(message, details = {}) {
+        super(409, 'CLUSTER_NOT_UPGRADED', message, details);
+        this.name = 'ClusterNotUpgraded';
+    }
+}
 /**
  * `409 RECOVERY_NOT_READY`: a recovery (an account's or an organization's)
  * may finish only once its 72-hour delay has passed. `readyAt` is when it may
@@ -223,7 +254,10 @@ function signUpRefusal(message) {
         return 'org-gone';
     return 'other';
 }
-/** `429 QUOTA_EXCEEDED`: the caller holds as many of something (origins, blobs, ...) as it may. */
+/**
+ * `429 QUOTA_EXCEEDED`: the caller holds as many of something (origins,
+ * served origins per package or per cluster, blobs, ...) as it may.
+ */
 export class QuotaExceeded extends CalimeroError {
     constructor(message, details = {}) {
         super(429, 'QUOTA_EXCEEDED', message, details);
@@ -321,6 +355,10 @@ export function errorFrom(status, body, retryAfterHeader) {
             return new BadOrigin(code, message, details);
         case '409 ORIGIN_TAKEN':
             return new OriginTaken(message, details);
+        case '400 NOT_SERVING':
+            return new NotServing(message, details);
+        case '409 CLUSTER_NOT_UPGRADED':
+            return new ClusterNotUpgraded(message, details);
         case '429 QUOTA_EXCEEDED':
             return new QuotaExceeded(message, details);
         case '409 RECOVERY_NOT_READY':

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

@@ -1,9 +1,9 @@
 export { CalimeroClient, deployerKey, frontendManifest, pageDeployment } from './client.js';
 export { DEFAULT_DIRECTORY, DirectoryError } from './directory.js';
 export type { DirectoryFailure } from './directory.js';
-export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, RecoveryNotReady, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ClusterNotUpgraded, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, NotServing, OriginNotRegistered, OriginTaken, QuotaExceeded, RecoveryNotReady, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
 export type { Committed, SignUpRefusal } from './errors.js';
-export type { AppInfo, AppXcalls, BlobContent, BlobInfo, DeadLetter, Deployer, DeployerGrant, DeployersInfo, DeploymentInfo, DeploymentOffer, DeploymentOrgs, FrontendManifest, MeInfo, PackageOrigin, PackageOriginAdded, PackageOriginRemoved, PackageOrigins, SignInOptions, AccountRecovery, SignUpOptions, SignUpPolicy, PublicDeployment, CallResult, CalimeroClientOptions, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgRecovery, RecoveryTimes, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.js';
+export type { AppInfo, AppXcalls, BlobContent, BlobInfo, DeadLetter, Deployer, DeployerGrant, DeployersInfo, DeploymentInfo, DeploymentOffer, DeploymentOrgs, FrontendManifest, MeInfo, PackageOrigin, PackageOriginAdded, PackageOriginRemoved, PackageOrigins, ServedOrigin, ServedOrigins, SignInOptions, AccountRecovery, SignUpOptions, SignUpPolicy, PublicDeployment, CallResult, CalimeroClientOptions, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgRecovery, RecoveryTimes, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.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';

package/dist/cloud-v2/index.js

@@ -1,6 +1,6 @@
 export { CalimeroClient, deployerKey, frontendManifest, pageDeployment } from './client.js';
 export { DEFAULT_DIRECTORY, DirectoryError } from './directory.js';
-export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, RecoveryNotReady, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ClusterNotUpgraded, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, NotServing, OriginNotRegistered, OriginTaken, QuotaExceeded, RecoveryNotReady, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
 export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from './attestation.js';
 export { browserPasskey, b64url, fromB64url } from './passkey.js';
 export { MAX_RECOVERY_NONCE_BYTES, RECOVERY_DOMAIN, newRecoverySeed, parseRecoverySeed, recoveryMessage, recoveryPublicKey, recoverySeedText, signRecovery, } from './recovery.js';