@cubist-labs/cubesigner-sdk 0.4.276 → 0.4.280

package/package.json

@@ -5,7 +5,7 @@
     "url": "git+https://github.com/cubist-labs/CubeSigner-TypeScript-SDK.git",
     "directory": "packages/sdk"
   },
-  "version": "0.4.276",
+  "version": "0.4.280",
   "type": "module",
   "description": "CubeSigner TypeScript SDK",
   "license": "MIT OR Apache-2.0",

package/src/acl.ts

@@ -7,7 +7,9 @@ export type Ace<TAction, TCtx> = {
   subjects: AceAttribute<string>;
   /** The actions being performed */
   actions: AceAttribute<TAction>;
+  /** The effect of this access control entry. */
+  effect?: "Allow" | "Deny";
 } & TCtx;
 
 /** An attribute of an access control entry. */
-export type AceAttribute<T> = "*" | T | T[];
+export type AceAttribute<T> = "*" | T | T[] | { except: T[] };

package/src/client/api_client.ts

@@ -224,6 +224,55 @@ export type SessionSelector =
       role?: string;
     };
 
+/**
+ * Options for listing the users in an org.
+ */
+export interface ListUsersOptions {
+  /** Pagination options. Defaults to fetching the entire result set. */
+  page?: PageOpts;
+
+  /**
+   * If defined, all returned users will contain this string in their name or email.
+   */
+  searchQuery?: string;
+
+  /**
+   * If defined, only users with one of these roles in the org are returned,
+   * grouped by role in descending role order (owners first, aliens last).
+   */
+  membership?: MemberRole[];
+}
+
+/**
+ * Options for listing the pending invitations in an org.
+ */
+export interface ListInvitationsOptions {
+  /** Pagination options. Defaults to fetching the entire result set. */
+  page?: PageOpts;
+
+  /**
+   * If defined, only invitations for one of these roles are returned,
+   * grouped by role in descending role order (owners first, aliens last).
+   */
+  membership?: MemberRole[];
+}
+
+/**
+ * Distinguishes the `ListUsersOptions` argument of {@link ApiClient.orgUsersList}
+ * from its deprecated leading `PageOpts` argument. This works because the two types
+ * have disjoint keys: any of the `PageOpts` keys being present identifies a `PageOpts`,
+ * so everything else is a `ListUsersOptions`. An argument with none of those keys
+ * (e.g. `{}`) is reported as `ListUsersOptions`, which is harmless: neither
+ * interpretation restricts the result set.
+ *
+ * @param arg The first argument passed to `orgUsersList`.
+ * @returns Whether `arg` is a `ListUsersOptions` (as opposed to `PageOpts`).
+ */
+function isListUsersOptions(arg: ListUsersOptions | PageOpts | undefined): arg is ListUsersOptions {
+  if (arg === undefined) return false;
+  return !("size" in arg || "start" in arg || "all" in arg);
+}
+
 /**
  * An extension of BaseClient that adds specialized methods for api endpoints
  */
