@icp-sdk/auth 4.0.0-beta.1

package/src/client/idle-manager.ts

@@ -0,0 +1,144 @@
+type IdleCB = () => unknown;
+
+export type IdleManagerOptions = {
+  /**
+   * Callback after the user has gone idle
+   */
+  onIdle?: IdleCB;
+  /**
+   * timeout in ms
+   * @default 30 minutes [600_000]
+   */
+  idleTimeout?: number;
+  /**
+   * capture scroll events
+   * @default false
+   */
+  captureScroll?: boolean;
+  /**
+   * scroll debounce time in ms
+   * @default 100
+   */
+  scrollDebounce?: number;
+};
+
+const events = ['mousedown', 'mousemove', 'keydown', 'touchstart', 'wheel'];
+
+/**
+ * Detects if the user has been idle for a duration of `idleTimeout` ms, and calls `onIdle` and registered callbacks.
+ * By default, the IdleManager will log a user out after 10 minutes of inactivity.
+ * To override these defaults, you can pass an `onIdle` callback, or configure a custom `idleTimeout` in milliseconds
+ */
+export class IdleManager {
+  callbacks: IdleCB[] = [];
+  idleTimeout: IdleManagerOptions['idleTimeout'] = 10 * 60 * 1000;
+  timeoutID?: number = undefined;
+
+  /**
+   * Creates an {@link IdleManager}
+   * @param {IdleManagerOptions} options Optional configuration
+   * @see {@link IdleManagerOptions}
+   * @param options.onIdle Callback once user has been idle. Use to prompt for fresh login, and use `Actor.agentOf(your_actor).invalidateIdentity()` to protect the user
+   * @param options.idleTimeout timeout in ms
+   * @param options.captureScroll capture scroll events
+   * @param options.scrollDebounce scroll debounce time in ms
+   */
+  public static create(
+    options: {
+      /**
+       * Callback after the user has gone idle
+       * @see {@link IdleCB}
+       */
+      onIdle?: () => unknown;
+      /**
+       * timeout in ms
+       * @default 10 minutes [600_000]
+       */
+      idleTimeout?: number;
+      /**
+       * capture scroll events
+       * @default false
+       */
+      captureScroll?: boolean;
+      /**
+       * scroll debounce time in ms
+       * @default 100
+       */
+      scrollDebounce?: number;
+    } = {},
+  ): IdleManager {
+    return new IdleManager(options);
+  }
+
+  /**
+   * @protected
+   * @param options {@link IdleManagerOptions}
+   */
+  protected constructor(options: IdleManagerOptions = {}) {
+    const { onIdle, idleTimeout = 10 * 60 * 1000 } = options || {};
+
+    this.callbacks = onIdle ? [onIdle] : [];
+    this.idleTimeout = idleTimeout;
+
+    const _resetTimer = this._resetTimer.bind(this);
+
+    window.addEventListener('load', _resetTimer, true);
+
+    events.forEach((name) => {
+      document.addEventListener(name, _resetTimer, true);
+    });
+
+    const debounce = (func: (...args: unknown[]) => void, wait: number) => {
+      let timeout: number | undefined;
+      return (...args: unknown[]) => {
+        const context = this;
+        const later = () => {
+          timeout = undefined;
+          func.apply(context, args);
+        };
+        clearTimeout(timeout);
+        timeout = window.setTimeout(later, wait);
+      };
+    };
+
+    if (options?.captureScroll) {
+      // debounce scroll events
+      const scroll = debounce(_resetTimer, options?.scrollDebounce ?? 100);
+      window.addEventListener('scroll', scroll, true);
+    }
+
+    _resetTimer();
+  }
+
+  /**
+   * @param {IdleCB} callback function to be called when user goes idle
+   */
+  public registerCallback(callback: IdleCB): void {
+    this.callbacks.push(callback);
+  }
+
+  /**
+   * Cleans up the idle manager and its listeners
+   */
+  public exit(): void {
+    clearTimeout(this.timeoutID);
+    window.removeEventListener('load', this._resetTimer, true);
+
+    const _resetTimer = this._resetTimer.bind(this);
+    events.forEach((name) => {
+      document.removeEventListener(name, _resetTimer, true);
+    });
+    this.callbacks.forEach((cb) => {
+      cb();
+    });
+  }
+
+  /**
+   * Resets the timeouts during cleanup
+   */
+  _resetTimer(): void {
+    const exit = this.exit.bind(this);
+    window.clearTimeout(this.timeoutID);
+    this.timeoutID = window.setTimeout(exit, this.idleTimeout);
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,10 @@
+export * from './auth-client.ts';
+export { type DBCreateOptions, IdbKeyVal } from './db.ts';
+export * from './idle-manager.ts';
+export {
+  type AuthClientStorage,
+  IdbStorage,
+  KEY_STORAGE_DELEGATION,
+  KEY_STORAGE_KEY,
+  LocalStorage,
+} from './storage.ts';

package/src/client/storage.ts

@@ -0,0 +1,112 @@
+import { type DBCreateOptions, IdbKeyVal } from './db.ts';
+
+export const KEY_STORAGE_KEY = 'identity';
+export const KEY_STORAGE_DELEGATION = 'delegation';
+export const KEY_VECTOR = 'iv';
+// Increment if any fields are modified
+export const DB_VERSION = 1;
+
+export type StoredKey = string | CryptoKeyPair;
+
+/**
+ * Interface for persisting user authentication data
+ */
+export interface AuthClientStorage {
+  get(key: string): Promise<StoredKey | null>;
+
+  set(key: string, value: StoredKey): Promise<void>;
+
+  remove(key: string): Promise<void>;
+}
+
+/**
+ * Legacy implementation of AuthClientStorage, for use where IndexedDb is not available
+ */
+export class LocalStorage implements AuthClientStorage {
+  constructor(
+    public readonly prefix = 'ic-',
+    private readonly _localStorage?: Storage,
+  ) {}
+
+  public get(key: string): Promise<string | null> {
+    return Promise.resolve(this._getLocalStorage().getItem(this.prefix + key));
+  }
+
+  public set(key: string, value: string): Promise<void> {
+    this._getLocalStorage().setItem(this.prefix + key, value);
+    return Promise.resolve();
+  }
+
+  public remove(key: string): Promise<void> {
+    this._getLocalStorage().removeItem(this.prefix + key);
+    return Promise.resolve();
+  }
+
+  private _getLocalStorage() {
+    if (this._localStorage) {
+      return this._localStorage;
+    }
+
+    const ls = globalThis.localStorage;
+    if (!ls) {
+      throw new Error('Could not find local storage.');
+    }
+
+    return ls;
+  }
+}
+
+/**
+ * IdbStorage is an interface for simple storage of string key-value pairs built on {@link IdbKeyVal}
+ *
+ * It replaces {@link LocalStorage}
+ * @see implements {@link AuthClientStorage}
+ */
+export class IdbStorage implements AuthClientStorage {
+  #options: DBCreateOptions;
+
+  /**
+   * @param options - DBCreateOptions
+   * @param options.dbName - name for the indexeddb database
+   * @param options.storeName - name for the indexeddb Data Store
+   * @param options.version - version of the database. Increment to safely upgrade
+   * @example
+   * ```ts
+   * const storage = new IdbStorage({ dbName: 'my-db', storeName: 'my-store', version: 2 });
+   * ```
+   */
+  constructor(options?: DBCreateOptions) {
+    this.#options = options ?? {};
+  }
+
+  // Initializes a KeyVal on first request
+  private initializedDb: IdbKeyVal | undefined;
+  get _db(): Promise<IdbKeyVal> {
+    return new Promise((resolve) => {
+      if (this.initializedDb) {
+        resolve(this.initializedDb);
+        return;
+      }
+      IdbKeyVal.create(this.#options).then((db) => {
+        this.initializedDb = db;
+        resolve(db);
+      });
+    });
+  }
+
+  public async get<T = string>(key: string): Promise<T | null> {
+    const db = await this._db;
+    return await db.get<T>(key);
+    // return (await db.get<string>(key)) ?? null;
+  }
+
+  public async set<T = string>(key: string, value: T): Promise<void> {
+    const db = await this._db;
+    await db.set(key, value);
+  }
+
+  public async remove(key: string): Promise<void> {
+    const db = await this._db;
+    await db.remove(key);
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+throw new Error(
+  'There are no exports in the root module of this package. Import from submodules instead. Use intellisense or the docs to find the available submodules.',
+);