@civic/auth 0.1.3 → 0.1.4-beta.1

package/src/reactjs/providers/index.ts

@@ -1,27 +0,0 @@
-export {
-  UserProvider,
-  UserContext,
-  type UserContextType,
-} from "@/shared/providers/UserProvider.js";
-
-export {
-  TokenProvider,
-  TokenContext,
-  type TokenContextType,
-} from "@/shared/providers/TokenProvider.js";
-
-export { AuthProvider } from "@/shared/providers/AuthProvider.js";
-
-export {
-  SessionProvider,
-  SessionContext,
-  type SessionContextType,
-} from "@/shared/providers/SessionProvider.js";
-
-export {
-  CivicAuthProvider,
-  type CivicAuthProviderProps,
-} from "@/shared/providers/CivicAuthProvider.js";
-
-export { AuthContext } from "@/shared/providers/AuthContext.js";
-export type { AuthContextType } from "@/shared/providers/AuthContext.js";

package/src/server/ServerAuthenticationResolver.ts

@@ -1,107 +0,0 @@
-import { GenericPublicClientPKCEProducer } from "@/services/PKCE.js";
-import { OAuth2Client } from "oslo/oauth2";
-import type {
-  AuthStorage,
-  Endpoints,
-  OIDCTokenResponseBody,
-  SessionData,
-} from "@/types.js";
-import type { AuthConfig } from "@/server/config.js";
-import {
-  exchangeTokens,
-  getEndpointsWithOverrides,
-  retrieveTokens,
-  storeTokens,
-} from "@/shared/lib/util.js";
-import type { AuthenticationResolver, PKCEProducer } from "@/services/types.ts";
-import { DEFAULT_AUTH_SERVER } from "@/constants.js";
-
-export class ServerAuthenticationResolver implements AuthenticationResolver {
-  private pkceProducer: PKCEProducer;
-  private oauth2client: OAuth2Client | undefined;
-  private endpoints: Endpoints | undefined;
-
-  private constructor(
-    readonly authConfig: AuthConfig,
-    readonly storage: AuthStorage,
-    readonly endpointOverrides?: Partial<Endpoints>,
-  ) {
-    this.pkceProducer = new GenericPublicClientPKCEProducer(storage);
-  }
-  validateExistingSession(): Promise<SessionData> {
-    throw new Error("Method not implemented.");
-  }
-
-  get oauthServer(): string {
-    return this.authConfig.oauthServer || DEFAULT_AUTH_SERVER;
-  }
-
-  async init(): Promise<this> {
-    // resolve oauth config
-    this.endpoints = await getEndpointsWithOverrides(
-      this.oauthServer,
-      this.endpointOverrides,
-    );
-    this.oauth2client = new OAuth2Client(
-      this.authConfig.clientId,
-      this.endpoints.auth,
-      this.endpoints.token,
-      {
-        redirectURI: this.authConfig.redirectUrl,
-      },
-    );
-
-    return this;
-  }
-
-  async tokenExchange(
-    code: string,
-    state: string,
-  ): Promise<OIDCTokenResponseBody> {
-    if (!this.oauth2client) await this.init();
-    const codeVerifier = await this.pkceProducer.getCodeVerifier();
-    if (!codeVerifier) throw new Error("Code verifier not found in storage");
-
-    // exchange auth code for tokens
-    const tokens = await exchangeTokens(
-      code,
-      state,
-      this.pkceProducer,
-      this.oauth2client!, // clean up types here to avoid the ! operator
-      this.oauthServer,
-      this.endpoints!, // clean up types here to avoid the ! operator
-    );
-
-    await storeTokens(this.storage, tokens);
-
-    return tokens;
-  }
-
-  async getSessionData(): Promise<SessionData | null> {
-    const storageData = await retrieveTokens(this.storage);
-
-    if (!storageData) return null;
-
-    return {
-      authenticated: !!storageData.id_token,
-      idToken: storageData.id_token,
-      accessToken: storageData.access_token,
-      refreshToken: storageData.refresh_token,
-    };
-  }
-
-  static async build(
-    authConfig: AuthConfig,
-    storage: AuthStorage,
-    endpointOverrides?: Partial<Endpoints>,
-  ): Promise<AuthenticationResolver> {
-    const resolver = new ServerAuthenticationResolver(
-      authConfig,
-      storage,
-      endpointOverrides,
-    );
-    await resolver.init();
-
-    return resolver;
-  }
-}

