@calimero-network/mero-js 27.5.0 → 28.1.0

package/README.md

@@ -97,12 +97,12 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 
 ## The API
 
-- **Credentials**: `signUp`, `signIn`, `refresh`, `signOut`, `signOutEverywhere`, `useSession`, `useApiKey`, `me`, `usage`, `addPasskey`, `labelPasskey`, `removePasskey`, `createApiKey`, `listApiKeys`, `revokeApiKey`.
+- **Credentials**: `signUp`, `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.
 - **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.
 - **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`.
+- **Organizations**: `createOrg`, `getOrg`, `deleteOrg`, `setOrgMetadata`, `setMember`, `removeMember`, `setMemberMetadata`, `setCapabilities` (`ORG_CAPABILITIES`), teams, `invite`, `redeemInvite`. 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`.

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

@@ -26,6 +26,10 @@ export interface Governance {
     releases: Authority;
     appUpgrades: Authority;
     outbound: Authority;
+    /** Who may install apps: any account (`open`, left out) or granted deployers only. */
+    deployments?: 'open' | 'granted';
+    /** Who grants deployers: the operator (left out) or the cluster's owner. */
+    deployers?: 'operator' | 'owner';
 }
 /**
  * Who upgrades a package's instances, as its signed manifest declares

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

@@ -72,6 +72,8 @@ export interface AppInfo {
     bundle: string;
     package: string | null;
     version: string | null;
+    /** The deployment it was created from, if any. */
+    deployment?: string | null;
 }
 /**
  * An organization-wide upgrade run, as `upgradeOrg`, `upgradeRun` and
@@ -130,6 +132,145 @@ export interface OrgInfo extends Record<string, unknown> {
         after: string;
     } | null;
 }
+/** A blob's bytes with the content type the node serves them as. */
+export interface BlobContent {
+    data: Uint8Array;
+    /** What the uploader gave (component apps); `application/octet-stream` otherwise. */
+    contentType: string;
+}
+/** One xcall that was never delivered (core's `DeadLetter`). */
+export interface DeadLetter {
+    seq: number;
+    /** The target app. */
+    app: string;
+    method: string;
+    reason: string;
+    /** The log entry's timestamp it was dead-lettered at (ms since the epoch). */
+    atMs: number;
+}
+/** `GET /apps/{app}/xcalls`: a component app's outbox and its dead letters, newest last. */
+export interface AppXcalls {
+    /** Messages waiting in the outbox. */
+    pending: number;
+    deadLetters: DeadLetter[];
+}
+/**
+ * An account or an organization, as a deployer, a deployment's owner or the
+ * cluster's owner: `{ account: id }` or `{ org: id }`.
+ */
+export type Deployer = {
+    account: string;
+} | {
+    org: string;
+};
+/** A deployer's key, as `GET /deployers` lists it and `DELETE /deployers/{key}` takes it. */
+export declare function deployerKey(deployer: Deployer): string;
+/** One deployer grant, as `GET /deployers` lists it. */
+export interface DeployerGrant {
+    /** `account:{id}` or `org:{id}`. */
+    key: string;
+    deployer: Deployer | null;
+    /** RFC 3339; `null`: it does not end. */
+    until: string | null;
+    untilSecs: number | null;
+    grantedAt: string;
+    grantedBy: string;
+}
+/** `GET /deployers`: who may install apps on the cluster, and who grants it. */
+export interface DeployersInfo {
+    /** `open` (any account) or `granted` (deployers only); absent on a default cluster. */
+    deployments?: 'open' | 'granted';
+    /** Who grants deployers: `operator` (its key) or `owner` (the cluster's owner, with a passkey). */
+    deployers?: 'operator' | 'owner';
+    owner: Deployer | null;
+    grants: DeployerGrant[];
+}
+/** One app a deployment offers, as its managers read it. */
+export interface DeploymentOffer {
+    /** The app's name in the deployment. */
+    app: string;
+    package: string;
+    version: string;
+    addedBy: string;
+    /** RFC 3339. */
+    addedAt: string;
+}
+/** A deployment as its managers read it (`GET /deployments`). */
+export interface DeploymentInfo {
+    id: string;
+    name: string;
+    owner: Deployer;
+    apps: DeploymentOffer[];
+    createdBy: string;
+    /** RFC 3339. */
+    createdAt: string;
+}
+/**
+ * `GET /deployments/{id}`, public: what a frontend and the customer's consent
+ * show. Never its managers, members or customers.
+ */
+export interface PublicDeployment {
+    id: string;
+    name: string;
+    /** The owner's kind and name (`null` if it is gone). */
+    owner: {
+        kind: 'account' | 'org';
+        name: string | null;
+    };
+    apps: Array<{
+        app: string;
+        package: string;
+        version: string;
+    }>;
+}
+/** `GET /deployments/{id}/orgs`: the organizations with instances created from a deployment. */
+export interface DeploymentOrgs {
+    deployment: string;
+    orgs: Array<{
+        orgId: string;
+        name: string | null;
+        instances: number;
+        /** Which of the deployment's apps they run, at which release. */
+        apps: Array<{
+            app: string;
+            version: string;
+        }>;
+        /** RFC 3339: when its first instance from the deployment was created. */
+        firstCreatedAt: string;
+    }>;
+    /** Instances outside any organization, counted only. */
+    outsideOrgs: number;
+}
+/**
+ * A package frontend's `/.well-known/calimero.json`: the package, its
+ * releases, the deployments offering it and the cluster's API URLs.
+ */
+export interface FrontendManifest {
+    package: string;
+    versions: string[];
+    deployments: Array<{
+        id: string;
+        name: string;
+        app: string;
+        version: string;
+    }>;
+    api: string[];
+}
+/**
+ * Read the `/.well-known/calimero.json` of the frontend at `origin` (by
+ * default the page's own). Served in the clear by the frontend host, like the
+ * page itself: for choosing a deployment and the API URL to connect to, never
+ * for trust (the client attests the node it then talks to).
+ */
+export declare function frontendManifest(origin?: string, fetcher?: typeof fetch): Promise<FrontendManifest>;
+/**
+ * The deployment a frontend page was opened for: the node serves
+ * `/d/{deployment}/` by redirecting to `/{version}/…?deployment={id}`, so the
+ * page creates its instances from that deployment
+ * (`createApp(name, { deployment, package })`). `null` when the page was
+ * not opened through a deployment. `href` defaults to `window.location.href`.
+ */
+export declare function pageDeployment(href?: string): string | null;
 /**
  * How a call or a view is sent again while the node is unavailable (D70): with
  * the same key, after a backoff that starts at `baseDelayMs` and doubles up to
@@ -320,10 +461,15 @@ export declare class CalimeroClient {
     /** End every session of the signed-in account, on every device, this one too. */
     signOutEverywhere(): Promise<void>;
     me(): Promise<Record<string, unknown>>;
-    /** Add another passkey (another device) to the signed-in account; answers its credential id. */
-    addPasskey(passkey: PasskeyProvider): Promise<string>;
-    /** Remove one of the account's passkeys (not the last). */
-    removePasskey(credentialId: string): Promise<void>;
+    /**
+     * Add another passkey (another device, `passkey`) to the signed-in account;
+     * answers its credential id. The node asks for the approval of a passkey
+     * the account already has (`412 CONFIRM_REQUIRED`, never the new one),
+     * which `approver` gives.
+     */
+    addPasskey(passkey: PasskeyProvider, approver: PasskeyProvider): Promise<string>;
+    /** Remove one of the account's passkeys (not the last), approved with `passkey` (one it has). */
+    removePasskey(credentialId: string, passkey: PasskeyProvider): Promise<void>;
     /** Name one of the account's passkeys (a device label); `''` clears the name. */
     labelPasskey(credentialId: string, label: string): Promise<void>;
     /** What this account uses (apps, bundle bytes, API keys, owned orgs), with the cluster's quotas. */
@@ -336,7 +482,11 @@ export declare class CalimeroClient {
     /** The account's API keys (never the keys themselves). */
     listApiKeys(): Promise<Array<Record<string, unknown>>>;
     revokeApiKey(keyId: string): Promise<void>;
-    /** Create an API key for an agent or server. The key is returned once. */
+    /**
+     * Create an API key for an agent or server, approved with the account's
+     * `passkey` (`412 CONFIRM_REQUIRED`); needs a passkey session (an API key
+     * is refused `403`). The key is returned once.
+     */
     createApiKey(options: {
         label?: string;
         apps?: string[];
@@ -344,20 +494,42 @@ export declare class CalimeroClient {
         readOnly?: boolean;
         allowConfirm?: boolean;
         ttlSecs?: number;
-    }): Promise<{
+    }, passkey: PasskeyProvider): Promise<{
         keyId: string;
         key: string;
     }>;
     /** Upload a raw WASM bundle (development clusters only); answers its hash. */
     uploadBundle(wasm: Uint8Array): Promise<string>;
-    /** Upload a blob for `app`: `blobId` is base58 (what apps print), `id` hex. */
-    uploadBlob(app: string, data: Uint8Array): Promise<{
+    /**
+     * Upload a blob for `app`: `blobId` is base58 (what apps print), `id` hex.
+     * `contentType` (default `application/octet-stream`; printable ASCII, the
+     * node refuses another with `400`) is sent as the upload's `Content-Type`:
+     * a component app records it and serves downloads with it. A component
+     * app holding as many blobs as it may answers `429 QUOTA_EXCEEDED`.
+     */
+    uploadBlob(app: string, data: Uint8Array, contentType?: string | {
+        contentType?: string;
+    }): Promise<{
         blobId: string;
         id: string;
         size: number;
     }>;
     /** One of `app`'s blobs, by id (base58 or hex). */
     downloadBlob(app: string, id: string): Promise<Uint8Array>;
+    /**
+     * Download a component app's blob with a grant one of its runs handed out
+     * (`BlobRef::grant`, up to 24 h). No session needed: the grant is the
+     * permission. A bad or expired grant answers `NotFound`, as a missing blob.
+     */
+    downloadBlobGranted(app: string, id: string, grant: string): Promise<Uint8Array>;
+    /**
+     * {@link downloadBlob} (or, with `grant`, {@link downloadBlobGranted}) with
+     * the content type the node serves it as: the uploader's, for a component
+     * app; `application/octet-stream` otherwise.
+     */
+    blobContent(app: string, id: string, options?: {
+        grant?: string;
+    }): Promise<BlobContent>;
     /** `app`'s blobs. */
     listBlobs(app: string): Promise<BlobInfo[]>;
     /** One of `app`'s blobs' id and size; `NotFound` if the app has no such blob. */
@@ -386,6 +558,13 @@ export declare class CalimeroClient {
     setAccess(app: string, access: Record<string, unknown>): Promise<void>;
     /** Set the app instance's metadata (its owner, or an admin of its organization); at most 16 KiB. */
     setAppMetadata(app: string, metadata: unknown): Promise<void>;
+    /**
+     * A component app's xcalls: how many messages wait in its outbox, and the
+     * dead letters (never delivered), newest last. Its owner's or an org
+     * admin's (`403` to anyone else); `409 NOT_SUPPORTED` for an app on the
+     * wasmer runtime, whose xcalls are follow-ups.
+     */
+    appXcalls(app: string): Promise<AppXcalls>;
     /** What the app's storage holds: `{ keys, bytes, blobs, blobBytes }`. */
     appStorage(app: string): Promise<Record<string, unknown>>;
     /** The ABI the app's bundle embeds: `{ bundle, abi }`. */
@@ -418,21 +597,35 @@ export declare class CalimeroClient {
     }>;
     /**
      * POST `body` to `path`, answering a `412 CONFIRM_REQUIRED` with `passkey`'s
-     * assertion over the node's challenge (deleting an org, approving a release, ...).
+     * assertion over the node's challenge (deleting an org, approving a release,
+     * adding a member, ...): the same body again, with `confirm`. Without a
+     * passkey (a caller in plain JavaScript passing none) the `412` reaches the
+     * caller as {@link ConfirmRequired}, carrying the challenge.
      */
     postConfirmed<T>(path: string, body: Record<string, unknown>, passkey: PasskeyProvider): Promise<T>;
-    /** {@link postConfirmed} for a DELETE (deleting an organization). */
+    /**
+     * {@link postConfirmed} for a DELETE (deleting an organization, removing a
+     * member or a passkey): `body` (`{}` by default) goes as JSON, and the
+     * confirmed retry carries `confirm` beside it.
+     */
     deleteConfirmed<T>(path: string, passkey: PasskeyProvider, body?: Record<string, unknown>): Promise<T>;
     private confirmed;
     /**
      * Create an app instance from a bundle hash, or from a package release
      * (`{ package, version?, service? }`, installed from the registry first if
-     * the cluster lacks it).
+     * the cluster lacks it). With `deployment`, the instance runs the release
+     * that deployment offers for `package` (`version`, if given, must be it)
+     * and records the deployment; no install, no deployer grant. A package or
+     * version it does not offer answers `400 NOT_OFFERED`, several offered
+     * releases with no `version` `400 VERSION_REQUIRED`, and an unknown
+     * `service` `400 NO_SUCH_SERVICE`. A page opened through `/d/{deployment}/`
+     * finds its deployment with {@link pageDeployment}.
      */
     createApp(name: string, bundle: string | {
         package: string;
         version?: string;
         service?: string;
+        deployment?: string;
     }, options?: {
         org?: string;
         access?: Record<string, unknown>;
@@ -612,15 +805,19 @@ export declare class CalimeroClient {
     setReleaseDeadline(version: string, after: Date | string): Promise<void>;
     /** Lift a release's deadline. Operator token. */
     liftReleaseDeadline(version: string): Promise<void>;
-    /** Add a member, or change their role. */
-    setMember(org: string, account: string, role: 'guest' | 'member' | 'admin' | 'owner'): Promise<void>;
-    removeMember(org: string, account: string): Promise<Record<string, unknown>>;
+    /** Add a member, or change their role, approved with the caller's `passkey`. */
+    setMember(org: string, account: string, role: 'guest' | 'member' | 'admin' | 'owner', passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Remove a member, or leave (`account` the caller's own), approved with the
+     * caller's `passkey`.
+     */
+    removeMember(org: string, account: string, passkey: PasskeyProvider): Promise<Record<string, unknown>>;
     /**
      * Set capability bits ({@link ORG_CAPABILITIES}): for a member (`account`),
      * for a member of one team (`account` and `team`), or the organization's
-     * default (neither).
+     * default (neither). Approved with the caller's `passkey`.
      */
-    setCapabilities(org: string, capabilities: number, at?: {
+    setCapabilities(org: string, capabilities: number, passkey: PasskeyProvider, at?: {
         account?: string;
         team?: string;
     }): Promise<void>;
@@ -638,16 +835,90 @@ export declare class CalimeroClient {
     }): Promise<void>;
     /** Delete a team, the teams below it and their apps. */
     deleteTeam(org: string, team: string): Promise<void>;
-    /** Add a member to a team, or change their row: role, lead, capability bits. */
-    setTeamMember(org: string, team: string, account: string, row?: {
+    /**
+     * Add a member to a team, or change their row: role, lead, capability bits.
+     * Approved with the caller's `passkey`.
+     */
+    setTeamMember(org: string, team: string, account: string, passkey: PasskeyProvider, row?: {
         role?: 'lead' | 'member' | 'readOnly';
         lead?: boolean;
         capabilities?: number;
     }): Promise<void>;
-    removeTeamMember(org: string, team: string, account: string): Promise<void>;
-    invite(org: string, role: 'guest' | 'member' | 'admin', teams?: string[], options?: {
+    /** Remove a member from a team, approved with the caller's `passkey`. */
+    removeTeamMember(org: string, team: string, account: string, passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Make an invite into `org` (and `teams`), approved with the caller's
+     * `passkey`; answers its token, which {@link redeemInvite} takes (no
+     * approval there).
+     */
+    invite(org: string, role: 'guest' | 'member' | 'admin', passkey: PasskeyProvider, teams?: string[], options?: {
         ttlSecs?: number;
         uses?: number;
     }): Promise<string>;
     redeemInvite(token: string): Promise<Record<string, unknown>>;
+    /**
+     * Let an account or organization install apps where the cluster's
+     * deployments are `granted`, until `until` (RFC 3339 or a `Date`; absent,
+     * the grant does not end). The cluster's owner grants it, approved with
+     * `passkey`, where governance says `deployers: owner`; elsewhere the
+     * operator grants with its key, and this is refused `403`.
+     */
+    grantDeployer(deployer: Deployer, passkey: PasskeyProvider, options?: {
+        until?: Date | string;
+    }): Promise<{
+        key: string;
+        deployer: Deployer;
+        grant: Record<string, unknown>;
+    }>;
+    /**
+     * Who may install apps on the cluster: its deployments rule, who grants
+     * deployers, its owner and every grant. For the cluster's owner, or the
+     * operator (its token, `useApiKey`).
+     */
+    deployers(): Promise<DeployersInfo>;
+    /**
+     * End a deployer's grant (`deployer`, or its key `account:{id}` /
+     * `org:{id}`), as the cluster's owner, approved with `passkey`. Apps it
+     * installed, and the apps running them, stay.
+     */
+    revokeDeployer(deployer: Deployer | string, passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Create a deployment: `owner`'s (the caller's own account, or an
+     * organization where it holds `MANAGE_APPLICATION` org-wide) list of the
+     * apps it offers, named `name` (1 to 64 characters, one line) for
+     * customers. Approved with `passkey`; where deployments are `granted` the
+     * caller needs a deployer grant. Answers the deployment's id.
+     */
+    createDeployment(name: string, owner: Deployer, passkey: PasskeyProvider): Promise<string>;
+    /** The deployments the caller manages: its account's, and its organizations' where it holds `MANAGE_APPLICATION`. */
+    deployments(): Promise<DeploymentInfo[]>;
+    /** A deployment as anyone may read it: its name, its owner's kind and name, and the apps it offers. Public. */
+    deployment(id: string): Promise<PublicDeployment>;
+    /** Delete a deployment that offers nothing and has no instances, approved with `passkey`. */
+    deleteDeployment(id: string, passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Offer `package@version` (installed, and seen by the caller) as `app`
+     * (1 to 64 letters, digits, `.`, `_`, `-`) in deployment `id`, or move an
+     * offered app to another release of its package. Approved with `passkey`.
+     */
+    offerApp(id: string, offer: {
+        app: string;
+        package: string;
+        version: string;
+    }, passkey: PasskeyProvider): Promise<{
+        deployment: string;
+        app: string;
+        offer: Record<string, unknown>;
+    }>;
+    /**
+     * Withdraw `app` from deployment `id`, approved with `passkey`; refused
+     * while an instance created from the deployment still runs it.
+     */
+    withdrawApp(id: string, app: string, passkey: PasskeyProvider): Promise<void>;
+    /**
+     * The organizations with instances created from deployment `id`, for its
+     * managers: each one's id, name, instance count, apps and releases, and
+     * first instance. Never members, teams or app data.
+     */
+    deploymentOrgs(id: string): Promise<DeploymentOrgs>;
 }