@civic/auth 0.0.1-beta.3 → 0.0.1-beta.31

package/src/shared/components/LoadingIcon.tsx

@@ -0,0 +1,53 @@
+import React from "react";
+
+const LoadingIcon = () => (
+  <div role="status">
+    <style>
+      {`
+        @keyframes spin {
+          0% { transform: rotate(0deg); }
+          100% { transform: rotate(360deg); }
+        }
+      `}
+    </style>
+    <svg
+      aria-hidden="true"
+      style={{
+        display: "inline",
+        height: "2rem",
+        width: "2rem",
+        animation: "spin 1s linear infinite",
+        fill: "#4b5563",
+        color: "#e5e7eb",
+      }}
+      viewBox="0 0 100 101"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        d="M100 50.5908C100 78.2051 77.6142 100.591 50 100.591C22.3858 100.591 0 78.2051 0 50.5908C0 22.9766 22.3858 0.59082 50 0.59082C77.6142 0.59082 100 22.9766 100 50.5908ZM9.08144 50.5908C9.08144 73.1895 27.4013 91.5094 50 91.5094C72.5987 91.5094 90.9186 73.1895 90.9186 50.5908C90.9186 27.9921 72.5987 9.67226 50 9.67226C27.4013 9.67226 9.08144 27.9921 9.08144 50.5908Z"
+        fill="currentColor"
+      />
+      <path
+        d="M93.9676 39.0409C96.393 38.4038 97.8624 35.9116 97.0079 33.5539C95.2932 28.8227 92.871 24.3692 89.8167 20.348C85.8452 15.1192 80.8826 10.7238 75.2124 7.41289C69.5422 4.10194 63.2754 1.94025 56.7698 1.05124C51.7666 0.367541 46.6976 0.446843 41.7345 1.27873C39.2613 1.69328 37.813 4.19778 38.4501 6.62326C39.0873 9.04874 41.5694 10.4717 44.0505 10.1071C47.8511 9.54855 51.7191 9.52689 55.5402 10.0491C60.8642 10.7766 65.9928 12.5457 70.6331 15.2552C75.2735 17.9648 79.3347 21.5619 82.5849 25.841C84.9175 28.9121 86.7997 32.2913 88.1811 35.8758C89.083 38.2158 91.5421 39.6781 93.9676 39.0409Z"
+        fill="currentFill"
+      />
+    </svg>
+    <span
+      style={{
+        position: "absolute",
+        width: "1px",
+        height: "1px",
+        padding: 0,
+        margin: "-1px",
+        overflow: "hidden",
+        clip: "rect(0, 0, 0, 0)",
+        border: 0,
+      }}
+    >
+      Loading...
+    </span>
+  </div>
+);
+
+export { LoadingIcon };

package/src/shared/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useToken } from "@/shared/hooks/useToken.js";
+export { useAuth } from "@/shared/hooks/useAuth.js";
+export { useConfig } from "@/shared/hooks/useConfig.js";
+export { useIframe } from "@/shared/hooks/useIframe.js";

package/src/shared/hooks/useAuth.ts

@@ -0,0 +1,15 @@
+"use client";
+import { useContext } from "react";
+import { AuthContext } from "@/shared/providers/AuthContext.js";
+
+const useAuth = () => {
+  const context = useContext(AuthContext);
+
+  if (!context) {
+    throw new Error("useAuth must be used within an AuthProvider");
+  }
+
+  return context;
+};
+
+export { useAuth };

package/src/shared/hooks/useConfig.ts

@@ -0,0 +1,14 @@
+"use client";
+import { useContext } from "react";
+import { ConfigContext } from "@/shared/providers/ConfigProvider.js";
+
+// TokenProvider will use this internal context to access Config
+const useConfig = () => {
+  const context = useContext(ConfigContext);
+  if (!context) {
+    throw new Error("useConfig must be used within an ConfigProvider");
+  }
+  return context;
+};
+
+export { useConfig };

