> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blursec.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Blursec SDK

> Pre-auth credential & session leak detection backed by live stealer-log threat intel.

> Official isomorphic TypeScript SDK for **Blursec** — answering one question in front of your `/login` endpoint: **"Is this credential already in the wild?"**

## What Blursec does

Most authentication breaches don't happen because someone "hacked" you. They happen because infostealer malware on a user's device harvested their saved credentials — for **your** app and every other platform, SaaS, or provider they use — into a stealer-log database, and an attacker logged in with a perfectly valid username + password.

Blursec sits in front of your `/login` endpoint and answers in under 50 ms from a continuously-updated stealer-log feed. If the credential is compromised, the SDK tells you what to do about it.

The SDK exposes four things:

1. **`blursec.checkCredential(email, password)`** — Layer 1. K-anonymity SHA-256 lookup. The raw password never leaves your server.
2. **`blursec.verifySession(req)`** — Layer 2. Extracts a session token from a Request, auto-detects JWT vs opaque, hashes appropriately, and looks it up.
3. **`blursec.webhooks.verify(...)`** — Verify HMAC-signed deliveries when a previously-clean session shows up in a fresh stealer-log batch *after* login.
4. **`dryRun: true`** — Observe-only mode on any check, so you can stage Blursec into production traffic before enforcing.

## Install

```bash theme={null}
npm install @blursec/sdk
```

Requires Node 18+, a modern browser, Cloudflare Workers, Deno, or Bun. **Zero runtime dependencies.**

## The 4-line login endpoint

```ts theme={null}
import { Blursec } from "@blursec/sdk";

const blursec = new Blursec({ apiKey: process.env.BLURSEC_API_KEY! });

app.post("/login", async (req, res) => {
  const { email, password } = req.body;

  const risk = await blursec.checkCredential(email, password);
  if (risk.leaked) {
    return res.status(403).json({
      error: "credential_compromised",
      action: risk.recommendedAction, // "block" | "force_reset" | "monitor"
    });
  }

  // ...your normal password verification continues here
});
```

That's the integration. Everything else is detail:

* [Configuration](/docs/configuration) — environments, timeouts, custom fetch
* [Errors & fail-open](/docs/errors) — the error hierarchy and why checks fail open
* [Advanced usage](/docs/advanced) — k-anonymity protocol, hash helpers, wire format
* [AI agents & MCP](/docs/mcp) — let Claude/Copilot query the database as tools
* [Mobile & frontend apps](/docs/frontend) — React, React Native, Flutter integration

## How it works (prefix-blinded lookup)

The SDK never sends the raw password to Blursec:

1. SDK hashes `email + ":" + password` with SHA-256 **locally** → 64-char hex digest.
2. SDK sends **only the first 10 hex characters** to the API — one-way, irreversible.
3. API returns every entry in that bucket; the SDK compares suffixes **locally**.

Neither the password nor the full hash ever leaves your process. See the full walkthrough in [Advanced usage](/docs/advanced).

## Runnable examples

Complete, copy-pasteable integrations live in the
[examples/ folder on GitHub](https://github.com/blur-sec/blursec-sdk/tree/main/examples) —
Express login endpoint, session validation, Cloudflare Worker, React pre-hash
form, strict error handling, and more.

## Ecosystem packages

| Package                                                                                | Purpose                             |
| -------------------------------------------------------------------------------------- | ----------------------------------- |
| [`@blursec/sdk`](https://www.npmjs.com/package/@blursec/sdk)                           | The core SDK                        |
| [`@blursec/replit`](https://github.com/blur-sec/blursec-sdk/tree/main/packages/replit) | Replit / Express drop-in middleware |
| [`@blursec/mcp`](https://github.com/blur-sec/blursec-sdk/tree/main/packages/mcp)       | MCP server for AI agents            |