@userfrosting/sprinkle-core 6.0.0-alpha.4 → 6.0.0-alpha.6

package/app/assets/composables/index.ts

@@ -1,2 +1,3 @@
-export { useSprunjer } from './sprunjer'
-export { usePageMeta } from './usePageMeta'
+export { useSprunjer } from './useSprunjer'
+export { useCsrf } from './useCsrf'
+export { useAxiosInterceptor } from './useAxiosInterceptor'

package/app/assets/composables/useAxiosInterceptor.ts

@@ -0,0 +1,30 @@
+import axios from 'axios'
+import { useAlertsStore } from '../stores/useAlertsStore'
+import { Severity } from '../interfaces'
+
+/**
+ * Axios Error Handler
+ *
+ * This composable sets up an Axios interceptor to handle errors globally using
+ * the Alerts store. It sends the error to the Alerts store, unless it's a 401
+ * error.
+ *
+ * @see https://axios-http.com/docs/interceptors
+ */
+export const useAxiosInterceptor = () => {
+    axios.interceptors.response.use(
+        (response) => response,
+        (error) => {
+            if (error.response.status !== 401) {
+                const alertStore = useAlertsStore()
+                alertStore.push({
+                    title: error.response.data.title ?? error.response?.statusText,
+                    description: error.response?.data?.description ?? error.message,
+                    style: Severity.Danger
+                })
+            }
+
+            return Promise.reject(error)
+        }
+    )
+}

package/app/assets/composables/useCsrf.ts

@@ -0,0 +1,129 @@
+import { ref, watchEffect } from 'vue'
+import { useConfigStore } from '../stores'
+import axios from 'axios'
+
+/**
+ * CSRF Protection Composable
+ *
+ * Automatically sets the CSRF token in the axios headers for all requests.
+ * The CSRF token is read from the meta tags in the HTML document.
+ * The CSRF token can updated when the server responds with a new token in the headers.
+ *
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#axios
+ */
+export const useCsrf = () => {
+    /**
+     * Public constant for the CSRF token name and value, plus respective keys.
+     */
+    const key_name = ref(getNameKey())
+    const key_value = ref(getValueKey())
+    const name = ref(readMetaTag(key_name.value))
+    const token = ref(readMetaTag(key_value.value))
+
+    /**
+     * Set the axios headers for CSRF protection
+     */
+    function setAxiosHeader() {
+        axios.defaults.headers.post[key_name.value] = name.value
+        axios.defaults.headers.post[key_value.value] = token.value
+        axios.defaults.headers.put[key_name.value] = name.value
+        axios.defaults.headers.put[key_value.value] = token.value
+        axios.defaults.headers.delete[key_name.value] = name.value
+        axios.defaults.headers.delete[key_value.value] = token.value
+        axios.defaults.headers.patch[key_name.value] = name.value
+        axios.defaults.headers.patch[key_value.value] = token.value
+    }
+
+    /**
+     * Fetch the CSRF token from the server
+     */
+    async function fetchCsrfToken() {
+        const response = await axios.get('/api/csrf')
+        updateFromHeaders(response.headers)
+    }
+
+    /**
+     * Get the CSRF token name and value keys from config.
+     */
+    function getNameKey(): string {
+        const config = useConfigStore()
+        return config.get('csrf.name', 'csrf') + '_name'
+    }
+    function getValueKey(): string {
+        const config = useConfigStore()
+        return config.get('csrf.name', 'csrf') + '_value'
+    }
+
+    /**
+     * Meta tag reader and writer
+     */
+    function readMetaTag(name: string): string {
+        return document.querySelector("meta[name='" + name + "']")?.getAttribute('content') ?? ''
+    }
+    function writeMetaTag(name: string, value: string) {
+        const metaTag = document.querySelector("meta[name='" + name + "']")
+        if (metaTag) {
+            metaTag.setAttribute('content', value)
+        } else {
+            const newMetaTag = document.createElement('meta')
+            newMetaTag.setAttribute('name', name)
+            newMetaTag.setAttribute('content', value)
+            document.head.appendChild(newMetaTag)
+        }
+    }
+
+    /**
+     * Update the CSRF token with the values from the request headers.
+     *
+     * N.B.: CSRF keys are hardcoded with '{name}_name' and '{name}_value' in
+     * PHP. However, the headers doesn't allows underscores that are replaced
+     * with dashes automatically.
+     */
+    function updateFromHeaders(headers: any) {
+        const config = useConfigStore()
+        const nameKey = config.get('csrf.name', 'csrf') + '-name'
+        const valueKey = config.get('csrf.name', 'csrf') + '-value'
+
+        // Update both value only if the headers are present
+        // This is to avoid overwriting the CSRF token with empty values
+        if (nameKey in headers) {
+            name.value = headers[nameKey]
+        }
+        if (valueKey in headers) {
+            token.value = headers[valueKey]
+        }
+    }
+
+    /**
+     * Return if CSRF is enabled
+     */
+    function isEnabled(): boolean {
+        const config = useConfigStore()
+        return config.get('csrf.enabled', true)
+    }
+
+    /**
+     * Watchers - Watch for changes in the CSRF token and update the axios
+     * headers + meta tags
+     */
+    watchEffect(() => {
+        if (isEnabled() && name.value !== '' && token.value !== '') {
+            writeMetaTag(key_name.value, name.value)
+            writeMetaTag(key_value.value, token.value)
+            setAxiosHeader()
+        }
+    })
+
+    /**
+     * Export functions and managed states
+     */
+    return {
+        key_name,
+        key_value,
+        name,
+        token,
+        isEnabled,
+        updateFromHeaders,
+        fetchCsrfToken
+    }
+}

