@cubist-labs/cubesigner-sdk 0.1.23

package/src/key.ts

@@ -0,0 +1,249 @@
+import { CubeSigner, KeyPolicy } from ".";
+import { components } from "./client";
+import { assertOk } from "./util";
+
+/** Secp256k1 key type */
+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
+}
+
+/** BLS key type */
+export enum BLS {
+  Eth2Deposited = "BlsPub", // eslint-disable-line no-unused-vars
+  Eth2Inactive = "BlsInactive", // eslint-disable-line no-unused-vars
+}
+
+/** Ed25519 key type */
+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
+}
+
+/** Key type */
+export type KeyType = Secp256k1 | BLS | Ed25519;
+
+/** 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"];
+
+/** Signing keys. */
+export class Key {
+  /** The CubeSigner instance that this key is associated with */
+  readonly #cs: CubeSigner;
+  /** The organization that this key is in */
+  readonly orgId: string;
+  /**
+   * The id of the key: "Key#" followed by a unique identifier specific to
+   * the type of key (such as a public key for BLS or an ethereum address for Secp)
+   * @example Key#0x8e3484687e66cdd26cf04c3647633ab4f3570148
+   * */
+  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
+   * */
+  readonly materialId: string;
+
+  /**
+   * @description Hex-encoded, serialized public key. The format used depends on the key type:
+   * - secp256k1 keys use 65-byte uncompressed SECG format
+   * - BLS keys use 48-byte compressed BLS12-381 (ZCash) format
+   * @example 0x04d2688b6bc2ce7f9879b9e745f3c4dc177908c5cef0c1b64cff19ae7ff27dee623c64fe9d9c325c7fbbc748bbd5f607ce14dd83e28ebbbb7d3e7f2ffb70a79431
+   * */
+  readonly publicKey: string;
+
+  /** Is the key enabled? */
+  async enabled(): Promise<boolean> {
+    const data = await this.fetch();
+    return data.enabled;
+  }
+
+  /** Enable the key. */
+  async enable() {
+    await this.update({ enabled: true });
+  }
+
+  /** Disable the key. */
+  async disable() {
+    await this.update({ enabled: false });
+  }
+
+  /**
+   * Set new policy (overwriting any policies previously set for this key)
+   * @param {KeyPolicy} policy The new policy to set
+   */
+  async setPolicy(policy: KeyPolicy) {
+    await this.update({ policy: policy as unknown as Record<string, never>[] });
+  }
+
+  /**
+   * Append to existing key policy. This append is not atomic -- it uses {@link policy} to fetch the current policy and then {@link setPolicy} to set the policy -- and should not be used in across concurrent sessions.
+   * @param {KeyPolicy} policy The policy to append to the existing one.
+   */
+  async appendPolicy(policy: KeyPolicy) {
+    const existing = await this.policy();
+    await this.setPolicy([...existing, ...policy]);
+  }
+
+  /**
+   * Get the policy for the org.
+   * @return {Promise<KeyPolicy>} The policy for the org.
+   */
+  async policy(): Promise<KeyPolicy> {
+    const data = await this.fetch();
+    return (data.policy ?? []) as unknown as KeyPolicy;
+  }
+
+  /**
+   * @description Owner of the key
+   * @example User#c3b9379c-4e8c-4216-bd0a-65ace53cf98f
+   * */
+  async owner(): Promise<string> {
+    const data = await this.fetch();
+    return data.owner;
+  }
+
+  /** Set the owner of the key. Only the key (or org) owner can change the owner of the key.
+   * @param {string} owner The user-id of the new owner of the key.
+   * */
+  async setOwner(owner: string) {
+    await this.update({ owner });
+  }
+
+  // --------------------------------------------------------------------------
+  // -- INTERNAL --------------------------------------------------------------
+  // --------------------------------------------------------------------------
+
+  /** Create a new key.
+   * @param {CubeSigner} cs The CubeSigner instance to use for signing.
+   * @param {string} orgId The id of the organization to which the key belongs.
+   * @param {KeyInfo} data The JSON response from the API server.
+   * @internal
+   * */
+  constructor(cs: CubeSigner, orgId: string, data: KeyInfo) {
+    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;
+  }
+
+  /** Update the key.
+   * @param {UpdateKeyRequest} request The JSON request to send to the API server.
+   * @return {KeyInfo} The JSON response from the API server.
+   * */
+  private async update(request: UpdateKeyRequest): Promise<KeyInfo> {
+    const resp = await (
+      await this.#cs.management()
+    ).patch("/v0/org/{org_id}/keys/{key_id}", {
+      params: { path: { org_id: this.orgId, key_id: this.id } },
+      body: request,
+      parseAs: "json",
+    });
+    return assertOk(resp);
+  }
+
+  /** Create new signing keys.
+   * @param {CubeSigner} cs The CubeSigner instance to use for signing.
+   * @param {string} orgId The id of the organization to which the key belongs.
+   * @param {KeyType} keyType The type of key to create.
+   * @param {number} count The number of keys to create.
+   * @param {string?} ownerId The owner of the keys. Defaults to the session's user.
+   * @return {Key[]} The new keys.
+   * @internal
+   * */
+  static async createKeys(
+    cs: CubeSigner,
+    orgId: string,
+    keyType: KeyType,
+    count: number,
+    ownerId?: string,
+  ): Promise<Key[]> {
+    const chain_id = 0; // not used anymore
+    const resp = await (
+      await cs.management()
+    ).post("/v0/org/{org_id}/keys", {
+      params: { path: { org_id: orgId } },
+      body: {
+        count,
+        chain_id,
+        key_type: keyType,
+        owner: ownerId || null,
+      },
+      parseAs: "json",
+    });
+    const data = assertOk(resp);
+    return data.keys.map((k: KeyInfo) => new Key(cs, orgId, k));
+  }
+
+  /** Get a key by id.
+   * @param {CubeSigner} cs The CubeSigner instance to use for signing.
+   * @param {string} orgId The id of the organization to which the key belongs.
+   * @param {string} keyId The id of the key to get.
+   * @return {Key} The key.
+   * @internal
+   * */
+  static async getKey(cs: CubeSigner, orgId: string, keyId: string): Promise<Key> {
+    const resp = await (
+      await cs.management()
+    ).get("/v0/org/{org_id}/keys/{key_id}", {
+      params: { path: { org_id: orgId, key_id: keyId } },
+      parseAs: "json",
+    });
+    const data = assertOk(resp);
+    return new Key(cs, orgId, data);
+  }
+
+  /** Fetches the key information.
+   * @return {KeyInfo} The key information.
+   * @internal
+   * */
+  private async fetch(): Promise<KeyInfo> {
+    const resp = await (
+      await this.#cs.management()
+    ).get("/v0/org/{org_id}/keys/{key_id}", {
+      params: { path: { org_id: this.orgId, key_id: this.id } },
+      parseAs: "json",
+    });
+    const data = assertOk(resp);
+    return data;
+  }
+}
+
+/** Convert a schema key type to a key type.
+ * @param {SchemaKeyType} ty The schema key type.
+ * @return {KeyType} The key type.
+ * @internal
+ * */
+function fromSchemaKeyType(ty: SchemaKeyType): KeyType {
+  switch (ty) {
+    case "SecpEthAddr":
+      return Secp256k1.Evm;
+    case "SecpBtc":
+      return Secp256k1.Btc;
+    case "SecpBtcTest":
+      return Secp256k1.BtcTest;
+    case "BlsPub":
+      return BLS.Eth2Deposited;
+    case "BlsInactive":
+      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}`);
+  }
+}

package/src/org.ts

@@ -0,0 +1,333 @@
+import { CubeSigner, KeyInfo, MfaRequestInfo } from ".";
+import { components, paths } from "./client";
+import { assertOk } from "./util";
+import { KeyType, Key } from "./key";
+import { Role, RoleInfo } from "./role";
+
+/** Organization id */
+export type OrgId = string;
+
+/** Org-wide policy */
+export type OrgPolicy = SourceIpAllowlistPolicy | OriginAllowlistPolicy | MaxDailyUnstakePolicy;
+
+/**
+ * Only allow requests from the specified origins.
+ * @example {"OriginAllowlist": "*"}
+ */
+export interface OriginAllowlistPolicy {
+  OriginAllowlist: string[] | "*";
+}
+
+/**
+ * Restrict signing to specific source IP addresses.
+ * @example {"SourceIpAllowlist": ["10.1.2.3/8", "169.254.17.1/16"]}
+ */
+export interface SourceIpAllowlistPolicy {
+  SourceIpAllowlist: string[];
+}
+
+/**
+ * Restrict the number of unstakes per day.
+ * @example {"MaxDailyUnstake": 5 }
+ */
+export interface MaxDailyUnstakePolicy {
+  MaxDailyUnstake: number;
+}
+
+type OrgInfo = components["schemas"]["OrgInfo"];
+type UserIdInfo = components["schemas"]["UserIdInfo"];
+type UpdateOrgRequest =
+  paths["/v0/org/{org_id}"]["patch"]["requestBody"]["content"]["application/json"];
+type UpdateOrgResponse =
+  paths["/v0/org/{org_id}"]["patch"]["responses"]["200"]["content"]["application/json"];
+
+export type OidcIdentity = components["schemas"]["OIDCIdentity"];
+export type MemberRole = components["schemas"]["MemberRole"];
+
+/** An organization. */
+export class Org {
+  readonly #cs: CubeSigner;
+  /**
+   * The ID of the organization.
+   * @example Org#124dfe3e-3bbd-487d-80c0-53c55e8ab87a
+   */
+  readonly #id: string;
+
+  /**
+   * @description The org id
+   * @example Org#c3b9379c-4e8c-4216-bd0a-65ace53cf98f
+   * */
+  get id(): OrgId {
+    return this.#id;
+  }
+
+  /** Human-readable name for the org */
+  async name(): Promise<string | undefined> {
+    const data = await this.fetch();
+    return data.name ?? undefined;
+  }
+
+  /** Set the human-readable name for the org.
+   * @param {string} name The new human-readable name for the org (must be alphanumeric).
+   * @example my_org_name
+   * */
+  async setName(name: string) {
+    if (!/^[a-zA-Z0-9_]{3,30}$/.test(name)) {
+      throw new Error("Org name must be alphanumeric and between 3 and 30 characters");
+    }
+    await this.update({ name });
+  }
+
+  /** Is the org enabled? */
+  async enabled(): Promise<boolean> {
+    const data = await this.fetch();
+    return data.enabled;
+  }
+
+  /** Enable the org. */
+  async enable() {
+    await this.update({ enabled: true });
+  }
+
+  /** Disable the org. */
+  async disable() {
+    await this.update({ enabled: false });
+  }
+
+  /** Get the policy for the org. */
+  async policy(): Promise<OrgPolicy[]> {
+    const data = await this.fetch();
+    return (data.policy ?? []) as unknown as OrgPolicy[];
+  }
+
+  /** Set the policy for the org.
+   * @param {OrgPolicy[]} policy The new policy for the org.
+   * */
+  async setPolicy(policy: OrgPolicy[]) {
+    const p = policy as unknown as Record<string, never>[];
+    await this.update({ policy: p });
+  }
+
+  /** Create a new signing key.
+   * @param {KeyType} type The type of key to create.
+   * @param {string?} ownerId The owner of the key. Defaults to the session's user.
+   * @return {Key[]} The new keys.
+   * */
+  async createKey(type: KeyType, ownerId?: string): Promise<Key> {
+    return (await Key.createKeys(this.#cs, this.id, type, 1, ownerId))[0];
+  }
+
+  /** Create new signing keys.
+   * @param {KeyType} type The type of key to create.
+   * @param {nummber} count The number of keys to create.
+   * @param {string?} ownerId The owner of the keys. Defaults to the session's user.
+   * @return {Key[]} The new keys.
+   * */
+  async createKeys(type: KeyType, count: number, ownerId?: string): Promise<Key[]> {
+    return Key.createKeys(this.#cs, this.id, type, count, ownerId);
+  }
+
+  /**
+   * Create a new user in the organization and sends an invitation to that user
+   * @param {string} email Email of the user
+   * @param {string} name The full name of the user
+   */
+  async createUser(email: string, name: string): Promise<void> {
+    const resp = await (
+      await this.#cs.management()
+    ).post("/v0/org/{org_id}/invite", {
+      params: { path: { org_id: this.id } },
+      body: {
+        email,
+        name,
+        skip_email: false,
+      },
+      parseAs: "json",
+    });
+    assertOk(resp);
+  }
+
+  /**
+   * 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
+   * @return {string} User id of the new user
+   */
+  async createOidcUser(identity: OidcIdentity, memberRole: MemberRole): 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,
+      },
+      parseAs: "json",
+    });
+    return assertOk(resp).user_id;
+  }
+
+  /**
+   * List users in the organization
+   * @return {UserIdInfo[]} List of users
+   */
+  async users(): Promise<UserIdInfo[]> {
+    const resp = await (
+      await this.#cs.management()
+    ).get("/v0/org/{org_id}/users", {
+      params: { path: { org_id: this.id } },
+      parseAs: "json",
+    });
+    return assertOk(resp).users;
+  }
+
+  /** Get a key by id.
+   * @param {string} keyId The id of the key to get.
+   * @return {Key} The key.
+   * */
+  async getKey(keyId: string): Promise<Key> {
+    return await Key.getKey(this.#cs, this.id, keyId);
+  }
+
+  /** Get all keys in the org.
+   * @param {KeyType?} type Optional key type to filter list for.
+   * @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));
+  }
+
+  /** Create a new role.
+   * @param {string?} name The name of the role.
+   * @return {Role} The new role.
+   * */
+  async createRole(name?: string): Promise<Role> {
+    return Role.createRole(this.#cs, this.id, name);
+  }
+
+  /** Get a role by id or name.
+   * @param {string} roleId The id or name of the role to get.
+   * @return {Role} The role.
+   * */
+  async getRole(roleId: string): Promise<Role> {
+    return Role.getRole(this.#cs, this.id, roleId);
+  }
+
+  /** List all roles in the org..
+   * @return {Role[]} The roles.
+   * */
+  async list(): Promise<Role[]> {
+    return Org.roles(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.
+   */
+  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);
+  }
+
+  /**
+   * Approve a pending MFA request.
+   *
+   * @param {string} mfaId The id of the MFA request.
+   * @return {Promise<MfaRequestInfo>} The MFA request.
+   */
+  async mfaApprove(mfaId: string): Promise<MfaRequestInfo> {
+    return Org.mfaApprove(this.#cs, this.#id, mfaId);
+  }
+
+  // --------------------------------------------------------------------------
+  // -- INTERNAL --------------------------------------------------------------
+  // --------------------------------------------------------------------------
+
+  /** Create a new org.
+   * @param {CubeSigner} cs The CubeSigner instance.
+   * @param {OrgInfo} data The JSON response from the API server.
+   * @internal
+   * */
+  constructor(cs: CubeSigner, data: OrgInfo) {
+    this.#cs = cs;
+    this.#id = data.org_id;
+  }
+
+  /**
+   * Approve a pending MFA request.
+   *
+   * @param {CubeSigner} cs The CubeSigner instance to use for requests
+   * @param {string} orgId The org id of the MFA request
+   * @param {string} mfaId The id of the MFA request
+   * @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);
+  }
+
+  /** Fetch org info.
+   * @return {OrgInfo} The org info.
+   * */
+  private async fetch(): Promise<OrgInfo> {
+    const resp = await (
+      await this.#cs.management()
+    ).get("/v0/org/{org_id}", {
+      params: { path: { org_id: this.id } },
+      parseAs: "json",
+    });
+    const data = assertOk(resp);
+    return data;
+  }
+
+  /** Update the org.
+   * @param {UpdateOrgRequest} request The JSON request to send to the API server.
+   * @return {UpdateOrgResponse} The JSON response from the API server.
+   * */
+  private async update(request: UpdateOrgRequest): Promise<UpdateOrgResponse> {
+    const resp = await (
+      await this.#cs.management()
+    ).patch("/v0/org/{org_id}", {
+      params: { path: { org_id: this.id } },
+      body: request,
+      parseAs: "json",
+    });
+    return assertOk(resp);
+  }
+
+  /** 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.
+   * @internal
+   * */
+  private static async roles(cs: CubeSigner, orgId: string): Promise<Role[]> {
+    const resp = await (
+      await cs.management()
+    ).get("/v0/org/{org_id}/roles", {
+      params: { path: { org_id: orgId } },
+      parseAs: "json",
+    });
+    const data = assertOk(resp);
+    return data.roles.map((r: RoleInfo) => new Role(cs, orgId, r));
+  }
+}