feat!: safe query fetching with server api route

Author: johannschopplich

playground/.env.example

@@ -1,2 +1,2 @@
-KIRBY_API_URL=https://kirby-headless-starter.jhnn.dev/api
+KIRBY_BASE_URL=https://kirby-headless-starter.jhnn.dev
 KIRBY_API_TOKEN=test

playground/app.vue

@@ -1,3 +1,5 @@
 <template>
-  <NuxtPage />
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
 </template>

playground/layouts/default.vue

@@ -0,0 +1,15 @@
+<template>
+  <header>
+    <NuxtLink to="/">
+      Index
+    </NuxtLink>
+    /
+    <NuxtLink to="/client">
+      <span>Client KQL</span>
+    </NuxtLink>
+  </header>
+
+  <main>
+    <slot />
+  </main>
+</template>

playground/nuxt.config.ts

@@ -7,7 +7,9 @@ export default defineNuxtConfig({
   ],
 
   kql: {
-    auth: 'bearer',
-    endpoint: 'kql',
+    kirbyEndpoint: 'api/kql',
+    kirbyAuth: 'bearer',
+    // Disable the following to prevent usage of `usePublicKql()` and `$publicKql()`
+    clientRequests: true,
   },
 })

playground/pages/client.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+const refreshIndex = ref(0)
+const query = ref({
+  query: 'site',
+  select: {
+    title: 'site.title',
+    children: 'site.children',
+  },
+})
+
+const { data, refresh } = await usePublicKql(query)
+
+function updateQuery() {
+  query.value.select.title = 'site.title.upper'
+  refresh()
+}
+</script>
+
+<template>
+  <div>
+    <h1>Fetch Data in Client</h1>
+    <p>
+      Data is being fetched in the client only. This is faster, since the content is<br>
+      fetched directly from your Kirby instance. But more unsafe depending on your usecase, because the authorization data is published in the frontend.
+    </p>
+    <h2>{{ data?.result?.title }}</h2>
+    <h3>Query</h3>
+    <pre>{{ JSON.stringify(query, undefined, 2) }}</pre>
+    <h3>Response</h3>
+    <pre>{{ JSON.stringify(data?.result, undefined, 2) }}</pre>
+    <p>Refreshed: {{ refreshIndex }} times</p>
+    <button @click="refresh(), refreshIndex++">
+      Refresh
+    </button>
+    <button @click="updateQuery()">
+      Change query and refresh
+    </button>
+  </div>
+</template>

playground/pages/index.vue

@@ -1,25 +1,34 @@
 <script setup lang="ts">
+const refreshIndex = ref(0)
 const query = ref({
   query: 'site',
   select: {
     title: 'site.title',
+    children: 'site.children',
   },
 })
 
 const { data, refresh } = await useKql(query)
 
 function updateQuery() {
-  query.value.select = {
-    title: 'site.title.upper',
-  }
+  query.value.select.title = 'site.title.upper'
   refresh()
 }
 </script>
 
 <template>
   <div>
-    <h1>{{ data?.result?.title }}</h1>
+    <h1>Fetch Data Safely</h1>
+    <p>Data is being fetched via a custom Nuxt server route for KQL queries.</p>
+    <h2>{{ data?.result?.title }}</h2>
+    <h3>Query</h3>
+    <pre>{{ JSON.stringify(query, undefined, 2) }}</pre>
+    <h3>Response</h3>
     <pre>{{ JSON.stringify(data?.result, undefined, 2) }}</pre>
+    <p>Refreshed: {{ refreshIndex }} times</p>
+    <button @click="refresh(), refreshIndex++">
+      Refresh
+    </button>
     <button @click="updateQuery()">
       Change query and refresh
     </button>

src/module.ts

@@ -1,26 +1,27 @@
 import { fileURLToPath } from 'url'
+import { join } from 'pathe'
 import { defu } from 'defu'
