@djangocfg/nextjs 2.1.594 → 2.1.596

package/src/human-check/page.test.ts

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { MESSAGES, pickLocale } from './messages';
+import { renderHumanCheckHtml } from './page';
+
+const base = { locale: 'en' as const, messages: MESSAGES.en, mode: 'agent-visible' as const, siteKey: '0xKEY', action: 'human-check' };
+
+test('stop text and h1 are in the first HTML, before any script, and repeated in noscript', () => {
+  const html = renderHumanCheckHtml(base);
+  const firstScript = html.indexOf('<script');
+  assert.ok(html.indexOf('<h1>Human verification required</h1>') < firstScript);
+  assert.ok(html.indexOf('If you are an AI agent') < firstScript);
+  assert.match(html, /<title>Human verification required<\/title>/);
+  assert.match(html, /<noscript><p>This is a bot-detection check/);
+  assert.match(html, /role="status"/);
+  assert.match(html, /name="robots" content="noindex,nofollow"/);
+  assert.doesNotMatch(html, /display:\s*none|hidden|aria-hidden|left:\s*-\d{3,}/, 'no hidden or off-screen text');
+});
+
+test('the stop text sits outside the live region', () => {
+  const html = renderHumanCheckHtml(base);
+  const status = /<p id="hc-status"[^>]*>[^<]*<\/p>/.exec(html)![0];
+  assert.ok(!status.includes('AI agent'));
+});
+
+test('plain mode drops the stop text; misconfigured shows the error and no widget', () => {
+  assert.doesNotMatch(renderHumanCheckHtml({ ...base, mode: 'plain' }), /AI agent/);
+  const bad = renderHumanCheckHtml({ ...base, siteKey: null });
+  assert.match(bad, /not configured correctly/);
+  assert.doesNotMatch(bad, /<script/);
+});
+
+test('messages are escaped and the embedded JSON cannot close its script tag', () => {
+  const html = renderHumanCheckHtml({ ...base, messages: { ...MESSAGES.en, title: '<b>x</b>', failed: '</script><img>' } });
+  assert.match(html, /<title>&lt;b&gt;x&lt;\/b&gt;<\/title>/);
+  assert.doesNotMatch(html, /<\/script><img>/);
+});
+
+test('Russian copy and locale picking', () => {
+  const html = renderHumanCheckHtml({ ...base, locale: 'ru', messages: MESSAGES.ru });
+  assert.match(html, /<html lang="ru">/);
+  assert.match(html, /Требуется проверка, что вы человек/);
+  assert.equal(pickLocale('ru', 'en', 'en'), 'ru');
+  assert.equal(pickLocale(null, 'de,ru;q=0.8', 'en'), 'ru');
+  assert.equal(pickLocale('xx', null, 'en'), 'en');
+});

package/src/human-check/page.ts

