—Systemstatus
Dokumentation

TrueSift Next.js SDK

Nur für React / Next.js App Router. Für Svelte 5 / SvelteKit siehe die Svelte-SDK-Dokumentation.

Das offizielle Paket @truesift/next bietet ein Client-Prüfwidget, lokale Next.js-App-Router-Handler und die serverseitige Prüfung des Business-Proofs. Aktuelle Version: 0.4.0.

Installation

bash
pnpm add @truesift/next

Architektur der Verifikation

  1. Browser: TrueSiftCheck ruft ausschließlich lokale Challenge-/Verify-API-Routen auf und erhält ein kurzlebiges, undurchsichtiges verificationToken.
  2. Next.js-Server: Lokale Routen kommunizieren mit der TrueSift-API. Zugangsdaten und Upstream-Aufrufe bleiben vom Browser getrennt.
  3. Geschützte Business-Route: Definiert die erwartete Action, den Path und Origin selbst und verbraucht den einmaligen Proof vor der Aktion.

Integration mit Next.js App Router

Serverseitige Umgebungsvariablen

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.

Lokale API-Handler für den Browser

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.

Client-Komponente

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.

Geschützte Business-Route

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)

Der optionale Browser-Collector zählt ausschließlich aggregierte Pointer-Bewegungen/Klicks, Scroll-, Touch-, Tastatur-, Fokus-/Blur-, Sichtbarkeits- und Challenge-Interaktionen sowie Zeitwerte. Das abbrechbare Beobachtungsfenster beträgt 2.500 ms. Bei jeder Prüfung werden die Signale zurückgesetzt; Event-Listener werden bei Abbruch, Wiederholung und Unmount entfernt. Es werden weder Tasteninhalte, Koordinaten, Formularwerte, DOM-Identitäten, Fingerprints noch persistente Besucherkennungen erfasst. Fehlende oder unzureichende Telemetrie ist allein kein Bot-Nachweis. Ältere Integrationen bleiben kompatibel.

Sicherheitsgrenze und Entscheidungen

Clientseitige Werte wie allowed, decision, score, failOpen, action, path und origin dürfen keine Aktion autorisieren. Nur das undurchsichtige verificationToken ist ein zulässiger clientseitiger Proof-Eingang. Ein serverseitig bestätigtes allow kann autorisieren; review, block sowie fehlende, ungültige, abgelaufene, wiederverwendete oder unpassende Proofs bleiben gesperrt. Fail-open ist ausschließlich eine serverseitige Richtlinie und sollte bei risikoreichen Aktionen deaktiviert bleiben.

Fehler und Verfügbarkeit

Ungültige Zugangsdaten (401), gesperrte/inaktive Sites (403) und ungültige Serverkonfiguration sind keine gewöhnliche Nichtverfügbarkeit. Netzwerkfehler, Zeitüberschreitungen und wiederholbare Upstream-Fehler liefern unavailable. failOpen: true bedeutet keine erfolgreiche Proof-Validierung (ok bleibt false).

Darstellung und Lokalisierung

Unterstützte Layouts: checkbox, banner, inline, badge; Größen: normal, compact, flexible; Themes: auto, light, dark; Sprachen: auto, en, de, bg. Für die Animation steht ein SVG-Fallback bereit. Die lottie-Option konfiguriert die visuelle Darstellung.

Änderungen nach Version

0.4.0 (12.10.2026): optionale aggregierte Behavioral Signals v2, abbrechbare Beobachtung, Weiterleitung über lokale Verify-Handler und zusätzliche Lifecycle-Tests. 0.3.0 (16.08.2026): Behavioral Signals v1. 0.2.0 (31.07.2026): serverseitiger verifyTrueSiftProof und eindeutige Proof-Entscheidungen.

Weitere Informationen

Siehe SDK-Übersicht, interaktive SDK-Seite, npm-Paket und TrueSift-Webseite.