@cubist-labs/cubesigner-sdk 0.1.77 → 0.2.2

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;
@@ -93,7 +98,9 @@ export type RequireMfa = {
 export const AllowRawBlobSigning = "AllowRawBlobSigning" as const;
 export type AllowRawBlobSigning = typeof AllowRawBlobSigning;
 
-/** Key policy
+/**
+ * Key policy
+ *
  * @example [
  *   {
  *     "TxReceiver": "0x8c594691c0e592ffa21f153a16ae41db5befcaaa"
@@ -114,30 +121,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,8 +151,8 @@ 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;
 
@@ -158,7 +164,7 @@ export class Role {
 
   /** 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 +183,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);
   }
 }