@cubist-labs/cubesigner-sdk 0.1.50 → 0.2.2

package/src/org.ts

@@ -1,14 +1,26 @@
-import { CubeSigner, MfaRequestInfo } from ".";
-import { components, paths } from "./client";
-import { assertOk } from "./util";
+import { OrgInfo } from "./schema_types";
+import { CubeSignerClient } from "./client";
 import { KeyType, Key } from "./key";
-import { MfaPolicy, Role, RoleInfo } from "./role";
+import { Role } from "./role";
+import { PageOpts } from "./paginator";
 
 /** 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.
@@ -34,27 +46,10 @@ 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"];
-
-/** 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;
+  readonly #csc: CubeSignerClient;
+
   /**
    * The ID of the organization.
    * @example Org#124dfe3e-3bbd-487d-80c0-53c55e8ab87a
@@ -64,47 +59,48 @@ export class Org {
   /**
    * @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();
+    const data = await this.#csc.orgGet();
     return data.name ?? undefined;
   }
 
-  /** Set the human-readable name for the org.
+  /**
+   * 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 });
+    await this.#csc.orgUpdate({ name });
   }
 
   /** Is the org enabled? */
   async enabled(): Promise<boolean> {
-    const data = await this.fetch();
+    const data = await this.#csc.orgGet();
     return data.enabled;
   }
 
   /** Enable the org. */
   async enable() {
-    await this.update({ enabled: true });
+    await this.#csc.orgUpdate({ enabled: true });
   }
 
   /** Disable the org. */
   async disable() {
-    await this.update({ enabled: false });
+    await this.#csc.orgUpdate({ enabled: false });
   }
 
   /** Get the policy for the org. */
   async policy(): Promise<OrgPolicy[]> {
-    const data = await this.fetch();
+    const data = await this.#csc.orgGet();
     return (data.policy ?? []) as unknown as OrgPolicy[];
   }
 
