@cubist-labs/cubesigner-sdk 0.1.26 → 0.1.77

package/src/key.ts

@@ -7,10 +7,12 @@ export enum Secp256k1 {
   Evm = "SecpEthAddr", // eslint-disable-line no-unused-vars
   Btc = "SecpBtc", // eslint-disable-line no-unused-vars
   BtcTest = "SecpBtcTest", // eslint-disable-line no-unused-vars
+  Ava = "SecpAvaAddr", // eslint-disable-line no-unused-vars
+  AvaTest = "SecpAvaTestAddr", // eslint-disable-line no-unused-vars
 }
 
 /** BLS key type */
-export enum BLS {
+export enum Bls {
   Eth2Deposited = "BlsPub", // eslint-disable-line no-unused-vars
   Eth2Inactive = "BlsInactive", // eslint-disable-line no-unused-vars
 }
@@ -20,16 +22,56 @@ export enum Ed25519 {
   Solana = "Ed25519SolanaAddr", // eslint-disable-line no-unused-vars
   Sui = "Ed25519SuiAddr", // eslint-disable-line no-unused-vars
   Aptos = "Ed25519AptosAddr", // eslint-disable-line no-unused-vars
+  Cardano = "Ed25519CardanoAddrVk", // eslint-disable-line no-unused-vars
+  Stellar = "Ed25519StellarAddr", // eslint-disable-line no-unused-vars
 }
 
+/** Mnemonic key type */
+export const Mnemonic = "Mnemonic" as const;
+export type Mnemonic = typeof Mnemonic;
+
+/** Stark key type */
+export const Stark = "Stark" as const;
+export type Stark = typeof Stark;
+
 /** Key type */
-export type KeyType = Secp256k1 | BLS | Ed25519;
+export type KeyType = Secp256k1 | Bls | Ed25519 | Mnemonic | Stark;
 
 /** Schema key type (i.e., key type at the API level) */
 type SchemaKeyType = components["schemas"]["KeyType"];
 
 type UpdateKeyRequest = components["schemas"]["UpdateKeyRequest"];
-type KeyInfo = components["schemas"]["KeyInfo"];
+type KeyInfoApi = components["schemas"]["KeyInfo"];
+type KeyTypeApi = components["schemas"]["KeyType"];
+
+/** Additional properties (for backward compatibility) */
+export interface KeyInfo extends KeyInfoApi {
+  /** Alias for key_id */
+  id: string;
+  /** Alias for key_type */
+  type: KeyTypeApi;
+  /** Alias for material_id */
+  materialId: string;
+  /** Alias for public_key */
+  publicKey: string;
+}
+
+/**
+ * Define some additional (backward compatibility) properties
+ * on a `KeyInfoApi` object returned from the remote end.
+ *
+ * @param {KeyInfoApi} key Key information returned from the remote end
+ * @return {KeyInfo} The same `key` object extended with some derived properties.
+ */
+export function toKeyInfo(key: KeyInfoApi): KeyInfo {
+  return {
+    ...key,
+    id: key.key_id,
+    type: key.key_type,
+    publicKey: key.public_key,
+    materialId: key.material_id,
+  };
+}
 
 /** Signing keys. */
 export class Key {
@@ -44,9 +86,6 @@ export class Key {
    * */
   readonly id: string;
 
-  /** The type of key. */
-  readonly type: KeyType;
-
   /**
    * A unique identifier specific to the type of key, such as a public key or an ethereum address
    * @example 0x8e3484687e66cdd26cf04c3647633ab4f3570148
@@ -61,6 +100,12 @@ export class Key {
    * */
   readonly publicKey: string;
 
+  /** The type of key. */
+  async type(): Promise<KeyType> {
+    const data = await this.fetch();
+    return fromSchemaKeyType(data.key_type);
+  }
+
   /** Is the key enabled? */
   async enabled(): Promise<boolean> {
     const data = await this.fetch();
@@ -119,6 +164,13 @@ export class Key {
     await this.update({ owner });
   }
 
+  /**
+   * Delete this key.
+   */
+  async delete() {
+    await this.#cs.deleteKey(this.orgId, this.id);
+  }
+
   // --------------------------------------------------------------------------
   // -- INTERNAL --------------------------------------------------------------
   // --------------------------------------------------------------------------
@@ -129,11 +181,10 @@ export class Key {
    * @param {KeyInfo} data The JSON response from the API server.
    * @internal
    * */
-  constructor(cs: CubeSigner, orgId: string, data: KeyInfo) {
+  constructor(cs: CubeSigner, orgId: string, data: KeyInfoApi) {
     this.#cs = cs;
     this.orgId = orgId;
     this.id = data.key_id;
-    this.type = fromSchemaKeyType(data.key_type);
     this.materialId = data.material_id;
     this.publicKey = data.public_key;
   }
@@ -150,7 +201,7 @@ export class Key {
       body: request,
       parseAs: "json",
     });
-    return assertOk(resp);
+    return toKeyInfo(assertOk(resp));
   }
 
   /** Create new signing keys.
@@ -183,7 +234,42 @@ export class Key {
       parseAs: "json",
     });
     const data = assertOk(resp);
-    return data.keys.map((k: KeyInfo) => new Key(cs, orgId, k));
+    return data.keys.map((k) => new Key(cs, orgId, k));
+  }
+
+  /**
+   * Derives a key of a specified type using a supplied derivation path and an existing long-lived mnemonic.
+   *
+   * The owner of the derived key will be the owner of the mnemonic.
+   *
+   * @param {CubeSigner} cs The CubeSigner instance to use for key creation.
+   * @param {string} orgId The id of the organization to which the key belongs.
+   * @param {KeyType} keyType The type of key to create.
+   * @param {string[]} derivationPaths Derivation paths from which to derive new keys.
+   * @param {string} mnemonicId materialId of mnemonic key used to derive the new key.
+   *
+   * @return {Key[]} The newly derived keys.
+   */
+  static async deriveKeys(
+    cs: CubeSigner,
+    orgId: string,
+    keyType: KeyType,
+    derivationPaths: string[],
+    mnemonicId: string,
+  ): Promise<Key[]> {
+    const resp = await (
+      await cs.management()
+    ).put("/v0/org/{org_id}/derive_key", {
+      params: { path: { org_id: orgId } },
+      body: {
+        derivation_path: derivationPaths,
+        mnemonic_id: mnemonicId,
+        key_type: keyType,
+      },
+      parseAs: "json",
+    });
+    const data = assertOk(resp);
+    return data.keys.map((k) => new Key(cs, orgId, k));
   }
 
   /** Get a key by id.
@@ -216,7 +302,7 @@ export class Key {
       parseAs: "json",
     });
     const data = assertOk(resp);
-    return data;
+    return toKeyInfo(data);
   }
 }
 
@@ -225,7 +311,7 @@ export class Key {
  * @return {KeyType} The key type.
  * @internal
  * */
-function fromSchemaKeyType(ty: SchemaKeyType): KeyType {
+export function fromSchemaKeyType(ty: SchemaKeyType): KeyType {
   switch (ty) {
     case "SecpEthAddr":
       return Secp256k1.Evm;
@@ -233,17 +319,27 @@ function fromSchemaKeyType(ty: SchemaKeyType): KeyType {
       return Secp256k1.Btc;
     case "SecpBtcTest":
       return Secp256k1.BtcTest;
+    case "SecpAvaAddr":
+      return Secp256k1.Ava;
+    case "SecpAvaTestAddr":
+      return Secp256k1.AvaTest;
     case "BlsPub":
-      return BLS.Eth2Deposited;
+      return Bls.Eth2Deposited;
     case "BlsInactive":
-      return BLS.Eth2Inactive;
+      return Bls.Eth2Inactive;
     case "Ed25519SolanaAddr":
       return Ed25519.Solana;
     case "Ed25519SuiAddr":
       return Ed25519.Sui;
     case "Ed25519AptosAddr":
       return Ed25519.Aptos;
-    default:
-      throw new Error(`Unknown key type: ${ty}`);
+    case "Ed25519CardanoAddrVk":
+      return Ed25519.Cardano;
+    case "Ed25519StellarAddr":
+      return Ed25519.Stellar;
+    case "Stark":
+      return Stark;
+    case "Mnemonic":
+      return Mnemonic;
   }
 }

package/src/org.ts

@@ -1,14 +1,34 @@
-import { CubeSigner, KeyInfo, MfaRequestInfo } from ".";
+import {
+  CubeSigner,
+  MfaRequestInfo,
+  IdentityProof,
+  PageOpts,
+  Page,
+  PageQueryArgs,
+  Paginator,
+} from ".";
 import { components, paths } from "./client";
 import { assertOk } from "./util";
 import { KeyType, Key } from "./key";
-import { Role, RoleInfo } from "./role";
+import { MfaPolicy, Role, RoleInfo } from "./role";
 
 /** Organization id */
 export type OrgId = string;
 
 /** Org-wide policy */
-export type OrgPolicy = SourceIpAllowlistPolicy | OriginAllowlistPolicy | MaxDailyUnstakePolicy;
+export type OrgPolicy =
+  | SourceIpAllowlistPolicy
+  | OidcAuthSourcesPolicy
+  | OriginAllowlistPolicy
+  | MaxDailyUnstakePolicy;
+
+/**
+ * Provides an allowlist of OIDC Issuers and audiences that are allowed to authenticate into this org.
+ * @example {"OidcAuthSources": { "https://accounts.google.com": [ "1234.apps.googleusercontent.com" ]}}
+ */
+export interface OidcAuthSourcesPolicy {
+  OidcAuthSources: Record<string, string[]>;
+}
 
 /**
  * Only allow requests from the specified origins.
@@ -44,6 +64,14 @@ type UpdateOrgResponse =
 export type OidcIdentity = components["schemas"]["OIDCIdentity"];
 export type MemberRole = components["schemas"]["MemberRole"];
 
+/** Options for a new OIDC user */
+export interface CreateOidcUserOptions {
+  /** The role of an OIDC user, default is "Alien" */
+  memberRole?: MemberRole;
+  /** Optional MFA policy to associate with the user account */
+  mfaPolicy?: MfaPolicy;
+}
+
 /** An organization. */
 export class Org {
   readonly #cs: CubeSigner;
@@ -127,6 +155,35 @@ export class Org {
     return Key.createKeys(this.#cs, this.id, type, count, ownerId);
   }
 
+  /**
+   * Derives a key of the given type using the given derivation path and mnemonic.
+   * The owner of the derived key will be the owner of the mnemonic.
+   *
+   * @param {KeyType} type Type of key to derive from the mnemonic.
+   * @param {string} derivationPath Mnemonic derivation path used to generate new key.
+   * @param {string} mnemonicId materialId of mnemonic key used to derive the new key.
+   *
+   * @return {Key} newly derived key.
+   */
+  async deriveKey(type: KeyType, derivationPath: string, mnemonicId: string): Promise<Key> {
+    return (await Key.deriveKeys(this.#cs, this.id, type, [derivationPath], mnemonicId))[0];
+  }
+
+  /**
+   * Derives a set of keys of the given type using the given derivation paths and mnemonic.
+   *
+   * The owner of the derived keys will be the owner of the mnemonic.
+   *
+   * @param {KeyType} type Type of key to derive from the mnemonic.
+   * @param {string[]} derivationPaths Mnemonic derivation paths used to generate new key.
+   * @param {string} mnemonicId materialId of mnemonic key used to derive the new key.
+   *
+   * @return {Key[]} newly derived keys.
+   */
+  async deriveKeys(type: KeyType, derivationPaths: string[], mnemonicId: string): Promise<Key[]> {
+    return await Key.deriveKeys(this.#cs, this.#id, type, derivationPaths, mnemonicId);
+  }
+
   /**
    * Create a new user in the organization and sends an invitation to that user
    * @param {string} email Email of the user
@@ -150,23 +207,54 @@ export class Org {
   /**
    * Create a new OIDC user
    * @param {OidcIdentity} identity The identity of the OIDC user
-   * @param {MemberRole} memberRole The type of membership of the new user
+   * @param {string} email Email of the OIDC user
+   * @param {CreateOidcUserOptions} opts Additional options for new OIDC users
    * @return {string} User id of the new user
    */
-  async createOidcUser(identity: OidcIdentity, memberRole: MemberRole): Promise<string> {
+  async createOidcUser(
+    identity: OidcIdentity,
+    email: string,
+    opts: CreateOidcUserOptions = {},
+  ): Promise<string> {
     const resp = await (
       await this.#cs.management()
     ).post("/v0/org/{org_id}/users", {
       params: { path: { org_id: this.id } },
       body: {
         identity,
-        role: memberRole,
+        role: opts.memberRole ?? "Alien",
+        email: email,
+        mfa_policy: opts.mfaPolicy ?? null,
       },
       parseAs: "json",
     });
     return assertOk(resp).user_id;
   }
 
+  /**
+   * Delete an existing OIDC user
+   * @param {OidcIdentity} identity The identity of the OIDC user
+   */
+  async deleteOidcUser(identity: OidcIdentity) {
+    const resp = await (
+      await this.#cs.management()
+    ).del("/v0/org/{org_id}/users/oidc", {
+      params: { path: { org_id: this.id } },
+      body: identity,
+      parseAs: "json",
+    });
+    return assertOk(resp);
+  }
+
+  /**
+   * Checks if a given proof of OIDC authentication is valid.
+   *
+   * @param {IdentityProof} proof The proof of authentication.
+   */
+  async verifyIdentity(proof: IdentityProof) {
+    await this.#cs.verifyIdentity(this.id, proof);
+  }
+
   /**
    * List users in the organization
    * @return {UserIdInfo[]} List of users
@@ -191,20 +279,33 @@ export class Org {
 
   /** Get all keys in the org.
    * @param {KeyType?} type Optional key type to filter list for.
+   * @param {PageOpts} page Pagination options. Defaults to fetching the entire result set.
    * @return {Key} The key.
    * */
-  async keys(type?: KeyType): Promise<Key[]> {
-    const resp = await (
-      await this.#cs.management()
-    ).get("/v0/org/{org_id}/keys", {
-      params: {
-        path: { org_id: this.id },
-        query: type ? { key_type: type } : undefined,
-      },
-      parseAs: "json",
-    });
-    const data = assertOk(resp);
-    return data.keys.map((k: KeyInfo) => new Key(this.#cs, this.id, k));
+  async keys(type?: KeyType, page?: PageOpts): Promise<Key[]> {
+    page ??= Page.default();
+    const listFn = async (query: PageQueryArgs) => {
+      const client = await this.#cs.management();
+      const resp = await client.get("/v0/org/{org_id}/keys", {
+        params: {
+          path: { org_id: this.id },
+          query: {
+            key_type: type,
+            ...query,
+          },
+        },
+        parseAs: "json",
+      });
+      return assertOk(resp);
+    };
+    const p = new Paginator(
+      page,
+      listFn,
+      (r) => r.keys,
+      (r) => r.last_evaluated_key,
+    );
+    const keys = await p.fetch();
+    return keys.map((k) => new Key(this.#cs, this.id, k));
   }
 
   /** Create a new role.
@@ -223,25 +324,32 @@ export class Org {
     return Role.getRole(this.#cs, this.id, roleId);
   }
 
-  /** List all roles in the org..
+  /**
+   * List all roles in the org.
+   *
+   * @param {PageOpts} page Pagination options. Defaults to fetching the entire result set.
    * @return {Role[]} The roles.
    * */
-  async list(): Promise<Role[]> {
-    return Org.roles(this.#cs, this.id);
+  async listRoles(page?: PageOpts): Promise<Role[]> {
+    return Org.roles(this.#cs, this.id, page);
+  }
+
+  /** List all users in the org.
+   * @return {User[]} The users.
+   * */
+  async listUsers(): Promise<UserIdInfo[]> {
+    return Org.users(this.#cs, this.id);
   }
 
   /**
    * Get a pending MFA request by its id.
    * @param {string} mfaId The id of the MFA request.
    * @return {Promise<MfaRequestInfo>} The MFA request.
+   *
+   * @deprecated Use {@link getMfaInfo()} instead.
    */
   async mfaGet(mfaId: string): Promise<MfaRequestInfo> {
-    const resp = await (
-      await this.#cs.management()
-    ).get("/v0/org/{org_id}/mfa/{mfa_id}", {
-      params: { path: { org_id: this.#id, mfa_id: mfaId } },
-    });
-    return assertOk(resp);
+    return await this.getMfaInfo(mfaId);
   }
 
   /**
@@ -249,8 +357,37 @@ export class Org {
    *
    * @param {string} mfaId The id of the MFA request.
    * @return {Promise<MfaRequestInfo>} The MFA request.
+   *
+   * @deprecated Use {@link approveMfaRequest()} instead.
    */
   async mfaApprove(mfaId: string): Promise<MfaRequestInfo> {
+    return await this.approveMfaRequest(mfaId);
+  }
+
+  /**
+   * Get a pending MFA request by its id.
+   * @param {string} mfaId The id of the MFA request.
+   * @return {Promise<MfaRequestInfo>} The MFA request.
+   */
+  async getMfaInfo(mfaId: string): Promise<MfaRequestInfo> {
+    return await this.#cs.mfaGet(this.id, mfaId);
+  }
+
+  /**
+   * List pending MFA requests accessible to the current user.
+   * @return {Promise<MfaRequestInfo[]>} The MFA requests.
+   */
+  async listMfaInfos(): Promise<MfaRequestInfo[]> {
+    return await this.#cs.mfaList(this.id);
+  }
+
+  /**
+   * Approve a pending MFA request.
+   *
+   * @param {string} mfaId The id of the MFA request.
+   * @return {Promise<MfaRequestInfo>} The MFA request.
+   */
+  async approveMfaRequest(mfaId: string): Promise<MfaRequestInfo> {
     return Org.mfaApprove(this.#cs, this.#id, mfaId);
   }
 
@@ -277,12 +414,7 @@ export class Org {
    * @return {Promise<MfaRequestInfo>} The result of the MFA request
    */
   static async mfaApprove(cs: CubeSigner, orgId: string, mfaId: string): Promise<MfaRequestInfo> {
-    const resp = await (
-      await cs.management()
-    ).patch("/v0/org/{org_id}/mfa/{mfa_id}", {
-      params: { path: { org_id: orgId, mfa_id: mfaId } },
-    });
-    return assertOk(resp);
+    return await cs.mfaApprove(orgId, mfaId);
   }
 
   /** Fetch org info.
@@ -317,17 +449,48 @@ export class Org {
   /** List roles.
    * @param {CubeSigner} cs The CubeSigner instance to use for signing.
    * @param {string} orgId The id of the organization to which the role belongs.
-   * @return {Role} The role.
+   * @param {PageOpts} page Pagination options. Defaults to fetching the entire result set.
+   * @return {Role[]} Org roles.
+   * @internal
+   * */
+  private static async roles(cs: CubeSigner, orgId: string, page?: PageOpts): Promise<Role[]> {
+    page ??= Page.default();
+    const listFn = async (query: PageQueryArgs) => {
+      const resp = await (
+        await cs.management()
+      ).get("/v0/org/{org_id}/roles", {
+        params: {
+          path: { org_id: orgId },
+          query,
+        },
+        parseAs: "json",
+      });
+      return assertOk(resp);
+    };
+    const p = new Paginator(
+      page,
+      listFn,
+      (u) => u.roles,
+      (u) => u.last_evaluated_key,
+    );
+    const roles = await p.fetch();
+    return roles.map((r: RoleInfo) => new Role(cs, orgId, r));
+  }
+
+  /** List users.
+   * @param {CubeSigner} cs The CubeSigner instance to use for signing.
+   * @param {string} orgId The id of the organization to which the role belongs.
+   * @return {User[]} Org users.
    * @internal
    * */
-  private static async roles(cs: CubeSigner, orgId: string): Promise<Role[]> {
+  private static async users(cs: CubeSigner, orgId: string): Promise<UserIdInfo[]> {
     const resp = await (
       await cs.management()
-    ).get("/v0/org/{org_id}/roles", {
+    ).get("/v0/org/{org_id}/users", {
       params: { path: { org_id: orgId } },
       parseAs: "json",
     });
     const data = assertOk(resp);
-    return data.roles.map((r: RoleInfo) => new Role(cs, orgId, r));
+    return data.users;
   }
 }

package/src/paginator.ts

@@ -0,0 +1,122 @@
+/** Pagination options. */
+export interface PageOpts {
+  /** Max number of items per page. */
+  size?: number;
+  /**
+   * Starting point (i.e., 'last_evaluated_key' from the previous page).
+   * Omit to start from the beginning.
+   */
+  start?: string;
+  /** Iterate until retrieving the entire result set. */
+  all: boolean;
+}
+
+/** Static constructors for `IPage` */
+export class Page {
+  /**
+   * The default is to fetch the entire result set
+   * (by repeatedly calling the remote endpoint until all pages are retrieved).
+   *
+   * @return {PageOpts} Pagination options.
+   */
+  static default(): PageOpts {
+    return <PageOpts>{
+      all: true,
+    };
+  }
+}
+
+export interface PageQueryArgs {
+  /**
+   * Max number of items to return per page.
+   *
+   * 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;
+
+  /**
+   * The start of the page.
+   *
+   * Omit to start from the beginning; otherwise, only specify the exact
+   * value previously returned as 'last_evaluated_key' from the same endpoint.
+   */
+  "page.start"?: string | null;
+}
+
+export type ListFn<U> = (pageQueryArgs: PageQueryArgs) => Promise<U>;
+export type ItemsFn<U, T> = (resp: U) => T[];
+export type LastFn<U> = (resp: U) => string | null | undefined;
+
+/**
+ * Helper class for fetching paginated results.
+ */
+export class Paginator<U, T> {
+  readonly #listFn: ListFn<U>;
+  readonly #itemsFn: ItemsFn<U, T>;
+  readonly #lastFn: LastFn<U>;
+  #opts: PageOpts;
+  #last: string | null | undefined;
+  #done: boolean;
+
+  /**
+   * @param {PageOpts} pageOpts Pagination options
+   * @param {ListFn<U>} listFn Calls a remote endpoint that returns a paginated response
+   * @param {ItemsFn<U, T>} itemsFn Extracts items from the paginated response
+   * @param {LastFn<U>} lastFn Extracts the last evaluated key from the paginated response
+   */
+  constructor(pageOpts: PageOpts, listFn: ListFn<U>, itemsFn: ItemsFn<U, T>, lastFn: LastFn<U>) {
+    this.#listFn = listFn;
+    this.#itemsFn = itemsFn;
+    this.#lastFn = lastFn;
+    this.#opts = pageOpts;
+    this.#last = pageOpts.start;
+    this.#done = false;
+  }
+
+  /**
+   * Fetches either a single page or the entire result set, depending on
+   * the `all` property of the pagination options.
+   *
+   * @return {Promise<T[]>} A single page or the entire result set.
+   */
+  async fetch(): Promise<T[]> {
+    return this.#opts.all ? await this.fetchAll() : await this.fetchPage();
+  }
+
+  /**
+   * Fetches a single page of the result set from where it previously left off.
+   * Mutates self to remember where it left off.
+   *
+   * @return {Promise<T[]>} The next page of the result set.
+   */
+  async fetchPage(): Promise<T[]> {
+    if (this.#done) {
+      return [];
+    }
+
+    const resp = await this.#listFn({
+      "page.size": this.#opts.size,
+      "page.start": this.#last,
+    });
+    this.#last = this.#lastFn(resp);
+    this.#done = !this.#last;
+    return this.#itemsFn(resp);
+  }
+
+  /**
+   * Fetches the entire result set starting from where it previously left off
+   * by iterating through the pages returned by the remote end.
+   *
+   * @return {Promise<T[]>} The entire result set.
+   */
+  async fetchAll(): Promise<T[]> {
+    const result = [];
+    while (!this.#done) {
+      const items = await this.fetchPage();
+      result.push(...items);
+    }
+    return result;
+  }
+}