@norriq/nuxt-api-proxy 1.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 NORRIQ. All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary property of NORRIQ. Unauthorized use, copying, modification,
+distribution, or any other exploitation of the Software, in whole or in part,
+is strictly prohibited without the prior written consent of NORRIQ.
+
+For licensing inquiries, contact: info@norriq.com

package/README.md

@@ -0,0 +1,33 @@
+# @norriq/nuxt-api-proxy
+
+Nuxt layer that adds a catch-all `/api/proxy/*` server route. Forwards requests to a backend API with the user's auth token automatically injected.
+
+Supports multipart uploads, binary responses, and distributed tracing (traceparent header forwarding).
+
+## Usage
+
+Requires `@norriq/nuxt-auth` (or `@sidebase/nuxt-auth`) to be configured in the consuming app — the proxy reads the session token from the auth module.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@norriq/nuxt-auth', '@norriq/nuxt-api-proxy'],
+})
+```
+
+## Environment variables
+
+| Variable | Scope | Required | Description |
+|----------|-------|----------|-------------|
+| `NUXT_API_URI` | Server | Yes | Target API base URL |
+| `NUXT_PUBLIC_API_URI` | Public | No | Fallback if `NUXT_API_URI` not set |
+
+## How it works
+
+All requests to `/api/proxy/*` are forwarded to the target API:
+
+- HTTP method, headers, query params, and body are preserved
+- `Authorization: Bearer <token>` is injected from the user's session
+- Multipart uploads are detected and forwarded as binary
+- JSON responses are parsed; binary responses are streamed through
+- `traceparent` header is forwarded for distributed tracing

package/nuxt.config.ts

@@ -0,0 +1,5 @@
+export default defineNuxtConfig({
+    runtimeConfig: {
+        apiUri: '', // Backend API URL (server-only, set via NUXT_API_URI)
+    },
+})

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@norriq/nuxt-api-proxy",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "exports": {
+    ".": "./nuxt.config.ts"
+  },
+  "files": [
+    "nuxt.config.ts",
+    "server"
+  ],
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "nuxt": ">=3.0.0",
+    "@sidebase/nuxt-auth": ">=1.0.0"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/server/api/proxy/[...path].ts

@@ -0,0 +1,92 @@
+import { getToken } from '#auth'
+
+export default defineEventHandler(async (event) => {
+    const config = useRuntimeConfig()
+    // Server-only NUXT_API_URI, falls back to NUXT_PUBLIC_API_URI for backward compatibility
+    const apiTarget = String(config.apiUri || config.public.apiUri || '')
+
+    if (!apiTarget) {
+        setResponseStatus(event, 500)
+        return { message: 'API proxy target not configured (set NUXT_API_URI)' }
+    }
+
+    // Auth: read token from httpOnly session cookie
+    const token = await getToken({ event })
+    const rawToken = token?.impersonateToken || token?.accessToken
+    const accessToken = typeof rawToken === 'string' ? rawToken : undefined
+
+    // Reconstruct target URL
+    const path = getRouterParam(event, 'path') ?? ''
+    const query = getQuery(event)
+    const qs = new URLSearchParams(
+        Object.fromEntries(Object.entries(query).map(([k, v]) => [k, String(v)]))
+    ).toString()
+    const targetUrl = `${apiTarget}/${path}${qs ? `?${qs}` : ''}`
+
+    // Detect request mode from content-type
+    const requestContentType = getRequestHeader(event, 'content-type') || ''
+    const isMultipartUpload = requestContentType.startsWith('multipart/')
+
+    const method = event.method
+    const headers: Record<string, string> = {}
+
+    // Read request body
+    let body: BodyInit | undefined
+    if (isMultipartUpload) {
+        // Raw buffer preserves binary/multipart integrity
+        body = (await readRawBody(event, false)) as BodyInit | undefined
+        headers['Content-Type'] = requestContentType
+    } else if (['POST', 'PUT', 'PATCH'].includes(method)) {
+        body = (await readRawBody(event)) as BodyInit | undefined
+        headers['Content-Type'] = 'application/json'
+    }
+
+    if (accessToken) headers['Authorization'] = `Bearer ${accessToken}`
+
+    // Forward APM traceparent for distributed tracing
+    try {
+        const apm = await import('elastic-apm-node').then((m) => m.default)
+        const traceparent = apm.currentTransaction?.traceparent
+        if (traceparent) headers['traceparent'] = traceparent
+    } catch {
+        // APM not available
+    }
+
+    try {
+        // Multipart uploads need native fetch to avoid body corruption
+        if (isMultipartUpload) {
+            const response = await fetch(targetUrl, { method, headers, body })
+            setResponseStatus(event, response.status)
+            const data = await response.json().catch(() => null)
+            return data
+        }
+
+        // Use native fetch for all requests so we can inspect the response
+        // content-type before deciding how to return the body
+        const response = await fetch(targetUrl, { method, headers, body })
+        setResponseStatus(event, response.status)
+
+        const responseContentType = response.headers.get('content-type') || ''
+
+        // Binary response: stream body back with original headers
+        if (response.ok && !responseContentType.includes('application/json')) {
+            const contentDisposition = response.headers.get('content-disposition')
+            if (responseContentType) setResponseHeader(event, 'content-type', responseContentType)
+            if (contentDisposition) setResponseHeader(event, 'content-disposition', contentDisposition)
+            return response.body
+        }
+
+        // JSON response (or error): parse and return
+        const data = await response.json().catch(() => null)
+
+        if (import.meta.dev && response.status >= 400) {
+            console.log(`[api-proxy] ${method} ${response.status} ${targetUrl}`)
+        }
+
+        return data
+    } catch (err) {
+        console.error('[api-proxy] Proxy error:', err)
+        setResponseStatus(event, 502)
+        return { message: 'Proxy error', error: String(err) }
+    }
+})

package/server/api/proxy/proxy.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { EventHandler } from 'h3'
+import { fakeEvent, fetchCallUrl, fetchCallHeaders } from '../../test-helpers'
+
+const mockGetToken = vi.fn()
+
+vi.mock('#auth', () => ({
+    getToken: (...args: unknown[]) => mockGetToken(...args),
+}))
+
+let capturedConfig = {
+    apiUri: 'https://api.example.com',
+    public: { apiUri: '' },
+}
+
+let mockPath = 'users/123'
+let mockQuery: Record<string, string> = {}
+let mockHeaders: Record<string, string> = {}
+
+vi.stubGlobal('defineEventHandler', <T>(fn: T): T => fn)
+vi.stubGlobal('useRuntimeConfig', () => capturedConfig)
+vi.stubGlobal('getRouterParam', (_event: unknown, param: string) => {
+    if (param === 'path') return mockPath
+    return undefined
+})
+vi.stubGlobal('getQuery', () => mockQuery)
+vi.stubGlobal('getRequestHeader', (_event: unknown, header: string) => {
+    return mockHeaders[header.toLowerCase()]
+})
+vi.stubGlobal('setResponseStatus', vi.fn())
+vi.stubGlobal('setResponseHeader', vi.fn())
+vi.stubGlobal('readRawBody', vi.fn().mockResolvedValue('{"key":"value"}'))
+
+const mockFetch = vi.fn()
+vi.stubGlobal('fetch', mockFetch)
+
+function jsonResponse(status: number, data: unknown, headers: Record<string, string> = {}) {
+    return {
+        status,
+        ok: status >= 200 && status < 300,
+        headers: new Headers({ 'content-type': 'application/json', ...headers }),
+        json: () => Promise.resolve(data),
+    }
+}
+
+describe('api-proxy handler', () => {
+    let handler: EventHandler
+
+    beforeEach(async () => {
+        vi.clearAllMocks()
+        mockPath = 'users/123'
+        mockQuery = {}
+        mockHeaders = {}
+        capturedConfig = {
+            apiUri: 'https://api.example.com',
+            public: { apiUri: '' },
+        }
+
+        vi.resetModules()
+        const mod = await import('./[...path]')
+        handler = mod.default
+    })
+
+    it('returns 500 when API target is not configured', async () => {
+        capturedConfig = { apiUri: '', public: { apiUri: '' } }
+
+        const result = await handler(fakeEvent())
+
+        expect(result).toEqual({ message: 'API proxy target not configured (set NUXT_API_URI)' })
+        expect(setResponseStatus).toHaveBeenCalledWith(fakeEvent(), 500)
+    })
+
+    it('forwards GET request to target URL', async () => {
+        mockGetToken.mockResolvedValue({ accessToken: 'test-token' })
+        mockFetch.mockResolvedValue(jsonResponse(200, { data: 'response' }))
+
+        const result = await handler(fakeEvent())
+
+        expect(mockFetch).toHaveBeenCalledWith(
+            'https://api.example.com/users/123',
+            expect.objectContaining({
+                method: 'GET',
+                headers: expect.objectContaining({ Authorization: 'Bearer test-token' }),
+            })
+        )
+        expect(result).toEqual({ data: 'response' })
+    })
+
+    it('appends query string to target URL', async () => {
+        mockQuery = { page: '2', limit: '10' }
+        mockGetToken.mockResolvedValue({ accessToken: 'tok' })
+        mockFetch.mockResolvedValue(jsonResponse(200, {}))
+
+        await handler(fakeEvent())
+
+        const url = fetchCallUrl(mockFetch)
+        expect(url).toContain('page=2')
+        expect(url).toContain('limit=10')
+    })
+
+    it('uses impersonateToken over accessToken when present', async () => {
+        mockGetToken.mockResolvedValue({ accessToken: 'user-token', impersonateToken: 'admin-token' })
+        mockFetch.mockResolvedValue(jsonResponse(200, {}))
+
+        await handler(fakeEvent())
+
+        expect(fetchCallHeaders(mockFetch)['Authorization']).toBe('Bearer admin-token')
+    })
+
+    it('does not set Authorization header when no token exists', async () => {
+        mockGetToken.mockResolvedValue(null)
+        mockFetch.mockResolvedValue(jsonResponse(200, {}))
+
+        await handler(fakeEvent())
+
+        expect(fetchCallHeaders(mockFetch)['Authorization']).toBeUndefined()
+    })
+
+    it('forwards POST body as JSON', async () => {
+        mockGetToken.mockResolvedValue(null)
+        mockFetch.mockResolvedValue(jsonResponse(201, { id: 1 }))
+
+        await handler(fakeEvent('POST'))
+
+        expect(mockFetch).toHaveBeenCalledWith(
+            expect.any(String),
+            expect.objectContaining({
+                method: 'POST',
+                headers: expect.objectContaining({ 'Content-Type': 'application/json' }),
+                body: '{"key":"value"}',
+            })
+        )
+    })
+
+    it('detects multipart uploads and preserves content-type', async () => {
+        mockHeaders = { 'content-type': 'multipart/form-data; boundary=----abc' }
+        mockGetToken.mockResolvedValue(null)
+        mockFetch.mockResolvedValue({ status: 200, json: () => Promise.resolve({ uploaded: true }) })
+
+        await handler(fakeEvent('POST'))
+
+        expect(fetchCallHeaders(mockFetch)['Content-Type']).toBe('multipart/form-data; boundary=----abc')
+    })
+
+    it('streams binary responses with correct headers', async () => {
+        mockGetToken.mockResolvedValue({ accessToken: 'tok' })
+        const mockBody = new ReadableStream()
+        mockFetch.mockResolvedValue({
+            status: 200,
+            ok: true,
+            headers: new Headers({
+                'content-type': 'application/pdf',
+                'content-disposition': 'attachment; filename="report.pdf"',
+            }),
+            body: mockBody,
+        })
+
+        const event = fakeEvent()
+        const result = await handler(event)
+
+        expect(result).toBe(mockBody)
+        expect(setResponseHeader).toHaveBeenCalledWith(event, 'content-type', 'application/pdf')
+        expect(setResponseHeader).toHaveBeenCalledWith(event, 'content-disposition', 'attachment; filename="report.pdf"')
+    })
+
+    it('returns 502 on fetch error', async () => {
+        mockGetToken.mockResolvedValue(null)
+        mockFetch.mockRejectedValue(new Error('ECONNREFUSED'))
+
+        const event = fakeEvent()
+        const result = await handler(event)
+
+        expect(setResponseStatus).toHaveBeenCalledWith(event, 502)
+        expect(result).toEqual({ message: 'Proxy error', error: 'Error: ECONNREFUSED' })
+    })
+
+    it('falls back to public apiUri when server apiUri is not set', async () => {
+        capturedConfig = { apiUri: '', public: { apiUri: 'https://public-api.example.com' } }
+        mockGetToken.mockResolvedValue(null)
+        mockFetch.mockResolvedValue(jsonResponse(200, {}))
+
+        await handler(fakeEvent())
+
+        expect(fetchCallUrl(mockFetch).startsWith('https://public-api.example.com/')).toBe(true)
+    })
+
+    it('forwards upstream status code', async () => {
+        mockGetToken.mockResolvedValue(null)
+        mockFetch.mockResolvedValue(jsonResponse(404, { error: 'Not found' }))
+
+        const event = fakeEvent()
+        const result = await handler(event)
+
+        expect(setResponseStatus).toHaveBeenCalledWith(event, 404)
+        expect(result).toEqual({ error: 'Not found' })
+    })
+})

package/server/test-helpers.ts

@@ -0,0 +1,14 @@
+import { vi } from 'vitest'
+import type { H3Event } from 'h3'
+
+export function fakeEvent(method = 'GET'): H3Event {
+    return { method } as H3Event
+}
+
+export function fetchCallUrl(mock: ReturnType<typeof vi.fn>): string {
+    return mock.mock.calls[0][0]
+}
+
+export function fetchCallHeaders(mock: ReturnType<typeof vi.fn>): Record<string, string> {
+    return mock.mock.calls[0][1].headers
+}