Skip to content

What's new in Basalt 1.13 ​

"Basalt 1.13" is the umbrella label for this wave of work; the @basaltkit/* packages ship independently (see Versioning). Below is what landed and the package version that carries it.

No package publishes a major

Forty-five packages publish in this wave: forty-four minors and patches, and one debut, @basaltkit/inbound-mail 0.1. Three 0.x packages move a minor — drives 0.4, mcp-core 0.5 and ai-mcp 0.4 — and none of them removes an API. Some defaults change and a few configurations that used to boot silently now print a boot warning; the stricter refusals arrive in a future major. Read Upgrading before you bump.

Basalt 1.13 is the release that closes the backlog without a major. While 1.12 was being audited, a document-management SaaS kept building on the framework and kept a list — items BK-025 to BK-087 — of every place it had to write by hand what the framework should have written: an idempotency plugin that only Fastify had, a tenant database client that stayed reserved for thirty seconds after each request, a webhook outbox that dead-lettered every entry under schema-per-tenant, an audit trail that could not forget a person without failing its own integrity check, API keys that every machine client shared one rate-limit bucket with.

This wave closes that list. Each item landed as a minor or a patch, with tests on Fastify, Express and Hono wherever it touches a request, and a release audit read the result before it shipped. The items that could only land as a breaking change — a warning that should become a refusal, a deprecated override that should stop being consulted — keep their warning for now and wait for the next major. Three deferred designs got their own RFC first: erasable audit chains, policy list filters (where an ORM-level row filter was considered and rejected) and inbound mail.

Since 1.13: the majors wave ​

Published to npm on 2026-10-11, after the 1.13 release (the umbrella version stays 1.13). Unlike the 1.13 minors, this wave does carry majors: @basaltkit/http 3.0 (with fastify, express, hono and testing 3.0) makes idempotency strict by default, @basaltkit/auth-prisma 3.0 needs a database migration, and the configurations 1.13 only warned about now refuse to boot (@basaltkit/auth 5.0, tenancy 4.0, http 3.0, notifications 2.0). Packages whose peer or shared dependency is one of those majors move a major with it, with no API change of their own (the list). The @basaltkit/* set moves together: read Upgrading before you bump.

  • API key lifecycle. ApiKeys.rotate() replaces a key's secret and keeps its id, with an optional grace window (up to 30 days) for the old secret; update() / setExpiry() change a key in one write; list({ includeExpired }) shows expired keys. Keys can act as a service (serviceId, scopes only, never ctx().user), carry an IP allowlist (403 AUTH_APIKEY_IP_NOT_ALLOWED, fail-closed, also emitted as the audited auth:apikey_refused) and flat meta. apiKeyRoutes() adds PATCH /apikeys/:id and POST /apikeys/:id/rotate, on every adapter. (@basaltkit/auth 5.0, auth-sqlite 3.0 — auto-migrated; auth-prisma 3.0 — migration below; create-basalt 1.13 scaffolds the new model.) See API keys.
  • Service callers in the audit trail. auditPlugin({ actor }) resolves the actorId of a request, so a service key can be attributed in your own id format; the default stays ctx().user?.id. (@basaltkit/audit 3.2)
  • MCP sessions bound to a userless key. A /mcp session opened with a userless API key is bound to that key's id: a leaked mcp-session-id is refused (404) for another key or an anonymous caller. (@basaltkit/mcp 6.0)
  • Idempotency is strict by default. A reused Idempotency-Key with a different request gets 422, and replays run after the guards. (@basaltkit/http 3.0) See below.
  • 1.13's boot warnings become refusals. A prefixed session cookie that browsers would drop, an unknown meta.tenant value and an invalid meta.responseHeaders no longer boot, and the Notifier decides through preference() only. (@basaltkit/auth 5.0, tenancy 4.0, http 3.0, notifications 2.0) See below.

Upgrading ​

Upgrade the whole @basaltkit/* set at once. This wave is not a menu. The packages share live objects with your app — container tokens, the adapter's error classes, the RouteMeta type every plugin augments — and a container token is a module-local symbol, so a second copy of a package never finds your app's binding. The adapters 3.0 run @basaltkit/http 3, auth 5 needs stores that implement its new methods, and every package that plugs into those moves with them. Mixing an old line with a new one is refused by the peer ranges where npm can see it, and breaks at boot or at request time where it cannot.

The shortest path is one command, which crosses every framework major in one go and prints each package's CHANGELOG link:

bash
pnpm basalt update --dry          # the plan
pnpm basalt update                # writes, installs, runs the codemods
npx create-basalt@latest update   # the same, in an app without the basalt script

Then take the steps that need you:

  1. Idempotency — clients that retry with a changed body or query now get 422; see idempotency is strict by default.
  2. auth-prisma — add the six API-key columns before the new client serves traffic; see Upgrading to auth-prisma 3.0.
  3. Boot refusals — fix whatever 1.13 warned about; see boot warnings that now refuse.
  4. MCP — tool routes passed to mcpPlugin({ routes }) now get the same boot checks as adapter routes, and an MCP client must send the same API key on every request of a session; see Other changes to watch.
  5. Shared peers — @basaltkit/mailer is now a peer of notifications 2 and testing 3, and @basaltkit/audit a peer of audit-viewer 3.1: each reads or binds that package's container token, so it must use your app's copy. pnpm basalt update (create-basalt 1.13) adds a required @basaltkit/* peer your package.json does not list, at its latest version, or warns when it cannot; by hand it is pnpm add @basaltkit/mailer. Do not rely on your package manager installing peers for you: yarn PnP, auto-install-peers=false and --legacy-peer-deps do not, and pnpm basalt doctor only sees what is installed.

Intentional incompatibilities. These combinations do not work, by design:

You keepNext toWhat happens
an adapter 2.x (fastify 2.6, express/hono 2.1)@basaltkit/http 3two copies of http: idempotencyPlugin gets the defaults of whichever copy you import it from, and plugins built against http 3 do not match the adapter's error classes
@basaltkit/auth 4.xauth-prisma 3 / auth-sqlite 3peer range refused (auth ^5); the stores implement ApiKeyStore.update and the lifecycle columns
auth-prisma 2 / auth-sqlite 2@basaltkit/auth 5peer range refused; rotate(), update() and setExpiry() need the new store method
@basaltkit/tenancy 3.xtenancy-prisma 3 / tenancy-sqlite 2peer range refused
@basaltkit/notifications 1.xnotifications-prisma 2 / -sqlite 2peer range refused
permissions 4 / subscriptions 5@basaltkit/http 3their meta.can / meta.subscribed typings target the other http copy, and a permissions validation 400 becomes a 500 (instanceof across copies)
auth-saml 3 / billing-ui 1auth 5 / subscriptions 6they bundled their own copy of auth / subscriptions; reading the app's AUTH / SUBSCRIPTIONS binding fails at boot. 4.0 / 2.0 make it a peer
@basaltkit/mcp 5@basaltkit/http 3tool calls run through http 2's pipeline while the HTTP routes run http 3's rules
@basaltkit/prisma 3@basaltkit/http 3peer range refused (request leases ride the http pipeline's ctx().onDispose)

The eleven patches (comments, files, drives, teams, teams-ui, api-keys-ui, inbound-mail, cli, activity, backup, dashboard) work on either line — they only build routes or read data through a private copy — but update takes them too, and that is what we test. Mixed lines (a patch on http 3 next to an adapter 2.x) are verified at runtime only, not by a typecheck: if TypeScript rejects passing their routes to an adapter 2.x, upgrade the adapter with them.

Release map. Every package this wave publishes (from changeset status):

PackagePublishedNextBumpWhy
@basaltkit/http2.8.03.0.0majorstrict idempotency; invalid meta.responseHeaders refused at boot; enrichers without a container fail closed
@basaltkit/fastify2.6.03.0.0majorneeds http 3
@basaltkit/express2.1.03.0.0majorneeds http 3
@basaltkit/hono2.1.03.0.0majorneeds http 3
@basaltkit/testing2.0.33.0.0majoroptional adapter peers move to 3.x; @basaltkit/mailer becomes a peer
@basaltkit/auth4.2.05.0.0majorinvalid session cookie refused; API key lifecycle (ApiKeyStore.update)
@basaltkit/auth-prisma2.1.03.0.0majordatabase migration (six columns)
@basaltkit/auth-sqlite2.1.03.0.0majorauth peer ^5 (auto-migrates)
@basaltkit/auth-saml3.0.04.0.0major@basaltkit/auth becomes a peer
@basaltkit/tenancy3.2.04.0.0majorunknown meta.tenant refused at boot and fails closed per request
@basaltkit/tenancy-prisma2.1.03.0.0majortenancy peer ^4
@basaltkit/tenancy-sqlite1.3.02.0.0majortenancy peer ^4
@basaltkit/notifications1.3.02.0.0majorallowed() removed; @basaltkit/mailer becomes a peer
@basaltkit/notifications-prisma1.2.02.0.0majornotifications peer ^2
@basaltkit/notifications-sqlite1.1.02.0.0majornotifications peer ^2
@basaltkit/prisma3.1.04.0.0majoroptional http peer ^3
@basaltkit/mcp5.1.06.0.0majorhttp 3 pipeline; boot checks on tool routes; sessions bound to a userless key
@basaltkit/permissions4.1.05.0.0majorshares the app's http 3
@basaltkit/permissions-prisma2.1.03.0.0majorpermissions peer ^5
@basaltkit/permissions-sqlite2.1.03.0.0majorpermissions peer ^5
@basaltkit/subscriptions5.0.06.0.0majorshares the app's http 3
@basaltkit/subscriptions-prisma3.0.04.0.0majorsubscriptions peer ^6
@basaltkit/subscriptions-sqlite3.0.04.0.0majorsubscriptions peer ^6
@basaltkit/subscriptions-proxypay2.1.53.0.0majorsubscriptions peer ^6
@basaltkit/subscriptions-pdf0.1.50.2.0minor (0.x breaking)subscriptions peer ^6
@basaltkit/billing-ui1.2.02.0.0major@basaltkit/subscriptions becomes a peer
@basaltkit/audit3.1.03.2.0minorauditPlugin({ actor })
create-basalt1.12.01.13.0minorAuthApiKey lifecycle model; ranges floored at the exact version; update adds missing required @basaltkit/* peers
@basaltkit/activity1.3.21.3.3patchtenancy ^4 (private copy)
@basaltkit/api-keys-ui1.4.01.4.1patchhttp ^3 (private copy)
@basaltkit/audit-viewer3.0.23.1.0minor@basaltkit/audit becomes a peer ^3.0.0 (reads the app's AUDIT binding; audit 3.0/3.1 still fit); http ^3 (private copy)
@basaltkit/backup0.3.20.3.3patchprisma ^4 (private copy)
@basaltkit/cli1.4.01.4.1patchhttp ^3 (private copy)
@basaltkit/comments4.1.04.1.1patchhttp ^3 (private copy)
@basaltkit/dashboard1.4.51.4.6patchsubscriptions ^6 (types only)
@basaltkit/drives0.4.00.4.1patchhttp ^3 (private copy)
@basaltkit/files6.1.06.1.1patchhttp ^3 (private copy)
@basaltkit/inbound-mail0.1.00.1.1patchhttp ^3 (private copy)
@basaltkit/teams4.1.04.1.1patchhttp ^3 (private copy)
@basaltkit/teams-ui1.2.01.2.1patchhttp ^3 (private copy)

Majors forced by dependencies ​

Apart from mcp (noted in its row), these packages change no API of their own. They move a major because the package they must share with your app moved one, so the old line cannot run next to the new one. Upgrade each together with the package it follows.

PackageNextFollowsWhy it must match
@basaltkit/testing3.0fastify / express / hono 3optional adapter peers (3.0 also makes @basaltkit/mailer a peer: fakeMailer() binds the app's MAILER)
@basaltkit/prisma4.0http 3optional peer (request leases)
@basaltkit/auth-sqlite3.0auth 5peer; implements ApiKeyStore.update
@basaltkit/tenancy-prisma, tenancy-sqlite3.0, 2.0tenancy 4peer
@basaltkit/notifications-prisma, notifications-sqlite2.0, 2.0notifications 2peer
@basaltkit/mcp6.0http 3runs your routes through the http pipeline (6.0 also has changes of its own: boot checks and key-bound sessions)
@basaltkit/permissions5.0http 3augments RouteMeta (meta.can); its 400 relies on the adapter's error classes
@basaltkit/permissions-prisma, permissions-sqlite3.0, 3.0permissions 5peer
@basaltkit/subscriptions6.0http 3augments RouteMeta (meta.subscribed, meta.feature)
@basaltkit/subscriptions-prisma, -sqlite, -proxypay4.0, 4.0, 3.0subscriptions 6peer
@basaltkit/subscriptions-pdf0.2subscriptions 6peer (0.x: the minor is the breaking line)
@basaltkit/auth-saml4.0auth 5, http 3@basaltkit/auth is now a peer: it reads the app's AUTH binding
@basaltkit/billing-ui2.0subscriptions 6, http 3@basaltkit/subscriptions is now a peer: it reads the app's SUBSCRIPTIONS binding

Packages that only build routes or read data with @basaltkit/http, tenancy, prisma or subscriptions as an ordinary dependency (comments, files, drives, teams, teams-ui, api-keys-ui, inbound-mail, cli, activity, backup, dashboard) get a patch: their routes run on either http line, so nothing on your side changes.

Upgrading: idempotency is strict by default (@basaltkit/http 3) ​

@basaltkit/http 3.0 flips the two idempotencyPlugin defaults that 2.x left off. @basaltkit/fastify, @basaltkit/express and @basaltkit/hono move to 3.0 with it (and @basaltkit/testing, whose adapter peer ranges follow); none of them changes its own API.

What changes.

  • A reused Idempotency-Key carrying a different request — other route params (/accounts/2/charge after /accounts/1/charge), another query string or another body — is refused with 422 IDEMPOTENCY_KEY_REUSED instead of silently receiving the first request's result. The new default fingerprint: 'request' binds params, query and body; 'body' keeps its 2.x meaning (the body only).
  • The check runs after the route guards and request validation (replayAfterGuards: true). A caller whose token was revoked, or whose permission was removed, gets the guard's 401/403 instead of the cached success; guards run on every replay.
  • A request refused by a guard or by validation no longer reserves the key at all. 1.13 already released such a refusal instead of replaying it; now a concurrent repeat is not answered 409 while the first is being refused either, and the corrected retry runs. Refusals raised by the handler itself keep 1.13's rules (408, 425, 429 and 5xx released, other 4xx replayed).

Who is affected.

  • Clients that put volatile fields in a retried body or query (timestamps, nonces, cache-busters) now get 422. Drop those fields with a function fingerprint (below), or send them as headers.
  • Forms that retry an edited submission under the same key now get 422. A new submission needs a new key.
  • Guards that are expensive or have side effects now run on every retry.
  • A schema tightened between the first attempt and its retry (a deploy adding a required field) now answers the retry 400, not the replay of the first success. Clients must not read that 400 as "not charged" and resubmit with a new key.
  • A guard-based rate limit (meta.rateLimit) now counts retries, so a retry storm can get 429 where 2.x replayed the 201.
  • upload() routes bind only params and query (their stream belongs to the handler and is not read); a different file under the same key still replays. Use a function fingerprint to bind more.
  • A fingerprint function that returns an object or array is now canonicalized (keys sorted at every level) instead of being hashed as "[object Object]" — the same for every object, a latent collision.

Keeping the 2.x behaviour. Both options stay supported:

ts
idempotencyPlugin({ fingerprint: false, replayAfterGuards: false }) // 2.x defaults

Or one axis at a time: fingerprint: 'body' ignores params and query, fingerprint: false binds nothing, a function binds what you choose (for example the body without a sentAt field), and replayAfterGuards: false restores the check before the guards.

Rolling deploy with a shared RedisIdempotencyStore. A fingerprinted reservation is stored as pending:<fingerprint>, and with the new default every reservation is fingerprinted. RedisIdempotencyStore from @basaltkit/fastify 2.5 or earlier does not understand that value and answers a concurrent repeat of the same key with 500. Move the whole fleet onto the last 2.x line (@basaltkit/http 2.8 / @basaltkit/fastify 2.6) first, then deploy 3.0.

Bump @basaltkit/http with the adapter. All three adapters are 3.0 and depend on @basaltkit/http 3. Raise your own @basaltkit/http range to ^3 in the same change, or the app can end up with two copies and the defaults of whichever one it imports idempotencyPlugin from. create-basalt update resolves the latest versions for you.

No data step. Scope hashes are unchanged, and records stored by 2.x carry no fingerprint, so they never mismatch: they keep replaying until they expire. The exception is a record that 2.x did fingerprint under a mode whose hash changes with the upgrade: an app that drops an explicit fingerprint: 'body' to take the 'request' default, or a function that returns an object or array. A retry that spans the deploy then gets 422; keep the 2.x option until the records have expired (24 h by default) if that matters.

Custom stores. No contract change, but a custom IdempotencyStore must persist record.fingerprint for completed records to be refused with 422. A store that drops the fingerprint on the reservation answers a concurrent repeat with a different request 409 instead of 422.

Upgrading to auth-prisma 3.0 ​

AuthApiKey (auth_api_keys) gains six nullable or empty-by-default columns: serviceId, previousHash (unique), previousHashExpiresAt, rotatedAt, allowedIps and meta. Prisma selects every column of a model, so once the client is regenerated every API-key query fails until the database has them. Copy the model from @basaltkit/auth-prisma/schema.prisma (or schema.mysql.prisma on MySQL; basalt prisma:sync never adds fields to an existing model), run prisma generate, then prisma migrate dev --name add_api_key_lifecycle — with schema-per-tenant, in every tenant schema (basalt tenant:migrate). It requires @basaltkit/auth 5.

migrate dev warns that adding the unique constraint on previousHash may fail on duplicates; that is safe, because the column is new and every row holds NULL. It also refuses to run in a non-interactive shell (CI, a container, an agent). There, write the migration and deploy it:

bash
mkdir -p prisma/migrations/20261011000000_add_api_key_lifecycle
prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --script \
  > prisma/migrations/20261011000000_add_api_key_lifecycle/migration.sql
prisma migrate deploy

(API_KEY_LIFECYCLE_MIGRATION_SQL.postgresql / .mysql holds the same statements, if you prefer to paste them.) Until the columns exist, API-key requests fail with AUTH_API_KEY_SCHEMA_OUTDATED, whose message carries the SQL (also exported as API_KEY_LIFECYCLE_MIGRATION_SQL). @basaltkit/auth-sqlite migrates itself on boot. See Upgrading to auth-prisma 3.0.

Upgrading: boot warnings that now refuse ​

1.13 printed a [basalt] … boot warning for the first three of these configurations and kept their old behaviour, saying the next major would refuse them (the 1.13 list), and deprecated the fourth. This wave refuses the three and removes the fourth. If your app boots on 1.13 without any of these warnings and does not override allowed(), nothing here changes for you.

  • @basaltkit/auth 5.0 — a prefixed session cookie that breaks its rule. A sessionCookie.name starting with __Host- or __Secure- (any case) with an explicit secure: false, or a __Host- cookie with a path other than /, throws SessionCookieConfigError (AUTH_SESSION_COOKIE_INVALID) when authPlugin registers. The usual culprit is secure: process.env.NODE_ENV === 'production' next to a __Host- name. Switch the name instead:

    ts
    authPlugin({ sessionCookie: { name: isProd ? '__Host-sid' : 'sid' } })

    The implied Secure of a prefixed name with secure unset, its one-time warning outside production, and the SameSite=None warning are unchanged. See Session lifetime.

  • @basaltkit/tenancy 4.0 — an unknown meta.tenant. A value other than true, false, 'never' or absent ('none', 'optional', 'false', null) refuses the boot with HTTP_INVALID_ROUTE_META on every adapter, naming each route; it no longer falls back to the app-wide required. Use 'never' for a central-only route, false for one that works with or without a tenant. See Central-only routes.

  • @basaltkit/http 3.0 — an invalid meta.responseHeaders. A record with a non-string value, a control character, or a header the route may not set (set-cookie, content-type, content-length, transfer-encoding, hop-by-hop headers, x-request-id) refuses the boot with HTTP_INVALID_ROUTE_META on every adapter; 2.8 ignored the whole record. A bespoke runRoute() driver that skips assertRouteMetaValid() gets the new InvalidRouteHeadersError (500) on each request instead. Set cookies with reply.header() in the handler. See Per-route headers.

  • @basaltkit/notifications 2.0 — allowed() is gone; preference() decides. The Notifier no longer detects an allowed() override, and NotificationPreferences.allowed() itself is removed. Move the logic of an override into preference() — false blocks, true sends, undefined lets the stored preferences and the definition's defaults decide (unlike allowed(), defaults now apply to it). A preferences object that still defines allowed() makes new Notifier() throw LegacyAllowedOverrideError (NOTIFICATION_ALLOWED_OVERRIDE_REMOVED) instead of ignoring it in silence. A caller of prefs.allowed(…) can use (await prefs.preference(…)) ?? true. See Preferences.

Other changes to watch ​

  • auth:apikey_rejected and auth:apikey_refused gain the reason 'ip_not_allowed'; an exhaustive switch needs a new case.
  • ApiKeyInfo also omits previousHash, so no hash reaches a listing.
  • mcpPlugin runs the adapters' boot checks over every route it exposes as a tool (assertRoutesGuarded with the container): a route reachable only through MCP with an unknown meta.tenant, an invalid meta.responseHeaders or security meta no guard enforces now refuses the boot. The new mcpPlugin({ allowUnguardedMeta }) takes the same waiver as the adapters. (@basaltkit/mcp 6.0) See MCP.
  • An MCP client using a userless API key must send the same key on every request of a /mcp session (either carrier, x-api-key or Authorization: Bearer); another key, or none, gets 404 and must re-initialize. A rotated key keeps its id, so the session survives a rotation.
  • isTenantRequired() throws InvalidTenantMetaError (500) for an unknown meta.tenant instead of returning the app-wide default, and the tenancy enricher refuses such a request before resolving a tenant — for a custom driver that skipped the boot check. (@basaltkit/tenancy 4.0)
  • A route pipeline that carries enrichers but no container throws EnrichersWithoutContainerError (HTTP_ENRICHERS_UNRUNNABLE, 500) instead of skipping them in silence, like guards already did — so a custom driver cannot drop tenancy's enricher (and its refusal above) by forgetting the container. Every shipped adapter and mcpPlugin pass it. (@basaltkit/http 3.0)
  • Idempotency keys are scoped to the raw credential, and the responses of POST /apikeys and POST /apikeys/:id/rotate are stored for the idempotency window when the client sends Idempotency-Key; see API keys and idempotency.

Highlights ​

Every adapter runs the same request pipeline ​

  • Idempotency on every adapter. idempotencyPlugin moved from @basaltkit/fastify into the shared route pipeline in @basaltkit/http, so Express and Hono get it too (the Fastify import keeps working). Two new options: fingerprint: 'body' refuses a reused key carrying a different body with 422 IDEMPOTENCY_KEY_REUSED, and replayAfterGuards: true moves the check after the route guards, so a revoked caller gets 401/403 instead of the cached success. Both will become the default in a future major — see Idempotent mutations. (@basaltkit/http 2.8, fastify 2.6, express 2.1, hono 2.1)
  • Request disposers. An enricher may return a RequestDisposer, and ctx().onDispose() registers one from anywhere in the request: cleanup that runs exactly once, after the handler has settled and the response is complete — streams, errors and client aborts included, identically on the three adapters. See Writing your own guard or enricher. (@basaltkit/http 2.8 and every adapter)
  • Per-route headers. meta.responseHeaders sets static response headers (say X-Robots-Tag: noindex on a public share link) on every response the route produces, its guard, validation and handler errors included — see Per-route headers. (@basaltkit/http 2.8)
  • An enricher can refuse with a header. Enrichers receive the reply, so a refusal can carry WWW-Authenticate; an enricher that sends a reply ends the request. rawBody() and upload() schemas built by a nested copy of @basaltkit/http are recognised by the adapter's copy. (@basaltkit/http 2.8)

API keys and rate limits for machine clients ​

  • API keys behave like credentials, not hints. apiKeysPlugin({ rejectInvalid: true }) answers a key that does not verify with 401 AUTH_APIKEY_INVALID and WWW-Authenticate before any guard; touchEveryMs throttles lastUsedAt writes to one per key per minute; a rejection names the key's display prefix and the client IP, never the secret. (@basaltkit/auth 4.2)
  • Budgets per key, per route and per prefix. meta.rateLimit accepts key: 'apiKey' (one budget per verified key), an array of budgets charged in order, and bucket: '<name>' to share one counter across routes; securityPlugin({ rateLimit: { prefixes } }) charges a path prefix such as /v1 instead of the global bucket. An identified caller with no resolved IP (an MCP tool over stdio, Hono without getClientIp) gets its own bucket instead of the shared unknown one. See Path-prefix budgets. (@basaltkit/http 2.8)
  • OpenAPI documents keys, scopes and idempotency. A route with meta.scopes gets an apiKeyAuth requirement and an x-required-scopes extension, and with idempotencyPlugin registered the guarded methods document the Idempotency-Key header. Documents of apps that use none of these are byte-identical. (@basaltkit/http 2.8)
  • An unknown key cannot flood the audit trail. auth:apikey_rejected leaves the default capture; refusals of a key that did verify are recorded under the new auth:apikey_refused. (@basaltkit/audit 3.1, auth 4.2)

Tenants, domains and the database ​

  • Tenant clients leased per request. prismaPlugin now leases a tenant's pooled client for each HTTP request and each tenancy.run(), and gives it back when the response ends, through the request disposers. Before, a client counted as in use for idleMs (30 s) after every request, so on defaults the 11th distinct tenant within 30 s waited 10 s for a 503 while nothing was running. The pool the plugin builds now defaults idleMs to 1 s, a grace period rather than a request budget — see The per-tenant client pool. (@basaltkit/prisma 3.1, tenancy 3.2, http 2.8)
  • The webhook outbox works with endpoints per tenant. Under schema-per-tenant (or database-per-tenant) with the webhook store over tenantClient(), every relayed entry used to fail with DB_UNAVAILABLE and dead-letter. tenancyPlugin now publishes a 'tenancy:run' signal (TenantRunner), and webhooksPlugin uses it to run the endpoint lookup of an off-request dispatch() scoped by tenantId inside tenancy.run — the lookup only, never the delivery, so a slow endpoint cannot hold a pooled client. webhookOutboxPlugin({ tenantOnly: true }) skips events emitted without a tenant. On by default; see the upgrade note below and Webhooks → Schema-per-tenant. (@basaltkit/webhooks 4.1, tenancy 3.2)
  • Central-only routes. meta: { tenant: 'never' } refuses a resolved tenant with a plain 404 before any guard, so a platform route cannot run inside a tenant reached on its host. basalt ai doctor flags routes that pair tenant: false with a platform: permission. (@basaltkit/tenancy 3.2, ai 1.4)
  • Custom domains survive a tenant save. PrismaDomainStore and SqliteDomainStore are durable DomainStores; tenant saves diff the domain set instead of erasing it (and its verification proof), and a claimed but unverified domain never resolves a request. @basaltkit/tenancy/testing ships a contract suite for your own store. (@basaltkit/tenancy 3.2, tenancy-prisma 2.1, tenancy-sqlite 1.3)
  • Database failures that say what to do. describeDbError() turns a permission failure, a baseline needed, an unreachable host or a missing migration into a cause and a fix (the GRANT, the migrate resolve); basalt db:status reports every plane without changing anything; and assertMigrated({ forbiddenTables }) refuses a central database that a root migrate dev filled with tenant tables. (@basaltkit/prisma 3.1)
  • Generated modules for every isolation mode. --tenant=schema|database generates a repository over the tenant's own client with no tenantId column, still fail-closed. (@basaltkit/generator 1.6)

Sign-up, sessions and permissions ​

  • Registration policy per plane. authRoutes({ register: 'open' | 'closed' | policy }) controls POST /auth/register; a refusing policy answers the same 202 as a success, so the route cannot reveal who was invited. teamsInviteGate() makes tenant hosts invite-only, and teams.acceptByEmail() accepts an invitation once the address is proven. (@basaltkit/auth 4.2, teams 4.1)
  • Verified accounts from trusted flows. auth.register(…, { emailVerified: true }) creates the account verified, and a provider-verified social account is created verified before auth:registered fires. (@basaltkit/auth 4.2, auth-prisma / auth-sqlite 2.1)
  • Idle sessions expire. sessionIdleTtl refuses a session unused for longer, on top of the absolute sessionTtl, and a __Host-/__Secure- cookie now implies Secure in every environment. (@basaltkit/auth 4.2, auth-prisma / auth-sqlite 2.1)
  • A policy can answer for a list. definePolicy(resource, checks, { filters }) declares the list form of a check next to it, and gate.listFilter(user, 'resource:action') returns unrestricted, none or a where for list and count queries — fail closed with PERMISSION_FILTER_MISSING when no filter matches (RFC 0003; an ORM-level row filter was considered and rejected). See Policies decide one object, not a list. (@basaltkit/permissions 4.1)
  • Listings hide what the caller cannot pass. tools/list and other listing surfaces hide routes whose meta.scopes the caller's key lacks, and meta.mfa routes from a session without MFA. (@basaltkit/auth 4.2)
  • Mounted route sets take your guards. fileRoutes(), apiKeysUiRoutes(), billingUiRoutes(), teamsUiRoutes(), commentRoutes() and inAppRoutes() accept meta ({ teamRole: 'admin' }, { can: 'billing:manage' }, a rate limit); auth: true always stays on. (@basaltkit/files 6.1, api-keys-ui 1.4, billing-ui 1.2, teams-ui 1.2, comments 4.1, notifications 1.3)

Audit and personal data ​

  • Erase a person without breaking the chain. audit.redact(entryId, …) replaces chosen payload paths with '[erased]' and appends an audit:redacted attestation to the entry's own chain in the same transaction; verify() checks the redacted entry through it. Opt-in integrity: { mode: 'hash-chain', erasable: true } writes v3 hashes with a per-entry nonce that the redaction destroys, so the erased value cannot be confirmed from the hash (RFC 0005). See Erasing personal data. (@basaltkit/audit 3.1, audit-prisma / audit-sqlite 2.1)
  • Personal data policies per event. fieldPolicies omits or pseudonymises fields before the redactor and before hashing, and audit.record(…, scope) attributes an entry written from a script to its tenant's chain. (@basaltkit/audit 3.1)
  • One AEAD for secrets at rest. @basaltkit/core/secret-box is the AES-256-GCM key-ring box behind auth's SecretBox and drives' DriveSecretBox; existing ciphertexts stay byte-compatible. (@basaltkit/core 1.6)

Webhooks, mail and drives ​

  • Operable webhooks. secretBox seals endpoint signing secrets at rest, onAttempt and DeliveryResult.durationMs report every delivery attempt, headerPrefix renames the x-basalt-* headers, and signPayload() / verifySignature() accept raw bytes — see Webhooks. createGuardedFetch() is the streaming, SSRF-guarded client for untrusted URLs. (@basaltkit/webhooks 4.1)
  • Inbound mail. A new package receives email from a relay as signed raw bytes (one recipient per request, envelope inside the signature), routes it by the signed recipient to tenant-aware handlers, and parses it within limits, trusting Authentication-Results and ARC only from servers you list. It ships with a reference Cloudflare Email Routing Worker (RFC 0004) — see Inbound mail. (@basaltkit/inbound-mail 0.1)
  • Drives you can operate. Connection health and a drives.check() probe, a vetoable drive:disconnecting hook, a per-call recursive listing mode, provider explanations kept on the log-only channel, rotateSecrets() for dormant connections, and a conformance suite for durable stores; SharePoint columns through listItemFields. (@basaltkit/drives 0.4, drives-google / drives-dropbox / drives-microsoft 1.1)

Collaboration and data in and out ​

  • Comments with anchors, soft deletes and revisions, and mentions that no longer read an e-mail domain as a user. (@basaltkit/comments 4.1, comments-prisma 1.2, comments-sqlite 1.1)
  • Notifications that mark everything read, group repeats, prune old rows, and take per-channel defaults and mandatory channels, with durable preference stores. (@basaltkit/notifications 1.3, notifications-prisma 1.2, notifications-sqlite 1.1)
  • CSV both ways. parseDelimited() and defineImport() read CSV strictly and report every bad cell by line and column; CSV and XLSX exports render numbers and dates for a locale, with a BOM, real date cells and column formats. (@basaltkit/exports 1.3, exports-xlsx 1.1)
  • Realtime over sse(). realtimeSse(hub, …) runs a hub-backed SSE endpoint unchanged on Fastify, Express and Hono. (@basaltkit/realtime 1.6)

MCP that does not leak its errors ​

  • Malformed arguments are refused, internal errors are generic. A non-object arguments is INVALID_PARAMS before the tool runs, and an unexpected throw answers Internal error instead of the exception's message; the cause goes to onError (stderr by default). A tool call never forwards the idempotency key, so a replay cannot hand the model an unredacted error. (@basaltkit/mcp-core 0.5, mcp 5.1, ai-mcp 0.4)

From npm create to production ​

  • A tested production path. New apps get a build script, a start that runs the compiled output, and a multi-stage Dockerfile that runs as a non-root user with a health check; --prisma apps generate the client outside src/. create-basalt update offers the missing pieces to older apps and create-basalt doctor flags what is left. basalt publish dockerfile / ci emit the same files. (create-basalt 1.12, @basaltkit/cli 1.4)
  • A route security review. basalt routes prints a column per guard, --json for tooling, and --unguarded --require=auth,can exits 1 on a route that is missing either — see Route security review. describeRoutes() and findUnguardedRoutes() let a test assert the same thing. (@basaltkit/http 2.8, cli 1.4)
  • A scaffold checked against real PostgreSQL. A new CI job drives a scaffolded app's own db:* scripts against a real database, which found the db:seed script below. (create-basalt 1.12)
  • A patched sharp. @basaltkit/image-sharp 1.1.8 requires sharp 0.35.5 or later (a vulnerability in the bundled librsvg).

Upgrading ​

No package needs a major, but these minors change what some applications see. Packages are independent — bump only what you use; each package's CHANGELOG.md carries the full notes. Read this list before upgrading.

Idempotency ​

  • Raw Fastify handlers lose idempotency. idempotencyPlugin now covers Basalt route() definitions only. A handler registered directly on the Fastify instance (fastify.post(...), outside fastifyPlugin({ routes })) that relied on the old Fastify-only hook is no longer guarded. Move it to route(). No boot warning flags these, so check your raw POST handlers.
  • Only what the handler did is recorded. A refusal raised before the handler runs (a guard's 401/403, the rate limiter's 429, a validation 400) releases the Idempotency-Key instead of being replayed for the whole TTL, so a client that signs in again or honours Retry-After gets its operation run on the retry. So does an upload() body refused while the handler streams it (413 over a limit, 400 malformed, 415 a refused file type): retry with a smaller file under the same key and the handler runs. 408, 425 and 429 are never recorded, even from the handler. Any other handler 4xx is still replayed byte for byte. Identical on Fastify, Express and Hono.
  • The check runs after the enrichers (and before the guards, unless replayAfterGuards: true). A replay is decided after the tenant is resolved, so a suspended tenant gets its 403 instead of the cached response.
  • What the scope covers. The replay scope is the caller's credentials, the raw x-tenant-id/host headers, the method, the route pattern and the key. It does not include a tenant resolved from the path or a token claim, nor the concrete path params: the same credential reusing a key on /t/acme/... and /t/globex/..., or on /orders/1/pay and /orders/2/pay, receives the first response. Mint a fresh key per operation and tenant, and bind it to the URL with fingerprint: ({ request }) => request.url + '\n' + JSON.stringify(request.body). fingerprint: 'body' covers the body only, not the query string or params.
  • Rolling deploys with fingerprint. RedisIdempotencyStore writes in-flight reservations as pending:<fingerprint>, which older instances misread. Deploy the new release everywhere first, then turn fingerprint on. Empty responses (204) are now recorded and replayed.
  • An enricher that sends a reply ends the request. After reply.send() in an enricher, the remaining enrichers, the guards and the handler no longer run.

See Idempotent mutations.

Request disposers and Prisma leases ​

  • Leases need @basaltkit/http 2.8. prismaPlugin leases only when the pipeline releases the lease at the end of the response: @basaltkit/http 2.8 with an adapter from the same release, and @basaltkit/tenancy 3.2 for tenancy.run(). With older versions nothing leaks: the plugin holds the client for 30 s and then returns it, as pool.get() did. @basaltkit/http is now an optional peer of @basaltkit/prisma. Upgrade http, your adapter and tenancy together with prisma.
  • Registration order no longer matters for ctx().db. The lease is taken as soon as the tenant is known, so an enricher registered between tenancyPlugin and prismaPlugin (auth, say) sees ctx().db. Each request holds exactly one lease, released even when a later enricher or guard rejects the request.
  • Disposers wait for the handler. On a client abort mid-request, Fastify and Express used to run enricher disposers while the handler was still running, which could disconnect its leased client mid-query. Disposers now run exactly once, after the handler has settled and the response is complete: sent or abandoned on Fastify/Express; on Hono a buffered response is complete when it is built, so its disposers are awaited before it is handed to the runtime. stream() and sse() bodies stay covered until their last byte or until the client leaves. A disposer handed to ctx().onDispose() after that point (from a timer the handler left behind, say) runs at once, on every adapter. A failing disposer is reported as REQUEST_DISPOSER_FAILED on every path (the adapter's onError, @basaltkit/mcp's reportError, console.error for a bare runRoute). ctx().onDispose is absent inside tenancy.run(), in jobs and on older pipelines: check for it rather than calling ctx().onDispose?.(…), which silently drops the cleanup there.
  • ctx().db after the response is not protected. The lease ends with the response, and the client then stays reserved for only 1 s. Work that outlives the reply must await before replying, or run in tenancy.run() / DB_POOL.use(). If you used DB_POOL.get() on the plugin's pool for work longer than 1 s, switch to DB_POOL.use() or pass idleMs explicitly. A tenancy:switched emitted on a request's context after its response ended gets the legacy 30 s hand-out, never a lease that nothing returns.
  • Size max by the distinct tenants active within a few seconds. Over-subscribing no longer answers 503; it churns: an idle client is closed and a new one opened on each request. Monitor how often your forTenant factory runs.
  • PRISMA_POOL_EXHAUSTED bodies are neutral. The 503 carries only the code and "Service unavailable.". max, leased, recentlyUsed and the tenant id go to the server log only.

Configurations that now warn at boot (refused in the next major) ​

Each of these booted before and still does, with the same runtime behaviour as before; each now prints one [basalt] … boot warning naming what is wrong. The next major turns each warning into a boot refusal, so fix them now — each has a one-line fix.

  • @basaltkit/auth: a prefixed session cookie with secure: false or a sub-path. A sessionCookie.name starting with __Host- or __Secure- together with an explicit secure: false (including the common secure: process.env.NODE_ENV === 'production' in dev and test), or a __Host- cookie with a path other than /. The cookie is still emitted exactly as configured; browsers drop it, so such an app has no working browser sessions there. Drop secure/path, or use an unprefixed name outside production: name: isProd ? '__Host-sid' : 'sid'. The next major throws AUTH_SESSION_COOKIE_INVALID (SessionCookieConfigError, exported now). Prefixes match case-insensitively (__host-sid counts), and a __Host- cookie with a sub-path and secure unset also gets the implied-Secure warning outside production. Separately (warning only, never refused), an unprefixed cookie with sameSite: 'None' and no Secure warns: browsers drop it too.
  • @basaltkit/tenancy: meta.tenant other than true, false or 'never'. A value such as 'none', 'optional', 'false' or null falls back to the app-wide required default, as before. If you meant central-only, the value is 'never'. The next major refuses the boot with HTTP_INVALID_ROUTE_META.
  • @basaltkit/http: an invalid meta.responseHeaders. It must be a record of string values without control characters and must not set set-cookie, content-type, content-length, transfer-encoding, hop-by-hop headers or x-request-id. An invalid record is ignored whole — none of its headers is sent — and the request never fails because of it. The key is new: an app that keeps its own data under meta.headers is untouched, because nothing reads or sends meta.headers.

Configurations that now refuse to boot ​

Only one, and only for forms added in this release:

  • @basaltkit/http: malformed new-form meta.rateLimit. An array (including []) with a malformed entry, an object whose bucket is a string that is not a valid bucket name, or routes sharing a bucket that disagree on limit, window or key, refuse the boot with HTTP_INVALID_ROUTE_META. The single object without a string bucket — including bucket: null — keeps its lenient parse and is enforced per route, as before.

Other changes ​

  • Audit — API key refusals. auth:apikey_rejected is no longer recorded by default, because any anonymous client could flood the trail with unknown keys. Refusals of a key that did verify (tenant_mismatch, not_allowed, scope) are still recorded, under the new auth:apikey_refused hook. A custom hooks list applies the default excludes too. To record every rejection again, name it: hooks: ['auth:**', 'auth:apikey_rejected'] (a valid-key refusal is then recorded twice) — or use the throttled listener in Which hooks are audited.
  • Audit — erasable chains. Upgrade every service that runs audit.verify() before the first audit.redact() or before turning on integrity: { mode: 'hash-chain', erasable: true }: older releases report v3 entries and redacted entries as hash-mismatch. See Erasing personal data.
  • Auth — a prefixed session cookie now implies Secure in every environment. With secure unset, a __Host-…/__Secure-… cookie is now Secure (and Path=/ for __Host-) outside production too; before, it was emitted without Secure and browsers dropped it. Browser flows now work, http://localhost included. Test-client caveat: cookie jars that honour Secure (supertest/superagent, tough-cookie) do not send it back over plain http, so a suite that relied on the old emission gets 401s; outside production this prints a one-time boot warning. Use an unprefixed name outside production, or set secure explicitly (secure: true silences it).
  • Auth — sessionIdleTtl is validated. The new option fails closed at boot (AUTH_SESSION_IDLE_CONFIG_INVALID) when it is not a positive duration or the session store has no touch(); apps that do not set it are unaffected.
  • Auth — custom UserSource without update(). create() now receives emailVerified; persist it to get verified social and trusted accounts. A source that neither persists it nor implements update() still signs OAuth users in through identity linking, unverified as before. Two cases still fail on such a source: a SAML user (no linked identity) is refused on the second login, as before this release. register(…, { emailVerified: true }) (new in this release) requires update() and otherwise throws AUTH_UPDATE_UNSUPPORTED before writing anything — no account is created, so a retry never hits EmailTakenError. Implement update() (and persist emailVerified in create()) to get both.
  • Boot warning for meta.rateLimit without a rate limiter. When any route declares meta.rateLimit — authRoutes() does, and so may your own routes — and securityPlugin({ rateLimit }) is not registered, the app now prints one console.warn at boot naming those routes, because nothing enforces the limit. Register the limiter, pass authRoutes({ rateLimit: false }) for the auth routes, or silence it with allowUnguardedMeta: ['rateLimit'] (or true) on the adapter plugin if an outer edge throttles.
  • Webhooks — runInTenant is on by default. With tenancyPlugin registered, each off-request dispatch() scoped by a tenantId makes one TenantSource.find call and fires tenancy:switched/tenancy:exited; under schema- or database-per-tenant prismaPlugin also leases that tenant's client, which can fail with PRISMA_POOL_EXHAUSTED when the pool is saturated. A deleted tenant or an invalid id rejects with TENANT_NOT_FOUND / TENANT_ID_INVALID, and its outbox entries dead-letter after maxAttempts. If your webhook tables are central, pass webhooksPlugin({ runInTenant: false }) — see what it costs.
  • Drives — connection health is opt-in per store. lastSucceededAt, lastFailedAt and lastErrorCode are written only to a store that declares persistsHealth: true (the in-memory store does). A durable store keeps working unchanged and reports no health. To turn it on, add the three nullable columns, migrate, then set readonly persistsHealth = true — see Connection health.
  • Notifications — the Notifier decides through preference(). It decides each channel through NotificationPreferences.preference(), then the notification's defaults and mandatory. A subclass that overrides allowed() keeps working: the Notifier detects the override and lets it decide, as before (defaults do not apply to it; mandatory still bypasses it). Overriding allowed() is deprecated — override preference(); the next major stops consulting an allowed() override.
  • MCP — internal errors are logged. An error that escapes a tool still answers Internal error, and its cause now goes to stderr by default. Use mcpPlugin({ onError }) to send it elsewhere, or onError: false to silence it.
  • MCP — no idempotency key in tool calls. A tool call never forwards Idempotency-Key (or the header set by idempotencyPlugin({ header })) to the route, even when it is listed in forwardHeaders: a replay would hand the model the recorded error body without the tool result's redaction. Each tool call runs the handler; deduplicate inside the handler if you need to.
  • Tenancy — basalt prisma:sync does not add the new TenantDomain columns. The bundled model gains verificationToken, verified, createdAt and verifiedAt. prisma:sync only adds missing models, so an app that already has TenantDomain must add the four fields by hand (copy them from @basaltkit/tenancy-prisma/prisma/schema.prisma) and run a migration before deploying a client generated from the new model.
  • Route table — central-only. basalt routes shows meta.tenant: 'never' as central-only (meta.tenant: 'never' on the route and central-only in the table are the same thing). The new describeRoutes() reads RouteRow.tenant from meta.tenant only; meta.central: true (the teams membership bypass) is listed among the guards as central.
  • Apps scaffolded with --prisma by create-basalt 1.8–1.11 — change one script. Their db:seed is tsx prisma/seed.ts, which loads no .env, so pnpm db:seed fails with ENV_INVALID (database URL and app secret missing) unless you export the variables; and Prisma 7's migrate dev never runs the seed, so the demo tenant the resolvers expect was never created (the "creates the tables and seeds the demo tenant" next step was wrong). In package.json, set "db:seed": "prisma db seed" — prisma.config.ts then loads .env and runs the migrations.seed command it already declares — and run pnpm db:seed after pnpm db:migrate. Nothing rewrites the script for you: create-basalt doctor flags it and create-basalt update prints the line.
  • Not verified automatically. The scaffold's real-PostgreSQL e2e covers db:migrate --name <change>, but not db:migrate without --name on a schema change (Prisma prompts for the name and blocks even with stdin closed) nor migrate dev's reset prompts for a destructive change or a drifted database: both need a terminal.
  • No npm provenance attestations yet. The packages of this wave are published without provenance attestations; restoring them is tracked in issue #409.

Previously — Basalt 1.12 ​

The release that keeps its word: an independent audit's eighty findings closed, each real defect with a regression test; thirty-two majors that make the code do what its documentation said; one wire across Fastify, Express and Hono; and the audit's harvest closed a day later.

Thirty-two packages publish a major — six of them twice

auth 4, auth-prisma 2, auth-sqlite 2, auth-saml 3, permissions 4 (permissions-prisma / -sqlite 2), tenancy 3, tenancy-prisma 2, storage 5, files 6, comments 4, search 2, search-elasticsearch 2, audit 3 (audit-prisma / -sqlite 2), webhooks 4 (webhooks-prisma / -sqlite 2), subscriptions 5 (subscriptions-prisma / -sqlite 3), teams 4, queue 3, prisma 3, mcp 5, express 2 and hono 2 — and the three drive adapters reach 1.0. Some packages went through two majors in this wave: permissions, storage, files, audit, webhooks and mcp first shipped the audit's fixes (as 3, 4, 5, 2, 3 and 4) and then, a day later, the follow-ups in Closing the harvest. Coming from 1.11, you take both sets of steps. Three 0.x packages break in a minor: drives 0.3, mcp-core 0.4 and ai-mcp 0.3 (by way of 0.2). Most of these are one option or one renamed call; four need a data step (a re-key, a re-encryption, two new auth models, regenerated RLS policies). See Upgrading to 1.12.

Basalt 1.12 is the release that keeps its word. Every package makes promises — in its README, in its types, in the name of an option — and 1.11 had made sure the secure behaviour was the default. What nobody had checked systematically was whether the default did what the promise said. So an independent audit, in two passes, read each package's source next to its documentation and turned every mismatch it found into a failing test against the published build.

It found eighty. Ten were rated high, and none of them looked like a security bug from the outside — each was a sentence the framework said about itself. The README promised audit.verify() would detect a forged row, and a row inserted straight into the table passed. idempotencyPlugin was documented for route() handlers, and a handler that returned its payload — the shape every example uses — ran again on every retry. A policy for project:constructor resolved through Object.prototype and authorized anyone. meta.teamRole: 'Admin', a typo for 'admin', ranked zero and admitted every member. swap() moved a free subscription onto a paid plan without charging it. @basaltkit/env said an unset NODE_ENV was production and @basaltkit/auth said it was development.

All eighty are closed. Each real defect was reproduced with a failing test before it was fixed, and that test now lives in the package's own suite; a hypothesis that did not reproduce is documented, not "fixed". The theme is the gap between declared and actual behaviour, and it runs through every item below: a single-tenant key that could not be a tenant's name, a resolver that could not be overruled by a header, three adapters that send the same bytes for the same route, an MCP endpoint that knows which session it is talking to.

The report also ended with a harvest: design gaps and improvements beyond its eighty numbered findings. Two more pull requests closed that list after the release and ship inside the same wave — policies that run in the route guard, error details that are public by construction, audit hashes that name their key, webhooks that respect a port policy and a fan-out cap, and more. See Closing the harvest.

Promises the code now keeps ​

  • The audit trail detects what the README said it detects. verify() now also reads a tenant's rows outside its chain: a row written after the chain began without a place in it fails with unchained-entry and is listed in unverified; verify({ expectedHead }) anchors the head so a deleted tail is truncated, not silent. Payloads are deep-frozen, the redactor matches secret keys on their words (privateKey, client_secret, dsn…) and pseudonymises international phone numbers as documented, and store filters are validated — ?tenantId[not]=x can no longer reach a Prisma where. (@basaltkit/audit 2.0, audit-prisma / audit-sqlite 2.0)
  • idempotencyPlugin replays handlers that return a value. Only handlers that called reply.send() themselves were covered; every other route ran on every retry of the same Idempotency-Key and reported a spurious 500. (@basaltkit/fastify 2.5)
  • A permission check answers only the question it was asked. Policy lookups no longer walk the prototype, a check authorizes only when it returns exactly true, only an exact resource:action selects a policy check, a missing user id is a 401 rather than a shared bucket, and a permission with an empty segment ('projects:') matches nothing. With tenancy active, a write with no tenant and no scope throws PERMISSION_SCOPE_REQUIRED instead of quietly granting platform-wide. (@basaltkit/permissions 3.0)
  • A typo'd role fails the boot. An unknown meta.teamRole used to rank zero and admit everyone; now it makes every adapter refuse to start with InvalidRouteMetaError, naming the route. An unranked role is matched exactly, and "one pending invitation per e-mail" is case-insensitive. (@basaltkit/teams 4.0)
  • One NODE_ENV rule everywhere. isProductionEnvironment() is the single fail-closed policy: only an explicit development or test is not production. auth applies its 32-character secret floor and Secure cookies under it, mailer stops logging mail bodies, and queue warns about an implicit sync driver. (@basaltkit/core 1.5, auth 4.0, mailer 2.1, queue 3.0)
  • The single-tenant key cannot be a tenant. SINGLE_TENANT_SCOPE was 'default' — a valid tenant id, so a request naming the tenant default reached a single-tenant app's records. It is '@single' in files, comments, search and drives, and a tenant equal to it is refused. (@basaltkit/files 5.0, comments 4.0, search 2.0, drives 0.3)
  • Storage keys name one object on every driver. A tenant segment must be canonical (Acme and acme shared a directory on a case-insensitive disk), every scoped disk fails closed without a tenant (a hand-built new Disk() used to fall back to the bucket root), keys with . or empty segments are refused, and a copy from a tenant disk cannot land in another tenant's tree. (@basaltkit/storage 4.0)
  • Webhook deliveries keep their identity. Outbox deliveries carry a stable id across retries, permanent failures stop being re-dispatched to healthy endpoints (onPermanentFailure), each retry is signed with its own timestamp, and register() validates the endpoint — URL, scheme, a secret of at least 16 characters, events — instead of storing one that fails on every delivery. (@basaltkit/webhooks 3.0)

Who is asking, and on whose behalf ​

  • The Host decides the tenant, not a header. subdomainResolver, domainResolver and routeResolver are authoritative: they run before any fallback, and a name that does not exist resolves to no tenant instead of deferring to x-tenant-id. The tenant-id grammar applies to resolution and run(), normalizeDomain() validates instead of URL-parsing (acme.basalt.app@evil.com became evil.com), unverified domain claims expire, and CustomDomains.reverify() lets a lapsed domain change hands. (@basaltkit/tenancy 3.0)
  • A social login is bound to the provider's subject. Account links (provider + subject → user) replace matching by e-mail alone; a second account at the same IdP claiming a linked e-mail gets 409 AUTH_ACCOUNT_LINK_CONFLICT. OIDC providers can be restricted to their e-mail domains — required once more than one provider is configured — and id_token aud, exp and iss are checked. (@basaltkit/auth 4.0)
  • Passkeys and TOTP secrets hold under concurrency and tampering. The WebAuthn counter is written by compare-and-set, so a cloned authenticator racing the genuine one loses; remove() checks the owner; the challenge is bound to the user. TOTP secrets are sealed with AES-256-GCM under an HKDF key ring with the user id as associated data, and a value that is not an envelope is refused rather than read as plaintext. (@basaltkit/auth 4.0, auth-prisma / auth-sqlite 2.0)
  • SAML responses belong to the browser that asked, signed with SHA-2.samlRoutes() bind each login to an HttpOnly cookie (login CSRF), node-saml errors are a 400, and SHA-1 signatures and digests are refused by default. (@basaltkit/auth-saml 3.0)
  • A job runs as its dispatcher, and nothing else. The worker rebuilds the context from an allowlist — request ids, a validated tenant, userId restored as user: { id } so audit entries name an actor — instead of spreading whatever the broker held. Envelopes can be HMAC-signed (signingKey), and a second definition under a taken job name throws. The Redis realtime backplane can be signed too, and subscribe() re-checks the connection after its async gate. (@basaltkit/queue 3.0, queue-bullmq 1.1, queue-rabbitmq 1.4, queue-sqs 1.3, realtime 1.5)

Money, indexes and rows ​

  • Billing charges before it grants. swap() onto a paid plan from a subscription with no gateway behind it throws 402 BILLING_PAYMENT_REQUIRED; usage amounts must be positive integers in every store; a webhook for a replaced gateway subscription no longer cancels the active one; Lemon Squeezy renewals are no longer dropped as duplicates; Paddle and Lemon Squeezy signatures are read from their own headers, and both go through checkout(). Coupons, invoices and the payment ledger validate their inputs. (@basaltkit/subscriptions 5.0, subscriptions-prisma / -sqlite 3.0)
  • A rebuild clears only what it can refill. reindex() never files a tenant-less row under the calling tenant, validates every row before it clears anything, and inside a tenant rebuilds only that tenant — a whole-index rebuild says { all: true }. Paging and filters are bounded and validated. Elasticsearch documents with URL-special characters in their id are addressed by one _id again. (@basaltkit/search 2.0, search-elasticsearch 2.0, search-postgres 1.2)
  • The tenant pool never disconnects a client in use. TenantClientPool evicts only idle clients and, when every client is busy, waits and then answers 503 PRISMA_POOL_EXHAUSTED — the cap is never exceeded. RLS policies compare against NULLIF(current_setting(…), ''), a switched tenant without a client fails closed, and class DTOs are scoped like plain objects. (@basaltkit/prisma 3.0)
  • MySQL stops truncating silently. Every *-prisma package ships a schema.mysql.prisma with the free-text columns widened, basalt prisma:sync copies it for a MySQL datasource, and an opt-in columnLimits: 'mysql' refuses an over-long value with COLUMN_LENGTH_EXCEEDED instead of writing a cut hash. Tenancy saves are atomic, and webhook endpoints are keyed by tenant. (@basaltkit/prisma 3.0, tenancy-prisma 2.0, webhooks-prisma 2.0, and the other *-prisma stores)

Three adapters, one wire ​

  • The same route sends the same bytes on Fastify, Express and Hono. A string is text/plain on all three (Express served it as text/html — a reflected XSS on that adapter only); JSON is application/json or +json by exact media type; a malformed body is a 400; a repeated query key is an array; the body limit is 1 MiB; sse() keeps the CORS and security headers set before it; after-hooks run for abandoned responses. A shared parity suite holds it. (@basaltkit/http 2.6, fastify 2.5, express 2.0, hono 2.0)
  • Route meta is validated at boot. Plugins register validators for the values their meta keys carry (http:meta-validators), and side-effect-free visibility checks (http:route-visibility) let a listing hide what a caller could never pass. expose = false keeps an upstream reply out of a 502. (@basaltkit/http 2.6)

MCP over a network ​

  • /mcp knows its caller and its session. A foreign Origin gets 403, a body that is not JSON gets 415, a tool call receives an allowlist of headers instead of all of them, and a 4xx from the handler is an isError result. initialize issues an Mcp-Session-Id bound to the caller, so a cancellation in a later POST reaches the call it names and no other; tools/list hides what the caller could not use. (@basaltkit/mcp 4.0)
  • The MCP core refuses to be reachable by accident. serveHttp will not bind off loopback without authorize, caps request bodies, never answers a notification, supports JSON-RPC batches and real stdio elicitation — so basalt_make in ai-mcp refuses an apply it cannot confirm instead of writing silently. (@basaltkit/mcp-core 0.4, ai-mcp 0.2)
  • External drives stay inside their root. Listing cursors are signed to their tenant and connection (a Graph cursor is a URL fetched with the connection's token), a rootId confines every call, and the three adapters reach 1.0. (@basaltkit/drives 0.3, drives-dropbox / drives-google / drives-microsoft 1.0)

Closing the harvest ​

The audit's report did not stop at its eighty findings: it closed with a harvest of design gaps and improvements. Two pull requests landed after the release and finished that list, so they ship inside 1.12 — and six packages publish their second major of the wave.

  • Policies run in the route guard. A plain meta.can was RBAC only: the guard never passed a resource, so a policy registered with definePolicy never decided a route. meta.can now also takes { permission, resource, notFound? }, alone or in an all-of array: the guard loads the resource with the route's parsed input, calls gate.authorize(user, permission, resource), answers 404 RESOURCE_NOT_FOUND for a missing one (or an audited 403 with notFound: 'deny'), and the handler reads it back with canResource(). A requirement no registered policy decides refuses the boot. (@basaltkit/permissions 4.0)
  • hasRole() answers membership, and /me/access shows every door that opens. A super admin no longer "holds" every role name ever typed — the bypass is authority, not membership, and gate.isSuperAdmin() asks for it explicitly. GET /me/access now comes from gate.describeAccess(): global grants, temporary grants, delegations and the super-admin bypass, each with its source. Temporary grants and delegations get durable stores, so they survive a restart and are seen by every instance. (@basaltkit/permissions 4.0, permissions-prisma / -sqlite 2.1)
  • Error details are public by construction. new HttpError(…, { internalDetails }) is a log-only channel the error reporter receives and no response or tool result ever carries. @basaltkit/mcp passes a thrown error's details through redactSensitiveDetails before they reach the model, and tool-call errors, which used to vanish, are reported. (@basaltkit/http 2.7, mcp 5.0)
  • Audit hashes name their algorithm and their key. New entries are v2:sha256:… or v2:hmac-sha256:<keyId>:…, so the HMAC key can be rotated (keyId, verifyKeys) without failing every entry the old key signed; v1 entries keep verifying. verify() also catches a duplicate seq at a page boundary. (@basaltkit/audit 3.0, audit-prisma / -sqlite 2.0.1)
  • Webhooks respect a port policy and a fan-out cap. Deliveries go to 80, 443 or an unprivileged port outside DEFAULT_BLOCKED_PORTS — no longer to an exposed Redis or Postgres. DNS resolution runs inside the per-attempt deadline, a dispatch to more than 100 endpoints per event and scope is refused, at most 16 deliveries run at once, and rotateSecret() signs with both secrets for a grace window. (@basaltkit/webhooks 4.0, webhooks-prisma / -sqlite 2.1)
  • Storage hands back the keys it takes, and holds lengths to their word.list() on a tenant disk returns a/1.txt, not tenants/<id>/a/1.txt, which get() then prefixed a second time; the prefix is a directory on every driver. A contentLength is validated and counted, and a body that contradicts it is never committed. S3 streams an unknown-length upload by multipart instead of buffering it. (@basaltkit/storage 5.0, storage-s3 1.4)
  • File routes answer a public projection. GET /files and friends returned the raw record — storage path, checksum, uploadedBy, the scanner's output. They now send toPublicFile(record), and fileRoutes({ present }) chooses another shape. (@basaltkit/files 6.0)
  • A suspended tenant is a 403, and an unknown status fails closed. Every status other than ready used to be a 503 "still being provisioned" — including suspended, so clients retried a locked-out account. (@basaltkit/tenancy 3.1)
  • The MFA step is no longer a password oracle. AUTH_MFA_REQUIRED is only returned for a correct password, so it now counts against the login throttles like a wrong one. (@basaltkit/auth 4.1)
  • The AI bridge enforces "dev-only". ai-mcp refuses to start under NODE_ENV=production without an explicit override, and a tool's workspaceRoot must resolve inside the project root. (@basaltkit/ai-mcp 0.3)

Docs ​

Upgrading to 1.12 ​

Packages are independent — bump only what you use. Each changeset carries its full migration notes in the package's CHANGELOG.md; below are the changes most likely to reach an application.

Defaults that now refuse ​

PackageWhat refusesOpt-out / fix
auth 4an unset NODE_ENV with a secret under 32 characters (AUTH_WEAK_SECRET); session cookies are Secure; several OAuth providers where an OIDC one declares no e-mail domains; a second IdP account claiming a linked e-mail (409); two different API keys on one request (400)NODE_ENV=development locally, sessionCookie: { secure: false }; allowedEmailDomains or allowAnyEmailDomain: true; oauthPlugin({ subjectConflict: 'link' }); send one key
mailer 2.1mail bodies in the log with NODE_ENV unsetNODE_ENV=development or logBody: true
tenancy 3a header overriding a Host resolver; an unknown subdomain falling through to the header; ids outside the grammar in resolution and run(); non-hostnames in normalizeDomain()authoritative(fn) for a trusted custom resolver; widen validateTenantId; IDNs in xn-- form
permissions 3scope-less writes outside a tenant when tenancy is active; permissions with an empty segment; three-segment permissions against a policy; grantTemporarily() without a deadlinepass GLOBAL_SCOPE explicitly or allowGlobalWrites: true; ttlMs / expiresAt
storage 4a hand-built Disk or custom scope with no tenant; non-canonical tenant ids in the default scope; keys like a//b, ./a, a trailing /; a scoped → central copy into tenants/scope: null or onMissingScope: 'root'; a custom scope that maps ids; build keys with parts.join('/')
files 5HTML, SVG, XML or executables uploaded as application/octet-streamdeclare the type and let allowedTypes judge it
webhooks 3register() with a bad URL, a secret under 16 characters or no events (WEBHOOK_ENDPOINT_INVALID); an id held by another tenant (409)validate input first; hook onPermanentFailure to alert on failures the outbox no longer retries
mcp 4a foreign Origin (403); a non-JSON body (415); a later POST without its Mcp-Session-Id (400 / 404)mcpRoutes({ allowedOrigins }); mcpRoutes({ sessions: false }); add Mcp-Session-Id to CORS exposeHeaders for browser clients
mcp-core 0.4 / ai-mcp 0.2serveHttp off loopback without authorize; bodies over 1 MiB; an apply that cannot be confirmedauthorize / allowRequest, maxBodyBytes; --token; --allow-unconfirmed-apply
auth-saml 3SHA-1 signatures and digests; a response not bound to the browser that started the login; a configured emailAttribute that is missingallowSha1: true per provider; bindToBrowser: false; fix the attribute name
teams 4an unknown meta.teamRole or tenantMembershipPlugin({ role }) — the app does not bootfix the role, or rank it in roleRank
queue 3two different jobs under one name; attempts: 0; job context with a tenant outside the grammarrename, or queuedOn(…, { name }); attempts ≥ 1; pass the same validateTenantId to the queue plugin
subscriptions 5swap() onto a paid plan with no gateway subscription (402); subscribe() to a paid plan on Paddle or Lemon Squeezy (501); non-positive-integer usageswap(id, plan, { allowUnpaid: true }); checkout()
search 2a bare reindex() outside a tenant when tenancy is registered; limit over 1000, offset over 10000; filters on undeclared fields or with null valuesreindex(name, { all: true }); searchPlugin({ maxLimit, maxOffset }); declare the field filterable
prisma 3a new tenant while every pooled client is in use — 503 after acquireTimeoutMssize max for concurrently active tenants; on prisma 3.0 keep idleMs above the longest request, or pool.use(tenantId, fn) — from 3.1 requests hold a lease instead (see the 1.13 upgrade notes)
audit 2verify() / verifyAll() fail for rows outside the chain written after it beganlegacyUntil for a known, benign source such as a rolling deploy

Data steps ​

The '@single' sentinel. A single-tenant app with persisted records re-keys them once, or they read as missing. Skip it if default was ever a real tenant in that database — those rows belong to it.

sql
UPDATE files         SET "tenantId" = '@single' WHERE "tenantId" = 'default';
UPDATE file_versions SET "tenantId" = '@single' WHERE "tenantId" = 'default'; -- with files-versions
UPDATE comments      SET "tenantId" = '@single' WHERE "tenantId" = 'default'; -- comments-prisma
UPDATE comments      SET tenant_id  = '@single' WHERE tenant_id  = 'default'; -- comments-sqlite

The search index is derived data: rebuild it (search.reindex(name)), or with search-postgres re-key in place. Drive connections cannot be re-keyed with SQL — each secret is sealed with its tenant as associated data — so re-seal them with DriveSecretBox as the @basaltkit/drives changelog shows, then move the import ledger.

MFA secrets. Keys must be at least 32 bytes, and rows sealed before 1.12 are refused. Upgrade with a temporary opt-in, re-encrypt, then remove it:

ts
authPlugin({
  mfaEncryption: {
    keys: [{ id: '2026-09', key: NEW_KEY_32_BYTES }],
    legacy: { v1Keys: [OLD_MFA_ENCRYPTION_KEY], plaintext: true },
  },
})
for (const userId of usersWithMfa) await auth.reencryptMfaSecret(userId)
// then drop `legacy`

Two new auth models. @basaltkit/auth-prisma adds AuthAccountLink and AuthPasskey — basalt prisma:sync, then a migration (in every tenant schema with schema-per-tenant; MySQL apps take them from schema.mysql.prisma). Then run normalizeAuthUserEmails(prisma, { dryRun: true }), again without dryRun, and merge any reported conflicts — until then those e-mails throw AUTH_EMAIL_AMBIGUOUS. @basaltkit/auth-sqlite creates the tables in migrate(). Configure a durable accountLinks store: existing users are linked on their next login by verified e-mail.

RLS policies. rlsPolicySql and rlsSearchFunctionSql now compare against NULLIF(current_setting(…, true), ''). Re-run the generated SQL — both are idempotent — in a new migration.

Smaller ones. Paddle and Lemon Squeezy subscriptions created through subscribe() carry a checkout id as gatewayRef: clear it or set the real sub_… id. Elasticsearch documents indexed one at a time with URL-special characters in their tenant or id need one reindex(name, { all: true }). Stored grants with an empty permission segment never granted anything and can be deleted.

Express and Hono change what a client receives ​

On Express: return HTML with an explicit content-type; send JSON with a JSON media type; an empty JSON body is now undefined, so default it in the schema (z.object({…}).default({})); routing is case-sensitive and strict and the query parser is simple — pass your own app if you relied on the old behaviour. On Hono: read a repeated query key as string | string[]; request.url is the path and query string, so build an absolute URL with new URL(request.url, base); a malformed JSON body is a 400 before the handler; pass errorHandler: false if you install your own onError.

Custom stores, drivers and gateways implement more ​

A custom PasskeyStore must implement compareAndSetCounter (the service refuses to start without it). A custom BillingGateway implements resumeSubscription or resume() throws, and CouponStore.incrementRedemptions takes a limit and may return null. Optional, but worth it: SearchDriver.clearTenant (tenant-scoped rebuilds), AuditStore.auditTenants, DomainStore.replace / listVerified, and replayKey from a custom drive adapter. Hand-written Prisma clients and test fakes need $transaction (tenancy-prisma) and create / updateMany (webhooks-prisma, auth-prisma); a generated PrismaClient already has them.

MySQL column limits are opt-in ​

Nothing changes on PostgreSQL or SQLite, or on MySQL until you ask. To adopt it, let basalt prisma:sync copy the schema.mysql.prisma variants, migrate, and pass columnLimits: 'mysql' to the store factories. The MySQL guide has the details.

What the harvest changes ​

These are the steps for the versions in Closing the harvest. Coming from 1.11, apply them on top of everything above: the rows for permissions 3, storage 4, files 5, audit 2, webhooks 3 and mcp 4 still hold for the next major. None of these needs a data migration unless you opt into a new store or column.

permissions 4 — hasRole() is membership. gate.hasRole(user, role) no longer returns true for every role to a super admin; can(), authorize() and meta.can still honour the bypass. Where hasRole() was an authorization check, check the permission instead, or ask for the bypass explicitly:

ts
if ((await gate.isSuperAdmin(user)) || (await gate.hasRole(user, 'billing-manager'))) { … }

GET /me/access keeps roles and permissions — clients now see more, correct, entries: global roles and grants, live temporary grants and delegations, '*' for a super admin — and adds superAdmin and grants (each permission with its source). The durable temporary-grant and delegation stores are opt-in: with permissions-prisma, wiring them means adding PermTemporaryGrant and PermDelegation (basalt prisma:sync) and migrating; permissions-sqlite creates the tables in migrate().

audit 3 — v2 hashes. New entries use the v2 format; existing v1 entries keep verifying and new entries chain onto them, so there is nothing to migrate. But:

  • Do not roll back to an earlier @basaltkit/audit after writing v2 entries — it cannot verify them.
  • Code that assumed a 64-hex hash (a column, a regex, --expected-head) must allow up to 144 characters; the bundled stores and the MySQL preset fit it.
  • Tooling that recomputes hashes: computeAuditHash() still computes v1 — use computeAuditHashV2() or checkAuditHash(entry, keysById).
  • An exhaustive switch over AuditVerifyFailure needs an 'unknown-key' case.
  • To rotate the key: integrity: { mode: 'hash-chain', key: NEW, keyId: '2026-09', verifyKeys: [OLD] }.

webhooks 4 — ports, fan-out and concurrency. An endpoint on a blocked port is refused at register() and at delivery: allow it with ssrf: { allowedPorts: […] } (or 'any'). A dispatch to more than 100 matching endpoints in one scope is refused — raise maxEndpointsPerDispatch. At most 16 deliveries run at once (dispatchConcurrency). To use rotateSecret(), Prisma users add previousSecret / previousSecretExpiresAt (basalt prisma:sync) and migrate first; webhooks-sqlite adds the columns in migrate(); a custom store must persist both fields and clear them when add() receives them as undefined. @basaltkit/drives gets the same port policy on every hop.

storage 5 — relative keys and exact lengths. Disk.list() returns keys relative to the disk's scope: drop code that stripped tenants/<id>/ by hand, and list a real directory instead of relying on a partial-name prefix match on a cloud driver. A contentLength that is not a non-negative safe integer is a 400 STORAGE_CONTENT_LENGTH_INVALID; a body that does not match it is a 400 STORAGE_CONTENT_LENGTH_MISMATCH and stores nothing. Custom drivers need no change.

files 6 — the routes' shape. GET /files, GET /files/:id and POST /files send toPublicFile(record): no path, checksum, tenantId, uploadedBy or scan detail. A client that read one of them needs a present:

ts
fileRoutes({ present: (file) => ({ ...toPublicFile(file), uploadedBy: file.uploadedBy }) })

files.get() / list() and the file:* hooks still return the full record. upload({ contentLength }) is now verified (413 FILE_TOO_LARGE up front, 400 on a mismatch) — never pass a multipart request's own Content-Length.

mcp 5 — redacted details, reported errors. A value under a secret-named key in a thrown error's details reaches the model as '[REDACTED]': move operator-only data to internalDetails, or pass redactErrorDetails: false (or your own redactor). Tool-call errors now reach reportError — the console by default; reportError: false restores the silence.

tenancy 3.1 — status codes. A suspended tenant answers a non-retryable 403 TENANT_SUSPENDED instead of 503; a status tenancy does not know (such as active) is 500 TENANT_STATUS_UNKNOWN. Store ready, or no status, for a serving tenant.

auth 4.1 — MFA and the throttle. A code-less first step on an MFA account now spends a login-throttle slot, like a wrong password; size ipLoginThrottle for large shared-NAT populations.

ai-mcp 0.3 — dev-only, enforced. It refuses NODE_ENV=production (--allow-production, allowProduction: true or BASALT_AI_MCP_ALLOW_PRODUCTION=1 to override), and basalt_analyze, basalt_doctor and basalt_plan refuse a workspaceRoot outside the project root.


Previously — Basalt 1.11 ​

The release that fails closed: composition bugs from a second security audit, fourteen majors that make secure behaviour the default, streaming on every adapter, a verifiable audit trail, and two new packages — backup and drives.

Fourteen packages publish a major

This wave changes secure defaults. auth 3, auth-saml 2, env 3, permissions 2, prisma 2, tenancy 2, storage 3, files 4, comments 3, audit-viewer 3, webhooks 2, subscriptions 4, teams 3 and mcp 3 each break something that used to work because it used to work without being asked. The rule for every one of them: a working app breaks without a code, config or data change. See Upgrading to 1.11 — most edits are one option, two need a data migration.

Basalt 1.11 is the release that fails closed. Two things happened in the same month. A second deep security audit — fourteen auditors, eighty-seven distinct findings, one critical — went through the framework looking not for bugs in packages but for bugs between them: an API key that was valid in every tenant because keys and tenancy had never been introduced; a Prisma operation the tenant extension did not know about and therefore did not scope; a webhook endpoint signed with the plugin-wide secret because nobody had said which tenant it belonged to. And two applications kept building on the framework — a document-management SaaS and a logistics SaaS — and kept a list of every place the framework made them write what it should have written: streaming, structured errors, a verifiable audit trail, roles for every tenant, a way to find stuck work under row-level security.

Seventy-seven of the findings are fixed with regression tests, and twenty-eight items from the applications' list are closed. The theme they share is the default. Where 1.10 supplied a missing half, 1.11 changes what happens when a half is missing: a disk with no tenant refuses instead of writing to the bucket root; a raw query inside a tenant refuses instead of seeing everything; an unset NODE_ENV counts as production instead of development. Nothing in this list is a new capability. Every one of them is a capability that used to be opt-in becoming the thing you have to opt out of.

Composition bugs the audit found ​

  • API keys are bound to their tenant. A key issued inside a tenant is refused on any request that resolves a different tenant, or none (403 AUTH_APIKEY_TENANT_MISMATCH); a key issued without a tenant is refused on tenant requests unless allowTenantlessKeys. This was the one critical finding: keys and tenancy each worked, and together a key was valid everywhere. Scopes are now an upper bound too — a key without * cannot act as its owner on routes that declare no meta.scopes, and meta.apiKey: false makes a route session-only. (@basaltkit/auth 3.0)
  • The Prisma tenant extension refuses what it cannot scope. Client-level raw operations, MongoDB raw reads and updateManyAndReturn inside a tenant are refused (PRISMA_RAW_IN_TENANT, PRISMA_UNSCOPED_OPERATION); nested relation writes are narrowed to the tenant and update data that changes the tenant field throws PRISMA_CROSS_TENANT_WRITE. tenantSchema() is injective, so two ids can no longer share a schema. (@basaltkit/prisma 2.0)
  • Storage, cache and realtime fail closed without a tenant. A disk on the default scope with tenancy active refuses a tenant-less write (STORAGE_TENANT_REQUIRED) instead of falling back to the bucket root; central disks say scope: null. Temporary URLs are capped at seven days. A tenant id with : in it cannot address another tenant's cache keys or channels, because the id is now validated (/^[a-z0-9][a-z0-9_-]{0,62}$/, global reserved) before anything is written. (@basaltkit/tenancy 2.0, storage 3.0, cache 2.0.1, realtime 1.4.1)
  • The global permission scope cannot be a tenant. GLOBAL_SCOPE is '@global', a value no tenant id can take; the Gate refuses to evaluate a tenant whose id is a reserved scope. Rows written under the old 'global' need a one-line migration. (@basaltkit/permissions 2.0)
  • Tenant webhooks get their own secret. A tenant endpoint is never signed with the plugin-wide secret and deliveries are never sent unsigned by default; a dispatch with no tenant reaches only tenant-agnostic endpoints. The SSRF guard classifies IPv6 by its parsed bytes, so mapped and translated private addresses are refused too. (@basaltkit/webhooks 2.0)
  • Object-level authorization on files, comments and the audit viewer.fileRoutes() is owner-only unless told otherwise; auditViewerRoutes() refuses to boot without a guard; an explicit tenantId argument inside a tenant context must match it. (@basaltkit/files 4.0, comments 3.0, audit-viewer 3.0, search 1.6)
  • Invitations, billing, SSO and MCP close their own doors. Accepting a team invitation needs a verified e-mail and one token enrols one account; a billing driver with an empty webhook secret throws instead of accepting an empty HMAC, and checkout redirects are restricted to known origins; each SAML provider is restricted to the e-mail domains it may assert; a spawned MCP server inherits an allow-list of environment variables, not APP_SECRET. (@basaltkit/teams 3.0, subscriptions 4.0, auth-saml 2.0, mcp 3.0)
  • An unset NODE_ENV is production. secret() applies devDefault only when NODE_ENV is explicitly development or test, so a deploy that forgets the variable can no longer boot on the public dev secret. New apps also get teamsPlugin() + tenantMembershipPlugin() by default, and make:resource generates authenticated, tenant-owned code with a test that proves it. (@basaltkit/env 3.0, create-basalt 1.5, generator 1.4)

What two applications made the framework write ​

  • Streaming, in both directions, on every adapter. disk.putStream / getStream / copy / stat on S3, Azure and GCS, with maxBytes enforced while the bytes arrive; S3 multipart for streams of unknown length as an optional capability; route({ body: upload({ maxBytes, maxFiles, allowedTypes }) }) for multipart on Fastify, Express and Hono alike; and a handler that returns stream(source, { contentType, filename }) — backpressure is real, a client that disconnects destroys the source, and GET /files/:id/content uses it. (@basaltkit/storage 3.2, storage-s3 1.3, http 2.2 & 2.4, files 4.1–4.3)
  • rawBody() — the octets that were actually sent. Every webhook provider signs the bytes it sent, and every adapter parsed JSON before a handler could see them; JSON.stringify of the parsed object is not those bytes. Apps verifying Stripe, Paddle or Lemon Squeezy signatures may have been failing every genuine delivery. A rawBody() route leaves the body unread until after guards ran, and refuses (RAW_BODY_UNAVAILABLE) rather than reconstructs. (@basaltkit/http 2.5, fastify 2.4, express 1.9, hono 1.9, subscriptions 4.0.1)
  • Errors carry data. new HttpError(status, code, message, { details }) and BasaltError expose error.details, bounded and sanitised by the serializer, so a UI stops parsing "Checks failed: A, B" out of a message. BasaltClientError.errorDetails reads it back. (@basaltkit/core 1.4, http 2.3, sdk 2.1)
  • A verifiable audit trail. integrity: 'hash-chain' gives every entry a sequence and a hash over its predecessor; audit.verify() detects edited, deleted, reordered and forged rows; requestContext: true records IP and user-agent through the redactor. (@basaltkit/audit 1.6, audit-prisma / audit-sqlite 1.2)
  • MFA by policy, throttles across replicas. authPlugin({ requireMfa }) refuses credentials obtained without a second factor; tokens carry amr; a ThrottleStore (memory or Redis) backs login and e-mail throttles across instances; logout ends a cookie session with an empty body; auth routes carry meta.account, which the membership guard honours. (@basaltkit/auth 3.1, teams 3.0.1)
  • Row-level security, applied and swept. tenancyExtension({ rls: true }) sets the tenant on the connection before every operation so Postgres policies filter too; prismaPlugin({ assertMigrated }) refuses to boot against the wrong database; crossTenantScan / crossTenantSweep give a reconciler an audited way to find stuck work in every tenant and handle each row inside its own tenant's context; and the GIN index survives full-text search under RLS. (@basaltkit/prisma 2.1–2.3, search-postgres 1.1, scheduler 1.5, events 1.3)
  • Roles for every tenant, once. roleCatalog on the Gate is a code-defined role → permissions map valid in every scope, so a catalogue no longer has to be copied into each tenant; teams.members() and the user source can now name everyone with a role without reaching into the auth tables. (@basaltkit/permissions 2.1, auth 3.2, teams 3.1)
  • Pre-signed direct uploads, with Content-Type, length and SHA-256 bound into the signature on S3 (and the honest subset on Azure and GCS), plus the s3Disk fix that had been dropping every disk option except scope. (@basaltkit/storage 3.1)
  • Files know what they are. validate.sniff reads the real type from the magic bytes; requireScan quarantines a file until a scanner clears it (423 FILE_NOT_SCANNED). (@basaltkit/files 4.1)
  • App-specific env prefixes. defineEnv(shape, { prefix: 'MY_SAAS' }) reads MY_SAAS_DATABASE_URL first, so node --env-file can no longer boot one app against another project's exported database. Scaffolds wire it. (@basaltkit/env 3.1, create-basalt 1.7)
  • Generated code that compiles. make:service alone no longer imports a repository it never created; every make:<kind> names the siblings it still needs. create-basalt asks the registry for the latest version of every dependency, and --prisma scaffolds a PostgreSQL-backed app. (@basaltkit/generator 1.5, create-basalt 1.5–1.8)

Two packages debut ​

  • @basaltkit/backup — PostgreSQL backups as a service: custom-format dumps streamed to any Basalt disk, manifests with checksums, retention, restore with integrity verification, per-tenant schema and database targets, scheduler and CLI integration. Passwords reach pg_dump through the environment, never the command line. (0.3.0)
  • @basaltkit/drives — connect a tenant's external file storage and keep it in sync: OAuth connect flow, listing, change feeds with cursor reset, streamed download and upload, signed notifications with a neutral endpoint parity-tested on all three adapters. Three adapters ship with it: drives-dropbox, drives-google and drives-microsoft (OneDrive / SharePoint). The phase-2 audit of the adapters found one credential leak and one silent data-loss bug before anyone else could. (0.2.0 / 0.1.0)

Docs ​

  • The multi-tenant pattern — the canonical way to build a schema-per-tenant SaaS on Basalt, written as ten checkable rules after auditing three production apps, with the privilege chains each of them actually shipped. The shared-database tip, the tenancy troubleshooting advice and the cookbook were corrected where they contradicted it.
  • Guides for backups and external drives.

Upgrading to 1.11 ​

Packages are independent — bump only what you use. Every major below has an explicit opt-out named next to it; prefer fixing the app.

Defaults that now refuse ​

PackageWhat refusesOpt-out / fix
auth 3API keys outside their tenant; narrow keys on unscoped routes; cross-site cookie-only writes (AUTH_CSRF_REJECTED); social login on unverified e-mail; OAuth without browser bindingapiKeysPlugin({ allowTenantlessKeys, allowNarrowKeysOnUnscopedRoutes }), authPlugin({ csrf: { trustedOrigins } }), socialLogin({ mfa: 'skip' }), use OAuth.authorize()
env 3devDefault when NODE_ENV is unsetset NODE_ENV=development where you meant it
tenancy 2ids outside the grammar; tenantScoped() with no tenant in contextrename ids; requireTenantId(id) / tenancy.run(id, …) in system code
prisma 2raw ops and cross-tenant writes inside a tenant; non-canonical schema namessetTenantConfigSql is the one allowed raw statement; rename schemas once (README)
storage 3tenant-less access on a tenant-scoped disk; temporary URLs over 7 daysscope: null on central disks; maxTemporaryUrlTtl
permissions 2evaluating a tenant named like a scopemigrate 'global' rows (below)
files 4 / comments 3 / audit-viewer 3non-owner file access; unguarded audit viewer; a tenantId that differs from the contextfileRoutes({ authorize, shared }), auditViewerRoutes({ meta: { can } })
webhooks 2unsigned or shared-secret tenant deliveries; tenant-less register/listallowUnsigned, allowSharedSecret, { system: true }
subscriptions 4empty webhookSecret; redirect URLs off the configured originsset the secret; allowedRedirectOrigins
teams 3invite acceptance without verified e-mail; granting roles above your rankteamRoutes({ requireVerifiedEmail: false }), grantableRoles
auth-saml 2assertions for other domains; IdP-initiated responses; node-saml < 5.1allowedEmailDomains, validateInResponseTo: 'ifPresent'
mcp 3full process.env to spawned serversenv allow-list on the client

Two data migrations ​

Permissions. Grants written under the pre-2.0 global scope are no longer read. Rename them once:

sql
UPDATE perm_user_roles       SET scope = '@global' WHERE scope = 'global';
UPDATE perm_user_permissions SET scope = '@global' WHERE scope = 'global';
UPDATE perm_role_permissions SET scope = '@global' WHERE scope = 'global';

readLegacyGlobalScope: true on the Gate keeps reading the old rows while the migration is scheduled — a transition aid, not a setting to keep.

Prisma schema names. tenantSchema() now suffixes any id that is not canonical (acme, acme_co keep their names; Acme Co becomes tenant_acme_co__<hash>). Tenants with non-canonical ids have a schema under the old name and must be renamed once — the @basaltkit/prisma README has the statement. Canonical ids are unaffected.

Columns that are added, never required ​

@basaltkit/audit-prisma 1.2 adds nullable ip, userAgent, chain, seq, prevHash, hash and a unique (chain, seq); they are written only when integrity or requestContext is on. @basaltkit/events-prisma 1.2 adds lockedUntil / lockedBy for multi-replica outbox claiming (claim: true). Run basalt prisma:sync and a migration; the SQLite stores add the columns themselves.

GLOBAL_SCOPE is a constant, not a string ​

If any code spells 'global' — a seed script, a CLI command, a test — it now grants into a scope nobody reads. Import GLOBAL_SCOPE from @basaltkit/permissions. The multi-tenant pattern has the shape.

sharp and nodemailer ​

@basaltkit/image-sharp 1.1.4 requires a patched sharp (libheif vulnerabilities); @basaltkit/mailer-smtp 1.0.1 accepts nodemailer 9 and 10.


Previously — Basalt 1.10 ​

The release of missing halves: a tenant that can be destroyed, an index that can be rebuilt, a durable store for files, revisions for documents, and permissions that know who is asking.

Two contracts changed

@basaltkit/files revises its store contract, and app.server in @basaltkit/testing is now awaited. Both edits are mechanical — see Upgrading to 1.10. Prisma apps that use API keys also need one new column.

Basalt 1.10 is the release of missing halves. The application that wrote 1.9 kept going, and what it ran into this time was not two packages that failed to fit together — it was capabilities with no other side. A tenant could be created and never destroyed. An index could be kept current and never rebuilt. A permission said what a caller may do and never who they are.

A missing half does not announce itself. There is no stack trace for a question the framework has no answer to: every application invents its own, the inventions differ, and the one that is wrong looks exactly like the one that is right — until somebody sees a record that was not theirs.

Capabilities that only worked in one direction ​

  • A tenant can be removed. TenantSource had find, findByDomain, list, create and save; Tenancy had no destroy — no path out, not even an optional one. In tests that meant DROP SCHEMA with a string-interpolated identifier, and the reason it was needed is worse than the pattern: without the cleanup, a leftover schema makes the next provisioning a no-op and every assertion below it passes green against the previous run's data. The order of operations is the design — mark deleting first, so the resolver stops routing before anything is torn down; run onDeprovision inside the tenant's context; delete the record last, because the record is the only thing naming that storage. (@basaltkit/tenancy)
  • search.reindex() rebuilds an index from the rules that feed it. A rule fed by events knows only what was created after the rule existed, so an application adding search to data it already had got a box that returned nothing for everything old — and an empty result is indistinguishable from "there is none". A rule's backfill yields hook payloads, not rows, so one document function serves both directions and a second mapping written by hand cannot drift from it. (@basaltkit/search)
  • The file domain has a durable store. Eleven domains ship both a -prisma and a -sqlite backend without a single exception; files shipped neither — the only domain with a store contract and no durable implementation of it. The disk key is files/<uuid> and the uuid lived in the process, so a restart left every upload in the bucket, unreferenced and unmatchable to the document it was, while the application reported an empty list and nothing errored. (@basaltkit/files-prisma)
  • Documents have revisions. Files.upload mints a new id and a new path on every call, so uploading the same contract twice produced two unrelated records with nothing linking them, and every application that needed "which draft am I reading?" wrote the same bookkeeping by hand. Not a version field on FileRecord: a file record describes bytes, a revision describes an editorial act, and each revision points at a whole file whose bytes are never overwritten. The store assigns the number and keys on [tenantId, groupId, version], so the database refuses the duplicate that a read-the-latest-and-add-one race would produce. (@basaltkit/files-versions)

Declarations instead of bookkeeping ​

  • activityRule — search has syncRule, realtime has bridgeRule, and activity, probably the most common of the three, had only the fluent builder, which is for writing a line by hand inside a service. The cost of the asymmetry is not the thirteen hooks.on() calls an application writes instead; it is that the natural answer to "record this" becomes "call activity from MatterService", coupling the domain to the package the other two teach you to keep at arm's length. A rule never rethrows, and that is where it deliberately differs from syncRule: a history line that cannot be written must not fail the case closure that produced it. (@basaltkit/activity)
  • canonicalDomain gives a new tenant an address. Every durable source reads domains from one key, and an application that never passes it creates tenants with none — silently, because subdomainResolver answers from the Host without consulting the table. The tenant serves traffic; what is missing is the record that the address belongs to it, so a custom domain cannot be attached and nothing stops a second tenant claiming the same one. Applied by tenancy.create(), so every creation path gets it instead of each one remembering. (@basaltkit/tenancy)
  • authorize decides who may see a hit. A driver filters by the fields declared filterable and nothing else, which left search as the one surface with no answer for per-row visibility. The hook runs after the driver, which is what lets the package keep asking until the page is full — the thing a caller cannot do from outside without guessing an over-fetch factor. Copying the ACL into the index is the fast alternative and the wrong one: a stale index gives an old result, a stale ACL gives an unauthorized one. (@basaltkit/search)

Answers that were quietly wrong ​

  • A permission is a capability, not a surface. matter:read cannot tell "read my own case in the client portal" from "read the case with the litigation strategy in it", so a role granted the first also passed the guard on the second — and an authenticated portal client received 200 on an internal listing with their own case's strategy in the body. meta.audience describes who a route is for, and the default is the whole design: a route that declares no audience is unreachable by a confined role. Marking the small surface a restricted role may reach is a list somebody maintains; marking every route they may not is a list somebody forgets. (@basaltkit/permissions)
  • File versions read the ambient tenant, like Files always did. They resolved the store key as tenantId ?? SINGLE_TENANT_SCOPE, skipping the request context, so a multi-tenant app that passed no explicit id — the normal case — wrote versions under acme and read them back under default: history() returned [], latest() returned null, and download() raised for a file sitting on the disk. The rule now lives in one place, exported by files and used by both. (@basaltkit/files-versions)
  • The activity feed is scoped required under tenancy. The old default meant "scope to the context tenant, run unscoped when there is none", so a feed query outside a tenant returned every tenant's records — and a feed line names a client in prose. The same rule cache already applied. (@basaltkit/activity)
  • Every HTTP adapter in testing is an optional peer. express and hono already were; fastify was a plain dependency because it is the default adapter, and that asymmetry cost somebody half an hour. When the package moved its fastify range to ^2 while an app was still on 1.x, pnpm installed both, and createTestApp resolved a FASTIFY token from a different copy than the one the app's fastifyPlugin registered: two createToken('fastify') calls, two identities, one container that cannot match them. The error said "No provider registered for token fastify" and named neither the package nor the version skew. A peer cannot duplicate. (@basaltkit/testing)

Upgrading to 1.10 ​

Packages are independent — bump only what you use. Two contracts changed, and both edits are mechanical.

app.server is now awaited ​

ts
const server = await app.server()   // was: app.server

@basaltkit/testing imports the adapter on demand, as it already did for express and hono, so an app booted without any HTTP plugin still works and the package never reaches for something the application may not have installed. A token resolved through a dynamic import cannot be synchronous.

If pnpm install starts warning about an unmet fastify peer, that warning is the point: it is the version skew that used to surface at runtime as a token that does not exist.

The files store contract has three revisions ​

@basaltkit/files publishes a major. A custom FileStore needs three edits:

WasIsWhy
scanned?: booleanscannedAt?: numberThe date derives the boolean and the boolean does not derive the date. "Scanned", with no idea when, stops being an answer the moment the scanner's rules change — the one thing antivirus rules reliably do. The file:scanned hook keeps its name: the event is not the field
metadata?: Record<string, unknown>metadata?: FileMetadataRecord<string, JsonValue> — otherwise every durable store casts its way past its driver's JSON type, a cast each implementation repeats and has to get right
FilePatch = Partial<Pick<…>>spelled outSo it can say that a key present with undefined clears the column while an absent key is left alone — which Partial of an optional field cannot express under exactOptionalPropertyTypes, and which is how a caller drops a stale scan result

prisma:sync learns the files domain, so its models merge like every other one.

Prisma apps add a column for API key expiration ​

@basaltkit/auth-prisma 1.5.0 added a nullable expiresAt column to AuthApiKey (auth_api_keys) for the new optional key expiration. Regenerating the client is not enough — the database needs the column, or every API-key request fails. Add a migration (prisma migrate dev --name add_api_key_expires_at), which on PostgreSQL is:

sql
ALTER TABLE "auth_api_keys" ADD COLUMN "expiresAt" TIMESTAMP(3);

With schema-per-tenant the column must exist in every tenant schema: add the migration to your tenant migrations, then run basalt tenant:migrate. A test suite that never issues an API key will not notice. Since auth-prisma 1.5.1 a missing column raises AUTH_API_KEY_SCHEMA_OUTDATED with these instructions instead of a raw Prisma P2022. @basaltkit/auth-sqlite needs nothing: it adds the column itself when the database is opened.

Two packages debut at 0.1.0 ​

files-prisma and files-versions publish 0.1.0, not 1.0.0. Neither has been run against a real database by anyone yet, and joining the ecosystem's semver commitment on their first day would promise something nobody has checked. The version number says that more cheaply than a changelog nobody reads, and leaves 1.0.0 for when it is earned.


Previously — Basalt 1.9 ​

The release written by an application rather than by the framework: a real legal SaaS was built on Basalt, and fifteen places where the framework made its author write code the framework should have written were closed.

Zod 4 is required from 1.9 on

Twelve packages narrow their zod peer from ^3.24.0 || ^4.0.0 to ^4.0.0 — see Upgrading to 1.9.

Two official packages that did not fit together ​

  • Full-text search could not run through the Prisma client at all. The language was passed as a bound parameter, which PostgreSQL will not accept where a regconfig belongs. Every query failed with a type error — not a degraded result, no result. Now cast at the call site. (@basaltkit/search-postgres)
  • The audit plugin aborted tenant provisioning. Its default hook patterns included tenancy:switched, which fires outside any tenant context; the capture threw, and the error propagated out through provision(), marking the tenant failed. An application following both packages' defaults could not create a single tenant. The pattern is gone and both bridges now isolate their own failures. (@basaltkit/audit)
  • The admin package would not bundle for the browser it targets. It imported node:crypto to mint one id, and the barrel re-exported it, so importing defineResource dragged a Node builtin into the bundle. Every application had to alias it away. (@basaltkit/admin)

The framework now writes what every application was writing ​

  • gate.actor() hydrates the caller's roles from the request scope, instead of each service reimplementing it — and getting a silent 403 when it forgot. (@basaltkit/permissions)
  • accessRoutes() and a dependency-free permissions/match subpath, so a browser evaluates wildcards the same way the server does. Divergence there is not a bug you notice; it is a screen that renders a button nobody can press. (@basaltkit/permissions)
  • inAppRoutes() serves the four endpoints every application wrote by hand. The routing shape was opinionated enough to leave out; the security rule was not, and is the same everywhere — the recipient is the session, never a parameter. (@basaltkit/notifications)
  • tenantClient() for stores constructed before any request exists, instead of each application writing the same proxy. (@basaltkit/prisma)
  • authRoutes({ password }), applied to registration and reset — a policy enforced on one of the two is not a policy. (@basaltkit/auth)

Declarations that are now checked ​

  • meta.subscribed is validated at boot. A plan name with a typo used to produce a route that quietly refused everyone. Every offending route is reported at once, because booting, fixing one, and booting again is a slow way to find three. (@basaltkit/subscriptions)
  • RouteMeta takes an index signature, so a package can extend route metadata without every application casting. (@basaltkit/http)
  • prisma:sync distinguishes the central schema from a tenant's. The most obvious flag used to put central tables inside every tenant's schema, silently. (@basaltkit/prisma)

Generated code that matches the project it is generated into ​

  • defineResource accepts field labels and translated enum options. Labels came from the field name — taxId read Tax Id — and enum options came out as the stored values. In an application written in another language the generated form ended up half in English and half in database values, which was enough to make hand-writing it the easier option. (@basaltkit/admin)
  • The generator takes a configurable Prisma client, and project-wide defaults. An application with a second client — schema-per-tenant, a read replica — had to hand-edit every generated repository. (@basaltkit/generator)
  • authorize receives the container, so a realtime subscription gate can reach a service without a module-level variable filled from someone else's boot. (@basaltkit/realtime)
  • The SDK passes native bodies through untouched — FormData, Blob, ReadableStream — and accepts an AbortSignal and per-call headers. (@basaltkit/sdk)

Upgrading to 1.9 ​

Packages are independent — bump only what you use. One change is required of everyone, and one behaviour tightened.

Zod 4 is required ​

Twelve packages — admin, audit-viewer, auth, comments, env, fastify, files, http, mcp, sdk, subscriptions, teams — narrow their zod peer from ^3.24.0 || ^4.0.0 to ^4.0.0. Each publishes a new major for it.

bash
pnpm add zod@^4

The second half of that old range had not been exercised in a long time: this repository tests against zod 4 only, so zod 3 was a compatibility promise nobody was checking. Supporting a major version you never run is worse than not supporting it — it holds the API surface back while promising something that would break on first contact.

Zod's own 3-to-4 migration guide covers the API changes. The two that touch Basalt users most:

  • z.string().datetime() becomes z.iso.datetime()
  • error customisation moves from message / invalid_type_error to a single error parameter

The peer asks for ^4.0.0, not the newest 4.x — requiring the version this repository happens to test would force every consumer to move in step with us for no reason.

An unknown plan name now fails the boot ​

meta.subscribed: 'pró' against a catalogue containing pro used to boot fine and refuse every caller at runtime. It is now an error at startup, listing every offending route at once. If a boot starts failing after the upgrade, the route was already dead — you can now see it.


Previously — Basalt 1.8 ​

The release where multi-tenant persistence stopped failing quietly: four distinct ways a tenant could end up with the wrong data — or no data at all — while every layer reported success.

A tenant is never served the wrong data quietly ​

  • Schema-per-tenant on a database that cannot do it. It relies on a schema being a namespace inside a database. In MySQL a "schema" is a database; SQLite has no equivalent. Configuring it there used to surface as a raw CREATE SCHEMA syntax error at tenant-creation time, far from the config that caused it. Now refused where the configuration is read — at boot, and once before any migration runs. (@basaltkit/prisma 1.5)
  • Migrations read from the wrong history. migrations.path belongs to your prisma.config.ts, not to the schema file, so pointing --schema at the tenant models left Prisma applying the central migration history. The tenant came up holding _prisma_migrations and none of its own tables. Pass configPath instead. (@basaltkit/prisma 1.5)
  • A migration that succeeded without doing anything. prisma migrate deploy exits 0 when it finds no migrations, so a missing or empty migrations directory looked exactly like success — and the tenant was marked ready. migrateTenants now counts the tenant's own tables and reports ok: false. It counts tables, not migrations, because db push is a legitimate strategy with no migration history at all. (@basaltkit/prisma 1.6)
  • Which strategy works on which database is now stated in the docs, per strategy and per engine, instead of being inferable from an error message. See Which strategy works on which database.

This is deliberately a set of guards, not abstractions. Translating mode: 'schema' into a separate database on MySQL would be doing database-per-tenant under a name that says otherwise — different backups, different connection limits, different migration cost. That belongs in your config as a decision, not in the framework as a silent substitution.

Central and tenant routes in one app ​

required: true rejected any request that resolved no tenant — on every route, which no app can live with: a health check has no tenant to send, and a load balancer will never set the header. Two ways out now, and they compose:

ts
// Deny by default…
tenancyPlugin({ source, resolvers, required: true })

// …and let each route say what it is, next to its handler.
route({ method: 'GET', url: '/pricing',  meta: { tenant: false }, handler })
route({ method: 'GET', url: '/invoices', meta: { tenant: true },  handler })

meta.tenant overrides the app-wide default in both directions, so the decision lives with the route and survives a rename — unlike a path list in another file, which stops matching silently. required: { except: [...] } remains for paths you do not own, such as routes mounted by another package. (@basaltkit/tenancy 1.7 and 1.8)

@basaltkit/http 1.16 passes the route being served to enrichers, not just guards — which is what makes the above possible, and why it behaves identically on Fastify, Express and Hono rather than through three parallel implementations.

One app, both worlds ​

prismaPlugin already accepted client (for the tenant-less context) alongside schemaPerTenant, but that was one undocumented sentence — so in practice it was undiscoverable. With both set, db() returns the central client on central requests and the tenant's client on tenant ones:

ts
route({ method: 'GET', url: '/users', meta: { tenant: false }, handler: async () =>
  db<PrismaClient>().authUser.findMany(),  // central on the apex, tenant on a subdomain
})

The same /auth/login then authenticates central users on the apex and tenant users on a subdomain — because the two look in different schemas, not because a handler checks. Routes mounted by other packages (authRoutes(), mfaRoutes()) are covered by mapping meta over them. See Serving central and tenant routes from one app, including the trade-off: with client set, a mis-scoped tenant route reads the central database instead of failing loudly, and required: true is what keeps that safe.

Upgrading to 1.8 ​

Packages are independent — bump only what you use. Nothing in 1.8 is a breaking change, but two behaviours tightened:

  1. migrateTenants can now fail a tenant it previously passed. A migration that produced no tables reports ok: false with PRISMA_TENANT_SCHEMA_EMPTY. That is almost always a missing or misdirected migration history — but if a tenant legitimately starts empty, pass verifyTables: false.
  2. Schema-per-tenant is refused at boot on MySQL and SQLite. It never worked there; it used to fail later and less clearly. Move to database-per-tenant (forTenant, or { mode: 'database', urlFor }), which gives stronger isolation anyway.

Previously — Basalt 1.7 ​

The release where no core forces a backend on you — and where a failed request became visible on every adapter.

A core defines the contract, a backend is a package ​

queue, storage, cache and mailer each shipped a string shorthand for one backend — connection, driver: 's3', driver: 'redis', driver: 'smtp'. A string cannot be resolved lazily, so the shorthand is what forced the dependency: an app on Azure Blob still installed 4.4 MB of AWS SDK, and one sending mail through Resend still installed an SMTP client it never opened.

CoreWas forced on everyoneNow
@basaltkit/queue 2.xbullmq@basaltkit/queue-bullmq 1.0
@basaltkit/storage 2.x@aws-sdk/client-s3 — 4.4 MB@basaltkit/storage-s3 1.0
@basaltkit/cache 2.xioredis — 1.5 MB@basaltkit/cache-redis 1.0
@basaltkit/mailer 2.xnodemailer — 688 KB@basaltkit/mailer-smtp 1.0

An app using local storage, the in-memory cache and Resend drops 6.5 MB of client libraries it never called. It also ends an inconsistency that had become hard to defend: adding a fifth queue backend was easy, adding a second first-class one was not, because the core had a favourite. The repo-wide driver-boundary tripwire's allowlist, which recorded exactly these four as known debt, is now empty.

A failed request is visible on every adapter ​

Whether an error reached your terminal used to depend on which adapter you had mounted — exactly the difference the neutral pipeline exists to erase. Express and Hono logged nothing at all: a 500 left no server-side trace. Fastify logged 5xx only, and only from one of its two catch sites. Now every 4xx and 5xx is reported on all three, as structured fields rather than an interpolated string. (@basaltkit/http 1.15)

main is protected ​

verify (Node 22 and 24), coverage, analyze and CodeQL are now required checks, enforced for administrators, with direct pushes blocked. Before this the branch was unprotected.

Upgrading to 1.7 ​

The four capability majors are the only breaking changes, and each is one import and one line:

diff
-queuePlugin({ connection: REDIS_URL, jobs, workers })
+bullmqQueuePlugin({ connection: REDIS_URL, jobs, workers })

-storagePlugin({ disks: { docs: { driver: 's3', bucket } } })
+storagePlugin({ disks: { docs: s3Disk({ bucket }) } })

-cachePlugin({ driver: 'redis', url })
+cachePlugin({ driver: redisCache(url) })

-mailerPlugin({ driver: 'smtp', smtp: { url }, from })
+mailerPlugin({ driver: smtpMailer({ url }), from })

You are not affected if you already passed a driver instance, used driver: 'local', the default in-memory cache, or the log/memory mailer drivers. TypeScript flags every case at compile time, because the removed strings left their unions. Full detail in Driver packages.


Previously — Basalt 1.6 ​

"Basalt 1.6" is the umbrella label for this wave of work; the @basaltkit/* packages ship independently (see Versioning). Below is what landed and the package version that carries it.

Basalt 1.6 is the release where the framework guarantees what it promises. Three architecture review cycles took the project's stated principles — adapter neutrality, the dev-only AI boundary, "SaaS is opt-in", secure-by-default — and turned each one from a convention people had to remember into a CI tripwire that fails the build. Along the way the reviews found, and fixed, real bugs those principles were supposed to prevent.

Promises became guarantees ​

Five new machine-enforced boundaries, each with a test that fails the build:

  • Adapter neutrality — no feature package may depend on a specific HTTP adapter. Ten packages had drifted into importing the route contract through@basaltkit/fastify, forcing Fastify into Express/Hono apps; all repointed to @basaltkit/http. A cross-adapter conformance suite now runs the same neutral contract on all three. (@basaltkit/testing gained createTestApp({ adapter }).)
  • SaaS is opt-in — a generic package may never require tenancy. Six had started to: audit.trail() threw on every call in a non-tenant app, pushing you to a method the docs call a dangerous escape hatch; search even required tenantId on write while reads threw. The new apps/beyond-saas boots a real app with 18 generic plugins and no tenancy to keep it honest. See Beyond SaaS.
  • The AI layer stays dev-only — an import-graph test keeps @basaltkit/ai and @basaltkit/ai-mcp out of any application runtime.
  • DI lifetime safety — the container now fails loudly on a captive dependency (a singleton that would freeze one request scope's instances app-wide) instead of silently serving stale objects. (@basaltkit/core 1.3)
  • Declared guards must be enforced — a route that declares meta.auth, can, teamRole, scopes, subscribed or feature with no plugin to enforce it now fails at boot, naming the plugin that fixes it, instead of serving unprotected traffic. Opt out deliberately with allowUnguardedMeta.

Security ​

  • Billing: checkout/portal/invoice routes shipped without auth (anyone could open a tenant's payment portal), and checkout() overwrote the subscription so a genuinely-signed webhook could activate an escalated plan. Both fixed, with the escalation reproduced as a test first. (@basaltkit/subscriptions 2.7)
  • Refresh-token reuse: markUsed was read-then-write, so two concurrent refreshes each returned a valid token pair. Now a compare-and-swap across all stores. (@basaltkit/auth 1.8)
  • Stored-XSS via signed file URLs closed (Content-Disposition: attachment by default), server-rendered UIs got a route-scoped, hash-locked CSP, mail bodies are redacted in production, and html\`` makes escaping the default path for HTML mail.

Reliability under load ​

Multi-replica deployments got the guarantees they were missing: the scheduler's .onOneServer() + ScheduleLock (no more every-replica double-runs), an event outbox that actually honours at-least-once, RabbitMQ publisher confirms before ack (closing a job-loss window), and Kafka redelivery instead of silent loss. Five process-crash paths were eliminated — one dead WebSocket or a Redis blip could previously take down a domain write.

The docs are now the official reference ​

With API generation dropped, the guides are the reference: 27 guides (EN + PT) rewritten to one didactic arc — what it is → mental model → runnable quickstart → recipes → full options table → failure modes keyed on real error codes — and Core concepts documents the internal API (container lifetimes, plugin phases, the route pipeline, metadata buckets, writing your own guard/enricher) well enough to build a third-party package from the docs alone. Writing them surfaced four more real bugs.

Upgrading to 1.6 ​

Packages are independent — bump only what you use. Two things to know:

  1. The boot check is new. If your app declares meta.auth (or can, teamRole, scopes, subscribed, feature) on a route but never registers the enforcing plugin, it now fails at boot with the plugin named. That route was serving unprotected before; register the plugin, or opt out with allowUnguardedMeta if your edge handles it.
  2. Some defaults tightened (documented per package): file URLs default to attachment, mail bodies are redacted in production, cache scoping fails closed when tenancy is active, and meta.can rejects non-string values instead of silently skipping the check.

Previously — Basalt 1.5 ​

The AI developer experience in your editor and any MCP client — Claude Desktop, Claude Code, or your own — plus the TypeScript 7 move across the whole repository.

AI development over MCP ​

  • @basaltkit/ai-mcp — a dev-only MCP bridge that exposes Basalt's AI workflows as MCP tools: basalt_analyze, basalt_doctor, basalt_plan, basalt_review, and a workspace-confined basalt_make. Point an MCP client at your app (npx @basaltkit/ai-mcp --cwd=<app>) and drive the whole analyze → plan → make → review loop from Claude Desktop/Code. It also ships project resources (basalt://project/*, basalt://knowledge/architecture) and workflow prompts (plan-feature, scaffold-resource, harden-tenancy, add-rbac), over stdio (default) or an opt-in HTTP transport. Like the rest of the AI surface, it is never a runtime dependency of your app. (@basaltkit/ai-mcp 0.1) → see AI in your editor (MCP bridge).
  • @basaltkit/mcp-core — a zero-dependency MCP core extracted from the runtime @basaltkit/mcp: the JSON-RPC protocol, a generic tool/resource/prompt server, stdio + HTTP transports, and progress/cancellation. Build your own MCP server on it without pulling the framework runtime into the graph; the runtime @basaltkit/mcp now sits on top of it with an unchanged public API. (@basaltkit/mcp-core 0.3) → see Building an MCP server.
  • Safe by design. basalt_make previews by default (clash detection + unified diffs, no writes); applying is explicit (mode:"apply"), overwrites need force, migrations are double-gated, and every write is confined to the target workspace.

TypeScript 7 everywhere ​

  • The root now runs on TypeScript 7 too, retiring the last 5.9 pin that existed only for linting — the whole repository, packages and root, is on the TS 7 native compiler. ESLint is temporarily paused (a documented no-op, re-enabled with a one-line change) until typescript-eslint ships official TS 7 support; typecheck stays fully active, so real type errors are never hidden.

Security hardening ​

  • The opt-in HTTP transport validates Origin and Host. @basaltkit/mcp-core's HTTP server already bound to loopback; it now also rejects cross-site (Origin) and DNS-rebinding (Host) requests, so a browser page can't drive the local dev bridge. Loopback-only by default, with an explicit allow-list escape hatch for deliberate remote/CI use. (@basaltkit/mcp-core 0.3, minor)

Documentation ​

Upgrading (1.5) ​

Packages are independent — bump only what you use. This wave is additive: the new @basaltkit/ai-mcp and @basaltkit/mcp-core are brand-new dev-only tooling, @basaltkit/mcp's runtime public API is unchanged, and the TypeScript 7 root move is internal. New Basalt apps can opt into the bridge with create-basalt --mcp.


Previously — Basalt 1.4 ​

Foundations-and-hardening: it modernized the toolchain, put real teeth back into the quality and security gates, and graduated the AI surface to a stable 1.0.

TypeScript 7 toolchain ​

  • The whole monorepo compiles, type-checks and tests on the TypeScript 7 native compiler. Every package's build moved from tsup to plain tsc — dropping rollup-plugin-dts, which is incompatible with the TS 7 compiler — with no change to the published exports/types contracts.

AI & MCP → 1.0 ​

  • @basaltkit/ai 1.0 — the dev-only AI developer experience: a provider-agnostic engine plus the basalt ai CLI (analyze, doctor, plan, make, review), under a stable public API. (@basaltkit/ai 1.0)
  • @basaltkit/mcp 1.0 — the runtime Model Context Protocol surface: expose opt-in routes as tools over HTTP (any adapter) or stdio, and consume external MCP servers as a client — all through the neutral route pipeline, no external SDK. (@basaltkit/mcp 1.0)

Quality gate ​

  • The coverage gate is enforced again. It had gone informational; it now blocks regressions, scoped to unit-testable runtime code. Real aggregate at re-baseline: statements 93% · branches 85% · functions 91% · lines 95%.

Security hardening ​

  • Every runtime-reachable ReDoS finding is eliminated. Quadratic trailing-character strips were rewritten as linear, non-regex trims across audit, tenancy, mailer, auth, sdk and search-elasticsearch, and the PII redactor length-bounds its input before matching. The code-scanning backlog is at zero open alerts.

Released under the MIT License.