`blursec.credentials`

Pre-auth prefix-blinded checks against the Blursec stealer-log database. This is the core surface of the SDK.

import { Blursec } from "@blursec/sdk";

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

const risk = await blursec.credentials.check(email, password);

Methods

`check(email, password, options?) → Promise<CredentialRiskResult>`

Layer 1 — email + password pair. The SDK locally:

Builds the canonical string lowercase(email) + ":" + password.
SHA-256 hashes it via crypto.subtle.digest.
Sends only the first 10 hex chars of the digest to POST /v1/credentials/check.
Compares the remaining 54 chars against returned hashSuffix values.
Returns a CredentialRiskResult.

The raw password never appears on the network.

const risk = await blursec.credentials.check("[email protected]", "P@ssw0rd!");

if (risk.leaked) {
  console.warn("Leaked credential:", risk.severity, risk.recommendedAction);
}

`checkToken(sessionToken, options?) → Promise<CredentialRiskResult>`

Layer 2 — session cookie / bearer token. Same k-anonymity model, but hashes the token alone. Use on every authenticated request if you suspect a session might have been hijacked (or routinely, e.g. on sensitive endpoints).

const risk = await blursec.credentials.checkToken(req.cookies.session);
if (risk.leaked && risk.severity === "critical") {
  await yourSessionStore.revokeAllFor(req.userId);
  return res.status(401).end();
}

For request-aware token extraction (JWT vs opaque auto-detection, cookie/header fallbacks) prefer blursec.sessions.verify(req) — it wraps checkToken and returns tokenType + compromised.

`checkHash(fullSha256HexDigest, options?) → Promise<CredentialRiskResult>`

Low-level escape hatch. Pass a 64-char SHA-256 hex digest you computed yourself (e.g. inside a WebAssembly worker, or when integrating with a non-standard transport). The SDK still only sends the prefix.

`CheckOptions`

All three methods accept the same options bag:

interface CheckOptions {
  context?: RequestContext;       // Layer 3 — device & connection signals
  failOpen?: boolean;             // default: true
  timeoutMs?: number;             // default: 1500
  signal?: AbortSignal;           // cancellation, composes with timeout
  severityActions?: Partial<Record<LeakSeverity, RecommendedAction>>;
  dryRun?: boolean;               // default: false — observe-only mode
}

`context` — Layer 3 risk scoring

Optional metadata about the request. When provided, Blursec factors device & connection signals into the response severity (e.g. a leaked credential coming from a known-good IP scores lower than one coming from a Tor exit node).

const risk = await blursec.credentials.check(email, password, {
  context: {
    ip: req.ip,
    userAgent: req.headers["user-agent"],
    deviceFingerprint: req.fingerprint,
    country: req.geo?.country,
    userId: existingUserId, // if known
  },
});

`failOpen`

When true (default), the SDK swallows timeouts, network errors, and 5xx responses, returning { leaked: false, failedOpen: true }. This guarantees a Blursec outage cannot lock out legitimate users. When false, the SDK throws — see errors.md.

`timeoutMs`

Per-call timeout. Defaults to 1500 ms (generous headroom above the typical sub-50 ms response time). Combined with failOpen: true, this ensures the worst-case latency added to your login flow is bounded.

// Very strict latency budget
const risk = await blursec.credentials.check(email, password, {
  timeoutMs: 200,
});

`signal`

Standard AbortSignal. Composes with the SDK’s internal timeout — whichever fires first wins.

`severityActions`

Override the default severity → recommendedAction mapping for one call:

const risk = await blursec.credentials.check(email, password, {
  severityActions: {
    low: "force_reset",   // be stricter
    high: "kill_sessions",
  },
});

`dryRun`

Observe-only mode. When true, the SDK still queries the API and reports the real leaked / severity / firstSeen, but coerces recommendedAction to "allow" so the integration never blocks traffic. The action it would have taken is surfaced on enforcedAction. Recommended for the first 1–2 weeks of any rollout.

