feat(auth): LIT-4211 - Add initial auth package

- Define localStorage storage plugin w/ tests

Author: MaximusHaximus

packages/auth/.babelrc

@@ -0,0 +1,10 @@
+{
+  "presets": [
+    [
+      "@nx/web/babel",
+      {
+        "useBuiltIns": "usage"
+      }
+    ]
+  ]
+}

packages/auth/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    }
+  ]
+}

packages/auth/README.md

@@ -0,0 +1,14 @@
+# Quick Start
+
+This module provides management of auth methods that are used to control LIT PKPs, and authorization primitives.
+
+### AuthManager
+An AuthManager works with `authenticators` (migrated from: @lit-protocol/lit-auth-client) to generate auth material using various methods (see: authenticators documentation).  
+
+The `AuthManager` then uses that auth material to create session credentials, and caches the resulting credentials for use with LIT network services.  It also validates auth material and session material, and will attempt to get new auth material any time it detects that existing cached credentials have expired.
+
+### node.js / browser
+
+```
+yarn add @lit-protocol/lit-auth
+```

packages/auth/jest.config.ts

@@ -0,0 +1,21 @@
+/* eslint-disable */
+export default {
+  displayName: 'lit-auth',
+  preset: '../../jest.preset.js',
+  globals: {
+    'ts-jest': {
+      tsconfig: '<rootDir>/tsconfig.spec.json',
+    },
+  },
+  transform: {
+    '^.+\\.[t]s$': 'ts-jest',
+  },
+  moduleFileExtensions: ['ts', 'js', 'html'],
+  coverageDirectory: '../../coverage/packages/lit-auth',
+  moduleNameMapper: {
+    '^ipfs-unixfs-importer':
+      'node_modules/ipfs-unixfs-importer/dist/index.min.js',
+    '^blockstore-core': 'node_modules/blockstore-core/dist/index.min.js',
+  },
+  setupFilesAfterEnv: ['../../jest.setup.js'],
+};

packages/auth/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@lit-protocol/lit-auth",
+  "license": "MIT",
+  "homepage": "https://github.com/Lit-Protocol/js-sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LIT-Protocol/js-sdk"
+  },
+  "keywords": [
+    "library"
+  ],
+  "bugs": {
+    "url": "https://github.com/LIT-Protocol/js-sdk/issues"
+  },
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public",
+    "directory": "../../dist/packages/lit-auth"
+  },
+  "gitHead": "0d7334c2c55f448e91fe32f29edc5db8f5e09e4b",
+  "tags": [
+    "universal"
+  ],
+  "peerDependencies": {
+    "tslib": "^2.3.0"
+  },
+  "browser": {
+    "crypto": false,
+    "stream": false
+  },
+  "version": "8.0.0-alpha.0",
+  "main": "./dist/src/index.js",
+  "typings": "./dist/src/index.d.ts"
+}

packages/auth/project.json

@@ -0,0 +1,35 @@
+{
+  "name": "lit-auth",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/lit-auth/src",
+  "projectType": "library",
+  "targets": {
+    "build": {
+      "executor": "@nx/js:tsc",
+      "outputs": ["{options.outputPath}"],
+      "options": {
+        "outputPath": "dist/packages/lit-auth",
+        "main": "packages/lit-auth/src/index.ts",
+        "tsConfig": "packages/lit-auth/tsconfig.lib.json",
+        "assets": ["packages/lit-auth/*.md"],
+        "updateBuildableProjectDepsInPackageJson": true
+      }
+    },
+    "lint": {
+      "executor": "@nx/linter:eslint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["packages/lit-auth/**/*.ts"]
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/packages/lit-auth"],
+      "options": {
+        "jestConfig": "packages/lit-auth/jest.config.ts",
+        "passWithNoTests": true
+      }
+    }
+  },
+  "tags": []
+}

packages/auth/src/lib/storage/index.ts

@@ -0,0 +1,3 @@
+import { localStorage } from './localStorage';
+
+export { localStorage };

