codeforlife 2.6.17 → 2.7.1

package/.github/workflows/main.yml

@@ -7,13 +7,20 @@ on:
       - '**/*.code-*'
       - '.vscode/**'
       - '.devcontainer.json'
+  pull_request:
+  issues:
+  issue_comment:
   workflow_dispatch:
 
 jobs:
+  issue:
+    uses: ocadotechnology/codeforlife-workspace/.github/workflows/issues.yaml@main
+    secrets: inherit
+
   contributor:
     uses: ocadotechnology/codeforlife-contributor-backend/.github/workflows/check-pr-authors-signed-latest-agreement.yaml@main
 
-  test:
+  test: 
     uses: ocadotechnology/codeforlife-workspace/.github/workflows/test-javascript-code.yaml@main
     secrets: inherit
     with:
@@ -44,3 +51,8 @@ jobs:
     needs: [release]
     with:
       node-version: 22
+
+  submodule:
+    uses: ocadotechnology/codeforlife-workspace/.github/workflows/gitmodules.yaml@main
+    secrets: inherit
+    needs: [release]

package/.prettierignore

@@ -1,5 +1 @@
-**/*.json
-**/*.yaml
-**/*.yml
-**/*.code-*
-**/*.md
+src/scripts/*

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.7.1](https://github.com/ocadotechnology/codeforlife-package-javascript/compare/v2.7.0...v2.7.1) (2025-08-15)
+
+
+### Bug Fixes
+
+* optionally set useSessionMetadata ([22c5253](https://github.com/ocadotechnology/codeforlife-package-javascript/commit/22c525341badef6f13fe9adc1489d033792d2340))
+
+# [2.7.0](https://github.com/ocadotechnology/codeforlife-package-javascript/compare/v2.6.17...v2.7.0) (2025-08-15)
+
+
+### Features
+
+* oauth2 support ([#87](https://github.com/ocadotechnology/codeforlife-package-javascript/issues/87)) ([6332e5c](https://github.com/ocadotechnology/codeforlife-package-javascript/commit/6332e5c9583a4936066e4144a2436af59fdaa46c))
+
 ## [2.6.17](https://github.com/ocadotechnology/codeforlife-package-javascript/compare/v2.6.16...v2.6.17) (2025-06-25)
 
 

package/package.json

@@ -2,10 +2,10 @@
   "name": "codeforlife",
   "description": "Common frontend code",
   "private": false,
-  "version": "2.6.17",
+  "version": "2.7.1",
   "type": "module",
   "scripts": {
-    "cli": "VITE_CONFIG=./vite.config.ts ../scripts/frontend/cli $@"
+    "cli": "VITE_CONFIG=./vite.config.ts ../scripts/frontend $@"
   },
   "repository": {
     "type": "git",

package/src/api/endpoints/session.ts

@@ -2,6 +2,12 @@ import { type EndpointBuilder, type Api } from "@reduxjs/toolkit/query/react"
 
 import { login, logout } from "../../slices/session"
 
+export type ExchangeOAuth2CodeArg = {
+  code: string
+  code_verifier: string
+  redirect_uri: string
+}
+
 export function buildLoginEndpoint<ResultType, QueryArg>(
   build: EndpointBuilder<any, any, any>,
   url: string = "session/login/",

package/src/hooks/auth.tsx

@@ -1,12 +1,29 @@
+import * as yup from "yup"
 import Cookies from "js-cookie"
-import { useEffect, type ReactNode } from "react"
-import { createSearchParams, useLocation, useNavigate } from "react-router-dom"
+import { useEffect, useState, useCallback, type ReactNode } from "react"
+import { createSearchParams } from "react-router-dom"
+import type { TypedUseMutation } from "@reduxjs/toolkit/query/react"
 import { useSelector } from "react-redux"
 
 import { type AuthFactor, type User } from "../api"
+import { generateSecureRandomString } from "../utils/general"
+import {
+  makeOAuth2StorageKey,
+  generateOAuth2CodeChallenge,
+  type OAuth2CodeChallengeLengths,
+  type OAuth2CodeChallenge,
+  type OAuth2RequestCodeUrlSearchParams,
+  type OAuth2ReceiveCodeUrlSearchParams,
+} from "../utils/auth"
+import { type ExchangeOAuth2CodeArg } from "../api/endpoints/session"
+import { useSearchParams, useLocation, useNavigate } from "./router"
 import { SESSION_METADATA_COOKIE_NAME } from "../settings"
 import { selectIsLoggedIn } from "../slices/session"
 
+// -----------------------------------------------------------------------------
+// Session
+// -----------------------------------------------------------------------------
+
 export interface SessionMetadata {
   user_id: User["id"]
   user_type: "teacher" | "student" | "indy"
@@ -85,3 +102,283 @@ export function useSession<
 
   return children
 }
+
+// -----------------------------------------------------------------------------
+// OAuth2
+// -----------------------------------------------------------------------------
+
+export function useOAuth2State(
+  provider: string,
+  length: number = 32,
+  storageKey: string = "state",
+): [string | undefined, () => void] {
+  const oAuth2StorageKey = makeOAuth2StorageKey(provider, storageKey)
+  const storageValue = sessionStorage.getItem(oAuth2StorageKey)
+
+  const [_state, _setState] = useState<string>()
+
+  useEffect(() => {
+    let state: string
+    if (storageValue && storageValue.length === length) {
+      state = storageValue
+    } else {
+      state = generateSecureRandomString(length)
+      sessionStorage.setItem(oAuth2StorageKey, state)
+    }
+
+    _setState(state)
+  }, [oAuth2StorageKey, storageValue, length])
+
+  const resetState = useCallback(() => {
+    sessionStorage.removeItem(oAuth2StorageKey)
+    _setState(undefined)
+  }, [oAuth2StorageKey])
+
+  return [_state, resetState]
+}
+
+export function useOAuth2CodeChallenge(
+  provider: string,
+  length: OAuth2CodeChallengeLengths = 128,
+  storageKey: string = "codeChallenge",
+): [OAuth2CodeChallenge | undefined, () => void] {
+  const oAuth2StorageKey = makeOAuth2StorageKey(provider, storageKey)
+  const storageValue = sessionStorage.getItem(oAuth2StorageKey)
+
+  const [_codeChallenge, _setCodeChallenge] = useState<OAuth2CodeChallenge>()
+
+  useEffect(() => {
+    let codeChallenge: OAuth2CodeChallenge | undefined
+    if (storageValue) {
+      const storageJsonValue: unknown = JSON.parse(storageValue)
+      if (
+        typeof storageJsonValue === "object" &&
+        storageJsonValue &&
+        "verifier" in storageJsonValue &&
+        typeof storageJsonValue.verifier == "string" &&
+        storageJsonValue.verifier.length === length &&
+        "challenge" in storageJsonValue &&
+        typeof storageJsonValue.challenge === "string" &&
+        "method" in storageJsonValue &&
+        storageJsonValue.method === "S256"
+      ) {
+        codeChallenge = {
+          verifier: storageJsonValue.verifier,
+          challenge: storageJsonValue.challenge,
+          method: storageJsonValue.method,
+        }
+      }
+    }
+
+    if (codeChallenge) _setCodeChallenge(codeChallenge)
+    else {
+      generateOAuth2CodeChallenge(length)
+        .then(codeChallenge => {
+          sessionStorage.setItem(
+            oAuth2StorageKey,
+            JSON.stringify(codeChallenge),
+          )
+
+          _setCodeChallenge(codeChallenge)
+        })
+        .catch(error => {
+          if (error) console.error(error)
+        })
+    }
+  }, [oAuth2StorageKey, storageValue, length])
+
+  const resetCodeChallenge = useCallback(() => {
+    sessionStorage.removeItem(oAuth2StorageKey)
+    _setCodeChallenge(undefined)
+  }, [oAuth2StorageKey])
+
+  return [_codeChallenge, resetCodeChallenge]
+}
+
+interface BaseUseOAuth2KwArgs<SessionMetadata> {
+  provider: string
+  authUri: string
+  clientId: string
+  redirectUri: string
+  scope: string
+  responseType?: "code"
+  accessType?: "offline"
+  prompt?: string
+  useLoginMutation: TypedUseMutation<
+    SessionMetadata,
+    ExchangeOAuth2CodeArg,
+    any
+  >
+  onCreateSession: (result: SessionMetadata) => void
+  onRetrieveSession: (metadata: SessionMetadata) => void
+}
+
+interface UseOAuth2KwArgs<SessionMetadata>
+  extends BaseUseOAuth2KwArgs<SessionMetadata> {
+  useSessionMetadata: () => SessionMetadata | undefined
+}
+
+export type OAuth2 = [string, OAuth2RequestCodeUrlSearchParams] | []
+
+// https://datatracker.ietf.org/doc/html/rfc7636
+function _useOAuth2<SessionMetadata>({
+  provider,
+  authUri,
+  clientId,
+  redirectUri,
+  scope,
+  responseType = "code",
+  accessType = "offline",
+  prompt,
+  useSessionMetadata,
+  useLoginMutation,
+  onCreateSession,
+  onRetrieveSession,
+}: UseOAuth2KwArgs<SessionMetadata>): OAuth2 {
+  const [state, resetState] = useOAuth2State(provider)
+  const [
+    {
+      verifier: codeVerifier,
+      challenge: codeChallenge,
+      method: codeChallengeMethod,
+    } = {},
+    resetCodeChallenge,
+  ] = useOAuth2CodeChallenge(provider)
+  const [
+    login,
+    {
+      originalArgs: loginArgs = {} as ExchangeOAuth2CodeArg,
+      isLoading: loginIsLoading,
+      isError: loginIsError,
+    },
+  ] = useLoginMutation()
+  const sessionMetadata = useSessionMetadata()
+  const navigate = useNavigate()
+  const searchParams =
+    useSearchParams({ code: yup.string(), state: yup.string() }) || {}
+  const location = useLocation<OAuth2ReceiveCodeUrlSearchParams>()
+
+  const locationState = location.state || {}
+
+  useEffect(() => {
+    // If the the auth provider has redirected back to our site with the
+    // expected search params, we redirect to the current page to remove them.
+    if (searchParams.code && searchParams.state) {
+      navigate<OAuth2ReceiveCodeUrlSearchParams>(".", {
+        // Removes the URL containing the search params from the history stack.
+        replace: true,
+        // Ensure we don't break the auth flow by navigating to another page.
+        next: false,
+        // Store the search params in the page's state instead.
+        state: { code: searchParams.code, state: searchParams.state },
+      })
+    }
+  }, [searchParams.code, searchParams.state, navigate])
+
+  useEffect(() => {
+    // If we're already logged in, no need to log in again.
+    if (sessionMetadata) onRetrieveSession(sessionMetadata)
+    else if (
+      // If the state and code verifier have been generated...
+      state &&
+      codeVerifier &&
+      // ...and the page's state contains a code...
+      locationState.code &&
+      // ...and the page's state contains the stored state...
+      locationState.state === state &&
+      // ...and the login endpoint was not called with the current values or has
+      // not returned an error...
+      (loginArgs.code !== locationState.code ||
+        loginArgs.code_verifier !== codeVerifier ||
+        loginArgs.redirect_uri !== redirectUri ||
+        !loginIsError) &&
+      // ...and the login endpoint is not currently being called...
+      !loginIsLoading
+    ) {
+      // ...call the login endpoint.
+      login({
+        code: locationState.code,
+        code_verifier: codeVerifier,
+        redirect_uri: redirectUri,
+      })
+        .unwrap()
+        .then(onCreateSession)
+        .catch(() => {
+          navigate(".", {
+            replace: true,
+            state: {
+              notifications: [
+                {
+                  props: {
+                    error: true,
+                    children: "Failed to login. Please try again.",
+                  },
+                },
+              ],
+            },
+          })
+        })
+        .finally(() => {
+          resetState()
+          resetCodeChallenge()
+        })
+    }
+  }, [
+    navigate,
+    redirectUri,
+    // State
+    state,
+    locationState.state,
+    resetState,
+    // Code
+    codeVerifier,
+    locationState.code,
+    resetCodeChallenge,
+    // Login
+    login,
+    loginIsLoading,
+    loginIsError,
+    loginArgs.code,
+    loginArgs.code_verifier,
+    loginArgs.redirect_uri,
+    // Session
+    sessionMetadata,
+    onCreateSession,
+    onRetrieveSession,
+  ])
+
+  if (state && codeChallenge && codeChallengeMethod) {
+    const urlSearchParams: OAuth2RequestCodeUrlSearchParams = {
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      scope,
+      response_type: responseType,
+      access_type: accessType,
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: codeChallengeMethod,
+    }
+
+    if (prompt) urlSearchParams["prompt"] = prompt
+
+    return [
+      authUri + "?" + new URLSearchParams(urlSearchParams).toString(),
+      urlSearchParams,
+    ]
+  }
+
+  return []
+}
+
+export const useOAuth2: {
+  <SessionMetadata>(kwargs: UseOAuth2KwArgs<SessionMetadata>): OAuth2
+  (kwargs: BaseUseOAuth2KwArgs<SessionMetadata>): OAuth2
+} = <_SessionMetadata,>(
+  kwargs:
+    | UseOAuth2KwArgs<_SessionMetadata>
+    | BaseUseOAuth2KwArgs<SessionMetadata>,
+): OAuth2 => {
+  return "useSessionMetadata" in kwargs
+    ? _useOAuth2(kwargs)
+    : _useOAuth2({ ...kwargs, useSessionMetadata })
+}

package/src/utils/auth.ts

@@ -5,6 +5,7 @@ import {
   SESSION_METADATA_COOKIE_NAME,
   CSRF_COOKIE_NAME,
 } from "../settings"
+import { generateSecureRandomString } from "./general"
 
 export function logout() {
   Cookies.remove(SESSION_COOKIE_NAME)
@@ -15,3 +16,63 @@ export function logout() {
 export function getCsrfCookie() {
   return Cookies.get(CSRF_COOKIE_NAME)
 }
+
+export function makeOAuth2StorageKey(provider: string, key: string) {
+  return `oauth2.${provider}.${key}`
+}
+
+export const OAUTH2_CODE_CHALLENGE_METHODS = ["S256"] as const
+
+export type OAuth2CodeChallengeMethods =
+  (typeof OAUTH2_CODE_CHALLENGE_METHODS)[number]
+
+export const OAUTH2_CODE_CHALLENGE_LENGTHS = [
+  43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61,
+  62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80,
+  81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99,
+  100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114,
+  115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128,
+] as const
+
+export type OAuth2CodeChallengeLengths =
+  (typeof OAUTH2_CODE_CHALLENGE_LENGTHS)[number]
+
+export type OAuth2RequestCodeUrlSearchParams = {
+  client_id: string
+  redirect_uri: string
+  scope: string
+  response_type: string
+  access_type: string
+  prompt?: string
+  state: string
+  code_challenge: string
+  code_challenge_method: string
+}
+
+export type OAuth2ReceiveCodeUrlSearchParams = {
+  code: string
+  state: string
+}
+
+export type OAuth2CodeChallenge = {
+  verifier: string
+  challenge: string
+  method: OAuth2CodeChallengeMethods
+}
+
+export async function generateOAuth2CodeChallenge(
+  length: OAuth2CodeChallengeLengths,
+): Promise<OAuth2CodeChallenge> {
+  const verifier = generateSecureRandomString(length)
+  const data = new TextEncoder().encode(verifier)
+  const digest = await window.crypto.subtle.digest("SHA-256", data)
+
+  return {
+    verifier,
+    challenge: btoa(String.fromCharCode(...new Uint8Array(digest)))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, ""),
+    method: "S256",
+  }
+}

package/src/utils/general.ts

@@ -1025,3 +1025,19 @@ export function excludeKeyPaths(
 
   return exclude.length ? _excludeKeyPaths(obj, []) : obj
 }
+
+export function generateSecureRandomString(
+  length: number,
+  charSet: string = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
+) {
+  // Create an array of 32-bit unsigned integers
+  const randomValues = window.crypto.getRandomValues(new Uint8Array(length))
+
+  // Map the random values to characters from our string
+  let result = ""
+  for (let i = 0; i < length; i++) {
+    result += charSet.charAt(randomValues[i] % charSet.length)
+  }
+
+  return result
+}

package/.prettierrc.json

@@ -1,4 +0,0 @@
-{
-  "semi": false,
-  "arrowParens": "avoid"
-}

package/.vscode/launch.json

@@ -1,22 +0,0 @@
-{
-  "configurations": [
-    {
-      "args": [
-        "run",
-        "${relativeFile}"
-      ],
-      "autoAttachChildProcesses": true,
-      "console": "integratedTerminal",
-      "name": "Vitest: Current File",
-      "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
-      "request": "launch",
-      "skipFiles": [
-        "<node_internals>/**",
-        "**/node_modules/**"
-      ],
-      "smartStep": true,
-      "type": "node"
-    }
-  ],
-  "version": "0.2.0"
-}

package/.vscode/settings.json

@@ -1,30 +0,0 @@
-{
-  "[md]": {
-    "editor.tabSize": 4
-  },
-  "cSpell.words": [
-    "codeforlife",
-    "klass",
-    "ocado",
-    "kurono",
-    "pipenv"
-  ],
-  "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": "always",
-    "source.organizeImports": "never"
-  },
-  "editor.defaultFormatter": "esbenp.prettier-vscode",
-  "editor.formatOnSave": true,
-  "editor.rulers": [
-    80
-  ],
-  "editor.tabSize": 2,
-  "files.exclude": {
-    "**/*.tsbuildinfo": true
-  },
-  "javascript.format.semicolons": "remove",
-  "javascript.preferences.quoteStyle": "double",
-  "prettier.configPath": ".prettierrc.json",
-  "typescript.format.semicolons": "remove",
-  "typescript.preferences.quoteStyle": "double"
-}