@djangocfg/nextjs 2.1.595 → 2.1.596

package/dist/human-check/index.d.mts

@@ -0,0 +1,252 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+declare const claimsCrawler: (ua: string | null) => boolean;
+declare const isPreviewBot: (ua: string | null) => boolean;
+type CrawlerVerdict = 'verified' | 'spoofed' | 'unknown' | 'none';
+interface CrawlerMatcherOptions {
+    sources: string[];
+    ttlMs?: number;
+    staleAfterMs?: number;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** Called (at most once per hour) when the last good list is older than `staleAfterMs`. */
+    onStale?: (ageMs: number) => void;
+}
+declare function createCrawlerMatcher(opts: CrawlerMatcherOptions): {
+    /** `verified`: IP is in a published range. `spoofed`: UA claims a crawler, lists loaded, IP not in them. `unknown`: UA claims a crawler, no list ever loaded. `none`: not a crawler claim and not in ranges. */
+    check(ip: string | null, ua: string | null): Promise<CrawlerVerdict>;
+    state: () => {
+        loadedAt: number;
+        attemptedAt: number;
+        ranges: number;
+    };
+};
+type CrawlerMatcher = ReturnType<typeof createCrawlerMatcher>;
+
+/**
+ * Human-check gate: configuration types and defaults.
+ *
+ * Off by default. The gate is a request, not a wall: the enforcement is the
+ * server-verified Turnstile cookie, the visible text only asks cooperating
+ * agents to stop. See `@dev/planned/bot-check-gate/PLAN.md`.
+ */
+type HumanCheckLocale = 'en' | 'ru';
+interface HumanCheckMessages {
+    title: string;
+    /** Stop text for agents. Rendered server-side, before any script. */
+    stop: string;
+    /** Text for people. */
+    human: string;
+    checking: string;
+    verifying: string;
+    done: string;
+    failed: string;
+    blocked: string;
+    misconfigured: string;
+    noscript: string;
+}
+type ScopeRule = 'site' | {
+    include: string[];
+    exclude?: string[];
+};
+type HumanCheckScope = {
+    kind: 'site';
+} | {
+    kind: 'routes';
+    include: string[];
+    exclude?: string[];
+}
+/** Per host. A host that is not listed is NOT gated (e.g. the marketing host). */
+ | {
+    kind: 'hosts';
+    hosts: Record<string, ScopeRule>;
+};
+interface HumanCheckConfig {
+    /** Master switch. Default false. */
+    enabled?: boolean;
+    /**
+     * `production` (default): the gate never runs when `isDev` from
+     * `@djangocfg/api` is true. `all`: it runs in development too.
+     * Note `NODE_ENV=production` is also what staging builds use; limit staging
+     * with `scope: { kind: 'hosts' }`.
+     */
+    enabledIn?: 'production' | 'all';
+    scope?: HumanCheckScope;
+    /** Path of the gate route, served by the proxy itself. Default `/__human-check`. */
+    gatePath?: string;
+    message?: {
+        mode?: 'agent-visible' | 'plain';
+        /** Per-locale overrides. */
+        overrides?: Partial<Record<HumanCheckLocale, Partial<HumanCheckMessages>>>;
+        defaultLocale?: HumanCheckLocale;
+    };
+    cookie?: {
+        name?: string;
+        ttlSeconds?: number;
+        /** Env var holding the signing secret. Comma-separated: first signs, all verify (rotation). */
+        secretEnv?: string;
+    };
+    turnstile?: {
+        siteKeyEnv?: string;
+        secretKeyEnv?: string;
+        /** Informational: the mode is a property of the widget in Cloudflare. */
+        mode?: 'non-interactive' | 'managed';
+        action?: string;
+        /** Hostnames Turnstile may report. Default: the request hostname. */
+        hostnames?: string[];
+    };
+    bypass?: {
+        crawlers?: boolean;
+        previewBots?: boolean;
+        /** Extra always-open paths (same pattern syntax as scope). */
+        paths?: string[];
+        /** Crawler IP lists (JSON with `prefixes`). Default: Google and Bing lists. */
+        crawlerSources?: string[];
+        /**
+         * When no crawler list has ever loaded: `allow-claimed` (default) lets a
+         * UA that claims to be a crawler through, so an outage cannot de-index the
+         * site; `gate` gates it.
+         */
+        onListUnavailable?: 'allow-claimed' | 'gate';
+        /** Trust `cf-connecting-ip` (only when the origin accepts Cloudflare traffic only). */
+        trustCloudflareIp?: boolean;
+    };
+    /** `private` (default): in-scope responses get `Cache-Control: private, no-store`. `leave`: do not touch. */
+    cache?: 'private' | 'leave';
+}
+interface ResolvedHumanCheckConfig {
+    enabled: boolean;
+    enabledIn: 'production' | 'all';
+    scope: HumanCheckScope;
+    gatePath: string;
+    message: {
+        mode: 'agent-visible' | 'plain';
+        overrides: Partial<Record<HumanCheckLocale, Partial<HumanCheckMessages>>>;
+        defaultLocale: HumanCheckLocale;
+    };
+    cookie: {
+        name: string;
+        ttlSeconds: number;
+        secretEnv: string;
+    };
+    turnstile: {
+        siteKeyEnv: string;
+        secretKeyEnv: string;
+        mode: 'non-interactive' | 'managed';
+        action: string;
+        hostnames?: string[];
+    };
+    bypass: {
+        crawlers: boolean;
+        previewBots: boolean;
+        paths: string[];
+        crawlerSources: string[];
+        onListUnavailable: 'allow-claimed' | 'gate';
+        trustCloudflareIp: boolean;
+    };
+    cache: 'private' | 'leave';
+}
+declare const DEFAULT_CRAWLER_SOURCES: string[];
+/** Paths that are never gated: crawl infrastructure, assets, OG images, health, webhooks. */
+declare const ALWAYS_OPEN_PATHS: string[];
+declare function resolveConfig(c?: HumanCheckConfig): ResolvedHumanCheckConfig;
+
+/**
+ * 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.
+ */
+
+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;
+}
+type HumanCheckDecision = 'disabled' | 'dev' | 'open' | 'out-of-scope' | 'crawler' | 'preview' | 'cleared' | 'gate';
+declare function clientIp(h: Headers, trustCloudflare: boolean): string | null;
+declare function createHumanCheck(userConfig?: HumanCheckConfig, deps?: HumanCheckDeps): {
+    proxy: (req: NextRequest) => Promise<NextResponse | undefined>;
+    decide: (req: NextRequest) => Promise<HumanCheckDecision>;
+    config: ResolvedHumanCheckConfig;
+};
+type HumanCheck = ReturnType<typeof createHumanCheck>;
+/** Compose with another proxy (e.g. the i18n one): the gate runs first. */
+declare function withHumanCheck<A extends unknown[], R>(humanCheck: HumanCheck, next: (req: NextRequest, ...args: A) => R | Promise<R>): (req: NextRequest, ...args: A) => Promise<NextResponse | R>;
+
+/**
+ * Wording is a neutral notice about the page's own state, not an override of
+ * the user's task: agents may treat instruction-like page text as prompt
+ * injection. To be tuned by the live test (PLAN task A1).
+ */
+declare const MESSAGES: Record<HumanCheckLocale, HumanCheckMessages>;
+
+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;
+}
+/**
+ * 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.
+ */
+declare function renderHumanCheckHtml(o: PageOptions): string;
+
+/**
+ * Path pattern: exact (`/pricing`), prefix (`/app/*` matches `/app` and everything under it)
+ * or bare-star suffix (`/sitemap*` matches `/sitemap.xml`, `/sitemap-1.xml`).
+ */
+declare function matchPath(pattern: string, pathname: string): boolean;
+/** Host pattern: exact or `*.example.com`. Case-insensitive, port ignored. */
+declare function matchHost(pattern: string, hostname: string): boolean;
+/** Is this host+path inside the gated scope? A host that is not listed in a `hosts` scope is not gated. */
+declare function inScope(scope: HumanCheckScope, hostname: string, pathname: string): boolean;
+/** `next` must be a same-origin relative path. Anything else becomes `/`. */
+declare function safeNext(raw: string | null | undefined, gatePath: string): string;
+
+declare function signClearance(secret: string, ua: string | null, ttlSeconds: number, now?: number): Promise<string>;
+declare function verifyClearance(secrets: string[], value: string | undefined, ua: string | null, now?: number): Promise<boolean>;
+
+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.
+ */
+declare function verifyTurnstile(args: {
+    secret: string;
+    token: string;
+    remoteIp?: string | null;
+    expectedHostnames: string[];
+    expectedAction: string;
+    fetch?: typeof fetch;
+}): Promise<VerifyResult>;
+
+export { ALWAYS_OPEN_PATHS, type CrawlerMatcher, type CrawlerVerdict, DEFAULT_CRAWLER_SOURCES, type HumanCheck, type HumanCheckConfig, type HumanCheckDecision, type HumanCheckDeps, type HumanCheckLocale, type HumanCheckMessages, type HumanCheckScope, MESSAGES, type ScopeRule, claimsCrawler, clientIp, createCrawlerMatcher, createHumanCheck, inScope, isPreviewBot, matchHost, matchPath, renderHumanCheckHtml, resolveConfig, safeNext, signClearance, verifyClearance, verifyTurnstile, withHumanCheck };