@cubist-labs/cubesigner-sdk 0.3.1 → 0.3.11

package/src/events.ts

@@ -3,8 +3,11 @@ 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 {}
+/** Event emitted when a request fails because of an expired/invalid session */
+export class SessionExpiredEvent {}
+
+/** Event emitted when a request fails because user failed to answer an MFA challenge */
+export class UserMfaFailedEvent extends ErrResponse {}
 
 /**
  * Dispatcher for a single event type.
@@ -58,31 +61,13 @@ class EventDispatcher<T> {
   }
 }
 
-const SessionExpiredRegexes = [
-  /^Session '(?<purpose>[^']*)' for '(?<identity>[^']*)' has expired$/,
-  /^Session '(?<purpose>[^']*)' for '(?<identity>[^']*)' has been revoked$/,
-  /^Auth token for epoch (?<epoch>\d+) has expired$/,
-  /^Refresh token for epoch (?<epoch_num>\d+) has expired$/,
-  /^Outdated session$/,
-];
-
-/**
- * Whether an error message matches one of several different "session expired" responses.
- *
- * @param {string} msg The string to test.
- * @return {boolean} Whether the string matches.
- * @internal Exported only so that it can be called from a unit test
- */
-export function messageMatchesSessionExpired(msg: string): boolean {
-  return SessionExpiredRegexes.some((re) => re.test(msg));
-}
-
 /**
  * Class for registering and unregistering event handlers.
  */
 export class Events {
   readonly #onError = new EventDispatcher<ErrorEvent>();
   readonly #onSessionExpired = new EventDispatcher<SessionExpiredEvent>();
+  readonly #onUserMfaFailed = new EventDispatcher<UserMfaFailedEvent>();
 
   /**
    * Register a handler for {@link ErrorEvent}: triggered every time a request to
@@ -104,6 +89,17 @@ export class Events {
     this.#onSessionExpired.register(handler);
   }
 
+  /**
+   * Register a handler for {@link UserMfaFailedEvent}: triggered every time a
+   * request to a CubeSigner API endpoint fails because the user failed to
+   * answer an MFA challenge.
+   *
+   * @param {EventHandler<UserMfaFailedEvent>} handler The handler to register.
+   */
+  onUserMfaFailed(handler: EventHandler<UserMfaFailedEvent>) {
+    this.#onUserMfaFailed.register(handler);
+  }
+
   /**
    * Unregister a handler for {@link ErrorEvent}.
    *
@@ -124,9 +120,27 @@ export class Events {
     return this.#onSessionExpired.unregister(handler);
   }
 
+  /**
+   * Unregister a handler for {@link UserMfaFailedEvent}.
+   *
+   * @param {EventHandler<UserMfaFailedEvent>} handler The handler to unregister.
+   * @return {boolean} Whether the handler was found (and unregistered).
+   */
+  unregisterOnUserMfaFailed(handler: EventHandler<UserMfaFailedEvent>): boolean {
+    return this.#onUserMfaFailed.unregister(handler);
+  }
+
   /** @internal */
   async triggerSessionExpired() {
-    await this.#onSessionExpired.dispatch(<SessionExpiredEvent>{});
+    await this.#onSessionExpired.dispatch(new SessionExpiredEvent());
+  }
+
+  /**
+   * @param {UserMfaFailedEvent} ev The event to emit
+   * @internal
+   */
+  async triggerUserMfaFailed(ev: UserMfaFailedEvent) {
+    await this.#onUserMfaFailed.dispatch(ev);
   }
 
   /**
@@ -168,13 +182,17 @@ export class EventEmitter {
       await ev.triggerErrorEvent(err);
     }
 
-    // if status is 403 and error matches one of the SessionExpiredRegexes trigger onSessionExpired
+    if (err.isUserMfaError()) {
+      await this.emitUserMfaFailed(err);
+    }
+
+    // if status is 403 and error matches one of the "invalid session" error codes trigger onSessionExpired
     //
     // TODO: because errors returned by the authorizer lambda are not forwarded to the client
     //       we also trigger onSessionExpired when "signerSessionRefresh" fails
     if (
       err.status === 403 &&
-      (messageMatchesSessionExpired(err.message) || err.operation == "signerSessionRefresh")
+      (err.isSessionExpiredError() || err.operation == "signerSessionRefresh")
     ) {
       await this.emitSessionExpired();
     }
@@ -191,6 +209,17 @@ export class EventEmitter {
       await e.triggerSessionExpired();
     }
   }
+
+  /**
+   * Emits {@link UserMfaFailedEvent} to all subscribers
+   *
+   * @param {UserMfaFailedEvent} ev The event to emit.
+   */
+  private async emitUserMfaFailed(ev: UserMfaFailedEvent) {
+    for (const e of this.#events) {
+      await e.triggerUserMfaFailed(ev);
+    }
+  }
 }
 
 /**

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 */
@@ -138,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
@@ -147,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) {

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

@@ -278,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 [