Next.js

npm install @shieldlabs-ai/next @shieldlabs-ai/react @shieldlabs-ai/js @shieldlabs-ai/node

// app/layout.tsx (a Server Component: ShieldLabsProvider is a client component inside it)
import type { ReactNode } from 'react';
import { ShieldLabsProvider } from '@shieldlabs-ai/next';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ShieldLabsProvider publicKey={process.env.NEXT_PUBLIC_SHIELDLABS_PUBLIC_KEY!}>
          {children}
        </ShieldLabsProvider>
      </body>
    </html>
  );
}

// app/signup/page.tsx
import { SignupForm } from './signup-form';

export default function SignupPage() {
  return (
    <main>
      <h1>Create an account</h1>
      <SignupForm />
    </main>
  );
}

// app/signup/signup-form.tsx
'use client';

import { useState, type SyntheticEvent } from 'react';
import { useIdentify } from '@shieldlabs-ai/next';
import { signup } from './actions';

export function SignupForm() {
  const { identify, isLoading } = useIdentify();
  const [message, setMessage] = useState('');

  async function onSubmit(event: SyntheticEvent<HTMLFormElement>) {
    event.preventDefault();
    const formData = new FormData(event.currentTarget);
    // null when there is no identification (a content blocker, a timeout): the signup goes out
    // anyway, and the Server Action treats it as unverified.
    const result = await identify();
    if (result) formData.set('requestId', result.requestId);
    const { ok } = await signup(formData);
    setMessage(ok ? 'Account created.' : 'We could not create your account.');
  }

  return (
    <form onSubmit={onSubmit}>
      <input name="email" type="email" required />
      <button disabled={isLoading}>Sign up</button>
      <p role="status">{message}</p>
    </form>
  );
}

// app/signup/actions.ts
'use server';

import { evaluateIdentification, getIdentification, type Identification } from '@shieldlabs-ai/next/server';
import { markRequestIdUsed } from '@/lib/request-ids';

export async function signup(formData: FormData): Promise<{ ok: boolean }> {
  const requestId = formData.get('requestId');
  let identification: Identification | null = null;
  if (typeof requestId === 'string' && requestId !== '') {
    try {
      // Waits until ShieldLabs has stored the verdict, for up to 10 seconds.
      identification = await getIdentification(requestId);
    } catch (error) {
      console.error('ShieldLabs verdict unavailable:', error); // a malformed ID, a wrong key, a network error
    }
  }

  // One identification authorizes one attempt: record its request ID first (the store is
  // asynchronous), then hand the answer to isReplay, which must answer synchronously.
  const firstUse = identification !== null && (await markRequestIdUsed(identification.request_id));

  // Refuses a missing, reused or stale identification, the rate-limit marker, missing device signals,
  // browser automation or disabled JavaScript, and the dangerous band.
  const verdict = evaluateIdentification(identification, { isReplay: () => !firstUse });
  if (!verdict.ok) return { ok: false };

  // Create the account here.
  return { ok: true };
}

// lib/request-ids.ts
// Used request IDs, in the memory of one server process. In production, use a store that every
// instance shares: Redis (SET <request id> 1 NX EX 600) or a column with a unique index.
const used = new Map<string, number>();

/** Records a request ID. Resolves to true the first time, and to false for every repeat. */
export async function markRequestIdUsed(requestId: string): Promise<boolean> {
  const now = Date.now();
  for (const [id, forgetAt] of used) if (forgetAt <= now) used.delete(id);
  if (used.has(requestId)) return false;
  used.set(requestId, now + 10 * 60 * 1000); // twice the 5-minute freshness window
  return true;
}

// app/api/shieldlabs/webhook/route.ts
import { createWebhookHandler } from '@shieldlabs-ai/next/server';

export const POST = createWebhookHandler({
  // Verified with SHIELDLABS_WEBHOOK_SECRET. webhook.ping is answered by the handler itself.
  onEvent(event) {
    if (event.event_type !== 'identification.scored') return;
    // Store the verdict here, keyed by request ID (an upsert), so a repeated delivery changes nothing.
    console.info('ShieldLabs verdict', event.data.request_id, event.data.risk_score);
  },
});