package/src/shared/hooks/useIframe.ts

@@ -0,0 +1,14 @@
+"use client";
+import { useContext } from "react";
+import { IframeContext } from "@/shared/providers/IframeProvider.js";
+
+// TokenProvider will use this internal context to access Iframe
+const useIframe = () => {
+  const context = useContext(IframeContext);
+  if (!context) {
+    throw new Error("useIframe must be used within an IframeProvider");
+  }
+  return context;
+};
+
+export { useIframe };

package/src/shared/hooks/useSession.ts

@@ -0,0 +1,14 @@
+"use client";
+import { useContext } from "react";
+import { SessionContext } from "@/shared/providers/SessionProvider.js";
+
+// TokenProvider will use this internal context to access session
+const useSession = () => {
+  const context = useContext(SessionContext);
+  if (!context) {
+    throw new Error("useSession must be used within an SessionProvider");
+  }
+  return context;
+};
+
+export { useSession };

package/src/shared/hooks/useToken.ts

@@ -0,0 +1,15 @@
+"use client";
+import { useContext } from "react";
+import { TokenContext } from "@/shared/providers/TokenProvider.js";
+
+const useToken = () => {
+  const context = useContext(TokenContext);
+
+  if (!context) {
+    throw new Error("useToken must be used within a TokenProvider");
+  }
+
+  return context;
+};
+
+export { useToken };

package/src/shared/lib/GenericAuthenticationRefresher.ts

@@ -0,0 +1,70 @@
+import type { AuthenticationRefresher } from "@/services/types.js";
+import type { AuthStorage, Endpoints, OIDCTokenResponseBody } from "@/types.js";
+import {
+  getEndpointsWithOverrides,
+  retrieveTokens,
+  storeTokens,
+} from "@/shared/lib/util.js";
+import type { AuthConfig } from "@/server/config.js";
+import { OAuth2Client } from "oslo/oauth2";
+
+export class GenericAuthenticationRefresher implements AuthenticationRefresher {
+  private oauth2client: OAuth2Client | undefined;
+  private endpoints: Endpoints | undefined;
+
+  private constructor(
+    private authConfig: AuthConfig,
+    private storage: AuthStorage,
+    private endpointOverrides?: Partial<Endpoints>,
+  ) {}
+
+  async init(): Promise<this> {
+    // resolve oauth config
+    this.endpoints = await getEndpointsWithOverrides(
+      this.authConfig.oauthServer,
+      this.endpointOverrides,
+    );
+    this.oauth2client = new OAuth2Client(
+      this.authConfig.clientId,
+      this.endpoints.auth,
+      this.endpoints.token,
+      {
+        redirectURI: this.authConfig.redirectUrl,
+      },
+    );
+
+    return this;
+  }
+
+  static async build(
+    authConfig: AuthConfig,
+    storage: AuthStorage,
+    endpointOverrides?: Partial<Endpoints>,
+  ): Promise<GenericAuthenticationRefresher> {
+    const refresher = new GenericAuthenticationRefresher(
+      authConfig,
+      storage,
+      endpointOverrides,
+    );
+    await refresher.init();
+
+    return refresher;
+  }
+
+  async refreshTokens() {
+    if (!this.oauth2client) await this.init();
+
+    const tokens = await retrieveTokens(this.storage);
+    if (!tokens?.refresh_token) throw new Error("No refresh token available");
+
+    const oauth2Client = this.oauth2client!;
+    const refreshedTokens =
+      await oauth2Client.refreshAccessToken<OIDCTokenResponseBody>(
+        tokens.refresh_token,
+      );
+
+    await storeTokens(this.storage, refreshedTokens);
+
+    return tokens;
+  }
+}

package/src/shared/lib/UserSession.ts