package/src/server/config.ts

@@ -1,9 +0,0 @@
-import type { Endpoints } from "@/types.ts";
-
-export type AuthConfig = {
-  clientId: string;
-  redirectUrl: string;
-  oauthServer?: string;
-  challengeUrl?: string;
-  endpointOverrides?: Partial<Endpoints> | undefined;
-};

package/src/server/index.ts

@@ -1,13 +0,0 @@
-export { CookieStorage } from "@/shared/lib/storage.js";
-export type {
-  SessionStorage,
-  CookieStorageSettings,
-} from "@/shared/lib/storage.js";
-export {
-  resolveOAuthAccessCode,
-  isLoggedIn,
-  buildLoginUrl,
-} from "@/server/login.js";
-export type { AuthConfig } from "@/server/config.js";
-export { getUser } from "@/shared/lib/session.js";
-export { refreshTokens } from "@/server/refresh.js";

package/src/server/login.ts

@@ -1,59 +0,0 @@
-import type { AuthStorage, OIDCTokenResponseBody } from "@/types.js";
-import { DEFAULT_AUTH_SERVER, DEFAULT_SCOPES } from "@/constants.js";
-import { GenericAuthenticationInitiator } from "@/services/AuthenticationService.js";
-import { GenericPublicClientPKCEProducer } from "@/services/PKCE.js";
-import { ServerAuthenticationResolver } from "@/server/ServerAuthenticationResolver.js";
-import type { AuthConfig } from "@/server/config.ts";
-/**
- * Resolve an OAuth access code to a set of OIDC tokens
- * @param code The access code, typically from a query parameter in the redirect url
- * @param state The oauth random state string, used to distinguish between requests. Typically also passed in the redirect url
- * @param storage The place that this server uses to store session data (e.g. a cookie store)
- * @param config Oauth Server configuration
- */
-export async function resolveOAuthAccessCode(
-  code: string,
-  state: string,
-  storage: AuthStorage,
-  config: AuthConfig,
-): Promise<OIDCTokenResponseBody> {
-  const authSessionService = await ServerAuthenticationResolver.build(
-    {
-      ...config,
-      oauthServer: config.oauthServer ?? DEFAULT_AUTH_SERVER,
-    },
-    storage,
-    config.endpointOverrides,
-  );
-
-  return authSessionService.tokenExchange(code, state);
-}
-
-export async function isLoggedIn(storage: AuthStorage): Promise<boolean> {
-  return !!(await storage.get("id_token"));
-}
-
-export async function buildLoginUrl(
-  config: Pick<AuthConfig, "clientId" | "redirectUrl"> &
-    Partial<Pick<AuthConfig, "oauthServer">> & {
-      scopes?: string[];
-      state?: string;
-      nonce?: string;
-    },
-  storage: AuthStorage,
-): Promise<URL> {
-  // generate a random state if not provided
-  const state = config.state ?? Math.random().toString(36).substring(2);
-  const scopes = config.scopes ?? DEFAULT_SCOPES;
-  const pkceProducer = new GenericPublicClientPKCEProducer(storage);
-  const authInitiator = new GenericAuthenticationInitiator({
-    ...config,
-    state,
-    scopes,
-    oauthServer: config.oauthServer ?? DEFAULT_AUTH_SERVER,
-    // When retrieving the PKCE challenge on the server-side, we produce it and store it in the session
-    pkceConsumer: pkceProducer,
-  });
-
-  return authInitiator.signIn();
-}

package/src/server/refresh.ts