@@ -0,0 +1,69 @@
+import type { HumanCheckLocale, HumanCheckMessages } from './types';
+
+export interface PageOptions {
+  locale: HumanCheckLocale;
+  messages: HumanCheckMessages;
+  mode: 'agent-visible' | 'plain';
+  /** Null when the gate is misconfigured: the page then shows the error and no widget. */
+  siteKey: string | null;
+  action: string;
+  /** Minimum time the message stays on screen after success, so a late snapshot still reads it. */
+  dwellMs?: number;
+}
+
+const esc = (s: string) =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+
+/** JSON safe inside a <script> element. */
+const scriptJson = (v: unknown) =>
+  JSON.stringify(v)
+    .replace(/</g, '\\u003c')
+    .replace(new RegExp(String.fromCharCode(0x2028), 'g'), '\\u2028')
+    .replace(new RegExp(String.fromCharCode(0x2029), 'g'), '\\u2029');
+
+const CLIENT = `(function(){
+var d=JSON.parse(document.getElementById('hc-data').textContent),m=d.m,s=document.getElementById('hc-status'),t0=Date.now(),id=null;
+function say(t){s.textContent=t}
+function go(n){setTimeout(function(){location.replace(n)},Math.max(0,d.dwell-(Date.now()-t0)))}
+function tok(t){say(m.verifying);
+fetch(location.pathname+location.search,{method:'POST',credentials:'same-origin',headers:{'content-type':'application/json'},body:JSON.stringify({token:t})})
+.then(function(r){return r.json()}).then(function(j){
+if(j&&j.ok){say(m.done);go(j.next)}else{say(m.failed);if(window.turnstile&&id!==null)window.turnstile.reset(id)}})
+.catch(function(){say(m.failed);if(window.turnstile&&id!==null)window.turnstile.reset(id)})}
+function mount(){if(!window.turnstile)return false;
+id=window.turnstile.render('#hc-widget',{sitekey:d.siteKey,action:d.action,appearance:'always',callback:tok,
+'error-callback':function(){say(m.blocked)},'expired-callback':function(){if(id!==null)window.turnstile.reset(id)}});return true}
+var tries=0,iv=setInterval(function(){if(mount()){clearInterval(iv)}else if(++tries>100){clearInterval(iv);say(m.blocked)}},100);
+})();`;
+
+/**
+ * Server-rendered gate page. The stop text and the h1 are in the first HTML,
+ * before any script, and the same text is repeated in <noscript>. No hidden
+ * text, no timers that move the page before verification succeeded.
+ */
+export function renderHumanCheckHtml(o: PageOptions): string {
+  const m = o.messages;
+  const agent = o.mode === 'agent-visible';
+  const stop = agent ? `<p id="hc-stop">${esc(m.stop)}</p>` : '';
+  const widget = o.siteKey
+    ? `<div id="hc-widget"></div><p id="hc-status" role="status" aria-live="polite">${esc(m.checking)}</p>`
+    : `<p id="hc-status" role="status">${esc(m.misconfigured)}</p>`;
+  const scripts = o.siteKey
+    ? `<script id="hc-data" type="application/json">${scriptJson({ m: { verifying: m.verifying, done: m.done, failed: m.failed, blocked: m.blocked }, siteKey: o.siteKey, action: o.action, dwell: o.dwellMs ?? 3000 })}</script>` +
+      `<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" async defer></script>` +
+      `<script>${CLIENT}</script>`
+    : '';
+  return (
+    `<!doctype html><html lang="${o.locale}"><head><meta charset="utf-8">` +
+    `<meta name="viewport" content="width=device-width,initial-scale=1">` +
+    `<meta name="robots" content="noindex,nofollow">` +
+    `<title>${esc(m.title)}</title>` +
+    `<style>:root{color-scheme:light dark}body{margin:0;font:16px/1.5 system-ui,sans-serif;display:grid;min-height:100vh;place-items:center}` +
+    `main{max-width:34rem;padding:1.5rem}h1{font-size:1.5rem;margin:0 0 1rem}p{margin:0 0 1rem}#hc-widget{min-height:65px;margin:1rem 0}</style>` +
+    `</head><body><main>` +
+    `<h1>${esc(m.title)}</h1>${stop}<p id="hc-human">${esc(m.human)}</p>` +
+    `${widget}` +
+    `<noscript>${agent ? `<p>${esc(m.stop)}</p>` : ''}<p>${esc(m.noscript)}</p></noscript>` +
+    `</main>${scripts}</body></html>`
+  );
+}

package/src/human-check/proxy.test.ts

