Authentication
Session auth with @pracht/session: encrypted cookies, middleware gates, login and logout routes, and password hashing on every adapter.
On this page
This recipe adds password login: an encrypted session cookie, a middleware gate that sends anonymous visitors to /login, and login, logout, and signup endpoints.
1. Install
pnpm add @pracht/sessionnpm install @pracht/sessionyarn add @pracht/sessionbun add @pracht/sessionGenerate a secret into .env, and confirm .env* is gitignored:
echo "SESSION_SECRET=$(openssl rand -base64 32)" >> .envcreateSessionStorage() throws if any secret is shorter than 16 characters.
2. Session storage
Define one storage instance for the app. Read the secret from serverEnv so it stays out of the client bundle.
import { serverEnv } from "@pracht/core/env/server";
import { createSessionStorage, type SessionRequestContext, type SessionStorage } from "@pracht/session";
export interface AppSession extends Record<string, unknown> {
userId: string;
email: string;
name: string;
/** Flash message — consumed by the first read after it is set. */
notice: string;
}
export type SessionContext = SessionRequestContext<AppSession>;
let storage: SessionStorage<AppSession> | undefined;
export function sessions(): SessionStorage<AppSession> {
storage ??= createSessionStorage<AppSession>({
cookie: {
// The default name. The browser rejects a `__Host-` cookie unless it is
// Secure, `Path=/`, and host-only, so a sibling subdomain cannot plant one.
name: "__Host-session",
// Newest first: the first secret seals, every secret opens.
secrets: [serverEnv.SESSION_SECRET as string],
maxAge: 60 * 60 * 24 * 7,
},
});
return storage;
}Build the storage lazily inside a function: on Cloudflare Workers, env bindings exist only per request, so reading serverEnv at module load throws.
| Setting | Default |
|---|---|
name |
__Host-session |
maxAge |
One week, counted from the last write |
HttpOnly |
On; JavaScript cannot read the cookie |
SameSite |
Lax |
Path |
/ |
Secure |
Always on with a __Host- or __Secure- name; otherwise on except for plain http from localhost, *.localhost, 127.0.0.1, or [::1] |
| Encryption | AES-256-GCM, key derived from the secret with HKDF-SHA256 |
| Size | Over 4 KB throws |
__Host- and local development
The __Host- prefix forces Secure in development too, which Chrome 89+ and Firefox 75+ accept on http://localhost. If login seems to do nothing because your browser drops the cookie, use an unprefixed name in development or run dev over https. In production, drop the prefix only when the cookie must be shared across subdomains.
secure: false is for http development on a non-localhost hostname; it throws with a __Host- or __Secure- name, or with sameSite: "None".
3. Session middleware
Create two middleware files:
sessionMiddleware(storage)loads the session ontocontext.sessionand never blocks.requireSession(storage)loads it and gates. A page request without a user is redirected to the login page with?redirect=<route path>; an API request gets401with{"error":"unauthorized"}.
import type { MiddlewareFn } from "@pracht/core";
import { sessionMiddleware } from "@pracht/session";
import { sessions } from "../server/session.ts";
let loader: MiddlewareFn | undefined;
export const middleware: MiddlewareFn = (args, next) => {
loader ??= sessionMiddleware(sessions());
return loader(args, next);
};import type { MiddlewareFn } from "@pracht/core";
import { requireSession } from "@pracht/session";
import { sessions } from "../server/session.ts";
let gate: MiddlewareFn | undefined;
export const middleware: MiddlewareFn = (args, next) => {
gate ??= requireSession(sessions(), { loginPath: "/login" });
return gate(args, next);
};Both commit the session after next(), so a loader can call context.session.set(...) and the cookie lands on its response; a request that changes nothing gets no Set-Cookie. requireSession treats a session with a userId as authenticated; pass isAuthenticated(session) to change that. See Middleware for the contract.
Type context.session once for every loader, API route, and capability:
import type { SessionRequestContext } from "@pracht/session";
import type { AppSession } from "./server/session.ts";
declare module "@pracht/core" {
interface Register {
context: SessionRequestContext<AppSession>;
}
}4. Password hashing
Hash with hashPassword() and check with verifyPassword(). Both use PBKDF2-HMAC-SHA256 through WebCrypto, so they run on every adapter.
import { hashPassword, verifyPassword } from "@pracht/session";
export interface User {
id: string;
email: string;
name: string;
}
export async function createUser(email: string, name: string, password: string) {
const passwordHash = await hashPassword(password);
return await db.users.insert({ email, name, passwordHash });
}
export async function verifyCredentials(email: string, password: string): Promise<User | null> {
const row = await db.users.findByEmail(email.trim().toLowerCase());
if (!row) return null;
return (await verifyPassword(password, row.passwordHash)) ? row : null;
}The stored hash records its own parameters, so raising the iteration count later keeps existing hashes valid.
- Never store a plain
SHA-256(password). - Prefer Argon2id or scrypt (native module, WASM build, or an identity provider) where the runtime allows it.
- On Cloudflare Workers, PBKDF2 spends metered CPU time. If a login exceeds your plan's CPU limit, pass a lower
hashPassword(password, { iterations })or hash off the worker.
5. Login and logout
The login page renders the form, and an API route validates and issues the session. Both read a redirect target from user input, so both pass it through one same-origin check:
// The redirect target is user input. Parse it before trusting it: URL parsing
// turns `\` into `/` and drops tabs, so `/\evil.com` starts with `/` but
// lands on another origin.
export function safeRedirectPath(value: unknown, base: URL, fallback: string): string {
if (typeof value !== "string" || !value.startsWith("/")) return fallback;
try {
const target = new URL(value, base);
return target.origin === base.origin
? `${target.pathname}${target.search}${target.hash}`
: fallback;
} catch {
return fallback;
}
}import { redirect, type ApiRouteArgs } from "@pracht/core";
import { safeRedirectPath } from "../../server/redirects.ts";
import { sessions } from "../../server/session.ts";
import { verifyCredentials } from "../../server/users.ts";
export async function POST({ request, url }: ApiRouteArgs) {
const form = await request.formData();
const email = String(form.get("email") ?? "");
const password = String(form.get("password") ?? "");
const target = safeRedirectPath(form.get("redirect"), url, "/dashboard");
const user = await verifyCredentials(email, password);
if (!user) {
// `<Form>` acts on 3xx responses; a 401 JSON body leaves the page looking
// like nothing happened.
return redirect(`/login?error=1&redirect=${encodeURIComponent(target)}`, { request });
}
const storage = sessions();
const session = await storage.getSession(request);
// Rotate the session id at the moment of privilege change, before writing
// the user onto it. See "Session fixation" below.
await session.regenerate();
session.set("userId", user.id);
session.set("email", user.email);
session.set("name", user.name);
session.flash("notice", `Welcome back, ${user.name}.`);
return storage.commit(session, redirect(target, { request }));
}storage.commit(session, response) appends the Set-Cookie, so cookies set elsewhere on the response survive.
import { Form, type LoaderArgs, type RouteComponentProps } from "@pracht/core";
import { safeRedirectPath } from "../server/redirects.ts";
export async function loader({ url }: LoaderArgs) {
return {
error: url.searchParams.get("error") === "1",
// Reflecting an unvalidated `?redirect=` back into the form hands an
// attacker an open redirect through a legitimate-looking login link.
redirect: safeRedirectPath(url.searchParams.get("redirect"), url, "/dashboard"),
};
}
export function head() {
return { title: "Log in" };
}
export function Component({ data }: RouteComponentProps<typeof loader>) {
return (
<section class="login">
<h1>Log in</h1>
{data.error && <p role="alert">Invalid email or password.</p>}
<Form method="post" action="/api/auth/login">
<input type="hidden" name="redirect" value={data.redirect} />
<label>
Email
<input type="email" name="email" required />
</label>
<label>
Password
<input type="password" name="password" required />
</label>
<button type="submit">Log in</button>
</Form>
</section>
);
}Submitting valid credentials sets the session cookie and redirects to the redirect target. Wrong credentials land back on /login?error=1 with the alert shown.
import { redirect, type ApiRouteArgs } from "@pracht/core";
import { sessions } from "../../server/session.ts";
export async function POST({ request }: ApiRouteArgs) {
const storage = sessions();
const session = await storage.getSession(request);
// Drops the store record (when one is configured) and puts an
// immediately-expiring cookie on the response.
return storage.destroy(session, redirect("/", { request }));
}Log out with a POST form; a GET logout link is a one-click CSRF, and link scanners prefetch it.
import { Form } from "@pracht/core";
<Form method="post" action="/api/auth/logout">
<button type="submit">Log out</button>
</Form>Signup has the same shape as login: validate, redirect to /signup?error=… on failure, otherwise createUser() and issue the session.
Session fixation
Call session.regenerate() on every privilege change: after credentials verify, after completing 2FA, after assuming an admin role. It issues a new id, keeps the data, and drops the old store record. With a store, this stops an attacker who planted a known session id from inheriting the login; cookie-only sessions are not exposed, but the call keeps the login path correct if you add a store later.
6. Read the user in loaders
Behind the middleware, loaders read context.session:
import type { LoaderArgs, RouteComponentProps } from "@pracht/core";
import type { SessionContext } from "../server/session.ts";
export async function loader({ context }: LoaderArgs<SessionContext>) {
const userId = context.session.get("userId") as string;
return {
// `get()` on a flashed key is the read that consumes it: the message
// shows once after the redirect and is gone from the next request.
notice: context.session.get("notice") ?? null,
projects: await db.projects.findMany({ userId }),
user: context.session.get("name") ?? "",
};
}
export function Component({ data }: RouteComponentProps<typeof loader>) {
return (
<div>
{data.notice && <p role="status">{data.notice}</p>}
<h1>{data.user}</h1>
<ul>
{data.projects.map((p) => (
<li key={p.id}>{p.name}</li>
))}
</ul>
</div>
);
}Loader data is serialized to the client. Return only what the component renders, never the whole session.
7. Wire it up
Put public routes in one group and protected routes in a group carrying the gate:
import { defineApp, group, route } from "@pracht/core";
export const app = defineApp({
shells: {
public: "./shells/public.tsx",
app: "./shells/app.tsx",
},
middleware: {
auth: "./middleware/auth.ts",
session: "./middleware/session.ts",
},
// Every API route can see the session; only the gated group is gated.
// Individual handlers still check what they need.
api: { middleware: ["session"] },
routes: [
// Public — no gate.
group({ shell: "public" }, [
route("/", "./routes/home.tsx", { render: "ssg" }),
route("/login", "./routes/login.tsx", { render: "ssr" }),
route("/signup", "./routes/signup.tsx", { render: "ssr" }),
]),
// Protected — the gate redirects anonymous visitors to /login.
group({ shell: "app", middleware: ["auth"] }, [
route("/dashboard", "./routes/dashboard.tsx", { render: "ssr" }),
route("/settings", "./routes/settings.tsx", { render: "ssr" }),
]),
],
});Open /dashboard in a fresh browser: you are redirected to /login?redirect=%2Fdashboard, and after logging in you land back on /dashboard with the welcome notice.
Use render: "ssr" for anything that reads the session; per-visitor output cannot be prerendered. Run /audit-auth to confirm every route you expect to be protected resolves the gate.
Server-side sessions
Pass a store and the cookie carries only a sealed session id instead of the data. Use one when the session outgrows 4 KB, when logout must end the session in every browser, or when the data must stay on the server.
import { createSessionStorage } from "@pracht/session";
import { serverEnv } from "@pracht/core/env/server";
export function sessions() {
return createSessionStorage<AppSession>({
cookie: { name: "__Host-session", secrets: [serverEnv.SESSION_SECRET as string] },
store: {
async get(id) {
return await KV.get(`session:${id}`, "json");
},
async set(id, data, expiresAt) {
await KV.put(`session:${id}`, JSON.stringify(data), {
// Cloudflare KV takes an absolute expiration in seconds, at least 60
// seconds out, and then reaps the record without a cron job. The
// sealed cookie still ends the session at `expiresAt`.
expiration: Math.max(Math.floor(expiresAt / 1000), Math.ceil(Date.now() / 1000) + 60),
});
},
async delete(id) {
await KV.delete(`session:${id}`);
},
},
});
}KV is a Workers binding, so build the storage inside the request (see Full-stack Cloudflare). Any backend with get, set(id, data, expiresAt), and delete works: D1, Durable Objects, Redis, Postgres. createMemorySessionStore() is for tests and single-process dev servers.
Session expiry
maxAge counts from the last write, and the middleware writes only when the session changed, so a user who browses longer than maxAge without changing anything is logged out. Pass rolling to make maxAge an idle timeout:
import { serverEnv } from "@pracht/core/env/server";
import { createSessionStorage } from "@pracht/session";
createSessionStorage<AppSession>({
cookie: { name: "__Host-session", secrets: [serverEnv.SESSION_SECRET as string], maxAge: 60 * 30 },
// Every request under sessionMiddleware() re-seals the cookie, so the
// 30-minute window is measured from the last request rather than the last
// write.
rolling: true,
});Every response then carries a Set-Cookie, and with a store every request writes to it. Anonymous visitors still get no cookie.
Add absoluteMaxAge (seconds) to cap a rolling session's total lifetime: absoluteMaxAge: 60 * 60 * 12 signs everyone out 12 hours after sign-in, however active. The cap counts from the first commit or the last regenerate().
storage.destroySession(session) ends a session immediately; with a store, in every browser holding the cookie.
Rotate the secret
Put the new secret first and keep the old one until cookies sealed with it have expired: maxAge after you deploy the new secret, or longer if you pass a larger maxAge to commit().
import { serverEnv } from "@pracht/core/env/server";
const secrets = [
serverEnv.SESSION_SECRET_V2 as string,
serverEnv.SESSION_SECRET as string,
];New cookies are sealed with the first secret, every listed secret opens existing ones, and a cookie is re-sealed with the new secret the next time its session is written. Removing the old secret too early logs out everyone still holding a cookie sealed with it.
CSRF protection
pracht rejects cross-site mutations by default. A POST, PUT, PATCH, or DELETE to an API route gets 403 Cross-origin request blocked unless the browser marks it same-origin; same-site requests are rejected too. Requests without browser provenance headers (curl, server-to-server, tests) pass. The check runs before API middleware and is controlled by ApiConfig.requireSameOrigin, default true.
Keep the default SameSite=Lax cookie alongside it, or use sameSite: "Strict" if links from other sites need not arrive signed in.
Allow trusted cross-origin callers
To accept mutations from another origin you trust (an admin app on another domain), replace the built-in check with a middleware that carries an allowlist:
import type { MiddlewareFn } from "@pracht/core";
const UNSAFE = new Set(["POST", "PUT", "PATCH", "DELETE"]);
const ALLOWED = new Set<string>([
// add trusted cross-origin callers here (e.g. "https://admin.example.com")
]);
export const middleware: MiddlewareFn = ({ request, url }, next) => {
// WebSocket upgrades are GETs that carry the user's cookies, so they are
// checked too: `requireSameOrigin: false` also turns off the built-in
// upgrade check.
const upgrade = request.headers.has("upgrade");
if (!UNSAFE.has(request.method) && !upgrade) return next();
const origin = request.headers.get("origin");
if (origin === null) {
// No Origin header: either a non-browser client or an attacker dodging
// the check. Sec-Fetch-Site tells us when the browser itself marked the
// request as same-origin or user-initiated.
const site = request.headers.get("sec-fetch-site");
if (site === "same-origin" || site === "none") return next();
return new Response("Forbidden: missing Origin", { status: 403 });
}
if (origin === url.origin) return next();
if (ALLOWED.has(origin)) return next();
return new Response(`Forbidden: origin ${origin} not allowed`, { status: 403 });
};Wire it to the API and turn off the built-in check, which would reject the allowlisted origins first:
import { defineApp } from "@pracht/core";
defineApp({
middleware: {
auth: "./middleware/auth.ts",
originCheck: "./middleware/origin-check.ts",
},
api: { middleware: ["originCheck"], requireSameOrigin: false },
routes: [],
});This checks headers and issues no tokens; add synchronizer tokens if you need them, for example with sameSite: "None" for embedding. Run /audit-csrf to check the posture end to end.
Out of scope
@pracht/session is session storage, not an auth framework. Build these yourself:
- OAuth / OIDC ("Sign in with GitHub"). Handle the callback in an API route, verify it with a protocol library (
arctic,openid-client, or the provider's SDK), then put the user id in the session. - Multi-factor auth. Keep an
mfaVerifiedflag in the session and gate on it withrequireSession(storage, { isAuthenticated }). - Password reset and email verification. Both need single-use, expiring, out-of-band tokens and an email sender.
- Rate limiting. Without it, a login endpoint is an online password oracle. Use the platform's (Cloudflare Rate Limiting, Vercel Firewall) or a counter in your store.
- Authorization. Sessions say who the user is. Enforce roles, permissions, and record ownership in loaders and handlers, not only in the UI.