@next-buildr/payload 2.0.0 → 3.0.0-rc.0

package/dist/plugin/forms/captcha.test.js

@@ -0,0 +1,262 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ancestorFormHasCaptcha, CAPTCHA_ACTION, CAPTCHA_FIELD, CAPTCHA_TYPE, captchaCData, createCaptchaGate, createTurnstileVerifier, findFormCaptchas, } from './captcha.js';
+import { createMemoryRateLimiter } from './rate-limit.js';
+// Pin these exact UTF-8 JSON tuple vectors in the components package too.
+const SIMPLE = '39d82018d38dd1145f9903261b443a1556acf5f672cc5a15e8fa61999b15d6bd';
+const UNICODE = 'ea58a41440286e8b7194961ae8b63704e6ceca9e305a190cf7637bc8d6dc4cc5';
+const SECRET = 'private-turnstile-secret';
+const TOKEN = 'opaque-token';
+const success = { success: true, hostname: 'example.com', action: CAPTCHA_ACTION, cdata: SIMPLE };
+const signal = () => new AbortController().signal;
+const run = (fetcher, input = TOKEN, log = vi.fn()) => createTurnstileVerifier({ secretKey: SECRET, fetch: fetcher, log }).verify({
+    token: input,
+    signal: signal(),
+});
+describe('captcha contract', () => {
+    it('pins constants and simple and Unicode golden vectors', () => {
+        expect([CAPTCHA_FIELD, CAPTCHA_ACTION, CAPTCHA_TYPE]).toEqual([
+            'buildr-captcha',
+            'buildr_form',
+            'buildr/captcha',
+        ]);
+        expect(captchaCData('pages:1', 'form000001')).toBe(SIMPLE);
+        expect(captchaCData('pages:za\u017c\u00f3\u0142\u0107-\u6771\u4eac', 'formularz-\u{1f6e1}\ufe0f')).toBe(UNICODE);
+    });
+    it('gates per instance and releases idempotently', () => {
+        const gate = createCaptchaGate(1);
+        const release = gate.tryAcquire();
+        expect(release).not.toBeNull();
+        expect(gate.tryAcquire()).toBeNull();
+        expect(createCaptchaGate(1).tryAcquire()).not.toBeNull();
+        release?.();
+        release?.();
+        expect(gate.tryAcquire()).not.toBeNull();
+        expect(gate.tryAcquire()).toBeNull();
+    });
+});
+describe('Turnstile verifier', () => {
+    it('uses the exact fixed, uncached, non-redirecting POST with only secret and response', async () => {
+        const fetcher = vi.fn().mockResolvedValue(Response.json(success));
+        const abort = signal();
+        const result = await createTurnstileVerifier({ secretKey: SECRET, fetch: fetcher }).verify({
+            token: TOKEN,
+            signal: abort,
+        });
+        expect(result).toEqual({
+            ok: true,
+            hostname: 'example.com',
+            action: CAPTCHA_ACTION,
+            cdata: SIMPLE,
+        });
+        expect(fetcher).toHaveBeenCalledOnce();
+        const [url, init] = fetcher.mock.calls[0] ?? [];
+        expect(url).toBe('https://challenges.cloudflare.com/turnstile/v0/siteverify');
+        expect(init).toEqual({
+            method: 'POST',
+            body: new URLSearchParams({ secret: SECRET, response: TOKEN }),
+            redirect: 'error',
+            cache: 'no-store',
+            signal: abort,
+        });
+        const body = init?.body;
+        expect(body).toBeInstanceOf(URLSearchParams);
+        expect(body instanceof URLSearchParams ? [...body.entries()] : []).toEqual([
+            ['secret', SECRET],
+            ['response', TOKEN],
+        ]);
+    });
+    it.each(['', 'a b', 'non-ASCII-\u00e9', 'valid\n', 'a'.repeat(2049), ['one', 'two'], 123, null])('makes no outbound call for malformed token %j', async (token) => {
+        const fetcher = vi.fn();
+        expect(await run(fetcher, token)).toEqual({ ok: false, reason: 'invalid' });
+        expect(fetcher).not.toHaveBeenCalled();
+    });
+    it.each([
+        ['missing-input-secret', 'unavailable', 'configuration'],
+        ['invalid-input-secret', 'unavailable', 'configuration'],
+        ['timeout-or-duplicate', 'expired-or-reused', 'expired-or-reused'],
+        ['internal-error', 'unavailable', 'unavailable'],
+        ['invalid-input-response', 'invalid', 'invalid'],
+        ['unknown-code', 'invalid', 'invalid'],
+    ])('maps Cloudflare %s safely', async (code, reason, loggedReason) => {
+        const log = vi.fn();
+        expect(await run(vi
+            .fn()
+            .mockResolvedValue(Response.json({ success: false, 'error-codes': [code] })), TOKEN, log)).toEqual({ ok: false, reason });
+        expect(log).toHaveBeenCalledWith({ reason: loggedReason, codes: [code] });
+        expect(JSON.stringify(log.mock.calls)).not.toContain(SECRET);
+        expect(JSON.stringify(log.mock.calls)).not.toContain(TOKEN);
+    });
+    it('filters and caps logged codes and gives configuration errors precedence', async () => {
+        const log = vi.fn();
+        const codes = [
+            TOKEN,
+            SECRET,
+            '<script>',
+            'a'.repeat(65),
+            'UPPER',
+            'bad-code\n',
+            'timeout-or-duplicate',
+            'invalid-input-secret',
+            ...Array.from({ length: 20 }, () => 'bad-request'),
+        ];
+        const response = { success: false, 'error-codes': codes, token: TOKEN, secret: SECRET };
+        expect(await run(vi.fn().mockResolvedValue(Response.json(response)), TOKEN, log)).toEqual({ ok: false, reason: 'unavailable' });
+        expect(log.mock.calls[0]?.[0].codes).toHaveLength(10);
+        expect(log.mock.calls[0]?.[0].codes).toEqual([
+            'timeout-or-duplicate',
+            'invalid-input-secret',
+            ...Array.from({ length: 8 }, () => 'bad-request'),
+        ]);
+        expect(JSON.stringify(log.mock.calls)).not.toContain(SECRET);
+        expect(JSON.stringify(log.mock.calls)).not.toContain(TOKEN);
+    });
+    it.each([302, 400, 500])('fails closed for HTTP %s', async (status) => {
+        expect(await run(vi.fn().mockResolvedValue(new Response('', { status })))).toEqual({ ok: false, reason: 'unavailable' });
+    });
+    it.each([
+        new TypeError('redirect'),
+        new DOMException('abort', 'AbortError'),
+        new DOMException('timeout', 'TimeoutError'),
+        new Error(SECRET),
+    ])('does not log thrown transport errors', async (error) => {
+        const log = vi.fn();
+        expect(await run(vi.fn().mockRejectedValue(error), TOKEN, log)).toEqual({
+            ok: false,
+            reason: 'unavailable',
+        });
+        expect(log).not.toHaveBeenCalled();
+    });
+    it.each([
+        '{',
+        '{}',
+        'null',
+        JSON.stringify({ success: 'true' }),
+        JSON.stringify({ success: true, hostname: 1 }),
+        JSON.stringify({ success: true, hostname: 'example.com' }),
+        JSON.stringify({ success: false, 'error-codes': [1] }),
+    ])('rejects malformed response %s', async (body) => {
+        expect(await run(vi.fn().mockResolvedValue(new Response(body)))).toEqual({
+            ok: false,
+            reason: 'unavailable',
+        });
+    });
+    it('defaults missing cdata to empty for the endpoint to reject', async () => {
+        expect(await run(vi.fn().mockResolvedValue(Response.json({ ...success, cdata: undefined })))).toMatchObject({ ok: true, cdata: '' });
+    });
+    it('accepts a chunked response at the byte limit and rejects a cumulative overflow', async () => {
+        const bytes = new TextEncoder().encode(JSON.stringify(success));
+        for (const extra of [0, 1]) {
+            const cancel = vi.fn();
+            const body = new ReadableStream({
+                start(controller) {
+                    controller.enqueue(bytes.subarray(0, 10));
+                    controller.enqueue(bytes.subarray(10));
+                    controller.enqueue(new TextEncoder().encode(' '.repeat(16 * 1024 - bytes.byteLength + extra)));
+                    if (extra === 0)
+                        controller.close();
+                },
+                cancel,
+            });
+            expect(await run(vi.fn().mockResolvedValue(new Response(body)))).toMatchObject(extra === 0 ? { ok: true } : { ok: false, reason: 'unavailable' });
+            expect(cancel).toHaveBeenCalledTimes(extra);
+        }
+    });
+    it('cancels an oversized streaming body without waiting for cancellation', async () => {
+        const cancel = vi.fn(() => new Promise(() => { }));
+        const body = new ReadableStream({
+            start(controller) {
+                controller.enqueue(new Uint8Array(16 * 1024 + 1));
+            },
+            cancel,
+        });
+        expect(await run(vi.fn().mockResolvedValue(new Response(body)))).toEqual({
+            ok: false,
+            reason: 'unavailable',
+        });
+        expect(cancel).toHaveBeenCalledOnce();
+    });
+    it('aborts a stalled body reader and a never-settling fetch', async () => {
+        for (const stallBody of [true, false]) {
+            const controller = new AbortController();
+            const cancel = vi.fn();
+            const fetcher = vi
+                .fn()
+                .mockImplementation(() => stallBody
+                ? Promise.resolve(new Response(new ReadableStream({ cancel })))
+                : new Promise(() => { }));
+            const pending = createTurnstileVerifier({ secretKey: SECRET, fetch: fetcher }).verify({
+                token: TOKEN,
+                signal: controller.signal,
+            });
+            await vi.waitFor(() => expect(fetcher).toHaveBeenCalledOnce());
+            controller.abort();
+            expect(await pending).toEqual({ ok: false, reason: 'unavailable' });
+            if (stallBody)
+                expect(cancel).toHaveBeenCalledOnce();
+        }
+    });
+    it('does not fetch with an already aborted signal', async () => {
+        const fetcher = vi.fn();
+        const controller = new AbortController();
+        controller.abort();
+        expect(await createTurnstileVerifier({ secretKey: SECRET, fetch: fetcher }).verify({
+            token: TOKEN,
+            signal: controller.signal,
+        })).toEqual({ ok: false, reason: 'unavailable' });
+        expect(fetcher).not.toHaveBeenCalled();
+    });
+});
+describe('literal nearest-form detection', () => {
+    const graph = () => ({
+        schemaVersion: 1,
+        root: 'root',
+        components: {},
+        nodes: {
+            root: { id: 'root', type: 'buildr/page', slots: { default: ['outer'] } },
+            outer: {
+                id: 'outer',
+                type: 'buildr/form',
+                slots: { default: ['wrapper', 'inner', 'dangling', 'toString'] },
+            },
+            wrapper: {
+                id: 'wrapper',
+                type: 'unregistered',
+                slots: { anything: ['cap', 'cap', 'outer'] },
+            },
+            cap: {
+                id: 'cap',
+                type: CAPTCHA_TYPE,
+                styles: { base: { visibility: { hidden: true } } },
+                visibleIf: { kind: 'static', value: false },
+            },
+            inner: { id: 'inner', type: 'buildr/form', slots: { default: ['inside'] } },
+            inside: { id: 'inside', type: CAPTCHA_TYPE },
+        },
+    });
+    it('tolerates cycles, duplicate/dangling/prototype references, ignores conditions, and skips nested forms', () => {
+        expect(findFormCaptchas(graph(), 'outer').map((node) => node.id)).toEqual(['cap']);
+        expect(findFormCaptchas(graph(), 'inner').map((node) => node.id)).toEqual(['inside']);
+        expect(findFormCaptchas(graph(), 'missing')).toEqual([]);
+        expect(findFormCaptchas(graph(), 'toString')).toEqual([]);
+    });
+    it('detects any protected form ancestor even across corrupt reverse edges', () => {
+        expect(ancestorFormHasCaptcha(graph(), 'inner')).toBe(true);
+        expect(ancestorFormHasCaptcha(graph(), 'outer')).toBe(false);
+        expect(ancestorFormHasCaptcha(graph(), 'missing')).toBe(false);
+    });
+});
+it('retains live captcha counters at capacity and admits new keys only after expiry', async () => {
+    let now = 0;
+    const limiter = createMemoryRateLimiter({
+        limit: 1,
+        windowMs: 1000,
+        now: () => now,
+        failClosed: true,
+    });
+    for (let i = 0; i < 10000; i++)
+        expect(await limiter.hit(String(i))).toEqual({ allowed: true });
+    expect(await limiter.hit('new')).toEqual({ allowed: false, retryAfterSeconds: 1 });
+    expect(await limiter.hit('0')).toEqual({ allowed: false, retryAfterSeconds: 1 });
+    now = 1000;
+    expect(await limiter.hit('new')).toEqual({ allowed: true });
+});

