chore: add CoderTokenAuth class

plugins/backstage-plugin-coder/src/api/Auth.ts

@@ -0,0 +1,70 @@
+/**
+ * @file Defines shared values and types used among any custom Coder auth
+ * implementations for the frontend.
+ */
+import { createApiRef } from '@backstage/core-plugin-api';
+import { CODER_API_REF_ID_PREFIX } from '../typesConstants';
+
+/**
+ * Data about the auth that can safely be exposed throughout multiple parts of
+ * the application without too much worry about security.
+ *
+ * All values should be JSON-serializable.
+ */
+export type SafeAuthData = Readonly<{
+  isTokenValid: boolean;
+  tokenHash: number | null;
+  initialTokenHash: number | null;
+  isInsideGracePeriod: boolean;
+}>;
+
+export type AuthSubscriptionCallback = (payload: SafeAuthData) => void;
+export type AuthValidatorDispatch = (newStatus: boolean) => void;
+
+/**
+ * Shared set of properties among all Coder auth implementations
+ */
+export type CoderAuthApi = SafeAuthData & {
+  /**
+   * Requests the token from the auth class. This may not always succeed (e.g.,
+   * auth doesn't think it's safe, there is no token to provide), in which case,
+   * the value will be null.
+   */
+  requestToken: () => string | null;
+
+  /**
+   * Gives back a "state setter" that lets a different class dispatch a new auth
+   * status to the auth class implementation.
+   *
+   * Use this to send the new status you think the auth should have. The auth
+   * will decide whether it will let the dispatch go through and update state.
+   */
+  getAuthStateSetter: () => AuthValidatorDispatch;
+
+  /**
+   * Subscribes an external system to auth changes.
+   *
+   * Returns an pre-wired unsubscribe callback to remove fuss of needing to hold
+   * onto the original callback if it's not directly needed anymore
+   */
+  subscribe: (callback: AuthSubscriptionCallback) => () => void;
+
+  /**
+   * Lets an external system unsubscribe from auth changes.
+   */
+  unsubscribe: (callback: AuthSubscriptionCallback) => void;
+
+  /**
+   * Lets an external system get a fully immutable snapshot of the current auth
+   * state.
+   */
+  getStateSnapshot: () => SafeAuthData;
+};
+
+/**
+ * A single, shared auth API ref that can be used with any of the CoderAuth
+ * API classes (CoderTokenAuth, eventually CoderOAuth, etc.)
+ */
+export const coderAuthApiRef = createApiRef<CoderAuthApi>({
+  id: `${CODER_API_REF_ID_PREFIX}.auth`,
+});

plugins/backstage-plugin-coder/src/api/CoderTokenAuth.test.ts

