@calimero-network/mero-js 27.0.2 → 27.2.0

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

@@ -11,7 +11,8 @@
  */
 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';
+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';
+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 {
     accountId: string;
@@ -112,6 +113,23 @@ export interface OrgUpgradeTarget {
     cascade?: boolean;
     migrate?: string;
 }
+/**
+ * `GET /orgs/{org}`: the organization as the caller sees it. Besides its
+ * members, teams and metadata, who may approve its releases, the package
+ * signing keys it publishes, and whether a passed release deadline has
+ * stopped new work on its own set.
+ */
+export interface OrgInfo extends Record<string, unknown> {
+    /** Accounts holding `APPROVE_RELEASES` there (owner and admins included). */
+    releaseApprovers: string[];
+    /** The signer ids (`did:key`) bound to it as publisher. */
+    publishes: string[];
+    /** `null` unless a deadline stopped new work: approve `release` (or newer) to lift it. */
+    newWorkStopped: {
+        release: string;
+        after: 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
@@ -138,8 +156,15 @@ export declare function retryDelayMs(retry: number, options: {
     maxDelayMs: number;
 }): number;
 export interface CalimeroClientOptions {
-    /** One node of the cluster. */
+    /** One node of the cluster: the one the client talks to first. */
     baseUrl: string;
+    /**
+     * Other nodes of the same cluster, in the order to move to them when a node
+     * answers `421 WRONG_NODE` (its release may not serve this account). Each is
+     * attested under the same `policy` before anything is sent to it. Without
+     * them a `421` reaches the caller as {@link WrongNode}.
+     */
+    nodes?: string[];
     policy: CloudPolicy;
     /** Fetch that carries attestation and envelopes. Defaults to global `fetch`. */
     fetch?: typeof fetch;
@@ -147,21 +172,70 @@ export interface CalimeroClientOptions {
     retry?: CloudRetryOptions;
 }
 export declare class CalimeroClient {
-    private readonly base;
-    private readonly sealed;
+    /** Every node this client may use, `baseUrl` first. */
+    private readonly nodeUrls;
+    /** The one in use: an index into {@link nodeUrls}. */
+    private at;
+    /** A sealed fetch per node, each attesting its own node on first use. */
+    private readonly channels;
+    private readonly policy;
     /** The unsealed fetch, for the one route served in the clear (`/attestation`). */
     private readonly raw;
     private auth;
     private current;
+    /** The refresh under way, which every request that needs one shares. */
+    private refreshing;
     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);
+    /** The node requests go to now: `baseUrl`, until a `421 WRONG_NODE` moved the client on. */
+    get nodeUrl(): string;
+    /** The sealed channel to `url`, attested under the client's policy before its first request. */
+    private channel;
+    /**
+     * Move on from node `from` (the one that answered `421 WRONG_NODE`) to the
+     * next one. False when there is no other. A request that saw the same node
+     * refuse after another request moved on already does not move again.
+     */
+    private moveOn;
     /** Authenticate every request with an API key. */
     useApiKey(key: string): void;
     useSession(session: CalimeroSession): void;
     get session(): CalimeroSession | undefined;
+    /**
+     * Send one request to the node in use, with the credential held now, and
+     * answer the response, whatever its status. {@link send} judges it.
+     */
     private request;
+    /**
+     * {@link request}, answering what a lost issuing node or a node on the
+     * wrong release does to a session: a successful response, or the refusal as a
+     * typed error ({@link errorFrom}).
+     *
+     * - `401 UNAUTHENTICATED` to a request that carried a session: the node that
+     *   signed the session may be gone, replaced, or out of reach of the node
+     *   asked, which any node of the cluster answers with a refresh. The client
+     *   refreshes once, shared by every request that needs it at the same time
+     *   ({@link refresh}), and repeats the request once. A refresh that is
+     *   refused surfaces as {@link LoginRequired}.
+     * - `421 WRONG_NODE`: this node's release may not serve the account. The
+     *   client moves to the next node it knows and repeats the request once; with
+     *   none, the {@link WrongNode} reaches the caller.
+     *
+     * Repeating is safe even for a request that is not idempotent: the node
+     * answers `401` and `421` when it judges the credential, before it reads what
+     * the request asks, so the first attempt ran nothing. The exceptions are the
+     * ceremonies that mint a session ({@link ceremony}), never repeated here.
+     */
+    private send;
+    /** Whether a `401` to a request sent with `token` is one a refresh may answer. */
+    private mayRefresh;
+    /**
+     * A fresh session in place of the one `token` belonged to: by the refresh
+     * another request already made, or by one this request starts.
+     */
+    private renew;
     private json;
     /**
      * {@link json} for a call or a view (D70): while the node answers 503 or
@@ -181,8 +255,14 @@ export declare class CalimeroClient {
     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. */
+    /**
+     * Swap the refresh token for a new session, on whichever node the client
+     * uses: any node of the cluster takes it. A refresh token is used once, so
+     * calls made while one refresh is under way share it rather than sending the
+     * same token again (which would revoke the session).
+     */
     refresh(): Promise<CalimeroSession>;
+    private exchangeRefresh;
     signOut(): Promise<void>;
     /** End every session of the signed-in account, on every device, this one too. */
     signOutEverywhere(): Promise<void>;
@@ -266,8 +346,11 @@ export declare class CalimeroClient {
      * 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.
+     * Where owners hold app upgrades, the node asks for the approval of
+     * whoever the package's manifest names (`412 CONFIRM_REQUIRED`), which
+     * `passkey` gives. Refused (`403`) to a session opened on an app's
+     * frontend: an app asks its user with {@link requestConsent} instead. Past
+     * a release deadline its approver has not met: {@link ReleaseDeadlineError}.
      */
     upgradeApp(app: string, target: {
         version?: string;
@@ -346,7 +429,7 @@ export declare class CalimeroClient {
     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>>;
+    getOrg(org: string): Promise<OrgInfo>;
     /**
      * 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.
@@ -370,8 +453,11 @@ export declare class CalimeroClient {
     /**
      * 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`.
+     * Until then, nodes on that release get none of those apps' data. For an
+     * organization, a member holding `APPROVE_RELEASES` approves with `passkey`;
+     * the node binds the release's measurements itself. Refused (`403`) to a
+     * session opened on an app's frontend: an app asks its user with
+     * {@link requestConsent} instead.
      */
     approveRelease(org: string | null, version: string, passkey: PasskeyProvider, approved?: boolean): Promise<Record<string, unknown>>;
     /**
@@ -379,12 +465,95 @@ export declare class CalimeroClient {
      * `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`.
+     * with `passkey`. Refused (`403`) to a session opened on an app's frontend:
+     * an app asks with {@link requestConsent} (`kind: 'outbound'`) instead.
      */
     approveOutbound(org: string | null, pkg: string, passkey: PasskeyProvider, options?: {
         prefixes?: string[] | 'manifest';
         replace?: boolean;
     }): Promise<Record<string, unknown>>;
+    /**
+     * One page of the report of a scope's apps: an organization's (any member;
+     * `404` to anyone else) or, with `org` `null`, the account's own outside any
+     * organization (a session bound to an app's frontend: that package's apps).
+     * The governance, the scope's approved releases, the releases the cluster's
+     * nodes run and whether each is approved, and per app its release, newer
+     * releases it may move to, last upgrade and replicas.
+     */
+    appsReport(org: string | null, page?: PageOptions): Promise<AppsReport>;
+    /** {@link appsReport}, every page, with the apps of all of them in `apps`. */
+    appsReportAll(org: string | null): Promise<AppsReport>;
+    /** `GET /releases`: the cluster's governance and every release deadline. Public. */
+    releaseRules(): Promise<ReleaseRules>;
+    /**
+     * What waits for a decision in a scope (`org`, or the account's own apps
+     * with `null`): mero-tee releases the cluster's nodes run that the scope has
+     * not approved, apps with newer releases of their package, and whether a
+     * passed deadline stops new work. Read over the sealed channel; act on an
+     * item by sending the user to the consent page ({@link requestConsent},
+     * `releaseConsent`, `upgradeConsent`).
+     */
+    pendingApprovals(org?: string | null): Promise<PendingApprovals>;
+    /**
+     * Ask the node to ask the user: a release, upgrade or outbound approval
+     * that only the account holder may make, decided on the node's own consent
+     * page, never in the app. Needs a passkey session (a session bound to the
+     * app's frontend is fine). Send the person to the answer's `url`; the page
+     * sends them back to `returnTo?request_id=…&result=approved|declined`
+     * (`consentReturn`), and {@link consentResult} confirms the decision.
+     */
+    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}.
+     */
+    openConsentPage(request: ConsentRequest, navigate?: (url: string) => void): Promise<ConsentStarted>;
+    /** The decision on a consent request (any node answers, for the account that asked). */
+    consentResult(requestId: string): Promise<ConsentResult>;
+    /**
+     * Poll {@link consentResult} until the request is decided, every
+     * `intervalMs` (2 s), until `signal` aborts or `expiresAt` (Unix seconds)
+     * passes, when it answers the last `pending` result.
+     */
+    waitForConsent(requestId: string, options?: {
+        intervalMs?: number;
+        signal?: AbortSignal;
+        expiresAt?: number;
+    }): Promise<ConsentResult>;
+    /** `GET /publishers/{signerId}`: the cluster name and binding generation a key signs to bind it next. */
+    publisherBinding(signerId: string): Promise<PublisherBindingInfo>;
+    /**
+     * Bind a package signing key to `org`, which then approves the node images
+     * every instance of the key's packages runs on, and upgrades those whose
+     * package declares `upgrades: publisher`. `proof` is the key's signature
+     * over `publisherBindingMessage(cluster, org, signerId, generation)`; a
+     * member holding `APPROVE_RELEASES` sends it with `passkey`.
+     */
+    bindPublisher(org: string, proof: PublisherProof, passkey: PasskeyProvider): Promise<Record<string, unknown>>;
+    /**
+     * Upgrade every instance of `pkg` whose release declares `upgrades:
+     * publisher`, whoever owns it, as its publisher `org` (a
+     * `MANAGE_APPLICATION` holder there), with one passkey approval. Answers
+     * the run, kept on the publisher.
+     */
+    upgradePublished(org: string, pkg: string, target: {
+        version: string;
+        migrate?: string;
+    }, passkey: PasskeyProvider): Promise<UpgradeRun>;
+    /** `GET /ops/apps`: what every app runs, without names or accounts. Operator token (`useApiKey`). */
+    opsApps(page?: PageOptions): Promise<OpsAppsReport>;
+    /** `GET /ops/orgs`: each organization's approved releases. Operator token. */
+    opsOrgs(page?: PageOptions): Promise<OpsOrgsReport>;
+    /**
+     * 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
+     * token.
+     */
+    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>>;