rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

The edge stack#

Security middleware goes at the front of the app, in a deliberate order: headers on everything, CORS before any work, CSRF and rate limiting before the routers. All of it comes from @rhythmjs/security. App-level HTTP middleware reads ctx.request, so the app declares the HTTP context as its input — the one place an explicit generic is needed:

TypeScript
import type { RhythmHttpContext } from "@rhythmjs/router/context";
import { secureHeaders } from "@rhythmjs/security/secure-headers";
import { cors } from "@rhythmjs/security/cors";
import { csrf } from "@rhythmjs/security/csrf";
import { rateLimit } from "@rhythmjs/security/rate-limit";
import { error } from "@rhythmjs/router/response";

export const appModule = new Rhythm<{}, RhythmHttpContext>({ name: "app" })
  /* ...startup registrations... */
  .use(secureHeaders())                               // nosniff, COOP/CORP, HSTS, referrer policy
  .use(cors({ origin: ["https://app.example.com"] })) // exact-match allowlist, never "*" with credentials
  .use(csrf())                                        // origin-checks unsafe form posts
  .use(rateLimit({ limit: 100, windowMs: 60_000 }))
  .use(mount(appController))
  .use(mount(notesModule))
  .use((ctx) => {
    // mounted routers always continue, so answer only when nothing wrote a response
    if (ctx.response.status === 200 && ctx.response.body === null) error(ctx, 404);
  });

secureHeaders covers every response, including ones other middleware produced, and cors lives on the app rather than a router so a preflight OPTIONS request is answered even for a path that only has a GET route.

The last use is new and deliberate. toFetchHandler answers its plain 404 only when the response is completely untouched, headers included. Once secureHeaders or cors has set a header on every response, a request no router matched is no longer untouched and would come back as an empty 200. The guard sits after every mount and answers 404 when no router wrote a body. Keep it last whenever app-level middleware sets headers.

rateLimit identifies clients by request.ip, which Bun does not set, so assign it where you hold Bun's server — in main.ts:

TypeScript
const handler = toFetchHandler(appModule);

const server = Bun.serve({
  port,
  fetch(request, server) {
    Object.assign(request, { ip: server.requestIP(request)?.address });
    return handler(request, server);
  },
});

Who is calling#

Authentication is ordinary middleware, so you write it with the primitives you already know. The per-request question "who is this?" is a job for derive(): it resolves whatever credentials you use into ctx.user (or null) and types it for every step after it. First the placeholder service it calls:

TypeScript
// src/auth/auth.service.ts
export interface User {
  id: string;
  roles: string[];
}

export const authService = {
  async verify(token: string): Promise<User | null> {
    return token === process.env.API_TOKEN ? { id: "1", roles: ["admin"] } : null; // swap in your real check
  },
  async login(input: { email: string; password: string }): Promise<User | null> {
    return input.password === process.env.ADMIN_PASSWORD ? { id: input.email, roles: ["admin"] } : null; // likewise
  },
};
TypeScript
// src/auth/authenticate.ts
import { derive } from "@rhythmjs/rhythm";
import { authService, type User } from "./auth.service";

export const authenticate = derive(async (ctx: { request: Request }) => {
  const token = /^Bearer (.+)$/i.exec(ctx.request.headers.get("authorization") ?? "")?.[1]; // Authorization: Bearer <token>
  const user: User | null = token ? await authService.verify(token) : null; // null on a missing or bad token
  return { user };
});

authenticate only identifies; it never rejects. Anonymous requests carry ctx.user === null, and deciding what that means is the job of the guards below. Because it is a derive-style step it goes on the router whose routes need the user, with .use(authenticate). (A route accepts one such handler as its first handler, and validate takes that slot.)

Who may do what#

Authorization is two small guards, plain (ctx, next) middleware that answer without calling next() when the request is refused. Unauthenticated requests get 401, authenticated-but-forbidden get 403:

TypeScript
// src/auth/guards.ts
import type { Next } from "@rhythmjs/rhythm/types";
import type { RhythmHttpContext } from "@rhythmjs/router/context";
import type { User } from "./auth.service";
import { error } from "@rhythmjs/router/response";

type AuthedContext = RhythmHttpContext & { user: User | null };

export const requireUser = (ctx: AuthedContext, next: Next) => {
  if (!ctx.user) return error(ctx, 401, "Sign in first");
  return next();
};

export const requireRole = (role: string) => (ctx: AuthedContext, next: Next) => {
  if (!ctx.user) return error(ctx, 401, "Sign in first");
  if (!ctx.user.roles.includes(role)) return error(ctx, 403, "Forbidden");
  return next();
};

Compose them on the router: attach the user once, require it, and require a role on the routes that need one. Middleware on a router runs only for that router's routes, so nothing here touches /health or the docs:

TypeScript
// src/notes/notes.controller.ts
import { authenticate } from "../auth/authenticate";
import { requireRole, requireUser } from "../auth/guards";
import { json } from "@rhythmjs/router/response";

export const notesController = new RhythmRouter<NotesContext>({ name: "notes" })
  .use(filter())
  .use(intercept(notesResponseSchema))
  .use(authenticate)                      // ctx.user: User | null
  .use(requireUser)                       // 401 unless signed in
  .get("/api/notes", async (ctx) => {
    json(ctx, await ctx.notesService.list());
  })
  .post("/api/notes", validate("body", createNoteSchema), async (ctx) => {
    json(ctx, await ctx.notesService.create(ctx.valid.body), 201);
  })
  .delete("/api/notes/:id", requireRole("admin"), async (ctx) => {
    if (!(await ctx.notesService.remove(ctx.params.id))) throw new HttpError(404, "Note not found");
    ctx.response.status = 204;
  });

The module needs no change: notesModule mounts this controller, so the protection travels with the feature.

The guards are plain middleware, so they can sit anywhere in a handler list, even after validate. authenticate is the only derive-style step, which is why it lives on the router. To keep part of the API public, put the public routes on another router. A guard does not narrow ctx.user's type, which stays User | null downstream.

Sessions and cookies#

For cookie-based apps, @rhythmjs/http/session puts a typed session on the context, backed by a pluggable store — always HttpOnly and SameSite=Lax; set secure: true in production:

TypeScript
// src/auth/session.controller.ts
import { session } from "@rhythmjs/http/session";
import { filter, HttpError } from "@rhythmjs/middleware/filter";
import { validate } from "@rhythmjs/middleware/validate";
import { RhythmRouter } from "@rhythmjs/router";
import { z } from "zod";
import { authService } from "./auth.service";
import { json } from "@rhythmjs/router/response";

const loginSchema = z.object({ email: z.string(), password: z.string() });

export const sessionController = new RhythmRouter({ name: "session" })
  .use(filter())
  .use(session({ secure: true, maxAge: 60 * 60 * 24 }))
  .post("/login", validate("body", loginSchema), async (ctx) => {
    const user = await authService.login(ctx.valid.body); // your own check
    if (!user) throw new HttpError(401, "Invalid credentials");
    ctx.session.set("userId", user.id);
    json(ctx, { ok: true });
  })
  .post("/logout", (ctx) => {
    ctx.session.destroy();
    ctx.response.status = 204;
  });

Mount it on the app next to the notes module, before the final guard: .use(mount(sessionController)). authService has a login next to verify; both are placeholders for your real credential check.

The hardening guide covers the rest of the surface: per-route rate limits, header tuning, and the CSRF model's caveats for non-form clients.