@@ -391,23 +440,19 @@ export class ApiClient extends BaseClient {
    * that must be answered either by calling {@link TotpChallenge.answer} (or
    * {@link ApiClient.userTotpResetComplete}).
    *
-   * @param issuer Optional issuer; defaults to "Cubist"
+   * @param request Optional request parameters (or just an issuer string); defaults to using "Cubist" as the issuer.
    * @param mfaReceipt MFA receipt(s) to include in HTTP headers
    * @returns A TOTP challenge that must be answered
    */
   async userTotpResetInit(
-    issuer?: string,
+    request?: string | schemas["TotpResetRequest"],
     mfaReceipt?: MfaReceipts,
   ): Promise<CubeSignerResponse<TotpChallenge>> {
     const o = op("/v0/org/{org_id}/user/me/totp", "post");
     const resetTotpFn = async (headers?: HeadersInit) => {
       const data = await this.exec(o, {
         headers,
-        body: issuer
-          ? {
-              issuer,
-            }
-          : null,
+        body: typeof request === "string" ? { issuer: request } : request,
       });
       return mapResponse(data, (totpInfo) => new TotpChallenge(this, totpInfo));
     };
@@ -422,10 +467,14 @@ export class ApiClient extends BaseClient {
    *
    * @param totpId The ID of the TOTP challenge
    * @param code The TOTP code that should verify against the TOTP configuration from the challenge.
+   * @returns TOTP registration response
    */
-  async userTotpResetComplete(totpId: string, code: string): Promise<void> {
+  async userTotpResetComplete(
+    totpId: string,
+    code: string,
+  ): Promise<schemas["TotpRegisterResponse"]> {
     const o = op("/v0/org/{org_id}/user/me/totp", "patch");
-    await this.exec(o, {
+    return await this.exec(o, {
       body: { totp_id: totpId, code },
     });
   }
@@ -494,12 +543,12 @@ export class ApiClient extends BaseClient {
    *
    * @param challengeId The ID of the challenge returned by the remote end.
    * @param credential The answer to the challenge.
-   * @returns An empty response
+   * @returns A FIDO registration response
    */
   async userFidoRegisterComplete(
     challengeId: string,
     credential: PublicKeyCredential,
-  ): Promise<Empty> {
+  ): Promise<schemas["FidoRegisterResponse"]> {
     const o = op("/v0/org/{org_id}/user/me/fido", "patch");
 
     return this.exec(o, {
@@ -785,17 +834,18 @@ export class ApiClient extends BaseClient {
    * List pending invitations in the org, i.e., those that have neither been
    * accepted nor canceled, and have not expired.
    *
-   * @param page Pagination options. Defaults to fetching the entire result set.
+   * @param opts Pagination and filtering options. Defaults to fetching the entire result set.
    * @returns Paginator for iterating over the pending invitations in the org.
    */
   orgInvitationsList(
-    page?: PageOpts,
+    opts?: ListInvitationsOptions,
   ): Paginator<PaginatedListInvitationsResponse, InvitationInfo[]> {
     const o = op("/v0/org/{org_id}/invitations", "get");
 
     return Paginator.items(
-      page ?? Page.default(),
-      (pageQuery) => this.exec(o, { params: { query: { ...pageQuery } } }),
+      opts?.page ?? Page.default(),
+      (pageQuery) =>
+        this.exec(o, { params: { query: { membership: opts?.membership, ...pageQuery } } }),
       (r) => r.invitations,
       (r) => r.last_evaluated_key,
     );
@@ -840,19 +890,44 @@ export class ApiClient extends BaseClient {
   /**
    * List users in the org.
    *
+   * @overload
+   * @param opts Pagination and filtering options. Defaults to fetching the entire result set.
+   * @returns Paginator for iterating over the users in the org.
+   */
+  orgUsersList(opts?: ListUsersOptions): Paginator<GetUsersInOrgResponse, UserInOrgInfo[]>;
+  /**
+   * List users in the org.
+   *
+   * @overload
    * @param page Pagination options. Defaults to fetching the entire result set.
-   * @param searchQuery Optional query string. If defined, all returned users will contain this string in their name or email.
+   * @param searchQuery Query string. If defined, all returned users will contain this string in their name or email.
    * @returns Paginator for iterating over the users in the org.
+   * @deprecated Use the `ListUsersOptions` parameter overload instead.
    */
   orgUsersList(
     page?: PageOpts,
     searchQuery?: string,
+  ): Paginator<GetUsersInOrgResponse, UserInOrgInfo[]>;
+  /**
+   * List users in the org.
+   *
+   * @param opts Either pagination and filtering options, or (deprecated) just pagination options.
+   * @param searchQuery Deprecated search query string; only used with the deprecated overload.
+   * @returns Paginator for iterating over the users in the org.
+   */
+  orgUsersList(
+    opts?: ListUsersOptions | PageOpts,
+    searchQuery?: string,
   ): Paginator<GetUsersInOrgResponse, UserInOrgInfo[]> {
+    const luOpts: ListUsersOptions = isListUsersOptions(opts) ? opts : { page: opts, searchQuery };
     const o = op("/v0/org/{org_id}/users", "get");
 
     return Paginator.items(
-      page ?? Page.default(),
-      (pageQuery) => this.exec(o, { params: { query: { q: searchQuery, ...pageQuery } } }),
+      luOpts.page ?? Page.default(),
+      (pageQuery) =>
+        this.exec(o, {
+          params: { query: { q: luOpts.searchQuery, membership: luOpts.membership, ...pageQuery } },
+        }),
       (r) => r.users.map(ApiClient.#processUserInOrgInfo),
       (r) => r.last_evaluated_key,
     );
@@ -2232,6 +2307,9 @@ export class ApiClient extends BaseClient {
   /**
    * List pending MFA requests accessible to the current user.
    *
+   * Note that legacy MFA requests are not paginated: every accessible one is
+   * returned in the first page, on top of the requested page limit.
+   *
    * @param page Pagination options. Defaults to fetching the entire result set.
    * @returns Paginator for iterating over the MFA requests.
    */

package/src/mfa.ts

@@ -260,13 +260,14 @@ export class TotpChallenge {
    * Answer the challenge with the code that corresponds to `this.totpUrl`.
    *
    * @param code 6-digit code that corresponds to `this.totpUrl`.
+   * @returns TOTP registration response
    */
   async answer(code: string) {
     if (!/^\d{1,6}$/.test(code)) {
       throw new Error(`Invalid TOTP code: ${code}; it must be a 6-digit string`);
     }
 
-    await this.#api.userTotpResetComplete(this.id, code);
+    return await this.#api.userTotpResetComplete(this.id, code);
   }
 }
 
@@ -294,10 +295,12 @@ export class AddFidoChallenge {
   /**
    * Answers this challenge by using the `CredentialsContainer` API to create a credential
    * based on the the public key credential creation options from this challenge.
+   *
+   * @returns FIDO registration response
    */
   async createCredentialAndAnswer() {
     const cred = await navigator.credentials.create({ publicKey: this.options });
-    await this.answer(cred);
+    return await this.answer(cred);
   }
 
   /**
@@ -310,10 +313,11 @@ export class AddFidoChallenge {
    *
    * @param cred Credential created by calling the `CredentialContainer`'s `create` method
    *                   based on the public key creation options from this challenge.
+   * @returns FIDO registration response
    */
   async answer(cred: any) {
     const answer = credentialToJSON(cred);
-    await this.#api.userFidoRegisterComplete(this.challengeId, answer);
+    return await this.#api.userFidoRegisterComplete(this.challengeId, answer);
   }
 }
 

package/src/org.ts

@@ -32,6 +32,8 @@ import type {
   AuditLogRequest,
   MfaReceipts,
   InvitationInfo,
+  ListUsersOptions,
+  ListInvitationsOptions,
 } from "./index.ts";
 import { Contact } from "./contact.ts";
 import { C2FFunction, Key, MfaRequest, Role } from "./index.ts";
@@ -541,10 +543,11 @@ export class Org {
    * List all pending invitations in the organization, i.e., those that have
    * neither been accepted nor canceled, and have not expired.
    *
+   * @param opts Pagination and filtering options. Defaults to fetching the entire result set.
    * @returns The list of pending invitations
    */
-  async invitations(): Promise<InvitationInfo[]> {
-    return await this.#apiClient.orgInvitationsList().fetchAll();
+  async invitations(opts?: ListInvitationsOptions): Promise<InvitationInfo[]> {
+    return await this.#apiClient.orgInvitationsList(opts).fetchAll();
   }
 
   /**
@@ -617,11 +620,32 @@ export class Org {
   /**
    * List all users in the organization.
    *
-   * @param searchQuery Optional query string. If defined, all returned users will contain this string in their name or email.
+   * @overload
+   * @param opts Additional options for filtering the users.
    * @returns The list of users
    */
-  async users(searchQuery?: string): Promise<UserInOrgInfo[]> {
-    return await this.#apiClient.orgUsersList(undefined, searchQuery).fetchAll();
+  async users(opts?: ListUsersOptions): Promise<UserInOrgInfo[]>;
+  /**
+   * List all users in the organization.
+   *
+   * @overload
+   * @param searchQuery Query string. If defined, all returned users will contain this string in their name or email.
+   * @returns The list of users
+   * @deprecated Use the `ListUsersOptions` parameter overload instead.
+   */
+  async users(searchQuery?: string): Promise<UserInOrgInfo[]>;
+  /**
+   * List all users in the organization.
+   *
+   * @param optsOrSearchQuery Either additional options for filtering the users, or (deprecated) a search query string.
+   * @returns The list of users
+   */
+  async users(optsOrSearchQuery?: ListUsersOptions | string): Promise<UserInOrgInfo[]> {
+    const opts: ListUsersOptions =
+      typeof optsOrSearchQuery === "string"
+        ? { searchQuery: optsOrSearchQuery }
+        : (optsOrSearchQuery ?? {});
+    return await this.#apiClient.orgUsersList(opts).fetchAll();
   }
 
   /**

package/src/policy.ts

@@ -78,7 +78,7 @@ export type PolicyCtx = {
    * The resources (keys, roles, and key-in-roles) that the access control entry
    * applies to.
    */
-  resources: AceAttribute<PolicyResource>;
+  resources?: AceAttribute<PolicyResource>;
 };
 
 /** A resource a policy is invoked with or attached to. */

package/src/schema.ts

@@ -755,6 +755,8 @@ export interface paths {
      *
      * NOTE that if pagination is used and a page limit is set, the returned result
      * set may contain either FEWER or MORE elements than the requested page limit.
+     * In particular, legacy MFA requests are not paginated: every accessible one
+     * is returned in the first page, on top of the page limit.
      */
     get: operations["mfaList"];
   };
@@ -2880,6 +2882,9 @@ export interface components {
     /** @enum {string} */
     BadRequestErrorCode:
       | "GenericBadRequest"
+      | "CannotVoteOnRedeemedRequest"
+      | "PendingOpAlreadyVetoed"
+      | "MultiplePendingOpsReferenced"
       | "DisallowedAllowRuleReference"
       | "InvalidPaginationToken"
       | "InvalidEmail"
@@ -6178,7 +6183,7 @@ export interface components {
     /** @default null */
     Empty: unknown;
     EmptyImpl: {
-      status: string;
+      status: components["schemas"]["StatusOk"];
     };
     /**
      * @description Request to create a set of EOTS nonces for a specified chain-id, starting
@@ -6940,6 +6945,19 @@ export interface components {
     };
     /** @description Declares intent to register a new FIDO key */
     FidoCreateRequest: {
+      /**
+       * @description If set, the attestation answering this registration challenge additionally counts as an
+       * approving vote on pending MFA request `mfa_id`.
+       *
+       * This exists so that a user who must register their first second factor in order to complete
+       * an operation (most commonly logging in) does not have to perform two authenticator
+       * ceremonies back to back: one to enroll the credential and another to immediately prove
+       * possession of it. The attestation is a full WebAuthn ceremony over a server-issued
+       * challenge, so it is no weaker than the separate assertion it replaces.
+       *
+       * Requires the 'manage:mfa:vote:fido' scope in addition to 'manage:mfa:register:fido'.
+       */
+      approve_mfa?: string | null;
       /** @description Whether this key can be used for passwordless login */
       discoverable?: boolean;
       /**
@@ -6956,6 +6974,11 @@ export interface components {
        */
       request_device_identifier?: boolean;
     };
+    /** @description Result of registering a FIDO key */
+    FidoRegisterResponse: {
+      mfa?: components["schemas"]["MfaRequestInfo"];
+      status: components["schemas"]["StatusOk"];
+    };
     /** @enum {string} */
     ForbiddenErrorCode:
       | "AlienKeyCreate"
@@ -7018,10 +7041,10 @@ export interface components {
       | "SessionPossiblyStolenToken"
       | "MfaDisallowedIdentity"
       | "MfaDisallowedApprover"
+      | "PendingOpDisallowedApprover"
       | "MfaTypeNotAllowed"
       | "MfaNotApprovedYet"
       | "MfaConfirmationCodeMismatch"
-      | "MfaHttpRequestMismatch"
       | "MfaRemoveBelowMin"
       | "MfaOrgRequirementNotMet"
       | "MfaRegistrationDisallowed"
@@ -7985,13 +8008,16 @@ export interface components {
      * }
      */
     MfaPolicy: {
-      /** @description Users who are allowed to approve. If empty at creation time, default to the current user. */
+      /**
+       * @description Users who are allowed to approve. If empty, the current user
+       * will be inserted by default.
+       */
       allowed_approvers?: string[];
       /** @description Allowed approval types. When omitted, defaults to any. */
       allowed_mfa_types?: components["schemas"]["MfaType"][] | null;
       /**
        * Format: int32
-       * @description How many users to require to approve (defaults to 1).
+       * @description How many users must approve (defaults to 1).
        */
       count?: number;
       lifetime?: components["schemas"]["Seconds"];
@@ -8054,7 +8080,7 @@ export interface components {
     MfaRequiredArgs: {
       /** @description Always set to first MFA id from `Self::ids` */
       id: string;
-      /** @description Non-empty MFA request IDs */
+      /** @description Non-empty MFA request IDs or [`PendingOpPolicyRef`]-form refs */
       ids: string[];
       /** @description Organization id */
       org_id: string;
@@ -9347,6 +9373,8 @@ export interface components {
       | components["schemas"]["EvmTxDepositErrorCode"];
     /** @enum {string} */
     PolicyErrorOwnCodes:
+      | "MfaHttpRequestMismatch"
+      | "MfaExpired"
       | "Inapplicable"
       | "SuiTxReceiversDisallowedTransactionKind"
       | "SuiTxReceiversDisallowedTransferAddress"
@@ -9423,6 +9451,7 @@ export interface components {
       | "WasmPolicyFailed"
       | "WebhookPoliciesDisabled"
       | "DeniedByWebhook"
+      | "MfaApprovalsNotYetValid"
       | "ExplicitlyDenied";
     /** @description A struct containing all the information about a specific version of a policy. */
     PolicyInfo: {
@@ -9523,8 +9552,7 @@ export interface components {
       | "ConcurrentSigningWhenTimeLimitPolicyIsDefined"
       | "BabylonEotsConcurrentSigning"
       | "TendermintStateError"
-      | "TendermintConcurrentSigning"
-      | "MfaApprovalsNotYetValid";
+      | "TendermintConcurrentSigning";
     /** @description Contains outputs of previous transactions. */
     PrevOutputs: OneOf<
       [
@@ -10676,29 +10704,47 @@ export interface components {
        */
       created_validator_key_id: string;
     };
+    /**
+     * @description Approval state for a [`MfaRequest`] in [`MfaRequestSource::Legacy`] mode:
+     * the per-policy [`ApprovalConstraints`] plus an inline `approved_by` map.
+     * Pooled MfaRequests carry only [`ApprovalConstraints`] — their approvals live
+     * on the linked [`PendingOp`] — so the type system enforces "no pooled
+     * MfaRequest has an `approved_by`."
+     */
     Status: {
       /** @description Users who are allowed to approve. Must be non-empty. */
       allowed_approvers: string[];
       /** @description Allowed approval types. When omitted, defaults to any. */
       allowed_mfa_types?: components["schemas"]["MfaType"][] | null;
-      /** @description Users who have already approved */
-      approved_by: {
-        [key: string]: {
-          [key: string]: components["schemas"]["ApprovalInfo"];
-        };
-      };
       /**
        * Format: int32
-       * @description How many users must approve
+       * @description How many users must approve (defaults to 1).
        */
       count: number;
       /**
        * Format: int32
-       * @description How many auth factors to require per user
+       * @description How many auth factors to require per user (defaults to 1).
        */
       num_auth_factors: number;
       request_comparer?: components["schemas"]["HttpRequestCmp"];
+    } & {
+      /** @description Users who have already approved. */
+      approved_by: {
+        [key: string]: {
+          [key: string]: components["schemas"]["ApprovalInfo"];
+        };
+      };
     };
+    /**
+     * @description The `status` field carried by [`Empty`] responses. Always serializes as `"ok"`.
+     *
+     * Endpoints that used to return [`Empty`] and now return something richer must keep emitting
+     * this field, because generated clients bind [`Empty`] to a struct with a *required* `status`
+     * and would otherwise fail to deserialize a successful response. Use this type rather than a
+     * bare `String` so the one acceptable value is not something anyone has to remember.
+     * @enum {string}
+     */
+    StatusOk: "ok";
     /**
      * @description A single asset balance entry returned by [`SubAccountAssetsResponse`].
      *
@@ -11119,8 +11165,25 @@ export interface components {
        */
       totp_url: string;
     };
+    /** @description Result of registering (resetting) TOTP */
+    TotpRegisterResponse: {
+      mfa?: components["schemas"]["MfaRequestInfo"];
+      status: components["schemas"]["StatusOk"];
+    };
     /** @description Request to reset TOTP. */
     TotpResetRequest: {
+      /**
+       * @description If set, the code answering this challenge additionally counts as an approving vote on
+       * pending MFA request `mfa_id`.
+       *
+       * This exists so that a user who must register their first second factor in order to complete
+       * an operation (most commonly logging in) does not have to enter two TOTP codes back to back:
+       * one to confirm enrollment and another to immediately approve the pending request. Answering
+       * the challenge already proves possession of the new secret.
+       *
+       * Requires the 'manage:mfa:vote:totp' scope in addition to 'manage:mfa:register:totp'.
+       */
+      approve_mfa?: string | null;
       /** @description The name of the issuer; defaults to "Cubist". */
       issuer?: string | null;
     };
@@ -12756,7 +12819,7 @@ export interface components {
     EmptyImpl: {
       content: {
         "application/json": {
-          status: string;
+          status: components["schemas"]["StatusOk"];
         };
       };
     };
@@ -12822,6 +12885,15 @@ export interface components {
         };
       };
     };
+    /** @description Result of registering a FIDO key */
+    FidoRegisterResponse: {
+      content: {
+        "application/json": {
+          mfa?: components["schemas"]["MfaRequestInfo"];
+          status: components["schemas"]["StatusOk"];
+        };
+      };
+    };
     /** @description The email sender configuration (without sensitive auth details) */
     GetEmailConfigResponse: {
       content: {
@@ -14012,6 +14084,15 @@ export interface components {
         };
       };
     };
+    /** @description Result of registering (resetting) TOTP */
+    TotpRegisterResponse: {
+      content: {
+        "application/json": {
+          mfa?: components["schemas"]["MfaRequestInfo"];
+          status: components["schemas"]["StatusOk"];
+        };
+      };
+    };
     /** @description A response to sign an eth2 unstake request. */
     UnstakeResponse: {
       content: {
@@ -16229,6 +16310,8 @@ export interface operations {
          * the exact value previously returned as 'last_evaluated_key' from the same endpoint.
          */
         "page.start"?: string | null;
+        /** @description Membership roles. If defined, only invitations for one of these roles are returned, grouped by role in descending role order (owners first, aliens last). */
+        membership?: components["schemas"]["MemberRole"][] | null;
       };
       path: {
         /**
@@ -16735,6 +16818,8 @@ export interface operations {
    *
    * NOTE that if pagination is used and a page limit is set, the returned result
    * set may contain either FEWER or MORE elements than the requested page limit.
+   * In particular, legacy MFA requests are not paginated: every accessible one
+   * is returned in the first page, on top of the page limit.
    */
   mfaList: {
     parameters: {
@@ -19478,7 +19563,7 @@ export interface operations {
       };
     };
     responses: {
-      200: components["responses"]["EmptyImpl"];
+      200: components["responses"]["FidoRegisterResponse"];
       default: {
         content: {
           "application/json": components["schemas"]["ErrorResponse"];
@@ -19625,7 +19710,7 @@ export interface operations {
       };
     };
     responses: {
-      200: components["responses"]["EmptyImpl"];
+      200: components["responses"]["TotpRegisterResponse"];
       default: {
         content: {
           "application/json": components["schemas"]["ErrorResponse"];
@@ -19691,6 +19776,8 @@ export interface operations {
         "page.start"?: string | null;
         /** @description A query string. If defined, all returned users will contain this string in their name or email. */
         q?: string | null;
+        /** @description Membership roles. If defined, only users with one of these roles in the org are returned, grouped by role in descending role order (owners first, aliens last). */
+        membership?: components["schemas"]["MemberRole"][] | null;
       };
       path: {
         /**