@nside/wefa 0.3.0 → 0.4.0

package/src/stores/backend/constants.ts

@@ -0,0 +1,22 @@
+/**
+ * A constant variable used as the key for storing and retrieving the authentication token
+ * in the browser's localStorage. This key is utilized to maintain user session or
+ * authentication state across browser sessions by securely saving the token locally.
+ */
+export const localStorageKey = 'authenticationToken'
+
+/**
+ * Constants used as keys for storing and retrieving JWT authentication tokens
+ * in the browser's localStorage. These keys are utilized to maintain user session or
+ * authentication state across browser sessions by securely saving the tokens locally.
+ */
+export const jwtAccessTokenKey = 'jwtAccessToken'
+export const jwtRefreshTokenKey = 'jwtRefreshToken'
+
+export const tokenLoginEndpoint = '/api/token-auth/'
+export const jwtLoginEndpoint = '/api/token/'
+export const jwtRefreshEndpoint = '/api/token/refresh/'
+
+export const oauthLoginEndpoint = '/proxy/api/auth/login'
+export const oauthLogoutEndpoint = '/proxy/api/auth/logout'
+export const oauthSessionEndpoint = '/proxy/api/auth/session'

package/src/stores/backend/schemes/jwt.ts

@@ -0,0 +1,208 @@
+import { ref, watch, type Ref } from 'vue'
+import type { AxiosError, AxiosResponse, InternalAxiosRequestConfig } from 'axios'
+import axiosInstance from '@/network/axios.ts'
+import { createCommonAuthFunctions } from '../common.ts'
+import {
+  jwtAccessTokenKey,
+  jwtLoginEndpoint,
+  jwtRefreshEndpoint,
+  jwtRefreshTokenKey,
+} from '../constants.ts'
+import type { BackendStore, BackendStoreOptions, Credentials } from '../types.ts'
+
+/**
+ * Configures and sets up a JWT-based authentication backend store for managing API authentication.
+ *
+ * The method initializes authentication states, such as access and refresh tokens, login/logout handlers, and
+ * authentication interceptors on the axios instance for requests and responses.
+ * It also provides helper functions for handling authentication processes, like login, logout,
+ * and post-login/logout callbacks. Additionally, it enables the setting of route guards to
+ * respond to authentication status changes in a Vue.js application.
+ *
+ * This implementation is designed to work with a backend offering JWT mechanism.
+ * @param backendStoreOptions
+ * @returns An object containing authentication state, API client instance, and helper functions:
+ * - `axiosInstance`: Pre-configured axios instance with authentication support
+ * - `authenticated`: Reactive flag representing the authentication status
+ * - `login`: Function to authenticate users using credentials
+ * - `logout`: Function to deauthenticate users and clear authentication tokens
+ * - `setPostLogin`: Method to set a callback function invoked after successful login
+ * - `setPostLogout`: Method to set a callback function invoked after logout
+ * - `setupAuthRouteGuard`: Function to set up route guard for managing authentication-driven route reevaluations
+ */
+export function jwtAuthenticationBackendStoreSetup(
+  backendStoreOptions: BackendStoreOptions
+): BackendStore {
+  /**
+   * A reactive variable that indicates whether a user is authenticated or not.
+   *
+   * The value is `false` by default, representing an unauthenticated state.
+   * This variable can be updated dynamically to reflect the authentication status
+   * of the user within the application.
+   */
+  const authenticated = ref(false)
+  const _accessToken: Ref<string | null> = ref(null)
+  const _refreshToken: Ref<string | null> = ref(null)
+  const _postLogout: Ref<() => void> = ref(() => {})
+  const _postLogin: Ref<() => void> = ref(() => {})
+  const _accessTokenFromLocalStorage = localStorage.getItem(jwtAccessTokenKey)
+  const _refreshTokenFromLocalStorage = localStorage.getItem(jwtRefreshTokenKey)
+  const loginEndpoint = backendStoreOptions.endpoints?.jwt?.loginEndpoint ?? jwtLoginEndpoint
+  const refreshUrl = backendStoreOptions.endpoints?.jwt?.refreshEndpoint ?? jwtRefreshEndpoint
+
+  // Create common authentication functions
+  const commonAuth = createCommonAuthFunctions(authenticated, _postLogin, _postLogout)
+
+  if (_accessTokenFromLocalStorage && _refreshTokenFromLocalStorage) {
+    _accessToken.value = _accessTokenFromLocalStorage
+    _refreshToken.value = _refreshTokenFromLocalStorage
+    authenticated.value = true
+  }
+
+  watch(_accessToken, () => {
+    localStorage.setItem(jwtAccessTokenKey, _accessToken.value ?? '')
+  })
+
+  watch(_refreshToken, () => {
+    localStorage.setItem(jwtRefreshTokenKey, _refreshToken.value ?? '')
+  })
+
+  axiosInstance.defaults.withCredentials = true
+  axiosInstance.defaults.headers.common['Content-Type'] = 'application/json'
+
+  axiosInstance.interceptors.request.use(
+    async (config) => {
+      if (authenticated.value && _accessToken.value) {
+        config.headers['Authorization'] = `Bearer ${_accessToken.value}`
+      }
+      return config
+    },
+    (error) => Promise.reject(error)
+  )
+
+  /**
+   * Checks if the error is related to token authentication issues
+   * @param error - The Axios error to check for token-related issues
+   * @param accessToken
+   * @param refreshToken
+   * @returns True if the error is related to token authentication, false otherwise
+   */
+  function defaultIsTokenError(
+    error: AxiosError,
+    accessToken: string | null,
+    refreshToken: string | null
+  ): boolean {
+    return !!(
+      error.response &&
+      [401, 403].includes(error.response.status) &&
+      ((error.response?.data as { code?: string })?.code === 'token_not_valid' ||
+        !accessToken ||
+        !refreshToken)
+    )
+  }
+
+  const isTokenError =
+    backendStoreOptions.endpoints?.jwt?.isTokenError ??
+    ((error: AxiosError, context: { accessToken: string | null; refreshToken: string | null }) =>
+      defaultIsTokenError(error, context.accessToken, context.refreshToken))
+
+  /**
+   * Attempts to refresh the JWT token and retry the original request
+   * @param originalRequest - The original Axios request configuration to retry after token refresh
+   * @returns A promise that resolves to the Axios response from the retried request
+   */
+  async function handleTokenRefresh(
+    originalRequest: InternalAxiosRequestConfig
+  ): Promise<AxiosResponse> {
+    const response = await axiosInstance.post(refreshUrl, {
+      refresh: _refreshToken.value,
+    })
+
+    if (response.status === 200) {
+      // Update the tokens
+      _accessToken.value = response.data.access
+      if (response.data.refresh) {
+        _refreshToken.value = response.data.refresh
+      }
+
+      // Retry the original request with the new token
+      originalRequest.headers['Authorization'] = `Bearer ${_accessToken.value}`
+      return axiosInstance(originalRequest)
+    }
+    throw new Error('Token refresh failed')
+  }
+
+  axiosInstance.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      if (
+        !isTokenError(error, {
+          accessToken: _accessToken.value,
+          refreshToken: _refreshToken.value,
+        })
+      ) {
+        return Promise.reject(error)
+      }
+
+      const originalRequest = error.config
+      const isRefreshRequest = originalRequest.url === refreshUrl
+
+      // Prevent infinite loops
+      if (!isRefreshRequest && _refreshToken.value) {
+        try {
+          return await handleTokenRefresh(originalRequest)
+        } catch (refreshError) {
+          logout()
+          return Promise.reject(refreshError)
+        }
+      } else {
+        logout()
+      }
+
+      return Promise.reject(error)
+    }
+  )
+
+  /**
+   * Authenticates a user by sending their credentials to the server.
+   * @param credentials - The user's login credentials, typically including a username and password.
+   * @returns A promise that resolves to the Axios response object returned from the authentication request.
+   */
+  async function login(credentials: Credentials): Promise<AxiosResponse> {
+    const response = await axiosInstance.post(loginEndpoint, credentials)
+    if (response.status === 200) {
+      authenticated.value = true
+      _accessToken.value = response.data.access
+      _refreshToken.value = response.data.refresh
+    }
+    _postLogin.value()
+    return response
+  }
+
+  /**
+   * Logs the user out of the application by performing the following actions:
+   * - Removes the user's authentication tokens from localStorage.
+   * - Updates the application's authenticated state to false.
+   * - Resets the stored authentication tokens to null.
+   * - Executes any additional post-logout logic defined in the application.
+   */
+  function logout(): void {
+    localStorage.removeItem(jwtAccessTokenKey)
+    localStorage.removeItem(jwtRefreshTokenKey)
+    authenticated.value = false
+    _accessToken.value = null
+    _refreshToken.value = null
+    _postLogout.value()
+  }
+
+  return {
+    axiosInstance,
+    authenticated,
+    login,
+    logout,
+    setPostLogin: commonAuth.setPostLogin,
+    setPostLogout: commonAuth.setPostLogout,
+    setupAuthRouteGuard: commonAuth.setupAuthRouteGuard,
+    unsetAuthRouteGuard: commonAuth.unsetAuthRouteGuard,
+  }
+}