-import { createResolver, defineNuxtModule } from '@nuxt/kit'
+import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export interface ModuleOptions {
   /**
-   * Kirby API base URL, like `https://kirby.example.com/api`
-   * @default 'process.env.KIRBY_API_URL'
+   * Kirby base URL, like `https://kirby.example.com`
+   * @default 'process.env.KIRBY_BASE_URL'
    */
-  url?: string
+  kirbyUrl?: string
 
   /**
    * Kirby KQL API route path
-   * @default 'query'
+   * @default 'api/query'
    */
-  endpoint?: string
+  kirbyEndpoint?: string
 
   /**
-   * Authentication method
+   * Kirby API authentication method
    * Set to `none` to disable authentication
    * @default 'basic'
    */
-  auth?: 'basic' | 'bearer' | 'none'
+  kirbyAuth?: 'basic' | 'bearer' | 'none'
 
   /**
    * Token for bearer authentication
@@ -36,6 +37,16 @@ export interface ModuleOptions {
     username: string
     password: string
   }
+
+  /**
+   * Enable client-side KQL request
+   * By default, KQL queries are fetched safely for client as well as server via
+   * an internal server API route
+   * If enabled, you can use `usePublicKql()` and `$publicKql()` to fetch data
+   * directly from the Kirby instance
+   * Note: This means your token or user credentials will be publicly visible
+   */
+  clientRequests?: boolean
 }
 
 export default defineNuxtModule<ModuleOptions>({
@@ -47,35 +58,70 @@ export default defineNuxtModule<ModuleOptions>({
     },
   },
   defaults: {
-    url: process.env.KIRBY_API_URL,
-    endpoint: 'query',
-    auth: 'basic',
+    kirbyUrl: process.env.KIRBY_BASE_URL,
+    kirbyEndpoint: 'api/query',
+    kirbyAuth: 'basic',
     token: process.env.KIRBY_API_TOKEN,
     credentials: {
       username: process.env.KIRBY_API_USERNAME,
       password: process.env.KIRBY_API_PASSWORD,
     },
+    clientRequests: false,
   },
   async setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url)
+    const { kirbyUrl, kirbyEndpoint, kirbyAuth, token, credentials, clientRequests } = options
+    const apiRoute = '/api/__kql__' as const
 
-    // Public runtimeConfig
+    // Private runtime config
+    nuxt.options.runtimeConfig.kql = defu(
+      nuxt.options.runtimeConfig.kql,
+      {
+        kirbyUrl,
+        kirbyEndpoint,
+        kirbyAuth,
+        token,
+        credentials,
+        clientRequests,
+      },
+    )
+
+    // Public runtime config
     nuxt.options.runtimeConfig.public.kql = defu(
       nuxt.options.runtimeConfig.public.kql,
       {
-        url: options.url,
-        endpoint: options.endpoint,
-        auth: options.auth,
-        token: options.token,
-        credentials: options.credentials,
+        kirbyUrl,
+        kirbyEndpoint,
+        kirbyAuth,
+        token,
+        credentials,
+        clientRequests,
+
+        // Only used by the module
+        apiRoute,
       },
     )
 
+    // Protect authorization data if no public requests are used
+    if (!clientRequests) {
+      const { kql } = nuxt.options.runtimeConfig.public
+      kql.kirbyUrl = ''
+      kql.kirbyEndpoint = ''
+      kql.kirbyAuth = ''
+      kql.token = ''
+      kql.credentials = { username: '', password: '' }
+    }
+
     const runtimeDir = fileURLToPath(new URL('./runtime', import.meta.url))
     nuxt.options.build.transpile.push(runtimeDir)
 
     nuxt.hook('autoImports:dirs', (dirs) => {
       dirs.push(resolve(runtimeDir, 'composables'))
     })
+
+    addServerHandler({
+      route: apiRoute,
+      handler: join(runtimeDir, 'server/api.ts'),
+    })
   },
 })

src/runtime/composables/kql.ts