@@ -0,0 +1,170 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { NextRequest } from 'next/server';
+
+import { signClearance } from './cookie';
+import { createCrawlerMatcher } from './crawlers';
+import { createHumanCheck, type HumanCheckDeps } from './proxy';
+
+import type { HumanCheckConfig } from './types';
+
+const ENV = { HUMAN_CHECK_SECRET: 'sek', NEXT_PUBLIC_TURNSTILE_SITE_KEY: '0xSITE', TURNSTILE_SECRET_KEY: 'tsecret' };
+const BROWSER = 'Mozilla/5.0 (Macintosh) Chrome/130';
+const jsonRes = (o: unknown) => ({ ok: true, status: 200, json: async () => o }) as Response;
+const LIST = { prefixes: [{ ipv4Prefix: '66.249.64.0/27' }] };
+const crawlers = () => createCrawlerMatcher({ sources: ['u'], fetch: (async () => jsonRes(LIST)) as typeof fetch });
+
+function make(config: HumanCheckConfig = {}, deps: HumanCheckDeps = {}) {
+  return createHumanCheck({ enabled: true, ...config }, { isDev: false, env: ENV, crawlers: crawlers(), log: () => {}, ...deps });
+}
+
+function req(path: string, init: { ua?: string; ip?: string; method?: string; cookie?: string; host?: string; body?: unknown; origin?: string } = {}) {
+  const headers: Record<string, string> = { 'user-agent': init.ua ?? BROWSER };
+  if (init.ip) headers['x-forwarded-for'] = init.ip;
+  if (init.cookie) headers.cookie = init.cookie;
+  if (init.origin) headers.origin = init.origin;
+  if (init.body !== undefined) headers['content-type'] = 'application/json';
+  return new NextRequest(`https://${init.host ?? 'app.example.com'}${path}`, {
+    method: init.method ?? 'GET',
+    headers,
+    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+  });
+}
+
+const passes = (r: Response | undefined) => r === undefined || r.headers.get('x-middleware-next') === '1';
+
+test('disabled by default: nothing happens, the gate route does not exist', async () => {
+  const hc = createHumanCheck({}, { isDev: false, env: ENV, log: () => {} });
+  assert.equal(await hc.proxy(req('/')), undefined);
+  assert.equal((await hc.proxy(req('/__human-check')))!.status, 404);
+});
+
+test('development: no gate, no redirect, route is 404, no startup noise even without keys', async () => {
+  const logs: string[] = [];
+  const hc = make({}, { isDev: true, env: {}, log: (m) => logs.push(m) });
+  assert.equal(await hc.proxy(req('/cabinet')), undefined);
+  const g = await hc.proxy(req('/__human-check'));
+  assert.equal(g!.status, 404);
+  assert.equal(logs.length, 0);
+});
+
+test('enabledIn "all" gates in development too', async () => {
+  const hc = make({ enabledIn: 'all' }, { isDev: true });
+  assert.equal((await hc.proxy(req('/cabinet')))!.status, 302);
+});
+
+test('browser UA without a cookie: 302 (never 301) to the gate with next, no-store', async () => {
+  const r = (await make().proxy(req('/cabinet?x=1')))!;
+  assert.equal(r.status, 302);
+  const loc = new URL(r.headers.get('location')!);
+  assert.equal(loc.pathname, '/__human-check');
+  assert.equal(loc.searchParams.get('next'), '/cabinet?x=1');
+  assert.equal(r.headers.get('cache-control'), 'private, no-store');
+});
+
+test('gate page: 200, noindex, no-store, stop text', async () => {
+  const r = (await make().proxy(req('/__human-check?next=/cabinet')))!;
+  assert.equal(r.status, 200);
+  assert.equal(r.headers.get('x-robots-tag'), 'noindex, nofollow');
+  assert.equal(r.headers.get('cache-control'), 'private, no-store');
+  const html = await r.text();
+  assert.match(html, /If you are an AI agent/);
+  assert.match(html, /0xSITE/);
+});
+
+test('valid cookie passes with private cache headers; cookie for another UA is gated', async () => {
+  const c = await signClearance('sek', BROWSER, 3600);
+  const ok = await make().proxy(req('/cabinet', { cookie: `__hc=${c}` }));
+  assert.ok(passes(ok));
+  assert.equal(ok!.headers.get('cache-control'), 'private, no-store');
+  const other = await make().proxy(req('/cabinet', { cookie: `__hc=${c}`, ua: 'curl/8' }));
+  assert.equal(other!.status, 302);
+});
+
+test('Googlebot from a Google IP passes, sets no cookie; fake Googlebot is gated', async () => {
+  const hc = make();
+  const real = await hc.proxy(req('/cabinet', { ua: 'Googlebot/2.1', ip: '66.249.64.10' }));
+  assert.ok(passes(real));
+  assert.equal(real!.headers.get('set-cookie'), null);
+  const fake = await hc.proxy(req('/cabinet', { ua: 'Googlebot/2.1', ip: '203.0.113.9' }));
+  assert.equal(fake!.status, 302);
+});
+
+test('crawler list never loaded: claimed crawler passes by default, gated with onListUnavailable "gate"', async () => {
+  const down = () => createCrawlerMatcher({ sources: ['u'], fetch: (async () => { throw new Error('x'); }) as typeof fetch });
+  const ua = { ua: 'Googlebot/2.1', ip: '203.0.113.9' };
+  assert.ok(passes(await make({}, { crawlers: down() }).proxy(req('/a', ua))));
+  assert.equal((await make({ bypass: { onListUnavailable: 'gate' } }, { crawlers: down() }).proxy(req('/a', ua)))!.status, 302);
+});
+
+test('preview bots: GET passes, POST does not', async () => {
+  const hc = make();
+  assert.ok(passes(await hc.proxy(req('/film/x', { ua: 'TelegramBot (like TwitterBot)' }))));
+  assert.equal((await hc.proxy(req('/film/x', { ua: 'TelegramBot', method: 'POST', body: {} })))!.status, 302);
+});
+
+test('always-open paths and the out-of-scope marketing host are untouched; cabinet host is gated', async () => {
+  const hc = make({ scope: { kind: 'hosts', hosts: { 'app.example.com': 'site' } } });
+  for (const p of ['/robots.txt', '/sitemap.xml', '/.well-known/x', '/_next/static/a.js', '/api/og/film', '/healthz']) {
+    assert.equal(await hc.proxy(req(p)), undefined, p);
+  }
+  assert.equal(await hc.proxy(req('/pricing', { host: 'www.example.com' })), undefined);
+  assert.equal((await hc.proxy(req('/pricing', { host: 'app.example.com' })))!.status, 302);
+});
+
+test('missing keys in production: loud log once, gate on, nobody passes', async () => {
+  const logs: string[] = [];
+  const hc = make({}, { env: {}, log: (m) => logs.push(m) });
+  assert.equal(logs.length, 1);
+  assert.match(logs[0] ?? '', /misconfigured/);
+  assert.equal((await hc.proxy(req('/cabinet')))!.status, 302);
+  assert.match(await (await hc.proxy(req('/__human-check')))!.text(), /not configured correctly/);
+  const v = await hc.proxy(req('/__human-check', { method: 'POST', body: { token: 't' } }));
+  assert.equal(v!.status, 503);
+});
+
+function verifyDeps(response: unknown) {
+  return { fetch: (async () => jsonRes(response)) as typeof fetch };
+}
+
+test('verify: success sets a signed HttpOnly cookie and returns a safe next', async () => {
+  const hc = make({}, verifyDeps({ success: true, hostname: 'app.example.com', action: 'human-check' }));
+  const r = (await hc.proxy(req('/__human-check?next=/cabinet', { method: 'POST', body: { token: 't' } })))!;
+  assert.equal(r.status, 200);
+  assert.deepEqual(await r.json(), { ok: true, next: '/cabinet' });
+  const sc = r.headers.get('set-cookie')!;
+  assert.match(sc, /^__hc=v1\./);
+  assert.match(sc, /HttpOnly/i);
+  assert.match(sc, /SameSite=lax/i);
+  assert.match(sc, /Secure/i);
+});
+
+test('verify: next=https://evil.example falls back to /', async () => {
+  const hc = make({}, verifyDeps({ success: true, hostname: 'app.example.com', action: 'human-check' }));
+  const r = (await hc.proxy(req(`/__human-check?next=${encodeURIComponent('https://evil.example')}`, { method: 'POST', body: { token: 't' } })))!;
+  assert.equal((await r.json()).next, '/');
+});
+
+test('verify: wrong hostname or action is rejected without a cookie; reused token asks for a retry', async () => {
+  const host = await make({}, verifyDeps({ success: true, hostname: 'evil.example', action: 'human-check' })).proxy(req('/__human-check', { method: 'POST', body: { token: 't' } }));
+  assert.equal(host!.status, 403);
+  assert.equal(host!.headers.get('set-cookie'), null);
+  const act = await make({}, verifyDeps({ success: true, hostname: 'app.example.com', action: 'login' })).proxy(req('/__human-check', { method: 'POST', body: { token: 't' } }));
+  assert.equal(act!.status, 403);
+  const dup = (await make({}, verifyDeps({ success: false, 'error-codes': ['timeout-or-duplicate'] })).proxy(req('/__human-check', { method: 'POST', body: { token: 't' } })))!;
+  assert.deepEqual(await dup.json(), { ok: false, reason: 'timeout-or-duplicate', retry: true });
+});
+
+test('verify: cross-origin POST and empty token are refused', async () => {
+  const hc = make({}, verifyDeps({ success: true, hostname: 'app.example.com', action: 'human-check' }));
+  assert.equal((await hc.proxy(req('/__human-check', { method: 'POST', body: { token: 't' }, origin: 'https://evil.example' })))!.status, 403);
+  assert.equal((await hc.proxy(req('/__human-check', { method: 'POST', body: {} })))!.status, 400);
+});
+
+test('an already cleared visitor opening the gate is sent on to next', async () => {
+  const c = await signClearance('sek', BROWSER, 3600);
+  const r = (await make().proxy(req('/__human-check?next=/cabinet%3Fa%3D1', { cookie: `__hc=${c}` })))!;
+  assert.equal(r.status, 302);
+  assert.equal(new URL(r.headers.get('location')!).pathname + new URL(r.headers.get('location')!).search, '/cabinet?a=1');
+});

