Replit integration

@blursec/replit is the official Replit adapter for @blursec/sdk — zero-config credential & session leak protection for apps hosted on Replit. The core SDK is already isomorphic and runs on Replit without any adapter. This package layers on the Replit-specific wiring that is tedious to do by hand:

Export	What it does
`createBlursecFromReplit()`	Reads `BLURSEC_API_KEY` from Replit Secrets, tags outbound traffic with your Repl owner/slug/id, validates `BLURSEC_ENVIRONMENT`.
`blursecSession()`	Express middleware that verifies the inbound session cookie/Bearer token against the live stealer-log feed on every request.
`blursecLogin()`	Express middleware for `POST /login` that runs email+password through Blursec before bcrypt.
`blursecReplitIdentity()`	Parses the `X-Replit-User-*` headers Replit’s edge proxy injects into a typed `ReplitAuthIdentity` on `req.blursec.identity`.
`replitAuthHeaders(req)`	Standalone version of the above — call it from any framework.

Like everything else in the Blursec ecosystem it fails open on outages, adds ~50 ms to a login, and runs on every Replit-supported runtime (Node 18+, Bun, Deno).

Install

npm i @blursec/sdk @blursec/replit

@blursec/sdk is a peer dependency, so the adapter and the SDK version independently — bring any SDK >= 1.0.0.

Quick start (Replit + Express)

Open your Repl’s Secrets pane (lock icon in the left sidebar).
Add a secret named BLURSEC_API_KEY with your Blursec API key.
Drop this into index.ts:

import express from "express";
import { createBlursecFromReplit } from "@blursec/replit";
import { blursecLogin, blursecSession } from "@blursec/replit/express";

const app = express();
app.use(express.json());

const blursec = createBlursecFromReplit();

// Per-request session verification (every authenticated request).
app.use(blursecSession(blursec, { cookieName: "sid" }));

// Login-time credential check (before bcrypt).
app.post("/login", blursecLogin(blursec), async (req, res) => {
  // Your normal password verification only runs if the credential
  // is not known-compromised (or if Blursec failed open).
  res.json({ ok: true });
});

app.listen(3000);

Both middlewares fail open on Blursec outages — your login flow keeps working even if the API is unreachable.

`createBlursecFromReplit(overrides?)`

Env-aware constructor. Every field of BlursecClientConfig may be overridden via the overrides argument.

Env var	Purpose
`BLURSEC_API_KEY`	API key from Replit Secrets (required unless overridden)
`BLURSEC_ENVIRONMENT`	`production` (default) / `staging` / `local`
`REPL_OWNER`	Repl owner — tagged on outbound headers
`REPL_SLUG`	Repl slug — tagged on outbound headers
`REPL_ID`	Repl id — tagged on outbound headers

Throws BlursecValidationError when BLURSEC_API_KEY is missing.

`blursecSession(blursec, options?)`

Express middleware. Verifies the inbound session token against the stealer-log feed.

Option	Default	Notes
`cookieName`	`"session"`	Forwarded to `extractSessionToken`.
`header`	`"authorization"`	Header to read instead of `Authorization`.
`dryRun`	`false`	Observe-only mode — never blocks.
`failOpen`	`true`	Inherited from the SDK.
`timeoutMs`	`1500`	Inherited from the SDK.
`resetPath`	`"/auth/reset"`	Set `null` to respond `403 JSON` instead.
`onResult`	—	Fires for every result (audit logging).
`onBlock`	—	Override the default `401 JSON`.
`contextBuilder`	`{ ip, userAgent }`	Custom `RequestContext` builder.
`severityActions`	SDK default	Per-severity action overrides.

Decision matrix:

`recommendedAction`	Default response
`allow`	pass through
`monitor`	pass through, fires `onResult`
`force_reset` / `kill_sessions`	`302 → resetPath` (or `403 JSON` when `resetPath: null`)
`block`	`401 JSON` (or `onBlock`)

When the SDK fails open (timeout, network, 5xx, circuit open) the middleware passes through unchanged.

`blursecLogin(blursec, options?)`

Express middleware for POST /login. Runs body[emailField] + body[passwordField] through blursec.checkCredential before returning control to your password-verification handler.

Option	Default	Notes
`emailField`	`"email"`	`req.body` field name.
`passwordField`	`"password"`	`req.body` field name.
`resetPath`	`"/auth/reset"`	Set `null` for `403 JSON`.
`dryRun`	`false`	Observe-only.
`failOpen`	`true`	Inherited from the SDK.
`onResult`	—	Fires for every result.
`onBlock`	—	Override default `403 JSON`.
`contextBuilder`	`{ ip, userAgent }`	Custom `RequestContext` builder.

The decision matrix matches blursecSession, except block responds 403 JSON by default.

Replit Auth identity

blursecReplitIdentity() attaches a typed identity parsed from the X-Replit-User-* headers to req.blursec.identity. It never short-circuits the response — pair it with your own logic for routes that require Replit Auth. replitAuthHeaders(req) is the framework-agnostic version: it accepts any RequestLike (WHATWG Request, Node IncomingMessage, Express req, or bare { headers }) and returns an unauthenticated identity (isAuthenticated: false) when no headers are present.

TypeScript: augmenting `Request.blursec`

The Express adapters attach state to req.blursec. For type completion in your handlers, add this to a *.d.ts in your project:

declare module "express-serve-static-core" {
  interface Request {
    blursec?: import("@blursec/replit/express").BlursecRequestState;
  }
}

Dry-run rollout (recommended)

Pass dryRun: true for the first 1–2 weeks so you can dashboard the real signal without enforcing:

app.use(blursecSession(blursec, { dryRun: true, onResult: logToDatadog }));
app.post("/login", blursecLogin(blursec, { dryRun: true, onResult: logToDatadog }));

recommendedAction will always be "allow"; the would-be action is surfaced via result.enforcedAction. Flip dryRun off when your dashboards are clean. See the runnable example in examples/replit-express.ts and the error model in errors.

Getting started

Resources

Replit

Replit integration

Install

Quick start (Replit + Express)

`createBlursecFromReplit(overrides?)`

`blursecSession(blursec, options?)`

`blursecLogin(blursec, options?)`

Replit Auth identity

TypeScript: augmenting `Request.blursec`

Dry-run rollout (recommended)

​Replit integration

​Install

​Quick start (Replit + Express)

​createBlursecFromReplit(overrides?)

​blursecSession(blursec, options?)

​blursecLogin(blursec, options?)

​Replit Auth identity

​TypeScript: augmenting Request.blursec

​Dry-run rollout (recommended)

Replit integration

Install

Quick start (Replit + Express)

`createBlursecFromReplit(overrides?)`

`blursecSession(blursec, options?)`

`blursecLogin(blursec, options?)`

Replit Auth identity

TypeScript: augmenting `Request.blursec`

Dry-run rollout (recommended)