@cubist-labs/cubesigner-sdk 0.2.24 → 0.3.1

package/package.json

@@ -1,68 +1,41 @@
 {
   "name": "@cubist-labs/cubesigner-sdk",
-  "author": "Cubist, Inc.",
-  "version": "0.2.24",
+  "version": "0.3.1",
   "description": "CubeSigner TypeScript SDK",
-  "homepage": "https://github.com/cubist-labs/CubeSigner-TypeScript-SDK",
-  "bugs": "https://github.com/cubist-labs/CubeSigner-TypeScript-SDK/issues",
   "license": "MIT OR Apache-2.0",
+  "author": "Cubist, Inc.",
+  "main": "dist/cjs/src/index.js",
   "files": [
     "tsconfig.json",
     "src/**",
     "dist/**",
-    "NOTICE",
-    "LICENSE-APACHE",
-    "LICENSE-MIT"
+    "../..NOTICE",
+    "../..LICENSE-APACHE",
+    "../..LICENSE-MIT"
   ],
-  "main": "dist/src/index.js",
-  "types": "dist/src/index.d.ts",
+  "exports": {
+    "require": "./dist/cjs/src/index.js",
+    "import": "./dist/esm/src/index.js"
+  },
   "scripts": {
-    "build": "tsc",
+    "build": "npm run build:cjs && npm run build:mjs",
+    "prepack": "npm run build",
+    "build:cjs": "tsc -p . --outDir dist/cjs --module commonjs --moduleResolution node",
+    "build:mjs": "tsc -p . --outDir dist/esm --module es2022",
+    "gen-schema": "openapi-typescript ./spec/openapi.json --output ./src/schema.ts",
     "test": "jest --maxWorkers=1",
-    "prepack": "tsc",
-    "typedoc": "typedoc",
-    "fix": "eslint . --ext .ts --fix",
-    "lint": "eslint . --ext .ts",
-    "fmt": "prettier --write .",
-    "fmt-check": "prettier --check .",
-    "gen-schema": "npx openapi-typescript ./spec/openapi.json --output ./src/schema.ts"
+    "typedoc": "typedoc"
   },
   "dependencies": {
-    "ethers": "6.7.1",
     "openapi-fetch": "0.6.1"
   },
-  "devDependencies": {
-    "@hpke/core": "^1.2.5",
-    "@types/chai": "^4.3.11",
-    "@types/chai-as-promised": "^7.1.8",
-    "@types/jest": "^29.5.10",
-    "@types/node": "^20.10.4",
-    "@types/node-fetch": "^2.6.9",
-    "@types/tmp": "^0.2.6",
-    "@typescript-eslint/eslint-plugin": "^6.13.1",
-    "chai": "^4.3.10",
-    "chai-as-promised": "^7.1.1",
-    "dotenv": "^16.3.1",
-    "eslint": "^8.55.0",
-    "eslint-config-google": "^0.14.0",
-    "eslint-config-prettier": "^9.1.0",
-    "jest": "^29.7.0",
-    "openapi-typescript": "^6.7.1",
-    "otplib": "^12.0.1",
-    "prettier": "3.1.1",
-    "tmp": "^0.2.1",
-    "ts-jest": "^29.1.0",
-    "ts-node": "^10.9.1",
-    "typescript": "^5.3.3"
-  },
   "optionalDependencies": {
-    "@aws-sdk/client-cognito-identity-provider": "^3.470.0",
     "@hpke/core": "^1.2.5"
   },
-  "prettier": {
-    "printWidth": 100
-  },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "directories": {
+    "test": "test"
   }
 }

package/src/api.ts