@@ -0,0 +1,25 @@
+import type { AuthStorage, ForwardedTokensJWT, User } from "@/types.js";
+import { UserStorage } from "@/shared/lib/types.js";
+import { convertForwardedTokenFormat } from "@/lib/jwt.js";
+
+export interface UserSession {
+  get(): Promise<User | null>;
+  set(user: User): Promise<void>;
+}
+
+export class GenericUserSession implements UserSession {
+  constructor(readonly storage: AuthStorage) {}
+
+  async get(): Promise<User | null> {
+    const user = await this.storage.get(UserStorage.USER);
+    return user ? JSON.parse(user) : null;
+  }
+
+  async set(user: User | null): Promise<void> {
+    const forwardedTokens = user?.forwardedTokens
+      ? convertForwardedTokenFormat(user?.forwardedTokens as ForwardedTokensJWT)
+      : null;
+    const value = user ? JSON.stringify({ ...user, forwardedTokens }) : "";
+    await this.storage.set(UserStorage.USER, value);
+  }
+}

package/src/shared/lib/session.ts

@@ -0,0 +1,11 @@
+import { retrieveTokens } from "@/shared/lib/util.js";
+import { parseJWT } from "oslo/jwt";
+import type { AuthStorage, User } from "@/types.js";
+
+export async function getUser(storage: AuthStorage): Promise<User | null> {
+  const tokens = await retrieveTokens(storage);
+  if (!tokens) return null;
+
+  // Assumes all information is in the ID token
+  return (parseJWT(tokens.id_token)?.payload as User) ?? null;
+}

package/src/shared/lib/storage.ts

@@ -0,0 +1,40 @@
+import type { AuthStorage, SessionData, UnknownObject, User } from "@/types.js";
+
+type SameSiteOption = "strict" | "lax" | "none";
+
+export interface SessionStorage {
+  get(): SessionData;
+  getUser(): User<UnknownObject> | null;
+  set(data: Partial<SessionData>): void;
+  setUser(data: User<UnknownObject> | null): void;
+  clear(): void;
+}
+
+export type CookieStorageSettings = {
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite: SameSiteOption;
+  expires: Date;
+  path: string;
+};
+
+export const DEFAULT_COOKIE_DURATION = 60 * 15; // 15 minutes
+
+export abstract class CookieStorage implements AuthStorage {
+  protected settings: CookieStorageSettings;
+  protected constructor(settings: Partial<CookieStorageSettings> = {}) {
+    this.settings = {
+      httpOnly: settings.httpOnly ?? true,
+      secure: settings.secure ?? true,
+      // the callback request comes the auth server
+      // 'lax' ensures the code_verifier cookie is sent with the request
+      sameSite: settings.sameSite ?? "lax",
+      expires:
+        settings.expires ??
+        new Date(Date.now() + 1000 * DEFAULT_COOKIE_DURATION),
+      path: settings.path ?? "/",
+    };
+  }
+  abstract get(key: string): Promise<string | null>;
+  abstract set(key: string, value: string): Promise<void>;
+}

package/src/shared/lib/types.ts

@@ -0,0 +1,26 @@
+export enum OAuthTokens {
+  ID_TOKEN = "id_token",
+  ACCESS_TOKEN = "access_token",
+  REFRESH_TOKEN = "refresh_token",
+}
+
+export enum CodeVerifier {
+  COOKIE_NAME = "code_verifier",
+  APP_URL = "app_url",
+}
+export enum UserStorage {
+  USER = "user",
+}
+export interface CookieConfig {
+  secure?: boolean;
+  sameSite?: "strict" | "lax" | "none";
+  domain?: string;
+  path?: string;
+  maxAge?: number;
+  httpOnly?: boolean;
+}
+
+export type TokensCookieConfig = Record<
+  OAuthTokens | CodeVerifier,
+  CookieConfig
+>;

package/src/shared/lib/util.ts

