@cubist-labs/cubesigner-sdk 0.1.50 → 0.2.2

package/src/ethers/index.ts

@@ -7,15 +7,9 @@ import {
   getBytes,
   toBeHex,
 } from "ethers";
-import {
-  BlobSignRequest,
-  EvmSignRequest,
-  MfaRequestInfo,
-  SignerSession,
-  SignResponse,
-} from "../signer_session";
+import { SignerSession, CubeSignerResponse } from "../signer_session";
+import { BlobSignRequest, EvmSignRequest, MfaRequestInfo } from "../schema_types";
 import { KeyInfo } from "../key";
-import { CubeSigner } from "..";
 
 /** Options for the signer */
 interface SignerOptions {
@@ -31,8 +25,6 @@ interface SignerOptions {
    * updates. Default is 1000ms
    */
   mfaPollIntervalMs?: number;
-  /** Optional management session. Used to check for MFA updates */
-  managementSession?: CubeSigner;
 }
 
 /**
@@ -57,9 +49,6 @@ export class Signer extends ethers.AbstractSigner {
   /** The amount of time to wait between checks for MFA updates */
   readonly #mfaPollIntervalMs: number;
 
-  /** Optional management session, used for MFA flows */
-  readonly #managementSession?: CubeSigner;
-
   /** Create new Signer instance
    * @param {KeyInfo | string} address The key or the eth address of the account to use.
    * @param {SignerSession} signerSession The underlying Signer session.
@@ -76,7 +65,6 @@ export class Signer extends ethers.AbstractSigner {
     this.#signerSession = signerSession;
     this.#onMfaPoll = options?.onMfaPoll ?? ((/* _mfaInfo: MfaRequestInfo */) => {}); // eslint-disable-line @typescript-eslint/no-empty-function
     this.#mfaPollIntervalMs = options?.mfaPollIntervalMs ?? 1000;
-    this.#managementSession = options?.managementSession;
   }
 
   /** Resolves to the signer address. */