@@ -0,0 +1,255 @@
+import { getMockLocalStorage } from '../testHelpers/mockBackstageData';
+import { hashValue } from '../utils/crypto';
+import type { SafeAuthData } from './Auth';
+import { CoderTokenAuth, AUTH_SETTER_TIMEOUT_MS } from './CoderTokenAuth';
+
+beforeEach(() => {
+  jest.useFakeTimers();
+});
+
+afterEach(() => {
+  jest.runOnlyPendingTimers();
+  jest.useRealTimers();
+});
+
+// Aggressively short time to ensure that the class can accept any arbitrary
+// timeout value. The auth logic is 90% synchronous, so this has no real risks
+const defaultGracePeriodTimeoutMs = 1_000;
+const defaultLocalStorageKey = 'backstage-plugin-coder/test';
+
+type SetupAuthInputs = Readonly<{
+  initialData?: Record<string, string>;
+  gracePeriodTimeoutMs?: number;
+  localStorageKey?: string;
+}>;
+
+type SetupAuthResult = Readonly<{
+  localStorage: Storage;
+  auth: CoderTokenAuth;
+}>;
+
+function setupAuth(inputs?: SetupAuthInputs): SetupAuthResult {
+  const {
+    initialData,
+    localStorageKey = defaultLocalStorageKey,
+    gracePeriodTimeoutMs = defaultGracePeriodTimeoutMs,
+  } = inputs ?? {};
+
+  const localStorage = getMockLocalStorage(initialData);
+  const auth = new CoderTokenAuth({
+    localStorage,
+    localStorageKey,
+    gracePeriodTimeoutMs,
+  });
+
+  return { auth, localStorage };
+}
+
+describe(`${CoderTokenAuth.name}`, () => {
+  describe('Subscriptions', () => {
+    it('Lets external systems subscribe to auth changes', () => {
+      const onChange = jest.fn();
+      const { auth } = setupAuth();
+      auth.subscribe(onChange);
+
+      auth.registerNewToken('blah');
+      expect(onChange).toHaveBeenCalled();
+    });
+
+    it('Lets external systems *un*subscribe to auth changes', () => {
+      const onChange = jest.fn();
+      const { auth } = setupAuth();
+      auth.subscribe(onChange);
+      auth.unsubscribe(onChange);
+
+      auth.registerNewToken('blah');
+      expect(onChange).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Setting tokens', () => {
+    it('Will reject empty strings', () => {
+      const onChange = jest.fn();
+      const { auth } = setupAuth();
+      auth.subscribe(onChange);
+
+      auth.registerNewToken('');
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("Will reject new token if it's the same as the current one", () => {
+      const onChange = jest.fn();
+      const { auth } = setupAuth();
+      auth.subscribe(onChange);
+
+      auth.registerNewToken('blah');
+      auth.registerNewToken('blah');
+      expect(onChange).toHaveBeenCalledTimes(1);
+    });
+
+    it('Will immediately notify subscriptions that the auth has been invalidated when a new token is set', () => {
+      const onChange = jest.fn();
+      const { auth } = setupAuth();
+      auth.subscribe(onChange);
+
+      auth.registerNewToken('blah');
+      expect(onChange).toHaveBeenCalledWith(
+        expect.objectContaining<Partial<SafeAuthData>>({
+          isTokenValid: false,
+        }),
+      );
+    });
+  });
+
+  describe('getAuthStateSetter', () => {
+    it('Lets another system set the auth state', () => {
+      const testToken = 'blah';
+      const hashed = hashValue(testToken);
+      const { auth } = setupAuth();
+
+      auth.registerNewToken(testToken);
+      const dispatchNewStatus = auth.getAuthStateSetter();
+      dispatchNewStatus(true);
+
+      const snapshot = auth.getStateSnapshot();
+      expect(snapshot).toEqual(
+        expect.objectContaining<Partial<SafeAuthData>>({
+          tokenHash: hashed,
+          isTokenValid: true,
+        }),
+      );
+    });
+
+    it('Rejects state changes if there is no token when the state setter is made', () => {
+      const onChange = jest.fn();
+      const { auth } = setupAuth();
+
+      auth.subscribe(onChange);
+      const dispatchNewStatus = auth.getAuthStateSetter();
+      dispatchNewStatus(true);
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it('Disables the state setter if the token changes after the setter was created', () => {
+      const onChange = jest.fn();
+      const { auth } = setupAuth();
+
+      auth.registerNewToken('dog');
+      const dispatchNewStatus = auth.getAuthStateSetter();
+      auth.registerNewToken('cat');
+
+      dispatchNewStatus(true);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("Makes the state setter 'go inert' after a set amount of time (will start rejecting dispatches)", async () => {
+      const { auth } = setupAuth();
+      auth.registerNewToken('blah');
+      const dispatchNewStatus = auth.getAuthStateSetter();
+
+      // Give an extra 100ms to give code time to flush state changes
+      await jest.advanceTimersByTimeAsync(AUTH_SETTER_TIMEOUT_MS + 100);
+      dispatchNewStatus(true);
+
+      const snapshot = auth.getStateSnapshot();
+      expect(snapshot).toEqual(
+        expect.objectContaining<Partial<SafeAuthData>>({
+          isTokenValid: false,
+        }),
+      );
+    });
+
+    it("Will eventually leave 'grace period' state when auth validity flips from true to false", async () => {
+      const { auth } = setupAuth();
+      auth.registerNewToken('blah');
+      const dispatchNewStatus = auth.getAuthStateSetter();
+
+      dispatchNewStatus(true);
+      const snapshot1 = auth.getStateSnapshot();
+      expect(snapshot1).toEqual(
+        expect.objectContaining<Partial<SafeAuthData>>({
+          isTokenValid: true,
+          isInsideGracePeriod: true,
+        }),
+      );
+
+      dispatchNewStatus(false);
+      const snapshot2 = auth.getStateSnapshot();
+      expect(snapshot2).toEqual(
+        expect.objectContaining<Partial<SafeAuthData>>({
+          isTokenValid: false,
+          isInsideGracePeriod: true,
+        }),
+      );
+
+      await jest.advanceTimersByTimeAsync(defaultGracePeriodTimeoutMs);
+      const snapshot3 = auth.getStateSnapshot();
+      expect(snapshot3).toEqual(
+        expect.objectContaining<Partial<SafeAuthData>>({
+          isTokenValid: false,
+          isInsideGracePeriod: false,
+        }),
+      );
+    });
+  });
+
+  describe('localStorage', () => {
+    it('Will read from localStorage when first initialized', () => {
+      const testValue = 'blah';
+      const hashed = hashValue(testValue);
+
+      const { auth } = setupAuth({
+        initialData: {
+          [defaultLocalStorageKey]: testValue,
+        },
+      });
+
+      const initialStateSnapshot = auth.getStateSnapshot();
+      expect(initialStateSnapshot).toEqual(
+        expect.objectContaining<Partial<SafeAuthData>>({
+          initialTokenHash: hashed,
+          tokenHash: hashed,
+          isTokenValid: false,
+        }),
+      );
+    });
+
+    it('Will immediately update localStorage when token is cleared', () => {
+      const { auth, localStorage } = setupAuth({
+        initialData: {
+          [defaultLocalStorageKey]: 'blah',
+        },
+      });
+
+      auth.clearToken();
+      expect(localStorage.getItem(defaultLocalStorageKey)).toEqual('');
+    });
+
+    it('Will write to localStorage when the token is confirmed to be valid', () => {
+      const testToken = 'blah';
+      const { auth, localStorage } = setupAuth();
+
+      auth.registerNewToken(testToken);
+      const dispatchNewStatus = auth.getAuthStateSetter();
+      dispatchNewStatus(true);
+
+      expect(localStorage.getItem(defaultLocalStorageKey)).toEqual(testToken);
+    });
+
+    it('Lets the user define a custom local storage key', () => {
+      const customKey = 'blah';
+      const testToken = 'blah blah';
+
+      const { auth, localStorage } = setupAuth({
+        localStorageKey: customKey,
+      });
+
+      auth.registerNewToken(testToken);
+      const dispatchNewStatus = auth.getAuthStateSetter();
+      dispatchNewStatus(true);
+
+      expect(localStorage.getItem(customKey)).toEqual(testToken);
+    });
+  });
+});