packages/auth/src/lib/storage/localStorage.spec.ts

@@ -0,0 +1,126 @@
+import { localStorage as createLocalStorage } from './localStorage';
+
+import type { LitAuthData } from '../types';
+
+describe('localStorage', () => {
+  let mockLocalStorage: WindowLocalStorage['localStorage'];
+
+  beforeEach(() => {
+    mockLocalStorage = (() => {
+      const store = new Map<string, string>();
+      return {
+        getItem: (key: string) =>
+          store.has(key) ? store.get(key) ?? null : null,
+        setItem: (key: string, value: string) => store.set(key, value),
+      };
+    })() as unknown as WindowLocalStorage['localStorage'];
+  });
+
+  const appName: string = 'testApp';
+  const networkName: string = 'testNetwork';
+  const pkpAddress: string = '0x123';
+  const authData: LitAuthData = {
+    credential: 'abc123',
+    authMethod: 'EthWallet',
+  };
+
+  test('initializes correctly and validates localStorage', () => {
+    expect(() =>
+      createLocalStorage({
+        appName,
+        networkName,
+        localStorage: mockLocalStorage,
+      })
+    ).not.toThrow();
+  });
+
+  test('throws an error if localStorage is missing', () => {
+    expect(() =>
+      // @ts-expect-error Stubbing localstorage for error checking
+      createLocalStorage({ appName, networkName, localStorage: null })
+    ).toThrow('localStorage is not available in this environment');
+  });
+
+  test('writes and reads to/from localStorage correctly', async () => {
+    mockLocalStorage.setItem(expect.any(String), JSON.stringify(authData));
+    const storage = createLocalStorage({
+      appName,
+      networkName,
+      localStorage: mockLocalStorage,
+    });
+
+    expect(storage.read({ pkpAddress })).resolves.toEqual(authData);
+  });
+
+  test('returns null when reading nonexistent data', async () => {
+    const storage = createLocalStorage({
+      appName,
+      networkName,
+      localStorage: mockLocalStorage,
+    });
+    const result = await storage.read({ pkpAddress });
+
+    expect(result).toBeNull();
+  });
+
+  test('isolates data between different network names', async () => {
+    const storageNetworkA = createLocalStorage({
+      appName,
+      networkName: 'networkA',
+      localStorage: mockLocalStorage,
+    });
+    const storageNetworkB = createLocalStorage({
+      appName,
+      networkName: 'networkB',
+      localStorage: mockLocalStorage,
+    });
+
+    const authDataNetworkA = { ...authData, credential: 'networkA' };
+    const authDataNetworkB = { ...authData, credential: 'networkB' };
+
+    await storageNetworkA.write({
+      pkpAddress,
+      authData: authDataNetworkA,
+    });
+
+    expect(storageNetworkA.read({ pkpAddress })).resolves.toEqual(
+      authDataNetworkA
+    );
+    expect(storageNetworkB.read({ pkpAddress })).resolves.toBeNull();
+
+    await storageNetworkB.write({
+      pkpAddress,
+      authData: authDataNetworkB,
+    });
+
+    expect(storageNetworkA.read({ pkpAddress })).resolves.toEqual(
+      authDataNetworkA
+    );
+    expect(storageNetworkB.read({ pkpAddress })).resolves.toEqual(
+      authDataNetworkB
+    );
+  });
+
+  test('isolates data between different app names', async () => {
+    const storageAppA = createLocalStorage({
+      appName: 'appA',
+      networkName,
+      localStorage: mockLocalStorage,
+    });
+    const storageAppB = createLocalStorage({
+      appName: 'appB',
+      networkName,
+      localStorage: mockLocalStorage,
+    });
+
+    const authDataNetworkB = { ...authData, credential: 'networkB' };
+
+    await storageAppA.write({ pkpAddress, authData });
+    expect(storageAppA.read({ pkpAddress })).resolves.toEqual(authData);
+    expect(storageAppB.read({ pkpAddress })).resolves.toBeNull();
+
+    await storageAppB.write({ pkpAddress, authData: authDataNetworkB });
+    expect(storageAppB.read({ pkpAddress })).resolves.toEqual(authDataNetworkB);
+    expect(storageAppA.read({ pkpAddress })).resolves.toEqual(authData);
+  });
+});