package/src/human-check/proxy.ts

@@ -0,0 +1,215 @@
+/**
+ * Human-check gate for Next.js (proxy / middleware).
+ *
+ * ```ts
+ * // proxy.ts
+ * import { createHumanCheck, withHumanCheck } from '@djangocfg/nextjs/human-check';
+ *
+ * const humanCheck = createHumanCheck({ enabled: true, scope: { kind: 'hosts', hosts: { 'app.example.com': 'site' } } });
+ * export default withHumanCheck(humanCheck, intlProxy);
+ * ```
+ *
+ * The proxy serves the gate route itself (GET page, POST verify), so no app
+ * route is needed (an `app/__human-check` folder would be a private folder
+ * and never routable). Order: disabled -> dev skip -> always-open paths ->
+ * gate route -> scope -> crawler/preview bypass -> valid cookie -> 302 to gate.
+ */
+
+import { isDev as apiIsDev } from '@djangocfg/api';
+import { NextResponse } from 'next/server';
+
+import { parseSecrets, signClearance, verifyClearance } from './cookie';
+import { createCrawlerMatcher, isPreviewBot, type CrawlerMatcher } from './crawlers';
+import { MESSAGES, pickLocale } from './messages';
+import { renderHumanCheckHtml } from './page';
+import { ALWAYS_OPEN_PATHS, resolveConfig, type HumanCheckConfig, type ResolvedHumanCheckConfig } from './types';
+import { inScope, matchAny, safeNext } from './scope';
+import { verifyTurnstile } from './turnstile';
+
+import type { NextRequest } from 'next/server';
+
+export interface HumanCheckDeps {
+  /** Test seam. Default: `isDev` from `@djangocfg/api`. */
+  isDev?: boolean;
+  fetch?: typeof fetch;
+  now?: () => number;
+  env?: Record<string, string | undefined>;
+  crawlers?: CrawlerMatcher;
+  log?: (msg: string) => void;
+}
+
+export type HumanCheckDecision = 'disabled' | 'dev' | 'open' | 'out-of-scope' | 'crawler' | 'preview' | 'cleared' | 'gate';
+
+const GATE_HEADERS = {
+  'Content-Type': 'text/html; charset=utf-8',
+  'X-Robots-Tag': 'noindex, nofollow',
+  'Cache-Control': 'private, no-store',
+  'Referrer-Policy': 'no-referrer',
+};
+
+export function clientIp(h: Headers, trustCloudflare: boolean): string | null {
+  if (trustCloudflare) {
+    const cf = h.get('cf-connecting-ip');
+    if (cf) return cf.trim();
+  }
+  return h.get('x-real-ip')?.trim() ?? h.get('x-forwarded-for')?.split(',')[0]?.trim() ?? null;
+}
+
+export function createHumanCheck(userConfig: HumanCheckConfig = {}, deps: HumanCheckDeps = {}) {
+  const cfg: ResolvedHumanCheckConfig = resolveConfig(userConfig);
+  const env = deps.env ?? process.env;
+  const dev = () => deps.isDev ?? apiIsDev;
+  const now = deps.now ?? Date.now;
+  const log = deps.log ?? ((m: string) => console.error(m));
+
+  /** The dev check comes first, before scope, cookie and Turnstile. */
+  const active = () => cfg.enabled && !(dev() && cfg.enabledIn !== 'all');
+
+  const crawlers =
+    deps.crawlers ??
+    (cfg.bypass.crawlers
+      ? createCrawlerMatcher({ sources: cfg.bypass.crawlerSources, fetch: deps.fetch, now: deps.now })
+      : null);
+
+  const secrets = () => parseSecrets(env[cfg.cookie.secretEnv]);
+  const siteKey = () => env[cfg.turnstile.siteKeyEnv] || null;
+  const turnstileSecret = () => env[cfg.turnstile.secretKeyEnv] || null;
+  const misconfigured = () => secrets().length === 0 || !siteKey() || !turnstileSecret();
+
+  // Fail closed and loud: gate on, never a silent pass.
+  if (active() && misconfigured()) {
+    log(
+      `[human-check] ENABLED but misconfigured: set ${cfg.cookie.secretEnv}, ${cfg.turnstile.siteKeyEnv} and ${cfg.turnstile.secretKeyEnv}. ` +
+        'Every in-scope request will be sent to the gate and no one can pass.',
+    );
+  }
+
+  const page = (req: NextRequest, status = 200) => {
+    const locale = pickLocale(req.nextUrl.searchParams.get('lang'), req.headers.get('accept-language'), cfg.message.defaultLocale);
+    const messages = { ...MESSAGES[locale], ...(cfg.message.overrides[locale] ?? {}) };
+    const key = misconfigured() ? null : siteKey();
+    const html = renderHumanCheckHtml({ locale, messages, mode: cfg.message.mode, siteKey: key, action: cfg.turnstile.action });
+    return new NextResponse(req.method === 'HEAD' ? null : html, { status, headers: GATE_HEADERS });
+  };
+
+  async function verifyPost(req: NextRequest): Promise<NextResponse> {
+    const json = (body: unknown, status: number) =>
+      NextResponse.json(body, { status, headers: { 'Cache-Control': 'private, no-store', 'X-Robots-Tag': 'noindex, nofollow' } });
+    const origin = req.headers.get('origin');
+    if (origin) {
+      let host = '';
+      try {
+        host = new URL(origin).host;
+      } catch {
+        /* invalid origin falls through to the mismatch below */
+      }
+      if (host !== req.nextUrl.host) return json({ ok: false, reason: 'bad-origin', retry: false }, 403);
+    }
+    if (misconfigured()) return json({ ok: false, reason: 'misconfigured', retry: false }, 503);
+    let token = '';
+    try {
+      const body = (await req.json()) as { token?: unknown };
+      if (typeof body.token === 'string') token = body.token;
+    } catch {
+      /* empty token is rejected below */
+    }
+    if (!token || token.length > 4096) return json({ ok: false, reason: 'no-token', retry: true }, 400);
+    const result = await verifyTurnstile({
+      secret: turnstileSecret()!,
+      token,
+      remoteIp: clientIp(req.headers, cfg.bypass.trustCloudflareIp),
+      expectedHostnames: cfg.turnstile.hostnames ?? [req.nextUrl.hostname],
+      expectedAction: cfg.turnstile.action,
+      fetch: deps.fetch,
+    });
+    if (!result.ok) return json({ ok: false, reason: result.reason, retry: result.retry }, 403);
+    const signer = secrets()[0];
+    if (!signer) return json({ ok: false, reason: 'misconfigured', retry: false }, 503);
+    const value = await signClearance(signer, req.headers.get('user-agent'), cfg.cookie.ttlSeconds, now());
+    const res = json({ ok: true, next: safeNext(req.nextUrl.searchParams.get('next'), cfg.gatePath) }, 200);
+    res.cookies.set(cfg.cookie.name, value, {
+      httpOnly: true,
+      secure: req.nextUrl.protocol === 'https:',
+      sameSite: 'lax',
+      path: '/',
+      maxAge: cfg.cookie.ttlSeconds,
+    });
+    return res;
+  }
+
+  async function decide(req: NextRequest): Promise<HumanCheckDecision> {
+    if (!cfg.enabled) return 'disabled';
+    if (!active()) return 'dev';
+    const { pathname } = req.nextUrl;
+    if (matchAny(ALWAYS_OPEN_PATHS, pathname) || matchAny(cfg.bypass.paths, pathname)) return 'open';
+    if (!inScope(cfg.scope, req.nextUrl.hostname, pathname)) return 'out-of-scope';
+    const ua = req.headers.get('user-agent');
+    if (cfg.bypass.previewBots && (req.method === 'GET' || req.method === 'HEAD') && isPreviewBot(ua)) return 'preview';
+    if (crawlers) {
+      const verdict = await crawlers.check(clientIp(req.headers, cfg.bypass.trustCloudflareIp), ua);
+      if (verdict === 'verified' || (verdict === 'unknown' && cfg.bypass.onListUnavailable === 'allow-claimed')) return 'crawler';
+    }
+    if (await verifyClearance(secrets(), req.cookies.get(cfg.cookie.name)?.value, ua, now())) return 'cleared';
+    return 'gate';
+  }
+
+  /**
+   * Returns a response when the gate handles the request (gate page, verify, redirect, or a
+   * pass-through with cache headers) and `undefined` when the request is none of its business.
+   */
+  async function proxy(req: NextRequest): Promise<NextResponse | undefined> {
+    const { pathname } = req.nextUrl;
+    if (pathname === cfg.gatePath) {
+      // Off and dev: the route does not exist.
+      if (!active()) return new NextResponse(null, { status: 404, headers: { 'Cache-Control': 'private, no-store' } });
+      if (req.method === 'POST') return verifyPost(req);
+      if (req.method !== 'GET' && req.method !== 'HEAD') return new NextResponse(null, { status: 405, headers: { Allow: 'GET, HEAD, POST' } });
+      if (await verifyClearance(secrets(), req.cookies.get(cfg.cookie.name)?.value, req.headers.get('user-agent'), now())) {
+        const to = req.nextUrl.clone();
+        const [p, q] = safeNext(req.nextUrl.searchParams.get('next'), cfg.gatePath).split('?');
+        to.pathname = p ?? '/';
+        to.search = q ? `?${q}` : '';
+        return NextResponse.redirect(to, 302);
+      }
+      return page(req);
+    }
+
+    const decision = await decide(req);
+    switch (decision) {
+      case 'gate': {
+        const to = req.nextUrl.clone();
+        const next = `${pathname}${req.nextUrl.search}`;
+        to.pathname = cfg.gatePath;
+        to.search = `?next=${encodeURIComponent(next)}`;
+        const res = NextResponse.redirect(to, 302);
+        res.headers.set('Cache-Control', 'private, no-store');
+        res.headers.set('X-Robots-Tag', 'noindex, nofollow');
+        return res;
+      }
+      case 'crawler':
+      case 'preview':
+      case 'cleared': {
+        if (cfg.cache === 'leave') return undefined;
+        // A crawler response must not be cached and served to a human without a cookie.
+        const res = NextResponse.next();
+        res.headers.set('Cache-Control', 'private, no-store');
+        res.headers.append('Vary', 'Cookie, User-Agent');
+        return res;
+      }
+      default:
+        return undefined;
+    }
+  }
+
+  return { proxy, decide, config: cfg };
+}
+
+export type HumanCheck = ReturnType<typeof createHumanCheck>;
+
+/** Compose with another proxy (e.g. the i18n one): the gate runs first. */
+export function withHumanCheck<A extends unknown[], R>(
+  humanCheck: HumanCheck,
+  next: (req: NextRequest, ...args: A) => R | Promise<R>,
+) {
+  return async (req: NextRequest, ...args: A): Promise<NextResponse | R> => (await humanCheck.proxy(req)) ?? next(req, ...args);
+}

