# 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 (locked)

- **Name:** Clerk
- **Guide (fetch and follow):** https://abusegraph.com/docs/guides/clerk
- **Best for:** Clerk apps
- **Typical time:** 8 min

Implement this stack. Do not switch stacks unless the user asks.

## 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):** `@abusegraph/sdk` with publishable `pk_…` → `collect()` → `evaluate()` → `toCheckBody(...)` including `verdictToken`.
2. **Server (authoritative):** `@abusegraph/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 `@abusegraph/sdk` + `@abusegraph/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.