Skip to main content

Advanced usage

Custom fetch

Inject any fetch-compatible function to add telemetry, retries on non-credential endpoints, DNS pinning, etc.

Why you should not retry checkCredential

It’s tempting to wrap checkCredential in an exponential-backoff retry loop. Don’t. The Blursec model is: “answer in under 50 ms or step out of the way.” If the API is slow, the right answer is to fail open immediately so the user’s login isn’t delayed. Retries:
  1. Multiply the latency cost of an outage — three attempts at 1500 ms each is 4.5 seconds added to every login.
  2. Add load to an already-struggling API — when Blursec is degraded, the worst possible thing every customer can do is retry.
  3. Don’t change the outcome — if a check times out once during a 30-second incident, it’s likely to time out again on the next 1-2 attempts.
The fail-open contract exists because retries are the wrong reflex. If you want stricter behavior, lower timeoutMs — don’t add retries.
For auth.* and sessions.kill(), retries are reasonable — those are infrequent ops on the control plane. Wrap them in your fetch if you want:

Telemetry

Every CredentialRiskResult includes checkedAt and durationMs, so you can record the SDK’s view of latency without instrumenting fetch:
For deeper visibility, instrument the injected fetch (see above).

Cancellation

Every method accepts an AbortSignal that composes with the SDK’s internal timeout:
If the caller’s signal aborts first, the SDK throws a BlursecTimeoutError with cause set to the abort reason. If the internal timeout fires first, the timeout error carries timeoutMs.

Edge runtimes

The SDK is shipped with "platform": "neutral" and targets es2022, so it runs unmodified on:
  • Cloudflare Workersimport { Blursec } from "@blursec/sdk" works. The Workers runtime provides fetch, crypto.subtle, and AbortController natively.
  • Vercel Edge Functions — same as Workers.
  • Denoimport { Blursec } from "npm:@blursec/sdk".
  • Bunbun add @blursec/sdk.
No polyfills needed. See examples/cloudflare-worker.ts for a complete edge integration.

Custom severity → action maps per route

The default mapping is conservative — block on critical, force-reset on high/medium, monitor on low. You can override per-call, which is useful when different routes warrant different strictness:

Manual hashing for non-standard transports

If you need to talk to the Blursec API through a transport the SDK doesn’t support (e.g. a gRPC bridge, a CDN-mirrored prefix endpoint), use the exported hash helpers and call checkHash (or skip the SDK entirely):
See examples/k-anonymity.ts.