WebSocket and login safeguards

Use wsRateLimit() on upgrades, loginThrottle() on failed authentication, and rotateSession() after login or a privilege change.

These focused safeguards cover authentication entry points, upload boundaries, and WebSocket upgrades with first-party helpers instead of copy-pasted local policy.

1. wsRateLimit()

wsRateLimit() adapts the existing rateLimit() shared-bucket primitive to the WebSocket upgrade boundary. Put the same groupId on HTTP login routes and the WebSocket session route so an attacker cannot dodge the bucket by switching transports.

import { App, loginThrottle, wsRateLimit } from "@daloyjs/core";

const app = new App({ env: "production" });

// No keyGenerator: both helpers use the default key, which is the
// trusted forwarded client IP (or the TCP peer when the request did not
// come through a listed proxy). Never key on a raw client header.
const authBucket = {
  windowMs: 60_000,
  max: 10,
  groupId: "auth-entry",
  trustedProxies: ["10.0.0.0/8"], // your load balancer's range
};

app.post(
  "/login",
  {
    hooks: loginThrottle(authBucket),
    responses: { 200: { description: "ok" } },
  },
  async () => ({ status: 200 as const, body: { ok: true } }),
);

app.ws("/session", {
  beforeUpgrade: wsRateLimit(authBucket),
  open(conn) {
    conn.send("ready");
  },
});

Both helpers must derive the same key for the shared counter to work. With proxy trust configured, as above, the default key is identical on both paths. Without proxy trust, rateLimit() (and so wsRateLimit()) keys every caller into one shared bucket while loginThrottle() keys per TCP peer, so the two would not line up. If you need a custom key, derive it from something the server controls, such as getConnInfo(ctx.request)?.remoteAddress or an authenticated identity.

Never key a limiter on a raw client-supplied header (x-user-key, x-client-id, an untrusted X-Forwarded-For). The client picks the value, so an attacker sends a fresh one on every attempt and gets a fresh budget each time.

2. loginThrottle()

loginThrottle() is the built-in preset for credential-entry routes. It combines a shared hard limit with a short progressive delay before the hard 429 response. By default it does not trust proxy IP headers and keys each caller on its TCP peer address, so one client cannot exhaust the budget for every other user. It falls back to a single shared bucket only on runtimes that expose no peer address. Pass a keyGenerator or opt in to trustProxyHeaders: true / trustedProxies only behind a trusted proxy. When proxy headers are trusted, the key is the rightmost X-Forwarded-For entry (the one your proxy appended), so rotating spoofed left entries cannot reset the budget. Multi-hop chains declare their length with trustedHops. Prefer trustedProxies when the origin can be reached without the proxy (see the autoBan note).

IPv6 clients are grouped by prefix (since 1.3.7). The ipv6Subnet option (default 64) masks IPv6 addresses to a /64, the block one subscriber normally holds, so an attacker cannot mint a fresh bucket per address. Different spellings of one address (::1 and 0:0::1, or 1.2.3.4 and ::ffff:1.2.3.4) collapse to one key. The option is ignored when you pass a keyGenerator.

Register loginThrottle() before your authentication hook. It then counts every rejected attempt, including guards that throw (for example a failed bearerAuth() check) rather than return a Response. Once the budget is exhausted the 429 replaces the auth error.

app.post(
  "/password-reset",
  {
    hooks: loginThrottle({
      windowMs: 15 * 60_000,
      max: 5,
      groupId: "auth-entry",
      delayAfter: 2,
      delayMs: 250,
      maxDelayMs: 2_000,
      ipv6Subnet: 56, // group IPv6 clients per /56 instead of /64
    }),
    responses: { 204: { description: "accepted" } },
  },
  async () => ({ status: 204 as const }),
);

3. rotateSession()

rotateSession() watches session privilege fields and calls session.regenerate() after the handler when those fields change. It skips itself when the handler already regenerated the session, so explicit login flows keep their exact behavior.

import { session, rotateSession } from "@daloyjs/core";

app.use(session({ secret: process.env.SESSION_SECRET! }));
app.use(rotateSession({ watch: ["userId", "roles", "tenantId"] }));

app.post(
  "/admin/promote",
  {
    responses: { 200: { description: "ok" } },
  },
  async ({ state }) => {
    state.session.set("roles", ["admin"]);
    return { status: 200 as const, body: { ok: true } };
  },
);

4. Upload MIME and magic-byte guards

fileField() already enforced maxBytes and MIME allowlists. Add magicBytes: true to derive known signatures from accept, or pass custom signatures for private formats. The OpenAPI generator emits x-magic-bytes alongside x-accept and x-max-bytes.

fileField({
  maxBytes: 1_000_000,
  accept: ["image/png", "image/jpeg"],
  magicBytes: true,
});

fileField({
  accept: ["application/x-daloy"],
  magicBytes: [
    { mime: "application/x-daloy", bytes: [0x44, 0x4c, 0x59] },
  ],
});

5. requirePayloadAuth

OpenAPI security scheme builders accept requirePayloadAuth: true for schemes such as webhook signatures that must authenticate the request body. A route using that scheme cannot set auth.payload: false. Daloy throws at route registration. The public OpenAPI document uses x-daloy-require-payload-auth rather than leaking a non-spec field.

const app = new App({
  openapi: {
    securitySchemes: {
      webhook: httpBearerScheme({ requirePayloadAuth: true }),
    },
  },
});

app.post(
  "/webhooks/provider",
  {
    auth: { scheme: "webhook" },
    responses: { 204: { description: "accepted" } },
  },
  async () => ({ status: 204 as const }),
);

6. WebSocket safe defaults

app.ws() now normalizes safe runtime defaults for Node and Bun: close on excessive outbound backpressure, a 1 MiB backpressure limit, compression off by default, a non-zero idle timeout, and a 1 MiB inbound payload cap. In production under secureDefaults, perMessageDeflate: true is refused. Daloy also refuses a maxPayloadLength larger than a route body schema's declared maximum when the schema exposes one.

app.ws("/events", {
  idleTimeout: 120,
  maxPayloadLength: 64 * 1024,
  closeOnBackpressureLimit: true,
  backpressureLimit: 1 * 1024 * 1024,
  perMessageDeflate: false,
  message(conn, data) {
    conn.send(data);
  },
});