@cubist-labs/cubesigner-sdk 0.2.17 → 0.2.21

package/src/client.ts

@@ -316,7 +316,7 @@ export class CubeSignerClient extends CubeSignerApi {
   /**
    * Get a pending MFA request by its id.
    *
-   * Same as {@link CubeSignerClient.getMfaInfo}
+   * Same as {@link mfaGet}
    */
   get getMfaInfo() {
     return this.mfaGet.bind(this);
@@ -325,7 +325,7 @@ export class CubeSignerClient extends CubeSignerApi {
   /**
    * List pending MFA requests accessible to the current user.
    *
-   * Same as {@link CubeSignerClient.mfaList}
+   * Same as {@link mfaList}
    */
   get listMfaInfos() {
     return this.mfaList.bind(this);
@@ -334,7 +334,7 @@ export class CubeSignerClient extends CubeSignerApi {
   /**
    * Obtain a proof of authentication.
    *
-   * Same as {@link CubeSignerClient.identityProve}
+   * Same as {@link identityProve}
    */
   get proveIdentity() {
     return this.identityProve.bind(this);
@@ -343,7 +343,7 @@ export class CubeSignerClient extends CubeSignerApi {
   /**
    * Check if a given proof of OIDC authentication is valid.
    *
-   * Same as {@link CubeSignerClient.identityVerify}
+   * Same as {@link identityVerify}
    */
   get verifyIdentity() {
     return this.identityVerify.bind(this);
@@ -356,10 +356,21 @@ export class CubeSignerClient extends CubeSignerApi {
    *
    * MFA may be required.
    *
-   * Same as {@link CubeSignerClient.userRegisterFidoInit}
+   * Same as {@link userFidoRegisterInit}
    */
   get addFidoStart() {
-    return this.userRegisterFidoInit.bind(this);
+    return this.userFidoRegisterInit.bind(this);
+  }
+
+  /**
+   * Delete a FIDO key from the user's account.
+   * Allowed only if TOTP is also defined.
+   * MFA via TOTP is always required.
+   *
+   * Same as {@link userFidoDelete}
+   */
+  get deleteFido() {
+    return this.userFidoDelete.bind(this);
   }
 
   /**
@@ -367,30 +378,41 @@ export class CubeSignerClient extends CubeSignerApi {
    * that must be answered by calling {@link TotpChallenge.answer} or
    * {@link resetTotpComplete}.
    *
-   * Same as {@link userResetTotpInit}
+   * Same as {@link userTotpResetInit}
    */
   get resetTotpStart() {
-    return this.userResetTotpInit.bind(this);
+    return this.userTotpResetInit.bind(this);
   }
 
   /**
    * Answer the TOTP challenge issued by {@link resetTotpStart}. If successful,
    * user's TOTP configuration will be updated to that of the TOTP challenge.
    *
-   * Same as {@link userResetTotpComplete}
+   * Same as {@link userTotpResetComplete}
    */
   get resetTotpComplete() {
-    return this.userResetTotpComplete.bind(this);
+    return this.userTotpResetComplete.bind(this);
   }
 
   /**
    * Verifies a given TOTP code against the current user's TOTP configuration.
    * Throws an error if the verification fails.
    *
-   * Same as {@link userVerifyTotp}
+   * Same as {@link userTotpVerify}
    */
   get verifyTotp() {
-    return this.userVerifyTotp.bind(this);
+    return this.userTotpVerify.bind(this);
+  }
+
+  /**
+   * Delete TOTP from the user's account.
+   * Allowed only if at least one FIDO key is registered with the user's account.
+   * MFA via FIDO is always required.
+   *
+   * Same as {@link userTotpDelete}.
+   */
+  get deleteTotp() {
+    return this.userTotpDelete.bind(this);
   }
 
   /**

package/src/events.ts

@@ -0,0 +1,197 @@
+import { ErrResponse } from "./api";
+
+export type EventHandler<T> = (event: T) => Promise<void>;
+export type ErrorEvent = ErrResponse;
+export interface SessionExpiredEvent {}
+
+/**
+ * Dispatcher for a single event type.
+ *
+ * Provides methods for registering and unregistering handlers,
+ * as well as dispatching events to all registered handlers.
+ */
+class EventDispatcher<T> {
+  readonly #handlers: EventHandler<T>[];
+
+  /**
+   * Constructor.
+   */
+  constructor() {
+    this.#handlers = [];
+  }
+
+  /**
+   * Register a new handler.
+   *
+   * @param {EventHandler<T>} handler Event handler to register
+   * @return {EventDispatcher<T>} This instance to allow for chaining.
+   */
+  register(handler: EventHandler<T>): EventDispatcher<T> {
+    this.#handlers.push(handler);
+    return this;
+  }
+
+  /**
+   * Unregister a handler. If {@link handler} is not already registered, it's a no-op.
+   *
+   * @param {EventHandler<T>} handler Event handler to unregister
+   * @return {boolean} Whether the handler was found (and unregistered).
+   */
+  unregister(handler: EventHandler<T>): boolean {
+    const idx = this.#handlers.indexOf(handler);
+    if (idx >= 0) {
+      this.#handlers.splice(idx, 1);
+      return true;
+    } else {
+      return false;
+    }
+  }
+
+  /**
+   * Dispatch an event to all registered handlers.
+   * @param {T} event Event to dispatch.
+   */
+  async dispatch(event: T): Promise<void> {
+    await Promise.all(this.#handlers.map((h) => h(event)));
+  }
+}
+
+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>();
+
+  /**
+   * Register a handler for {@link ErrorEvent}: triggered every time a request to
+   * a CubeSigner API endpoint returns a non-success response.
+   *
+   * @param {EventHandler<ErrorEvent>} handler The handler to register.
+   */
+  onError(handler: EventHandler<ErrorEvent>) {
+    this.#onError.register(handler);
+  }
+
+  /**
+   * Register a handler for {@link SessionExpiredEvent}: triggered every time a
+   * request to a CubeSigner API endpoint fails because of an expired session.
+   *
+   * @param {EventHandler<SessionExpiredEvent>} handler The handler to register.
+   */
+  onSessionExpired(handler: EventHandler<SessionExpiredEvent>) {
+    this.#onSessionExpired.register(handler);
+  }
+
+  /**
+   * Unregister a handler for {@link ErrorEvent}.
+   *
+   * @param {EventHandler<ErrorEvent>} handler The handler to unregister.
+   * @return {boolean} Whether the handler was found (and unregistered).
+   */
+  unregisterOnError(handler: EventHandler<ErrorEvent>): boolean {
+    return this.#onError.unregister(handler);
+  }
+
+  /**
+   * Unregister a handler for {@link SessionExpiredEvent}.
+   *
+   * @param {EventHandler<SessionExpiredEvent>} handler The handler to unregister.
+   * @return {boolean} Whether the handler was found (and unregistered).
+   */
+  unregisterOnSessionExpired(handler: EventHandler<SessionExpiredEvent>): boolean {
+    return this.#onSessionExpired.unregister(handler);
+  }
+
+  /** @internal */
+  async triggerSessionExpired() {
+    await this.#onSessionExpired.dispatch(<SessionExpiredEvent>{});
+  }
+
+  /**
+   * @param {ErrorEvent} event Event to trigger
+   * @internal
+   */
+  async triggerErrorEvent(event: ErrorEvent) {
+    await this.#onError.dispatch(event);
+  }
+}
+
+/**
+ * Used to classify and emit events to one or more {@link Events} instances.
+ */
+export class EventEmitter {
+  readonly #events: Events[];
+
+  /**
+   *
+   * @param {Events[]} events Instances to which to emit events
+   * @param {boolean} skipGlobal Whether to include the global events instance {@link GlobalEvents}
+   */
+  constructor(events: Events[], skipGlobal?: boolean) {
+    skipGlobal ??= false;
+    this.#events = events;
+    if (!skipGlobal) {
+      this.#events.push(GlobalEvents);
+    }
+  }
+
+  /**
+   * Called by {@link CubeSignerApi} when an API response indicates an error.
+   *
+   * @param {ErrorEvent} err The error to dispatch.
+   * @internal
+   */
+  async classifyAndEmitError(err: ErrorEvent) {
+    for (const ev of this.#events) {
+      await ev.triggerErrorEvent(err);
+    }
+
+    // if status is 403 and error matches one of the SessionExpiredRegexes 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")
+    ) {
+      await this.emitSessionExpired();
+    }
+  }
+
+  /**
+   * Called by {@link SignerSessionManager} to notify that the session is expired
+   * beyond the possibility of refreshing, meaning that full re-login is required.
+   *
+   * @internal
+   */
+  async emitSessionExpired() {
+    for (const e of this.#events) {
+      await e.triggerSessionExpired();
+    }
+  }
+}
+
+/**
+ * Global events.
+ */
+export const GlobalEvents = new Events();

package/src/index.ts

@@ -180,7 +180,7 @@ export class CubeSigner {
 
   /** Initiate adding a new FIDO device. MFA may be required. */
   get addFidoStart() {
-    return this.csc.userRegisterFidoInit.bind(this.csc);
+    return this.csc.userFidoRegisterInit.bind(this.csc);
   }
 
   /**
@@ -188,7 +188,7 @@ export class CubeSigner {
    * that must be answered by calling `resetTotpComplete`
    */
   get resetTotpStart() {
-    return this.csc.userResetTotpInit.bind(this.#csc);
+    return this.csc.userTotpResetInit.bind(this.#csc);
   }
 
   /**
@@ -196,7 +196,7 @@ export class CubeSigner {
    * TOTP configuration will be updated to that of the TOTP challenge.he TOTP configuration from the challenge.
    */
   get resetTotpComplete() {
-    return this.csc.userResetTotpComplete.bind(this.#csc);
+    return this.csc.userTotpResetComplete.bind(this.#csc);
   }
 
   /**
@@ -204,7 +204,7 @@ export class CubeSigner {
    * Throws an error if the verification fails.
    */
   get verifyTotp() {
-    return this.csc.userVerifyTotp.bind(this.#csc);
+    return this.csc.userTotpVerify.bind(this.#csc);
   }
 
   /**
@@ -294,6 +294,8 @@ export class CubeSigner {
 export * from "./api";
 /** Client */
 export * from "./client";
+/** Callbacks */
+export { Events, EventHandler, ErrorEvent, GlobalEvents, SessionExpiredEvent } from "./events";
 /** Organizations */
 export * from "./org";
 /** Keys */

package/src/mfa.ts

@@ -53,7 +53,7 @@ export class TotpChallenge {
       throw new Error(`Invalid TOTP code: ${code}; it must be a 6-digit string`);
     }
 
-    await this.#api.userResetTotpComplete(this.totpId, code);
+    await this.#api.userTotpResetComplete(this.totpId, code);
   }
 }
 
@@ -118,7 +118,7 @@ export class AddFidoChallenge {
         attestationObject: encodeToBase64Url(cred.response.attestationObject),
       },
     };
-    await this.#api.userRegisterFidoComplete(this.challengeId, answer);
+    await this.#api.userFidoRegisterComplete(this.challengeId, answer);
   }
 }
 

package/src/schema.ts

@@ -504,6 +504,15 @@ export interface paths {
      */
     patch: operations["userRegisterFidoComplete"];
   };
+  "/v0/org/{org_id}/user/me/fido/{fido_id}": {
+    /**
+     * Delete FIDO key
+     * @description Delete FIDO key
+     *
+     * Deletes a FIDO key from the user's account (if the key is not the sole MFA factor). MFA is always required.
+     */
+    delete: operations["userDeleteFido"];
+  };
   "/v0/org/{org_id}/user/me/totp": {
     /**
      * Initialize TOTP Reset
@@ -518,6 +527,13 @@ export interface paths {
      * otherwise, MFA is required.
      */
     post: operations["userResetTotpInit"];
+    /**
+     * Delete TOTP
+     * @description Delete TOTP
+     *
+     * Deletes TOTP from the user's account (if TOTP is not the sole MFA factor). MFA is always required.
+     */
+    delete: operations["userDeleteTotp"];
     /**
      * Finalize resetting TOTP
      * @description Finalize resetting TOTP
@@ -5385,6 +5401,41 @@ export interface operations {
       };
     };
   };
+  /**
+   * Delete FIDO key
+   * @description Delete FIDO key
+   *
+   * Deletes a FIDO key from the user's account (if the key is not the sole MFA factor). MFA is always required.
+   */
+  userDeleteFido: {
+    parameters: {
+      path: {
+        /**
+         * @description Name or ID of the desired Org
+         * @example Org#124dfe3e-3bbd-487d-80c0-53c55e8ab87a
+         */
+        org_id: string;
+        /**
+         * @description Name or ID of the desired FidoKey
+         * @example FidoKey#124dfe3e-3bbd-487d-80c0-53c55e8ab87a
+         */
+        fido_id: string;
+      };
+    };
+    requestBody: {
+      content: {
+        "application/json": components["schemas"]["Empty"];
+      };
+    };
+    responses: {
+      200: components["responses"]["EmptyImpl"];
+      default: {
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
+    };
+  };
   /**
    * Initialize TOTP Reset
    * @description Initialize TOTP Reset
@@ -5426,6 +5477,36 @@ export interface operations {
       };
     };
   };
+  /**
+   * Delete TOTP
+   * @description Delete TOTP
+   *
+   * Deletes TOTP from the user's account (if TOTP is not the sole MFA factor). MFA is always required.
+   */
+  userDeleteTotp: {
+    parameters: {
+      path: {
+        /**
+         * @description Name or ID of the desired Org
+         * @example Org#124dfe3e-3bbd-487d-80c0-53c55e8ab87a
+         */
+        org_id: string;
+      };
+    };
+    requestBody: {
+      content: {
+        "application/json": components["schemas"]["Empty"];
+      };
+    };
+    responses: {
+      200: components["responses"]["EmptyImpl"];
+      default: {
+        content: {
+          "application/json": components["schemas"]["ErrorResponse"];
+        };
+      };
+    };
+  };
   /**
    * Finalize resetting TOTP
    * @description Finalize resetting TOTP

package/src/schema_types.ts

@@ -85,6 +85,8 @@ export type UserExportCompleteResponse = schemas["UserExportCompleteResponse"];
 export type UserExportListResponse = schemas["PaginatedUserExportListResponse"];
 export type UserExportKeyMaterial = schemas["JsonKeyPackage"];
 
+export type Empty = schemas["EmptyImpl"];
+
 /** 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,7 +1,7 @@
 import path from "path";
 import { Client } from "../api";
 import { EnvInterface } from "../env";
-import { HasEnv, OrgSessionManager } from "./session_manager";
+import { HasEnv, OrgSessionManager, SessionManager } from "./session_manager";
 import { JsonFileSessionStorage, SessionStorage } from "./session_storage";
 import { configDir } from "../util";
 
@@ -70,7 +70,7 @@ export class CognitoSessionManager extends OrgSessionManager<CognitoSessionInfo>
    */
   async isStale(): Promise<boolean> {
     const session = await this.storage.retrieve();
-    return this.hasExpired(new Date(session.expiration).getTime());
+    return SessionManager.hasExpired(new Date(session.expiration));
   }
 
   /**

package/src/session/session_manager.ts

@@ -1,6 +1,7 @@
-import { SessionStorage } from "..";
+import { Events } from "../events";
 import { EnvInterface } from "../env";
 import { Client, createHttpClient } from "../api";
+import { SessionStorage } from "./session_storage";
 
 const DEFAULT_EXPIRATION_BUFFER_SECS = 30;
 
@@ -8,6 +9,7 @@ const DEFAULT_EXPIRATION_BUFFER_SECS = 30;
 export abstract class SessionManager<U> {
   readonly env: EnvInterface;
   readonly storage: SessionStorage<U>;
+  readonly events = new Events();
 
   /**
    * @return {string} The current auth token.
@@ -87,12 +89,16 @@ export abstract class SessionManager<U> {
 
   /**
    * Check if a timestamp has expired.
-   * @param {number} exp The timestamp to check
-   * @param {number} buffer Optional time buffer when checking the expiration
+   * @param {Date} exp The timestamp to check
+   * @param {number} bufferSeconds Time buffer in seconds (defaults to 30s)
    * @return {boolean} True if the timestamp has expired
    */
-  protected hasExpired(exp: number, buffer?: number): boolean {
-    return exp < new Date().getTime() + (buffer || DEFAULT_EXPIRATION_BUFFER_SECS) * 1000;
+  protected static hasExpired(exp: Date, bufferSeconds?: number): boolean {
+    bufferSeconds ??= DEFAULT_EXPIRATION_BUFFER_SECS;
+    const expMsSinceEpoch = exp.getTime();
+    const nowMsSinceEpoch = new Date().getTime();
+    const bufferMs = bufferSeconds * 1000;
+    return expMsSinceEpoch < nowMsSinceEpoch + bufferMs;
   }
 
   /**

package/src/session/signer_session_manager.ts

@@ -1,13 +1,13 @@
-import { EnvInterface } from "..";
 import {
   ClientSessionInfo,
   NewSessionResponse,
   RefreshSignerSessionRequest,
 } from "../schema_types";
-import { Client } from "../api";
-import { HasEnv, OrgSessionManager } from "./session_manager";
+import { Client, OpClient } from "../api";
+import { HasEnv, OrgSessionManager, SessionManager } from "./session_manager";
 import { MemorySessionStorage, SessionStorage } from "./session_storage";
-import { assertOk } from "../util";
+import { EventEmitter } from "../events";
+import { EnvInterface } from "../env";
 
 /** JSON representation of our "signer session" file format */
 export interface SignerSessionObject {
@@ -23,6 +23,15 @@ export interface SignerSessionObject {
   session_info: ClientSessionInfo;
 }
 
+/**
+ * Constructs {@link Date} from a number representing seconds since unix epoch.
+ * @param {number} secs Seconds since unix epoch.
+ * @return {Date} The equivalent date.
+ */
+function secondsSinceEpochToDate(secs: number): Date {
+  return new Date(secs * 1000);
+}
+
 export interface SignerSessionData extends SignerSessionObject, HasEnv {}
 
 /** Type of storage required for signer sessions */
@@ -41,7 +50,8 @@ export interface SignerSessionLifetime {
 
 /** Manager for signer sessions. */
 export class SignerSessionManager extends OrgSessionManager<SignerSessionData> {
-  #client: Client;
+  readonly #eventEmitter: EventEmitter;
+  #client: { client: Client; exp: Date };
 
   /**
    * @return {string} The current auth token.
@@ -59,17 +69,21 @@ export class SignerSessionManager extends OrgSessionManager<SignerSessionData> {
    */
   async client(): Promise<Client> {
     await this.refreshIfNeeded();
-    return this.#client;
+
+    // trigger "session expired" if for whatever reason the token is still stale
+    if (SessionManager.hasExpired(this.#client.exp, /* buffer */ 0)) {
+      await this.#eventEmitter.emitSessionExpired();
+    }
+
+    return this.#client.client;
   }
 
   /** Revokes the session. */
   async revoke(): Promise<void> {
-    const client = await this.client();
-    const resp = await client.del("/v0/org/{org_id}/session/self", {
+    const client = new OpClient("revokeCurrentSession", await this.client(), this.#eventEmitter);
+    await client.del("/v0/org/{org_id}/session/self", {
       params: { path: { org_id: this.orgId } },
-      parseAs: "json",
     });
-    assertOk(resp);
   }
 
   /**
@@ -78,8 +92,7 @@ export class SignerSessionManager extends OrgSessionManager<SignerSessionData> {
    * @internal
    */
   async isStale(): Promise<boolean> {
-    const session = await this.storage.retrieve();
-    return this.hasExpired(session.session_info.auth_token_exp * 1000);
+    return SessionManager.hasExpired(this.#client.exp);
   }
 
   /**
@@ -88,17 +101,16 @@ export class SignerSessionManager extends OrgSessionManager<SignerSessionData> {
   async refresh(): Promise<void> {
     const currSession = await this.storage.retrieve();
 
+    const client = new OpClient("signerSessionRefresh", this.#client.client, this.#eventEmitter);
     const csi = currSession.session_info;
-    const resp = await this.#client.patch("/v1/org/{org_id}/token/refresh", {
+    const data = await client.patch("/v1/org/{org_id}/token/refresh", {
       params: { path: { org_id: this.orgId } },
       body: <RefreshSignerSessionRequest>{
         epoch_num: csi.epoch,
         epoch_token: csi.epoch_token,
         other_token: csi.refresh_token,
       },
-      parseAs: "json",
     });
-    const data = assertOk(resp);
     const newSession = <SignerSessionData>{
       ...currSession,
       session_info: data.session_info,
@@ -106,7 +118,10 @@ export class SignerSessionManager extends OrgSessionManager<SignerSessionData> {
     };
 
     await this.storage.save(newSession);
-    this.#client = this.createClient(newSession.token);
+    this.#client = {
+      client: this.createClient(newSession.token),
+      exp: secondsSinceEpochToDate(newSession.session_info.auth_token_exp),
+    };
   }
 
   /**
@@ -136,6 +151,20 @@ export class SignerSessionManager extends OrgSessionManager<SignerSessionData> {
     return await SignerSessionManager.loadFromStorage(storage);
   }
 
+  /**
+   * @param {SignerSessionData} sessionData The session information.
+   * @param {SignerSessionStorage} storage The storage to use for saving the session.
+   * @return {Promise<SignerSessionManager>} New signer session manager.
+   */
+  static async createFromSessionData(
+    sessionData: SignerSessionData,
+    storage?: SignerSessionStorage,
+  ): Promise<SignerSessionManager> {
+    storage ??= new MemorySessionStorage();
+    await storage.save(sessionData);
+    return await SignerSessionManager.loadFromStorage(storage);
+  }
+
   /**
    * Uses an existing session to create a new signer session manager.
    *
@@ -153,8 +182,12 @@ export class SignerSessionManager extends OrgSessionManager<SignerSessionData> {
    * @param {SignerSessionData} sessionData Session data
    * @param {SignerSessionStorage} storage The session storage to use.
    */
-  private constructor(sessionData: SignerSessionData, storage: SignerSessionStorage) {
+  protected constructor(sessionData: SignerSessionData, storage: SignerSessionStorage) {
     super(sessionData.env["Dev-CubeSignerStack"], sessionData.org_id, storage);
-    this.#client = this.createClient(sessionData.token);
+    this.#eventEmitter = new EventEmitter([this.events]);
+    this.#client = {
+      client: this.createClient(sessionData.token),
+      exp: secondsSinceEpochToDate(sessionData.session_info.auth_token_exp),
+    };
   }
 }