@@ -1,23 +0,0 @@
-import type { AuthStorage, OIDCTokenResponseBody } from "@/types.js";
-import { DEFAULT_AUTH_SERVER } from "@/constants.js";
-import { GenericAuthenticationRefresher } from "@/shared/lib/GenericAuthenticationRefresher.js";
-import type { AuthConfig } from "@/server/config.ts";
-
-/**
- * Refresh the current set of OIDC tokens
- */
-export async function refreshTokens(
-  storage: AuthStorage,
-  config: AuthConfig,
-): Promise<OIDCTokenResponseBody> {
-  const refresher = await GenericAuthenticationRefresher.build(
-    {
-      ...config,
-      oauthServer: config.oauthServer ?? DEFAULT_AUTH_SERVER,
-    },
-    storage,
-    config.endpointOverrides,
-  );
-
-  return refresher.refreshTokens();
-}

package/src/services/AuthenticationService.ts

@@ -1,329 +0,0 @@
-// Proposals for revised versions of the SessionService AKA AuthSessionService
-
-import type {
-  DisplayMode,
-  Endpoints,
-  LoginPostMessage,
-  OIDCTokenResponseBody,
-  SessionData,
-} from "@/types.js";
-import { BrowserPublicClientPKCEProducer } from "@/services/PKCE.js";
-import {
-  clearTokens,
-  clearUser,
-  exchangeTokens,
-  generateOauthLoginUrl,
-  generateOauthLogoutUrl,
-  getEndpointsWithOverrides,
-  retrieveTokens,
-  storeTokens,
-  validateOauth2Tokens,
-} from "@/shared/lib/util.js";
-import { displayModeFromState, generateState } from "@/lib/oauth.js";
-import { OAuth2Client } from "oslo/oauth2";
-import { LocalStorageAdapter } from "@/browser/storage.js";
-import type {
-  AuthenticationInitiator,
-  AuthenticationResolver,
-  PKCEConsumer,
-} from "@/services/types.js";
-import { PopupError } from "@/services/types.js";
-import { removeParamsWithoutReload } from "@/lib/windowUtil.js";
-import { DEFAULT_OAUTH_GET_PARAMS } from "@/constants.js";
-import { validateLoginAppPostMessage } from "@/lib/postMessage.js";
-
-/**
- * An authentication initiator that works on a browser. Since this is just triggering
- * login and logout, session data is not stored here.
- * An associated AuthenticationResolver would be needed to get the session data.
- * Storage is needed for the code verifier, this is the domain of the PKCEConsumer
- * The storage used by the PKCEConsumer should be available to the AuthenticationResolver.
- *
- * Example usage:
- *
- * 1) Client-only SPA -eg a react app with no server:
- * new BrowserAuthenticationInitiator({
- *   pkceConsumer: new BrowserPublicClientPKCEProducer(), // generate and retrieve the challenge client-side
- *   ... other config
- * })
- *
- * 2) Client-side of a client/server app - eg a react app with a backend:
- * new BrowserAuthenticationInitiator({
- *  pkceConsumer: new ConfidentialClientPKCEConsumer("https://myserver.com/pkce"), // get the challenge from the server
- *  ... other config
- * })
- */
-export class BrowserAuthenticationInitiator implements AuthenticationInitiator {
-  private postMessageHandler: null | ((event: MessageEvent) => void) = null;
-
-  protected config: {
-    clientId: string;
-    redirectUrl: string;
-    state: string;
-    scopes: string[];
-    // determines whether to trigger the login/logout in an iframe, a new browser window, or redirect the current one.
-    displayMode: DisplayMode;
-    oauthServer: string;
-    // the endpoints to use for the login (if not obtained from the auth server
-    endpointOverrides?: Partial<Endpoints>;
-    // used to get the PKCE challenge
-    pkceConsumer: PKCEConsumer;
-    // the nonce to use for the login
-    nonce?: string;
-  };
-
-  constructor(config: typeof this.config) {
-    this.config = config;
-  }
-
-  async handleLoginAppPopupFailed(redirectUrl: string) {
-    console.warn(
-      "Login app popup failed open a popup, using redirect mode instead...",
-      redirectUrl,
-    );
-    window.location.href = redirectUrl;
-  }
-
-  // Use the config (Client ID, scopes OAuth Server, Endpoints, PKCEConsumer) to generate a new login url
-  // and then use the display mode to decide how to send the user there
-  async signIn(iframeRef: HTMLIFrameElement | null): Promise<URL> {
-    const url = await generateOauthLoginUrl(this.config);
-
-    this.postMessageHandler = (event: MessageEvent) => {
-      const thisURL = new URL(window.location.href);
-      if (
-        event.origin.endsWith("civic.com") ||
-        thisURL.hostname === "localhost"
-      ) {
-        if (!validateLoginAppPostMessage(event.data, this.config.clientId)) {
-          return;
-        }
-        const loginMessage = event.data as LoginPostMessage;
-        this.handleLoginAppPopupFailed(loginMessage.data.url);
-      }
-    };
-
-    window.addEventListener("message", this.postMessageHandler);
-
-    if (this.config.displayMode === "iframe") {
-      if (!iframeRef)
-        throw new Error("iframeRef is required for displayMode 'iframe'");
-      iframeRef.setAttribute("src", url.toString());
-    }
-
-    if (this.config.displayMode === "redirect") {
-      window.location.href = url.toString();
-    }
-
-    if (this.config.displayMode === "new_tab") {
-      try {
-        const popupWindow = window.open(url.toString(), "_blank");
-        if (!popupWindow) {
-          throw new PopupError("Failed to open popup window");
-        }
-      } catch (error) {
-        console.error("popupWindow", error);
-        throw new PopupError(
-          "window.open has thrown: Failed to open popup window",
-        );
-      }
-    }
-
-    return url;
-  }
-
-  async signOut(): Promise<URL> {
-    const localStorage = new LocalStorageAdapter();
-    await clearTokens(localStorage);
-    await clearUser(localStorage);
-    // TODO open the iframe or new tab etc: the logout URL is not currently
-    // supported by on the oauth, so just clear state until then
-    const url = await generateOauthLogoutUrl(this.config);
-    return url;
-  }
-
-  cleanup() {
-    if (this.postMessageHandler) {
-      window.removeEventListener("message", this.postMessageHandler);
-    }
-  }
-}
-
-/** A general-purpose authentication initiator, that just generates urls, but lets
- * the caller decide how to use them. This is useful for server-side applications
- * that may serve this URL to their front-ends or just call them directly
- */
-export class GenericAuthenticationInitiator implements AuthenticationInitiator {
-  protected config: {
-    clientId: string;
-    redirectUrl: string;
-    state: string;
-    scopes: string[];
-    oauthServer: string;
-    nonce?: string;
-    // the endpoints to use for the login (if not obtained from the auth server)
-    endpointOverrides?: Partial<Endpoints>;
-    // used to get the PKCE challenge
-    pkceConsumer: PKCEConsumer;
-  };
-
-  constructor(config: typeof this.config) {
-    this.config = config;
-  }
-
-  // Use the config (Client ID, scopes OAuth Server, Endpoints, PKCEConsumer) to generate a new login url
-  // and simply return the url
-  async signIn(): Promise<URL> {
-    return generateOauthLoginUrl(this.config);
-  }
-
-  async signOut(): Promise<URL> {
-    return generateOauthLogoutUrl(this.config);
-  }
-}
-
-type BrowserAuthenticationConfig = {
-  clientId: string;
-  redirectUrl: string;
-  scopes: string[];
-  oauthServer: string;
-  endpointOverrides?: Partial<Endpoints>;
-  displayMode: DisplayMode;
-};
-
-/**
- * An authentication resolver that can run on the browser (i.e. a public client)
- * It uses PKCE for security. PKCE and Session data are stored in local storage
- */
-export class BrowserAuthenticationService extends BrowserAuthenticationInitiator {
-  private oauth2client: OAuth2Client | undefined;
-  private endpoints: Endpoints | undefined;
-
-  // TODO WIP - perhaps we want to keep resolver and initiator separate here
-  constructor(
-    config: BrowserAuthenticationConfig,
-    // Since we are running fully on the client, we produce as well as consume the PKCE challenge
-    protected pkceProducer = new BrowserPublicClientPKCEProducer(),
-  ) {
-    super({
-      ...config,
-      state: generateState(config.displayMode),
-      // Store and retrieve the PKCE challenge in local storage
-      pkceConsumer: pkceProducer,
-    });
-  }
-
-  // TODO too much code duplication here between the browser and the server variant.
-  // Suggestion for refactor: Standardise the config for AuthenticationResolvers and create a one-shot
-  // function for generating an oauth2client from it
-  async init(): Promise<this> {
-    // resolve oauth config
-    this.endpoints = await getEndpointsWithOverrides(
-      this.config.oauthServer,
-      this.config.endpointOverrides,
-    );
-    this.oauth2client = new OAuth2Client(
-      this.config.clientId,
-      this.endpoints.auth,
-      this.endpoints.token,
-      {
-        redirectURI: this.config.redirectUrl,
-      },
-    );
-
-    return this;
-  }
-
-  // Two responsibilities:
-  // 1. resolve the auth code to get the tokens (should use library code)
-  // 2. store the tokens in local storage
-  async tokenExchange(
-    code: string,
-    state: string,
-  ): Promise<OIDCTokenResponseBody> {
-    if (!this.oauth2client) await this.init();
-    const codeVerifier = await this.pkceProducer.getCodeVerifier();
-    if (!codeVerifier) throw new Error("Code verifier not found in storage");
-
-    // exchange auth code for tokens
-    const tokens = await exchangeTokens(
-      code,
-      state,
-      this.pkceProducer,
-      this.oauth2client!, // clean up types here to avoid the ! operator
-      this.config.oauthServer,
-      this.endpoints!, // clean up types here to avoid the ! operator
-    );
-
-    await storeTokens(new LocalStorageAdapter(), tokens);
-
-    // cleanup the browser window if needed
-    const parsedDisplayMode = displayModeFromState(
-      state,
-      this.config.displayMode,
-    );
-
-    if (parsedDisplayMode === "new_tab") {
-      // Close the popup window
-      window.close();
-    }
-    // these are the default oAuth params that get added to the URL in redirect which we want to remove if present
-    removeParamsWithoutReload(DEFAULT_OAUTH_GET_PARAMS);
-    return tokens;
-  }
-
-  // Get the session data from local storage
-  async getSessionData(): Promise<SessionData | null> {
-    const storageData = await retrieveTokens(new LocalStorageAdapter());
-
-    if (!storageData) return null;
-
-    return {
-      authenticated: !!storageData.id_token,
-      idToken: storageData.id_token,
-      accessToken: storageData.access_token,
-      refreshToken: storageData.refresh_token,
-    };
-  }
-
-  async validateExistingSession(): Promise<SessionData> {
-    try {
-      const sessionData = await this.getSessionData();
-      if (!sessionData?.idToken || !sessionData.accessToken) {
-        const unAuthenticatedSession = { ...sessionData, authenticated: false };
-        await clearTokens(new LocalStorageAdapter());
-        return unAuthenticatedSession;
-      }
-      if (!this.endpoints || !this.oauth2client) await this.init();
-
-      // this function will throw if any of the tokens are invalid
-      await validateOauth2Tokens(
-        {
-          access_token: sessionData.accessToken,
-          id_token: sessionData.idToken,
-          refresh_token: sessionData.refreshToken,
-        },
-        this.endpoints!,
-        this.oauth2client!,
-        this.config.oauthServer,
-      );
-      return sessionData;
-    } catch (error) {
-      console.warn("Failed to validate existing tokens", error);
-      const unAuthenticatedSession = {
-        authenticated: false,
-      };
-      await clearTokens(new LocalStorageAdapter());
-      return unAuthenticatedSession;
-    }
-  }
-
-  static async build(
-    config: BrowserAuthenticationConfig,
-  ): Promise<AuthenticationResolver> {
-    const resolver = new BrowserAuthenticationService(config);
-    await resolver.init();
-
-    return resolver;
-  }
-}

