@calimero-network/mero-js 29.8.1 → 29.10.0

package/README.md

@@ -97,7 +97,7 @@ Pinned measurements go through `policy.verifyQuote` (`createQuoteVerifier`).
 
 ## The API
 
-- **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.
+- **Credentials**: `signUp` (with an `invite`, on a cluster that takes new accounts by invite; `signUpPolicy` reads which), `signIn`, `refresh`, `signOut`, `signOutEverywhere`, `listSessions`, `revokeSession`, `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.
 - **Account recovery** (core #4844): `createRecoveryCode`, `removeRecoveryCode` (passkey-approved; the code is shown once), then signed out `startAccountRecovery(code, passkey)` and, 72 hours later, `finishAccountRecovery(passkey, accountId?)`; a passkey the account still has cancels in between (`cancelAccountRecovery`; `me()` shows `recoveryCode` and `recoveryPending`).
 - **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`. `packageOrigins.add(pkg, origin, passkey, { served: true })` registers a custom domain: the cluster also serves the package's frontend there from its signed bundle (`https://host`, no port; the passkey's consent names `served: true`); `list` answers `served` on each origin, and the extra refusals are `NotServing` (the cluster serves no frontends), `ClusterNotUpgraded` (a node is on an older release), `QuotaExceeded` (4 served per package, 64 per cluster) and `OriginTaken` (held with the other `served`).
 - **Packages**: `installPackage`, `uploadPackage`, `packages`, `package`, `uninstallPackage`; `uploadBundle` (raw WASM, development clusters only).

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

@@ -175,6 +175,20 @@ export interface ScopeApp {
      * instance of the package here; `[]`: none, for a fresh install).
      */
     instances?: string[];