packages/auth/src/lib/storage/localStorage.ts

@@ -0,0 +1,103 @@
+import type { LitAuthStorageProvider } from './types';
+import type { LitAuthData } from '../types';
+
+const LOCALSTORAGE_LIT_AUTH_PREFIX = 'lit-auth';
+
+interface LocalStorageConfig {
+  appName: string;
+  localStorage?: WindowLocalStorage['localStorage'];
+  networkName: string;
+}
+
+function assertLocalstorageValid(
+  localStorage: unknown
+): asserts localStorage is WindowLocalStorage['localStorage'] {
+  console.log('localStorage is...', localStorage);
+  if (!localStorage) {
+    throw new Error('localStorage is not available in this environment');
+  }
+
+  if (typeof localStorage !== 'object') {
+    throw new Error('localStorage is not an object');
+  }
+
+  if (
+    !('getItem' in localStorage) ||
+    typeof localStorage.getItem !== 'function'
+  ) {
+    throw new Error('localStorage does not have `getItem` method');
+  }
+
+  if (
+    !('setItem' in localStorage) ||
+    typeof localStorage.setItem !== 'function'
+  ) {
+    throw new Error('localStorage does not have `setItem` method');
+  }
+}
+
+/**
+ * Builds a lookup key for localStorage based on the provided parameters.
+ * Ensures that all auth data loaded for a given PKP is for the expected LIT network
+ * in cases where the same environment may be used to communicate w/ multiple networks
+ *
+ * @param {object} params - The parameters required to build the lookup key.
+ * @param {string} params.appName - The name of the application; used to store different auth material for the same PKP on the same domain
+ * @param {string} params.networkName - The name of the network; used to store different auth material per LIT network
+ * @param {string} params.pkpAddress - The LIT PKP address.
+ *
+ * @returns {string} The generated lookup key for localStorage.
+ *
+ * @private
+ */
+function buildLookupKey({
+  appName,
+  networkName,
+  pkpAddress,
+}: {
+  appName: string;
+  networkName: string;
+  pkpAddress: string;
+}): string {
+  return `${LOCALSTORAGE_LIT_AUTH_PREFIX}:${appName}:${networkName}:${pkpAddress}`;
+}
+
+export function localStorage({
+  appName,
+  networkName,
+  localStorage = globalThis.localStorage,
+}: LocalStorageConfig): LitAuthStorageProvider {
+  assertLocalstorageValid(localStorage);
+
+  return {
+    config: { appName, networkName, localStorage },
+
+    async write({ pkpAddress, authData }) {
+      localStorage.setItem(
+        buildLookupKey({
+          appName,
+          networkName,
+          pkpAddress,
+        }),
+        JSON.stringify(authData)
+      );
+    },
+
+    async read({ pkpAddress }): Promise<LitAuthData | null> {
+      const value = localStorage.getItem(
+        buildLookupKey({
+          appName,
+          networkName,
+          pkpAddress,
+        })
+      );
+
+      if (!value) {
+        // Empty string will be converted to null
+        return null;
+      } else {
+        return JSON.parse(value);
+      }
+    },
+  };
+}

packages/auth/src/lib/storage/types.ts

@@ -0,0 +1,15 @@
+import type { LitAuthData } from '../types';
+
+export interface LitAuthStorageProvider {
+  config: unknown;
+
+  read<T extends { pkpAddress: string }>(
+    params: T,
+    options?: unknown
+  ): Promise<LitAuthData | null>;
+
+  write<T extends { pkpAddress: string; authData: LitAuthData }>(
+    params: T,
+    options?: unknown
+  ): Promise<void>;
+}