package/src/human-check/scope.test.ts

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import type { HumanCheckScope } from './types';
+import { inScope, matchHost, matchPath, safeNext } from './scope';
+
+test('path patterns: exact, prefix, star suffix', () => {
+  assert.ok(matchPath('/app/*', '/app'));
+  assert.ok(matchPath('/app/*', '/app/x/y'));
+  assert.ok(!matchPath('/app/*', '/apple'));
+  assert.ok(matchPath('/sitemap*', '/sitemap-1.xml'));
+  assert.ok(matchPath('/pricing', '/pricing'));
+  assert.ok(!matchPath('/pricing', '/pricing/x'));
+});
+
+test('host patterns', () => {
+  assert.ok(matchHost('app.example.com', 'APP.example.com'));
+  assert.ok(matchHost('*.example.com', 'a.example.com'));
+  assert.ok(!matchHost('*.example.com', 'example.com'));
+  assert.ok(!matchHost('*.example.com', 'evilexample.com'));
+});
+
+test('site, routes and hosts scopes; marketing open, cabinet gated', () => {
+  assert.ok(inScope({ kind: 'site' }, 'x.com', '/anything'));
+  const routes: HumanCheckScope = { kind: 'routes', include: ['/cabinet/*'], exclude: ['/cabinet/public/*'] };
+  assert.ok(inScope(routes, 'x.com', '/cabinet/a'));
+  assert.ok(!inScope(routes, 'x.com', '/cabinet/public/a'));
+  assert.ok(!inScope(routes, 'x.com', '/pricing'));
+  const hosts: HumanCheckScope = { kind: 'hosts', hosts: { 'app.x.com': 'site', 'x.com': { include: ['/admin/*'] } } };
+  assert.ok(inScope(hosts, 'app.x.com', '/'));
+  assert.ok(inScope(hosts, 'x.com', '/admin/u'));
+  assert.ok(!inScope(hosts, 'x.com', '/'));
+  assert.ok(!inScope(hosts, 'other.com', '/'), 'unlisted host is not gated');
+});
+
+test('next must be a same-origin relative path', () => {
+  const g = '/__human-check';
+  assert.equal(safeNext('/a?b=1', g), '/a?b=1');
+  for (const bad of ['https://evil.example', '//evil.example', '/\\evil.example', 'javascript:1', '/a\r\nb', '', null, undefined, '/__human-check?next=/']) {
+    assert.equal(safeNext(bad as string, g), '/', String(bad));
+  }
+});