+    /**
+     * Open (`everyone`) or close (`invite`) this package's app team in this
+     * step, and no other (absent: as `shared` says). Naming it on any package
+     * leaves an absent `shared` meaning "no other team"; `shared: true` with an
+     * `everyone` is refused.
+     */
+    join?: 'everyone' | 'invite';
+    /**
+     * Closing (`join: 'invite'`) only: who keeps the app besides the team's
+     * leads, members of the organization (at most 1024). Absent: everyone who
+     * reaches it now keeps it. Everyone else loses it, with their rows in the
+     * teams below it (its private channels); opening the team again lets them back.
+     */
+    keep?: string[];
 }
 /** What {@link CalimeroClient.scopeApps} asks for; every field absent takes the node's default. */
 export interface ScopeAppsOptions {
@@ -191,8 +205,12 @@ export interface ScopedAppTeam {
     created: boolean;
     /** The instances moved onto it. */
     apps: string[];
-    /** How many rows were added for people who reached those instances. */
+    /** How many rows were added for people who reached those instances (or kept on a close). */
     added: number;
+    /** The team's `join` after the step (absent from nodes before per-app close). */
+    join?: 'everyone' | 'invite';
+    /** How many people lost the app in this step (a close with `keep`; absent from nodes before per-app close). */
+    dropped?: number;
 }
 /** `POST /orgs/{org}/app-teams`: the organization's mode after, and each package's team. */
 export interface ScopeAppsResult {
@@ -402,11 +420,46 @@ export declare function frontendManifest(origin?: string, fetcher?: typeof fetch
  * not opened through a deployment. `href` defaults to `window.location.href`.
  */
 export declare function pageDeployment(href?: string): string | null;
+/** One of the account's passkeys (devices), as `GET /auth/me` lists it. */
+export interface MePasskey {
+    /** The credential id, which {@link CalimeroClient.labelPasskey} and {@link CalimeroClient.removePasskey} take. */
+    id: string;
+    /** The account's name for it; `null` when unnamed. */
+    label?: string | null;
+    signCount: number;
+    /**
+     * When it was added (Unix seconds). `null` when it was added on a release
+     * that kept no times (1.0.0-rc.14 and earlier); absent from such a node.
+     */
+    addedAt?: number | null;
+    /**
+     * When it last signed in (Unix seconds): a sign-up, a sign-in or an account
+     * recovery's finish; a refresh does not move it. `null` when it has not
+     * signed in since the node kept times; absent from a node that keeps none.
+     */
+    lastSignInAt?: number | null;
+}
+/** An organization the account is in, as `GET /auth/me` lists it. */
+export interface MeOrg {
+    orgId: string;
+    name: string;
+    role: 'guest' | 'member' | 'admin' | 'owner';
+}
 /** `GET /auth/me`: who the credential is. */
 export interface MeInfo extends Record<string, unknown> {
     accountId?: string;
-    /** `session` or `apikey`. */
+    name?: string;
+    /** The account's passkeys. */
+    passkeys?: MePasskey[];
+    /** The organizations the account is in, with its role in each. */
+    orgs?: MeOrg[];
+    /** `session` or `apiKey`. */
     via?: string;
+    /**
+     * The passkey (credential id) this session was opened with; `null` for an
+     * API key.
+     */
+    passkeyId?: string | null;
     /**
      * The package the session is bound to: opened on an app's frontend or on
      * an origin its manager registered ({@link CalimeroClient.packageOrigins}).
@@ -425,6 +478,30 @@ export interface MeInfo extends Record<string, unknown> {
      */
     recoveryPending?: AccountRecovery | null;
 }
+/**
+ * One of the account's live sessions, as {@link CalimeroClient.listSessions}
+ * lists it (core #4894).
+ */
+export interface AccountSession {
+    /** The session's id, which {@link CalimeroClient.revokeSession} takes. */
+    session: string;
+    /** The passkey (credential id) it was opened with. */
+    passkey: string | null;
+    /** The package it is bound to; `null` on the cluster's own origin. */
+    app: string | null;
+    /** The registered origin it was opened on; `null` on the cluster's own origin. */
+    origin: string | null;
+    /** When it opened (Unix seconds); `null` when opened before the node kept it. */
+    openedAt: number | null;
+    /**
+     * When its refresh token was last exchanged (Unix seconds). A token younger
+     * than an hour refreshes without a write and a session token lives 15
+     * minutes, so the session may have been used up to about 1 h 15 min later.
+     */
+    lastActiveAt: number;
+    /** Whether it is the caller's own session. */
+    current: boolean;
+}
 /** A recovery of an account under way (core #4844, `docs/specs/account-recovery.md`). */
 export interface AccountRecovery {
     accountId: string;
@@ -782,6 +859,24 @@ export declare class CalimeroClient {
      * request fails, and the failure is thrown.
      */
     signOutEverywhere(): Promise<void>;
+    /**
+     * The signed-in account's live sessions, latest active first (at most 256,
+     * `GET /auth/sessions`); `current` marks this one. The account holder's own
+     * session on the cluster's origin only: an API key or a package-bound
+     * session is refused (`403`). A node before core #4894 has no such route
+     * ({@link NotFound}).
+     */
+    listSessions(): Promise<AccountSession[]>;
+    /**
+     * End one of the signed-in account's sessions (`DELETE
+     * /auth/sessions/{session}`), say a lost phone's, from another; no passkey
+     * is asked. A session the account does not hold live (ended already, or
+     * another account's) is {@link NotFound}; gated as {@link listSessions}.
+     * To end this client's own session ({@link AccountSession.current}) use
+     * {@link signOut}, which also drops its tokens: ended here, they stay
+     * held and the next request or refresh is {@link LoginRequired}.
+     */
+    revokeSession(session: string): Promise<void>;
     private signingOut;
     /** Who the credential is: the account, how it signed in, and the package (`app`) and `origin` a session is bound to. */
     me(): Promise<MeInfo>;
@@ -941,7 +1036,10 @@ export declare class CalimeroClient {
     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`.
+     * members), approved with `passkey`. The app's owner may; for an
+     * organization's app, its owner only while a member of the organization
+     * (`member` or above), and the organization's admins (`admin`, `owner`)
+     * too, so an organization can hand on an app whose owner left (core #4893).
      */
     transferApp(app: string, to: string, passkey: PasskeyProvider): Promise<void>;
     /**
@@ -1312,6 +1410,8 @@ export declare class CalimeroClient {
      * Give apps their own access lists in one step (owner or admin): find or
      * make each package's app team, add everyone who reaches its instances now,
      * and move those instances onto it; with `shared`, close every app team.
+     * A package's own `join` opens or closes its team alone, a close keeping
+     * everyone who reaches it or only the leads and `keep`.
      * Idempotent per package. Approved with the caller's `passkey`
      * (`__scope_apps { apps, shared }`); a refusal is `400 REJECTED` with the
      * node's reason. For a fresh standalone install pass

package/dist/cloud-v2/client.js

@@ -639,6 +639,29 @@ export class CalimeroClient {
     async signOutEverywhere() {
         await this.signingOut('auth/logout-all');
     }
+    /**
+     * The signed-in account's live sessions, latest active first (at most 256,
+     * `GET /auth/sessions`); `current` marks this one. The account holder's own
+     * session on the cluster's origin only: an API key or a package-bound
+     * session is refused (`403`). A node before core #4894 has no such route
+     * ({@link NotFound}).
+     */
+    async listSessions() {
+        const { sessions } = await this.get('auth/sessions');
+        return sessions;
+    }
+    /**
+     * End one of the signed-in account's sessions (`DELETE
+     * /auth/sessions/{session}`), say a lost phone's, from another; no passkey
+     * is asked. A session the account does not hold live (ended already, or
+     * another account's) is {@link NotFound}; gated as {@link listSessions}.
+     * To end this client's own session ({@link AccountSession.current}) use
+     * {@link signOut}, which also drops its tokens: ended here, they stay
+     * held and the next request or refresh is {@link LoginRequired}.
+     */
+    async revokeSession(session) {
+        await this.delete(`auth/sessions/${seg(session)}`);
+    }
     async signingOut(path) {
         try {
             await this.post(path);
@@ -896,7 +919,10 @@ export class CalimeroClient {
     }
     /**
      * Hand the app to another account (an organization's app only to one of its
-     * members). The owner approves with `passkey`.
+     * members), approved with `passkey`. The app's owner may; for an
+     * organization's app, its owner only while a member of the organization
+     * (`member` or above), and the organization's admins (`admin`, `owner`)
+     * too, so an organization can hand on an app whose owner left (core #4893).
      */
     async transferApp(app, to, passkey) {
         await this.postConfirmed(`apps/${seg(app)}/transfer`, { to }, passkey);
@@ -1442,6 +1468,8 @@ export class CalimeroClient {
      * Give apps their own access lists in one step (owner or admin): find or
      * make each package's app team, add everyone who reaches its instances now,
      * and move those instances onto it; with `shared`, close every app team.
+     * A package's own `join` opens or closes its team alone, a close keeping
+     * everyone who reaches it or only the leads and `keep`.
      * Idempotent per package. Approved with the caller's `passkey`
      * (`__scope_apps { apps, shared }`); a refusal is `400 REJECTED` with the
      * node's reason. For a fresh standalone install pass

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

@@ -3,7 +3,7 @@ export { DEFAULT_DIRECTORY, DirectoryError } from './directory.js';
 export type { DirectoryFailure } from './directory.js';
 export { AppError, ArgsTooLarge, BadOrigin, CalimeroError, ClusterNotUpgraded, ConfirmCancelled, ConfirmPromptBlocked, ConfirmRequired, IdempotencyMismatch, LoginRequired, ConsentStale, NotFound, NotServing, OriginNotRegistered, OriginTaken, PasskeyUnknownHere, QuotaExceeded, RecoveryNotReady, ReleaseDeadlineError, SignUpRefused, TrapError, UnavailableError, WrongNode, WrongRecoveryCode, errorFrom, } from './errors.js';
 export type { Committed, SignUpRefusal } from './errors.js';
-export type { AppInfo, AppTeam, AppTeams, AppXcalls, BlobContent, BlobInfo, DeadLetter, Deployer, DeployerGrant, DeployersInfo, DeploymentInfo, DeploymentOffer, DeploymentOrgs, FrontendManifest, MeInfo, PackageOrigin, PackageOriginAdded, PackageOriginRemoved, PackageOrigins, ServedOrigin, ServedOrigins, SignInOptions, AccountRecovery, SignUpOptions, SignUpPolicy, PublicDeployment, CallResult, CalimeroClientOptions, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgInvite, OrgMode, OrgRecovery, RecoveryTimes, OrgUpgradeTarget, PresenceEntry, ScopeApp, ScopeAppsOptions, ScopeAppsResult, ScopedAppTeam, TeamInfo, TeamMemberInfo, UpgradeRun, ViewResult, } from './client.js';
+export type { AppInfo, AppTeam, AppTeams, AppXcalls, BlobContent, BlobInfo, DeadLetter, Deployer, DeployerGrant, DeployersInfo, DeploymentInfo, DeploymentOffer, DeploymentOrgs, FrontendManifest, MeInfo, MeOrg, MePasskey, AccountSession, PackageOrigin, PackageOriginAdded, PackageOriginRemoved, PackageOrigins, ServedOrigin, ServedOrigins, SignInOptions, AccountRecovery, SignUpOptions, SignUpPolicy, PublicDeployment, CallResult, CalimeroClientOptions, CalimeroConnectOptions, CloudEvent, CalimeroSession, PackageInfo, PackageInstalled, CloudRetryOptions, OrgInfo, OrgInvite, OrgMode, OrgRecovery, RecoveryTimes, OrgUpgradeTarget, PresenceEntry, ScopeApp, ScopeAppsOptions, ScopeAppsResult, ScopedAppTeam, TeamInfo, TeamMemberInfo, 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';