@pikku/core 0.11.2 → 0.12.1

package/src/middleware/cors.test.ts

@@ -0,0 +1,424 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert'
+import { cors } from './cors.js'
+import { resetPikkuState } from '../pikku-state.js'
+
+beforeEach(() => {
+  resetPikkuState()
+})
+
+const createMockRequest = (method = 'get', origin?: string) => ({
+  method: () => method,
+  header: (name: string) => {
+    if (name === 'origin') return origin
+    return undefined
+  },
+})
+
+const createMockResponse = () => {
+  const headers: Record<string, string> = {}
+  let statusCode: number | undefined
+  let jsonBody: any
+  return {
+    header: (name: string, value: string) => {
+      headers[name] = value
+    },
+    status: (code: number) => {
+      statusCode = code
+      return {
+        json: (body: any) => {
+          jsonBody = body
+        },
+      }
+    },
+    json: (body: any) => {
+      jsonBody = body
+    },
+    _headers: headers,
+    _getStatus: () => statusCode,
+    _getJson: () => jsonBody,
+  }
+}
+
+describe('cors', () => {
+  describe('configuration validation', () => {
+    test('should throw when wildcard origin used with credentials', () => {
+      assert.throws(() => cors({ origin: '*', credentials: true }), {
+        message:
+          'CORS misconfiguration: wildcard origin (*) cannot be used with credentials: true',
+      })
+    })
+
+    test('should not throw with wildcard origin and no credentials', () => {
+      const middleware = cors({ origin: '*' })
+      assert.ok(middleware)
+    })
+
+    test('should not throw with specific origin and credentials', () => {
+      const middleware = cors({
+        origin: 'https://example.com',
+        credentials: true,
+      })
+      assert.ok(middleware)
+    })
+
+    test('should not throw with default options', () => {
+      const middleware = cors()
+      assert.ok(middleware)
+    })
+  })
+
+  describe('wildcard origin', () => {
+    test('should set Access-Control-Allow-Origin to * by default', async () => {
+      const middleware = cors()
+      const request = createMockRequest()
+      const response = createMockResponse()
+      let nextCalled = false
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {
+          nextCalled = true
+        }
+      )
+
+      assert.strictEqual(response._headers['Access-Control-Allow-Origin'], '*')
+      assert.strictEqual(nextCalled, true)
+    })
+  })
+
+  describe('single origin', () => {
+    test('should set Access-Control-Allow-Origin to specified origin', async () => {
+      const middleware = cors({ origin: 'https://example.com' })
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Origin'],
+        'https://example.com'
+      )
+    })
+  })
+
+  describe('array of origins', () => {
+    test('should use request origin when it matches array', async () => {
+      const middleware = cors({ origin: ['https://a.com', 'https://b.com'] })
+      const request = createMockRequest('get', 'https://b.com')
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Origin'],
+        'https://b.com'
+      )
+    })
+
+    test('should use first origin when request origin not in array', async () => {
+      const middleware = cors({ origin: ['https://a.com', 'https://b.com'] })
+      const request = createMockRequest('get', 'https://unknown.com')
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Origin'],
+        'https://a.com'
+      )
+    })
+
+    test('should use first origin when no request origin header', async () => {
+      const middleware = cors({ origin: ['https://a.com', 'https://b.com'] })
+      const request = createMockRequest('get')
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Origin'],
+        'https://a.com'
+      )
+    })
+
+    test('should set Vary: Origin header when origin is array', async () => {
+      const middleware = cors({ origin: ['https://a.com', 'https://b.com'] })
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(response._headers['Vary'], 'Origin')
+    })
+  })
+
+  describe('headers', () => {
+    test('should set default allowed methods', async () => {
+      const middleware = cors()
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Methods'],
+        'GET, POST, PUT, PATCH, DELETE, OPTIONS'
+      )
+    })
+
+    test('should set default allowed headers', async () => {
+      const middleware = cors()
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Headers'],
+        'Content-Type, Authorization, x-api-key'
+      )
+    })
+
+    test('should set custom methods', async () => {
+      const middleware = cors({ methods: ['GET', 'POST'] })
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Methods'],
+        'GET, POST'
+      )
+    })
+
+    test('should set custom headers', async () => {
+      const middleware = cors({ headers: ['X-Custom'] })
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Headers'],
+        'X-Custom'
+      )
+    })
+
+    test('should not set Vary when origin is string', async () => {
+      const middleware = cors({ origin: 'https://example.com' })
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(response._headers['Vary'], undefined)
+    })
+  })
+
+  describe('credentials', () => {
+    test('should set Access-Control-Allow-Credentials when enabled', async () => {
+      const middleware = cors({
+        origin: 'https://example.com',
+        credentials: true,
+      })
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Credentials'],
+        'true'
+      )
+    })
+
+    test('should not set credentials header when disabled', async () => {
+      const middleware = cors({ credentials: false })
+      const request = createMockRequest()
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(
+        response._headers['Access-Control-Allow-Credentials'],
+        undefined
+      )
+    })
+  })
+
+  describe('OPTIONS preflight', () => {
+    test('should return 204 for OPTIONS requests', async () => {
+      const middleware = cors()
+      const request = createMockRequest('options')
+      const response = createMockResponse()
+      let nextCalled = false
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {
+          nextCalled = true
+        }
+      )
+
+      assert.strictEqual(response._getStatus(), 204)
+      assert.strictEqual(nextCalled, false)
+    })
+
+    test('should set Access-Control-Max-Age for OPTIONS', async () => {
+      const middleware = cors({ maxAge: 3600 })
+      const request = createMockRequest('options')
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(response._headers['Access-Control-Max-Age'], '3600')
+    })
+
+    test('should use default maxAge of 86400', async () => {
+      const middleware = cors()
+      const request = createMockRequest('options')
+      const response = createMockResponse()
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {}
+      )
+
+      assert.strictEqual(response._headers['Access-Control-Max-Age'], '86400')
+    })
+
+    test('should call next for non-OPTIONS requests', async () => {
+      const middleware = cors()
+      const request = createMockRequest('get')
+      const response = createMockResponse()
+      let nextCalled = false
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {
+          nextCalled = true
+        }
+      )
+
+      assert.strictEqual(nextCalled, true)
+    })
+
+    test('should call next for POST requests', async () => {
+      const middleware = cors()
+      const request = createMockRequest('post')
+      const response = createMockResponse()
+      let nextCalled = false
+
+      await middleware(
+        {} as any,
+        { http: { request, response } } as any,
+        async () => {
+          nextCalled = true
+        }
+      )
+
+      assert.strictEqual(nextCalled, true)
+    })
+  })
+
+  describe('missing http', () => {
+    test('should call next when no request', async () => {
+      const middleware = cors()
+      let nextCalled = false
+
+      await middleware(
+        {} as any,
+        { http: { response: createMockResponse() } } as any,
+        async () => {
+          nextCalled = true
+        }
+      )
+
+      assert.strictEqual(nextCalled, true)
+    })
+
+    test('should call next when no response', async () => {
+      const middleware = cors()
+      let nextCalled = false
+
+      await middleware(
+        {} as any,
+        { http: { request: createMockRequest() } } as any,
+        async () => {
+          nextCalled = true
+        }
+      )
+
+      assert.strictEqual(nextCalled, true)
+    })
+
+    test('should call next when no http', async () => {
+      const middleware = cors()
+      let nextCalled = false
+
+      await middleware({} as any, {} as any, async () => {
+        nextCalled = true
+      })
+
+      assert.strictEqual(nextCalled, true)
+    })
+  })
+})

