@calimero-network/mero-js 26.11.0 → 27.0.0

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

@@ -0,0 +1,30 @@
+/**
+ * What a member may do in an organization beyond their role, as core's
+ * `caps` bits (`setCapabilities`, `setTeamMember`'s `capabilities`). A team's
+ * lead and an organization's admin hold them all.
+ */
+export declare const ORG_CAPABILITIES: {
+    /** Create an app in the organization (on its team, or org-wide). */
+    readonly CREATE_APP: number;
+    /** Mint invites (org-wide, or on each team the invite names). */
+    readonly INVITE_MEMBERS: number;
+    /** Inherited into open teams; denying it keeps a member out of them. */
+    readonly JOIN_OPEN_TEAMS: number;
+    /** Add and remove a team's members. */
+    readonly MANAGE_MEMBERS: number;
+    /** Upgrade the organization's apps, start org upgrade runs, approve outbound hosts (org-wide). */
+    readonly MANAGE_APPLICATION: number;
+    /** Create a top-level team without being an admin. */
+    readonly CREATE_TEAM: number;
+    /** Delete a team, and what it holds, without being an admin. */
+    readonly DELETE_TEAM: number;
+    /** Change who may join a team (open or invite-only). */
+    readonly MANAGE_VISIBILITY: number;
+    /** Set the organization's and its teams' metadata. */
+    readonly MANAGE_METADATA: number;
+};
+export type OrgCapability = keyof typeof ORG_CAPABILITIES;
+/** What a member holds unless an admin says otherwise. */
+export declare const DEFAULT_ORG_CAPABILITIES: number;
+/** The bitmask of `names`. */
+export declare function orgCapabilities(...names: OrgCapability[]): number;

package/dist/cloud-v2/capabilities.js

@@ -0,0 +1,31 @@
+/**
+ * What a member may do in an organization beyond their role, as core's
+ * `caps` bits (`setCapabilities`, `setTeamMember`'s `capabilities`). A team's
+ * lead and an organization's admin hold them all.
+ */
+export const ORG_CAPABILITIES = {
+    /** Create an app in the organization (on its team, or org-wide). */
+    CREATE_APP: 1 << 0,
+    /** Mint invites (org-wide, or on each team the invite names). */
+    INVITE_MEMBERS: 1 << 1,
+    /** Inherited into open teams; denying it keeps a member out of them. */
+    JOIN_OPEN_TEAMS: 1 << 2,
+    /** Add and remove a team's members. */
+    MANAGE_MEMBERS: 1 << 3,
+    /** Upgrade the organization's apps, start org upgrade runs, approve outbound hosts (org-wide). */
+    MANAGE_APPLICATION: 1 << 4,
+    /** Create a top-level team without being an admin. */
+    CREATE_TEAM: 1 << 5,
+    /** Delete a team, and what it holds, without being an admin. */
+    DELETE_TEAM: 1 << 6,
+    /** Change who may join a team (open or invite-only). */
+    MANAGE_VISIBILITY: 1 << 7,
+    /** Set the organization's and its teams' metadata. */
+    MANAGE_METADATA: 1 << 8,
+};
+/** What a member holds unless an admin says otherwise. */
+export const DEFAULT_ORG_CAPABILITIES = ORG_CAPABILITIES.JOIN_OPEN_TEAMS;
+/** The bitmask of `names`. */
+export function orgCapabilities(...names) {
+    return names.reduce((mask, name) => mask | ORG_CAPABILITIES[name], 0);
+}

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

