@cubist-labs/cubesigner-sdk 0.1.77 → 0.2.15

package/src/response.ts

@@ -0,0 +1,196 @@
+import { CubeSignerClient, SignerSession } from ".";
+import { MfaReceipt } from "./mfa";
+import { AcceptedResponse, NewSessionResponse } from "./schema_types";
+
+/**
+ * Response type, which can be either a value of type {@link U}
+ * or {@link AcceptedResponse} (status code 202) which requires MFA.
+ */
+export type Response<U> = U | AcceptedResponse;
+
+/**
+ * Request function which optionally takes additional headers
+ * (which, for example, can be used to attach an MFA receipt).
+ */
+export type RequestFn<U> = (headers?: HeadersInit) => Promise<Response<U>>;
+
+/**
+ * Map function occasionally used to map a response from the API into a higher-level type.
+ */
+export type MapFn<U, V> = (u: U) => V;
+
+/**
+ * Take a {@link Response<U>} and a {@link MapFn<U, V>} function and return
+ * a {@link Response<V>} that maps the value of the original response when its status code is 200.
+ *
+ * @param {Response<U>} resp Original response
+ * @param {Map<U, V>} mapFn Map to apply to the response value when its status code is 200.
+ * @return {Response<V>} Response whose value for status code 200 is mapped from U to V
+ */
+export function mapResponse<U, V>(resp: Response<U>, mapFn: MapFn<U, V>): Response<V> {
+  if ((resp as AcceptedResponse).accepted?.MfaRequired) {
+    return resp as AcceptedResponse;
+  } else {
+    return mapFn(resp as U);
+  }
+}
+
+export interface MfaRequired {
+  /** Org id */
+  org_id: string;
+  /** MFA request id */
+  id: string;
+  /** Optional MFA session */
+  session?: NewSessionResponse | null;
+}
+
+/**
+ * A response of a CubeSigner request.
+ */
+export class CubeSignerResponse<U> {
+  readonly #requestFn: RequestFn<U>;
+  readonly #resp: U | AcceptedResponse;
+  /**
+   * Optional MFA id. Only set if there is an MFA request associated with the
+   * signing request
+   */
+  readonly #mfaRequired?: MfaRequired;
+
+  /** @return {string} The MFA id associated with this request (if any) */
+  mfaId(): string {
+    return this.#mfaRequired!.id;
+  }
+
+  /** @return {boolean} True if this request requires an MFA approval */
+  requiresMfa(): boolean {
+    return this.#mfaRequired !== undefined;
+  }
+
+  /**
+   * Return session information to use for any MFA approval requests (if any was included in the response).
+   * @return {ClientSessionInfo | undefined}
+   */
+  mfaSessionInfo(): NewSessionResponse | undefined {
+    return (this.#resp as AcceptedResponse).accepted?.MfaRequired?.session ?? undefined;
+  }
+
+  /** @return {U} The response data, if no MFA is required */
+  data(): U {
+    if (this.requiresMfa()) {
+      throw new Error("Cannot call `data()` while MFA is required");
+    }
+    return this.#resp as U;
+  }
+
+  /**
+   * Approve the MFA request using a given session and a TOTP code.
+   *
+   * @param {SignerSession} session Signer session to use
+   * @param {string} code 6-digit TOTP code
+   * @return {CubeSignerResponse<U>} The result of signing with the approval
+   */
+  async approveTotp(session: SignerSession, code: string): Promise<CubeSignerResponse<U>> {
+    if (!this.requiresMfa()) {
+      return this;
+    }
+
+    const mfaId = this.mfaId();
+    const mfaOrgId = this.#mfaRequired!.org_id;
+    const mfaApproval = await session.mfaApproveTotp(mfaId, code);
+    const mfaConf = mfaApproval.receipt?.confirmation;
+
+    if (!mfaConf) {
+      return this;
+    }
+
+    return await this.signWithMfaApproval({ mfaId, mfaOrgId, mfaConf });
+  }
+
+  /**
+   * Approve the MFA request using a given `CubeSignerClient` instance (i.e., its session).
+   *
+   * @param {CubeSignerClient} cs CubeSigner whose session to use
+   * @return {CubeSignerResponse<U>} The result of signing with the approval
+   */
+  async approve(cs: CubeSignerClient): Promise<CubeSignerResponse<U>> {
+    if (!this.requiresMfa()) {
+      return this;
+    }
+
+    const mfaId = this.#mfaRequired!.id;
+    const mfaOrgId = this.#mfaRequired!.org_id;
+
+    const mfaApproval = await cs.mfaApprove(mfaId);
+    const mfaConf = mfaApproval.receipt?.confirmation;
+
+    if (!mfaConf) {
+      return this;
+    }
+
+    return await this.signWithMfaApproval({ mfaId, mfaOrgId, mfaConf });
+  }
+
+  /**
+   * Resubmits the request with a given MFA receipt attached.
+   *
+   * @param {MfaReceipt} mfaReceipt The MFA receipt
+   * @return {Promise<CubeSignerResponse<U>>} The result of signing after MFA approval
+   */
+  async signWithMfaApproval(mfaReceipt: MfaReceipt): Promise<CubeSignerResponse<U>> {
+    const headers = CubeSignerResponse.getMfaHeaders(mfaReceipt);
+    return new CubeSignerResponse(this.#requestFn, await this.#requestFn(headers));
+  }
+
+  // --------------------------------------------------------------------------
+  // -- INTERNAL --------------------------------------------------------------
+  // --------------------------------------------------------------------------
+
+  /**
+   * Constructor.
+   *
+   * @param {RequestFn} requestFn
+   *    The signing function that this response is from.
+   *    This argument is used to resend requests with different headers if needed.
+   * @param {U | AcceptedResponse} resp The response as returned by the OpenAPI client.
+   * @internal
+   */
+  constructor(requestFn: RequestFn<U>, resp: U | AcceptedResponse) {
+    this.#requestFn = requestFn;
+    this.#resp = resp;
+    this.#mfaRequired = (this.#resp as AcceptedResponse).accepted?.MfaRequired;
+  }
+
+  /**
+   * Static constructor.
+   * @param {RequestFn} requestFn
+   *    The request function that this response is from.
+   *    This argument is used to resend requests with different headers if needed.
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
+   * @return {Promise<CubeSignerResponse<U>>} New instance of this class.
+   * @internal
+   */
+  static async create<U>(
+    requestFn: RequestFn<U>,
+    mfaReceipt?: MfaReceipt,
+  ): Promise<CubeSignerResponse<U>> {
+    const seed = await requestFn(this.getMfaHeaders(mfaReceipt));
+    return new CubeSignerResponse(requestFn, seed);
+  }
+
+  /**
+   * Return HTTP headers containing a given MFA receipt.
+   *
+   * @param {MfaReceipt} mfaReceipt MFA receipt
+   * @return {HeadersInit} Headers including that receipt
+   * @internal
+   */
+  static getMfaHeaders(mfaReceipt?: MfaReceipt): HeadersInit | undefined {
+    return mfaReceipt
+      ? {
+          "x-cubist-mfa-id": mfaReceipt.mfaId,
+          "x-cubist-mfa-org-id": mfaReceipt.mfaOrgId,
+          "x-cubist-mfa-confirmation": mfaReceipt.mfaConf,
+        }
+      : undefined;
+  }
+}

package/src/role.ts

@@ -1,24 +1,23 @@
 import {
-  CubeSigner,
   Key,
+  KeyWithPoliciesInfo,
   MfaType,
+  PageOpts,
+  RoleInfo,
   SignerSession,
   SignerSessionInfo,
   SignerSessionLifetime,
   SignerSessionManager,
   SignerSessionStorage,
+  UpdateRoleRequest,
 } from ".";
-import { components, paths } from "./client";
-import { assertOk } from "./util";
+import { CubeSignerClient } from "./client";
 
-type UpdateRoleRequest =
-  paths["/v0/org/{org_id}/keys/{key_id}"]["patch"]["requestBody"]["content"]["application/json"];
-type KeyWithPoliciesInfo = components["schemas"]["KeyInRoleInfo"];
-export type RoleInfo = components["schemas"]["RoleInfo"];
-
-/** Restrict transaction receiver.
+/**
+ * Restrict transaction receiver.
+ *
  * @example { TxReceiver: "0x8c594691c0e592ffa21f153a16ae41db5befcaaa" }
- * */
+ */
 export type TxReceiver = { TxReceiver: string };
 
 /** The kind of deposit contracts. */
@@ -35,14 +34,18 @@ export type TxDeposit = TxDepositBase | TxDepositPubkey | TxDepositRole;
 /** Restrict transactions to calls to deposit contract*/
 export type TxDepositBase = { TxDeposit: { kind: DepositContract } };
 
-/** Restrict transactions to calls to deposit contract with fixed validator (pubkey):
- *  @example { TxDeposit: { kind: DespositContract.Canonical, validator: { pubkey: "8879...8"} }}
- * */
+/**
+ * Restrict transactions to calls to deposit contract with fixed validator (pubkey):
+ *
+ * @example { TxDeposit: { kind: DespositContract.Canonical, validator: { pubkey: "8879...8"} }}
+ */
 export type TxDepositPubkey = { TxDeposit: { kind: DepositContract; pubkey: string } };
 
-/** Restrict transactions to calls to deposit contract with any validator key in a role:
+/**
+ * Restrict transactions to calls to deposit contract with any validator key in a role:
+ *
  * @example { TxDeposit: { kind: DespositContract.Canonical, validator: { role_id: "Role#c63...af"} }}
- * */
+ */
 export type TxDepositRole = { TxDeposit: { kind: DepositContract; role_id: string } };
 
 /** All different kinds of sensitive operations. */
@@ -55,7 +58,9 @@ export enum OperationKind {
   SolanaSign = "SolanaSign", // eslint-disable-line no-unused-vars
 }
 
-/** MFA policy
+/**
+ * MFA policy
+ *
  * @example {
  * {
  *   count: 1,
@@ -63,7 +68,7 @@ export enum OperationKind {
  *   allowed_mfa_types: [ "Totp" ],
  *   allowed_approvers: [ "User#123" ],
  * }
- * */
+ */
 export type MfaPolicy = {
   count?: number;
   num_auth_factors?: number;
@@ -72,7 +77,9 @@ export type MfaPolicy = {
   restricted_operations?: OperationKind[];
 };
 
-/** Require MFA for transactions.
+/**
+ * Require MFA for transactions.
+ *
  * @example {
  *     RequireMfa: {
  *       count: 1,
@@ -84,7 +91,7 @@ export type MfaPolicy = {
  *       ]
  *     }
  *   }
- * */
+ */
 export type RequireMfa = {
   RequireMfa: MfaPolicy;
 };
@@ -93,7 +100,9 @@ export type RequireMfa = {
 export const AllowRawBlobSigning = "AllowRawBlobSigning" as const;
 export type AllowRawBlobSigning = typeof AllowRawBlobSigning;
 
-/** Key policy
+/**
+ * Key policy
+ *
  * @example [
  *   {
  *     "TxReceiver": "0x8c594691c0e592ffa21f153a16ae41db5befcaaa"
@@ -114,30 +123,29 @@ export type AllowRawBlobSigning = typeof AllowRawBlobSigning;
  *     }
  *   }
  * ]
- * */
+ */
 export type KeyPolicy = (TxReceiver | TxDeposit | RequireMfa | AllowRawBlobSigning)[];
 
 /** A key guarded by a policy. */
 export class KeyWithPolicies {
-  readonly #cs: CubeSigner;
-  readonly #orgId: string;
+  readonly #csc: CubeSignerClient;
   readonly keyId: string;
   readonly policy?: KeyPolicy;
 
   /** @return {Promise<Key>} The key */
   async getKey(): Promise<Key> {
-    return await Key.getKey(this.#cs, this.#orgId, this.keyId);
+    const keyInfo = await this.#csc.keyGet(this.keyId);
+    return new Key(this.#csc, keyInfo);
   }
 
-  /** Constructor.
-   * @param {CubeSigner} cs The CubeSigner instance to use for signing.
-   * @param {string} orgId The id of the organization to which the key belongs.
+  /**
+   * Constructor.
+   * @param {CubeSignerClient} csc The CubeSigner instance to use for signing.
    * @param {KeyWithPoliciesInfo} keyWithPolicies The key and its policies
    * @internal
-   * */
-  constructor(cs: CubeSigner, orgId: string, keyWithPolicies: KeyWithPoliciesInfo) {
-    this.#cs = cs;
-    this.#orgId = orgId;
+   */
+  constructor(csc: CubeSignerClient, keyWithPolicies: KeyWithPoliciesInfo) {
+    this.#csc = csc;
     this.keyId = keyWithPolicies.key_id;
     this.policy = keyWithPolicies.policy as unknown as KeyPolicy;
   }
@@ -145,20 +153,20 @@ export class KeyWithPolicies {
 
 /** Roles. */
 export class Role {
-  readonly #cs: CubeSigner;
-  readonly #orgId: string;
+  readonly #csc: CubeSignerClient;
+
   /** Human-readable name for the role */
   public readonly name?: string;
 
   /**
    * The ID of the role.
    * @example Role#bfe3eccb-731e-430d-b1e5-ac1363e6b06b
-   * */
+   */
   readonly id: string;
 
   /** Delete the role. */
   async delete(): Promise<void> {
-    await Role.deleteRole(this.#cs, this.#orgId, this.id);
+    await this.#csc.roleDelete(this.id);
   }
 
   /** Is the role enabled? */
@@ -177,222 +185,143 @@ export class Role {
     await this.update({ enabled: false });
   }
 
-  /** The list of users with access to the role.
+  /**
+   * The list of all users with access to the role.
    * @example [
    *   "User#c3b9379c-4e8c-4216-bd0a-65ace53cf98f",
    *   "User#5593c25b-52e2-4fb5-b39b-96d41d681d82"
    * ]
-   * */
-  async users(): Promise<string[]> {
-    const data = await this.fetch();
-    return data.users || [];
+   *
+   * @param {PageOpts} page Optional pagination options; by default, retrieves all users.
+   */
+  async users(page?: PageOpts): Promise<string[]> {
+    const users = await this.#csc.roleUsersList(this.id, page).fetch();
+    return (users || []).map((u) => u.user_id);
   }
 
-  /** Add a user to the role.
-   * Adds an existing user to an existing role.
+  /**
+   * Add an existing user to an existing role.
+   *
    * @param {string} userId The user-id of the user to add to the role.
-   * */
+   */
   async addUser(userId: string) {
-    const resp = await (
-      await this.#cs.management()
-    ).put("/v0/org/{org_id}/roles/{role_id}/add_user/{user_id}", {
-      params: { path: { org_id: this.#orgId, role_id: this.id, user_id: userId } },
-      parseAs: "json",
-    });
-    assertOk(resp, "Failed to add user to role");
+    await this.#csc.roleUserAdd(this.id, userId);
   }
 
-  /** The list of keys in the role.
+  /**
+   * The list of keys in the role.
    * @example [
    *    {
    *     id: "Key#bfe3eccb-731e-430d-b1e5-ac1363e6b06b",
    *     policy: { TxReceiver: "0x8c594691c0e592ffa21f153a16ae41db5befcaaa" }
    *    },
    *  ]
-   * */
-  async keys(): Promise<KeyWithPolicies[]> {
-    const data = await this.fetch();
-    return (data.keys || []).map((k) => new KeyWithPolicies(this.#cs, this.#orgId, k));
+   *
+   * @param {PageOpts} page Optional pagination options; by default, retrieves all keys in this role.
+   */
+  async keys(page?: PageOpts): Promise<KeyWithPolicies[]> {
+    const keysInRole = await this.#csc.roleKeysList(this.id, page).fetch();
+    return keysInRole.map((k) => new KeyWithPolicies(this.#csc, k));
   }
 
-  /** Add keys to the role.
-   * Adds a list of existing keys to an existing role.
+  /**
+   * Add a list of existing keys to an existing role.
+   *
    * @param {Key[]} keys The list of keys to add to the role.
    * @param {KeyPolicy?} policy The optional policy to apply to each key.
-   * */
+   */
   async addKeys(keys: Key[], policy?: KeyPolicy) {
-    const resp = await (
-      await this.#cs.management()
-    ).put("/v0/org/{org_id}/roles/{role_id}/add_keys", {
-      params: { path: { org_id: this.#orgId, role_id: this.id } },
-      body: {
-        key_ids: keys.map((k) => k.id),
-        policy: (policy ?? null) as Record<string, never>[] | null,
-      },
-      parseAs: "json",
-    });
-    assertOk(resp, "Failed to add keys to role");
+    await this.#csc.roleKeysAdd(
+      this.id,
+      keys.map((k) => k.id),
+      policy,
+    );
   }
 
-  /** Add a key to the role.
-   * Adds an existing key to an existing role.
+  /**
+   * Add an existing key to an existing role.
+   *
    * @param {Key} key The key to add to the role.
    * @param {KeyPolicy?} policy The optional policy to apply to the key.
-   * */
+   */
   async addKey(key: Key, policy?: KeyPolicy) {
-    return await this.addKeys([key], policy);
+    await this.addKeys([key], policy);
   }
 
-  /** Remove key from the role.
-   * Removes an existing key from an existing role.
+  /**
+   * Remove an existing key from an existing role.
+   *
    * @param {Key} key The key to remove from the role.
-   * */
+   */
   async removeKey(key: Key) {
-    const resp = await (
-      await this.#cs.management()
-    ).del("/v0/org/{org_id}/roles/{role_id}/keys/{key_id}", {
-      params: { path: { org_id: this.#orgId, role_id: this.id, key_id: key.id } },
-      parseAs: "json",
-    });
-    assertOk(resp, "Failed to remove key from role");
+    await this.#csc.roleKeysRemove(this.id, key.id);
   }
 
   /**
    * Create a new session for this role.
    * @param {SignerSessionStorage} storage The session storage to use
    * @param {string} purpose Descriptive purpose.
-   * @param {SignerSessionLifetime} ttl Optional session lifetimes.
+   * @param {SignerSessionLifetime} lifetimes Optional session lifetimes.
+   * @param {string[]} scopes Session scopes. Only `sign:*` scopes are allowed.
    * @return {Promise<SignerSession>} New signer session.
    */
   async createSession(
     storage: SignerSessionStorage,
     purpose: string,
-    ttl?: SignerSessionLifetime,
+    lifetimes?: SignerSessionLifetime,
+    scopes?: string[],
   ): Promise<SignerSession> {
-    const manager = await SignerSessionManager.create(
-      this.#cs,
-      storage,
-      this.#orgId,
-      this.id,
-      purpose,
-      ttl,
-    );
+    const sessionData = await this.#csc.sessionCreateForRole(this.id, purpose, scopes, lifetimes);
+    await storage.save(sessionData);
+    const manager = await SignerSessionManager.loadFromStorage(storage);
     return new SignerSession(manager);
   }
 
   /**
    * List all signer sessions for this role. Returned objects can be used to
    * revoke individual sessions, but they cannot be used for authentication.
+   *
+   * @param {PageOpts} page Optional pagination options; by default, retrieves all sessions.
    * @return {Promise<SignerSessionInfo[]>} Signer sessions for this role.
    */
-  async sessions(): Promise<SignerSessionInfo[]> {
-    const resp = await (
-      await this.#cs.management()
-    ).get("/v0/org/{org_id}/roles/{role_id}/tokens", {
-      params: { path: { org_id: this.#orgId, role_id: this.id } },
-    });
-    const data = assertOk(resp);
-    return data.tokens.map(
-      (t) => new SignerSessionInfo(this.#cs, this.#orgId, this.id, t.hash, t.purpose),
-    );
+  async sessions(page?: PageOpts): Promise<SignerSessionInfo[]> {
+    const sessions = await this.#csc.sessionsList(this.id, page).fetch();
+    return sessions.map((t) => new SignerSessionInfo(this.#csc, t.session_id, t.purpose));
   }
 
   // --------------------------------------------------------------------------
   // -- INTERNAL --------------------------------------------------------------
   // --------------------------------------------------------------------------
 
-  /** Create a new role.
-   * @param {CubeSigner} cs The CubeSigner instance to use for signing.
-   * @param {string} orgId The id of the organization to which the role belongs.
+  /**
+   * Constructor.
+   * @param {CubeSignerClient} csc The CubeSigner instance to use for signing.
    * @param {RoleInfo} data The JSON response from the API server.
    * @internal
-   * */
-  constructor(cs: CubeSigner, orgId: string, data: RoleInfo) {
-    this.#cs = cs;
-    this.#orgId = orgId;
+   */
+  constructor(csc: CubeSignerClient, data: RoleInfo) {
+    this.#csc = csc;
     this.id = data.role_id;
     this.name = data.name ?? undefined;
   }
 
-  /** Update the role.
+  /**
+   * Update the role.
+   *
    * @param {UpdateRoleRequest} request The JSON request to send to the API server.
-   * */
-  private async update(request: UpdateRoleRequest): Promise<void> {
-    const resp = await (
-      await this.#cs.management()
-    ).patch("/v0/org/{org_id}/roles/{role_id}", {
-      params: { path: { org_id: this.#orgId, role_id: this.id } },
-      body: request,
-      parseAs: "json",
-    });
-    assertOk(resp);
-  }
-
-  /** Create new role.
-   * @param {CubeSigner} cs The CubeSigner instance to use for signing.
-   * @param {string} orgId The id of the organization to which the role belongs.
-   * @param {string?} name The optional name of the role.
-   * @return {Role} The new role.
-   * @internal
-   * */
-  static async createRole(cs: CubeSigner, orgId: string, name?: string): Promise<Role> {
-    const resp = await (
-      await cs.management()
-    ).post("/v0/org/{org_id}/roles", {
-      params: { path: { org_id: orgId } },
-      body: name ? { name } : undefined,
-      parseAs: "json",
-    });
-    const data = assertOk(resp);
-    return await Role.getRole(cs, orgId, data.role_id);
-  }
-
-  /** Get a role by id.
-   * @param {CubeSigner} cs The CubeSigner instance to use for signing.
-   * @param {string} orgId The id of the organization to which the role belongs.
-   * @param {string} roleId The id of the role to get.
-   * @return {Role} The role.
-   * @internal
-   * */
-  static async getRole(cs: CubeSigner, orgId: string, roleId: string): Promise<Role> {
-    const resp = await (
-      await cs.management()
-    ).get("/v0/org/{org_id}/roles/{role_id}", {
-      params: { path: { org_id: orgId, role_id: roleId } },
-      parseAs: "json",
-    });
-    const data = assertOk(resp);
-    return new Role(cs, orgId, data);
+   * @return {Promise<RoleInfo>} The updated role information.
+   */
+  private async update(request: UpdateRoleRequest): Promise<RoleInfo> {
+    return await this.#csc.roleUpdate(this.id, request);
   }
 
-  /** Fetches the role information.
+  /**
+   * Fetches the role information.
+   *
    * @return {RoleInfo} The role information.
    * @internal
-   * */
+   */
   private async fetch(): Promise<RoleInfo> {
-    const resp = await (
-      await this.#cs.management()
-    ).get("/v0/org/{org_id}/roles/{role_id}", {
-      params: { path: { org_id: this.#orgId, role_id: this.id } },
-      parseAs: "json",
-    });
-    const data = assertOk(resp);
-    return data;
-  }
-
-  /** Delete role.
-   * @param {CubeSigner} cs The CubeSigner instance to use for signing.
-   * @param {string} orgId The id of the organization to which the role belongs.
-   * @param {string} roleId The id of the role to delete.
-   * @internal
-   * */
-  private static async deleteRole(cs: CubeSigner, orgId: string, roleId: string): Promise<void> {
-    const resp = await (
-      await cs.management()
-    ).del("/v0/org/{org_id}/roles/{role_id}", {
-      params: { path: { org_id: orgId, role_id: roleId } },
-      parseAs: "json",
-    });
-    assertOk(resp);
+    return await this.#csc.roleGet(this.id);
   }
 }