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

package/app/assets/composables/index.ts

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

package/app/assets/composables/useCsrf.ts

@@ -0,0 +1,120 @@
+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
+    }
+
+    /**
+     * 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
+    }
+}

package/app/assets/index.ts

@@ -1,12 +1,13 @@
 import type { App } from 'vue'
 import { useConfigStore, useTranslator } from './stores'
+import { useCsrf } from './composables/useCsrf'
 
 /**
  * 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) => {
@@ -22,5 +23,10 @@ export default {
         translator.load()
         app.config.globalProperties.$t = translator.translate
         app.config.globalProperties.$tdate = translator.translateDate
+
+        /**
+         * Setup CSRF Protection.
+         */
+        useCsrf()
     }
 }

package/app/assets/stores/index.ts

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

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/config'
+import { useCsrf } from '../../composables/useCsrf'
+import { nextTick } from 'vue'
+
+// Mock the config store
+vi.mock('../../stores/config')
+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

@@ -6,7 +6,8 @@ import * as Config from '../stores/config'
 import * as Translator from '../stores/useTranslator'
 
 const mockConfigStore = {
-    load: vi.fn()
+    load: vi.fn(),
+    get: vi.fn().mockReturnValue('csrf')
 }
 
 const mockTranslatorStore = {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@userfrosting/sprinkle-core",
-    "version": "6.0.0-alpha.4",
+    "version": "6.0.0-alpha.5",
     "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",
@@ -60,9 +60,9 @@
         "less": "^4.2.0",
         "npm-run-all2": "^6.1.2",
         "prettier": "^3.2.5",
-        "vite": "^5.2.8",
+        "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"