package/src/middleware/cors.ts

@@ -0,0 +1,104 @@
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
+
+/**
+ * CORS middleware that handles cross-origin requests including OPTIONS preflight.
+ *
+ * Sets appropriate CORS headers on all responses and short-circuits OPTIONS
+ * preflight requests with a 204 No Content response.
+ *
+ * @param options.origin - Allowed origin(s). Use `'*'` for any origin, `true` to reflect the request origin, a string for a single origin, or an array for multiple origins. Defaults to `'*'`.
+ * @param options.methods - Allowed HTTP methods. Defaults to common methods.
+ * @param options.headers - Allowed request headers. Defaults to common headers.
+ * @param options.credentials - Whether to allow credentials. Defaults to `false`.
+ * @param options.maxAge - Preflight cache duration in seconds. Defaults to `86400` (24 hours).
+ *
+ * @example
+ * ```typescript
+ * import { cors } from '@pikku/core/middleware'
+ *
+ * // Allow all origins
+ * addHTTPMiddleware('*', [cors()])
+ *
+ * // Specific origin with credentials
+ * addHTTPMiddleware('*', [
+ *   cors({
+ *     origin: 'https://app.example.com',
+ *     credentials: true,
+ *   })
+ * ])
+ *
+ * // Multiple origins
+ * addHTTPMiddleware('*', [
+ *   cors({
+ *     origin: ['https://app.example.com', 'https://admin.example.com'],
+ *   })
+ * ])
+ * ```
+ */
+export const cors = pikkuMiddlewareFactory<{
+  origin?: string | string[] | true
+  methods?: string[]
+  headers?: string[]
+  credentials?: boolean
+  maxAge?: number
+}>(
+  ({
+    origin = '*',
+    methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+    headers = ['Content-Type', 'Authorization', 'x-api-key'],
+    credentials = false,
+    maxAge = 86400,
+  } = {}) => {
+    if (origin === '*' && credentials) {
+      throw new Error(
+        'CORS misconfiguration: wildcard origin (*) cannot be used with credentials: true'
+      )
+    }
+    return pikkuMiddleware({
+      name: 'CORS',
+      description: 'Handles cross-origin requests including OPTIONS preflight',
+      func: async (_services, wires, next) => {
+        const request = wires.http?.request
+        const response = wires.http?.response
+
+        if (!request || !response) {
+          return next()
+        }
+
+        const requestOrigin = request.header('origin')
+
+        let allowedOrigin: string
+        if (origin === true) {
+          allowedOrigin = requestOrigin || '*'
+        } else if (Array.isArray(origin)) {
+          allowedOrigin =
+            requestOrigin && origin.includes(requestOrigin)
+              ? requestOrigin
+              : origin[0]
+        } else {
+          allowedOrigin = origin
+        }
+
+        response.header('Access-Control-Allow-Origin', allowedOrigin)
+        response.header('Access-Control-Allow-Methods', methods.join(', '))
+        response.header('Access-Control-Allow-Headers', headers.join(', '))
+
+        if (credentials) {
+          response.header('Access-Control-Allow-Credentials', 'true')
+        }
+
+        if (origin === true || Array.isArray(origin)) {
+          response.header('Vary', 'Origin')
+        }
+
+        if (request.method() === 'options') {
+          response.header('Access-Control-Max-Age', String(maxAge))
+          response.status(204).json(undefined as any)
+          return
+        }
+
+        return next()
+      },
+    })
+  }
+)

package/src/middleware/index.ts

@@ -1,3 +1,5 @@
-export * from './auth-apikey.js'
-export * from './auth-cookie.js'
-export * from './auth-bearer.js'
+export { authAPIKey } from './auth-apikey.js'
+export { authCookie } from './auth-cookie.js'
+export { authBearer } from './auth-bearer.js'
+export { pikkuRemoteAuthMiddleware } from './remote-auth.js'
+export { cors } from './cors.js'