Upgrading to 3.0#
3.0 is a security and correctness release. The API surface is mostly additive, but several defaults changed to safer values. Work through the items below before deploying.
bun add @buntok/core@3. Buntok now requires Bun >=1.2.0.Encryption no longer takes an IV#
encrypt() now generates the AES-GCM IV internally. Passing a caller-controlled IV made nonce reuse possible, which breaks the cipher. Use deriveKey() instead of passing a raw password.
// Before
await encrypt(data, key, iv);
// After
const { ciphertext, iv } = await encrypt(data, key);
const plaintext = await decrypt(ciphertext, key, iv);
// Derive a key from a password (preferred)
const { key, salt, iterations } = await deriveKey(password);Cookies default to SameSite=Lax#
setCookie() now adds SameSite=Lax when no policy is provided. If cross-site cookies are required, setsameSite: "none" together with secure: true - the combination is validated and throws when insecure.
// Cross-site (third-party) cookie
ctx.setCookie("session", token, {
sameSite: "none",
secure: true,
httpOnly: true,
});
// Session cookie for same-site navigation (default)
ctx.setCookie("session", token, { httpOnly: true });ctx.ip is the real peer address#
ctx.ip now comes from server.requestIP(). Forwarding headers are ignored unless the peer is trusted. trustedProxy.depth counts trusted hops from the right of X-Forwarded-For.
// Behind one trusted reverse proxy
app.setTrustedProxy({ depth: 1 });
// Or trust specific proxy addresses
app.setTrustedProxy({ addresses: ["10.0.0.0/8"] });ctx.ip reading X-Forwarded-For directly, configure setTrustedProxy() or the value will be the proxy address.Timeouts return 504#
TimeoutError (from the timeout middleware) is now mapped to 504 Gateway Timeout instead of 500. Update clients or tests that assert on 500.
CORS rejects disallowed origins explicitly#
Disallowed origins no longer receive an Access-Control-Allow-Origin header, and preflight requests from them return 403. credentials: true with a wildcard origin logs a warning because browsers reject it.
app.use(cors({
origin: ["https://app.example.com"],
credentials: true, // never combine with origin: "*"
}));API docs are disabled in production by default#
apiDocs.safeOnProduction now defaults to true. To expose docs in production, opt out explicitly.
app.apiDocs({
path: "/docs",
title: "My API",
safeOnProduction: false, // only if you really want public docs
});Static dotfiles and body limits#
Static routes deny dotfiles by default, and request bodies are capped at 4 MB. Enable dotfiles only for directories that need them, and raise the body limit when accepting large uploads through route handlers.
app.static("/assets", "./public", { dotfiles: "allow" });
// Default is 4 MB
app.bodyLimit(20 * 1024 * 1024);uploader() keep their own per-field limits; the body limit applies to the raw request body.Smaller changes#
- Unsupported methods on a known path return
405with anAllowheader instead of404. ctx.html()sendstext/html; charset=utf-8.- The published package ships
dist,README.md, andscripts/buntok-skillonly. - Container
scan()no longer guesses dependencies for classes with constructor parameters but no@Dependencies().
CHANGELOG.md inside the package.