@@ -180,17 +168,22 @@ export class Signer extends ethers.AbstractSigner {
   /**
    * If the sign request requires MFA, this method waits for approvals
    *
-   * @param {SignResponse<U>} res The response of a sign request
+   * @param {CubeSignerResponse<U>} res The response of a sign request
    * @return {Promise<U>} The sign data after MFA approvals
    */
-  async #handleMfa<U>(res: SignResponse<U>): Promise<U> {
+  async #handleMfa<U>(res: CubeSignerResponse<U>): Promise<U> {
     while (res.requiresMfa()) {
       await new Promise((resolve) => setTimeout(resolve, this.#mfaPollIntervalMs));
 
-      const mfaInfo = await this.#signerSession.getMfaInfo(this.#managementSession!, res.mfaId());
+      const mfaId = res.mfaId();
+      const mfaInfo = await this.#signerSession.getMfaInfo(mfaId);
       this.#onMfaPoll(mfaInfo);
       if (mfaInfo.receipt) {
-        res = await res.signWithMfaApproval(mfaInfo);
+        res = await res.signWithMfaApproval({
+          mfaId,
+          mfaOrgId: this.#signerSession.orgId,
+          mfaConf: mfaInfo.receipt.confirmation,
+        });
       }
     }
     return res.data();

package/src/index.ts

@@ -1,14 +1,21 @@
 import { envs, EnvInterface } from "./env";
-import { components, Client, paths } from "./client";
+import { Client, CubeSignerClient, OidcClient } from "./client";
 import { Org } from "./org";
 import { JsonFileSessionStorage } from "./session/session_storage";
 
 import { SignerSessionStorage, SignerSessionManager } from "./session/signer_session_manager";
-import { MfaRequestInfo, SignResponse, SignerSession } from "./signer_session";
+import { CubeSignerResponse, 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 { MfaReceipt } from "./mfa";
+import {
+  IdentityProof,
+  MfaRequestInfo,
+  OidcAuthResponse,
+  RatchetConfig,
+  UserInfo,
+} from "./schema_types";
 
 /** CubeSigner constructor options */
 export interface CubeSignerOptions {
@@ -16,28 +23,41 @@ export interface CubeSignerOptions {
   env?: EnvInterface;
   /** The management authorization token */
   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"];
-
-type OidcAuthResponse =
-  paths["/v0/org/{org_id}/oidc"]["post"]["responses"]["200"]["content"]["application/json"];
-
-/** CubeSigner client */
+/**
+ * CubeSigner client
+ *
+ * @deprecated Use {@link CubeSignerClient} instead.
+ */
 export class CubeSigner {
   readonly #env: EnvInterface;
   readonly sessionMgr?: CognitoSessionManager | SignerSessionManager;
+  #csc: CubeSignerClient;
 
   /** @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.#csc = this.#csc.withOrg(orgId);
+  }
+
   /**
    * Loads an existing management session and creates a CubeSigner instance.
+   *
    * @param {CognitoSessionStorage} storage Optional session storage to load
    * the session from. If not specified, the management session from the config
    * directory will be loaded.
@@ -68,7 +88,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;
@@ -77,10 +97,21 @@ export class CubeSigner {
       env = env ?? this.sessionMgr.env;
     }
     this.#env = env ?? envs["gamma"];
+    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
@@ -99,30 +130,13 @@ export class CubeSigner {
     return await SignerSessionManager.createFromSessionInfo(this.env, orgId, resp.data(), storage);
   }
 
-  /** Retrieves information about the current user. */
-  async aboutMe(): Promise<UserInfo> {
-    const resp = await (
-      await this.management()
-    ).get("/v0/about_me", {
-      parseAs: "json",
-    });
-    const data = assertOk(resp);
-    return data;
-  }
-
   /**
-   * Creates and sets a new TOTP configuration for the logged in user,
-   * if and only if no TOTP configuration is already set.
+   * Retrieves information about the current user.
    *
-   * @return {Promise<TotpInfo>} Newly created TOTP configuration.
+   * @return {Promise<UserInfo>} User information.
    */
-  async initTotp(): Promise<TotpInfo> {
-    const resp = await (
-      await this.management()
-    ).put("/v0/totp", {
-      parseAs: "json",
-    });
-    return assertOk(resp);
+  async aboutMe(): Promise<UserInfo> {
+    return await this.#csc.userGet();
   }
 
   /**
@@ -133,56 +147,79 @@ 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);
   }
 
   /**
-   * 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> {
-    const resp = await (
-      await this.management()
-    ).patch("/v0/totp", {
-      parseAs: "json",
-    });
-    return assertOk(resp);
+  async mfaList(orgId: string): Promise<MfaRequestInfo[]> {
+    return await this.#csc.withOrg(orgId).mfaList();
+  }
+
+  /**
+   * 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> {
+    return await this.#csc.withOrg(orgId).mfaApprove(mfaId);
+  }
+
+  /** Initiate adding a new FIDO device. MFA may be required. */
+  get addFidoStart() {
+    return this.#csc.userRegisterFidoInit.bind(this.#csc);
+  }
+
+  /** Complete a previously initiated request to add a new FIDO device. */
+  get addFidoComplete() {
+    return this.#csc.userRegisterFidoComplete.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`
+   */
+  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.he TOTP configuration from the challenge.
+   */
+  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 resp = await (
-      await this.management()
-    ).get("/v0/totp/verify/{code}", {
-      params: { path: { code } },
-      parseAs: "json",
-    });
-    assertOk(resp);
+  get verifyTotp() {
+    return this.#csc.userVerifyTotp.bind(this.#csc);
   }
 
   /** Retrieves 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",
-    });
+  async getOrg(orgId?: string): Promise<Org> {
+    const orgInfo = await this.#csc.withOrg(orgId).orgGet();
+    return new Org(this.#csc, orgInfo);
+  }
 
-    const data = assertOk(resp);
-    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) {
+    await this.#csc.withOrg(orgId).keyDelete(keyId);
   }
 
   /** Get the management client.
@@ -196,6 +233,38 @@ 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> {
+    return await this.#csc.withOrg(orgId).identityProve();
+  }
+
+  /**
+   * 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 oidcClient = new OidcClient(this.#env, orgId, oidcToken);
+    return await oidcClient.identityProve();
+  }
+
+  /**
+   * 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) {
+    await this.#csc.withOrg(orgId).identityVerify(identityProof);
+  }
+
   /**
    * Exchange an OIDC token for a CubeSigner session token.
    * @param {string} oidcToken The OIDC token
@@ -203,7 +272,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<OidcAuthResponse>>} The session data.
    */
   async oidcLogin(
     oidcToken: string,
@@ -211,41 +280,14 @@ 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.mfaId, mfaReceipt.mfaConf)
-      : undefined;
-    return new SignResponse(orgId, loginFn, await loginFn(h1));
+  ): Promise<CubeSignerResponse<OidcAuthResponse>> {
+    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;
-  /** MFA confirmation code */
-  mfaConf: string;
-}
-
+/** Client */
+export * from "./client";
 /** Organizations */
 export * from "./org";
 /** Keys */
@@ -254,6 +296,12 @@ export * from "./key";
 export * from "./role";
 /** Env */
 export * from "./env";
+/** Fido */
+export * from "./mfa";
+/** Pagination */
+export * from "./paginator";
+/** Types */
+export * from "./schema_types";
 /** Sessions */
 export * from "./signer_session";
 /** Session storage */

package/src/key.ts

@@ -1,6 +1,6 @@
-import { CubeSigner, KeyPolicy } from ".";
-import { components } from "./client";
-import { assertOk } from "./util";
+import { KeyPolicy } from "./role";
+import { KeyInfoApi, KeyTypeApi, UpdateKeyRequest, SchemaKeyType } from "./schema_types";
+import { CubeSignerClient } from "./client";
 
 /** Secp256k1 key type */
 export enum Secp256k1 {
@@ -23,6 +23,7 @@ export enum Ed25519 {
   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 */
@@ -36,13 +37,6 @@ export type Stark = typeof Stark;
 /** Key type */
 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 KeyInfoApi = components["schemas"]["KeyInfo"];
-type KeyTypeApi = components["schemas"]["KeyType"];
-
 /** Additional properties (for backward compatibility) */
 export interface KeyInfo extends KeyInfoApi {
   /** Alias for key_id */
@@ -75,9 +69,13 @@ export function toKeyInfo(key: KeyInfoApi): KeyInfo {
 /** Signing keys. */
 export class Key {
   /** The CubeSigner instance that this key is associated with */
-  readonly #cs: CubeSigner;
+  readonly #csc: CubeSignerClient;
+
   /** The organization that this key is in */
-  readonly orgId: string;
+  get orgId() {
+    return this.#csc.orgId;
+  }
+
   /**
    * 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)
@@ -163,124 +161,37 @@ export class Key {
     await this.update({ owner });
   }
 
+  /**
+   * Delete this key.
+   */
+  async delete() {
+    await this.#csc.keyDelete(this.id);
+  }
+
   // --------------------------------------------------------------------------
   // -- 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 {CubeSignerClient} csc The CubeSigner instance to use for signing.
    * @param {KeyInfo} data The JSON response from the API server.
    * @internal
    * */
-  constructor(cs: CubeSigner, orgId: string, data: KeyInfoApi) {
-    this.#cs = cs;
-    this.orgId = orgId;
+  constructor(csc: CubeSignerClient, data: KeyInfoApi) {
+    this.#csc = csc;
     this.id = data.key_id;
     this.materialId = data.material_id;
     this.publicKey = data.public_key;
   }
 
-  /** Update the 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 toKeyInfo(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) => new Key(cs, orgId, k));
-  }
-
-  /**
-   * Derives a key of a specified type using a supplied derivation path and an existing long-lived 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.
-   * @param {string?} ownerId The owner of newly derived keys. Defaults to the session's user.
-   *
-   * @return {Key[]} The newly derived keys.
    */
-  static async deriveKeys(
-    cs: CubeSigner,
-    orgId: string,
-    keyType: KeyType,
-    derivationPaths: string[],
-    mnemonicId: string,
-    ownerId?: 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,
-        owner: ownerId || null,
-      },
-      parseAs: "json",
-    });
-    const data = assertOk(resp);
-    return data.keys.map((k) => 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);
+  private async update(request: UpdateKeyRequest): Promise<KeyInfo> {
+    const data = await this.#csc.keyUpdate(this.id, request);
+    return toKeyInfo(data);
   }
 
   /** Fetches the key information.
@@ -288,13 +199,7 @@ export class Key {
    * @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);
+    const data = await this.#csc.keyGet(this.id);
     return toKeyInfo(data);
   }
 }
@@ -328,6 +233,8 @@ export function fromSchemaKeyType(ty: SchemaKeyType): KeyType {
       return Ed25519.Aptos;
     case "Ed25519CardanoAddrVk":
       return Ed25519.Cardano;
+    case "Ed25519StellarAddr":
+      return Ed25519.Stellar;
     case "Stark":
       return Stark;
     case "Mnemonic":