@cubist-labs/cubesigner-sdk 0.2.2 → 0.2.15

package/src/schema_types.ts

@@ -78,6 +78,13 @@ export type BtcSignatureKind = schemas["BtcSignatureKind"];
 export type MfaType = schemas["MfaType"];
 export type MfaRequestInfo = schemas["MfaRequestInfo"];
 
+export type UserExportInitRequest = schemas["UserExportInitRequest"];
+export type UserExportInitResponse = schemas["UserExportInitResponse"];
+export type UserExportCompleteRequest = schemas["UserExportCompleteRequest"];
+export type UserExportCompleteResponse = schemas["UserExportCompleteResponse"];
+export type UserExportListResponse = schemas["PaginatedUserExportListResponse"];
+export type UserExportKeyMaterial = schemas["JsonKeyPackage"];
+
 /** Options for a new OIDC user */
 export interface CreateOidcUserOptions {
   /** The role of an OIDC user, default is "Alien" */

package/src/session/cognito_manager.ts

@@ -1,10 +1,14 @@
-import { Client } from "../client";
+import path from "path";
+import { Client } from "../api";
 import { EnvInterface } from "../env";
-import { HasEnv, SessionManager } from "./session_manager";
-import { SessionStorage } from "./session_storage";
+import { HasEnv, OrgSessionManager } from "./session_manager";
+import { JsonFileSessionStorage, SessionStorage } from "./session_storage";
+import { configDir } from "../util";
 
 /** JSON representation of our "management session" file format */
 export interface CognitoSessionObject {
+  /** The organization ID */
+  org_id: string;
   /** The email address of the user */
   email: string;
   /** The ID token */
@@ -23,7 +27,7 @@ export interface CognitoSessionInfo extends CognitoSessionObject, HasEnv {}
 export type CognitoSessionStorage = SessionStorage<CognitoSessionInfo>;
 
 /** The session manager for cognito (management) sessions */
-export class CognitoSessionManager extends SessionManager<CognitoSessionInfo> {
+export class CognitoSessionManager extends OrgSessionManager<CognitoSessionInfo> {
   #client: Client;
 
   /**
@@ -116,19 +120,42 @@ export class CognitoSessionManager extends SessionManager<CognitoSessionInfo> {
     const sessionInfo = await storage.retrieve();
     return new CognitoSessionManager(
       sessionInfo.env["Dev-CubeSignerStack"],
+      sessionInfo.org_id,
       sessionInfo.id_token,
       storage,
     );
   }
 
+  /**
+   * Loads an existing management session and creates a Cognito session manager for it.
+   *
+   * @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<CognitoSessionManager>} Cognito session manager
+   */
+  static async loadManagementSession(
+    storage?: CognitoSessionStorage,
+  ): Promise<CognitoSessionManager> {
+    return await CognitoSessionManager.loadFromStorage(
+      storage ?? new JsonFileSessionStorage(path.join(configDir(), "management-session.json")),
+    );
+  }
+
   /**
    * Constructor.
    * @param {EnvInterface} env The environment of the session
+   * @param {string} orgId The id of the org associated with this session
    * @param {string} token The current token of the session
    * @param {CognitoSessionStorage} storage The storage back end to use
    */
-  private constructor(env: EnvInterface, token: string, storage: CognitoSessionStorage) {
-    super(env, storage);
+  private constructor(
+    env: EnvInterface,
+    orgId: string,
+    token: string,
+    storage: CognitoSessionStorage,
+  ) {
+    super(env, orgId, storage);
     this.#client = this.createClient(token);
   }
 }

package/src/session/session_manager.ts

@@ -1,7 +1,6 @@
 import { SessionStorage } from "..";
 import { EnvInterface } from "../env";
-import { Client, paths } from "../client";
-import createClient from "openapi-fetch";
+import { Client, createHttpClient } from "../api";
 
 const DEFAULT_EXPIRATION_BUFFER_SECS = 30;
 
@@ -83,12 +82,7 @@ export abstract class SessionManager<U> {
    * @return {Client} The new REST client
    */
   protected createClient(token: string): Client {
-    return createClient<paths>({
-      baseUrl: this.env.SignerApiRoot,
-      headers: {
-        Authorization: token,
-      },
-    });
+    return createHttpClient(this.env.SignerApiRoot, token);
   }
 
   /**

package/src/session/signer_session_manager.ts

@@ -4,7 +4,7 @@ import {
   NewSessionResponse,
   RefreshSignerSessionRequest,
 } from "../schema_types";
-import { Client } from "../client";
+import { Client } from "../api";
 import { HasEnv, OrgSessionManager } from "./session_manager";
 import { MemorySessionStorage, SessionStorage } from "./session_storage";
 import { assertOk } from "../util";
@@ -62,13 +62,6 @@ export class SignerSessionManager extends OrgSessionManager<SignerSessionData> {
     return this.#client;
   }
 
-  /**
-   * @return {Client} A client using the current session (without attempting to refresh it).
-   */
-  clientNoRefresh(): Client {
-    return this.#client;
-  }
-
   /** Revokes the session. */
   async revoke(): Promise<void> {
     const client = await this.client();
@@ -158,9 +151,9 @@ export class SignerSessionManager extends OrgSessionManager<SignerSessionData> {
    * Constructor.
    *
    * @param {SignerSessionData} sessionData Session data
-   * @param {SignerSessionStorage} storage The session storage to use
+   * @param {SignerSessionStorage} storage The session storage to use.
    */
-  constructor(sessionData: SignerSessionData, storage: SignerSessionStorage) {
+  private constructor(sessionData: SignerSessionData, storage: SignerSessionStorage) {
     super(sessionData.env["Dev-CubeSignerStack"], sessionData.org_id, storage);
     this.#client = this.createClient(sessionData.token);
   }

package/src/signer_session.ts

@@ -1,180 +1,7 @@
-import assert from "assert";
-import { CubeSigner, toKeyInfo, MfaReceipt, KeyInfo } from ".";
 import { CubeSignerClient } from "./client";
-import { AcceptedResponse, NewSessionResponse } from "./schema_types";
+import { KeyInfo, toKeyInfo } from "./key";
 import { SignerSessionManager, SignerSessionStorage } from "./session/signer_session_manager";
 
-type Response<U> = U | AcceptedResponse;
-type RequestFn<U> = (headers?: HeadersInit) => Promise<Response<U>>;
-type MapFn<U, V> = (u: U) => V;
-
-/**
- * Takes a {@link Response<U>} and a {@link MapFn<U, V>} function and returns
- * a {@link Response<V>} that maps the value of the original response when its status code is 200.
- *
- * @param {Response<U>} resp Original response
- * @param {Map<U, V>} mapFn Map to apply to the response value when its status code is 200.
- * @return {Response<V>} Response whose value for status code 200 is mapped from U to V
- */
-export function mapResponse<U, V>(resp: Response<U>, mapFn: MapFn<U, V>): Response<V> {
-  if ((resp as AcceptedResponse).accepted?.MfaRequired) {
-    return resp as AcceptedResponse;
-  } else {
-    return mapFn(resp as U);
-  }
-}
-
-export interface MfaRequired {
-  /** Org id */
-  org_id: string;
-  /** MFA request id */
-  id: string;
-  /** Optional MFA session */
-  session?: NewSessionResponse | null;
-}
-
-/**
- * A response of a CubeSigner request.
- */
-export class CubeSignerResponse<U> {
-  readonly #requestFn: RequestFn<U>;
-  readonly #resp: U | AcceptedResponse;
-  /**
-   * Optional MFA id. Only set if there is an MFA request associated with the
-   * signing request
-   */
-  readonly #mfaRequired?: MfaRequired;
-
-  /** @return {string} The MFA id associated with this request */
-  mfaId(): string {
-    return this.#mfaRequired!.id;
-  }
-
-  /** @return {boolean} True if this request requires an MFA approval */
-  requiresMfa(): boolean {
-    return this.#mfaRequired !== undefined;
-  }
-
-  /**
-   * Returns session information to use for any MFA approval requests (if any was included in the response).
-   * @return {ClientSessionInfo | undefined}
-   */
-  mfaSessionInfo(): NewSessionResponse | undefined {
-    return (this.#resp as AcceptedResponse).accepted?.MfaRequired?.session ?? undefined;
-  }
-
-  /** @return {U} The response data, if no MFA is required */
-  data(): U {
-    if (this.requiresMfa()) {
-      throw new Error("Cannot call `data()` while MFA is required");
-    }
-    return this.#resp as U;
-  }
-
-  /**
-   * Approves the MFA request using a given session and a TOTP code.
-   *
-   * @param {SignerSession} session Signer session to use
-   * @param {string} code 6-digit TOTP code
-   * @return {CubeSignerResponse<U>} The result of signing with the approval
-   */
-  async approveTotp(session: SignerSession, code: string): Promise<CubeSignerResponse<U>> {
-    assert(this.requiresMfa());
-    const mfaId = this.mfaId();
-    const mfaOrgId = this.#mfaRequired!.org_id;
-    const mfaApproval = await session.totpApprove(mfaId, code);
-    assert(mfaApproval.id === mfaId);
-    const mfaConf = mfaApproval.receipt?.confirmation;
-
-    if (!mfaConf) {
-      return this;
-    }
-
-    return await this.signWithMfaApproval({ mfaId, mfaOrgId, mfaConf });
-  }
-
-  /**
-   * Approves the MFA request using a given `CubeSignerClient` instance (i.e., its session).
-   *
-   * @param {CubeSigner} cs CubeSigner whose session to use
-   * @return {CubeSignerResponse<U>} The result of signing with the approval
-   */
-  async approve(cs: CubeSigner): Promise<CubeSignerResponse<U>> {
-    assert(this.requiresMfa());
-    const mfaId = this.#mfaRequired!.id;
-    const mfaOrgId = this.#mfaRequired!.org_id;
-
-    const mfaApproval = await cs.mfaApprove(mfaOrgId, mfaId);
-    assert(mfaApproval.id === mfaId);
-    const mfaConf = mfaApproval.receipt?.confirmation;
-
-    if (!mfaConf) {
-      return this;
-    }
-
-    return await this.signWithMfaApproval({ mfaId, mfaOrgId, mfaConf });
-  }
-
-  /**
-   * @param {MfaReceipt} mfaReceipt The MFA receipt
-   * @return {Promise<CubeSignerResponse<U>>} The result of signing after MFA approval
-   */
-  async signWithMfaApproval(mfaReceipt: MfaReceipt): Promise<CubeSignerResponse<U>> {
-    const headers = CubeSignerResponse.getMfaHeaders(mfaReceipt);
-    return new CubeSignerResponse(this.#requestFn, await this.#requestFn(headers));
-  }
-
-  // --------------------------------------------------------------------------
-  // -- INTERNAL --------------------------------------------------------------
-  // --------------------------------------------------------------------------
-
-  /**
-   * Constructor.
-   *
-   * @param {RequestFn} requestFn
-   *    The signing function that this response is from.
-   *    This argument is used to resend requests with different headers if needed.
-   * @param {U | AcceptedResponse} resp The response as returned by the OpenAPI client.
-   */
-  constructor(requestFn: RequestFn<U>, resp: U | AcceptedResponse) {
-    this.#requestFn = requestFn;
-    this.#resp = resp;
-    this.#mfaRequired = (this.#resp as AcceptedResponse).accepted?.MfaRequired;
-  }
-
-  /**
-   * Static constructor.
-   * @param {RequestFn} requestFn
-   *    The request function that this response is from.
-   *    This argument is used to resend requests with different headers if needed.
-   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
-   * @return {Promise<CubeSignerResponse<U>>} New instance of this class.
-   */
-  static async create<U>(
-    requestFn: RequestFn<U>,
-    mfaReceipt?: MfaReceipt,
-  ): Promise<CubeSignerResponse<U>> {
-    const seed = await requestFn(this.getMfaHeaders(mfaReceipt));
-    return new CubeSignerResponse(requestFn, seed);
-  }
-
-  /**
-   * Returns HTTP headers containing a given MFA receipt.
-   *
-   * @param {MfaReceipt} mfaReceipt MFA receipt
-   * @return {HeadersInit} Headers including that receipt
-   */
-  static getMfaHeaders(mfaReceipt?: MfaReceipt): HeadersInit | undefined {
-    return mfaReceipt
-      ? {
-          "x-cubist-mfa-id": mfaReceipt.mfaId,
-          "x-cubist-mfa-org-id": mfaReceipt.mfaOrgId,
-          "x-cubist-mfa-confirmation": mfaReceipt.mfaConf,
-        }
-      : undefined;
-  }
-}
-
 /** Signer session info. Can only be used to revoke a token, but not for authentication. */
 export class SignerSessionInfo {
   readonly #csc: CubeSignerClient;
@@ -206,93 +33,9 @@ export class SignerSessionInfo {
 
 /**
  * Signer session.
- *
- * @deprecated Use {@link CubeSignerClient} instead.
+ * Extends {@link CubeSignerClient} and provides a few convenience methods on top.
  */
-export class SignerSession {
-  readonly #csc: CubeSignerClient;
-
-  /** Deprecated */
-  get sessionMgr() {
-    return this.#csc.sessionMgr;
-  }
-
-  /** Org id */
-  get orgId() {
-    return this.#csc.orgId;
-  }
-
-  /**
-   * Returns the list of keys that this token grants access to.
-   * @return {KeyInfo[]} The list of keys.
-   */
-  async keys(): Promise<KeyInfo[]> {
-    const keys = await this.#csc.sessionKeysList();
-    return keys.map((k) => toKeyInfo(k));
-  }
-
-  /** Approve a pending MFA request using TOTP. */
-  get totpApprove() {
-    return this.#csc.mfaApproveTotp.bind(this.#csc);
-  }
-
-  /** Initiate approval of an existing MFA request using FIDO. */
-  get fidoApproveStart() {
-    return this.#csc.mfaApproveFidoInit.bind(this.#csc);
-  }
-
-  /** Get a pending MFA request by its id. */
-  get getMfaInfo() {
-    return this.#csc.mfaGet.bind(this.#csc);
-  }
-
-  /** Submit an EVM sign request. */
-  get signEvm() {
-    return this.#csc.signEvm.bind(this.#csc);
-  }
-
-  /** Submit an 'eth2' sign request. */
-  get signEth2() {
-    return this.#csc.signEth2.bind(this.#csc);
-  }
-
-  /** Sign a stake request. */
-  get stake() {
-    return this.#csc.signStake.bind(this.#csc);
-  }
-
-  /** Sign an unstake request. */
-  get unstake() {
-    return this.#csc.signUnstake.bind(this.#csc);
-  }
-
-  /** Sign a raw blob.*/
-  get signBlob() {
-    return this.#csc.signBlob.bind(this.#csc);
-  }
-
-  /** Sign a bitcoin message. */
-  get signBtc() {
-    return this.#csc.signBtc.bind(this.#csc);
-  }
-
-  /** Sign a solana message. */
-  get signSolana() {
-    return this.#csc.signSolana.bind(this.#csc);
-  }
-
-  /** Sign an Avalanche P- or X-chain message. */
-  get signAva() {
-    return this.#csc.signAva.bind(this.#csc);
-  }
-
-  /**
-   * Obtain a proof of authentication.
-   */
-  get proveIdentity() {
-    return this.#csc.identityProve.bind(this.#csc);
-  }
-
+export class SignerSession extends CubeSignerClient {
   /**
    * Loads an existing signer session from storage.
    * @param {SignerSessionStorage} storage The session storage to use
@@ -309,6 +52,15 @@ export class SignerSession {
    * @internal
    */
   constructor(sessionMgr: SignerSessionManager) {
-    this.#csc = new CubeSignerClient(sessionMgr);
+    super(sessionMgr);
+  }
+
+  /**
+   * Returns the list of keys that this token grants access to.
+   * @return {KeyInfo[]} The list of keys.
+   */
+  async keys(): Promise<KeyInfo[]> {
+    const keys = await this.sessionKeysList();
+    return keys.map((k) => toKeyInfo(k));
   }
 }

package/src/user_export.ts

@@ -0,0 +1,116 @@
+import { UserExportCompleteResponse, UserExportKeyMaterial } from "./schema_types";
+import { decodeBase64 } from "./util";
+import type { CipherSuite } from "@hpke/core";
+
+/** Get the HPKE ciphersuite for user-export decryption.
+ *
+ * @return {any} The HPKE ciphersuite for user export.
+ */
+export async function userExportCipherSuite(): Promise<CipherSuite> {
+  const hpke = await import("@hpke/core"); // eslint-disable-line @typescript-eslint/no-var-requires
+  const suite = new hpke.CipherSuite({
+    kem: new hpke.DhkemP256HkdfSha256(),
+    kdf: new hpke.HkdfSha256(),
+    aead: new hpke.Aes256Gcm(),
+  });
+  return suite;
+}
+
+/**
+ * Generate a key pair for user export.
+ *
+ * @return {Promise<CryptoKeyPair>} The newly generated key pair.
+ */
+export async function userExportKeygen(): Promise<CryptoKeyPair> {
+  return (await userExportCipherSuite()).kem.generateKeyPair();
+}
+
+/**
+ * Get the ArrayBuffer slice represented by a Buffer
+ *
+ * @param {Uint8Array} b The buffer to convert
+ * @return {ArrayBuffer} The resulting ArrayBuffer
+ */
+function toArrayBuffer(b: Uint8Array): ArrayBuffer {
+  return b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
+}
+
+/**
+ * Decrypt a user export.
+ *
+ * @param {CryptoKey} recipientKey The NIST P-256 secret key corresponding to the `publicKey` argument to the `userExportComplete` invocation that returned `response`.
+ * @param {UserExportCompleteResponse} response The response from a successful `userExportComplete` request.
+ * @return {Promise<UserExportKeyMaterial>} The decrypted key material.
+ */
+export async function userExportDecrypt(
+  recipientKey: CryptoKey,
+  response: UserExportCompleteResponse,
+): Promise<UserExportKeyMaterial> {
+  // The ciphersuite we use for decryption
+  const suite = await userExportCipherSuite();
+
+  // decrypt the export ciphertext using the HPKE one-shot API
+  const tenc = new TextEncoder();
+  const tdec = new TextDecoder();
+  const info = toArrayBuffer(tenc.encode(`cubist-signer::UserExportOwner::${response.user_id}`));
+  const public_key = toArrayBuffer(decodeBase64(response.ephemeral_public_key));
+  const ctxt = toArrayBuffer(decodeBase64(response.encrypted_key_material));
+  const decrypted: UserExportKeyMaterial = JSON.parse(
+    tdec.decode(
+      await suite.open(
+        {
+          recipientKey,
+          enc: public_key,
+          info: info,
+        },
+        ctxt,
+      ),
+    ),
+  );
+
+  return decrypted;
+}
+
+/**
+ * Figure out how to load SubtleCrypto in the current environment.
+ *
+ * This functionality is reproduced from the hpke-js package,
+ *   https://github.com/dajiaji/hpke-js/
+ * which is Copyright (C) 2022 Ajitomi Daisuke and licensed
+ * under the MIT License, which follows:
+ *
+ * MIT License
+ *
+ * Copyright (c) 2022 Ajitomi Daisuke
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+export async function loadSubtleCrypto() {
+  if (globalThis !== undefined && globalThis.crypto !== undefined) {
+    // Browsers, Node.js >= v19, Cloudflare Workers, Bun, etc.
+    return globalThis.crypto.subtle;
+  }
+  // Node.js <= v18
+  try {
+    const { webcrypto } = await import("crypto"); // node:crypto
+    return (webcrypto as unknown as Crypto).subtle;
+  } catch (e: unknown) {
+    throw new Error("subtle crypto not supported");
+  }
+}

package/src/util.ts

@@ -65,6 +65,18 @@ export function assertOk<D, T>(resp: ResponseType<D, T>, description?: string):
   return resp.data;
 }
 
+/**
+ * Browser-friendly helper for decoding a 'base64'-encoded string into a byte array.
+ *
+ * @param {string} b64 The 'base64'-encoded string to decode
+ * @return {Uint8Array} Decoded byte array
+ */
+export function decodeBase64(b64: string): Uint8Array {
+  return typeof Buffer === "function"
+    ? Buffer.from(b64, "base64")
+    : Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+}
+
 /**
  * Browser-friendly helper for decoding a 'base64url'-encoded string into a byte array.
  *
@@ -72,28 +84,35 @@ export function assertOk<D, T>(resp: ResponseType<D, T>, description?: string):
  * @return {Uint8Array} Decoded byte array
  */
 export function decodeBase64Url(b64url: string): Uint8Array {
-  const b64 = b64url.replace(/-/g, "+").replace(/_/g, "/").replace(/=*$/g, "");
-
   // NOTE: there is no "base64url" encoding in the "buffer" module for the browser (unlike in node.js)
-  return typeof Buffer === "function"
-    ? Buffer.from(b64, "base64")
-    : Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+  const b64 = b64url.replace(/-/g, "+").replace(/_/g, "/").replace(/=*$/g, "");
+  return decodeBase64(b64);
 }
 
 /**
- * Browser-friendly helper for encoding a byte array into a 'base64url`-encoded string.
+ *
+ * Browser-friendly helper for encoding a byte array into a padded `base64`-encoded string.
  *
  * @param {Iterable<number>} buffer The byte array to encode
- * @return {string} The 'base64url' encoding of the byte array.
+ * @return {string} The 'base64' encoding of the byte array.
  */
-export function encodeToBase64Url(buffer: Iterable<number>): string {
+export function encodeToBase64(buffer: Iterable<number>): string {
   const bytes = new Uint8Array(buffer);
-
-  // NOTE: there is no "base64url" encoding in the "buffer" module for the browser (unlike in node.js)
   const b64 =
     typeof Buffer === "function"
       ? Buffer.from(bytes).toString("base64")
       : btoa(bytes.reduce((s, b) => s + String.fromCharCode(b), ""));
+  return b64;
+}
 
+/**
+ * Browser-friendly helper for encoding a byte array into a 'base64url`-encoded string.
+ *
+ * @param {Iterable<number>} buffer The byte array to encode
+ * @return {string} The 'base64url' encoding of the byte array.
+ */
+export function encodeToBase64Url(buffer: Iterable<number>): string {
+  const b64 = encodeToBase64(buffer);
+  // NOTE: there is no "base64url" encoding in the "buffer" module for the browser (unlike in node.js)
   return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=*$/g, "");
 }