Security
Basalt is secure by default at the HTTP edge and fail-closed on secrets. Everything here is zero-dependency and wired through the plugin lifecycle.
The secure defaults, at a glance
Each of these ships ON by default — you have to opt out, never in. This table is the map; each row's guide has the details and the opt-out.
| Default | What it prevents | Where |
|---|---|---|
Boot refuses routes whose security meta has no enforcing guard (UnguardedRouteMetaError) | "protected" routes silently serving open | this page, below |
Billing/invoice routes require an authenticated user (meta.auth) | anonymous card/plan management via a forged tenant | Billing |
Membership guard on every authenticated tenant request (tenantMembershipPlugin) | a valid user of tenant A driving tenant B (TEAM_NOT_A_MEMBER) | this page, below |
Cache fails closed outside tenant context in multi-tenant apps (MissingCacheScopeError) | cross-tenant reads through a shared "global" namespace | Caching |
meta.can rejects unenforceable shapes (PERMISSION_META_INVALID) | a malformed declaration silently skipping authorization | Authorization |
Signed storage URLs serve Content-Disposition: attachment | stored XSS via user uploads on a CDN origin | Storage |
Mail bodies build through html`…` with auto-escaped interpolations; log driver redacts bodies in production | markup injection in app mail · reset links in log aggregators | Notifications |
| Admin/UI pages carry a route-scoped, hash-locked CSP | inline-script injection — without weakening the app-wide CSP | Admin pages |
Rate-limit keys ignore X-Forwarded-For; CORS never reflects arbitrary origins with credentials; HSTS/nosniff/frame-deny on | header-spoofed limits · credentialed cross-origin reads · clickjacking | this page, below |
Secrets fail closed in production (secret(), AUTH_WEAK_SECRET) | booting with a guessable signing key | this page, below |
Edge protection — securityPlugin
One plugin covers rate limiting, CORS and secure response headers. Secure response headers are on by default; rate limiting and CORS are opt-in — enable them explicitly for production. New apps ship securityPlugin() in the scaffold with a global per-IP rate limit enabled (rateLimit: { limit: 120, windowMs: 60_000 }), so headers and request budgets are protected from the first deploy. With tenancy and auth, the scaffold also registers teamsPlugin() + tenantMembershipPlugin() (see Never trust a client-supplied tenant below).
import { securityPlugin } from '@basaltkit/fastify'
securityPlugin({
rateLimit: { limit: 100, windowMs: 60_000 }, // 100 req / minute / IP
cors: { origin: ['https://app.example.com'], credentials: true },
headers: true, // secure defaults
})Rate limiting
A fixed-window limiter keyed by client IP (override with key). Blocked requests get 429 RATE_LIMITED with Retry-After, and every response carries X-RateLimit-Limit / -Remaining / -Reset.
securityPlugin({
rateLimit: {
limit: 20,
windowMs: 10_000,
// The default. Behind a proxy, have the adapter resolve request.ip from
// the proxy you trust rather than reading a forwarding header here.
key: (req) => req.ip ?? 'unknown',
skip: (req) => req.url.startsWith('/livez'),
},
})Never key the global limit by a credential header
The global key runs before authentication, so it sees only what the client sent. A key such as req.headers['x-api-key'] ?? req.ip is a bypass: a client that sends a fresh made-up value on every request gets a fresh bucket every time and is never limited, and the flood of buckets pushes legitimate clients out of the store. Key the global limit by address only (req.ip, or a header your own proxy sets and strips from client requests). For a budget per API key, use meta.rateLimit with key: 'apiKey' (below): it reads the key the enricher verified, so a made-up key never gets a bucket of its own.
The default store is in-memory (MemoryRateLimitStore). Its memory is bounded: expired buckets are swept as traffic arrives, and at most maxEntries (default 100 000) buckets are kept — past that the oldest windows are evicted first, so a flood of distinct client addresses cannot grow the process without limit (new MemoryRateLimitStore({ maxEntries }) to size it). A bucket that has used up its limit is never evicted: a flood of new addresses cannot free a limited client early — it is held until its window ends. For multiple instances implement the RateLimitStore interface over Redis — the same driver pattern used by @basaltkit/cache.
Per-route limits. A route can tighten the budget for a sensitive endpoint via meta.rateLimit — it gets its own bucket (keyed by IP + route pattern) at that threshold. It is enforced as a route guard, so it holds identically on Fastify, Express and Hono, and also when the route is invoked as an MCP tool. On Express and Hono (where the edge hook runs before routing) the request also counts against the global bucket; on Fastify it is counted once, in its own bucket:
route({
method: 'POST',
url: '/auth/login',
meta: { rateLimit: { limit: 5, windowMs: 60_000 } }, // 5/min on top of the global limit
// …
})Per-user and per-tenant budgets. By default the bucket is the client IP, so everyone behind one NAT or corporate proxy shares it. meta.rateLimit.key picks who the bucket belongs to:
key | Bucket | Use it for |
|---|---|---|
'ip' (default) | client address (request.ip) | anonymous endpoints: login, sign-up, password reset |
'user' | ctx().user.id | expensive per-user actions: exports, AI calls, uploads |
'tenant' | ctx().tenant.id (shared by the tenant's users) | a per-organization quota |
'user+tenant' | one bucket per user per tenant | a user who belongs to several tenants |
'apiKey' | ctx().apiKey.id (a key apiKeysPlugin verified) | bursts per machine client |
(ctx) => string | whatever id you return | anything else |
route({
method: 'POST',
url: '/reports/export',
meta: { auth: true, rateLimit: { limit: 10, windowMs: 60_000, key: 'user' } },
// …
})The key is resolved in the route guard, after the enrichers ran, so auth and tenancy have already set ctx().user / ctx().tenant. When the id is missing (an anonymous caller, no tenant resolved, or the function returns nothing), the bucket falls back to the client IP, and anonymous buckets never mix with signed-in ones. When the adapter could not resolve an IP either (request.ip undefined — Hono on a runtime without getClientIp, a hand-built runRoute, an MCP tool called over stdio or through McpServer.callTool), a signed-in caller is keyed by identity (user:<id>|tenant:<id>, as 'user+tenant' would), and every anonymous ip-less request shares one unknown bucket: fail closed, rather than a bucket per spoofable header. Configure the adapter to resolve the client IP to get per-client buckets back. Keyed buckets use the same store (MemoryRateLimitStore, or Redis across instances). A keyed route still counts against the global per-IP limit on every adapter, because the pre-routing hook cannot know the user yet. To give a family of paths a different per-IP ceiling, use path-prefix budgets.
'apiKey' keys the bucket by ctx().apiKey.id — one budget per API key, so several machine clients behind one address no longer share one. Only a key that apiKeysPlugin verified becomes a bucket id; with no verified key (a session caller, an anonymous one, or an invalid key that rejectInvalid: false let through) the bucket falls back like any other missing id. A per-key budget multiplies with the number of keys a customer mints, so use it for bursts and put quotas on 'tenant'.
Several budgets on one route
meta.rateLimit also takes an array. Every budget is enforced, in the order declared; the first one that refuses answers 429 and the later ones are not charged — so put the short burst budget first, and a request refused for bursting does not use up the daily quota:
import type { RouteRateLimits } from '@basaltkit/http'
route({
method: 'GET',
url: '/v1/orders',
meta: {
scopes: ['orders:read'],
rateLimit: [
{ limit: 10, windowMs: 1_000, key: 'apiKey' }, // burst, per key
{ limit: 50_000, windowMs: 86_400_000, key: 'tenant' }, // daily, per customer
] satisfies RouteRateLimits,
},
// …
})X-RateLimit-*report the budget with the fewest requests left (on a tie, the one that resets later); on a refusal they andRetry-Aftercome from the budget that refused.- The budgets are charged one after another (one store hit each), with no atomicity across them.
- Each array entry has its own counter, keyed by method, route and position: reordering the entries remaps the counters. Changing a
limitorwindowMskeeps the running window — editing a quota does not hand everyone a fresh one. - The array form (and
bucket, below) is always charged in the route guard, on every adapter, on top of the edge bucket (global or prefix). On Fastify that differs from the single object, which is charged instead of the global bucket: wrapping{ limit, windowMs }in an array puts the global per-IP limit back on that route. If you relied on the Fastify replacement to lift the ceiling, move to a path prefix, which does it on every adapter.
Shared buckets
bucket names a budget shared by every route that declares it — one daily quota for a whole public API:
const daily = { limit: 50_000, windowMs: 86_400_000, key: 'tenant', bucket: 'public-api-daily' } as const
route({ method: 'GET', url: '/v1/orders', meta: { rateLimit: [{ limit: 10, windowMs: 1_000, key: 'apiKey' }, daily] }, /* … */ })
route({ method: 'POST', url: '/v1/orders', meta: { rateLimit: daily }, /* … */ })Every declaration of one name must carry the same limit, windowMs and key string; the app refuses to boot (InvalidRouteMetaError, on every adapter) when they disagree. Function keys are not compared — two inline lambdas are different objects even when they mean the same. Names match /^[A-Za-z0-9._:-]{1,64}$/. A malformed array or bucket entry (empty array, a non-positive limit, an unknown key string) also refuses the boot; the single object keeps its historical lenient reading.
Path-prefix budgets
rateLimit.prefixes gives a family of paths its own edge budget, charged before routing instead of the global bucket — the way a public API under /v1 gets a higher per-IP ceiling than the rest of the app while still paying a per-IP budget before any key is looked up:
securityPlugin({
rateLimit: {
limit: 300,
windowMs: 60_000,
prefixes: [{ prefix: '/v1', limit: 3_000, windowMs: 60_000 }],
},
})The longest matching prefix wins. Matching is on segment boundaries (/v1 matches /v1 and /v1/orders, never /v10) after a minimal normalisation: the query string is cut, runs of / collapse, case is ignored and a trailing / is dropped — there is no percent-decoding or dot-segment resolution. 404s, preflights and requests an enricher rejects are counted too. Each prefix may take its own key(request) (default: the global key, else the IP); like the global key it runs before authentication, so never read a credential header in it. skip skips prefix budgets too. A bad prefix (no leading /, a ? or #, a non-positive limit, a duplicate) throws a TypeError when the plugin is created.
Prefixes set or lift the edge budget for a path family; they are not a way to make one endpoint stricter, because a request that reaches the route through a path form the normaliser does not fold falls back to the global bucket. A budget that must hold for a specific endpoint belongs in its meta.rateLimit, which is bound to the matched route. On Fastify, a route's single-object IP-keyed meta.rateLimit still replaces the edge bucket (prefix or global), as before.
CORS
origin accepts true (reflect), a string, an allow-list array, or a predicate. Preflight OPTIONS requests are answered automatically (204). They count against the global rate limit like any other request, and the Access-Control-Allow-Methods / -Allow-Headers / -Max-Age headers go only to an allowed origin — a disallowed one gets a bare 204 that discloses nothing.
Credentials require an explicit allow-list
Reflecting an arbitrary Origin back with credentials: true would hand authenticated, cookie-bearing responses to any site. When credentials is on, Basalt refuses to reflect — you must pass an explicit origin (string, array, or predicate). A wildcard * is only ever emitted for non-credentialed requests.
Secure headers
headers: true sets HSTS, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer, Cross-Origin-Opener-Policy: same-origin and a restrictive default Content-Security-Policy: default-src 'none'; frame-ancestors 'none' (right for a JSON API), plus Cache-Control: no-store so no browser or intermediary cache keeps a response carrying a session token, API key or MFA secret. Pass an object to customize (e.g. your own contentSecurityPolicy for an HTML/docs surface, or cacheControl: 'private, no-cache'), contentSecurityPolicy: false / cacheControl: false to omit just that header, or headers: false to disable them all. A route that is safe to cache sets its own Cache-Control header, which replaces the default — do so on meta.etag routes (e.g. private, no-cache), since no-store keeps browsers from revalidating.
Per-route headers — meta.responseHeaders
Some routes need headers the rest of the API does not: a public share link that search engines must not index, a download that must never be cached. Declare them on the route:
route({
method: 'POST',
url: '/s/:token',
meta: { responseHeaders: { 'X-Robots-Tag': 'noindex, nofollow', 'Cache-Control': 'no-store' } },
handler: /* … */,
})The pipeline sets them as soon as the route matches, before enrichers and guards, so they are on every response the route produces — the 200, a guard's 401/403, a validation 400, a thrown 500 — on all three adapters. A header set by reply.header() would only reach the success path. They replace a global header of the same name (here securityPlugin's Cache-Control), and a handler can still override one with reply.header().
The values are checked at boot on every adapter: strings without CR, LF or other control characters, and never Set-Cookie, Content-Type, Content-Length, Transfer-Encoding, hop-by-hop headers or X-Request-Id, which belong to the response or the adapter. A record that breaks a rule refuses the boot with HTTP_INVALID_ROUTE_META, naming every offending route (@basaltkit/http 2.8 only warned and sent none of its headers). If you drive runRoute() yourself without assertRouteMetaValid(), such a route throws InvalidRouteHeadersError (500, HTTP_INVALID_ROUTE_HEADERS) on each request before any of its headers is set.
The key is responseHeaders, not headers: route meta is also yours, and nothing reads or sends meta.headers. A request that never reaches the route — a 404, a rate-limit 429 or a malformed body rejected by the framework's parser — carries only the global headers.
Resource limits & DoS resistance
Beyond headers and rate limits, long-lived and slow connections can exhaust a server. Basalt ships sane defaults and knobs for the sharp edges.
Request timeouts (anti-slowloris)
A slow client that dribbles out a request one byte at a time ties up a connection indefinitely. The Fastify adapter defaults to a 30 s requestTimeout (Fastify's own default is disabled); override it via fastifyPlugin({ fastify: { requestTimeout } }). Express and Hono run on a Node server you own — set the same protection on it:
// Express / Hono (node:http server)
server.requestTimeout = 30_000 // whole request must arrive within 30s
server.headersTimeout = 20_000 // headers within 20s (slowloris headers)
server.keepAliveTimeout = 5_000SSE streams
Server-Sent Events are long-lived by design, so give them a heartbeat and a lifetime cap. send() also returns a backpressure boolean — stop producing when it's false:
return sse(async (stream) => {
for await (const update of source) {
if (!stream.send({ data: update })) break // client can't keep up → back off
}
}, { heartbeatMs: 15_000, maxDurationMs: 30 * 60_000 }) // ping every 15s, cap at 30 minThe heartbeat pings keep proxies from dropping an idle stream and reveal a dead socket; maxDurationMs is a backstop against connections that never disconnect. Cap the number of concurrent streams per user/tenant in your handler for a hard ceiling.
Ceremony endpoints (WebAuthn, MFA)
Endpoints that mint a challenge or verify a code are pre-auth and cheap to hammer — throttle them. Reuse the brute-force lockout and per-route limits, and in production back the WebAuthn PasskeyStore / WebAuthnChallengeStore (and MFA stores) with a durable implementation, not the in-memory default.
Custom-domain re-verification
A verified custom domain that later expires or repoints its DNS is a takeover risk. Re-verify on a schedule with @basaltkit/scheduler — reverifyAll() re-checks the TXT record of every verified domain and revokes those whose record is definitively gone (a DNS timeout leaves them verified):
schedule.call('reverify-domains', async () => {
const { revoked } = await customDomains.reverifyAll()
if (revoked.length) log.warn({ revoked }, 'custom domains un-verified')
}).daily().at('04:00')A new owner of a lapsed domain can also take a stale verified claim over by publishing its challenge() record — see Tenancy.
Inbound mail endpoint
inboundMailRoutes() is unauthenticated until the signature over the bytes is checked, so it caps requests at 10 MiB (not the 1 MiB rawBody() default), answers unrouted addresses exactly like routed ones, and only believes Authentication-Results from servers you list. Add a meta.rateLimit — see Inbound mail.
Fail-closed secrets — secret()
The most common production incident is shipping a placeholder signing key. secret() makes that impossible:
import { defineEnv, secret } from '@basaltkit/env'
export const env = defineEnv({
APP_SECRET: secret({ devDefault: 'dev-only-insecure-secret-value' }),
})- Development (
NODE_ENV=developmentortest, set explicitly): usesdevDefaultwhen unset — the app just runs. - Everywhere else —
NODE_ENV=production,staging, or unset: the variable is required, must meet a minimum length, and is rejected if it looks like a placeholder (change-me,secret,password, …). The app refuses to boot otherwise, so forgettingNODE_ENVon a deploy can never fall back to the public dev default.
Brute-force lockout
@basaltkit/auth throttles failed logins per email out of the box — no wiring needed. After too many failures within a rolling window, login() throws AccountLockedError (HTTP 429) even for the correct password; a success clears the counter.
import { authPlugin, LoginThrottle } from '@basaltkit/auth'
authPlugin({
users,
secret: env.APP_SECRET,
// defaults to 5 attempts / 15 min; customize or disable:
loginThrottle: new LoginThrottle({ maxAttempts: 10, windowMs: 5 * 60_000 }),
// loginThrottle: false, // to turn it off
})A per-IP throttle runs alongside it (on by default) so a spray of one attempt across many accounts is caught too — pass the client IP to login({ ip }) (the built-in route does this).
Account enumeration is closed by default
The public register endpoint is enumeration-safe: registering an email that already exists returns the same 202 (and does equivalent work) as a fresh signup, so it can't be used to probe which emails have accounts. The collision is signalled out-of-band via the auth:register_existing_email hook — email the address "you already have an account; sign in or reset your password":
app.hooks.on('auth:register_existing_email', ({ email }) => sendAlreadyRegisteredEmail(email))
// opt out (classic 409 on duplicate) if you really need it:
authPlugin({ users, secret: env.APP_SECRET, enumerationSafeRegister: false })Login, password-reset and email-verification responses are likewise uniform whether or not the account exists (equalized timing, generic { ok: true }), so none of the auth endpoints leak which emails are registered.
Idempotent mutations — idempotencyPlugin
Safe retries for POST: a client that sends an Idempotency-Key gets the same response replayed on a retry, so a dropped connection never charges a card twice. It runs inside the shared route pipeline, so it behaves the same on Fastify, Express and Hono:
import { idempotencyPlugin } from '@basaltkit/http' // also re-exported by @basaltkit/fastify
// Guards POST by default. Each key is bound to its request (params, query and
// body: a different one → 422), and replays happen only after the route guards
// and validation (a revoked caller gets 401/403, not the cached success).
idempotencyPlugin()- Repeat with the same key → the cached response, with
Idempotent-Replayed: true. This holds for every handler shape — one that returns its payload is replayed exactly like one that callsreply.send(). - A repeat while the first is still in flight →
409 IDEMPOTENCY_CONFLICT. - Only the handler's own outcome is recorded. A refusal raised before the handler ran — a guard's
401/403, the rate limiter's429, a validation400— releases the key, so a client that honoursRetry-After(or signs in again) gets its operation run on the retry. 5xxresponses, the retry-later statuses408,425and429(even from the handler),stream()downloads andsse()streams are not cached, so genuine failures stay retryable. Any other client error the handler throws (4xx) is recorded and replayed byte-for-byte.- Keys are scoped by caller credentials + tenant headers + method + route pattern, hashed with SHA-256 before they reach the store. The credentials are every header in
credentialHeaders(defaultauthorization,x-session-id,cookie,x-api-key), so one credential's cached response is never replayed to another credential. The route is its pattern (/accounts/:id/charge), so the same key on two different routes never collides. If you authenticate with another header, add it tocredentialHeaders. - What the scope does not cover. The tenant part is only the raw
x-tenant-idandhostheaders — not a tenant resolved from a path segment (/t/:tenant/...) or a token claim — and the route is its pattern, not the concrete path params. The defaultfingerprint('request', below) binds those params, the query and the body, so the same credential reusing one key on/t/acme/ordersand/t/globex/orders, or on/orders/1/payand/orders/2/pay, is refused with422. Withfingerprint: 'body'orfalsethat reuse receives the first response: have clients mint a fresh key per operation (and per tenant). - The credential part is raw bytes. A retry whose credential headers differ in any byte is a different caller to the plugin: after an API key rotation, after switching from
x-api-keytoAuthorization: Bearer(or back), or after thecookieheader changed, the retry finds no record and runs the operation again. It never replays to another caller; it can duplicate. Retry with the credential the first attempt used. See API keys and idempotency. - The recorded response is stored as sent, for
ttlMs(24 h by default), in the configured store. A response that carries a secret —POST /apikeysandPOST /apikeys/:id/rotatereturn the plaintext key — sits in that store (process memory, or Redis) when the client sentIdempotency-Key. Protect a shared store like any secret store. - Requests with no credential header are not cached or replayed by default (a stranger who guessed the key would otherwise get the response). Opt in with
allowAnonymous: trueonly for public endpoints with nothing private in them. - Keys longer than 255 characters →
400 IDEMPOTENCY_KEY_INVALID;MemoryIdempotencyStoresweeps expired entries and is capped bymaxEntries(default 10 000).RedisIdempotencyStoreshares replays across instances. - It covers the routes Basalt serves (
route()definitions). A handler you register on the underlying framework by hand — a rawfastify.post(...)— is not covered: declare it withroute().
The key is bound to the request — fingerprint. A client that reuses a key for a different request (a bug, or a retry after the user edited the form) would otherwise silently receive the first request's result. The fingerprint is a SHA-256 stored with the record; a repeat whose fingerprint differs is refused with 422 IDEMPOTENCY_KEY_REUSED, also while the first request is still running. The modes:
'request'(default) — the route params, the query and the body: canonical JSON with sorted keys for a parsed body, the exact bytes for arawBody()route. The same key on/accounts/1/chargeand then/accounts/2/chargeis a422, even with an identical body.upload()routes bind only params and query: their stream belongs to the handler and is not read.'body'— the body only (canonical JSON, or the raw bytes); params and query are not bound, andupload()routes are not fingerprinted.- a function
({ route, request }) => unknown— your own fingerprint. An object or array is canonicalized first, so key order never matters; a string or other primitive is hashed as-is. Returnundefinedto skip a request. false— keys are not bound to a request.
With fingerprint on, RedisIdempotencyStore writes in-flight reservations as pending:<fingerprint>, which an instance still on the Fastify-only plugin (@basaltkit/fastify 2.5 or older) misreads during a rolling deploy: move the whole fleet onto @basaltkit/http 2.8 / @basaltkit/fastify 2.6 first, then upgrade to 3.x.
A function is how you drop volatile fields a client changes on every retry:
idempotencyPlugin({
fingerprint: ({ request }) => {
const { sentAt, ...rest } = (request.body ?? {}) as Record<string, unknown>
return { params: request.params, body: rest } // canonicalized: key order is irrelevant
},
})Where the check runs — replayAfterGuards. By default (true) the check runs after the route guards and request validation, just before the handler: a caller whose token was revoked since the first request gets the guard's 401/403 instead of the cached success, guards run on every replay (a suspended tenant gets its 403, not a replay), and a request that fails validation never reserves the key. false runs it after the enrichers and before the guards: a revoked caller presenting the same credential header then still receives the cached success. Even then, a rawBody() route fingerprinted by 'request' or 'body' is checked after the guards, since its bytes are never read before they pass.
To keep the @basaltkit/http 2.x behaviour, pass idempotencyPlugin({ fingerprint: false, replayAfterGuards: false }) — see Upgrading: idempotency is strict by default. A custom IdempotencyStore must persist record.fingerprint for a completed record to be refused with 422; to answer a concurrent repeat with 422 instead of 409 it also keeps the fingerprint passed to setPending(key, { fingerprint }) and returns { pending: true, fingerprint } from get(), as both bundled stores do.
Revoking access tokens
Access tokens (JWTs) are stateless, so they normally stay valid until they expire. Wire a TokenVersionStore to revoke them early — a password reset (and the explicit revokeAllTokens(userId)) then invalidates every token issued before the bump:
import { authPlugin, MemoryTokenVersionStore } from '@basaltkit/auth'
import { PrismaTokenVersionStore } from '@basaltkit/auth-prisma' // or SqliteTokenVersionStore
authPlugin({ users, secret: env.APP_SECRET, tokenVersions: new PrismaTokenVersionStore(prisma) })Off by default (verification then costs one store read per request). The signing secret itself is guarded too: Auth refuses to start with an empty secret, and in production (anything but an explicit NODE_ENV=development/test, unset included) rejects one shorter than 32 chars (a short HS256 key is offline-forgeable) — use secret({ minLength: 32 }).
Encrypting TOTP secrets at rest
TOTP is replay-protected out of the box (a code's time-step is recorded, so an intercepted code is single-use). To also survive a database leak, encrypt the stored secrets with an app-held key (at least 32 bytes) — they're kept as AES-256-GCM envelopes (HKDF-derived key with a key id, bound to the user) and decrypted only when verifying a code:
authPlugin({ users, secret: env.APP_SECRET, mfaEncryptionKey: env.MFA_KEY })A stored value that is not such an envelope is refused, so a write to the table cannot downgrade a secret to a plaintext one the writer knows. Key rotation and migrating plaintext or v1: rows (an explicit legacy opt-in plus auth.reencryptMfaSecret(userId)) are covered in Encrypting TOTP secrets at rest.
Secrets at rest
Every secret Basalt stores encrypted — TOTP secrets (@basaltkit/auth's SecretBox, envelope bka2) and cloud-drive OAuth tokens (@basaltkit/drives' DriveSecretBox, envelope bkd1) — goes through one audited primitive, createSecretBox from @basaltkit/core/secret-box:
- AES-256-GCM, random 96-bit IV, full 128-bit tag (a shorter tag is refused);
- HKDF-SHA256 key derivation under a per-box label, so the same key material used by two boxes yields unrelated keys;
- a key ring with ids: the first key seals, every key opens, and
reseal()moves a row to the active key — rotation is rolling; - AAD binding to the owning record (user, or tenant + connection + provider): a blob copied into another row fails the tag check;
- no plaintext path: anything that is not an envelope of that box is refused.
Use it for a secret of your own (webhook signing secrets, third-party API tokens) instead of hand-rolling AES:
import { createSecretBox } from '@basaltkit/core/secret-box'
const box = createSecretBox({
keys: [{ id: '2026-10', key: env.INTEGRATIONS_KEY }], // ≥ 32 bytes; new keys go first
info: 'my-app:integration-tokens:v1', // unique per box
version: 'mya1', // envelope tag, [a-z0-9]{1,16}
aadFields: 2, // what each secret is bound to
})
const sealed = box.seal(token, [tenantId, integrationId])
const token2 = box.open(sealed, [tenantId, integrationId]) // throws SecretBoxError otherwiseFailures throw SecretBoxError with a failure of config, malformed, unknown-key, context or auth-failed (never the secret or the key). The subpath is not re-exported from @basaltkit/core's main entry.
Outbound HTTP & SSRF
Any time your app fetches a URL it did not write — a tenant's "import from URL", an avatar link, a file a provider points at — that URL is hostile input: it can name 169.254.169.254, a database on your private network, or a public host that redirects to one. Don't use bare fetch for it. @basaltkit/webhooks exports the streaming client @basaltkit/drives uses for every provider call:
import { createGuardedFetch, GuardedFetchError } from '@basaltkit/webhooks'
const fetchUntrusted = createGuardedFetch({
maxBytes: 20 * 1024 * 1024, // required: abandoned mid-stream past this
timeoutMs: 15_000, // socket inactivity + each hop's wait for headers
deadlineMs: 120_000, // optional: the whole exchange, body included
allowedHosts: ['.example-cdn.com'], // optional: `.suffix` = subdomains only
})
const response = await fetchUntrusted(url)
await files.upload(response.body, { name: 'import.pdf' }) // streamed, cappedWhat it enforces, on every redirect hop: https: only (widen with allowedSchemes), the optional host allowlist, DNS resolved once with every answer checked against private/loopback/link-local/CGNAT/ULA/reserved and IPv4-embedded IPv6 ranges, the socket pinned to the validated IP (no DNS rebinding), at most maxRedirects (3) hops with authorization/cookie dropped on a hop to another host, no accept-encoding (so a decompression bomb cannot hide behind the cap), and the byte cap counted on the wire.
Refusals throw GuardedFetchError with kind SSRF_BLOCKED, BODY_TOO_LARGE, TIMEOUT or TOO_MANY_REDIRECTS (code OUTBOUND_<kind>). The message names the host, never the URL — a pre-signed URL is a credential — and expose is false, so a client only sees the code. allowPrivateHosts is the one escape hatch, for a self-hosted target on your own network.
Shared responsibility — hardening your integration
Basalt closes the vulnerabilities it can close on its own. Three things, though, depend on how your app wires the pieces together — the framework can't decide them for you. Get these right in every deployment.
1. Authorization is explicit — declare a guard, don't just declare intent
A route's meta.auth / meta.can / meta.teamRole / meta.scopes / meta.subscribed / meta.feature documents what the route needs, but the guard that enforces it must actually be registered. A declared-but-unguarded route would be open — so the adapters refuse to boot it: at startup they verify that every declared security meta key has a registered guard claiming it (via the http:guarded-meta bucket) and fail loud listing every offending route.
// ❌ meta says "admin", but nothing enforces it → UnguardedRouteMetaError at BOOT
route({ method: 'POST', url: '/admin/purge', meta: { can: 'admin' }, handler })
// ✅ register the plugin whose guard enforces the key
authPlugin(…) // enforces meta.auth
permissionsPlugin(…) // enforces meta.can
teamsPlugin(…) // enforces meta.teamRole
apiKeysPlugin(…) // enforces meta.scopes
subscriptionsPlugin(…) // enforces meta.subscribed and meta.featureThe full guarded set is auth, can, teamRole, scopes, subscribed and feature (GUARDED_META_KEYS). Keys that relax rather than protect are deliberately excluded — meta.central (skips the tenant-membership check), meta.mcp (opts a route into MCP exposure) and meta.rateLimit (abuse throttling, not an authorization boundary). A meta.rateLimit with no limiter registered (no securityPlugin({ rateLimit })) does not refuse the boot, but the adapter warns once, naming the routes, that those budgets are not enforced. Silence it with allowUnguardedMeta: ['rateLimit'] (or true) when an outer edge throttles.
If protection genuinely happens at an outer edge/gateway, opt out explicitly with the adapter option allowUnguardedMeta: true (or ['auth', …] for specific keys). A custom guard plugin that enforces one of these keys should claim it: ensureMetadata(container).add('http:guarded-meta', 'auth').
Claiming a key proves someone enforces it; it says nothing about the value. For that, a plugin registers a route-meta validator in http:meta-validators (META_VALIDATORS_BUCKET): every adapter runs them over its full route list at boot, right after the guarded-meta check, and refuses to start with InvalidRouteMetaError (HTTP_INVALID_ROUTE_META) listing every route: problem. teamsPlugin uses it so meta.teamRole: 'Admin' (a typo) fails the boot instead of answering 500 on the first request. allowUnguardedMeta never waives validators.
const validator: RouteMetaValidator = ({ route, container }) =>
typeof route.meta?.['shape'] === 'string' || route.meta?.['shape'] === undefined
? undefined
: `meta.shape must be a string` // or string[] for several problems; throwing counts too
ensureMetadata(container).add(META_VALIDATORS_BUCKET, validator)Driving runRoute() without an adapter? assertRoutesGuarded(routes, app.container) runs both checks; assertRouteMetaValid(routes, app.container) runs the validators alone.
A guard may also publish a pure visibility check in http:route-visibility (RouteVisibilityCheck, evaluated by isRouteVisible) — "could this caller possibly pass?" with no side effects (no rate limit, no audit, no hooks), used by listing surfaces such as MCP's tools/list. Visibility is never authorization: the guard still runs on every call.
2. Never trust a client-supplied tenant — verify membership
Resolving the active tenant from a request header (or subdomain, or path) is convenient, but the header is attacker-controlled. Reading X-Tenant-Id: acme and scoping to acme without checking that the authenticated user actually belongs to acme lets any logged-in user read another tenant's data.
// ❌ tenant taken straight from a client header — cross-tenant access
const tenantId = req.headers['x-tenant-id']
// ✅ resolve, then confirm the user is a member before trusting it
const tenantId = req.headers['x-tenant-id']
if (!(await teams.can(tenantId, ctx().user.id, 'member'))) {
throw new ForbiddenError()
}Bind tenant selection to a verified user↔tenant membership (via @basaltkit/teams, an API-key's tenantId, or a session claim) — never to the raw request alone.
Do this for every route at once with tenantMembershipPlugin. Instead of repeating the check, register the guard from @basaltkit/teams: on every authenticated, tenant-scoped request it asserts the user is a member of the resolved tenant and returns 403 otherwise. Central routes that legitimately act outside one tenant (login, tenant creation, platform admin, invite accept) opt out with meta: { central: true }.
import { teamsPlugin, tenantMembershipPlugin } from '@basaltkit/teams'
createApp({
plugins: [
authPlugin(/* … */),
tenancyPlugin(/* … */),
teamsPlugin(/* … */),
tenantMembershipPlugin(), // secure by default: membership enforced everywhere
],
})
// a route the current user is not a member of → 403; central route opts out:
route({ method: 'POST', url: '/tenants', meta: { central: true }, /* … */ })By default the guard checks membership existence — any membership record passes, so custom roles absent from roleRank are not rejected; pass role: 'member' (or higher) to enforce rank semantics. Two more options:
tenantMembershipPlugin({
// WHO-based escape: platform admins / support cross tenants legitimately.
// Prefer this over meta.central when the exemption is about the caller —
// central disables the guard for everyone on that route.
exempt: ({ user }) => (user as { platformAdmin?: boolean })?.platformAdmin === true,
// Opt-in decision cache: without it, each authenticated tenant request costs
// one indexed membership lookup (usually fine). Cached decisions are dropped
// immediately by the team:joined/role_changed/member_removed hooks in the
// same process; ttlMs only bounds staleness for changes made on ANOTHER
// replica — a member removed elsewhere may retain access for up to ttlMs.
cache: { ttlMs: 30_000 },
})3. Automatic tenant scoping covers the ORM — not raw SQL or foreign-key scalars
The Prisma tenancy extension scopes model operations (nested relation writes included) and fails closed: without a tenant context, and for any operation it cannot scope (PRISMA_UNSCOPED_OPERATION). Update data cannot move a row to another tenant (PRISMA_CROSS_TENANT_WRITE). Two paths sit outside that net:
- Raw queries —
$queryRaw,$executeRaw,$queryRawTyped,$runCommandRaw(every client-level operation) and MongoDBfindRaw/aggregateRawbypass model scoping. Basalt refuses them by default when a tenant is in scope (PRISMA_RAW_IN_TENANT), so a raw query can't silently read across tenants. Run them in central code (no tenant in context), or add thetenant_id = $1predicate yourself and setonRawInTenant: 'allow'. - Foreign-key scalars — nested
connect/createare scoped, but a raw FK value (data: { projectId: body.projectId }) is not checked, and anincludefollows whatever FK is stored. Use composite foreign keys(tenantId, id)(the database then refuses a cross-tenant link) and RLS, or verify the related record belongs to the current tenant first.
// ❌ raw query inside a tenant context now throws PRISMA_RAW_IN_TENANT
await db.$queryRaw`SELECT * FROM invoices WHERE status = ${status}`
// ✅ scope explicitly, parameterized, and opt in
const tenantId = ctx().tenant.id
await db.$queryRaw`
SELECT * FROM invoices WHERE status = ${status} AND tenant_id = ${tenantId}`
// with tenancyExtension({ onRawInTenant: 'allow' })Defense in depth — enable Postgres RLS. Application-layer scoping is one layer; add a database-enforced one so even a forgotten predicate can't leak — including the foreign-key include above, which the extension cannot see. rlsPolicySql generates the migration, and tenancyExtension({ rls: true }) names the active tenant to Postgres on every tenant-scoped operation:
import { rlsPolicySql, tenancyExtension, tenantTransaction } from '@basaltkit/prisma'
import { PrismaPg } from '@prisma/adapter-pg'
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! })
// migration (once): put the generated SQL in a Prisma migration — it enables
// and FORCEs RLS and adds a tenant-isolation policy on each table
console.log(rlsPolicySql({ tables: ['invoices', 'projects'], tenantColumn: 'tenantId' }))
// every model operation in tenant scope now runs as
// $transaction([ set_config('app.tenant_id', <tenant>, true), <operation> ])
const db = new PrismaClient({ adapter }).$extends(tenancyExtension({ rls: true }))
// interactive transactions: open them with tenantTransaction, which sets the
// tenant on the transaction's own connection first — tx stays tenant-scoped
await tenantTransaction(db, async (tx) => {
const invoice = await tx.invoice.create({ data })
await tx.invoiceLine.createMany({ data: lines(invoice.id) })
})- Connect as a role RLS applies to. Superusers and
BYPASSRLSroles skip every policy; table owners skip them unless the table hasFORCE ROW LEVEL SECURITY(rlsPolicySqladds it by default). Run the app as a plain login role and keep migrations/admin work on a separate one. - No tenant means no rows — even on a reused connection. The policy compares against
NULLIF(current_setting('app.tenant_id', true), ''): once a pooled session has set the tenant in any transaction, Postgres returns''(notNULL) for it afterwards, and a bare comparison would match rows whose tenant column is''. Policies generated before@basaltkit/prisma3.0 lack theNULLIF— re-runrlsPolicySql(idempotent) in a new migration. - Costs. Each tenant-scoped operation becomes a short batch transaction (
BEGIN,set_config, the query,COMMIT) — a few extra statements on the same connection (≈ +2 ms p50 in the app team's measurements). The setting is transaction-local (set_config(…, true)), so it never leaks onto a pooled connection. - Transactions you open yourself are not wrapped (they can't be nested): a plain interactive
db.$transaction(async (tx) => …)runs without the tenant setting and fails closed (reads see no rows, writes fail with42501) — usetenantTransaction(db, fn)instead. A batchdb.$transaction([...])must lead with the setting:db.$executeRawUnsafe(setTenantConfigSql(), ...tenantConfigParams(tenantId)). That exact statement, for the tenant already in scope, is the one raw query thePRISMA_RAW_IN_TENANTguard lets through — every other raw query is still refused. - A client with
onMissingTenant: 'bypass'sends no setting, so under RLS it sees nothing: give central/admin code its own database role (BYPASSRLS, or one the policies don't cover).
Full-text search under RLS — the GIN index silently disappears. RLS on a table that also has a tsvector column with a GIN index (what @basaltkit/search-postgres creates) is a trap nothing warns about: PostgreSQL may only evaluate a qualifier before a row-security policy if that qualifier is LEAKPROOF, and the text-search operator @@ is not. So for the very role the policy protects you with, tsv @@ plainto_tsquery(…) can never be an index condition — it becomes a filter applied after the policy, and the plan degrades to a sequential scan over every tenant's rows. Measured on 30 200 documents (PostgreSQL 16):
-- as the owner -- as the application role, same SQL
-> Bitmap Heap Scan -> Seq Scan on basalt_search
Recheck Cond: (tsv @@ …) Filter: (… AND (tsv @@ …))
-> Bitmap Index Scan on Rows Removed by Filter: 30197
basalt_search_tsv_idx Execution Time: 14.702 ms
Execution Time: 4.920 ms (~24x slower, warm)rlsSearchFunctionSql generates the fix: a SECURITY DEFINER search function that re-applies the tenant predicate itself, so @@ is an index condition again while the rows it can ever return are still exactly one tenant's.
import { rlsSearchFunctionSql } from '@basaltkit/prisma'
// migration (once), run as a role that bypasses the table's RLS
rlsSearchFunctionSql({
name: 'basalt_search_scoped', table: 'basalt_search', vectorColumn: 'tsv',
partitionColumn: 'idx', filterColumn: 'document',
columns: [{ name: 'document', type: 'jsonb' }],
role: 'app', owner: 'app_owner', maxRows: 100,
})
// runtime — the driver routes text queries through the function
new PostgresSearchDriver({ client: pool, searchFunction: 'basalt_search_scoped' })-- as the application role, through the function
-> Bitmap Heap Scan on basalt_search t
Filter: ((idx = 'notes') AND (tenant_id = NULLIF(current_setting('app.tenant_id', true), '')))
-> Bitmap Index Scan on basalt_search_tsv_idx
Execution Time: 1.850 msThe function takes no tenant parameter: it reads the tenant from the same current_setting(…) the policy reads (the one tenancyExtension({ rls: true }) already sets), so there is nothing for a caller to point elsewhere, and an unset setting reads as NULL — no rows, never all rows. It is hardened like the cross-tenant scan (pinned search_path, validated identifiers, EXECUTE revoked from PUBLIC, p_limit clamped), and the driver additionally refuses any returned row whose tenant is not the one it asked for.
Never ALTER FUNCTION ts_match_vq(tsvector, tsquery) LEAKPROOF. It is the shortcut every search result suggests, and it does bring the index back — by weakening the leakproof rule database-wide, for every table and every policy in the database, so a crafted @@ becomes a side channel for probing rows a policy hides. A local speed-up bought with a global loss of isolation.
Sweeping every tenant — the one hole, made narrow. A reconciler has to find stuck rows across all tenants, which under RLS the application role can never see. crossTenantScanSql generates the only safe shape of that query: a SECURITY DEFINER function that returns identifiers only (tenant id + row id), owned by a role the policies don't reach, with search_path pinned inside it and EXECUTE revoked from PUBLIC. crossTenantSweep then processes every identifier back inside its own tenant's scope, where the policies apply again:
import { crossTenantScanSql, crossTenantSweep } from '@basaltkit/prisma'
// migration (once): identifiers only — never a column holding tenant data
crossTenantScanSql({
name: 'stuck_jobs', table: 'jobs', tenantColumn: 'tenantId', columns: ['id'],
where: `t."status" = 'PROCESSING' AND t."updatedAt" < now() - interval '15 minutes'`,
role: 'app', owner: 'app_owner', maxRows: 500,
})
// reconciler (central code, no tenant in scope)
await crossTenantSweep({
client: db,
scanFunction: 'stuck_jobs',
run: (tenantId, fn) => tenancy.run(tenantId, fn),
handle: (item) => RetryJob.dispatch({ jobId: item.id }),
})The function is a deliberate RLS bypass, so treat its definition as security-critical: widen it to one data column and every caller with EXECUTE reads every tenant. Basalt fails closed around it — the scan refuses to run inside a tenant context (PRISMA_CROSS_TENANT_IN_TENANT; unlike the internal set_config, it gets no exemption from the raw guard), refuses a deployed function that returns columns you did not declare (PRISMA_CROSS_TENANT_SCAN_SHAPE), and pages with a capped, ordered cursor so a sweep can't pull the whole table. Without RLS the function isn't needed at all: pass an ordinary central query as scan. See the scheduler guide.
When in doubt, prefer model operations (which are scoped automatically) over raw SQL, and review every connect against the current tenant.
4. CSRF — safe by default with header auth; cookies are your responsibility
Basalt authenticates every request from a header — Authorization: Bearer <jwt> or x-session-id: <id> (see the auth enricher). This is CSRF-safe by design: a cross-site request forgery works only with credentials the browser attaches automatically (cookies, HTTP Basic). A custom header is never sent cross-origin on a forged request, so an attacker's page can't ride the victim's session. Keep auth in a header and there is nothing to do.
The session cookie authRoutes() sets on login (basalt_session) is covered by authPlugin's built-in check: a cookie-only request with an unsafe method that the browser marks cross-site/same-site, or whose Origin is not your own host or a csrf.trustedOrigins entry, is not authenticated (403 AUTH_CSRF_REJECTED on meta.auth routes) — see Cookie sessions and CSRF.
You take on CSRF yourself the moment you move a credential into a cookie of your own — e.g. storing a JWT in a cookie so the browser sends it automatically. If you do, protect it yourself:
- Set the cookie
SameSite=Lax(orStrict),HttpOnly, andSecure.SameSite=Laxalone stops the common cross-sitePOST. - Add a second check for state-changing requests: a double-submit CSRF token (a random value mirrored in a cookie and a header/body field, compared on the server), or an Origin/Referer allow-list.
- Never rely on CORS for this — CORS governs reading a response, not whether a forged request is sent. A form
POSTfires regardless of CORS.
// ✅ preferred — no cookie, no CSRF surface
fetch('/api/pay', { method: 'POST', headers: { authorization: `Bearer ${jwt}` } })
// ⚠️ if you must use a cookie session, add SameSite + a CSRF token check
setCookie('sid', session.id, { httpOnly: true, secure: true, sameSite: 'lax' })Route security review — basalt routes
basalt routes lists every route with the guards it declares: auth, can, rateLimit, tenant and the other guarded keys (mfa, teamRole, scopes, subscribed, feature). The tenant column reads required (meta.tenant: true), exempt (meta.tenant: false), central-only (meta.tenant: 'never' — the route rejects any request that resolves a tenant), or is blank when the route inherits the app-wide default. The column reflects meta.tenant only: meta.central: true (the @basaltkit/teams membership bypass) shows in the guards column as central; assert on row.tenant === 'central-only' to pin a console route to the central plane. Two ways to turn that into a gate:
# CI: exit 1 when a route does not declare both auth and can (explicit opt-outs pass)
pnpm basalt routes --unguarded --require=auth,can --allow='POST /webhooks/*'
pnpm basalt routes --json > routes.json # the whole table, for review or diffing// A vitest that boots the app (no listen) and asserts on the same rows
import { ensureMetadata } from '@basaltkit/core'
import { describeRoutes, findUnguardedRoutes } from '@basaltkit/http'
it('every route declares auth + can', async () => {
const app = await buildApp().boot()
const rows = describeRoutes(ensureMetadata(app.container).get('http:routes'))
expect(findUnguardedRoutes(rows, { require: ['auth', 'can'] })).toEqual([])
await app.shutdown()
})auth: false (or public: true) is an intentional opt-out and satisfies both requirements; can: false satisfies can. Only auth: true counts as auth — it is the one value authPlugin enforces. This checks route meta only: an app-wide rate limit, URL-based tenancy (tenancyPlugin({ required: { except } })), app hooks or middleware, and the edge routes plugins mount themselves (healthPlugin, metricsPlugin, openapiPlugin) are invisible to it — a clean run means "every route asks for protection", while the boot check above guarantees a guard is there to enforce it.
Catch regressions automatically — ai:doctor
basalt ai:doctor statically checks your project against the framework's security invariants — offline, no API key. Two checks encode the most important guarantees from the security guide:
missing-tenant-membership(error) — you wire tenancy + auth but notenantMembershipPlugin(whether or not@basaltkit/teamsis installed — if it is not, the fix is to install it), so a resolved tenant is never bound to a verified member. This is the cross-tenant-access class in section 2.missing-security-plugin(warning) — nosecurityPlugin(), so responses ship without secure headers.
basalt ai:doctor # run it in CI to fail the build on a security regressionWire it into your pipeline so a change that drops the membership guard or the security plugin turns the build red instead of shipping.
Supply chain
CI runs pnpm audit (high severity), CodeQL SAST, and Dependabot keeps dependencies and Actions current. Releases publish to npm with provenance (NPM_CONFIG_PROVENANCE) via changesets — no manual tokens or OTP in the pipeline.