@calimero-network/mero-js 29.1.0 → 29.3.0

package/README.md

@@ -97,7 +97,7 @@ 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`. Adding or removing a passkey and creating an API key are approved with a passkey the account already has.
+- **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.
 - **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`.
 - **Packages**: `installPackage`, `uploadPackage`, `packages`, `package`, `uninstallPackage`; `uploadBundle` (raw WASM, development clusters only).
 - **Apps**: `createApp`, `listApps`, `getApp`, `deleteApp`, `setAccess`, `setAppMetadata`, `appStorage`, `appAbi`, `upgradeApp`, `transferApp`.

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

@@ -12,8 +12,8 @@
 import { type AttestationDoc, type CloudPolicy } from './attestation.js';
 import { type PasskeyProvider } from './passkey.js';
 import { type AppsReport, type ConsentRequest, type ConsentResult, type ConsentStarted, type OpenConsentOptions, type OpsAppsReport, type OpsOrgsReport, type PageOptions, type PendingApprovals, type PublisherBindingInfo, type PublisherProof, type ReleaseRules } from './approvals.js';
-export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
-export type { Committed } from './errors.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
+export type { Committed, SignUpRefusal } from './errors.js';
 export interface CalimeroSession {
     accountId: string;
     sessionToken: string;
@@ -338,6 +338,30 @@ export interface PackageOrigins {
 export interface SignInOptions {
     origin?: string | null;
 }
+/**
+ * {@link SignInOptions} for a sign-up, and the invite it is made with: an
+ * organization invite's token (the new account joins the organization at
+ * the invite's role) or a cluster sign-up invite's. A cluster whose policy
+ * is `invite` or `closed` ({@link CalimeroClient.signUpPolicy}) needs one.
+ */
+export interface SignUpOptions extends SignInOptions {
+    invite?: string;
+}
+/**
+ * `GET /sign-up`: who may create an account on the cluster (core's sign-up
+ * policy, read without a session), so a page can say "invite only" before
+ * any passkey prompt.
+ */
+export interface SignUpPolicy {
+    /** `open` (anyone), `invite` (an organization or sign-up invite), `closed` (a sign-up invite only). */
+    policy: 'open' | 'invite' | 'closed';
+    /** Whether an organization invite lets a new person sign up (and join it). */
+    orgInvites: boolean;
+    /** Whether a cluster sign-up invite does (always). */
+    signUpInvites: boolean;
+    /** Whether a sign-up without an invite is refused. */
+    inviteRequired: boolean;
+}
 /**
  * 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
@@ -520,8 +544,15 @@ export declare class CalimeroClient {
      * origin's relying party (the confirmation's `rpId` is that origin's too)
      * and binds the session to the package the origin is registered for; an
      * unregistered origin is refused with {@link OriginNotRegistered}.
+     *
+     * `invite` ({@link SignUpOptions}) goes on both halves and on the retry,
+     * as the node judges it on each before it spends anything; a sign-up the
+     * cluster's policy refuses, or an unknown, expired or used invite, is
+     * {@link SignUpRefused} (from `begin`, before any passkey is made).
      */
-    signUp(passkey: PasskeyProvider, name: string, options?: SignInOptions): Promise<CalimeroSession>;
+    signUp(passkey: PasskeyProvider, name: string, options?: SignUpOptions): Promise<CalimeroSession>;
+    /** Who may create an account on the cluster (`GET /sign-up`); needs no session. */
+    signUpPolicy(): Promise<SignUpPolicy>;
     /**
      * Sign in with an existing passkey. On a page whose origin is not the
      * cluster's ({@link SignInOptions}), the assertion is made for that
@@ -576,6 +607,12 @@ export declare class CalimeroClient {
      * 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.
+     *
+     * `upgrades: { app, package? }` makes an upgrade key, for CI: it upgrades
+     * that one app to signed releases of its package (default: the one the app
+     * runs, by that package's pinned signer) with {@link upgradeApp} and no
+     * passkey, and every other request with it is refused
+     * `403 UPGRADE_KEY_ONLY`. It takes no other scope field.
      */
     createApiKey(options: {
         label?: string;
@@ -584,6 +621,10 @@ export declare class CalimeroClient {
         readOnly?: boolean;
         allowConfirm?: boolean;
         ttlSecs?: number;
+        upgrades?: {
+            app: string;
+            package?: string;
+        };
     }, passkey: PasskeyProvider): Promise<{
         keyId: string;
         key: string;
@@ -673,6 +714,8 @@ export declare class CalimeroClient {
      * `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}.
+     * With an upgrade key ({@link createApiKey} `upgrades`) pass no passkey and
+     * a `version` of the key's package: the key's own proof stands in for it.
      */
     upgradeApp(app: string, target: {
         version?: string;

package/dist/cloud-v2/client.js

@@ -15,7 +15,7 @@ import { DEFAULT_DIRECTORY, orderNodes, readDirectory } from './directory.js';
 import { CalimeroError, ConfirmCancelled, ConfirmRequired, LoginRequired, OriginNotRegistered, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 import { b64url, fromB64url } from './passkey.js';
 import { confirmationCode, pageQuery, pendingApprovalsFrom, } from './approvals.js';
-export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, SignUpRefused, 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}`;
@@ -462,15 +462,25 @@ export class CalimeroClient {
      * origin's relying party (the confirmation's `rpId` is that origin's too)
      * and binds the session to the package the origin is registered for; an
      * unregistered origin is refused with {@link OriginNotRegistered}.
+     *
+     * `invite` ({@link SignUpOptions}) goes on both halves and on the retry,
+     * as the node judges it on each before it spends anything; a sign-up the
+     * cluster's policy refuses, or an unknown, expired or used invite, is
+     * {@link SignUpRefused} (from `begin`, before any passkey is made).
      */
     async signUp(passkey, name, options = {}) {
         const origin = this.pageOrigin(options);
-        const begin = await this.begin('auth/passkey/register/begin', origin === undefined ? { name } : { name, origin }, origin);
+        const invite = options.invite ? { invite: options.invite } : {};
+        const begin = await this.begin('auth/passkey/register/begin', origin === undefined ? { name, ...invite } : { name, origin, ...invite }, origin);
         const registration = await passkey.create(begin.options);
-        const session = await this.postConfirmed('auth/passkey/register/finish', { challengeId: begin.challengeId, registration }, passkey);
+        const session = await this.postConfirmed('auth/passkey/register/finish', { challengeId: begin.challengeId, registration, ...invite }, passkey);
         this.useSession(session);
         return session;
     }
+    /** Who may create an account on the cluster (`GET /sign-up`); needs no session. */
+    signUpPolicy() {
+        return this.get('sign-up');
+    }
     /**
      * Sign in with an existing passkey. On a page whose origin is not the
      * cluster's ({@link SignInOptions}), the assertion is made for that
@@ -625,6 +635,12 @@ export class CalimeroClient {
      * 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.
+     *
+     * `upgrades: { app, package? }` makes an upgrade key, for CI: it upgrades
+     * that one app to signed releases of its package (default: the one the app
+     * runs, by that package's pinned signer) with {@link upgradeApp} and no
+     * passkey, and every other request with it is refused
+     * `403 UPGRADE_KEY_ONLY`. It takes no other scope field.
      */
     createApiKey(options, passkey) {
         return this.postConfirmed('auth/apikeys', { ...options }, passkey);
@@ -766,6 +782,8 @@ export class CalimeroClient {
      * `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}.
+     * With an upgrade key ({@link createApiKey} `upgrades`) pass no passkey and
+     * a `version` of the key's package: the key's own proof stands in for it.
      */
     upgradeApp(app, target, passkey) {
         const path = `apps/${seg(app)}/upgrade`;

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

@@ -126,6 +126,26 @@ export declare class BadOrigin extends CalimeroError {
 export declare class OriginTaken extends CalimeroError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/** Why a sign-up was refused ({@link SignUpRefused.reason}), read from what the node said. */
+export type SignUpRefusal = 'invite-only' | 'closed' | 'unknown-invite' | 'expired-invite' | 'org-gone' | 'other';
+/**
+ * `403 SIGN_UP_REFUSED`: the cluster's sign-up policy does not take this
+ * sign-up (core `SystemState::admits`), answered by `register/begin` before a
+ * passkey is made and by `register/finish` before its challenge is spent.
+ * `reason` says why, so a page can say "invite only" or "this invite has
+ * expired" instead of the node's sentence:
+ *
+ * - `invite-only`: the cluster takes new accounts with an invite only.
+ * - `closed`: only a cluster sign-up invite (the operator's or the owner's) admits.
+ * - `unknown-invite`: the invite is not one the cluster knows (mistyped, revoked,
+ *   or used up: a spent invite is gone).
+ * - `expired-invite`: past its expiry, or no use left.
+ * - `org-gone`: the organization the invite was for was deleted.
+ */
+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. */
 export declare class QuotaExceeded extends CalimeroError {
     constructor(message: string, details?: Record<string, unknown>);

package/dist/cloud-v2/errors.js

@@ -165,6 +165,40 @@ export class OriginTaken extends CalimeroError {
         this.name = 'OriginTaken';
     }
 }
+/**
+ * `403 SIGN_UP_REFUSED`: the cluster's sign-up policy does not take this
+ * sign-up (core `SystemState::admits`), answered by `register/begin` before a
+ * passkey is made and by `register/finish` before its challenge is spent.
+ * `reason` says why, so a page can say "invite only" or "this invite has
+ * expired" instead of the node's sentence:
+ *
+ * - `invite-only`: the cluster takes new accounts with an invite only.
+ * - `closed`: only a cluster sign-up invite (the operator's or the owner's) admits.
+ * - `unknown-invite`: the invite is not one the cluster knows (mistyped, revoked,
+ *   or used up: a spent invite is gone).
+ * - `expired-invite`: past its expiry, or no use left.
+ * - `org-gone`: the organization the invite was for was deleted.
+ */
+export class SignUpRefused extends CalimeroError {
+    constructor(message, details = {}) {
+        super(403, 'SIGN_UP_REFUSED', message, details);
+        this.name = 'SignUpRefused';
+        this.reason = signUpRefusal(message);
+    }
+}
+function signUpRefusal(message) {
+    if (/invite only/.test(message))
+        return 'invite-only';
+    if (/pre-authorized|sign-up invite/.test(message))
+        return 'closed';
+    if (/unknown invite/.test(message))
+        return 'unknown-invite';
+    if (/invite has expired/.test(message))
+        return 'expired-invite';
+    if (/organization is gone/.test(message))
+        return 'org-gone';
+    return 'other';
+}
 /** `429 QUOTA_EXCEEDED`: the caller holds as many of something (origins, blobs, ...) as it may. */
 export class QuotaExceeded extends CalimeroError {
     constructor(message, details = {}) {
@@ -265,6 +299,8 @@ export function errorFrom(status, body, retryAfterHeader) {
             return new OriginTaken(message, details);
         case '429 QUOTA_EXCEEDED':
             return new QuotaExceeded(message, details);
+        case '403 SIGN_UP_REFUSED':
+            return new SignUpRefused(message, details);
         case '412 CONFIRM_REQUIRED':
             return new ConfirmRequired(message, details);
         case '413 ARGS_TOO_LARGE':

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, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
-export type { Committed } from './errors.js';
-export type { AppInfo, AppXcalls, BlobContent, BlobInfo, DeadLetter, Deployer, DeployerGrant, DeployersInfo, DeploymentInfo, DeploymentOffer, DeploymentOrgs, FrontendManifest, MeInfo, PackageOrigin, PackageOriginAdded, PackageOriginRemoved, PackageOrigins, SignInOptions, PublicDeployment, CallResult, CalimeroClientOptions, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgUpgradeTarget, PresenceEntry, UpgradeRun, ViewResult, } from './client.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, 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, SignUpOptions, SignUpPolicy, 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,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, ReleaseDeadlineError, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
+export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ConfirmCancelled, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, OriginNotRegistered, OriginTaken, QuotaExceeded, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, errorFrom, } from './errors.js';
 export { claimedRelease, fetchAttestedKey, freshCollateral, MOCK_QUOTE_HEADER } from './attestation.js';
 export { browserPasskey, b64url, fromB64url } from './passkey.js';
 export { MAX_REPORT_PAGE, RELEASE_VERIFIER, compareVersions, confirmationCode, consentReturn, pageQuery, pendingApprovalsFrom, publisherBindingBytes, publisherBindingMessage, releaseConsent, releaseNotesUrl, stalledBy, upgradeConsent, verifyReleaseUrl, withdrawConsent, } from './approvals.js';