@cubist-labs/cubesigner-sdk 0.4.269 → 0.4.272

package/src/client/api_client.ts

@@ -74,6 +74,8 @@ import type {
   PolicyInfo,
   JsonRpcRequest,
   JsonRpcResult,
+  Eip7702SignRequest,
+  SignResponse,
 } from "../schema_types.ts";
 import { encodeToBase64 } from "../util.ts";
 import { auditLogEntrySchema } from "../audit_log.ts";
@@ -723,7 +725,7 @@ export class ApiClient extends BaseClient {
 
   // #endregion
 
-  // #region ORG USERS: orgUserInvite, orgUserDelete, orgUsersList, orgUserGet, orgUserGetByEmail, orgUserCreateOidc, orgUserDeleteOidc
+  // #region ORG USERS: orgUserInvite, orgUserDelete, orgUsersList, orgUserGet, orgUserGetByEmail, orgUserCreateOidc, orgUserDeleteOidc, resetUserMfaInit, resetUserMfaComplete
 
   /**
    * Create a new (first-party) user in the organization and send an email invitation to that user.
@@ -923,6 +925,55 @@ export class ApiClient extends BaseClient {
     });
   }
 
+  /**
+   * Initiate an MFA reset for a user in the org (then the user must call {@link resetUserMfaComplete}).
+   *
+   * Can only be called by an org owner. The target may be any org user with an
+   * email configured; the backend emails them a short-lived reset token, which
+   * the user can use to complete the reset.
+   *
+   * @param userId The id of the user whose MFA should be reset.
+   * @returns An empty response
+   */
+  async resetUserMfaInit(userId: string): Promise<Empty> {
+    const o = op("/v0/org/{org_id}/users/reset_mfa", "post");
+
+    return this.exec(o, {
+      body: { user_id: userId },
+    });
+  }
+
+  /**
+   * Complete an MFA reset for a user in the org (after an org owner initiates
+   * with {@link resetUserMfaInit}).
+   *
+   * Clears all of the calling user's MFA factors. Authenticated via an OIDC
+   * token, since an MFA-locked user cannot complete a session login.
+   *
+   * @param env The environment to use
+   * @param orgId The org the user belongs to
+   * @param oidcToken An OIDC token identifying the user whose MFA is being reset
+   * @param resetToken The reset token emailed to the user by {@link resetUserMfaInit}
+   * @param headers Optional headers to set
+   */
+  static async resetUserMfaComplete(
+    env: EnvInterface,
+    orgId: string,
+    oidcToken: string,
+    resetToken: string,
+    headers?: HeadersInit,
+  ): Promise<void> {
+    const o = op("/v0/org/{org_id}/users/reset_mfa", "patch");
+    await retryOn5XX(() =>
+      o({
+        baseUrl: env.SignerApiRoot,
+        params: { path: { org_id: orgId } },
+        body: { token: resetToken },
+        headers: mergeHeaders(headers, authHeader(oidcToken)),
+      }),
+    ).then(assertOk);
+  }
+
   // #endregion
 
   // #region KEYS: keyGet, keyAttest, keyUpdate, keyDelete, keysCreate, keysDerive, keysList, keyHistory
@@ -2144,13 +2195,17 @@ export class ApiClient extends BaseClient {
   /**
    * List pending MFA requests accessible to the current user.
    *
-   * @returns The MFA requests.
+   * @param page Pagination options. Defaults to fetching the entire result set.
+   * @returns Paginator for iterating over the MFA requests.
    */
-  async mfaList(): Promise<MfaRequestInfo[]> {
+  mfaList(page?: PageOpts): Paginator<schemas["PaginatedListMfaResponse"], MfaRequestInfo[]> {
     const o = op("/v0/org/{org_id}/mfa", "get");
-
-    const { mfa_requests } = await this.exec(o, {});
-    return mfa_requests;
+    return Paginator.items(
+      page ?? Page.default(),
+      (query) => this.exec(o, { params: { query } }),
+      (r) => r.mfa_requests,
+      (r) => r.last_evaluated_key,
+    );
   }
 
   /**
@@ -2350,6 +2405,33 @@ export class ApiClient extends BaseClient {
     return await CubeSignerResponse.create(this.env, signFn, mfaReceipt);
   }
 
+  /**
+   * Sign EIP-7702 authorization request.
+   *
+   * This requires the key to have a '"AllowEip7702Signing"' {@link KeyPolicy}.
+   *
+   * @param key The key to sign with (either {@link Key} or its material ID).
+   * @param req What to sign
+   * @param mfaReceipt Optional MFA receipt(s)
+   * @returns Signature (or MFA approval request).
+   */
+  async signEip7702(
+    key: Key | string,
+    req: Eip7702SignRequest,
+    mfaReceipt?: MfaReceipts,
+  ): Promise<CubeSignerResponse<SignResponse>> {
+    const o = op("/v0/org/{org_id}/evm/eip7702/sign/{pubkey}", "post");
+
+    const pubkey = typeof key === "string" ? (key as string) : key.materialId;
+    const signFn = async (headers?: HeadersInit) =>
+      this.exec(o, {
+        params: { path: { pubkey } },
+        body: req,
+        headers,
+      });
+    return await CubeSignerResponse.create(this.env, signFn, mfaReceipt);
+  }
+
   /**
    * Sign an Eth2/Beacon-chain validation message.
    *

package/src/client.ts

@@ -160,6 +160,20 @@ export class CubeSignerClient {
     return await ApiClient.identityProveOidc(...args);
   }
 
+  /**
+   * Complete an MFA reset for a user in the org. The reset must first be
+   * initiated by an org owner via {@link Org.resetUserMfaInit}.
+   *
+   * Same as {@link ApiClient.resetUserMfaComplete}, see its documentation for more details.
+   *
+   * @param args Request arguments
+   */
+  static async resetUserMfaComplete(
+    ...args: Parameters<typeof ApiClient.resetUserMfaComplete>
+  ): Promise<void> {
+    await ApiClient.resetUserMfaComplete(...args);
+  }
+
   /**
    * Initialize email OTP authentication.
    *

package/src/key.ts

@@ -30,6 +30,8 @@ import type {
   KeyInfoJwt,
   KeyAttestationQuery,
   KeyPropertiesPatch,
+  Eip7702SignRequest,
+  SignResponse,
 } from "./schema_types.ts";
 import type {
   ApiClient,
@@ -553,6 +555,22 @@ export class Key {
     return await this.#apiClient.signEip712(this, req, mfaReceipt);
   }
 
+  /**
+   * Sign EIP-7702 authorization request.
+   *
+   * This requires the key to have a '"AllowEip7702Signing"' {@link KeyPolicy}.
+   *
+   * @param req What to sign
+   * @param mfaReceipt Optional MFA receipt(s)
+   * @returns Signature (or MFA approval request).
+   */
+  async signEip7702(
+    req: Eip7702SignRequest,
+    mfaReceipt?: MfaReceipts,
+  ): Promise<CubeSignerResponse<SignResponse>> {
+    return await this.#apiClient.signEip7702(this, req, mfaReceipt);
+  }
+
   /**
    * Sign an Eth2/Beacon-chain validation message.
    *

package/src/org.ts

@@ -569,6 +569,18 @@ export class Org {
     return this.#apiClient.orgUserDeleteOidc.bind(this.#apiClient);
   }
 
+  /**
+   * Initiate an MFA reset for a user in the org. The reset is completed by
+   * the user via {@link CubeSignerClient.resetUserMfaComplete}.
+   *
+   * Same as {@link ApiClient.resetUserMfaInit}, see its documentation for more information.
+   *
+   * @returns A function that initiates an MFA reset for a user
+   */
+  get resetUserMfaInit() {
+    return this.#apiClient.resetUserMfaInit.bind(this.#apiClient);
+  }
+
   /**
    * List all users in the organization.
    *
@@ -997,11 +1009,13 @@ export class Org {
   /**
    * List pending MFA requests accessible to the current user.
    *
+   * @param page Pagination options. Defaults to fetching the entire result set.
    * @returns The MFA requests.
    */
-  async mfaRequests(): Promise<MfaRequest[]> {
+  async mfaRequests(page?: PageOpts): Promise<MfaRequest[]> {
     return await this.#apiClient
-      .mfaList()
+      .mfaList(page)
+      .fetch()
       .then((mfaInfos) => mfaInfos.map((mfaInfo) => new MfaRequest(this.#apiClient, mfaInfo)));
   }
 

package/src/role.ts

@@ -462,6 +462,10 @@ export type AllowEip191Signing = typeof AllowEip191Signing;
 export const AllowEip712Signing = "AllowEip712Signing" as const;
 export type AllowEip712Signing = typeof AllowEip712Signing;
 
+/** Allow EIP-7702 signing */
+export const AllowEip7702Signing = "AllowEip7702Signing" as const;
+export type AllowEip7702Signing = typeof AllowEip7702Signing;
+
 /** Allow BTC message signing */
 export const AllowBtcMessageSigning = "AllowBtcMessageSigning" as const;
 export type AllowBtcMessageSigning = typeof AllowBtcMessageSigning;
@@ -471,6 +475,7 @@ export type AllowPolicy =
   | AllowDiffieHellmanExchange
   | AllowEip191Signing
   | AllowEip712Signing
+  | AllowEip7702Signing
   | AllowBtcMessageSigning;
 
 /** A reference to an org-level named policy, using its name/id and its version */

package/src/schema.ts

@@ -439,6 +439,17 @@ export interface paths {
      */
     post: operations["eip712Sign"];
   };
+  "/v0/org/{org_id}/evm/eip7702/sign/{pubkey}": {
+    /**
+     * Sign an EIP-7702 Authorization
+     * @description Sign an EIP-7702 Authorization
+     *
+     * Signs an EIP-7702 authorization tuple `(chain_id, address, nonce)` with a given
+     * Secp256k1 key. The resulting 65-byte signature (`r || s || y_parity`) can be used to
+     * assemble a `SignedAuthorization` for an EIP-7702 set-code transaction.
+     */
+    post: operations["eip7702Sign"];
+  };
   "/v0/org/{org_id}/export/{key_id}": {
     /**
      * Get an Org-Export Ciphertext
@@ -740,6 +751,9 @@ export interface paths {
      * Retrieves and returns all pending MFA requests that are accessible to the current session,
      * i.e., those created by the current session identity plus those in which the current user
      * is listed as an approver
+     *
+     * 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.
      */
     get: operations["mfaList"];
   };
@@ -2965,6 +2979,7 @@ export interface components {
       | "InvalidDiffieHellmanRequest"
       | "InvalidSolanaSignRequest"
       | "InvalidEip712SignRequest"
+      | "InvalidEip7702SignRequest"
       | "OnlySpecifyOne"
       | "IncompatibleParams"
       | "NoOidcDataInProof"
@@ -3239,6 +3254,7 @@ export interface components {
       | "TaprootSign"
       | "Eip712Sign"
       | "Eip191Sign"
+      | "Eip7702Sign"
       | "Eth1Sign"
       | "Eth2Sign"
       | "SolanaSign"
@@ -5657,6 +5673,51 @@ export interface components {
       tweak?: string | null;
       typed_data: components["schemas"]["TypedData"];
     };
+    Eip7702SignRequest: {
+      /** @description Do not produce a valid signature, just evaluate attached policies. */
+      dry_run?: boolean;
+      /**
+       * @description Request additional information to be included in the response, explaining
+       * the outcome (i.e., permitted vs. denied vs. MFA required) of the sign request.
+       * Defaults to false.
+       */
+      explain?: boolean;
+      /**
+       * @description If MFA is required, fail the request instead of returning 202 and creating
+       * pending MFA request. Defaults to false.
+       */
+      fail_on_mfa?: boolean;
+      /**
+       * @description Optional metadata. Passing additional information as metadata can be used to make reviewing
+       * of pending MFA requests and/or historical key transactions more transparent. It can also be used e.g., to carry additional data to WebHook policies.
+       */
+      metadata?: unknown;
+    } & {
+      /**
+       * @description The address to delegate to (the target of the authorization), as
+       * hex-encoded bytes. Must be exactly 20 bytes.
+       * @example 0x1100000000000000000000000000000000000011
+       */
+      address: string;
+      /**
+       * Format: int64
+       * @description The chain id for which this authorization is valid. A value of `0` means
+       * the authorization is valid on any chain that supports EIP-7702.
+       */
+      chain_id: number;
+      /**
+       * Format: int64
+       * @description The nonce of the authorizing account.
+       */
+      nonce: number;
+      /**
+       * @description An optional tweak value that will be applied to the secret key before signing.
+       * This field must contain a base-64 string encoding a vector of exactly 32 bytes.
+       * See the CubeSigner documentation for more information on the tweaking procedure.
+       * @example F41HAy2q5Gn8laF2CuMsZbRAQTmD+4Ob3VUMZ7TBGK4=
+       */
+      tweak?: string | null;
+    };
     Email: string;
     /** @description An answer to the challenge returned by the `mfa_email_init` endpoint. */
     EmailOtpAnswer: {
@@ -6222,6 +6283,7 @@ export interface components {
       | "sign:evm:tx"
       | "sign:evm:eip191"
       | "sign:evm:eip712"
+      | "sign:evm:eip7702"
       | "sign:eth2:*"
       | "sign:eth2:validate"
       | "sign:eth2:stake"
@@ -6507,6 +6569,7 @@ export interface components {
       | "SessionForWrongOrg"
       | "SelfDelete"
       | "SelfDisable"
+      | "SelfMfaReset"
       | "InvalidOrgMembershipRoleChange"
       | "UserDisabled"
       | "OrgDisabled"
@@ -7399,10 +7462,6 @@ export interface components {
       /** @description Pending invitations */
       invitations: components["schemas"]["InvitationInfo"][];
     };
-    ListMfaResponse: {
-      /** @description All pending MFA requests */
-      mfa_requests: components["schemas"]["MfaRequestInfo"][];
-    };
     /** @description All pending MMI requests created by the current user. */
     ListPendingMessagesResponse: {
       /** @description All pending messages for a user. */
@@ -7881,6 +7940,7 @@ export interface components {
       | "TaprootSign"
       | "Eip191Sign"
       | "Eip712Sign"
+      | "Eip7702Sign"
       | "EotsNonces"
       | "EotsSign"
       | "Eth1Sign"
@@ -8531,6 +8591,21 @@ export interface components {
        */
       last_evaluated_key?: string | null;
     };
+    /**
+     * @description Response type that wraps another type and adds base64url-encoded encrypted `last_evaluated_key`
+     * value (which can the user pass back to use as a url query parameter to continue pagination).
+     */
+    PaginatedListMfaResponse: {
+      /** @description All pending MFA requests */
+      mfa_requests: components["schemas"]["MfaRequestInfo"][];
+    } & {
+      /**
+       * @description If set, the content of `response` does not contain the entire result set.
+       * To fetch the next page of the result set, call the same endpoint
+       * but specify this value as the 'page.start' query parameter.
+       */
+      last_evaluated_key?: string | null;
+    };
     /**
      * @description Response type that wraps another type and adds base64url-encoded encrypted `last_evaluated_key`
      * value (which can the user pass back to use as a url query parameter to continue pagination).
@@ -8860,6 +8935,7 @@ export interface components {
       | "BtcSignatureExceededValue"
       | "BtcValueOverflow"
       | "BtcSighashTypeDisallowed"
+      | "Eip7702AddressMismatch"
       | "EvmTxReceiverMismatch"
       | "EvmTxChainIdMismatch"
       | "EvmTxSenderMismatch"
@@ -8900,6 +8976,7 @@ export interface components {
       | "RequireRoleSessionKeyAccessError"
       | "BtcMessageSigningNotAllowed"
       | "Eip191SigningNotAllowed"
+      | "Eip7702SigningNotAllowed"
       | "TaprootSigningDisallowed"
       | "SegwitSigningDisallowed"
       | "PsbtSigningDisallowed"
@@ -9836,7 +9913,7 @@ export interface components {
        * Can be `None` if the request is creating a secret without ACL or updating an
        * existing secret's value.
        */
-      acl?: unknown[] | null;
+      acl?: unknown;
       import_key?: components["schemas"]["KeyImportKey"] | null;
       value?: components["schemas"]["SecretValue"] | null;
     };
@@ -11285,26 +11362,8 @@ export interface components {
     };
     /** @description Request body for updating a named policy. */
     UpdatePolicyRequest: {
-      /**
-       * @description New Access-control entries.
-       * @example [
-       *   {
-       *     "action": "attach",
-       *     "resources": [
-       *       {
-       *         "key_id": "*",
-       *         "role_id": "Role#e427c28a-9c5b-49cc-a257-878aea58a22c"
-       *       }
-       *     ],
-       *     "subjects": "*"
-       *   },
-       *   {
-       *     "action": "sign",
-       *     "subjects": "Role#e427c28a-9c5b-49cc-a257-878aea58a22c"
-       *   }
-       * ]
-       */
-      acl?: unknown[] | null;
+      /** @description New Access-control entries. */
+      acl?: unknown;
       edit_policy?: components["schemas"]["EditPolicy"] | null;
       /** @description A new metadata. */
       metadata?: unknown;
@@ -12529,14 +12588,6 @@ export interface components {
         };
       };
     };
-    ListMfaResponse: {
-      content: {
-        "application/json": {
-          /** @description All pending MFA requests */
-          mfa_requests: components["schemas"]["MfaRequestInfo"][];
-        };
-      };
-    };
     /** @description All pending MMI requests created by the current user. */
     ListPendingMessagesResponse: {
       content: {
@@ -12875,6 +12926,21 @@ export interface components {
         };
       };
     };
+    PaginatedListMfaResponse: {
+      content: {
+        "application/json": {
+          /** @description All pending MFA requests */
+          mfa_requests: components["schemas"]["MfaRequestInfo"][];
+        } & {
+          /**
+           * @description If set, the content of `response` does not contain the entire result set.
+           * To fetch the next page of the result set, call the same endpoint
+           * but specify this value as the 'page.start' query parameter.
+           */
+          last_evaluated_key?: string | null;
+        };
+      };
+    };
     PaginatedListPoliciesResponse: {
       content: {
         "application/json": {
@@ -15128,6 +15194,48 @@ export interface operations {
       };
     };
   };
+  /**
+   * Sign an EIP-7702 Authorization
+   * @description Sign an EIP-7702 Authorization
+   *
+   * Signs an EIP-7702 authorization tuple `(chain_id, address, nonce)` with a given
+   * Secp256k1 key. The resulting 65-byte signature (`r || s || y_parity`) can be used to
+   * assemble a `SignedAuthorization` for an EIP-7702 set-code transaction.
+   */
+  eip7702Sign: {
+    parameters: {
+      path: {
+        /**
+         * @description Name or ID of the desired Org
+         * @example Org#124dfe3e-3bbd-487d-80c0-53c55e8ab87a
+         */
+        org_id: string;
+        /**
+         * @description Hex-encoded EVM address of the Secp256k1 key
+         * @example 0x49011adbCC3bC9c0307BB07F37Dda1a1a9c69d2E
+         */
+        pubkey: string;
+      };
+    };
+    requestBody: {
+      content: {
+        "application/json": components["schemas"]["Eip7702SignRequest"];
+      };
+    };
+    responses: {
+      200: components["responses"]["SignResponse"];
+      202: {
+        content: {
+          "application/json": components["schemas"]["AcceptedResponse"];
+        };
+      };
+      default: {
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
+    };
+  };
   /**
    * Get an Org-Export Ciphertext
    * @description Get an Org-Export Ciphertext
@@ -16142,9 +16250,27 @@ export interface operations {
    * Retrieves and returns all pending MFA requests that are accessible to the current session,
    * i.e., those created by the current session identity plus those in which the current user
    * is listed as an approver
+   *
+   * 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.
    */
   mfaList: {
     parameters: {
+      query?: {
+        /**
+         * @description Max number of items to return per page.
+         *
+         * If the actual number of returned items may be less that this, even if there exist more
+         * data in the result set. To reliably determine if more data is left in the result set,
+         * inspect the [UnencryptedLastEvalKey] value in the response object.
+         */
+        "page.size"?: number;
+        /**
+         * @description The start of the page.  Omit to start from the beginning; otherwise, only specify a
+         * the exact value previously returned as 'last_evaluated_key' from the same endpoint.
+         */
+        "page.start"?: string | null;
+      };
       path: {
         /**
          * @description Name or ID of the desired Org
@@ -16154,7 +16280,7 @@ export interface operations {
       };
     };
     responses: {
-      200: components["responses"]["ListMfaResponse"];
+      200: components["responses"]["PaginatedListMfaResponse"];
       default: {
         content: {
           "application/json": components["schemas"]["ErrorResponse"];

package/src/schema_types.ts

@@ -33,6 +33,8 @@ export type UpdateOrgRequest = schemas["UpdateOrgRequest"];
 export type OrgExtProps = NonNullable<UpdateOrgRequest["ext_props"]>;
 export type UpdateOrgResponse = schemas["UpdateOrgResponse"];
 export type UpdateUserMembershipRequest = schemas["UpdateUserMembershipRequest"];
+export type MfaResetRequest = schemas["MfaResetRequest"];
+export type CompleteMfaResetRequest = schemas["CompleteMfaResetRequest"];
 export type NotificationEndpointConfiguration = schemas["NotificationEndpointConfiguration"];
 export type OrgEvents = schemas["OrgEventDiscriminants"];
 export type BillingEvent = schemas["BillingEvent"];
@@ -78,6 +80,7 @@ const AllOperationKinds: Record<OperationKind, true> = {
   TaprootSign: true,
   Eip191Sign: true,
   Eip712Sign: true,
+  Eip7702Sign: true,
   EotsNonces: true,
   EotsSign: true,
   Eth1Sign: true,
@@ -165,7 +168,9 @@ export type EvmSignRequest = schemas["Eth1SignRequest"];
 export type EvmSignResponse = schemas["Eth1SignResponse"];
 export type Eip191SignRequest = schemas["Eip191SignRequest"];
 export type Eip712SignRequest = schemas["Eip712SignRequest"];
+export type Eip7702SignRequest = schemas["Eip7702SignRequest"];
 export type Eip191Or712SignResponse = schemas["SignResponse"];
+export type SignResponse = schemas["SignResponse"];
 export type Eth2SignRequest = schemas["Eth2SignRequest"];
 export type Eth2SignResponse = schemas["SignResponse"];
 export type Eth2StakeRequest = schemas["StakeRequest"];

package/src/scopes.ts

@@ -70,7 +70,8 @@ export const AllScopes: Record<ExplicitScope, string> =
   "sign:evm:*"                                  : "Allows access to all sign 'evm' endpoints",
   "sign:evm:tx"                                 : "Allows access to the signing endpoint for evm transactions",
   "sign:evm:eip191"                             : "Allows access to the signing endpoint for EIP-191 personal_message data",
-  "sign:evm:eip712"                             : "Allows acess to the signing endpoint for EIP-712 typed data",
+  "sign:evm:eip712"                             : "Allows access to the signing endpoint for EIP-712 typed data",
+  "sign:evm:eip7702"                            : "Allows access to the signing endpoint for EIP-7702 authorization requests",
   "sign:eth2:*"                                 : "Allows access to all sign 'eth2' endpoints",
   "sign:eth2:validate"                          : "Allows access to the sign eth2 'validate' endpoint",
   "sign:eth2:stake"                             : "Allows access to the sign eth2 'stake' endpoint",