@cubist-labs/cubesigner-sdk 0.2.28 → 0.3.8

package/src/key.ts

@@ -1,5 +1,12 @@
 import { KeyPolicy } from "./role";
-import { KeyInfoApi, KeyTypeApi, UpdateKeyRequest, SchemaKeyType } from "./schema_types";
+import { PageOpts } from "./paginator";
+import {
+  KeyInfoApi,
+  KeyTypeApi,
+  UpdateKeyRequest,
+  SchemaKeyType,
+  KeyInRoleInfo,
+} from "./schema_types";
 import { CubeSignerClient } from "./client";
 
 /** Secp256k1 key type */
@@ -66,14 +73,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 +92,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 +110,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> {
@@ -119,6 +145,15 @@ export class Key {
     await this.update({ enabled: false });
   }
 
+  /**
+   * The list roles this key is in.
+   * @param {PageOpts} page Optional pagination options; by default, retrieves all roles this key is in.
+   * @return {Promise<KeyInRoleInfo[]>} Roles this key is in.
+   */
+  async roles(page?: PageOpts): Promise<KeyInRoleInfo[]> {
+    return await this.csc.keyRolesList(this.id, page).fetch();
+  }
+
   /**
    * Set new policy (overwriting any policies previously set for this key)
    * @param {KeyPolicy} policy The new policy to set
@@ -128,7 +163,20 @@ export class Key {
   }
 
   /**
-   * Append to existing key 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.
+   * Set key metadata. The metadata must be at most 1024 characters
+   * and must match the following regex: ^[A-Za-z0-9_=+/ \-\.\,]{0,1024}$.
+   *
+   * @param {string} metadata The new metadata to set.
+   */
+  async setMetadata(metadata: string) {
+    await this.update({ metadata });
+  }
+
+  /**
+   * Append to existing key 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 {KeyPolicy} policy The policy to append to the existing one.
    */
   async appendPolicy(policy: KeyPolicy) {
@@ -137,8 +185,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 +214,7 @@ export class Key {
    * Delete this key.
    */
   async delete() {
-    await this.#csc.keyDelete(this.id);
+    await this.csc.keyDelete(this.id);
   }
 
   // --------------------------------------------------------------------------
@@ -177,24 +225,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 +251,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/mfa.ts

@@ -4,6 +4,7 @@ import {
   ApiAddFidoChallenge,
   ApiMfaFidoChallenge,
   MfaRequestInfo,
+  MfaVote,
   PublicKeyCredential,
   TotpInfo,
 } from "./schema_types";
@@ -159,10 +160,12 @@ export class MfaFidoChallenge {
   /**
    * Answers this challenge by using the `CredentialsContainer` API to get a credential
    * based on the the public key credential request options from this challenge.
+   *
+   * @param {MfaVote} vote Approve or reject the MFA request. Defaults to "approve".
    */
-  async createCredentialAndAnswer(): Promise<MfaRequestInfo> {
+  async createCredentialAndAnswer(vote?: MfaVote): Promise<MfaRequestInfo> {
     const cred = await navigator.credentials.get({ publicKey: this.options });
-    return await this.answer(cred);
+    return await this.answer(cred, vote);
   }
 
   /**
@@ -175,8 +178,9 @@ export class MfaFidoChallenge {
    *
    * @param {any} cred Credential created by calling the `CredentialContainer`'s `get` method
    *                   based on the public key credential request options from this challenge.
+   * @param {MfaVote} vote Approve or reject. Defaults to "approve".
    */
-  async answer(cred: any): Promise<MfaRequestInfo> {
+  async answer(cred: any, vote: MfaVote = "approve"): Promise<MfaRequestInfo> {
     const answer = <PublicKeyCredential>{
       id: cred.id,
       response: {
@@ -185,6 +189,6 @@ export class MfaFidoChallenge {
         signature: encodeToBase64Url(cred.response.signature),
       },
     };
-    return await this.#api.mfaApproveFidoComplete(this.mfaId, this.challengeId, answer);
+    return await this.#api.mfaVoteFidoComplete(this.mfaId, vote, this.challengeId, answer);
   }
 }

package/src/response.ts

@@ -1,4 +1,4 @@
-import { CubeSignerClient, SignerSession } from ".";
+import { CubeSignerClient, MfaVote, SignerSession } from ".";
 import { MfaReceipt } from "./mfa";
 import { AcceptedResponse, NewSessionResponse } from "./schema_types";
 
@@ -90,13 +90,39 @@ export class CubeSignerResponse<U> {
    * @return {CubeSignerResponse<U>} The result of signing with the approval
    */
   async approveTotp(session: SignerSession, code: string): Promise<CubeSignerResponse<U>> {
+    return await this.#mfaVoteTotp(session, code, "approve");
+  }
+
+  /**
+   * Reject 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
+   */
+  async rejectTotp(session: SignerSession, code: string) {
+    await this.#mfaVoteTotp(session, code, "reject");
+  }
+
+  /**
+   * Approve or reject an MFA request using a given session and a TOTP code.
+   *
+   * @param {SignerSession} session Signer session to use
+   * @param {string} code 6-digit TOTP code
+   * @param {MfaVote} vote Approve or reject
+   * @return {CubeSignerResponse<U>} The result of signing with the approval
+   */
+  async #mfaVoteTotp(
+    session: SignerSession,
+    code: string,
+    vote: MfaVote,
+  ): Promise<CubeSignerResponse<U>> {
     if (!this.requiresMfa()) {
       return this;
     }
 
     const mfaId = this.mfaId();
     const mfaOrgId = this.#mfaRequired!.org_id;
-    const mfaApproval = await session.mfaApproveTotp(mfaId, code);
+    const mfaApproval = await session.mfaVoteTotp(mfaId, code, vote);
     const mfaConf = mfaApproval.receipt?.confirmation;
 
     if (!mfaConf) {
@@ -107,12 +133,32 @@ export class CubeSignerResponse<U> {
   }
 
   /**
-   * Approve the MFA request using a given `CubeSignerClient` instance (i.e., its session).
+   * Approve the MFA request using a given {@link CubeSignerClient} instance (i.e., its session).
    *
    * @param {CubeSignerClient} cs CubeSigner whose session to use
    * @return {CubeSignerResponse<U>} The result of signing with the approval
    */
   async approve(cs: CubeSignerClient): Promise<CubeSignerResponse<U>> {
+    return await this.#mfaVoteCs(cs, "approve");
+  }
+
+  /**
+   * Reject the MFA request using a given {@link CubeSignerClient} instance (i.e., its session).
+   *
+   * @param {CubeSignerClient} cs CubeSigner client whose session to use
+   */
+  async reject(cs: CubeSignerClient) {
+    await this.#mfaVoteCs(cs, "reject");
+  }
+
+  /**
+   * Approve or reject an MFA request using a given {@link CubeSignerClient} instance (i.e., its session).
+   *
+   * @param {CubeSignerClient} cs CubeSigner whose session to use
+   * @param {MfaVote} mfaVote Approve or reject
+   * @return {CubeSignerResponse<U>} The result of signing with the approval
+   */
+  async #mfaVoteCs(cs: CubeSignerClient, mfaVote: MfaVote): Promise<CubeSignerResponse<U>> {
     if (!this.requiresMfa()) {
       return this;
     }
@@ -120,7 +166,7 @@ export class CubeSignerResponse<U> {
     const mfaId = this.#mfaRequired!.id;
     const mfaOrgId = this.#mfaRequired!.org_id;
 
-    const mfaApproval = await cs.mfaApprove(mfaId);
+    const mfaApproval = await cs.mfaVoteCs(mfaId, mfaVote);
     const mfaConf = mfaApproval.receipt?.confirmation;
 
     if (!mfaConf) {

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 [
@@ -208,6 +278,15 @@ export class Role {
     await this.#csc.roleUserAdd(this.id, userId);
   }
 
+  /**
+   * Remove an existing user from an existing role.
+   *
+   * @param {string} userId The user-id of the user to remove from the role.
+   */
+  async removeUser(userId: string) {
+    await this.#csc.roleUserRemove(this.id, userId);
+  }
+
   /**
    * The list of keys in the role.
    * @example [
@@ -301,8 +380,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 +390,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 +401,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;
   }
 }