@calimero-network/mero-js 27.5.0 → 28.1.0

package/dist/cloud-v2/client.js

@@ -16,6 +16,44 @@ import { CalimeroError, ConfirmCancelled, ConfirmRequired, LoginRequired, Unavai
 import { b64url, fromB64url } from './passkey.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';
+/** A deployer's key, as `GET /deployers` lists it and `DELETE /deployers/{key}` takes it. */
+export function deployerKey(deployer) {
+    return 'account' in deployer ? `account:${deployer.account}` : `org:${deployer.org}`;
+}
+/**
+ * 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 async function frontendManifest(origin, fetcher = fetch) {
+    const base = origin ?? globalThis.location?.origin;
+    if (!base)
+        throw new Error('no page origin to read the frontend manifest from; pass `origin`');
+    const response = await fetcher(new URL('/.well-known/calimero.json', base).toString());
+    if (!response.ok)
+        throw await refusal(response);
+    const manifest = (await response.json());
+    return { ...manifest, deployments: manifest.deployments ?? [] };
+}
+/**
+ * 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 function pageDeployment(href) {
+    const at = href ?? globalThis.location?.href;
+    if (!at)
+        return null;
+    try {
+        return new URL(at).searchParams.get('deployment') || null;
+    }
+    catch {
+        return null;
+    }
+}
 /** One URL path segment, so an id cannot reach another route. */
 function seg(value) {
     return encodeURIComponent(value);
@@ -478,19 +516,21 @@ export class CalimeroClient {
     me() {
         return this.get('auth/me');
     }
-    /** Add another passkey (another device) to the signed-in account; answers its credential id. */
-    async addPasskey(passkey) {
+    /**
+     * 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.
+     */
+    async addPasskey(passkey, approver) {
         const begin = await this.post('auth/passkeys/add/begin');
         const registration = await passkey.create(begin.options);
-        const { credentialId } = await this.post('auth/passkeys/add/finish', {
-            challengeId: begin.challengeId,
-            registration,
-        });
+        const { credentialId } = await this.postConfirmed('auth/passkeys/add/finish', { challengeId: begin.challengeId, registration }, approver);
         return credentialId;
     }
-    /** Remove one of the account's passkeys (not the last). */
-    async removePasskey(credentialId) {
-        await this.delete(`auth/passkeys/${seg(credentialId)}`);
+    /** Remove one of the account's passkeys (not the last), approved with `passkey` (one it has). */
+    async removePasskey(credentialId, passkey) {
+        await this.deleteConfirmed(`auth/passkeys/${seg(credentialId)}`, passkey);
     }
     /** Name one of the account's passkeys (a device label); `''` clears the name. */
     async labelPasskey(credentialId, label) {
@@ -519,9 +559,13 @@ export class CalimeroClient {
     async revokeApiKey(keyId) {
         await this.delete(`auth/apikeys/${seg(keyId)}`);
     }
-    /** Create an API key for an agent or server. The key is returned once. */
-    createApiKey(options) {
-        return this.post('auth/apikeys', options);
+    /**
+     * 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, passkey) {
+        return this.postConfirmed('auth/apikeys', { ...options }, passkey);
     }
     // ---------------------------------------------------------------- apps
     /** Upload a raw WASM bundle (development clusters only); answers its hash. */
@@ -529,14 +573,41 @@ export class CalimeroClient {
         const { hash } = await this.json('POST', 'bundles', undefined, wasm);
         return hash;
     }
-    /** Upload a blob for `app`: `blobId` is base58 (what apps print), `id` hex. */
-    uploadBlob(app, data) {
-        return this.json('POST', `apps/${seg(app)}/blobs`, undefined, data);
+    /**
+     * 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, data, contentType = {}) {
+        const mime = (typeof contentType === 'string' ? contentType : contentType.contentType) ?? 'application/octet-stream';
+        return this.json('POST', `apps/${seg(app)}/blobs`, undefined, data, mime);
     }
     /** One of `app`'s blobs, by id (base58 or hex). */
     async downloadBlob(app, id) {
-        const response = await this.send('GET', `apps/${seg(app)}/blobs/${seg(id)}`);
-        return new Uint8Array(await response.arrayBuffer());
+        return (await this.blobContent(app, id)).data;
+    }
+    /**
+     * 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.
+     */
+    async downloadBlobGranted(app, id, grant) {
+        return (await this.blobContent(app, id, { grant })).data;
+    }
+    /**
+     * {@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.
+     */
+    async blobContent(app, id, options = {}) {
+        const query = options.grant === undefined ? '' : `?grant=${encodeURIComponent(options.grant)}`;
+        const response = await this.send('GET', `apps/${seg(app)}/blobs/${seg(id)}${query}`);
+        return {
+            data: new Uint8Array(await response.arrayBuffer()),
+            contentType: response.headers.get('content-type') ?? 'application/octet-stream',
+        };
     }
     /** `app`'s blobs. */
     async listBlobs(app) {
@@ -600,6 +671,15 @@ export class CalimeroClient {
     async setAppMetadata(app, metadata) {
         await this.post(`apps/${seg(app)}/metadata`, { metadata });
     }
+    /**
+     * 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) {
+        return this.get(`apps/${seg(app)}/xcalls`);
+    }
     /** What the app's storage holds: `{ keys, bytes, blobs, blobBytes }`. */
     appStorage(app) {
         return this.get(`apps/${seg(app)}/storage`);
@@ -631,12 +711,19 @@ export 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(path, body, passkey) {
         return this.confirmed('POST', path, body, passkey);
     }
-    /** {@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(path, passkey, body = {}) {
         return this.confirmed('DELETE', path, body, passkey);
     }
@@ -645,7 +732,7 @@ export class CalimeroClient {
             return await send(body);
         }
         catch (error) {
-            if (!(error instanceof ConfirmRequired))
+            if (!(error instanceof ConfirmRequired) || !passkey)
                 throw error;
             const d = error.details;
             let assertion;
@@ -666,7 +753,13 @@ export class CalimeroClient {
     /**
      * 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}.
      */
     async createApp(name, bundle, options = {}) {
         const target = typeof bundle === 'string' ? { bundle } : bundle;
@@ -973,20 +1066,24 @@ export class CalimeroClient {
     async liftReleaseDeadline(version) {
         await this.delete(`ops/releases/${seg(version)}/deadline`);
     }
-    /** Add a member, or change their role. */
-    async setMember(org, account, role) {
-        await this.post(`orgs/${seg(org)}/members`, { account, role });
+    /** Add a member, or change their role, approved with the caller's `passkey`. */
+    async setMember(org, account, role, passkey) {
+        await this.postConfirmed(`orgs/${seg(org)}/members`, { account, role }, passkey);
     }
-    removeMember(org, account) {
-        return this.delete(`orgs/${seg(org)}/members/${seg(account)}`);
+    /**
+     * Remove a member, or leave (`account` the caller's own), approved with the
+     * caller's `passkey`.
+     */
+    removeMember(org, account, passkey) {
+        return this.deleteConfirmed(`orgs/${seg(org)}/members/${seg(account)}`, passkey);
     }
     /**
      * 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`.
      */
-    async setCapabilities(org, capabilities, at = {}) {
-        await this.post(`orgs/${seg(org)}/capabilities`, { capabilities, ...at });
+    async setCapabilities(org, capabilities, passkey, at = {}) {
+        await this.postConfirmed(`orgs/${seg(org)}/capabilities`, { capabilities, ...at }, passkey);
     }
     async createTeam(org, name, join, parent) {
         const { teamId } = await this.post(`orgs/${seg(org)}/teams`, { name, join, parent });
@@ -1006,18 +1103,104 @@ export class CalimeroClient {
     async deleteTeam(org, team) {
         await this.delete(`orgs/${seg(org)}/teams/${seg(team)}`);
     }
-    /** Add a member to a team, or change their row: role, lead, capability bits. */
-    async setTeamMember(org, team, account, row = {}) {
-        await this.post(`orgs/${seg(org)}/teams/${seg(team)}/members`, { account, ...row });
+    /**
+     * Add a member to a team, or change their row: role, lead, capability bits.
+     * Approved with the caller's `passkey`.
+     */
+    async setTeamMember(org, team, account, passkey, row = {}) {
+        await this.postConfirmed(`orgs/${seg(org)}/teams/${seg(team)}/members`, { account, ...row }, passkey);
     }
-    async removeTeamMember(org, team, account) {
-        await this.delete(`orgs/${seg(org)}/teams/${seg(team)}/members/${seg(account)}`);
+    /** Remove a member from a team, approved with the caller's `passkey`. */
+    async removeTeamMember(org, team, account, passkey) {
+        await this.deleteConfirmed(`orgs/${seg(org)}/teams/${seg(team)}/members/${seg(account)}`, passkey);
     }
-    async invite(org, role, teams = [], options = {}) {
-        const { token } = await this.post(`orgs/${seg(org)}/invites`, { role, teams, ...options });
+    /**
+     * Make an invite into `org` (and `teams`), approved with the caller's
+     * `passkey`; answers its token, which {@link redeemInvite} takes (no
+     * approval there).
+     */
+    async invite(org, role, passkey, teams = [], options = {}) {
+        const { token } = await this.postConfirmed(`orgs/${seg(org)}/invites`, { role, teams, ...options }, passkey);
         return token;
     }
     redeemInvite(token) {
         return this.post(`invites/${seg(token)}/redeem`);
     }
+    // ---------------------------------------------------------------- deployers
+    /**
+     * 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, passkey, options = {}) {
+        const until = options.until instanceof Date ? options.until.toISOString() : options.until;
+        return this.postConfirmed('deployers', { deployer, ...(until === undefined ? {} : { until }) }, passkey);
+    }
+    /**
+     * 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() {
+        return this.get('deployers');
+    }
+    /**
+     * 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.
+     */
+    async revokeDeployer(deployer, passkey) {
+        const key = typeof deployer === 'string' ? deployer : deployerKey(deployer);
+        await this.deleteConfirmed(`deployers/${seg(key)}`, passkey);
+    }
+    // ---------------------------------------------------------------- deployments
+    /**
+     * 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.
+     */
+    async createDeployment(name, owner, passkey) {
+        const { id } = await this.postConfirmed('deployments', { name, owner }, passkey);
+        return id;
+    }
+    /** The deployments the caller manages: its account's, and its organizations' where it holds `MANAGE_APPLICATION`. */
+    async deployments() {
+        const { deployments } = await this.get('deployments');
+        return deployments;
+    }
+    /** A deployment as anyone may read it: its name, its owner's kind and name, and the apps it offers. Public. */
+    deployment(id) {
+        return this.get(`deployments/${seg(id)}`);
+    }
+    /** Delete a deployment that offers nothing and has no instances, approved with `passkey`. */
+    async deleteDeployment(id, passkey) {
+        await this.deleteConfirmed(`deployments/${seg(id)}`, passkey);
+    }
+    /**
+     * 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, offer, passkey) {
+        return this.postConfirmed(`deployments/${seg(id)}/apps`, { ...offer }, passkey);
+    }
+    /**
+     * Withdraw `app` from deployment `id`, approved with `passkey`; refused
+     * while an instance created from the deployment still runs it.
+     */
+    async withdrawApp(id, app, passkey) {
+        await this.deleteConfirmed(`deployments/${seg(id)}/apps/${seg(app)}`, passkey);
+    }
+    /**
+     * 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) {
+        return this.get(`deployments/${seg(id)}/orgs`);
+    }
 }

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

@@ -1,9 +1,9 @@
-export { CalimeroClient } from './client.js';
+export { CalimeroClient, deployerKey, frontendManifest, pageDeployment } from './client.js';
 export { DEFAULT_DIRECTORY, DirectoryError } from './directory.js';
 export type { DirectoryFailure } from './directory.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, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.js';
+export type { AppInfo, AppXcalls, BlobContent, BlobInfo, DeadLetter, Deployer, DeployerGrant, DeployersInfo, DeploymentInfo, DeploymentOffer, DeploymentOrgs, FrontendManifest, PublicDeployment, CallResult, CalimeroClientOptions, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, 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,4 +1,4 @@
-export { CalimeroClient } from './client.js';
+export { CalimeroClient, deployerKey, frontendManifest, pageDeployment } from './client.js';
 export { DEFAULT_DIRECTORY, DirectoryError } from './directory.js';
 export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from './attestation.js';