@@ -0,0 +1,426 @@
+/**
+ * Client for Calimero 1.0, the confidential cloud: one app = one replicated log on
+ * attested nodes; this client verifies the node, seals every request to it,
+ * signs people in with passkeys and machines with API keys.
+ *
+ * ```ts
+ * const cloud = new CalimeroClient({ baseUrl, policy: { release: { minReleaseVersion: '2.3.109' } } });
+ * await cloud.signIn(browserPasskey());
+ * const { result } = await cloud.call(appId, 'set', { key: 'a', value: '1' });
+ * ```
+ */
+import { type AttestationDoc, type CloudPolicy } from './attestation.js';
+import { type PasskeyProvider } from './passkey.js';
+export { AppError, ArgsTooLarge, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, NotFound, TrapError, UnavailableError, errorFrom, } from './errors.js';
+export type { Committed } from './errors.js';
+export interface CalimeroSession {
+    accountId: string;
+    sessionToken: string;
+    expiresAt: number;
+    refreshToken: string;
+}
+export interface CallResult {
+    index: number;
+    result: unknown;
+    events: Array<{
+        kind: string;
+        data: unknown;
+    }>;
+}
+export interface ViewResult {
+    index: number;
+    result: unknown;
+}
+export interface CloudEvent {
+    id: string;
+    kind: string;
+    data: unknown;
+}
+/** What installing a package release answers. */
+export interface PackageInstalled {
+    package: string;
+    version: string;
+    signerId: string;
+    /** Service name (`''` for a single-service bundle) -> the bundle hash it runs as. */
+    services: Record<string, string>;
+}
+/** An installed package and its releases. */
+export interface PackageInfo {
+    package: string;
+    signerId: string;
+    owner: string;
+    latest: string | null;
+    versions: Array<{
+        version: string;
+        mpk: string;
+        size: number;
+        source: 'registry' | 'upload';
+        services: Record<string, string>;
+        metadata: unknown;
+        outbound: string[];
+        installedBy: string;
+        installedAt: number;
+    }>;
+}
+/** One app instance as `listApps` answers it. */
+export interface AppInfo {
+    appId: string;
+    name: string;
+    owner: string;
+    org: string | null;
+    bundle: string;
+    package: string | null;
+    version: string | null;
+}
+/**
+ * An organization-wide upgrade run, as `upgradeOrg`, `upgradeRun` and
+ * `retryUpgradeRun` answer it (core's `UpgradeRun`).
+ */
+export interface UpgradeRun {
+    runId: string;
+    package: string;
+    version: string;
+    team?: string;
+    cascade: boolean;
+    /** The account that started it, or `operator`. */
+    by: string;
+    startedAt: number;
+    apps: string[];
+    done: string[];
+    /** App id -> why its upgrade failed. */
+    failed: Record<string, unknown>;
+    finished: boolean;
+}
+/** One of an app's blobs: `blobId` base58 (what apps print), `id` hex. */
+export interface BlobInfo {
+    blobId: string;
+    id: string;
+    size: number;
+}
+/** One device present in an app (`publishPresence`); `state` hex, `null` once retracted. */
+export interface PresenceEntry {
+    account: string;
+    device: string;
+    state: string | null;
+}
+/** What an organization-wide upgrade targets. */
+export interface OrgUpgradeTarget {
+    package: string;
+    version: string;
+    /** Only this team's apps (and, with `cascade`, those of the teams below it). */
+    team?: string;
+    cascade?: boolean;
+    migrate?: string;
+}
+/**
+ * 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
+ * `maxDelayMs`, no jitter, at most `retries` times. The defaults are the Rust
+ * client's: 6 retries, 200 ms doubling, at most 2 s (about 9 s in all, past a
+ * leader election).
+ */
+export interface CloudRetryOptions {
+    /** Retries after the first attempt. Default 6. */
+    retries?: number;
+    /** The first backoff; each retry doubles it. Default 200 ms. */
+    baseDelayMs?: number;
+    /** The longest backoff. Default 2 s. */
+    maxDelayMs?: number;
+}
+export declare const DEFAULT_RETRY: {
+    readonly retries: 6;
+    readonly baseDelayMs: 200;
+    readonly maxDelayMs: 2000;
+};
+/** The backoff before retry `retry` (0 for the first): `baseDelayMs` doubling, at most `maxDelayMs`. */
+export declare function retryDelayMs(retry: number, options: {
+    baseDelayMs: number;
+    maxDelayMs: number;
+}): number;
+export interface CalimeroClientOptions {
+    /** One node of the cluster. */
+    baseUrl: string;
+    policy: CloudPolicy;
+    /** Fetch that carries attestation and envelopes. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** How calls and views retry a 503 or a failed connection. */
+    retry?: CloudRetryOptions;
+}
+export declare class CalimeroClient {
+    private readonly base;
+    private readonly sealed;
+    /** The unsealed fetch, for the one route served in the clear (`/attestation`). */
+    private readonly raw;
+    private auth;
+    private current;
+    private readonly retry;
+    /** Rejections of the underlying `fetch` itself: the node could not be reached or dropped the connection. */
+    private readonly networkFailures;
+    constructor(options: CalimeroClientOptions);
+    /** Authenticate every request with an API key. */
+    useApiKey(key: string): void;
+    useSession(session: CalimeroSession): void;
+    get session(): CalimeroSession | undefined;
+    private request;
+    private json;
+    /**
+     * {@link json} for a call or a view (D70): while the node answers 503 or
+     * cannot be reached, the same request, with the same idempotency key, is sent
+     * again after {@link retryDelayMs} (or the pause the node asked for, if
+     * longer), at most `retries` times. Every other answer is final. The last
+     * failure surfaces as {@link UnavailableError}: the node's 503, or reason
+     * `network` for a connection that failed, whose `committed` is `'unknown'`.
+     * `retries` 0 sends the request exactly once.
+     */
+    private retried;
+    post<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;
+    get<T = Record<string, unknown>>(path: string): Promise<T>;
+    put<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;
+    delete<T = Record<string, unknown>>(path: string, body?: unknown): Promise<T>;
+    /** Create an account with a new passkey, and sign in. */
+    signUp(passkey: PasskeyProvider, name: string): Promise<CalimeroSession>;
+    /** Sign in with an existing passkey. */
+    signIn(passkey: PasskeyProvider): Promise<CalimeroSession>;
+    /** Swap the refresh token for a new session. */
+    refresh(): Promise<CalimeroSession>;
+    signOut(): Promise<void>;
+    /** 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>;
+    /** 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. */
+    usage(): Promise<Record<string, unknown>>;
+    /**
+     * The node's attestation document, unverified: for display only. Every
+     * request this client sends is sealed to a key it verified itself first.
+     */
+    attestation(): Promise<AttestationDoc>;
+    /** 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. */
+    createApiKey(options: {
+        label?: string;
+        apps?: string[];
+        methods?: string[];
+        readOnly?: boolean;
+        allowConfirm?: boolean;
+        ttlSecs?: number;
+    }): 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<{
+        blobId: string;
+        id: string;
+        size: number;
+    }>;
+    /** One of `app`'s blobs, by id (base58 or hex). */
+    downloadBlob(app: string, id: string): Promise<Uint8Array>;
+    /** `app`'s blobs. */
+    listBlobs(app: string): Promise<BlobInfo[]>;
+    /** One of `app`'s blobs' id and size; `NotFound` if the app has no such blob. */
+    blobInfo(app: string, id: string): Promise<BlobInfo>;
+    /** Delete one of `app`'s blobs (its owner, or an admin of its organization). */
+    deleteBlob(app: string, id: string): Promise<void>;
+    /** Install a signed `.mpk` package file. */
+    uploadPackage(mpk: Uint8Array): Promise<PackageInstalled>;
+    /** Install `package@version` from the cluster's registry; every node that runs it verifies it. */
+    installPackage(pkg: string, version: string): Promise<PackageInstalled>;
+    /** Installed packages and their versions. */
+    packages(): Promise<PackageInfo[]>;
+    /** One installed package and its versions. */
+    package(pkg: string): Promise<PackageInfo>;
+    /** Uninstall one version, or the whole package. Refused while an app runs it. */
+    uninstallPackage(pkg: string, version?: string): Promise<Record<string, unknown>>;
+    /** Apps this caller reaches, optionally only those of one package or bundle. */
+    listApps(filter?: {
+        package?: string;
+        bundle?: string;
+    }): Promise<AppInfo[]>;
+    getApp(app: string): Promise<Record<string, unknown>>;
+    /** Delete an app instance (its owner, or an admin of its organization). */
+    deleteApp(app: string): Promise<void>;
+    /** Who may reach the app: `{ kind: 'owner' | 'org' | 'public' | 'accounts' | 'team', ... }`. */
+    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>;
+    /** 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 }`. */
+    appAbi(app: string): Promise<Record<string, unknown>>;
+    /**
+     * Hand the app to another account (an organization's app only to one of its
+     * members). The owner approves with `passkey`.
+     */
+    transferApp(app: string, to: string, passkey: PasskeyProvider): Promise<void>;
+    /**
+     * Move an app to another release of its package (`{ version }`), another
+     * package, or a bundle hash, running its migration. Answers the upgrade's
+     * entry; a failed migration rejects with code `UPGRADE_FAILED` (422).
+     * Where the owner holds app upgrades, the node asks for the owner's approval
+     * (`412 CONFIRM_REQUIRED`), which `passkey` gives.
+     */
+    upgradeApp(app: string, target: {
+        version?: string;
+        package?: string;
+        service?: string;
+        bundle?: string;
+        migrate?: string;
+    }, passkey?: PasskeyProvider): Promise<{
+        index: number;
+        status: string;
+        error: unknown;
+    }>;
+    /**
+     * POST `body` to `path`, answering a `412 CONFIRM_REQUIRED` with `passkey`'s
+     * assertion over the node's challenge (deleting an org, approving a release, ...).
+     */
+    postConfirmed<T>(path: string, body: Record<string, unknown>, passkey: PasskeyProvider): Promise<T>;
+    /** {@link postConfirmed} for a DELETE (deleting an organization). */
+    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).
+     */
+    createApp(name: string, bundle: string | {
+        package: string;
+        version?: string;
+        service?: string;
+    }, options?: {
+        org?: string;
+        access?: Record<string, unknown>;
+        confirmMethods?: string[];
+        /** Arguments for the app's `init`. A failed init rejects with code `INIT_FAILED`. */
+        initArgs?: unknown;
+    }): Promise<string>;
+    /**
+     * Call a method. A retry with the same `idempotencyKey` is answered once.
+     * Without one, the client makes one, so its own retries of a 503 share it.
+     */
+    call(app: string, method: string, args?: unknown, idempotencyKey?: string): Promise<CallResult>;
+    /**
+     * Call a method that needs the account holder's approval: the node returns a
+     * challenge over this exact call, which `passkey` signs. A declined prompt
+     * rejects with {@link ConfirmCancelled}.
+     */
+    callConfirmed(app: string, method: string, args: unknown, passkey: PasskeyProvider, idempotencyKey?: string): Promise<CallResult>;
+    /** Run a read-only method: strong by default, or stale from any replica. */
+    view(app: string, method: string, args?: unknown, options?: {
+        stale?: boolean;
+        minIndex?: number;
+    }): Promise<ViewResult>;
+    /** Committed events from index `from`, then live, until `signal` aborts. */
+    events(app: string, from?: number, signal?: AbortSignal): AsyncGenerator<CloudEvent>;
+    /** A server-sent event stream on `path`, sealed like every other answer. */
+    private stream;
+    /**
+     * Publish this device's presence in `app`: `state` (at most 4 KiB) or `null`
+     * to retract it. The newest `seq` wins; send the same `seq` and state again
+     * as a heartbeat, since an entry not refreshed within 7 s is gone.
+     */
+    publishPresence(app: string, seq: number, state: Uint8Array | null): Promise<void>;
+    /** Who is present in `app` now. */
+    presence(app: string): Promise<PresenceEntry[]>;
+    /**
+     * Presence as a stream until `signal` aborts: a `snapshot` event (`data` the
+     * entries present), then a `presence` event (`data` one entry) per change.
+     */
+    presenceStream(app: string, signal?: AbortSignal): AsyncGenerator<CloudEvent>;
+    /** Name an app (its id or context id) for this account. */
+    setAlias(alias: string, app: string): Promise<void>;
+    /** This account's aliases, alias → app id. */
+    aliases(): Promise<Record<string, string>>;
+    /** The app an alias names. */
+    alias(alias: string): Promise<string>;
+    deleteAlias(alias: string): Promise<void>;
+    createOrg(name: string): Promise<string>;
+    /** The organization, with the teams this caller reaches or manages. */
+    getOrg(org: string): Promise<Record<string, unknown>>;
+    /**
+     * Delete an organization with its teams, invites and apps (its owner only).
+     * The node asks for the owner's passkey (`412 CONFIRM_REQUIRED`), which `passkey` gives.
+     */
+    deleteOrg(org: string, passkey: PasskeyProvider): Promise<void>;
+    /** Set the organization's metadata (an admin, or a holder of `MANAGE_METADATA`); at most 16 KiB. */
+    setOrgMetadata(org: string, metadata: unknown): Promise<void>;
+    /** Set a member's metadata (theirs, or an admin's); `null` clears it. */
+    setMemberMetadata(org: string, account: string, metadata: unknown): Promise<void>;
+    /**
+     * Upgrade every app of `org` that runs `target.package` to `target.version`
+     * (optionally one team's, with `cascade` the teams below it). The org's owner,
+     * or a holder of `MANAGE_APPLICATION`, approves the whole run with `passkey`.
+     * Answers the run; {@link upgradeRun} follows it.
+     */
+    upgradeOrg(org: string, target: OrgUpgradeTarget, passkey: PasskeyProvider): Promise<UpgradeRun>;
+    /** An organization-wide upgrade run: its apps, those done and those that failed. */
+    upgradeRun(org: string, run: string): Promise<UpgradeRun>;
+    /** Run the apps that failed in `run` again, as a new run, approved with `passkey`. */
+    retryUpgradeRun(org: string, run: string, passkey: PasskeyProvider): Promise<UpgradeRun>;
+    /**
+     * Approve a mero-tee release to hold the apps of `org`, or of this account
+     * outside any organization (`org` `null`); `approved: false` withdraws it.
+     * Until then, nodes on that release get none of those apps' data. The owner
+     * approves with `passkey`.
+     */
+    approveRelease(org: string | null, version: string, passkey: PasskeyProvider, approved?: boolean): Promise<Record<string, unknown>>;
+    /**
+     * Approve the URL prefixes apps from `pkg`'s publisher may call out to, for
+     * `org`'s apps or this account's own (`org` `null`). `prefixes` `'manifest'`
+     * (the default) approves every prefix the package's latest release declares;
+     * `replace` sets exactly `prefixes`, which is how one is revoked. Approved
+     * with `passkey`.
+     */
+    approveOutbound(org: string | null, pkg: string, passkey: PasskeyProvider, options?: {
+        prefixes?: string[] | 'manifest';
+        replace?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** 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>>;
+    /**
+     * 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).
+     */
+    setCapabilities(org: string, capabilities: number, at?: {
+        account?: string;
+        team?: string;
+    }): Promise<void>;
+    createTeam(org: string, name: string, join: 'everyone' | 'invite', parent?: string): Promise<string>;
+    getTeam(org: string, team: string): Promise<Record<string, unknown>>;
+    /**
+     * Rename, change who may join, set the app's metadata, or move the team:
+     * `parent: null` moves it to the top, an absent `parent` leaves it.
+     */
+    updateTeam(org: string, team: string, update: {
+        name?: string;
+        join?: 'everyone' | 'invite';
+        parent?: string | null;
+        metadata?: unknown;
+    }): 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?: {
+        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?: {
+        ttlSecs?: number;
+        uses?: number;
+    }): Promise<string>;
+    redeemInvite(token: string): Promise<Record<string, unknown>>;
+}