package/app/assets/composables/{sprunjer.ts → useSprunjer.ts}

@@ -33,7 +33,13 @@
  */
 import { ref, toValue, watchEffect, computed } from 'vue'
 import axios from 'axios'
-import type { AssociativeArray, Sprunjer, SprunjerData, SprunjerResponse } from '../interfaces'
+import type {
+    ApiErrorResponse,
+    AssociativeArray,
+    Sprunjer,
+    SprunjerData,
+    SprunjerResponse
+} from '../interfaces'
 
 export const useSprunjer = (
     dataUrl: string | (() => string),
@@ -60,6 +66,7 @@ export const useSprunjer = (
 
     // State
     const loading = ref<boolean>(false)
+    const error = ref<ApiErrorResponse | null>(null)
 
     /**
      * Api fetch function
@@ -87,8 +94,7 @@ export const useSprunjer = (
                 data.value.filterable = response.data.filterable ?? []
             })
             .catch((err) => {
-                // TODO : User toast alert, or export alert
-                console.error(err)
+                error.value = err.response.data as ApiErrorResponse
             })
             .finally(() => {
                 loading.value = false
@@ -169,6 +175,7 @@ export const useSprunjer = (
         data,
         fetch,
         loading,
+        error,
         downloadCsv,
         totalPages,
         countFiltered,

package/app/assets/index.ts

@@ -1,15 +1,24 @@
 import type { App } from 'vue'
 import { useConfigStore, useTranslator } from './stores'
+import { useCsrf } from './composables/useCsrf'
+import { useAxiosInterceptor } from './composables'
 
 /**
  * Core Sprinkle initialization recipe.
  *
  * This recipe is responsible for loading the configuration from the api,
- * loading the translations and register the translator as $t and $tdate global
- * properties.
+ * loading the translations, register the translator as $t and $tdate global
+ * properties and setting up the axios CSRF headers.
  */
 export default {
     install: (app: App) => {
+        /**
+         * Add Axios error handler.
+         * Load first to ensure that all axios requests are intercepted.
+         * This is important for the config loading and translator loading.
+         */
+        useAxiosInterceptor()
+
         /**
          * Load configuration
          */
@@ -22,5 +31,10 @@ export default {
         translator.load()
         app.config.globalProperties.$t = translator.translate
         app.config.globalProperties.$tdate = translator.translateDate
+
+        /**
+         * Setup CSRF Protection.
+         */
+        useCsrf()
     }
 }

package/app/assets/interfaces/ApiResponse.ts

@@ -4,5 +4,12 @@
  * Generic API Response interface.
  */
 export interface ApiResponse {
-    message: string
+    title: string
+    description?: string
+}
+
+export interface ApiErrorResponse {
+    title: string
+    description: string
+    status: number
 }

package/app/assets/interfaces/index.ts

@@ -27,4 +27,4 @@ export type { SprunjerRequest, SprunjerResponse } from './sprunjerApi'
 export type { DictionaryResponse, DictionaryEntries, DictionaryConfig } from './DictionaryApi'
 
 // Misc
-export type { ApiResponse } from './ApiResponse'
+export type { ApiResponse, ApiErrorResponse } from './ApiResponse'

package/app/assets/interfaces/sprunjer.ts

@@ -4,7 +4,7 @@
  * Represents the interface for the Sprunjer composable.
  */
 import type { Ref, ComputedRef } from 'vue'
-import type { AssociativeArray } from '.'
+import type { ApiErrorResponse, AssociativeArray } from '.'
 
 export interface Sprunjer {
     dataUrl: string | (() => string)
@@ -15,6 +15,7 @@ export interface Sprunjer {
     data: Ref<SprunjerData>
     fetch: () => void
     loading: Ref<boolean>
+    error: Ref<ApiErrorResponse | null>
     totalPages: ComputedRef<number>
     downloadCsv: () => void
     countFiltered: ComputedRef<number>

package/app/assets/routes/index.ts

@@ -12,7 +12,7 @@ export default [
             title: 'ERROR.404.TITLE',
             description: 'ERROR.404.DESCRIPTION'
         },
-        component: () => import('../views/404NotFound.vue')
+        component: () => import('../views/Page404NotFound.vue')
     },
     {
         path: '/:pathMatch(.*)*',
@@ -21,7 +21,7 @@ export default [
             title: 'ERROR.401.TITLE',
             description: 'ERROR.401.DESCRIPTION'
         },
-        component: () => import('../views/401Unauthorized.vue')
+        component: () => import('../views/Page401Unauthorized.vue')
     },
     {
         path: '/:pathMatch(.*)*',
@@ -30,7 +30,7 @@ export default [
             title: 'ERROR.403.TITLE',
             description: 'ERROR.403.DESCRIPTION'
         },
-        component: () => import('../views/403Forbidden.vue')
+        component: () => import('../views/Page403Forbidden.vue')
     },
     {
         path: '/:pathMatch(.*)*',
@@ -39,6 +39,6 @@ export default [
             title: 'ERROR.TITLE',
             description: 'ERROR.DESCRIPTION'
         },
-        component: () => import('../views/ErrorPage.vue')
+        component: () => import('../views/PageError.vue')
     }
 ]

package/app/assets/stores/index.ts

@@ -1,2 +1,4 @@
-export { useConfigStore } from './config'
+export { useConfigStore } from './useConfigStore'
+export { usePageMeta } from './usePageMeta'
 export { useTranslator } from './useTranslator'
+export { useAlertsStore } from './useAlertsStore'

package/app/assets/stores/useAlertsStore.ts

@@ -0,0 +1,30 @@
+import { defineStore } from 'pinia'
+import type { AlertInterface } from '../interfaces'
+
+/**
+ * Alerts Store
+ *
+ * Manages application alerts in a reactive store. Templates can use this
+ * store to display alerts to users, including errors, warnings,
+ * informational, or success messages. When an alert is added, templates
+ * should automatically update the interface to reflect the change.
+ */
+export const useAlertsStore = defineStore('alerts', {
+    state: () => ({
+        alerts: [] as AlertInterface[]
+    }),
+    actions: {
+        push(alert: AlertInterface) {
+            this.alerts.push(alert)
+        },
+        pop() {
+            return this.alerts.pop()
+        },
+        shift() {
+            return this.alerts.shift()
+        },
+        clear() {
+            this.alerts = []
+        }
+    }
+})

package/app/assets/tests/composables/useCsrf.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, beforeEach, afterEach, test, vi } from 'vitest'
+import axios from 'axios'
+import { useConfigStore } from '../../stores/useConfigStore'
+import { useCsrf } from '../../composables/useCsrf'
+import { nextTick } from 'vue'
+
+// Mock the config store
+vi.mock('../../stores/useConfigStore')
+const mockUseConfigStore = {
+    get: vi.fn()
+}
+
+describe('Csrf Composable', () => {
+    afterEach(() => {
+        vi.clearAllMocks()
+        vi.resetAllMocks()
+    })
+
+    beforeEach(() => {
+        // Mock the config store
+        mockUseConfigStore.get.mockImplementation((key, defaultValue) => {
+            if (key === 'csrf.enabled') return true
+            if (key === 'csrf.name') return 'csrf'
+            return defaultValue
+        })
+        vi.mocked(useConfigStore).mockReturnValue(mockUseConfigStore as any)
+
+        // Reset axios defaults
+        axios.defaults.headers.post = {}
+        axios.defaults.headers.put = {}
+        axios.defaults.headers.delete = {}
+        axios.defaults.headers.patch = {}
+
+        // Reset the document head
+        document.head.innerHTML = ''
+    })
+
+    test('initializes CSRF token name and value from meta tags', () => {
+        document.head.innerHTML = `
+            <meta name="csrf_name" content="123456">
+            <meta name="csrf_value" content="7c4a8d09">
+        `
+
+        const { name, token } = useCsrf()
+        expect(name.value).toBe('123456')
+        expect(token.value).toBe('7c4a8d09')
+    })
+
+    test('sets axios headers correctly when CSRF is enabled', async () => {
+        const csrf = useCsrf()
+
+        // Expect axios default headers
+        expect(axios.defaults.headers.post).toEqual({})
+        expect(axios.defaults.headers.put).toEqual({})
+        expect(axios.defaults.headers.delete).toEqual({})
+        expect(axios.defaults.headers.patch).toEqual({})
+
+        // Set CSRF token values - Will trigger the WatchEffect
+        csrf.name.value = '654321'
+        csrf.token.value = 'abcdef'
+
+        // Wait for the next tick to ensure watchEffect is triggered
+        await nextTick()
+
+        // Expect axios headers to be set correctly
+        expect(csrf.isEnabled()).toBe(true)
+        expect(csrf.name.value).toBe('654321')
+        expect(csrf.token.value).toBe('abcdef')
+        expect(csrf.key_name.value).toBe('csrf_name')
+        expect(csrf.key_value.value).toBe('csrf_value')
+        expect(axios.defaults.headers.post['csrf_name']).toBe('654321')
+        expect(axios.defaults.headers.post['csrf_value']).toBe('abcdef')
+        expect(axios.defaults.headers.put['csrf_name']).toBe('654321')
+        expect(axios.defaults.headers.put['csrf_value']).toBe('abcdef')
+        expect(axios.defaults.headers.delete['csrf_name']).toBe('654321')
+        expect(axios.defaults.headers.delete['csrf_value']).toBe('abcdef')
+        expect(axios.defaults.headers.patch['csrf_name']).toBe('654321')
+        expect(axios.defaults.headers.patch['csrf_value']).toBe('abcdef')
+    })
+
+    test('does not set axios headers when CSRF is disabled', () => {
+        // Change the mock implementation to simulate CSRF being disabled
+        mockUseConfigStore.get.mockImplementation((key, defaultValue) => {
+            if (key === 'csrf.enabled') return false // CSRF is disabled
+            if (key === 'csrf.name') return 'csrf'
+            return defaultValue
+        })
+        vi.mocked(useConfigStore).mockReturnValue(mockUseConfigStore as any)
+
+        // Get the CSRF composable
+        const csrf = useCsrf()
+
+        // Assert everything is empty
+        expect(csrf.isEnabled()).toBe(false)
+        expect(csrf.name.value).toBe('')
+        expect(csrf.token.value).toBe('')
+        expect(axios.defaults.headers.post).toEqual({})
+        expect(axios.defaults.headers.put).toEqual({})
+        expect(axios.defaults.headers.delete).toEqual({})
+        expect(axios.defaults.headers.patch).toEqual({})
+    })
+
+    test('updates CSRF token updates meta tags', async () => {
+        document.head.innerHTML = `
+            <meta name="csrf_name" content="old_name">
+            <meta name="csrf_value" content="old_value">
+        `
+
+        // Assert initial state
+        const csrf = useCsrf()
+        expect(csrf.name.value).toBe('old_name')
+        expect(csrf.token.value).toBe('old_value')
+        expect(document.querySelector("meta[name='csrf_name']")?.getAttribute('content')).toBe(
+            'old_name'
+        )
+        expect(document.querySelector("meta[name='csrf_value']")?.getAttribute('content')).toBe(
+            'old_value'
+        )
+
+        // Update CSRF tokens manually
+        csrf.name.value = 'new_name'
+        csrf.token.value = 'new_value'
+
+        // Wait for the next tick to ensure watchEffect is triggered
+        await nextTick()
+
+        // Assert new state
+        expect(csrf.name.value).toBe('new_name')
+        expect(csrf.token.value).toBe('new_value')
+        expect(document.querySelector("meta[name='csrf_name']")?.getAttribute('content')).toBe(
+            'new_name'
+        )
+        expect(document.querySelector("meta[name='csrf_value']")?.getAttribute('content')).toBe(
+            'new_value'
+        )
+    })
+
+    test('CSRF token can be updated from headers', async () => {
+        const csrf = useCsrf()
+
+        // Assert initial state
+        expect(csrf.name.value).toBe('')
+        expect(csrf.token.value).toBe('')
+
+        const headers = {
+            'csrf-name': 'new_name',
+            'csrf-value': 'new_value'
+        }
+        csrf.updateFromHeaders(headers)
+
+        // Wait for the next tick to ensure watchEffect is triggered
+        await nextTick()
+
+        expect(csrf.name.value).toBe('new_name')
+        expect(csrf.token.value).toBe('new_value')
+        expect(document.querySelector("meta[name='csrf_name']")?.getAttribute('content')).toBe(
+            'new_name'
+        )
+        expect(document.querySelector("meta[name='csrf_value']")?.getAttribute('content')).toBe(
+            'new_value'
+        )
+        expect(axios.defaults.headers.post['csrf_name']).toBe('new_name')
+        expect(axios.defaults.headers.post['csrf_value']).toBe('new_value')
+        expect(axios.defaults.headers.put['csrf_name']).toBe('new_name')
+        expect(axios.defaults.headers.put['csrf_value']).toBe('new_value')
+        expect(axios.defaults.headers.delete['csrf_name']).toBe('new_name')
+        expect(axios.defaults.headers.delete['csrf_value']).toBe('new_value')
+        expect(axios.defaults.headers.patch['csrf_name']).toBe('new_name')
+        expect(axios.defaults.headers.patch['csrf_value']).toBe('new_value')
+    })
+
+    test('CSRF token can handle empty headers', async () => {
+        document.head.innerHTML = `
+            <meta name="csrf_name" content="123456">
+            <meta name="csrf_value" content="abcdef">
+        `
+
+        // Assert initial state
+        const csrf = useCsrf()
+        expect(csrf.name.value).toBe('123456')
+        expect(csrf.token.value).toBe('abcdef')
+        expect(document.querySelector("meta[name='csrf_name']")?.getAttribute('content')).toBe(
+            '123456'
+        )
+        expect(document.querySelector("meta[name='csrf_value']")?.getAttribute('content')).toBe(
+            'abcdef'
+        )
+        expect(axios.defaults.headers.post['csrf_name']).toBe('123456')
+        expect(axios.defaults.headers.post['csrf_value']).toBe('abcdef')
+
+        // Call updateFromHeaders with empty headers
+        const headers = {
+            foo: 'bar'
+        }
+        csrf.updateFromHeaders(headers)
+
+        // Wait for the next tick to ensure watchEffect is triggered
+        await nextTick()
+
+        // Assert state remains unchanged
+        expect(csrf.name.value).toBe('123456')
+        expect(csrf.token.value).toBe('abcdef')
+        expect(document.querySelector("meta[name='csrf_name']")?.getAttribute('content')).toBe(
+            '123456'
+        )
+        expect(document.querySelector("meta[name='csrf_value']")?.getAttribute('content')).toBe(
+            'abcdef'
+        )
+        expect(axios.defaults.headers.post['csrf_name']).toBe('123456')
+        expect(axios.defaults.headers.post['csrf_value']).toBe('abcdef')
+    })
+})

package/app/assets/tests/plugin.test.ts

@@ -1,12 +1,13 @@
 import { describe, expect, test, vi } from 'vitest'
 import { createApp } from 'vue'
-import { useConfigStore } from '../stores/config'
+import { useConfigStore } from '../stores/useConfigStore'
 import plugin from '..'
-import * as Config from '../stores/config'
+import * as Config from '../stores/useConfigStore'
 import * as Translator from '../stores/useTranslator'
 
 const mockConfigStore = {
-    load: vi.fn()
+    load: vi.fn(),
+    get: vi.fn().mockReturnValue('csrf')
 }
 
 const mockTranslatorStore = {

package/app/assets/tests/stores/config.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, beforeEach, test, vi } from 'vitest'
 import { setActivePinia, createPinia } from 'pinia'
 import axios from 'axios'
-import { useConfigStore } from '../../stores/config'
+import { useConfigStore } from '../../stores/useConfigStore'
 
 const testConfig = {
     name: 'Test Config',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@userfrosting/sprinkle-core",
-    "version": "6.0.0-alpha.4",
+    "version": "6.0.0-alpha.6",
     "type": "module",
     "description": "Core Sprinkle for UserFrosting",
     "funding": "https://opencollective.com/userfrosting",
@@ -49,7 +49,7 @@
         "@types/luxon": "^3.4.2",
         "@types/node": "^20.12.5",
         "@vitejs/plugin-vue": "^5.0.4",
-        "@vitest/coverage-v8": "^1.6.0",
+        "@vitest/coverage-v8": "^3.1.1",
         "@vue/eslint-config-prettier": "^9.0.0",
         "@vue/eslint-config-typescript": "^13.0.0",
         "@vue/test-utils": "^2.4.6",
@@ -59,10 +59,10 @@
         "happy-dom": "^15.11.6",
         "less": "^4.2.0",
         "npm-run-all2": "^6.1.2",
-        "prettier": "^3.2.5",
-        "vite": "^5.2.8",
+        "prettier": "^3.6.2",
+        "vite": "^6.2",
         "vite-plugin-dts": "^4.0.0",
-        "vitest": "^1.6.0",
+        "vitest": "^3.1.1",
         "vue": "^3.4.21",
         "vue-router": "^4.2.4",
         "vue-tsc": "^2.0.11"