package/dist/plugin/forms/client-ip.d.ts

@@ -0,0 +1,8 @@
+import type { PayloadRequest } from 'payload';
+export type ClientIpSource = {
+    readonly header: string;
+    readonly hops?: number;
+} | ((req: PayloadRequest) => string | undefined);
+/** A configured, trusted source never falls back to client-controlled forwarding headers. */
+export declare function clientIpOf(req: PayloadRequest, source?: ClientIpSource): string;
+//# sourceMappingURL=client-ip.d.ts.map

package/dist/plugin/forms/client-ip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-ip.d.ts","sourceRoot":"","sources":["../../../src/plugin/forms/client-ip.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,CAAC,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;AAElD,6FAA6F;AAC7F,wBAAgB,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,CAmC/E"}

package/dist/plugin/forms/client-ip.js

@@ -0,0 +1,41 @@
+import { isIP } from 'node:net';
+/** A configured, trusted source never falls back to client-controlled forwarding headers. */
+export function clientIpOf(req, source) {
+    if (source === undefined) {
+        const forwarded = req.headers.get('x-forwarded-for')?.split(',')[0]?.trim();
+        return forwarded || req.headers.get('x-real-ip') || 'unknown';
+    }
+    try {
+        const chain = typeof source === 'function' ? undefined : req.headers.get(source.header)?.split(',');
+        const raw = typeof source === 'function' ? source(req) : chain?.at(-(source.hops ?? 1));
+        const ip = typeof raw === 'string' ? raw.trim() : '';
+        if (ip.includes('%'))
+            return 'unknown';
+        const family = isIP(ip);
+        if (family === 4)
+            return ip;
+        if (family !== 6)
+            return 'unknown';
+        // URL canonicalisation expands dotted IPv4 tails and compresses equivalent IPv6 spellings.
+        const canonical = new URL(`http://[${ip}]/`).hostname.slice(1, -1);
+        const [left = '', right = ''] = canonical.split('::');
+        const head = left ? left.split(':') : [];
+        const tail = right ? right.split(':') : [];
+        const words = canonical.includes('::')
+            ? [...head, ...Array(8 - head.length - tail.length).fill('0'), ...tail]
+            : head;
+        const nums = words.map((word) => Number.parseInt(word, 16));
+        if (nums.slice(0, 5).every((word) => word === 0) && nums[5] === 65535) {
+            const a = nums[6] ?? 0;
+            const b = nums[7] ?? 0;
+            return `${a >> 8}.${a & 255}.${b >> 8}.${b & 255}`;
+        }
+        return `${nums
+            .slice(0, 4)
+            .map((word) => word.toString(16))
+            .join(':')}::/64`;
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/dist/plugin/forms/client-ip.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client-ip.test.d.ts.map

package/dist/plugin/forms/client-ip.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-ip.test.d.ts","sourceRoot":"","sources":["../../../src/plugin/forms/client-ip.test.ts"],"names":[],"mappings":""}

package/dist/plugin/forms/client-ip.test.js

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { clientIpOf } from './client-ip.js';
+const request = (headers = {}) => ({ headers: new Headers(headers) });
+describe('clientIpOf', () => {
+    it('preserves the old default including unvalidated values and whitespace', () => {
+        expect(clientIpOf(request({ 'x-forwarded-for': ' spoofed , 192.0.2.1', 'x-real-ip': 'other' }))).toBe('spoofed');
+        expect(clientIpOf(request({ 'x-forwarded-for': ' ,x', 'x-real-ip': ' untrimmed ' }))).toBe('untrimmed');
+        expect(clientIpOf(request())).toBe('unknown');
+    });
+    it('selects the configured hop from the right and validates IPv4 and IPv6', () => {
+        const req = request({ 'trusted-ip': '192.0.2.1, 2001:db8::1, 198.51.100.1' });
+        expect(clientIpOf(req, { header: 'trusted-ip' })).toBe('198.51.100.1');
+        expect(clientIpOf(req, { header: 'trusted-ip', hops: 2 })).toBe('2001:db8:0:0::/64');
+        expect(clientIpOf(req, { header: 'trusted-ip', hops: 3 })).toBe('192.0.2.1');
+    });
+    it.each([undefined, '', 'unknown', '192.0.2.1:80', '[2001:db8::1]', '999.2.3.4', 'example.com'])('shares one unknown bucket for bad configured addresses: %s', (value) => {
+        const req = request({
+            'x-forwarded-for': '192.0.2.9',
+            'x-real-ip': '192.0.2.8',
+            ...(value === undefined ? {} : { trusted: value }),
+        });
+        expect(clientIpOf(req, { header: 'trusted' })).toBe('unknown');
+        expect(clientIpOf(req, () => value)).toBe('unknown');
+    });
+    it('never falls back for a short chain or throwing callback, and passes the request', () => {
+        const req = request({ trusted: '192.0.2.1', 'x-real-ip': '192.0.2.8' });
+        expect(clientIpOf(req, { header: 'trusted', hops: 2 })).toBe('unknown');
+        const source = (received) => {
+            expect(received).toBe(req);
+            return ' 2001:db8::1 ';
+        };
+        expect(clientIpOf(req, source)).toBe('2001:db8:0:0::/64');
+        expect(clientIpOf(req, () => {
+            throw new Error('private details');
+        })).toBe('unknown');
+    });
+});
+it('normalises mapped IPv4 and groups IPv6 by /64 across spellings and zones', () => {
+    const key = (ip) => clientIpOf(request(), () => ip);
+    expect(key('::ffff:192.0.2.1')).toBe(key('192.0.2.1'));
+    expect(key('::ffff:c000:201')).toBe(key('192.0.2.1'));
+    expect(key('2001:db8::1')).toBe(key('2001:0db8:0000:0000:ffff:0:0:2'));
+    expect(key('2001:db8:0:1::1')).not.toBe(key('2001:db8::1'));
+    expect(key('fe80::1%eth0')).toBe('unknown');
+});

package/dist/plugin/forms/rate-limit.d.ts

@@ -18,6 +18,8 @@ export interface MemoryRateLimiterOptions {
     readonly windowMs: number;
     /** Replaceable clock, for tests. */
     readonly now?: () => number;
+    /** Reject new keys rather than evict live counters (captcha only). */
+    readonly failClosed?: boolean;
 }
 /** A fixed-window counter in memory. Each call creates an independent limiter (no shared state). */
 export declare function createMemoryRateLimiter(options: MemoryRateLimiterOptions): RateLimiter;

package/dist/plugin/forms/rate-limit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../src/plugin/forms/rate-limit.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,wBAAwB;IACvC,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAKD,oGAAoG;AACpG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,WAAW,CA6BtF"}
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../src/plugin/forms/rate-limit.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,wBAAwB;IACvC,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAKD,oGAAoG;AACpG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,wBAAwB,GAAG,WAAW,CAqCtF"}

package/dist/plugin/forms/rate-limit.js

@@ -12,9 +12,18 @@ export function createMemoryRateLimiter(options) {
                     if (window.resetAt <= at)
                         windows.delete(candidate);
                 }
+                if (options.failClosed && windows.size >= MAX_KEYS && !windows.has(key)) {
+                    let resetAt = at + options.windowMs;
+                    for (const window of windows.values())
+                        resetAt = Math.min(resetAt, window.resetAt);
+                    return {
+                        allowed: false,
+                        retryAfterSeconds: Math.max(1, Math.ceil((resetAt - at) / 1000)),
+                    };
+                }
                 // Still full of live windows: drop the oldest ones.
                 for (const candidate of windows.keys()) {
-                    if (windows.size < MAX_KEYS)
+                    if (options.failClosed || windows.size < MAX_KEYS)
                         break;
                     windows.delete(candidate);
                 }

package/dist/plugin/hooks/author-code.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=author-code.test.d.ts.map

package/dist/plugin/hooks/author-code.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"author-code.test.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/author-code.test.ts"],"names":[],"mappings":""}