—Системен статус
Документация

TrueSift Next.js SDK

Само за React / Next.js App Router. За Svelte 5 / SvelteKit вижте документацията на Svelte SDK.

Официалният пакет @truesift/next предоставя клиентски компонент за проверка, локални Next.js App Router обработчици и сървърна проверка на proof преди изпълнение на защитено действие. Текуща версия: 0.4.0.

Инсталация

bash
pnpm add @truesift/next

Архитектура на проверката

  1. Браузър: TrueSiftCheck изпраща заявки само към локални challenge/verify API маршрути и получава краткоживеещ непрозрачен verificationToken.
  2. Next.js сървър: локалните маршрути комуникират с TrueSift API; ключовете и външните заявки остават скрити за браузъра.
  3. Защитен бизнес маршрут: сам определя очакваните action, path и origin и консумира еднократния proof преди изпълнение на действието.

Интеграция с Next.js App Router

Променливи на средата само за сървъра

env
TRUESIFT_API_BASE_URL=https://api.truesift.de
TRUESIFT_SITE_KEY=your_site_key
TRUESIFT_SECRET_KEY=your_secret_key
TRUESIFT_DEFAULT_ACTION=website_check
TRUESIFT_FAIL_OPEN=false
TRUESIFT_TIMEOUT_MS=2500

TRUESIFT_API_BASE_URL must be the service origin only, without /api/v1 or endpoint suffixes. Never use NEXT_PUBLIC_ for credentials.

Локални API обработчици

src/app/api/truesift/challenge/route.ts

ts
import { createTrueSiftChallengeHandler } from "@truesift/next/server";

export const dynamic = "force-dynamic";
export const runtime = "nodejs";

export const POST = createTrueSiftChallengeHandler({
  apiBaseUrl: process.env.TRUESIFT_API_BASE_URL,
  siteKey: process.env.TRUESIFT_SITE_KEY,
  secretKey: process.env.TRUESIFT_SECRET_KEY,
  defaultAction: process.env.TRUESIFT_DEFAULT_ACTION,
  failOpen: process.env.TRUESIFT_FAIL_OPEN === "true",
  timeoutMs: Number(process.env.TRUESIFT_TIMEOUT_MS ?? 2500)
});

src/app/api/truesift/verify/route.ts

ts
import { createTrueSiftVerifyHandler } from "@truesift/next/server";

export const dynamic = "force-dynamic";
export const runtime = "nodejs";

export const POST = createTrueSiftVerifyHandler({
  apiBaseUrl: process.env.TRUESIFT_API_BASE_URL,
  siteKey: process.env.TRUESIFT_SITE_KEY,
  secretKey: process.env.TRUESIFT_SECRET_KEY,
  defaultAction: process.env.TRUESIFT_DEFAULT_ACTION,
  failOpen: process.env.TRUESIFT_FAIL_OPEN === "true",
  timeoutMs: Number(process.env.TRUESIFT_TIMEOUT_MS ?? 2500)
});

The browser calls /api/truesift/challenge and /api/truesift/verify. These local routes forward to the upstream challenge/verify endpoints; never expose the proof-verification endpoint as a public browser proxy.

Клиентски компонент

tsx
"use client";

import { useState } from "react";
import { TrueSiftCheck } from "@truesift/next/client";

export function SecurityCheck() {
  const [verificationToken, setVerificationToken] = useState<string | null>(null);

  return (
    <TrueSiftCheck
      action="contact_form"
      path="/contact"
      challengeUrl="/api/truesift/challenge"
      verifyUrl="/api/truesift/verify"
      onVerified={(result) => setVerificationToken(result.verificationToken ?? null)}
      onError={() => setVerificationToken(null)}
    />
  );
}

Send verificationToken with the protected form submission. The action and path here are illustrative; replace them with the real protected action and route. Do not trust the UI state as authorization.

Защитен бизнес маршрут

ts
import { verifyTrueSiftProof } from "@truesift/next/server";

export async function POST(request: Request): Promise<Response> {
  const body: unknown = await request.json();
  const verificationToken =
    typeof body === "object" && body !== null &&
    "verificationToken" in body &&
    typeof body.verificationToken === "string"
      ? body.verificationToken
      : "";

  const proof = await verifyTrueSiftProof({
    verificationToken,
    expectedAction: "contact_form",
    expectedPath: "/contact",
    expectedOrigin: "https://example.com"
  });

  if (!proof.allowed) {
    return Response.json(
      { error: "TRUESIFT_PROOF_REJECTED", reason: proof.reason },
      { status: proof.reason === "unavailable" ? 503 : 403 }
    );
  }

  // Execute the protected operation only after the server-side decision.
  return Response.json({ success: true });
}

The expected context must be defined by the business route, never copied from the browser. Replace example values with the actual action, route, and origin. On service unavailability, a trusted server-side fail-open policy may return allowed: true with ok: false; handle that explicitly according to your risk policy.

Behavioral Signals v2 (0.4.0)

Опционалният браузърен колектор отчита само агрегирани движения и натискания на показалеца, скролиране, докосвания, клавиатурни събития, focus/blur, промени във видимостта, взаимодействия с проверката и времеви показатели. Прозорецът за наблюдение е 2500 ms и може да се прекъсва. Броячите се нулират при всяка проверка, а обработчиците на събития се освобождават при прекъсване, повторен опит и демонтиране. Не се събират натиснати клавиши, координати, съдържание на форми, DOM идентичности, fingerprint или постоянни идентификатори. Липсващите сигнали сами по себе си не доказват бот. Старият протокол остава съвместим.

Граница на доверие и решения

Клиентски полета като allowed, decision, score, failOpen, action, path и origin не дават право за изпълнение. Единственото приемано клиентско доказателство е непрозрачният verificationToken. Само сървърно потвърден allow може да разреши действието. review, block, липсващи, невалидни, изтекли, повторно използвани или несъвпадащи proof токени се отхвърлят. Fail-open е единствено сървърна политика и следва да е изключена за високорискови действия.

Грешки и достъпност

Невалидни ключове (401), забранен/неактивен сайт (403) и неправилна сървърна конфигурация са отделни грешки, а не недостъпност. Мрежови проблеми, timeout и временни грешки на външната услуга връщат unavailable. failOpen: true не означава успешно валидиран proof (ok остава false).

Визуализация и преводи

Компонентът поддържа режими checkbox, banner, inline, badge; размери normal, compact, flexible; теми auto, light, dark; езици auto, en, de, bg. Анимацията има SVG резервен вариант. Свойството lottie управлява визуалното поведение.

Промени по версии

0.4.0 (12.10.2026): добавени Behavioral Signals v2, прекъсваем прозорец за наблюдение, препращане през локалния verify обработчик и допълнителни тестове на жизнения цикъл. 0.3.0 (16.08.2026): Behavioral Signals v1. 0.2.0 (31.07.2026): сървърна функция verifyTrueSiftProof и детерминирана оценка на proof.

Допълнителна информация

Вижте преглед на SDK, интерактивната SDK страница, npm пакета и официалния сайт.