package/src/stores/backend/schemes/oauth.ts

@@ -0,0 +1,142 @@
+import { ref, type Ref } from 'vue'
+import type { AxiosResponse } from 'axios'
+import axiosInstance from '@/network/axios.ts'
+import { createCommonAuthFunctions } from '../common.ts'
+import { oauthLoginEndpoint, oauthLogoutEndpoint, oauthSessionEndpoint } from '../constants.ts'
+import type { BackendStore, BackendStoreOptions } from '../types.ts'
+
+/**
+ * Response shape returned by the Backend-for-Frontend (BFF) session endpoint.
+ */
+interface OAuthSessionStatus {
+  session: boolean
+}
+
+/**
+ * Response shape returned by the Backend-for-Frontend (BFF) login endpoint.
+ */
+interface OAuthLoginResponse {
+  redirect?: string
+}
+
+/**
+ * Configures and sets up an OAuth session-based authentication backend store.
+ *
+ * This implementation expects a Backend-for-Frontend (BFF) to manage OAuth login/logout flows and session cookies.
+ * It checks session state on initialization, initiates login when no session exists, and
+ * ensures axios requests include credentials.
+ *
+ * Consuming apps should call `useBackendStore` once at app startup, or ensure it is created
+ * before route guards run, so session state is resolved early.
+ * @param backendStoreOptions - Store configuration, including OAuth endpoint overrides and redirect handler.
+ * @returns An object containing authentication state, API client instance, and helper functions:
+ */
+export function oauthAuthenticationBackendStoreSetup(
+  backendStoreOptions: BackendStoreOptions
+): BackendStore {
+  const authenticated = ref(false)
+  const _postLogout: Ref<() => void> = ref(() => {})
+  const _postLogin: Ref<() => void> = ref(() => {})
+
+  const commonAuth = createCommonAuthFunctions(authenticated, _postLogin, _postLogout)
+
+  const oauthOverrides = backendStoreOptions.endpoints?.oauth
+  const oauthEndpoints = {
+    login: oauthOverrides?.loginEndpoint ?? oauthLoginEndpoint,
+    logout: oauthOverrides?.logoutEndpoint ?? oauthLogoutEndpoint,
+    session: oauthOverrides?.sessionEndpoint ?? oauthSessionEndpoint,
+  }
+  const redirectHandler =
+    oauthOverrides?.redirectHandler ??
+    ((url: string) => {
+      if (typeof window === 'undefined') {
+        return
+      }
+      window.location.assign(url)
+    })
+
+  axiosInstance.defaults.withCredentials = true
+  axiosInstance.defaults.headers.common['Content-Type'] = 'application/json'
+
+  initializeAuthenticationStore().catch((error) => {
+    console.debug(error)
+  })
+
+  /**
+   * Initializes the OAuth store by checking session state and triggering login if no session exists.
+   * This is invoked once during store creation to prime `authenticated` early in app startup.
+   */
+  async function initializeAuthenticationStore(): Promise<void> {
+    const sessionStatus = await checkSessionStatus()
+    authenticated.value = sessionStatus.session
+
+    if (!sessionStatus.session) {
+      await initiateOauthSession()
+    }
+  }
+
+  /**
+   * Calls the Backend-for-Frontend (BFF) session endpoint to determine whether a valid session exists.
+   * On failure, it forces an unauthenticated state and returns `{ session: false }`.
+   * @returns Session status payload from the Backend-for-Frontend (BFF).
+   */
+  async function checkSessionStatus(): Promise<OAuthSessionStatus> {
+    return axiosInstance
+      .get(oauthEndpoints.session, { withCredentials: true })
+      .then((response) => response.data as OAuthSessionStatus)
+      .catch((error) => {
+        console.debug(error)
+        authenticated.value = false
+        return { session: false }
+      })
+  }
+
+  /**
+   * Initiates the OAuth login flow via the Backend-for-Frontend (BFF) login endpoint.
+   * Expects a JSON payload containing a `redirect` URL and navigates to it.
+   * Runs the post-login callback after a redirect URL is received.
+   * @returns Axios response from the login endpoint for chaining/testing.
+   */
+  async function initiateOauthSession(): Promise<AxiosResponse> {
+    const response = await axiosInstance.get(oauthEndpoints.login, { withCredentials: true })
+    const redirect = (response.data as OAuthLoginResponse | undefined)?.redirect
+    if (redirect) {
+      redirectHandler(redirect)
+      _postLogin.value()
+    } else {
+      authenticated.value = false
+    }
+    return response
+  }
+
+  /**
+   * Starts the OAuth login flow. Credentials are ignored because the Backend-for-Frontend (BFF) handles login.
+   * @returns Axios response from the login endpoint for chaining/testing.
+   */
+  async function login(): Promise<AxiosResponse> {
+    return await initiateOauthSession()
+  }
+
+  /**
+   * Logs out via the Backend-for-Frontend (BFF) logout endpoint and clears local authentication state.
+   * Post-logout callbacks are executed after the request completes (success or failure).
+   */
+  function logout(): void {
+    authenticated.value = false
+    axiosInstance
+      .get(oauthEndpoints.logout, { withCredentials: true })
+      .catch((error) => console.debug(error))
+      .finally(() => _postLogout.value())
+  }
+
+  return {
+    axiosInstance,
+    authenticated,
+    login,
+    logout,
+    setPostLogin: commonAuth.setPostLogin,
+    setPostLogout: commonAuth.setPostLogout,
+    setupAuthRouteGuard: commonAuth.setupAuthRouteGuard,
+    unsetAuthRouteGuard: commonAuth.unsetAuthRouteGuard,
+  }
+}