@@ -113,337 +109,192 @@ export class Org {
    * */
   async setPolicy(policy: OrgPolicy[]) {
     const p = policy as unknown as Record<string, never>[];
-    await this.update({ policy: p });
+    await this.#csc.orgUpdate({ policy: p });
   }
 
-  /** Create a new signing key.
+  /**
+   * 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];
+    return (await this.createKeys(type, 1, ownerId))[0];
   }
 
-  /** Create new signing keys.
+  /**
+   * Create new signing keys.
    * @param {KeyType} type The type of key to create.
-   * @param {nummber} count The number of keys 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.
-   * */
+   */
   async createKeys(type: KeyType, count: number, ownerId?: string): Promise<Key[]> {
-    return Key.createKeys(this.#cs, this.id, type, count, ownerId);
+    const keys = await this.#csc.keysCreate(type, count, ownerId);
+    return keys.map((k) => new Key(this.#csc, k));
   }
 
   /**
-   * Derives a key of the given type using the given derivation path and mnemonic.
+   * Derive 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.
-   * @param {string} ownerId optional owner of the derived key.
    *
    * @return {Key} newly derived key.
    */
-  async deriveKey(
-    type: KeyType,
-    derivationPath: string,
-    mnemonicId: string,
-    ownerId?: string,
-  ): Promise<Key> {
-    return (
-      await Key.deriveKeys(this.#cs, this.id, type, [derivationPath], mnemonicId, ownerId)
-    )[0];
+  async deriveKey(type: KeyType, derivationPath: string, mnemonicId: string): Promise<Key> {
+    return (await this.deriveKeys(type, [derivationPath], mnemonicId))[0];
   }
 
   /**
-   * Derives a set of keys of the given type using the given derivation paths and mnemonic.
+   * Derive 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.
-   * @param {string} ownerId optional owner of the derived key.
    *
    * @return {Key[]} newly derived keys.
    */
-  async deriveKeys(
-    type: KeyType,
-    derivationPaths: string[],
-    mnemonicId: string,
-    ownerId?: string,
-  ): Promise<Key[]> {
-    return await Key.deriveKeys(this.#cs, this.#id, type, derivationPaths, mnemonicId, ownerId);
+  async deriveKeys(type: KeyType, derivationPaths: string[], mnemonicId: string): Promise<Key[]> {
+    const keys = await this.#csc.keysDerive(type, derivationPaths, mnemonicId);
+    return keys.map((k) => new Key(this.#csc, k));
   }
-  /**
-   * 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 user in the organization and sends an invitation to that user. */
+  get createUser() {
+    return this.#csc.orgUserInvite.bind(this.#csc);
   }
 
-  /**
-   * Create a new OIDC user
-   * @param {OidcIdentity} identity The identity of the OIDC 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,
-    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: opts.memberRole ?? "Alien",
-        email: email,
-        mfa_policy: opts.mfaPolicy ?? null,
-      },
-      parseAs: "json",
-    });
-    return assertOk(resp).user_id;
+  /** Create a new OIDC user */
+  get createOidcUser() {
+    return this.#csc.orgUserCreateOidc.bind(this.#csc);
   }
 
-  /**
-   * 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);
+  /** Delete an existing OIDC user */
+  get deleteOidcUser() {
+    return this.#csc.orgUserDeleteOidc.bind(this.#csc);
   }
 
-  /**
-   * 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;
+  /** Checks if a given proof of OIDC authentication is valid. */
+  get verifyIdentity() {
+    return this.#csc.identityVerify.bind(this.#csc);
   }
 
-  /** Get a key by id.
+  /**  List users in the organization */
+  get users() {
+    return this.#csc.orgUsersList.bind(this.#csc);
+  }
+
+  /**
+   * 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);
+    const keyInfo = await this.#csc.keyGet(keyId);
+    return new Key(this.#csc, keyInfo);
   }
 
-  /** Get all keys in the 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) => new Key(this.#cs, this.id, k));
+   */
+  async keys(type?: KeyType, page?: PageOpts): Promise<Key[]> {
+    const paginator = this.#csc.keysList(type, page);
+    const keys = await paginator.fetch();
+    return keys.map((k) => new Key(this.#csc, k));
   }
 
-  /** Create a new role.
+  /**
+   * 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);
+    const roleId = await this.#csc.roleCreate(name);
+    const roleInfo = await this.#csc.roleGet(roleId);
+    return new Role(this.#csc, roleInfo);
   }
 
-  /** Get a role by id or 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);
+    const roleInfo = await this.#csc.roleGet(roleId);
+    return new Role(this.#csc, roleInfo);
   }
 
-  /** 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 listRoles(): Promise<Role[]> {
-    return Org.roles(this.#cs, this.id);
+   */
+  async listRoles(page?: PageOpts): Promise<Role[]> {
+    const roles = await this.#csc.rolesList(page).fetch();
+    return roles.map((r) => new Role(this.#csc, r));
   }
 
-  /** List all users in the org.
-   * @return {User[]} The users.
-   * */
-  async listUsers(): Promise<UserIdInfo[]> {
-    return Org.users(this.#cs, this.id);
+  /** List all users in the org. */
+  get listUsers() {
+    return this.#csc.orgUsersList.bind(this.#csc);
   }
 
   /**
    * 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> {
-    return await this.getMfaInfo(mfaId);
+  get mfaGet() {
+    return this.#csc.mfaGet.bind(this.#csc);
   }
 
   /**
    * Approve a pending MFA request.
    *
-   * @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 mfaApprove() {
+    return this.#csc.mfaApprove.bind(this.#csc);
   }
 
-  /**
-   * 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> {
-    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);
+  /** Get a pending MFA request by its id. */
+  get getMfaInfo() {
+    return this.#csc.mfaGet.bind(this.#csc);
   }
 
-  /**
-   * 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);
+  /** List pending MFA requests accessible to the current user. */
+  get listMfaInfos() {
+    return this.#csc.mfaList.bind(this.#csc);
+  }
+
+  /** Approve a pending MFA request. */
+  get approveMfaRequest() {
+    return this.#csc.mfaApprove.bind(this.#csc);
   }
 
   // --------------------------------------------------------------------------
   // -- INTERNAL --------------------------------------------------------------
   // --------------------------------------------------------------------------
 
-  /** Create a new org.
-   * @param {CubeSigner} cs The CubeSigner instance.
+  /**
+   * Create a new org.
+   * @param {CubeSignerClient} csc 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[]} Org roles.
-   * @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));
-  }
-
-  /** 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 users(cs: CubeSigner, orgId: string): Promise<UserIdInfo[]> {
-    const resp = await (
-      await cs.management()
-    ).get("/v0/org/{org_id}/users", {
-      params: { path: { org_id: orgId } },
-      parseAs: "json",
-    });
-    const data = assertOk(resp);
-    return data.users;
+  constructor(csc: CubeSignerClient, data: OrgInfo) {
+    this.#csc = csc.withOrg(data.org_id);
+    this.#id = data.org_id;
   }
 }

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;
+  }
+}