@cubist-labs/cubesigner-sdk 0.2.28 → 0.3.1

package/package.json

@@ -1,68 +1,41 @@
 {
   "name": "@cubist-labs/cubesigner-sdk",
-  "author": "Cubist, Inc.",
-  "version": "0.2.28",
+  "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.2",
-    "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,
@@ -225,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}`,
     },
   });
 }
@@ -1155,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.
    *
@@ -1457,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/events.ts

@@ -2,6 +2,8 @@ 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);
   }
 
   /**
@@ -318,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;
   }
 }
 

package/src/role.ts

@@ -48,6 +48,13 @@ export type TxDepositPubkey = { TxDeposit: { kind: DepositContract; pubkey: stri
  */
 export type TxDepositRole = { TxDeposit: { kind: DepositContract; role_id: string } };
 
+/**
+ * Only allow connections from clients whose IP addresses match any of these IPv4 CIDR blocks.
+ *
+ * @example { SourceIpAllowlist: [ "123.456.78.9/16" ] }
+ */
+export type SourceIpAllowlist = { SourceIpAllowlist: string[] };
+
 /** All different kinds of sensitive operations. */
 export enum OperationKind {
   BlobSign = "BlobSign", // eslint-disable-line no-unused-vars
@@ -100,6 +107,17 @@ export type RequireMfa = {
 export const AllowRawBlobSigning = "AllowRawBlobSigning" as const;
 export type AllowRawBlobSigning = typeof AllowRawBlobSigning;
 
+/** Allow EIP-191 signing */
+export const AllowEip191Signing = "AllowEip191Signing" as const;
+export type AllowEip191Signing = typeof AllowEip191Signing;
+
+/** Allow EIP-712 signing */
+export const AllowEip712Signing = "AllowEip712Signing" as const;
+export type AllowEip712Signing = typeof AllowEip712Signing;
+
+/** Key policies that restrict the requests that the signing endpoints accept */
+type KeyDenyPolicy = TxReceiver | TxDeposit | SourceIpAllowlist | RequireMfa;
+
 /**
  * Key policy
  *
@@ -124,7 +142,15 @@ export type AllowRawBlobSigning = typeof AllowRawBlobSigning;
  *   }
  * ]
  */
-export type KeyPolicy = (TxReceiver | TxDeposit | RequireMfa | AllowRawBlobSigning)[];
+export type KeyPolicy = (
+  | KeyDenyPolicy
+  | AllowRawBlobSigning
+  | AllowEip191Signing
+  | AllowEip712Signing
+)[];
+
+/** Role policy */
+export type RolePolicy = KeyDenyPolicy[];
 
 /** A key guarded by a policy. */
 export class KeyWithPolicies {
@@ -154,15 +180,30 @@ export class KeyWithPolicies {
 /** Roles. */
 export class Role {
   readonly #csc: CubeSignerClient;
+  /** The role information */
+  #data: RoleInfo;
 
   /** Human-readable name for the role */
-  public readonly name?: string;
+  get name(): string | undefined {
+    return this.#data.name ?? undefined;
+  }
 
   /**
    * The ID of the role.
    * @example Role#bfe3eccb-731e-430d-b1e5-ac1363e6b06b
    */
-  readonly id: string;
+  get id(): string {
+    return this.#data.role_id;
+  }
+
+  /**
+   * @return {RoleInfo} the cached properties of this role. The cached properties
+   * reflect the state of the last fetch or update (e.g., after awaiting
+   * `Role.enabled()` or `Role.disable()`).
+   */
+  get cached(): RoleInfo {
+    return this.#data;
+  }
 
   /** Delete the role. */
   async delete(): Promise<void> {
@@ -185,6 +226,35 @@ export class Role {
     await this.update({ enabled: false });
   }
 
+  /**
+   * Set new policy (overwriting any policies previously set for this role)
+   * @param {RolePolicy} policy The new policy to set
+   */
+  async setPolicy(policy: RolePolicy) {
+    await this.update({ policy: policy as unknown as Record<string, never>[] });
+  }
+
+  /**
+   * Append to existing role policy. This append is not atomic---it uses
+   * {@link policy} to fetch the current policy and then {@link setPolicy}
+   * to set the policy---and should not be used in across concurrent sessions.
+   *
+   * @param {RolePolicy} policy The policy to append to the existing one.
+   */
+  async appendPolicy(policy: RolePolicy) {
+    const existing = await this.policy();
+    await this.setPolicy([...existing, ...policy]);
+  }
+
+  /**
+   * Get the policy for the role.
+   * @return {Promise<RolePolicy>} The policy for the role.
+   */
+  async policy(): Promise<RolePolicy> {
+    const data = await this.fetch();
+    return (data.policy ?? []) as unknown as RolePolicy;
+  }
+
   /**
    * The list of all users with access to the role.
    * @example [
@@ -301,8 +371,7 @@ export class Role {
    */
   constructor(csc: CubeSignerClient, data: RoleInfo) {
     this.#csc = csc;
-    this.id = data.role_id;
-    this.name = data.name ?? undefined;
+    this.#data = data;
   }
 
   /**
@@ -312,7 +381,8 @@ export class Role {
    * @return {Promise<RoleInfo>} The updated role information.
    */
   private async update(request: UpdateRoleRequest): Promise<RoleInfo> {
-    return await this.#csc.roleUpdate(this.id, request);
+    this.#data = await this.#csc.roleUpdate(this.id, request);
+    return this.#data;
   }
 
   /**
@@ -322,6 +392,7 @@ export class Role {
    * @internal
    */
   private async fetch(): Promise<RoleInfo> {
-    return await this.#csc.roleGet(this.id);
+    this.#data = await this.#csc.roleGet(this.id);
+    return this.#data;
   }
 }