package/src/stores/backend/schemes/token.ts

@@ -0,0 +1,122 @@
+import { ref, watch, type Ref } from 'vue'
+import type { AxiosResponse } from 'axios'
+import axiosInstance from '@/network/axios.ts'
+import { createCommonAuthFunctions } from '../common.ts'
+import { localStorageKey, tokenLoginEndpoint } from '../constants.ts'
+import type { BackendStore, BackendStoreOptions, Credentials } from '../types.ts'
+
+/**
+ * Configures and sets up a token-based authentication backend store for managing API authentication.
+ *
+ * The method initializes authentication states, such as tokens, login/logout handlers, and
+ * authentication interceptors on the axiosInstance for requests and responses.
+ * It also provides helper functions for handling authentication processes, like login, logout,
+ * and post-login/logout callbacks. Additionally, it enables the setting of route guards to
+ * respond to authentication status changes in a Vue.js application.
+ * @param backendStoreOptions
+ * @returns An object containing authentication state, API client instance, and helper functions:
+ * - `axiosInstance`: Pre-configured axios instance with authentication support
+ * - `authenticated`: Reactive flag representing the authentication status
+ * - `login`: Function to authenticate users using credentials
+ * - `logout`: Function to deauthenticate users and clear authentication tokens
+ * - `setPostLogin`: Method to set a callback function invoked after successful login
+ * - `setPostLogout`: Method to set a callback function invoked after logout
+ * - `setupAuthRouteGuard`: Function to set up route guard for managing authentication-driven route reevaluations
+ */
+export function tokenAuthenticationBackendStoreSetup(
+  backendStoreOptions: BackendStoreOptions
+): BackendStore {
+  /**
+   * A reactive variable that indicates whether a user is authenticated or not.
+   *
+   * The value is `false` by default, representing an unauthenticated state.
+   * This variable can be updated dynamically to reflect the authentication status
+   * of the user within the application.
+   */
+  const authenticated = ref(false)
+  const _token: Ref<string | null> = ref(null)
+  const _postLogout: Ref<() => void> = ref(() => {})
+  const _postLogin: Ref<() => void> = ref(() => {})
+  const _fromLocalStorage = localStorage.getItem(localStorageKey)
+  const loginEndpoint = backendStoreOptions.endpoints?.token?.loginEndpoint ?? tokenLoginEndpoint
+
+  // Create common authentication functions
+  const commonAuth = createCommonAuthFunctions(authenticated, _postLogin, _postLogout)
+
+  if (_fromLocalStorage) {
+    _token.value = _fromLocalStorage
+    authenticated.value = true
+  }
+
+  watch(_token, () => {
+    localStorage.setItem(localStorageKey, _token.value ?? '')
+  })
+
+  axiosInstance.defaults.withCredentials = true
+  axiosInstance.defaults.headers.common['Content-Type'] = 'application/json'
+
+  axiosInstance.interceptors.request.use(
+    async (config) => {
+      if (authenticated.value && _token.value) {
+        config.headers['Authorization'] = `Token ${_token.value}`
+      }
+      return config
+    },
+    (error) => Promise.reject(error)
+  )
+
+  axiosInstance.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      if (error.response.status === 403) {
+        const data = error.response.data
+        if (data?.detail === 'Authentication credentials were not provided.') {
+          logout()
+        }
+        return Promise.reject(error)
+      } else {
+        return Promise.reject(error)
+      }
+    }
+  )
+
+  /**
+   * Authenticates a user by sending their credentials to the server.
+   * @param credentials - The user's login credentials, typically including a username and password.
+   * @returns A promise that resolves to the Axios response object returned from the authentication request.
+   */
+  async function login(credentials: Credentials): Promise<AxiosResponse> {
+    const response = await axiosInstance.post(loginEndpoint, credentials)
+    if (response.status === 200) {
+      authenticated.value = true
+      _token.value = response.data.token
+    }
+    _postLogin.value()
+    return response
+  }
+
+  /**
+   * Logs the user out of the application by performing the following actions:
+   * - Removes the user's authentication token from localStorage.
+   * - Updates the application's authenticated state to false.
+   * - Resets the stored authentication token to null.
+   * - Executes any additional post-logout logic defined in the application.
+   */
+  function logout(): void {
+    localStorage.removeItem(localStorageKey)
+    authenticated.value = false
+    _token.value = null
+    _postLogout.value()
+  }
+
+  return {
+    axiosInstance,
+    authenticated,
+    login,
+    logout,
+    setPostLogin: commonAuth.setPostLogin,
+    setPostLogout: commonAuth.setPostLogout,
+    setupAuthRouteGuard: commonAuth.setupAuthRouteGuard,
+    unsetAuthRouteGuard: commonAuth.unsetAuthRouteGuard,
+  }
+}