@@ -34,6 +34,9 @@ import {
   SessionInfo,
   OrgInfo,
   RatchetConfig,
+  Eip191SignRequest,
+  Eip712SignRequest,
+  Eip191Or712SignResponse,
   EvmSignRequest,
   EvmSignResponse,
   Eth2SignRequest,
@@ -61,6 +64,7 @@ import {
 import { encodeToBase64 } from "./util";
 import { AddFidoChallenge, MfaFidoChallenge, MfaReceipt, TotpChallenge } from "./mfa";
 import { CubeSignerResponse, mapResponse } from "./response";
+import { ErrResponse } from "./error";
 import { Key, KeyType } from "./key";
 import { Page, PageOpts, PageQueryArgs, Paginator } from "./paginator";
 import { KeyPolicy } from "./role";
@@ -110,28 +114,6 @@ export type FetchClient<Op extends keyof operations> = ReturnType<typeof createC
  */
 export type FetchResponseSuccessData<T> = Required<FetchResponse<T>>["data"];
 
-/**
- * Error response type, thrown on non-successful responses.
- */
-export class ErrResponse extends Error {
-  /** Operation that produced this error */
-  readonly operation?: keyof operations;
-  /** HTTP status code text (derived from `this.status`) */
-  readonly statusText?: string;
-  /** HTTP status code */
-  readonly status?: number;
-  /** HTTP response url */
-  readonly url?: string;
-
-  /**
-   * @param {Partial<ErrResponse>} init Initializer
-   */
-  constructor(init: Partial<ErrResponse>) {
-    super(init.message);
-    Object.assign(this, init);
-  }
-}
-
 /**
  * Wrapper around an open-fetch client restricted to a single operation.
  * The restriction applies only when type checking, the actual
@@ -246,9 +228,11 @@ export class OpClient<Op extends keyof operations> {
 export function createHttpClient(baseUrl: string, authToken: string): Client {
   return createClient<paths>({
     baseUrl,
+    cache: "no-store",
     headers: {
       Authorization: authToken,
       ["User-Agent"]: `${NAME}@${VERSION}`,
+      ["X-Cubist-Ts-Sdk"]: `${NAME}@${VERSION}`,
     },
   });
 }
@@ -306,7 +290,7 @@ export class CubeSignerApi {
    * @return {Promise<OpClient<Op>>} The client restricted to {@link op}
    */
   private async client<Op extends keyof operations>(op: Op): Promise<OpClient<Op>> {
-    const fetchClient = await this.#sessionMgr.client();
+    const fetchClient = await this.#sessionMgr.client(op);
     return new OpClient(op, fetchClient, this.#eventEmitter);
   }
 
@@ -1176,6 +1160,64 @@ export class CubeSignerApi {
     return await CubeSignerResponse.create(signFn, mfaReceipt);
   }
 
+  /**
+   * Sign EIP-191 typed data.
+   *
+   * This requires the key to have a '"AllowEip191Signing"' {@link KeyPolicy}.
+   *
+   * @param {Key | string} key The key to sign with (either {@link Key} or its material ID).
+   * @param {BlobSignRequest} req What to sign
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
+   * @return {Promise<EvmSignResponse | AcceptedResponse>} Signature (or MFA approval request).
+   */
+  async signEip191(
+    key: Key | string,
+    req: Eip191SignRequest,
+    mfaReceipt?: MfaReceipt,
+  ): Promise<CubeSignerResponse<Eip191Or712SignResponse>> {
+    const pubkey = typeof key === "string" ? (key as string) : key.materialId;
+    const signFn = async (headers?: HeadersInit) => {
+      const client = await this.client("eip191Sign");
+      return await client.post("/v0/org/{org_id}/evm/eip191/sign/{pubkey}", {
+        params: {
+          path: { org_id: this.orgId, pubkey },
+        },
+        body: req,
+        headers,
+      });
+    };
+    return await CubeSignerResponse.create(signFn, mfaReceipt);
+  }
+
+  /**
+   * Sign EIP-712 typed data.
+   *
+   * This requires the key to have a '"AllowEip712Signing"' {@link KeyPolicy}.
+   *
+   * @param {Key | string} key The key to sign with (either {@link Key} or its material ID).
+   * @param {BlobSignRequest} req What to sign
+   * @param {MfaReceipt} mfaReceipt Optional MFA receipt
+   * @return {Promise<EvmSignResponse | AcceptedResponse>} Signature (or MFA approval request).
+   */
+  async signEip712(
+    key: Key | string,
+    req: Eip712SignRequest,
+    mfaReceipt?: MfaReceipt,
+  ): Promise<CubeSignerResponse<Eip191Or712SignResponse>> {
+    const pubkey = typeof key === "string" ? (key as string) : key.materialId;
+    const signFn = async (headers?: HeadersInit) => {
+      const client = await this.client("eip712Sign");
+      return await client.post("/v0/org/{org_id}/evm/eip712/sign/{pubkey}", {
+        params: {
+          path: { org_id: this.orgId, pubkey },
+        },
+        body: req,
+        headers,
+      });
+    };
+    return await CubeSignerResponse.create(signFn, mfaReceipt);
+  }
+
   /**
    * Sign an Eth2/Beacon-chain validation message.
    *
@@ -1478,6 +1520,22 @@ export class CubeSignerApi {
     return await CubeSignerResponse.create(completeFn, mfaReceipt);
   }
   // #endregion
+
+  // #region MISC: heartbeat()
+  /**
+   * Send a heartbeat / upcheck request.
+   *
+   * @return { Promise<void> } The response.
+   */
+  async heartbeat(): Promise<void> {
+    const client = await this.client("cube3signerHeartbeat");
+    await client.post("/v1/org/{org_id}/cube3signer/heartbeat", {
+      params: {
+        path: { org_id: this.orgId },
+      },
+    });
+  }
+  // #endregion
 }
 
 /**

package/src/client.ts

@@ -1,5 +1,4 @@
 import { SignerSessionManager, SignerSessionStorage } from "./session/signer_session_manager";
-import { CognitoSessionManager } from "./session/cognito_manager";
 import { CubeSignerApi, OidcClient } from "./api";
 import { KeyType, Key } from "./key";
 import { OrgInfo, RatchetConfig } from "./schema_types";
@@ -49,15 +48,20 @@ export class CubeSignerClient extends CubeSignerApi {
   /**
    * Loads an existing management session and creates a {@link CubeSignerClient} instance.
    *
+   * @param {SignerSessionStorage} storage Storage from which to load the session
    * @return {Promise<CubeSignerClient>} New CubeSigner instance
    */
-  static async loadManagementSession(): Promise<CubeSignerClient> {
-    const mgr = await CognitoSessionManager.loadManagementSession();
-    // 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.
-    // NOTE: This will go away once `cs login` starts producing signer sessions.
-    return new CubeSignerClient(mgr as unknown as SignerSessionManager);
+  static async loadManagementSession(storage: SignerSessionStorage): Promise<CubeSignerClient> {
+    // Throw and actionable error if the management session file contains a Cognito session
+    const session = await storage.retrieve();
+    if ((session as unknown as { id_token: string }).id_token) {
+      throw new Error(
+        `It appears that the storage contains the old (Cognito) session; please update your session by updating your 'cs' to version 'v0.37.0' or later and then running 'cs login'`,
+      );
+    }
+
+    const mgr = await SignerSessionManager.loadFromStorage(storage);
+    return new CubeSignerClient(mgr);
   }
 
   /**

package/src/error.ts

@@ -0,0 +1,42 @@
+import { operations } from "./schema";
+
+/**
+ * Error response type, thrown on non-successful responses.
+ */
+export class ErrResponse extends Error {
+  /** Operation that produced this error */
+  readonly operation?: keyof operations;
+  /** HTTP status code text (derived from `this.status`) */
+  readonly statusText?: string;
+  /** HTTP status code */
+  readonly status?: number;
+  /** HTTP response url */
+  readonly url?: string;
+
+  /**
+   * @param {Partial<ErrResponse>} init Initializer
+   */
+  constructor(init: Partial<ErrResponse>) {
+    super(init.message);
+    Object.assign(this, init);
+  }
+}
+
+/**
+ * An error that is thrown when a session has expired
+ */
+export class SessionExpiredError extends ErrResponse {
+  /**
+   * Constructor.
+   *
+   * @param {operations} operation The operation that was attempted
+   */
+  constructor(operation?: keyof operations) {
+    super({
+      message: "Session has expired",
+      status: 403,
+      statusText: "Forbidden",
+      operation,
+    });
+  }
+}

package/src/events.ts

@@ -1,7 +1,9 @@
-import { ErrResponse } from "./api";
+import { ErrResponse } from "./error";
 
 export type EventHandler<T> = (event: T) => Promise<void>;
 export type ErrorEvent = ErrResponse;
+
+/* eslint-disable-next-line @typescript-eslint/no-empty-interface */
 export interface SessionExpiredEvent {}
 
 /**

package/src/index.ts

@@ -2,7 +2,6 @@ import { envs, EnvInterface } from "./env";
 import { Client, OidcClient } from "./api";
 import { CubeSignerClient } from "./client";
 import { Org } from "./org";
-import { JsonFileSessionStorage } from "./session/session_storage";
 
 import {
   SignerSessionStorage,
@@ -11,9 +10,6 @@ import {
 } from "./session/signer_session_manager";
 import { CubeSignerResponse } from "./response";
 import { SignerSession } from "./signer_session";
-import { CognitoSessionManager, CognitoSessionStorage } from "./session/cognito_manager";
-import { configDir } from "./util";
-import * as path from "path";
 import { MfaReceipt } from "./mfa";
 import { name, version } from "./../package.json";
 import { IdentityProof, MfaRequestInfo, RatchetConfig, UserInfo } from "./schema_types";
@@ -23,7 +19,7 @@ export interface CubeSignerOptions {
   /** The environment to use */
   env?: EnvInterface;
   /** The management authorization token */
-  sessionMgr?: CognitoSessionManager | SignerSessionManager;
+  sessionMgr?: SignerSessionManager;
   /** Optional organization id */
   orgId?: string;
 }
@@ -35,7 +31,7 @@ export interface CubeSignerOptions {
  */
 export class CubeSigner {
   readonly #env: EnvInterface;
-  readonly sessionMgr?: CognitoSessionManager | SignerSessionManager;
+  readonly sessionMgr?: SignerSessionManager;
   #csc?: CubeSignerClient;
 
   /**
@@ -70,28 +66,22 @@ export class CubeSigner {
   /**
    * 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.
+   * @param {SignerSessionStorage} storage Session storage to load the session from.
    * @return {Promise<CubeSigner>} New CubeSigner instance
    */
-  static async loadManagementSession(storage?: CognitoSessionStorage): Promise<CubeSigner> {
+  static async loadManagementSession(storage: SignerSessionStorage): Promise<CubeSigner> {
     return new CubeSigner(<CubeSignerOptions>{
-      sessionMgr: await CognitoSessionManager.loadManagementSession(storage),
+      sessionMgr: await SignerSessionManager.loadFromStorage(storage),
     });
   }
 
   /**
    * Loads a signer session from a session storage (e.g., session file).
-   * @param {SignerSessionStorage} storage Optional session storage to load
-   * the session from. If not specified, the signer session from the config
-   * directory will be loaded.
+   * @param {SignerSessionStorage} storage Session storage to load the session from.
    * @return {Promise<SignerSession>} New signer session
    */
-  static async loadSignerSession(storage?: SignerSessionStorage): Promise<SignerSession> {
-    const defaultFilePath = path.join(configDir(), "signer-session.json");
-    const sss = storage ?? new JsonFileSessionStorage(defaultFilePath);
-    return await SignerSession.loadSignerSession(sss);
+  static async loadSignerSession(storage: SignerSessionStorage): Promise<SignerSession> {
+    return await SignerSession.loadSignerSession(storage);
   }
 
   /**
@@ -290,6 +280,8 @@ export class CubeSigner {
   }
 }
 
+/** Errors */
+export * from "./error";
 /** API */
 export * from "./api";
 /** Client */
@@ -316,16 +308,12 @@ export * from "./schema_types";
 export * from "./signer_session";
 /** Session storage */
 export * from "./session/session_storage";
-/** Session manager */
-export * from "./session/session_manager";
-/** Management session manager */
-export * from "./session/cognito_manager";
 /** Signer session manager */
 export * from "./session/signer_session_manager";
+/** Utils */
+export * from "./util";
 /** 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;

package/src/key.ts

@@ -66,14 +66,18 @@ export function toKeyInfo(key: KeyInfoApi): KeyInfo {
   };
 }
 
-/** Signing keys. */
+/**
+ * A representation of a signing key.
+ */
 export class Key {
   /** The CubeSigner instance that this key is associated with */
-  readonly #csc: CubeSignerClient;
+  protected readonly csc: CubeSignerClient;
+  /** The key information */
+  #data: KeyInfo;
 
   /** The organization that this key is in */
   get orgId() {
-    return this.#csc.orgId;
+    return this.csc.orgId;
   }
 
   /**
@@ -81,13 +85,17 @@ export class Key {
    * the type of key (such as a public key for BLS or an ethereum address for Secp)
    * @example Key#0x8e3484687e66cdd26cf04c3647633ab4f3570148
    */
-  readonly id: string;
+  get id(): string {
+    return this.#data.key_id;
+  }
 
   /**
    * A unique identifier specific to the type of key, such as a public key or an ethereum address
    * @example 0x8e3484687e66cdd26cf04c3647633ab4f3570148
    */
-  readonly materialId: string;
+  get materialId(): string {
+    return this.#data.material_id;
+  }
 
   /**
    * @description Hex-encoded, serialized public key. The format used depends on the key type:
@@ -95,7 +103,18 @@ export class Key {
    * - BLS keys use 48-byte compressed BLS12-381 (ZCash) format
    * @example 0x04d2688b6bc2ce7f9879b9e745f3c4dc177908c5cef0c1b64cff19ae7ff27dee623c64fe9d9c325c7fbbc748bbd5f607ce14dd83e28ebbbb7d3e7f2ffb70a79431
    */
-  readonly publicKey: string;
+  get publicKey(): string {
+    return this.#data.public_key;
+  }
+
+  /**
+   * Get the cached properties of this key. The cached properties reflect the
+   * state of the last fetch or update (e.g., after awaiting `Key.enabled()`
+   * or `Key.disable()`).
+   */
+  get cached(): KeyInfo {
+    return this.#data;
+  }
 
   /** The type of key. */
   async type(): Promise<KeyType> {
@@ -137,8 +156,8 @@ export class Key {
   }
 
   /**
-   * Get the policy for the org.
-   * @return {Promise<KeyPolicy>} The policy for the org.
+   * Get the policy for the key.
+   * @return {Promise<KeyPolicy>} The policy for the key.
    */
   async policy(): Promise<KeyPolicy> {
     const data = await this.fetch();
@@ -166,7 +185,7 @@ export class Key {
    * Delete this key.
    */
   async delete() {
-    await this.#csc.keyDelete(this.id);
+    await this.csc.keyDelete(this.id);
   }
 
   // --------------------------------------------------------------------------
@@ -177,24 +196,23 @@ export class Key {
    * Create a new key.
    *
    * @param {CubeSignerClient} csc The CubeSigner instance to use for signing.
-   * @param {KeyInfo} data The JSON response from the API server.
+   * @param {KeyInfoApi} data The JSON response from the API server.
    * @internal
    */
   constructor(csc: CubeSignerClient, data: KeyInfoApi) {
-    this.#csc = csc;
-    this.id = data.key_id;
-    this.materialId = data.material_id;
-    this.publicKey = data.public_key;
+    this.csc = csc;
+    this.#data = toKeyInfo(data);
   }
 
   /**
    * Update the key.
    * @param {UpdateKeyRequest} request The JSON request to send to the API server.
    * @return {KeyInfo} The JSON response from the API server.
+   * @internal
    */
   private async update(request: UpdateKeyRequest): Promise<KeyInfo> {
-    const data = await this.#csc.keyUpdate(this.id, request);
-    return toKeyInfo(data);
+    this.#data = await this.csc.keyUpdate(this.id, request).then(toKeyInfo);
+    return this.#data;
   }
 
   /**
@@ -204,8 +222,8 @@ export class Key {
    * @internal
    */
   private async fetch(): Promise<KeyInfo> {
-    const data = await this.#csc.keyGet(this.id);
-    return toKeyInfo(data);
+    this.#data = await this.csc.keyGet(this.id).then(toKeyInfo);
+    return this.#data;
   }
 }