@@ -0,0 +1,217 @@
+// Utility functions shared by auth server and client integrations
+// Typically these functions should be used inside AuthenticationInitiator and AuthenticationResolver implementations
+import type {
+  AuthStorage,
+  Endpoints,
+  JWTPayload,
+  OIDCTokenResponseBody,
+  ParsedTokens,
+} from "@/types.js";
+import { CodeVerifier, OAuthTokens } from "./types.js";
+import { OAuth2Client } from "oslo/oauth2";
+import { getIssuerVariations, getOauthEndpoints } from "@/lib/oauth.js";
+import * as jose from "jose";
+import { withoutUndefined } from "@/utils.js";
+import type { PKCEConsumer, PKCEProducer } from "@/services/types.js";
+import { GenericUserSession } from "@/shared/lib/UserSession.js";
+
+/**
+ * Given a PKCE code verifier, derive the code challenge using SHA
+ */
+export async function deriveCodeChallenge(
+  codeVerifier: string,
+  method: "Plain" | "S256" = "S256",
+): Promise<string> {
+  if (method === "Plain") {
+    console.warn("Using insecure plain code challenge method");
+    return codeVerifier;
+  }
+
+  const encoder = new TextEncoder();
+  const data = encoder.encode(codeVerifier);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return btoa(String.fromCharCode(...new Uint8Array(digest)))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+export async function getEndpointsWithOverrides(
+  oauthServer: string,
+  endpointOverrides: Partial<Endpoints> = {},
+): Promise<Endpoints> {
+  const endpoints = await getOauthEndpoints(oauthServer);
+  return {
+    ...endpoints,
+    ...endpointOverrides,
+  };
+}
+
+export async function generateOauthLoginUrl(config: {
+  clientId: string;
+  scopes: string[];
+  state: string;
+  redirectUrl: string;
+  oauthServer: string;
+  nonce?: string;
+  endpointOverrides?: Partial<Endpoints>;
+  // used to get the PKCE challenge
+  pkceConsumer: PKCEConsumer;
+}): Promise<URL> {
+  const endpoints = await getEndpointsWithOverrides(
+    config.oauthServer,
+    config.endpointOverrides,
+  );
+  const oauth2Client = buildOauth2Client(
+    config.clientId,
+    config.redirectUrl,
+    endpoints,
+  );
+  const challenge = await config.pkceConsumer.getCodeChallenge();
+  const oAuthUrl = await oauth2Client.createAuthorizationURL({
+    state: config.state,
+    scopes: config.scopes,
+  });
+  // The OAuth2 client supports PKCE, but does not allow passing in a code challenge from some other source
+  // It only allows passing in a code verifier which it then hashes itself.
+  oAuthUrl.searchParams.append("code_challenge", challenge);
+  oAuthUrl.searchParams.append("code_challenge_method", "S256");
+  if (config.nonce) {
+    // nonce isn't supported by oslo, so we add it manually
+    oAuthUrl.searchParams.append("nonce", config.nonce);
+  }
+  // Required by the auth server for offline_access scope
+  oAuthUrl.searchParams.append("prompt", "consent");
+
+  return oAuthUrl;
+}
+
+export async function generateOauthLogoutUrl(config: {
+  clientId: string;
+  scopes: string[];
+  oauthServer: string;
+  endpointOverrides?: Partial<Endpoints>;
+  // used to get the PKCE challenge
+  pkceConsumer: PKCEConsumer;
+}): Promise<URL> {
+  // TODO TECH-676: Implement logout
+  console.log("generateOauthLogoutUrl not implemented", config);
+  return new URL("http://localhost");
+}
+
+export function buildOauth2Client(
+  clientId: string,
+  redirectUri: string,
+  endpoints: Endpoints,
+): OAuth2Client {
+  return new OAuth2Client(clientId, endpoints.auth, endpoints.token, {
+    redirectURI: redirectUri,
+  });
+}
+
+export async function exchangeTokens(
+  code: string,
+  state: string,
+  pkceProducer: PKCEProducer,
+  oauth2Client: OAuth2Client,
+  oauthServer: string,
+  endpoints: Endpoints,
+) {
+  const codeVerifier = await pkceProducer.getCodeVerifier();
+  if (!codeVerifier) throw new Error("Code verifier not found in state");
+
+  const tokens =
+    await oauth2Client.validateAuthorizationCode<OIDCTokenResponseBody>(code, {
+      codeVerifier,
+    });
+
+  // Validate relevant tokens
+  try {
+    await validateOauth2Tokens(tokens, endpoints, oauth2Client, oauthServer);
+  } catch (error) {
+    console.error("tokenExchange error", { error, tokens });
+    throw new Error(
+      `OIDC tokens validation failed: ${(error as Error).message}`,
+    );
+  }
+
+  return tokens;
+}
+
+export async function storeTokens(
+  storage: AuthStorage,
+  tokens: OIDCTokenResponseBody,
+) {
+  // store tokens in storage ( TODO we should probably store them against the state to allow multiple logins )
+  await storage.set(OAuthTokens.ID_TOKEN, tokens.id_token);
+  await storage.set(OAuthTokens.ACCESS_TOKEN, tokens.access_token);
+  if (tokens.refresh_token) {
+    await storage.set(OAuthTokens.REFRESH_TOKEN, tokens.refresh_token);
+  }
+}
+
+export async function clearTokens(storage: AuthStorage) {
+  const clearOAuthPromises = Object.values(OAuthTokens).map((cookie) => {
+    storage.set(cookie, "");
+  });
+  const clearCodeVerifierPromises = Object.values(CodeVerifier.COOKIE_NAME).map(
+    (cookie) => {
+      storage.set(cookie, "");
+    },
+  );
+  await Promise.all([...clearOAuthPromises, ...clearCodeVerifierPromises]);
+}
+export async function clearUser(storage: AuthStorage) {
+  const userSession = new GenericUserSession(storage);
+  await userSession.set(null);
+}
+
+export async function retrieveTokens(
+  storage: AuthStorage,
+): Promise<OIDCTokenResponseBody | null> {
+  const idToken = await storage.get(OAuthTokens.ID_TOKEN);
+  const accessToken = await storage.get(OAuthTokens.ACCESS_TOKEN);
+  const refreshToken = await storage.get(OAuthTokens.REFRESH_TOKEN);
+
+  if (!idToken || !accessToken) return null;
+
+  return {
+    id_token: idToken,
+    access_token: accessToken,
+    refresh_token: refreshToken ?? undefined,
+  };
+}
+
+export async function validateOauth2Tokens(
+  tokens: OIDCTokenResponseBody,
+  endpoints: Endpoints,
+  oauth2Client: OAuth2Client,
+  issuer: string,
+): Promise<ParsedTokens> {
+  const JWKS = jose.createRemoteJWKSet(new URL(endpoints.jwks));
+
+  // validate the ID token
+  const idTokenResponse = await jose.jwtVerify<JWTPayload>(
+    tokens.id_token,
+    JWKS,
+    {
+      issuer: getIssuerVariations(issuer),
+      audience: oauth2Client.clientId,
+    },
+  );
+
+  // validate the access token
+  const accessTokenResponse = await jose.jwtVerify<JWTPayload>(
+    tokens.access_token,
+    JWKS,
+    {
+      issuer: getIssuerVariations(issuer),
+    },
+  );
+
+  return withoutUndefined({
+    id_token: idTokenResponse.payload,
+    access_token: accessTokenResponse.payload,
+    refresh_token: tokens.refresh_token,
+  });
+}

package/src/shared/providers/AuthContext.tsx

@@ -0,0 +1,11 @@
+import { createContext } from "react";
+import type { DisplayMode } from "@/types.js";
+
+export type AuthContextType = {
+  signIn: (displayMode?: DisplayMode) => Promise<void>;
+  isAuthenticated: boolean;
+  isLoading: boolean;
+  error: Error | null;
+  signOut: () => Promise<void>;
+};
+export const AuthContext = createContext<AuthContextType | null>(null);