package/src/stores/backend/types.ts

@@ -0,0 +1,96 @@
+import type { Ref } from 'vue'
+import type { AxiosError, AxiosInstance, AxiosResponse } from 'axios'
+import type { Router } from 'vue-router'
+
+/**
+ * Represents the types of authentication mechanisms that can be used.
+ *
+ * This type includes the following options:
+ * - 'TOKEN': Authentication is performed using a token-based system.
+ * - 'JWT': Authentication is performed using JSON Web Tokens.
+ * - 'SESSION': Authentication is managed using session-based mechanisms (reserved, not yet implemented).
+ * - 'OAUTH': Authentication is managed by a Backend-for-Frontend (BFF) using OAuth session cookies.
+ *
+ * Note: Future enhancement could include more flexible procedures registration
+ * (postLogin, postLogout) to allow different actors to register their procedures
+ * on some collection.
+ */
+export type AuthenticationType = 'TOKEN' | 'JWT' | 'SESSION' | 'OAUTH'
+
+/**
+ * Represents a set of credentials consisting of a username and password.
+ * Typically used for authentication purposes.
+ */
+export interface Credentials {
+  username: string
+  password: string
+}
+
+/**
+ * Endpoint configuration for OAuth session authentication.
+ *
+ * `redirectHandler` can be used by consuming apps to control the redirect side effect
+ * (e.g. for tests, SPA-specific navigation, or analytics hooks).
+ */
+export interface OAuthEndpoints {
+  loginEndpoint?: string
+  logoutEndpoint?: string
+  sessionEndpoint?: string
+  redirectHandler?: (url: string) => void
+}
+
+/**
+ * Endpoint configuration for token authentication.
+ */
+export interface TokenEndpoints {
+  loginEndpoint?: string
+}
+
+/**
+ * Endpoint configuration for JWT authentication.
+ */
+export interface JwtEndpoints {
+  loginEndpoint?: string
+  refreshEndpoint?: string
+  /**
+   * Optional hook to detect token-related errors (e.g., SimpleJWT or custom backend behavior).
+   * When omitted, a default SimpleJWT-compatible check is used.
+   */
+  isTokenError?: (
+    error: AxiosError,
+    context: { accessToken: string | null; refreshToken: string | null }
+  ) => boolean
+}
+
+/**
+ * Optional per-scheme endpoint overrides for authentication flows.
+ */
+export interface AuthenticationEndpoints {
+  token?: TokenEndpoints
+  jwt?: JwtEndpoints
+  oauth?: OAuthEndpoints
+}
+
+/**
+ * Contract for the backend store returned by `useBackendStore`.
+ * Provides authentication state, auth actions, and optional router guard helpers.
+ */
+export interface BackendStore {
+  authenticated: Ref<boolean>
+  axiosInstance: AxiosInstance
+  login: (credentials: Credentials) => Promise<AxiosResponse>
+  logout: () => void
+  setPostLogin: (fn: () => void) => void
+  setPostLogout: (fn: () => void) => void
+  setupAuthRouteGuard: (router: Router) => void
+  unsetAuthRouteGuard: () => void
+}
+
+/**
+ * Configuration passed to `useBackendStore`/`defineBackendStore`.
+ * Controls the authentication scheme and any OAuth endpoint overrides.
+ */
+export interface BackendStoreOptions {
+  authenticationType: AuthenticationType
+  endpoints?: AuthenticationEndpoints
+}