# AbuseGraph — agent integration brief

You are an engineering agent. Integrate **AbuseGraph** account protection into this codebase so signup/login (and related auth events) get a risk **score**, **verdict**, and **reasons**. The host app keeps enforcement.

Canonical sources (fetch as needed):
- This prompt: https://abusegraph.com/llms-full.txt
- Index: https://abusegraph.com/llms.txt
- OpenAPI: https://abusegraph.com/openapi.json
- Interactive docs: https://abusegraph.com/docs
- SDK overview: https://abusegraph.com/how-it-works

## Target stack

Detect the auth / backend / mobile stack from this repo (package.json, auth config, etc.).
Then fetch the matching guide from the list below and follow it.

| Stack | Guide |
|-------|-------|
| Better Auth | https://abusegraph.com/guides/better-auth |
| Clerk | https://abusegraph.com/guides/clerk |
| Supabase | https://abusegraph.com/guides/supabase |
| NextAuth / Auth.js | https://abusegraph.com/guides/nextauth |
| Next.js App Router | https://abusegraph.com/guides/nextjs |
| Express / Node | https://abusegraph.com/guides/express |
| Auth0 | https://abusegraph.com/guides/auth0 |
| Firebase Auth | https://abusegraph.com/guides/firebase |
| Cloudflare Workers | https://abusegraph.com/guides/cloudflare |
| Python | https://abusegraph.com/guides/python |
| Go | https://abusegraph.com/guides/go-backend |
| cURL / direct API | https://abusegraph.com/guides/curl |
| CDN / script tag | https://abusegraph.com/how-it-works#sdk |
| iOS (Swift) | https://abusegraph.com/guides/ios |
| Android (Kotlin) | https://abusegraph.com/guides/android |
| React Native | https://abusegraph.com/guides/react-native |

If unclear, ask once: "Which stack? (Better Auth, Clerk, Next.js, Express, iOS, …)"
You can also reload this prompt with `?stack=clerk` (aliases: better-auth, next-auth, react-native, …).

## Account status (ask if unknown)

Ask once: "Do you already have AbuseGraph keys, or should we start from a free signup?"

### If they are a customer
- Use env keys, or have them paste `sk_test_…` / `pk_test_…` + site from https://abusegraph.com/app/settings/keys

### If they are not a customer
- Send them to https://abusegraph.com/signup → finish setup → copy test keys
- Free: 1,000 live checks / month after DNS verify; test keys never bill
- Wire with `sk_test_…` / `pk_test_…` placeholders until they paste real values
- Never invent live keys

## Architecture (always)

1. **Browser (recommended):** `@palisade/sdk` with publishable `pk_…` → `collect()` → `evaluate()` → `toCheckBody(...)` including `verdictToken`.
2. **Server (authoritative):** `@palisade/server` `createCheckClient` or `POST https://abusegraph.com/api/v1/check` with secret `sk_…` header `x-api-key`.
3. Events: `signup` | `login` | `password_reset` | `email_change`. Optional `sessionId` from `POST https://abusegraph.com/api/v1/session`.
4. Edge evaluate defaults to `https://api.abusegraph.com` — no config required for production DNS.

### Minimum env

```bash
ABUSEGRAPH_SITE=yourdomain.com
ABUSEGRAPH_CHECK_URL=https://abusegraph.com/api/v1/check
ABUSEGRAPH_SECRET_KEY=sk_test_…
ABUSEGRAPH_SECRET_KEY_TEST=sk_test_…
NEXT_PUBLIC_ABUSEGRAPH_PUBLISHABLE_KEY=pk_test_…
```

Live (`sk_live_…`): also send header `x-abusegraph-site: $ABUSEGRAPH_SITE`.

### Hard rules

- Secret keys (`sk_`) **never** in browser, mobile public binaries, git, or screenshots.
- Do not call bare browser `check()` as the only decision — always finish on the server with `sk_`.
- Prefer fail-open on network errors for signup (do not brick registration if AbuseGraph is unreachable) unless the user asks for fail-closed.
- Match existing project style; keep the change focused.
- Do not invent product APIs. Prefer the official guide + OpenAPI.
- No third-party fraud-vendor names in user-facing copy.

## Implementation checklist

1. Install packages the guide specifies (usually `@palisade/sdk` + `@palisade/server`).
2. Add env vars (test keys first).
3. Hook the auth lifecycle (create user / session / webhook) **before** trusting the account.
4. Forward browser `toCheckBody` fields when available for a full score.
5. Branch on `verdict`: `allow` | `challenge` | `shadow` | `block` (and optionally `score`).
6. Log `requestId` for support; do not log full secrets.

## Verify

- [ ] `sk_test_` check returns 200 with `score` + `verdict` (curl or guide snippet)
- [ ] Browser path forwards `verdictToken` when using the SDK
- [ ] No `sk_` in client bundles
- [ ] Live path documents DNS verify + `x-abusegraph-site` before switching to `sk_live_`

## Quick curl smoke test

```bash
curl -sS -X POST https://abusegraph.com/api/v1/check \
  -H "content-type: application/json" \
  -H "x-api-key: $ABUSEGRAPH_SECRET_KEY" \
  -H "x-abusegraph-site: $ABUSEGRAPH_SITE" \
  -d '{"email":"user@example.com","event":"signup","site":"'"$ABUSEGRAPH_SITE"'"}'
```

When done, summarize files changed and how to rotate from test → live keys.