@cubist-labs/cubesigner-sdk 0.1.26 → 0.1.77

package/src/index.ts

@@ -1,49 +1,94 @@
 import { envs, EnvInterface } from "./env";
-import { components, Client } from "./client";
+import { components, Client, paths } from "./client";
 import { Org } from "./org";
-import { JsonFileSessionStorage, MemorySessionStorage } from "./session/session_storage";
-import { SignerSessionStorage } from "./session/signer_session_manager";
-import { SignerSession } from "./signer_session";
-import {
-  ManagementSessionManager,
-  ManagementSessionStorage,
-} from "./session/management_session_manager";
-import { OidcSessionManager, OidcSessionStorage } from "./session/oidc_session_manager";
+import { JsonFileSessionStorage } from "./session/session_storage";
+
+import { SignerSessionStorage, SignerSessionManager } from "./session/signer_session_manager";
+import { AcceptedResponse, MfaRequestInfo, SignResponse, SignerSession } from "./signer_session";
+import { CognitoSessionManager, CognitoSessionStorage } from "./session/cognito_manager";
 import { assertOk, configDir } from "./util";
 import * as path from "path";
+import createClient from "openapi-fetch";
+import { AddFidoChallenge, ApiAddFidoChallenge, PublicKeyCredential } from "./fido";
 
 /** CubeSigner constructor options */
 export interface CubeSignerOptions {
   /** The environment to use */
   env?: EnvInterface;
   /** The management authorization token */
-  sessionMgr?: ManagementSessionManager | OidcSessionManager;
+  sessionMgr?: CognitoSessionManager | SignerSessionManager;
+  /** Optional organization id */
+  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"];
+
+/** 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`.
+   */
+  async answer(code: string) {
+    await this.#cs.resetTotpComplete(this.totpId, code);
+  }
+}
 
 /** CubeSigner client */
 export class CubeSigner {
   readonly #env: EnvInterface;
-  readonly sessionMgr?: ManagementSessionManager | OidcSessionManager;
+  readonly sessionMgr?: CognitoSessionManager | SignerSessionManager;
+  #orgId?: string;
 
   /** @return {EnvInterface} The CubeSigner environment of this client */
   get env(): EnvInterface {
     return this.#env;
   }
 
+  /**
+   * Set the organization ID
+   * @param {string} orgId The new organization id.
+   */
+  setOrgId(orgId: string) {
+    this.#orgId = orgId;
+  }
+
   /**
    * Loads an existing management session and creates a CubeSigner instance.
-   * @param {ManagementSessionStorage} storage Optional session storage to load
+   *
+   * @param {CognitoSessionStorage} storage Optional session storage to load
    * the session from. If not specified, the management session from the config
    * directory will be loaded.
    * @return {Promise<CubeSigner>} New CubeSigner instance
    */
-  static async loadManagementSession(storage?: ManagementSessionStorage): Promise<CubeSigner> {
+  static async loadManagementSession(storage?: CognitoSessionStorage): Promise<CubeSigner> {
     const defaultFilePath = path.join(configDir(), "management-session.json");
-    const sessionMgr = await ManagementSessionManager.loadFromStorage(
+    const sessionMgr = await CognitoSessionManager.loadFromStorage(
       storage ?? new JsonFileSessionStorage(defaultFilePath),
     );
     return new CubeSigner(<CubeSignerOptions>{
@@ -61,110 +106,235 @@ export class CubeSigner {
   static async loadSignerSession(storage?: SignerSessionStorage): Promise<SignerSession> {
     const defaultFilePath = path.join(configDir(), "signer-session.json");
     const sss = storage ?? new JsonFileSessionStorage(defaultFilePath);
-    const env = (await sss.retrieve()).env["Dev-CubeSignerStack"];
-    return await SignerSession.loadSignerSession(new CubeSigner({ env }), sss);
-  }
-
-  /**
-   * Loads a signer session from OIDC storage
-   * @param {OidcSessionStorage} storage The storage to load from
-   * @return {Promise<SignerSession>} New signer session
-   */
-  static async loadOidcSession(storage: OidcSessionStorage): Promise<SignerSession> {
-    const env = (await storage.retrieve()).env;
-    return await SignerSession.loadOidcSession(new CubeSigner({ env }), storage);
+    return await SignerSession.loadSignerSession(sss);
   }
 
   /**
    * Create a new CubeSigner instance.
-   * @param {CubeSignerOptions} options The options for the CubeSigner instance.
+   * @param {CubeSignerOptions} options The optional configuraiton options for the CubeSigner instance.
    */
-  constructor(options: CubeSignerOptions) {
-    let env = options.env;
-    if (options.sessionMgr) {
+  constructor(options?: CubeSignerOptions) {
+    let env = options?.env;
+    if (options?.sessionMgr) {
       this.sessionMgr = options.sessionMgr;
       env = env ?? this.sessionMgr.env;
     }
     this.#env = env ?? envs["gamma"];
+    this.#orgId = options?.orgId;
   }
 
   /**
-   * Authenticate an OIDC user and create a new OIDC session manager for them.
+   * 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
-   * @param {OidcSessionStorage} storage The signer session storage
-   * @return {Promise<OidcSessionManager>} The OIDC session manager
+   * @param {RatchetConfig} lifetimes Lifetimes of the new session.
+   * @param {SignerSessionStorage?} storage Optional signer session storage (defaults to in-memory storage)
+   * @return {Promise<SignerSessionManager>} The signer session manager
    */
-  async createOidcManager(
+  async oidcAuth(
     oidcToken: string,
     orgId: string,
     scopes: Array<string>,
-    storage?: OidcSessionStorage,
-  ): Promise<OidcSessionManager> {
-    return await OidcSessionManager.create(
-      this.env,
-      storage || new MemorySessionStorage(),
-      oidcToken,
-      orgId,
-      scopes,
-    );
+    lifetimes?: RatchetConfig,
+    storage?: SignerSessionStorage,
+  ): Promise<SignerSessionManager> {
+    const resp = await this.oidcLogin(oidcToken, orgId, scopes, lifetimes);
+    return await SignerSessionManager.createFromSessionInfo(this.env, orgId, resp.data(), storage);
   }
 
   /**
-   * Authenticate an OIDC user and create a new session 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
-   * @param {OidcSessionStorage} storage The signer session storage
-   * @return {Promise<SignerSession>} The signer session
+   * Retrieves information about the current user.
+   *
+   * @return {Promise<UserInfo>} User information.
    */
-  async createOidcSession(
-    oidcToken: string,
-    orgId: string,
-    scopes: Array<string>,
-    storage?: OidcSessionStorage,
-  ): Promise<SignerSession> {
-    const mgr = await this.createOidcManager(oidcToken, orgId, scopes, storage);
-    return await CubeSigner.loadOidcSession(mgr.storage);
+  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;
   }
 
-  /** Retrieves information about the current user. */
-  async aboutMe(): Promise<UserInfo> {
+  /**
+   * Retrieves existing MFA request.
+   *
+   * @param {string} orgId Organization ID
+   * @param {string} mfaId MFA request ID
+   * @return {Promise<MfaRequestInfo>} MFA request information
+   */
+  async mfaGet(orgId: string, mfaId: string): Promise<MfaRequestInfo> {
     const resp = await (
       await this.management()
-    ).get("/v0/about_me", {
-      parseAs: "json",
+    ).get("/v0/org/{org_id}/mfa/{mfa_id}", {
+      params: { path: { org_id: orgId, mfa_id: mfaId } },
     });
-    const data = assertOk(resp);
-    return data;
+    return assertOk(resp);
   }
 
   /**
-   * Creates and sets a new TOTP configuration for the logged-in user,
-   * overriding the existing one (if any).
+   * List pending MFA requests accessible to the current user.
+   * @param {string} orgId Organization ID
+   * @return {Promise<MfaRequestInfo[]>} The MFA requests.
    */
-  async resetTotp(): Promise<TotpInfo> {
+  async mfaList(orgId: string): Promise<MfaRequestInfo[]> {
     const resp = await (
       await this.management()
-    ).patch("/v0/totp", {
-      parseAs: "json",
+    ).get("/v0/org/{org_id}/mfa", {
+      params: { path: { org_id: orgId } },
+    });
+    return assertOk(resp).mfa_requests;
+  }
+
+  /**
+   * Approve a pending MFA request.
+   *
+   * @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
+   */
+  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);
   }
 
+  /**
+   * 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);
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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.
+   */
+  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);
+  }
+
   /**
    * 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 resp = await (
-      await this.management()
-    ).get("/v0/totp/verify/{code}", {
-      params: { path: { code } },
-      parseAs: "json",
-    });
+    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);
   }
 
@@ -184,6 +354,21 @@ export class CubeSigner {
     return new Org(this, data);
   }
 
+  /**
+   * Deletes a given key.
+   * @param {string} orgId - Organization id
+   * @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);
+  }
+
   /** Get the management client.
    * @return {Client} The client.
    * @internal
@@ -194,6 +379,108 @@ export class CubeSigner {
     }
     return await this.sessionMgr.client();
   }
+
+  /**
+   * Obtain a proof of authentication.
+   *
+   * @param {string} orgId The id of the organization that the user is in
+   * @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);
+  }
+
+  /**
+   * Exchange an OIDC token for a proof of authentication.
+   *
+   * @param {string} oidcToken The OIDC token
+   * @param {string} orgId The id of the organization that the user is in
+   * @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);
+  }
+
+  /**
+   * Checks if a given identity proof is valid.
+   *
+   * @param {string} orgId The id of the organization that the user is in.
+   * @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);
+  }
+
+  /**
+   * Exchange an OIDC token for a CubeSigner session token.
+   * @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
+   * @param {RatchetConfig} lifetimes Lifetimes of the new session.
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt (id + confirmation code)
+   * @return {Promise<SignResponse<OidcAuthResponse>>} The session data.
+   */
+  async oidcLogin(
+    oidcToken: string,
+    orgId: string,
+    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));
+  }
+}
+
+/** MFA receipt */
+export interface MfaReceipt {
+  /** MFA request ID */
+  mfaId: string;
+  /** Corresponding org ID */
+  mfaOrgId: string;
+  /** MFA confirmation code */
+  mfaConf: string;
 }
 
 /** Organizations */
@@ -204,6 +491,10 @@ export * from "./key";
 export * from "./role";
 /** Env */
 export * from "./env";
+/** Fido */
+export * from "./fido";
+/** Pagination */
+export * from "./paginator";
 /** Sessions */
 export * from "./signer_session";
 /** Session storage */
@@ -211,9 +502,7 @@ export * from "./session/session_storage";
 /** Session manager */
 export * from "./session/session_manager";
 /** Management session manager */
-export * from "./session/management_session_manager";
-/** OIDC session manager */
-export * from "./session/oidc_session_manager";
+export * from "./session/cognito_manager";
 /** Signer session manager */
 export * from "./session/signer_session_manager";
 /** Export ethers.js Signer */