@@ -1,52 +1,67 @@
-import type { NitroFetchRequest } from 'nitropack'
-import type { Ref } from 'vue'
-import { computed, unref } from 'vue'
-import type { FetchOptions } from 'ohmyfetch'
-import type { KqlQueryRequest, KqlQueryResponse } from '../types'
-import { getAuthHeaders, normalizeHeaders } from '../utils/headers'
-import type { AsyncData, UseFetchOptions } from '#app'
-import { useFetch, useRuntimeConfig } from '#app'
-
-export function useKql<ResT = KqlQueryResponse, ReqT = KqlQueryRequest>(
-  query: Ref<ReqT> | ReqT | (() => ReqT),
-  opts: Omit<UseFetchOptions<ResT>, 'baseURL' | 'method' | 'body' > = {},
-) {
-  const { public: { kql: { url, endpoint } } } = useRuntimeConfig()
-
-  if (!endpoint)
-    throw new Error('KQL endpoint is not configured')
-
-  const _query = computed(() => {
-    let q = query
-    if (typeof q === 'function')
-      q = (q as (() => ReqT))()
-
-    return unref(q)
-  })
+import { hash as ohash } from 'ohash'
+import type { KqlPrivateFetchOptions, KqlPublicFetchOptions, KqlQueryRequest, KqlQueryResponse } from '../types'
+import { assertKqlPublicConfig, getAuthHeaders, normalizeHeaders } from '../utils'
+import type { ModuleOptions } from '../../module'
+import { useRuntimeConfig } from '#app'
 
-  return useFetch<ResT, Error, NitroFetchRequest, ResT>(endpoint, {
-    ...opts,
-    baseURL: url,
-    method: 'POST',
-    body: _query.value,
-    headers: { ...normalizeHeaders(opts.headers), ...getAuthHeaders() },
-  }) as AsyncData<ResT, true | Error>
+interface InternalState<T> {
+  promiseMap: Map<string, Promise<T>>
 }
 
 export function $kql<T = KqlQueryResponse>(
-  query: T,
-  opts: Omit<FetchOptions, 'baseURL' | 'method' | 'body' > = {},
-) {
-  const { public: { kql: { url, endpoint } } } = useRuntimeConfig()
+  query: KqlQueryRequest,
+  options: KqlPrivateFetchOptions = {},
+): Promise<T> {
+  const { cache = true } = options
+  const { public: { kql } } = useRuntimeConfig()
+
+  const nuxt = useNuxtApp()
+  const queries: Record<string, T> = nuxt.payload.kqlQueries = (nuxt.payload.kqlQueries || {})
+
+  const state = (nuxt.__kql__ || {}) as InternalState<T>
+  state.promiseMap = state.promiseMap || new Map()
+
+  const body = { data: query }
+
+  if (!cache) {
+    return $fetch<T>(kql.apiRoute, {
+      method: 'POST',
+      body,
+    })
+  }
+
+  const key = ohash(query)
+
+  if (key in queries)
+    return Promise.resolve(queries[key])
+
+  if (state.promiseMap.has(key))
+    return state.promiseMap.get(key)
+
+  const request = $fetch<T>(kql.apiRoute, { method: 'POST', body })
+    .then((r) => {
+      queries[key] = r
+      state.promiseMap.delete(key)
+      return r
+    })
+
+  state.promiseMap.set(key, request)
+
+  return request
+}
 
-  if (!endpoint)
-    throw new Error('KQL endpoint is not configured')
+export function $publicKql<T = KqlQueryResponse>(
+  query: KqlQueryRequest,
+  opts: KqlPublicFetchOptions = {},
+): Promise<T> {
+  const { public: { kql } } = useRuntimeConfig()
+  assertKqlPublicConfig(kql as ModuleOptions)
 
-  return $fetch<T>(endpoint, {
+  return $fetch<T>(kql.kirbyEndpoint, {
     ...opts,
-    baseURL: url,
+    baseURL: kql.kirbyUrl,
     method: 'POST',
     body: query,
-    headers: { ...normalizeHeaders(opts.headers), ...getAuthHeaders() },
+    headers: { ...normalizeHeaders(opts.headers), ...getAuthHeaders(kql as ModuleOptions) },
   })
 }