package/src/human-check/scope.ts

@@ -0,0 +1,57 @@
+import type { HumanCheckScope, ScopeRule } from './types';
+
+/**
+ * Path pattern: exact (`/pricing`), prefix (`/app/*` matches `/app` and everything under it)
+ * or bare-star suffix (`/sitemap*` matches `/sitemap.xml`, `/sitemap-1.xml`).
+ */
+export function matchPath(pattern: string, pathname: string): boolean {
+  if (pattern.endsWith('/*')) {
+    const base = pattern.slice(0, -2);
+    return pathname === base || pathname.startsWith(`${base}/`);
+  }
+  if (pattern.endsWith('*')) return pathname.startsWith(pattern.slice(0, -1));
+  return pathname === pattern;
+}
+
+export const matchAny = (patterns: readonly string[], pathname: string) => patterns.some((p) => matchPath(p, pathname));
+
+/** Host pattern: exact or `*.example.com`. Case-insensitive, port ignored. */
+export function matchHost(pattern: string, hostname: string): boolean {
+  const h = hostname.toLowerCase();
+  const p = pattern.toLowerCase();
+  if (p.startsWith('*.')) return h.endsWith(p.slice(1)) && h.length > p.length - 1;
+  return h === p;
+}
+
+function applyRule(rule: ScopeRule, pathname: string): boolean {
+  if (rule === 'site') return true;
+  if (rule.exclude && matchAny(rule.exclude, pathname)) return false;
+  return matchAny(rule.include, pathname);
+}
+
+/** Is this host+path inside the gated scope? A host that is not listed in a `hosts` scope is not gated. */
+export function inScope(scope: HumanCheckScope, hostname: string, pathname: string): boolean {
+  switch (scope.kind) {
+    case 'site':
+      return true;
+    case 'routes':
+      return applyRule({ include: scope.include, exclude: scope.exclude }, pathname);
+    case 'hosts': {
+      for (const [host, rule] of Object.entries(scope.hosts)) {
+        if (matchHost(host, hostname)) return applyRule(rule, pathname);
+      }
+      return false;
+    }
+  }
+}
+
+/** `next` must be a same-origin relative path. Anything else becomes `/`. */
+export function safeNext(raw: string | null | undefined, gatePath: string): string {
+  if (!raw || raw.length > 2048) return '/';
+  if (!raw.startsWith('/') || raw.startsWith('//') || raw.startsWith('/\\')) return '/';
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f\\]/.test(raw)) return '/';
+  const path = raw.split(/[?#]/, 1)[0];
+  if (path === gatePath) return '/';
+  return raw;
+}

package/src/human-check/turnstile.ts

@@ -0,0 +1,45 @@
+export const SITEVERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
+
+export interface SiteverifyResponse {
+  success: boolean;
+  hostname?: string;
+  action?: string;
+  'error-codes'?: string[];
+}
+
+export type VerifyResult = { ok: true } | { ok: false; reason: string; retry: boolean };
+
+/**
+ * Server-side Turnstile check. `success` alone is not enough: the token must
+ * have been issued for this host and this action, or a token minted on any
+ * other site that shares the key would clear the gate.
+ */
+export async function verifyTurnstile(args: {
+  secret: string;
+  token: string;
+  remoteIp?: string | null;
+  expectedHostnames: string[];
+  expectedAction: string;
+  fetch?: typeof fetch;
+}): Promise<VerifyResult> {
+  const body = new URLSearchParams({ secret: args.secret, response: args.token });
+  if (args.remoteIp) body.set('remoteip', args.remoteIp);
+  let data: SiteverifyResponse;
+  try {
+    const res = await (args.fetch ?? fetch)(SITEVERIFY_URL, { method: 'POST', body, signal: AbortSignal.timeout(5000) });
+    data = (await res.json()) as SiteverifyResponse;
+  } catch {
+    return { ok: false, reason: 'siteverify-unreachable', retry: true };
+  }
+  if (!data.success) {
+    const codes = data['error-codes'] ?? [];
+    // An expired or reused token is fixed by a new widget run.
+    const retry = codes.includes('timeout-or-duplicate') || codes.includes('invalid-input-response');
+    return { ok: false, reason: codes[0] ?? 'rejected', retry };
+  }
+  if (!data.hostname || !args.expectedHostnames.some((h) => h.toLowerCase() === data.hostname!.toLowerCase())) {
+    return { ok: false, reason: 'hostname-mismatch', retry: false };
+  }
+  if (data.action !== args.expectedAction) return { ok: false, reason: 'action-mismatch', retry: false };
+  return { ok: true };
+}