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.

Info
Upgrade with 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.

typescript
// 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.

typescript
// 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.

typescript
// Behind one trusted reverse proxy
app.setTrustedProxy({ depth: 1 });

// Or trust specific proxy addresses
app.setTrustedProxy({ addresses: ["10.0.0.0/8"] });
Warning
If you previously relied on 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.

typescript
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.

typescript
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.

typescript
app.static("/assets", "./public", { dotfiles: "allow" });

// Default is 4 MB
app.bodyLimit(20 * 1024 * 1024);
Info
Multipart uploads handled by 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 405 with an Allow header instead of 404.
  • ctx.html() sends text/html; charset=utf-8.
  • The published package ships dist, README.md, and scripts/buntok-skill only.
  • Container scan() no longer guesses dependencies for classes with constructor parameters but no @Dependencies().
Info
Full details are in CHANGELOG.md inside the package.