package/src/services/PKCE.ts

@@ -1,45 +0,0 @@
-import { deriveCodeChallenge } from "@/shared/lib/util.js";
-import { generateCodeVerifier } from "oslo/oauth2";
-import { LocalStorageAdapter } from "@/browser/storage.js";
-import type { PKCEConsumer, PKCEProducer } from "@/services/types.js";
-import type { AuthStorage } from "@/types.js";
-import { CodeVerifier } from "@/shared/lib/types.js";
-
-/** A PKCE consumer that retrieves the challenge from a server endpoint */
-export class ConfidentialClientPKCEConsumer implements PKCEConsumer {
-  constructor(private pkceChallengeEndpoint: string) {}
-  async getCodeChallenge(): Promise<string> {
-    const response = await fetch(
-      `${this.pkceChallengeEndpoint}?appUrl=${window.location.origin}`,
-    );
-    const data = (await response.json()) as { challenge: string };
-    return data.challenge;
-  }
-}
-
-/** A PKCE Producer that can generate and store a code verifier, but is agnostic as to the storage location */
-export class GenericPublicClientPKCEProducer implements PKCEProducer {
-  constructor(private storage: AuthStorage) {}
-
-  // if there is already a verifier, return it,
-  // If not, create a new one and store it
-  async getCodeChallenge(): Promise<string> {
-    // let verifier = await this.getCodeVerifier();
-    // if (!verifier) {
-    const verifier = generateCodeVerifier();
-    this.storage.set(CodeVerifier.COOKIE_NAME, verifier);
-    // }
-    return deriveCodeChallenge(verifier);
-  }
-  // if there is already a verifier, return it,
-  async getCodeVerifier(): Promise<string | null> {
-    return this.storage.get(CodeVerifier.COOKIE_NAME);
-  }
-}
-
-/** A PKCE Producer that is expected to run on a browser, and does not need a backend */
-export class BrowserPublicClientPKCEProducer extends GenericPublicClientPKCEProducer {
-  constructor() {
-    super(new LocalStorageAdapter());
-  }
-}

