@cubist-labs/cubesigner-sdk 0.1.77 → 0.2.15

package/src/index.ts

@@ -1,15 +1,22 @@
 import { envs, EnvInterface } from "./env";
-import { components, Client, paths } from "./client";
+import { Client, OidcClient } from "./api";
+import { CubeSignerClient } from "./client";
 import { Org } from "./org";
 import { JsonFileSessionStorage } from "./session/session_storage";
 
-import { SignerSessionStorage, SignerSessionManager } from "./session/signer_session_manager";
-import { AcceptedResponse, MfaRequestInfo, SignResponse, SignerSession } from "./signer_session";
+import {
+  SignerSessionStorage,
+  SignerSessionManager,
+  SignerSessionData,
+} from "./session/signer_session_manager";
+import { CubeSignerResponse } from "./response";
+import { SignerSession } from "./signer_session";
 import { CognitoSessionManager, CognitoSessionStorage } from "./session/cognito_manager";
-import { assertOk, configDir } from "./util";
+import { configDir } from "./util";
 import * as path from "path";
-import createClient from "openapi-fetch";
-import { AddFidoChallenge, ApiAddFidoChallenge, PublicKeyCredential } from "./fido";
+import { MfaReceipt } from "./mfa";
+import { name, version } from "./../package.json";
+import { IdentityProof, MfaRequestInfo, RatchetConfig, UserInfo } from "./schema_types";
 
 /** CubeSigner constructor options */
 export interface CubeSignerOptions {
@@ -21,61 +28,43 @@ export interface CubeSignerOptions {
   orgId?: string;
 }
 
-export type UserInfo = components["schemas"]["UserInfo"];
-export type TotpInfo = components["responses"]["TotpInfo"]["content"]["application/json"];
-export type ConfiguredMfa = components["schemas"]["ConfiguredMfa"];
-export type RatchetConfig = components["schemas"]["RatchetConfig"];
-export type IdentityProof = components["schemas"]["IdentityProof"];
-
-type OidcAuthResponse =
-  paths["/v0/org/{org_id}/oidc"]["post"]["responses"]["200"]["content"]["application/json"];
+/**
+ * CubeSigner client
+ *
+ * @deprecated Use {@link Org} or {@link CubeSignerClient} instead.
+ */
+export class CubeSigner {
+  readonly #env: EnvInterface;
+  readonly sessionMgr?: CognitoSessionManager | SignerSessionManager;
+  #csc?: CubeSignerClient;
 
-/** TOTP challenge that must be answered before user's TOTP is updated */
-export class TotpChallenge {
-  readonly #cs: CubeSigner;
-  readonly #totpInfo: TotpInfo;
-  /** The id of the challenge */
-  get totpId() {
-    return this.#totpInfo.totp_id;
-  }
-  /** The new TOTP configuration */
-  get totpUrl() {
-    return this.#totpInfo.totp_url;
-  }
-  /**
-   * @param {CubeSigner} cs Used when answering the challenge.
-   * @param {TotpInfo} totpInfo TOTP challenge information.
-   */
-  constructor(cs: CubeSigner, totpInfo: TotpInfo) {
-    this.#cs = cs;
-    this.#totpInfo = totpInfo;
-  }
   /**
-   * Answer the challenge with the code that corresponds to this `this.totpUrl`.
-   * @param {string} code 6-digit code that corresponds to this `this.totpUrl`.
+   * Underlying {@link CubeSignerClient} instance, if set; otherwise throws.
+   * @internal
    */
-  async answer(code: string) {
-    await this.#cs.resetTotpComplete(this.totpId, code);
+  get csc(): CubeSignerClient {
+    if (!this.#csc) {
+      throw new Error("CubeSignerClient is not set");
+    }
+    return this.#csc;
   }
-}
-
-/** CubeSigner client */
-export class CubeSigner {
-  readonly #env: EnvInterface;
-  readonly sessionMgr?: CognitoSessionManager | SignerSessionManager;
-  #orgId?: string;
 
   /** @return {EnvInterface} The CubeSigner environment of this client */
   get env(): EnvInterface {
     return this.#env;
   }
 
+  /** Organization ID */
+  get orgId() {
+    return this.csc.orgId;
+  }
+
   /**
    * Set the organization ID
    * @param {string} orgId The new organization id.
    */
   setOrgId(orgId: string) {
-    this.#orgId = orgId;
+    this.#csc = this.csc.withOrg(orgId);
   }
 
   /**
@@ -87,12 +76,8 @@ export class CubeSigner {
    * @return {Promise<CubeSigner>} New CubeSigner instance
    */
   static async loadManagementSession(storage?: CognitoSessionStorage): Promise<CubeSigner> {
-    const defaultFilePath = path.join(configDir(), "management-session.json");
-    const sessionMgr = await CognitoSessionManager.loadFromStorage(
-      storage ?? new JsonFileSessionStorage(defaultFilePath),
-    );
     return new CubeSigner(<CubeSignerOptions>{
-      sessionMgr,
+      sessionMgr: await CognitoSessionManager.loadManagementSession(storage),
     });
   }
 
@@ -111,7 +96,7 @@ export class CubeSigner {
 
   /**
    * Create a new CubeSigner instance.
-   * @param {CubeSignerOptions} options The optional configuraiton options for the CubeSigner instance.
+   * @param {CubeSignerOptions} options The optional configuration options for the CubeSigner instance.
    */
   constructor(options?: CubeSignerOptions) {
     let env = options?.env;
@@ -120,11 +105,21 @@ export class CubeSigner {
       env = env ?? this.sessionMgr.env;
     }
     this.#env = env ?? envs["gamma"];
-    this.#orgId = options?.orgId;
+    this.#csc = new CubeSignerClient(
+      // HACK: ignore that sessionMgr may be a CognitoSessionManager and pretend that it
+      //       is a SignerSessionManager; that's fine because the CubeSignerClient will
+      //       almost always just call `await token()` on it, which works in both cases.
+      //
+      // This is done here for backward compatibility reasons only; in the future,
+      // we should deprecate this class and people should start using `CubeSingerClient` directly.
+      options?.sessionMgr as unknown as SignerSessionManager,
+      options?.orgId,
+    );
   }
 
   /**
    * Authenticate an OIDC user and create a new session manager for them.
+   *
    * @param {string} oidcToken The OIDC token
    * @param {string} orgId The id of the organization that the user is in
    * @param {List<string>} scopes The scopes of the resulting session
@@ -149,17 +144,7 @@ export class CubeSigner {
    * @return {Promise<UserInfo>} User information.
    */
   async aboutMe(): Promise<UserInfo> {
-    const client = await this.management();
-    const resp = this.#orgId
-      ? await client.get("/v0/org/{org_id}/user/me", {
-          params: { path: { org_id: this.#orgId } },
-          parseAs: "json",
-        })
-      : await client.get("/v0/about_me", {
-          parseAs: "json",
-        });
-    const data = assertOk(resp);
-    return data;
+    return await this.csc.userGet();
   }
 
   /**
@@ -170,12 +155,7 @@ export class CubeSigner {
    * @return {Promise<MfaRequestInfo>} MFA request information
    */
   async mfaGet(orgId: string, mfaId: string): Promise<MfaRequestInfo> {
-    const resp = await (
-      await this.management()
-    ).get("/v0/org/{org_id}/mfa/{mfa_id}", {
-      params: { path: { org_id: orgId, mfa_id: mfaId } },
-    });
-    return assertOk(resp);
+    return await this.csc.withOrg(orgId).mfaGet(mfaId);
   }
 
   /**
@@ -184,12 +164,7 @@ export class CubeSigner {
    * @return {Promise<MfaRequestInfo[]>} The MFA requests.
    */
   async mfaList(orgId: string): Promise<MfaRequestInfo[]> {
-    const resp = await (
-      await this.management()
-    ).get("/v0/org/{org_id}/mfa", {
-      params: { path: { org_id: orgId } },
-    });
-    return assertOk(resp).mfa_requests;
+    return await this.csc.withOrg(orgId).mfaList();
   }
 
   /**
@@ -200,158 +175,45 @@ export class CubeSigner {
    * @return {Promise<MfaRequestInfo>} The result of the MFA request
    */
   async mfaApprove(orgId: string, mfaId: string): Promise<MfaRequestInfo> {
-    const resp = await (
-      await this.management()
-    ).patch("/v0/org/{org_id}/mfa/{mfa_id}", {
-      params: { path: { org_id: orgId, mfa_id: mfaId } },
-    });
-    return assertOk(resp);
+    return await this.csc.withOrg(orgId).mfaApprove(mfaId);
   }
 
-  /**
-   * Initiate adding a new FIDO device. MFA may be required.
-   * @param {string} name The name of the new device.
-   * @param {MfaReceipt} mfaReceipt Optional MFA receipt to include in HTTP headers
-   * @return {Promise<SignResponse<AddFidoChallenge>>} A challenge that must be answered in order to complete FIDO registration.
-   */
-  async addFidoStart(
-    name: string,
-    mfaReceipt?: MfaReceipt,
-  ): Promise<SignResponse<AddFidoChallenge>> {
-    const orgId = this.#orgId || mfaReceipt?.mfaOrgId;
-    if (!orgId) {
-      throw new Error("Org ID must be set");
-    }
-    const addFidoFn = async (headers?: HeadersInit) => {
-      const client = await this.management();
-      const resp = await client.post("/v0/org/{org_id}/user/me/fido", {
-        headers,
-        params: { path: { org_id: orgId } },
-        body: { name },
-        parseAs: "json",
-      });
-      const x = assertOk(resp);
-      // TODO: add mapFn to SignResponse
-      if ((x as AcceptedResponse).accepted?.MfaRequired) {
-        return x as AcceptedResponse;
-      } else {
-        return new AddFidoChallenge(this, x as ApiAddFidoChallenge);
-      }
-    };
-    return await SignResponse.create(addFidoFn, mfaReceipt);
-  }
-
-  /**
-   * Complete a previously initiated request to add a new FIDO device.
-   * @param {string} challengeId The ID of the challenge returned by the remote end.
-   * @param {PublicKeyCredential} credential The answer to the challenge.
-   */
-  async addFidoComplete(challengeId: string, credential: PublicKeyCredential) {
-    const orgId = this.#orgId;
-    if (!orgId) {
-      throw new Error("Org ID must be set");
-    }
-    const client = await this.management();
-    const resp = await client.patch("/v0/org/{org_id}/user/me/fido", {
-      params: { path: { org_id: orgId } },
-      body: {
-        challenge_id: challengeId,
-        credential,
-      },
-      parseAs: "json",
-    });
-    assertOk(resp);
+  /** Initiate adding a new FIDO device. MFA may be required. */
+  get addFidoStart() {
+    return this.csc.userRegisterFidoInit.bind(this.csc);
   }
 
   /**
    * Creates a request to change user's TOTP. This request returns a new TOTP challenge
    * that must be answered by calling `resetTotpComplete`
-   *
-   * @param {MfaReceipt} mfaReceipt MFA receipt to include in HTTP headers
    */
-  async resetTotpStart(mfaReceipt?: MfaReceipt): Promise<SignResponse<TotpChallenge>> {
-    const resetTotpFn = async (headers?: HeadersInit) => {
-      const orgId = this.#orgId || mfaReceipt?.mfaOrgId;
-      const client = await this.management();
-      const resp = orgId
-        ? await client.post("/v0/org/{org_id}/user/me/totp", {
-            headers,
-            params: { path: { org_id: orgId } },
-            body: null,
-            parseAs: "json",
-          })
-        : await client.post("/v0/user/me/totp", {
-            headers,
-            body: null,
-            parseAs: "json",
-          });
-      const x = assertOk(resp);
-      // TODO: add mapFn to SignResponse
-      if ((x as AcceptedResponse).accepted?.MfaRequired) {
-        return x as AcceptedResponse;
-      } else {
-        return new TotpChallenge(this, x as TotpInfo);
-      }
-    };
-    return await SignResponse.create(resetTotpFn, mfaReceipt);
+  get resetTotpStart() {
+    return this.csc.userResetTotpInit.bind(this.#csc);
   }
 
   /**
    * Answer the TOTP challenge issued by `resetTotpStart`. If successful, user's
-   * TOTP configuration will be updated to that of the TOTP challenge.
-   *
-   * @param {string} totpId - The ID of the TOTP challenge
-   * @param {string} code - The TOTP code that should verify against the TOTP configuration from the challenge.
+   * TOTP configuration will be updated to that of the TOTP challenge.he TOTP configuration from the challenge.
    */
-  async resetTotpComplete(totpId: string, code: string): Promise<void> {
-    const client = await this.management();
-    const resp = this.#orgId
-      ? await client.patch("/v0/org/{org_id}/user/me/totp", {
-          parseAs: "json",
-          params: { path: { org_id: this.#orgId } },
-          body: { totp_id: totpId, code },
-        })
-      : await client.patch("/v0/user/me/totp", {
-          parseAs: "json",
-          body: { totp_id: totpId, code },
-        });
-    assertOk(resp);
+  get resetTotpComplete() {
+    return this.csc.userResetTotpComplete.bind(this.#csc);
   }
 
   /**
    * Verifies a given TOTP code against the current user's TOTP configuration.
    * Throws an error if the verification fails.
-   * @param {string} code Current TOTP code
    */
-  async verifyTotp(code: string) {
-    const client = await this.management();
-    const resp = this.#orgId
-      ? await client.post("/v0/org/{org_id}/user/me/totp/verify", {
-          params: { path: { org_id: this.#orgId } },
-          body: { code },
-          parseAs: "json",
-        })
-      : await client.post("/v0/user/me/totp/verify", {
-          body: { code },
-          parseAs: "json",
-        });
-    assertOk(resp);
+  get verifyTotp() {
+    return this.csc.userVerifyTotp.bind(this.#csc);
   }
 
-  /** Retrieves information about an organization.
+  /**
+   * Retrieve information about an organization.
    * @param {string} orgId The ID or name of the organization.
    * @return {Org} The organization.
-   * */
-  async getOrg(orgId: string): Promise<Org> {
-    const resp = await (
-      await this.management()
-    ).get("/v0/org/{org_id}", {
-      params: { path: { org_id: orgId } },
-      parseAs: "json",
-    });
-
-    const data = assertOk(resp);
-    return new Org(this, data);
+   */
+  async getOrg(orgId?: string): Promise<Org> {
+    return new Org(this.csc.sessionMgr, orgId ?? this.csc.orgId);
   }
 
   /**
@@ -360,19 +222,14 @@ export class CubeSigner {
    * @param {string} keyId - Key id
    */
   async deleteKey(orgId: string, keyId: string) {
-    const resp = await (
-      await this.management()
-    ).del("/v0/org/{org_id}/keys/{key_id}", {
-      params: { path: { org_id: orgId, key_id: keyId } },
-      parseAs: "json",
-    });
-    assertOk(resp);
+    await this.csc.withOrg(orgId).keyDelete(keyId);
   }
 
-  /** Get the management client.
+  /**
+   * Get the management client.
    * @return {Client} The client.
    * @internal
-   * */
+   */
   async management(): Promise<Client> {
     if (!this.sessionMgr) {
       throw new Error("No management session loaded");
@@ -387,12 +244,7 @@ export class CubeSigner {
    * @return {Promise<IdentityProof>} Proof of authentication
    */
   async proveIdentity(orgId: string): Promise<IdentityProof> {
-    const client = await this.management();
-    const resp = await client.post("/v0/org/{org_id}/identity/prove", {
-      params: { path: { org_id: orgId } },
-      parseAs: "json",
-    });
-    return assertOk(resp);
+    return await this.csc.withOrg(orgId).identityProve();
   }
 
   /**
@@ -403,17 +255,8 @@ export class CubeSigner {
    * @return {Promise<IdentityProof>} Proof of authentication
    */
   async oidcProveIdentity(oidcToken: string, orgId: string): Promise<IdentityProof> {
-    const client = createClient<paths>({
-      baseUrl: this.env.SignerApiRoot,
-      headers: {
-        Authorization: oidcToken,
-      },
-    });
-    const resp = await client.post("/v0/org/{org_id}/identity/prove/oidc", {
-      params: { path: { org_id: orgId } },
-      parseAs: "json",
-    });
-    return assertOk(resp);
+    const oidcClient = new OidcClient(this.#env, orgId, oidcToken);
+    return await oidcClient.identityProve();
   }
 
   /**
@@ -423,14 +266,7 @@ export class CubeSigner {
    * @param {IdentityProof} identityProof The proof of authentication.
    */
   async verifyIdentity(orgId: string, identityProof: IdentityProof) {
-    const resp = await (
-      await this.management()
-    ).post("/v0/org/{org_id}/identity/verify", {
-      params: { path: { org_id: orgId } },
-      body: identityProof,
-      parseAs: "json",
-    });
-    assertOk(resp);
+    await this.csc.withOrg(orgId).identityVerify(identityProof);
   }
 
   /**
@@ -440,7 +276,7 @@ export class CubeSigner {
    * @param {List<string>} scopes The scopes of the resulting session
    * @param {RatchetConfig} lifetimes Lifetimes of the new session.
    * @param {MfaReceipt} mfaReceipt Optional MFA receipt (id + confirmation code)
-   * @return {Promise<SignResponse<OidcAuthResponse>>} The session data.
+   * @return {Promise<CubeSignerResponse<SignerSessionData>>} The session data.
    */
   async oidcLogin(
     oidcToken: string,
@@ -448,41 +284,16 @@ export class CubeSigner {
     scopes: Array<string>,
     lifetimes?: RatchetConfig,
     mfaReceipt?: MfaReceipt,
-  ): Promise<SignResponse<OidcAuthResponse>> {
-    const client = createClient<paths>({
-      baseUrl: this.env.SignerApiRoot,
-      headers: {
-        Authorization: oidcToken,
-      },
-    });
-    const loginFn = async (headers?: HeadersInit) => {
-      const resp = await client.post("/v0/org/{org_id}/oidc", {
-        params: { path: { org_id: orgId } },
-        headers,
-        body: {
-          scopes,
-          tokens: lifetimes,
-        },
-        parseAs: "json",
-      });
-      return assertOk(resp);
-    };
-
-    const h1 = mfaReceipt ? SignResponse.getMfaHeaders(mfaReceipt) : undefined;
-    return new SignResponse(loginFn, await loginFn(h1));
+  ): Promise<CubeSignerResponse<SignerSessionData>> {
+    const oidcClient = new OidcClient(this.#env, orgId, oidcToken);
+    return await oidcClient.sessionCreate(scopes, lifetimes, mfaReceipt);
   }
 }
 
-/** MFA receipt */
-export interface MfaReceipt {
-  /** MFA request ID */
-  mfaId: string;
-  /** Corresponding org ID */
-  mfaOrgId: string;
-  /** MFA confirmation code */
-  mfaConf: string;
-}
-
+/** API */
+export * from "./api";
+/** Client */
+export * from "./client";
 /** Organizations */
 export * from "./org";
 /** Keys */
@@ -492,9 +303,13 @@ export * from "./role";
 /** Env */
 export * from "./env";
 /** Fido */
-export * from "./fido";
+export * from "./mfa";
 /** Pagination */
 export * from "./paginator";
+/** Response */
+export * from "./response";
+/** Types */
+export * from "./schema_types";
 /** Sessions */
 export * from "./signer_session";
 /** Session storage */
@@ -505,5 +320,13 @@ export * from "./session/session_manager";
 export * from "./session/cognito_manager";
 /** Signer session manager */
 export * from "./session/signer_session_manager";
+/** User-export decryption helper */
+export { userExportDecrypt, userExportKeygen } from "./user_export";
 /** Export ethers.js Signer */
 export * as ethers from "./ethers";
+
+/** CubeSigner SDK package name */
+export const NAME: string = name;
+
+/** CubeSigner SDK version */
+export const VERSION: string = version;