const risk = await blursec.credentials.check(email, password, { dryRun: true });
// risk.recommendedAction === "allow"  (always, in dry-run)
// risk.enforcedAction    === "block"  (what it *would* have been)
metrics.increment("blursec.shadow", { action: risk.enforcedAction });

`CredentialRiskResult`

interface CredentialRiskResult {
  leaked: boolean;
  severity: "low" | "medium" | "high" | "critical" | null;
  recommendedAction:
    | "allow" | "monitor" | "force_reset" | "kill_sessions" | "block";
  firstSeen: string | null;   // ISO 8601
  sources: number;            // # of distinct stealer-log sources
  checkedAt: string;          // ISO 8601, when the SDK ran the check
  durationMs: number;         // end-to-end SDK time
  failedOpen: boolean;        // true when SDK returned a safe default
  failureReason?:             // only set when failedOpen is true
    | "timeout" | "network" | "server_error"
    | "circuit_open" | "malformed_response";
  dryRun?: boolean;           // true when called with { dryRun: true }
  enforcedAction?:            // action that *would* apply outside dry-run
    RecommendedAction;
}

Default severity → action mapping

`severity`	`recommendedAction`
`critical`	`block`
`high`	`force_reset`
`medium`	`force_reset`
`low`	`monitor`
(none)	`allow`

When multiple matches come back for the same prefix, the SDK picks the highest severity, sums sources, and picks the earliest firstSeen.

The convenience shortcut

blursec.checkCredential(email, password, options?) is an exact alias for blursec.credentials.check(email, password, options?). Use whichever reads better:

// equivalent
await blursec.checkCredential(email, password);
await blursec.credentials.check(email, password);

Manual hashing

If you want to perform the prefix-blinded lookup yourself (e.g. you have a custom transport):

import { hashCredential, matchesHash, HASH_PREFIX_LENGTH } from "@blursec/sdk";

const hashed = await hashCredential(email, password);
// → { full, prefix (10 hex chars = 40 bits), suffix (54 hex chars) }

const matches = await fetchFromBlursec(hashed.prefix); // your transport
const leaked = matches.some((m) => matchesHash(hashed.full, m.hashSuffix));

Threat model. A 40-bit prefix is one-way (SHA-256 is preimage-resistant) and cannot be reversed back to the credential. However, a malicious or compromised Blursec backend could in principle log prefixes and correlate them across requests to identify specific credentials in its own database. The SDK’s confidentiality story trusts the Blursec backend not to do this. If your threat model does not allow that trust, run the database on-prem.

See examples/k-anonymity.ts for a runnable walkthrough.

Getting started

Resources

Credentials

`blursec.credentials`

Methods

`check(email, password, options?) → Promise<CredentialRiskResult>`

`checkToken(sessionToken, options?) → Promise<CredentialRiskResult>`

`checkHash(fullSha256HexDigest, options?) → Promise<CredentialRiskResult>`

`CheckOptions`

`context` — Layer 3 risk scoring

`failOpen`

`timeoutMs`

`signal`

`severityActions`

`dryRun`

`CredentialRiskResult`

Default severity → action mapping

The convenience shortcut

Manual hashing

​blursec.credentials

​Methods

​check(email, password, options?) → Promise<CredentialRiskResult>

​checkToken(sessionToken, options?) → Promise<CredentialRiskResult>

​checkHash(fullSha256HexDigest, options?) → Promise<CredentialRiskResult>

​CheckOptions

​context — Layer 3 risk scoring

​failOpen

​timeoutMs

​signal

​severityActions

​dryRun

​CredentialRiskResult

​Default severity → action mapping

​The convenience shortcut

​Manual hashing

`blursec.credentials`

Methods

`check(email, password, options?) → Promise<CredentialRiskResult>`

`checkToken(sessionToken, options?) → Promise<CredentialRiskResult>`

`checkHash(fullSha256HexDigest, options?) → Promise<CredentialRiskResult>`

`CheckOptions`

`context` — Layer 3 risk scoring

`failOpen`

`timeoutMs`

`signal`

`severityActions`

`dryRun`

`CredentialRiskResult`

Default severity → action mapping

The convenience shortcut

Manual hashing