package/src/services/types.ts

@@ -1,54 +0,0 @@
-import type { OIDCTokenResponseBody, SessionData } from "@/types.js";
-
-// A PKCEConsumer can get a code challenge to use in the login process
-// A PKCEProducer can also generate and store verifiers. The producer must also be a consumer in order to get the challenge from an existing flow
-// Examples:
-// - Client-only SPA: The SPA generates the code challenge and verifier, stores the verifier in state and returns the code challenge
-// Note - The SPA should use PKCEProducer instead to do both
-// - Client-side of a client/server app: The client calls the backend to get the challenge.
-// - Server-side: The server should generate a new stored verifier and derive the challenge from it.
-export interface PKCEConsumer {
-  // Retrieve a new PKCE challenge
-  getCodeChallenge(): Promise<string>;
-}
-
-// All producers are consumers, because the producer can get its own challenge
-export interface PKCEProducer extends PKCEConsumer {
-  // Retrieve the PKCE challenge from the session if one exists
-  getCodeVerifier(): Promise<string | null>;
-}
-
-// A service that can initiate requests to login or log out
-export interface AuthenticationInitiator {
-  // trigger a new login
-  signIn(iframeRef: HTMLIFrameElement | null): Promise<URL>;
-
-  // trigger a new logout
-  signOut(): Promise<URL>;
-}
-
-// A service that can resolve an authentication request according to the OAuth Auth Code grant types
-export interface AuthenticationResolver {
-  // Given an auth code, get the tokens from the auth server and store them. works in PKCE and non-PKCE environments
-  // Note, if we choose later to implement other grants, this method would move into a subinterface specifically
-  // for the authorization code grant type.
-  // The return type is just for convenience and can be ignored, as the same data would be provided by getSessionData
-  tokenExchange(code: string, state: string): Promise<OIDCTokenResponseBody>;
-
-  // If the tokens have already been retrieved, return them
-  getSessionData(): Promise<SessionData | null>;
-
-  // If an existing session is found, validate it and return the session data
-  validateExistingSession(): Promise<SessionData>;
-}
-
-export interface AuthenticationRefresher {
-  refreshTokens: () => Promise<OIDCTokenResponseBody>;
-}
-
-export class PopupError extends Error {
-  constructor(message: string) {
-    super(message);
-    Object.setPrototypeOf(this, PopupError.prototype);
-  }
-}