(cacheAction, null);
+
+ return
+
+
+
+
+
+
+
+
+ ;
+}
diff --git a/tests/fixtures/next-app/app/layout.tsx b/tests/fixtures/next-app/app/layout.tsx
new file mode 100644
index 0000000..0e3f772
--- /dev/null
+++ b/tests/fixtures/next-app/app/layout.tsx
@@ -0,0 +1,3 @@
+export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+ return {children};
+}
diff --git a/tests/fixtures/next-app/app/page.tsx b/tests/fixtures/next-app/app/page.tsx
new file mode 100644
index 0000000..81042f5
--- /dev/null
+++ b/tests/fixtures/next-app/app/page.tsx
@@ -0,0 +1,12 @@
+import { api } from '../lib/api';
+import { ClientHarness } from './client-harness';
+
+export const dynamic = 'force-dynamic';
+
+export default async function Page() {
+ const serverComponentResult = await api.get('/rotate', { operationName: 'e2e.server-component' });
+ return <>
+ {JSON.stringify(serverComponentResult)}
+
+ ;
+}
diff --git a/tests/fixtures/next-app/lib/api.ts b/tests/fixtures/next-app/lib/api.ts
new file mode 100644
index 0000000..00e0c2a
--- /dev/null
+++ b/tests/fixtures/next-app/lib/api.ts
@@ -0,0 +1,22 @@
+import { createNextApiBridge } from 'next-api-bridge';
+
+const baseUrl = process.env.API_URL!;
+
+export const api = createNextApiBridge({ baseUrl });
+
+export const trustedApi = createNextApiBridge({
+ baseUrl,
+ requestContext: {
+ clientIp: { enabled: true, trustProxy: 'cloudflare' },
+ },
+});
+
+export const originApi = createNextApiBridge({
+ baseUrl,
+ requestContext: {
+ clientOrigin: {
+ enabled: true,
+ allowedHosts: ['127.0.0.1', 'localhost'],
+ },
+ },
+});
diff --git a/tests/fixtures/next-app/next-env.d.ts b/tests/fixtures/next-app/next-env.d.ts
new file mode 100644
index 0000000..6080add
--- /dev/null
+++ b/tests/fixtures/next-app/next-env.d.ts
@@ -0,0 +1,2 @@
+///
+///
diff --git a/tests/fixtures/next-app/next.config.mjs b/tests/fixtures/next-app/next.config.mjs
new file mode 100644
index 0000000..b50b442
--- /dev/null
+++ b/tests/fixtures/next-app/next.config.mjs
@@ -0,0 +1,5 @@
+/** @type {import('next').NextConfig} */
+const config = {
+ reactStrictMode: true,
+};
+export default config;
diff --git a/tests/fixtures/next-app/package.json b/tests/fixtures/next-app/package.json
new file mode 100644
index 0000000..0772e9e
--- /dev/null
+++ b/tests/fixtures/next-app/package.json
@@ -0,0 +1,9 @@
+{
+ "name": "next-api-bridge-e2e-fixture",
+ "private": true,
+ "type": "module",
+ "scripts": {
+ "build": "next build",
+ "start": "next start"
+ }
+}
diff --git a/tests/fixtures/next-app/playwright.config.mjs b/tests/fixtures/next-app/playwright.config.mjs
new file mode 100644
index 0000000..d02949e
--- /dev/null
+++ b/tests/fixtures/next-app/playwright.config.mjs
@@ -0,0 +1,17 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+ testDir: './tests',
+ timeout: 60_000,
+ use: {
+ baseURL: process.env.NEXT_APP_URL ?? 'http://127.0.0.1:3100',
+ userAgent: 'next-api-bridge-e2e-browser/1.0',
+ locale: 'en-KE',
+ extraHTTPHeaders: {
+ 'x-request-id': 'browser-request-id',
+ 'cf-connecting-ip': '203.0.113.42',
+ 'x-forwarded-for': '198.51.100.99',
+ traceparent: '00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01'
+ }
+ }
+});
diff --git a/tests/fixtures/next-app/tests/bridge.spec.mjs b/tests/fixtures/next-app/tests/bridge.spec.mjs
new file mode 100644
index 0000000..4330d73
--- /dev/null
+++ b/tests/fixtures/next-app/tests/bridge.spec.mjs
@@ -0,0 +1,101 @@
+import { expect, test } from '@playwright/test';
+
+async function submitAndRead(page, buttonId, resultId) {
+ const result = page.getByTestId(resultId);
+ const previous = await result.textContent();
+ await page.getByTestId(buttonId).click();
+ await expect.poll(async () => result.textContent()).not.toBe(previous);
+ const text = await result.textContent();
+ if (!text || text === 'null') throw new Error(`No result produced for ${buttonId}`);
+ return JSON.parse(text);
+}
+
+test.beforeEach(async ({ page }) => {
+ await page.goto('/');
+});
+
+test('Server Component reports read-only cookie synchronization', async ({ page }) => {
+ const result = JSON.parse(await page.getByTestId('server-component-sync').textContent());
+ expect(result.cookieSync).toEqual({ attempted: true, applied: false, reason: 'read-only-context' });
+ expect(result.headers).not.toHaveProperty('set-cookie');
+});
+
+test('useActionState consumes serializable login response and cookie policy is enforced', async ({ page, context }) => {
+ const result = await submitAndRead(page, 'login', 'login-result');
+ expect(result.status).toBe(200);
+ expect(result.success).toBe(true);
+ expect(result.headers).toEqual({ 'x-request-id': 'browser-request-id' });
+ expect(JSON.stringify(result)).not.toContain('Set-Cookie');
+ expect(JSON.stringify(result)).not.toContain('login-session');
+
+ const cookies = await context.cookies();
+ const session = cookies.find((cookie) => cookie.name === 'nab_session');
+ const unrelated = cookies.find((cookie) => cookie.name === 'app_theme');
+ expect(session).toBeTruthy();
+ expect(session.value).toBe('login-session');
+ expect(session.path).toBe('/');
+ expect(session.domain).toBe('127.0.0.1');
+ expect(session.expires).toBeGreaterThan(Date.now() / 1000);
+ expect(unrelated?.value).toBe('dark');
+});
+
+test('rotated authentication cookies persist from a Server Action', async ({ page, context }) => {
+ await submitAndRead(page, 'login', 'login-result');
+ const result = await submitAndRead(page, 'rotate', 'rotate-result');
+ expect(result.cookieSync).toEqual({ attempted: true, applied: true, reason: 'applied' });
+ const session = (await context.cookies()).find((cookie) => cookie.name === 'nab_session');
+ expect(session?.value).toBe('rotated-session');
+ expect(session?.path).toBe('/');
+});
+
+test('browser context is forwarded safely while spoofed IP is ignored by default', async ({ page }) => {
+ const result = await submitAndRead(page, 'inspect', 'inspect-result');
+ expect(result.body.userAgent).toContain('next-api-bridge-e2e-browser/1.0');
+ expect(result.body.acceptLanguage.toLowerCase()).toContain('en-ke');
+ expect(result.body.traceparent).toBe('00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01');
+ expect(result.body.requestId).toBe('browser-request-id');
+ expect(result.body.bridge).toBe('next-api-bridge/0.1.7');
+ expect(result.body.clientIp).toBeNull();
+ expect(result.body.query).toEqual({ active: 'false', page: '0', search: '' });
+ expect(JSON.stringify(result.body.query)).not.toMatch(/undefined|null/);
+});
+
+test('trusted client IP and approved client origin are forwarded explicitly', async ({ page }) => {
+ const trusted = await submitAndRead(page, 'trusted', 'trusted-result');
+ expect(trusted.body.clientIp).toBe('203.0.113.42');
+
+ const origin = await submitAndRead(page, 'origin', 'origin-result');
+ expect(origin.body.clientOrigin).toMatch(/^http:\/\/127\.0\.0\.1:3100$/);
+});
+
+test('HTTP status codes and empty responses remain distinguishable', async ({ page }) => {
+ for (const status of [401, 403, 404, 409, 422, 429, 500]) {
+ await page.getByTestId('status-input').fill(String(status));
+ const result = await submitAndRead(page, 'status', 'status-result');
+ expect(result.status).toBe(status);
+ expect(result.body.status).toBe(status);
+ expect(result.headers).not.toHaveProperty('set-cookie');
+ }
+
+ const empty = await submitAndRead(page, 'empty', 'empty-result');
+ expect(empty.status).toBe(204);
+ expect(empty.body).toBeNull();
+ expect(empty.errorCode).toBeUndefined();
+});
+
+test('force-cache reuses backend data and no-store stays fresh', async ({ page }) => {
+ const result = await submitAndRead(page, 'cache', 'cache-result');
+ expect(result.forceOne.body.count).toBe(result.forceTwo.body.count);
+ expect(result.freshTwo.body.count).toBe(result.freshOne.body.count + 1);
+});
+
+test('Server Action responses contain plain records and no transport secrets', async ({ page }) => {
+ const result = await submitAndRead(page, 'inspect', 'inspect-result');
+ expect(Object.getPrototypeOf(result.headers)).toBe(Object.prototype);
+ const serialized = JSON.stringify(result);
+ expect(result.headers).not.toHaveProperty('authorization');
+ expect(result.headers).not.toHaveProperty('cookie');
+ expect(result.headers).not.toHaveProperty('set-cookie');
+ expect(serialized).not.toContain('login-session');
+ expect(serialized).not.toContain('rotated-session');
+});
diff --git a/tests/fixtures/next-app/tsconfig.json b/tests/fixtures/next-app/tsconfig.json
new file mode 100644
index 0000000..a0533d6
--- /dev/null
+++ b/tests/fixtures/next-app/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "ES2017",
+ "lib": ["dom", "dom.iterable", "esnext"],
+ "allowJs": false,
+ "skipLibCheck": true,
+ "strict": true,
+ "noEmit": true,
+ "esModuleInterop": true,
+ "module": "esnext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "jsx": "preserve",
+ "incremental": true,
+ "plugins": [{ "name": "next" }]
+ },
+ "include": ["next-env.d.ts", ".next/types/**/*.ts", "**/*.ts", "**/*.tsx"],
+ "exclude": ["node_modules"]
+}
diff --git a/tests/integration/bridge.test.cjs b/tests/integration/bridge.test.cjs
new file mode 100644
index 0000000..563135c
--- /dev/null
+++ b/tests/integration/bridge.test.cjs
@@ -0,0 +1,220 @@
+const assert = require('node:assert/strict');
+const http = require('node:http');
+const test = require('node:test');
+const testing = require('../../.test-dist/testing.js');
+
+class MemoryCookies {
+ constructor(values = {}) {
+ this.values = new Map(Object.entries(values));
+ this.writes = [];
+ this.deletes = [];
+ }
+ get(name) {
+ const value = this.values.get(name);
+ return value === undefined ? undefined : { name, value };
+ }
+ getAll() {
+ return Array.from(this.values, ([name, value]) => ({ name, value }));
+ }
+ set(name, value, options = {}) {
+ this.values.set(name, value);
+ this.writes.push({ name, value, options });
+ }
+ delete(name) {
+ this.values.delete(name);
+ this.deletes.push(name);
+ }
+}
+
+let server;
+let baseUrl;
+let lastRequest;
+
+function readBody(req) {
+ return new Promise((resolve) => {
+ let body = '';
+ req.setEncoding('utf8');
+ req.on('data', (chunk) => body += chunk);
+ req.on('end', () => resolve(body));
+ });
+}
+
+test.before(async () => {
+ server = http.createServer(async (req, res) => {
+ const body = await readBody(req);
+ const route = req.url.replace(/^\/v1/, '') || '/';
+ lastRequest = { method: req.method, url: route, headers: req.headers, body };
+ if (route.startsWith('/empty')) {
+ res.statusCode = 204;
+ res.end();
+ return;
+ }
+ if (route.startsWith('/text')) {
+ res.setHeader('content-type', 'text/plain');
+ res.end('plain response');
+ return;
+ }
+ if (route.startsWith('/status/')) {
+ const status = Number(route.split('/').pop());
+ res.statusCode = status;
+ res.setHeader('content-type', 'application/json');
+ res.setHeader('x-request-id', 'backend-request');
+ res.setHeader('x-ratelimit-remaining', '4');
+ res.setHeader('set-cookie', 'rotated=secret; Path=/api; Domain=backend.invalid; Expires=Wed, 21 Oct 2030 07:28:00 GMT; HttpOnly');
+ res.end(JSON.stringify({ success: false, message: `status-${status}`, status }));
+ return;
+ }
+ res.setHeader('content-type', 'application/json');
+ res.setHeader('x-request-id', req.headers['x-request-id'] || 'generated-backend');
+ res.end(JSON.stringify({
+ success: true,
+ message: 'ok',
+ method: req.method,
+ url: route,
+ }));
+ });
+ await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+ baseUrl = `http://127.0.0.1:${server.address().port}/v1`;
+});
+
+test.after(async () => {
+ await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+});
+
+async function request({ options = {}, incoming = {}, cookies = {}, path = '/echo', method = 'GET', body, requestOptions = {} } = {}) {
+ const cookieStore = new MemoryCookies(cookies);
+ const normalizedOptions = testing.validateAndNormalizeOptions({ baseUrl, ...options });
+ const response = await testing.executeBridgeRequest({
+ normalizedOptions,
+ method,
+ path,
+ body,
+ requestOptions,
+ cookieStore,
+ incomingHeaders: new Headers(incoming),
+ });
+ return { response, cookieStore };
+}
+
+test('cookie forwarding uses only the configured prefix and bearer/API-key auth still work', async () => {
+ const { response } = await request({
+ options: {
+ cookiePrefix: 'bridge_',
+ auth: { type: 'bearer', tokenCookie: 'accessToken' },
+ apiKey: 'api-secret',
+ apiKeyHeader: 'x-api-key',
+ },
+ cookies: {
+ bridge_accessToken: 'bearer-secret',
+ bridge_session: 'backend-session',
+ application_cookie: 'must-not-forward',
+ },
+ });
+ assert.equal(response.status, 200);
+ assert.equal(lastRequest.headers.cookie, 'accessToken=bearer-secret; session=backend-session');
+ assert.equal(lastRequest.headers.authorization, 'Bearer bearer-secret');
+ assert.equal(lastRequest.headers['x-api-key'], 'api-secret');
+ assert.doesNotMatch(lastRequest.headers.cookie, /application_cookie/);
+ assert.equal(JSON.stringify(response).includes('bearer-secret'), false);
+});
+
+test('browser context headers and request IDs reach the backend', async () => {
+ const { response } = await request({
+ incoming: {
+ 'user-agent': 'Integration Browser/1.0',
+ 'accept-language': 'en-KE,en;q=0.9',
+ traceparent: '00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01',
+ 'x-request-id': 'incoming-request-id',
+ },
+ });
+ assert.equal(lastRequest.headers['user-agent'], 'Integration Browser/1.0');
+ assert.equal(lastRequest.headers['accept-language'], 'en-KE,en;q=0.9');
+ assert.equal(lastRequest.headers.traceparent, '00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-bbbbbbbbbbbbbbbb-01');
+ assert.equal(lastRequest.headers['x-request-id'], 'incoming-request-id');
+ assert.equal(lastRequest.headers['x-api-bridge'], 'next-api-bridge/0.1.7');
+
+ const generated = await request();
+ assert.match(lastRequest.headers['x-request-id'], /^[0-9a-f-]{36}$/i);
+});
+
+test('client IP is absent by default and only present for configured trusted providers', async () => {
+ const absent = await request({ incoming: { 'x-forwarded-for': '203.0.113.5', 'cf-connecting-ip': '203.0.113.6' } });
+ assert.equal(lastRequest.headers['x-client-ip'], undefined);
+
+ const cloudflare = await request({
+ options: { requestContext: { clientIp: { enabled: true, trustProxy: 'cloudflare' } } },
+ incoming: { 'x-forwarded-for': '198.51.100.7', 'cf-connecting-ip': '203.0.113.6' },
+ });
+ assert.equal(lastRequest.headers['x-client-ip'], '203.0.113.6');
+
+ const spoofed = await request({
+ options: { requestContext: { clientIp: { enabled: true, trustProxy: 'cloudflare' } } },
+ incoming: { 'x-forwarded-for': '198.51.100.7' },
+ });
+ assert.equal(lastRequest.headers['x-client-ip'], undefined);
+});
+
+test('forbidden custom headers are rejected before fetch', async () => {
+ await assert.rejects(() => request({ requestOptions: { headers: { authorization: 'Bearer attacker' } } }), /managed or forbidden/);
+ await assert.rejects(() => request({ requestOptions: { headers: { host: 'evil.test' } } }), /managed or forbidden/);
+});
+
+test('response status and safe headers are serializable while Set-Cookie stays hidden', async () => {
+ const { response, cookieStore } = await request({ path: '/status/429', cookies: { unrelated: 'keep-me' } });
+ assert.equal(response.status, 429);
+ assert.equal(response.message, 'status-429');
+ assert.deepEqual(response.headers, { 'x-request-id': 'backend-request', 'x-ratelimit-remaining': '4' });
+ assert.equal(Object.getPrototypeOf(response.headers), Object.prototype);
+ assert.equal(response.headers['set-cookie'], undefined);
+ assert.equal(JSON.stringify(response).includes('secret'), false);
+ assert.equal(cookieStore.get('nab_rotated').value, 'secret');
+ assert.equal(cookieStore.get('unrelated').value, 'keep-me');
+ assert.equal(cookieStore.writes[0].options.domain, undefined);
+ assert.equal(cookieStore.writes[0].options.path, '/');
+ assert.equal(cookieStore.writes[0].options.expires.toISOString(), '2030-10-21T07:28:00.000Z');
+});
+
+test('custom logger never receives request credentials or response bodies', async () => {
+ const entries = [];
+ const logger = {
+ debug: (entry) => entries.push(entry),
+ info: (entry) => entries.push(entry),
+ warn: (entry) => entries.push(entry),
+ error: (entry) => entries.push(entry),
+ };
+ await request({
+ options: { logger, apiKey: 'api-secret', apiKeyHeader: 'x-api-key', auth: { type: 'bearer', tokenCookie: 'accessToken' } },
+ cookies: { nab_accessToken: 'bearer-secret', nab_session: 'cookie-secret' },
+ requestOptions: { operationName: 'integration.echo' },
+ });
+ const serialized = JSON.stringify(entries);
+ assert.equal(serialized.includes('api-secret'), false);
+ assert.equal(serialized.includes('bearer-secret'), false);
+ assert.equal(serialized.includes('cookie-secret'), false);
+ assert.equal(serialized.includes('set-cookie'), false);
+ assert.equal(entries.every((entry) => entry.operationName === 'integration.echo'), true);
+});
+
+test('empty, JSON, text and distinguishable error statuses work', async () => {
+ const empty = await request({ path: '/empty' });
+ assert.equal(empty.response.status, 204);
+ assert.equal(empty.response.body, null);
+
+ const text = await request({ path: '/text' });
+ assert.equal(text.response.status, 200);
+ assert.equal(text.response.body, 'plain response');
+
+ for (const status of [401, 403, 404, 409, 422, 429, 500]) {
+ const result = await request({ path: `/status/${status}` });
+ assert.equal(result.response.status, status);
+ assert.equal(result.response.body.status, status);
+ }
+});
+
+test('query absence never reaches the backend as literal undefined or null', async () => {
+ const { response } = await request({ requestOptions: { query: { missing: undefined, nil: null, active: false, page: 0, search: '' } } });
+ assert.match(lastRequest.url, /active=false/);
+ assert.match(lastRequest.url, /page=0/);
+ assert.match(lastRequest.url, /search=/);
+ assert.doesNotMatch(lastRequest.url, /undefined|null/);
+});
diff --git a/tests/pack-verify.mjs b/tests/pack-verify.mjs
new file mode 100644
index 0000000..ebae96c
--- /dev/null
+++ b/tests/pack-verify.mjs
@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+for (const [subpath, target] of Object.entries(pkg.exports)) {
+ for (const field of ['types', 'import', 'require']) {
+ assert.equal(existsSync(target[field]), true, `${subpath} ${field} target is missing: ${target[field]}`);
+ }
+}
+
+const output = execFileSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], { encoding: 'utf8' });
+const packed = JSON.parse(output)[0];
+const packedPaths = new Set(packed.files.map((file) => `./${file.path}`));
+for (const target of Object.values(pkg.exports)) {
+ for (const field of ['types', 'import', 'require']) {
+ assert.equal(packedPaths.has(target[field]), true, `Tarball is missing declared export: ${target[field]}`);
+ }
+}
+console.log(`Verified ${Object.keys(pkg.exports).length} export groups in ${packed.filename}`);
diff --git a/tests/unit/core.test.cjs b/tests/unit/core.test.cjs
new file mode 100644
index 0000000..767eecd
--- /dev/null
+++ b/tests/unit/core.test.cjs
@@ -0,0 +1,237 @@
+const assert = require('node:assert/strict');
+const test = require('node:test');
+
+const query = require('../../.test-dist/query.js');
+const testing = require('../../.test-dist/testing.js');
+
+class MemoryCookies {
+ constructor(values = {}) {
+ this.values = new Map(Object.entries(values));
+ this.writes = [];
+ this.deletes = [];
+ }
+ get(name) {
+ const value = this.values.get(name);
+ return value === undefined ? undefined : { name, value };
+ }
+ getAll() {
+ return Array.from(this.values, ([name, value]) => ({ name, value }));
+ }
+ set(name, value, options = {}) {
+ this.values.set(name, value);
+ this.writes.push({ name, value, options });
+ }
+ delete(name) {
+ this.values.delete(name);
+ this.deletes.push(name);
+ }
+}
+
+test('query omission and falsy preservation', () => {
+ assert.equal(query.serializeQuery({ missing: undefined, nil: null, active: false, page: 0, search: '' }), 'active=false&page=0&search=');
+});
+
+test('query dates and arrays are encoded consistently', () => {
+ assert.equal(
+ query.serializeQuery({ at: new Date('2026-07-24T06:51:02.515Z'), relations: ['pool', undefined, 'prices'] }),
+ 'at=2026-07-24T06%3A51%3A02.515Z&relations=pool%2Cprices',
+ );
+});
+
+test('URL construction preserves base paths and encodes path params', () => {
+ const url = testing.buildRequestUrl('https://api.example.com/v1/', '/events', ['a/b', 'hello world'], { q: 'x/y', empty: '' });
+ assert.equal(url, 'https://api.example.com/v1/events/a%2Fb/hello%20world?q=x%2Fy&empty=');
+});
+
+test('configuration validates base URL, cookie prefix, auth pairs, and cache context', () => {
+ assert.throws(() => testing.validateAndNormalizeOptions({ baseUrl: 'ftp://example.com' }), /http or https/);
+ assert.throws(() => testing.validateAndNormalizeOptions({ baseUrl: 'https://user:pass@example.com' }), /credentials/);
+ assert.throws(() => testing.validateAndNormalizeOptions({ baseUrl: 'https://example.com', cookiePrefix: '' }), /cookiePrefix/);
+ assert.throws(() => testing.validateAndNormalizeOptions({ baseUrl: 'https://example.com', apiKey: 'secret' }), /provided together/);
+ assert.throws(() => testing.validateAndNormalizeOptions({
+ baseUrl: 'https://example.com',
+ requestContext: { clientIp: { enabled: true, trustProxy: false } },
+ }), /trustProxy/);
+ assert.throws(() => testing.validateAndNormalizeOptions({
+ baseUrl: 'https://example.com',
+ requestContext: { clientOrigin: { enabled: true } },
+ }), /allowedHosts or allowedOrigins/);
+});
+
+test('safe response header allowlist excludes secrets', () => {
+ const headers = new Headers({
+ 'x-request-id': 'req-1',
+ 'retry-after': '30',
+ 'set-cookie': 'session=secret',
+ authorization: 'Bearer secret',
+ 'x-api-key': 'secret',
+ });
+ assert.deepEqual(testing.collectSafeResponseHeaders(headers), {
+ 'x-request-id': 'req-1',
+ 'retry-after': '30',
+ });
+});
+
+test('redaction removes credentials recursively and sanitizes URLs', () => {
+ const redacted = testing.redactValue({
+ password: 'secret',
+ nested: { accessToken: 'token', value: 'safe' },
+ headers: { authorization: 'Bearer abc', accept: 'json' },
+ });
+ assert.equal(redacted.password, '[REDACTED]');
+ assert.equal(redacted.nested.accessToken, '[REDACTED]');
+ assert.equal(redacted.nested.value, 'safe');
+ assert.equal(redacted.headers.authorization, '[REDACTED]');
+ assert.equal(testing.sanitizeUrlForLog('https://api.test/path?token=abc&q=ok'), 'https://api.test/path?token=%5BREDACTED%5D&q=ok');
+});
+
+test('forbidden request headers and CRLF values are rejected', () => {
+ for (const name of ['authorization', 'cookie', 'set-cookie', 'host', 'content-length', 'next-action', 'x-nextjs-data', 'sec-fetch-site']) {
+ assert.equal(testing.isForbiddenRequestHeader(name), true, name);
+ }
+ assert.throws(() => testing.assertAllowedCustomHeaders({ cookie: 'x=y' }), /managed or forbidden/);
+ assert.throws(() => testing.assertAllowedCustomHeaders({ 'x-safe': 'ok\r\nInjected: yes' }), /CR\/LF/);
+});
+
+test('client origin accepts only approved origin-only values', () => {
+ const options = { allowedHosts: ['app.example.com'], allowedOrigins: ['https://admin.example.com'] };
+ assert.equal(testing.validateClientOrigin('https://app.example.com', options), 'https://app.example.com');
+ assert.equal(testing.validateClientOrigin('https://admin.example.com', options), 'https://admin.example.com');
+ assert.equal(testing.validateClientOrigin('https://app.example.com/path', options), undefined);
+ assert.equal(testing.validateClientOrigin('https://user:pass@app.example.com', options), undefined);
+ assert.equal(testing.validateClientOrigin('https://evil.example.com', options), undefined);
+});
+
+test('IPv4, IPv6 and forwarded chains are validated', () => {
+ assert.equal(testing.normalizeIp('203.0.113.10'), '203.0.113.10');
+ assert.equal(testing.normalizeIp('[2001:db8::1]:443'), '2001:db8::1');
+ assert.equal(testing.normalizeIp('not-an-ip'), undefined);
+ assert.deepEqual(testing.parseForwardedChain('203.0.113.10, 10.0.0.1'), ['203.0.113.10', '10.0.0.1']);
+ assert.equal(testing.parseForwardedChain('203.0.113.10, bad'), undefined);
+});
+
+test('Vercel, Cloudflare and custom trusted proxy resolution', () => {
+ assert.equal(testing.resolveClientIp(new Headers({ 'x-vercel-forwarded-for': '203.0.113.10, 10.0.0.1' }), 'vercel'), '203.0.113.10');
+ assert.equal(testing.resolveClientIp(new Headers({ 'cf-connecting-ip': '2001:db8::1' }), 'cloudflare'), '2001:db8::1');
+ assert.equal(testing.resolveClientIp(new Headers({ 'x-forwarded-for': '203.0.113.10, 10.0.0.1, 10.0.0.2' }), {
+ headers: ['x-forwarded-for'], trustedProxyHops: 1,
+ }), '10.0.0.1');
+ assert.equal(testing.resolveClientIp(new Headers({ 'x-forwarded-for': 'spoofed' }), false), undefined);
+});
+
+test('cookie parsing preserves expires, priority and partitioned', () => {
+ const cookie = testing.parseSetCookieString('session=abc==; Expires=Wed, 21 Oct 2030 07:28:00 GMT; Path=/api; Domain=api.example.com; HttpOnly; Secure; SameSite=Lax; Priority=High; Partitioned');
+ assert.equal(cookie.value, 'abc==');
+ assert.equal(cookie.expires.toISOString(), '2030-10-21T07:28:00.000Z');
+ assert.equal(cookie.priority, 'high');
+ assert.equal(cookie.partitioned, true);
+});
+
+test('cookie policy drops domain, rewrites path and preserves expiration', () => {
+ const parsed = testing.parseSetCookieString('session=abc; Expires=Wed, 21 Oct 2030 07:28:00 GMT; Path=/api; Domain=api.example.com; Secure');
+ const policy = testing.normalizeCookiePolicy();
+ const options = testing.applyCookiePolicy(parsed, policy, true);
+ assert.equal(options.domain, undefined);
+ assert.equal(options.path, '/');
+ assert.equal(options.secure, true);
+ assert.equal(options.expires.toISOString(), '2030-10-21T07:28:00.000Z');
+});
+
+test('cookie synchronization protects unprefixed cookies', async () => {
+ const store = new MemoryCookies({ session: 'application-cookie' });
+ const response = new Response('{}', { headers: { 'content-type': 'application/json', 'set-cookie': 'session=backend; Path=/api; Domain=api.example.com; Expires=Wed, 21 Oct 2030 07:28:00 GMT' } });
+ const result = await testing.syncResponseCookies({
+ response,
+ cookieStore: store,
+ cookiePrefix: 'nab_',
+ cookiePolicy: testing.normalizeCookiePolicy(),
+ requestIsSecure: true,
+ });
+ assert.deepEqual(result, { attempted: true, applied: true, reason: 'applied' });
+ assert.equal(store.get('session').value, 'application-cookie');
+ assert.equal(store.get('nab_session').value, 'backend');
+ assert.deepEqual(store.deletes, []);
+ assert.equal(store.writes[0].options.domain, undefined);
+ assert.equal(store.writes[0].options.path, '/');
+});
+
+test('read-only cookie writes are reported instead of hidden', async () => {
+ const store = new MemoryCookies();
+ store.set = () => { throw new Error('Cookies can only be modified in a Server Action or Route Handler'); };
+ const result = await testing.syncResponseCookies({
+ response: new Response('{}', { headers: { 'set-cookie': 'session=abc' } }),
+ cookieStore: store,
+ cookiePrefix: 'nab_',
+ cookiePolicy: testing.normalizeCookiePolicy(),
+ requestIsSecure: true,
+ });
+ assert.deepEqual(result, { attempted: true, applied: false, reason: 'read-only-context' });
+});
+
+test('204, JSON and text response parsing', async () => {
+ const empty = await testing.parseApiResponse(new Response(null, { status: 204 }));
+ assert.equal(empty.status, 204);
+ assert.equal(empty.body, null);
+
+ const json = await testing.parseApiResponse(new Response(JSON.stringify({ success: false, message: 'Denied', value: 1 }), {
+ status: 403, headers: { 'content-type': 'application/json', 'x-request-id': 'req-2', 'set-cookie': 'secret=x' },
+ }));
+ assert.equal(json.success, false);
+ assert.equal(json.message, 'Denied');
+ assert.deepEqual(json.body, { success: false, message: 'Denied', value: 1 });
+ assert.deepEqual(json.headers, { 'x-request-id': 'req-2' });
+
+ const text = await testing.parseApiResponse(new Response('hello', { headers: { 'content-type': 'text/plain' } }));
+ assert.equal(text.body, 'hello');
+});
+
+test('timeout and caller abort signals are combined safely', async () => {
+ const timed = testing.combineAbortSignals(undefined, 10);
+ await new Promise((resolve) => setTimeout(resolve, 20));
+ assert.equal(timed.signal.aborted, true);
+ assert.equal(timed.didTimeout(), true);
+ timed.cleanup();
+
+ const caller = new AbortController();
+ const combined = testing.combineAbortSignals(caller.signal, 1000);
+ caller.abort();
+ assert.equal(combined.signal.aborted, true);
+ assert.equal(combined.didTimeout(), false);
+ combined.cleanup();
+});
+
+test('conflicting cache options are rejected', () => {
+ assert.throws(() => testing.validateCacheOptions({ cache: 'no-store', next: { revalidate: 30 } }), /conflicts/);
+ assert.throws(() => testing.validateCacheOptions({ cache: 'force-cache', next: { revalidate: 0 } }), /conflicts/);
+ assert.doesNotThrow(() => testing.validateCacheOptions({ cache: 'force-cache', next: { revalidate: 30, tags: ['events'] } }));
+});
+
+test('request context forwards only configured safe values and generates IDs', () => {
+ const options = testing.validateAndNormalizeOptions({
+ baseUrl: 'https://api.example.com',
+ requestContext: {
+ clientIp: { enabled: true, trustProxy: 'cloudflare' },
+ clientOrigin: { enabled: true, allowedHosts: ['app.example.com'], cookieName: 'client_url' },
+ },
+ });
+ const result = testing.buildRequestContextHeaders(
+ new Headers({
+ 'user-agent': 'Browser UA',
+ 'accept-language': 'en-KE',
+ traceparent: '00-abc-def-01',
+ baggage: 'not-forwarded-by-default',
+ 'cf-connecting-ip': '203.0.113.10',
+ host: 'app.example.com',
+ }),
+ new MemoryCookies({ client_url: 'https://app.example.com' }),
+ options.requestContext,
+ );
+ assert.equal(result.headers['user-agent'], 'Browser UA');
+ assert.equal(result.headers['accept-language'], 'en-KE');
+ assert.equal(result.headers.traceparent, '00-abc-def-01');
+ assert.equal(result.headers.baggage, undefined);
+ assert.equal(result.headers['x-client-ip'], '203.0.113.10');
+ assert.equal(result.headers['x-client-origin'], 'https://app.example.com');
+ assert.match(result.headers['x-request-id'], /^[0-9a-f-]{36}$/i);
+ assert.equal(result.headers['x-api-bridge'], 'next-api-bridge/0.1.7');
+});
diff --git a/tests/write-test-package-type.cjs b/tests/write-test-package-type.cjs
new file mode 100644
index 0000000..74a80a9
--- /dev/null
+++ b/tests/write-test-package-type.cjs
@@ -0,0 +1,5 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+fs.mkdirSync(path.resolve('.test-dist'), { recursive: true });
+fs.writeFileSync(path.resolve('.test-dist/package.json'), JSON.stringify({ type: 'commonjs' }));
diff --git a/tsconfig.json b/tsconfig.json
index 0d349b0..bf1d2c6 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,13 +1,13 @@
{
- "compilerOptions": {
- "target": "ES2022",
- "module": "ESNext",
- "moduleResolution": "Bundler",
- "declaration": true,
- "strict": true,
- "skipLibCheck": true
- },
- "include": [
- "src"
- ]
-}
\ No newline at end of file
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "declaration": true,
+ "strict": true,
+ "skipLibCheck": true,
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
+ "types": ["node"]
+ },
+ "include": ["src"]
+}
diff --git a/tsconfig.test.json b/tsconfig.test.json
new file mode 100644
index 0000000..8479bb6
--- /dev/null
+++ b/tsconfig.test.json
@@ -0,0 +1,12 @@
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "module": "CommonJS",
+ "moduleResolution": "Node",
+ "outDir": ".test-dist",
+ "declaration": false,
+ "noEmit": false,
+ "rootDir": "src"
+ },
+ "include": ["src"]
+}
diff --git a/tsup.config.ts b/tsup.config.ts
index 01605e8..f51ac83 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -1,7 +1,13 @@
import { defineConfig } from 'tsup';
export default defineConfig({
- entry: ['src/index.ts', 'src/form/index.ts', 'src/cache.ts', 'src/query.ts'],
+ entry: [
+ 'src/index.ts',
+ 'src/form/index.ts',
+ 'src/cache.ts',
+ 'src/query.ts',
+ 'src/testing.ts',
+ ],
format: ['esm', 'cjs'],
dts: true,
clean: true,