Safe error handling and logging
Design error handling that fails closed, tells clients only what they need, gives operators a correlation id and full context, and keeps logs free of secrets and injected lines.
01Understand the problem
- Make security decisions fail closed when something throws
- Split every error into a public part for the client and a private part for the logs
- Prevent log injection and keep secrets out of log lines
- Avoid enumeration through different error messages or status codes
What they probe: what happens when the policy service times out, what the client sees for an unexpected exception, how support finds the matching log line, and what must never be logged. Where candidates slip: catch { return true } in an access check, stack traces in production responses, User not found versus Wrong password, and logging the whole request including the Authorization header.
Error paths are where security code is least tested and most often wrong. A check that returns true from its catch block turns every outage of the policy service into an authorisation bypass. A default framework error page leaks the stack, library versions and SQL fragments. A log line built with string concatenation lets an attacker forge entries by putting a newline in their username.
- Security decisions (authentication, authorisation, signature checks) deny on any exception.
- Clients get a status code, a stable error code and a correlation id; never a stack trace, query or internal hostname.
- Logs get the correlation id, the error class, the cause chain and safe context; never passwords, tokens or full card numbers.
- Logs are structured (JSON), so user data cannot break a record or forge a new one.
- Authentication failures look the same whether the account exists or not.
| Log it | Never log it |
|---|---|
| Correlation id, route, status, latency | Passwords, even wrong ones (often a real password typed in the wrong field) |
| User id, tenant id, key id (not the key) | Session ids, bearer tokens, API keys, cookies |
| Error class, message from your own code, cause chain | Full card numbers (PCI DSS) or secrets embedded in URLs |
| Decision and reason for security events (denied: missing role) | Full request bodies by default; health or special-category data |
02Interfaces first
export type PublicCode = "bad_request" | "unauthenticated" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal";
/** An error your code raised on purpose. The message is for logs; publicMessage is safe to show. */
export class AppError extends Error {
constructor(
readonly status: number,
readonly publicCode: PublicCode,
readonly publicMessage: string,
message: string,
options?: { cause?: unknown },
) {
super(message, options);
this.name = "AppError";
}
}
export interface ErrorBody {
error: { code: PublicCode; message: string; correlationId: string };
}
export interface Log {
error(msg: string, fields: Record<string, unknown>): void;
warn(msg: string, fields: Record<string, unknown>): void;
info(msg: string, fields: Record<string, unknown>): void;
}Wrapping a low-level error (new AppError(503, ..., { cause: dbErr })) keeps the database error for the operator while the client only sees internal. Standard Error supports cause since ES2022, and most loggers print the chain.
03Fail closed, respond generically, log precisely
// Wrong: any exception (timeout, bad JSON, null) grants access.
async function canEditBad(userId: string, docId: string): Promise<boolean> {
try { return await policy.check(userId, "edit", docId); }
catch { return true; } // "don't block users during an outage"
}
// Right: the decision is false unless the check positively says true.
async function canEdit(userId: string, docId: string, log: Log): Promise<boolean> {
try {
const decision = await policy.check(userId, "edit", docId);
return decision === true; // undefined, "true" or 1 are not true
} catch (err) {
log.error("policy check failed, denying", { userId, docId, err });
return false;
}
}import { randomUUID } from "node:crypto";
import type { Request, Response, NextFunction } from "express";
/** Register last. Express recognises error middleware by its four parameters. */
export function errorHandler(log: Log) {
return (err: unknown, req: Request, res: Response, _next: NextFunction): void => {
const correlationId = (req as { id?: string }).id ?? randomUUID();
const known = err instanceof AppError ? err : undefined;
const status = known?.status ?? 500;
const fields = {
correlationId,
method: req.method,
route: req.route?.path ?? "unmatched", // the pattern, not the raw URL with its query string
status,
err, // the logger serialises name, message, stack and cause
};
if (status >= 500) log.error("request failed", fields); else log.warn("request rejected", fields);
const body: ErrorBody = {
error: {
code: known?.publicCode ?? "internal",
message: known?.publicMessage ?? "Something went wrong. Quote the correlation id if you contact support.",
correlationId,
},
};
if (!res.headersSent) res.status(status).json(body);
};
}Login failures deserve their own care. The response must be identical for an unknown user and a wrong password, and so must the timing, which means running a password hash even when no user exists. The log, by contrast, records the precise reason for the security team.
import json, logging, sys
class JsonFormatter(logging.Formatter):
def format(self, record: logging.LogRecord) -> str:
doc = {"ts": self.formatTime(record), "level": record.levelname, "msg": record.getMessage()}
doc.update(getattr(record, "fields", {}))
return json.dumps(doc, default=str) # newlines inside values become \n, so one event stays one line
log = logging.getLogger("auth")
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(JsonFormatter())
log.addHandler(handler)
def login(username: str, password: str) -> dict:
user = users.find(username)
ok = hasher.verify(user.hash if user else DUMMY_HASH, password) # same work whether or not the user exists
if not (user and ok):
log.warning("login failed", extra={"fields": {"reason": "no_user" if not user else "bad_password", "username": username}})
return {"status": 401, "error": "Invalid username or password."}
return {"status": 200}04Traps and tests
| Trap | What leaks or breaks | Fix |
|---|---|---|
| Framework debug mode in production | Stack traces, source snippets, environment variables | Set NODE_ENV=production or DEBUG=False; test that a thrown error returns the generic body |
| String-built log lines | Username bob\nINFO login ok user=admin forges a record | JSON logs, or escape CR and LF |
| Logging the raw URL | Reset tokens and API keys in query strings | Log the route pattern; redact sensitive query parameters |
| Different status codes | 403 for an existing private document, 404 for a missing one | Return 404 for both when existence itself is sensitive |
| Swallowed errors | catch {} hides an attack or a broken control | Catch narrowly, log, and rethrow or deny |
| Errors in the error handler | A logging failure crashes the process or returns a raw 500 page | Keep the handler simple and guard the logger call |
Anything you log is copied to log pipelines, vendors and backups, often with broader access than the production database. Treat a secret in a log as a leaked secret: rotate it, and fix the log statement.
import { describe, it, expect } from "vitest";
import express from "express";
import request from "supertest";
function app(log: Log) {
const a = express();
a.get("/boom", () => { throw new Error("db password=hunter2 at 10.0.3.7"); });
a.get("/nope", () => { throw new AppError(403, "forbidden", "You cannot do that.", "missing role editor"); });
a.use(errorHandler(log));
return a;
}
describe("errorHandler", () => {
const lines: Record<string, unknown>[] = [];
const log: Log = { error: (_m, f) => lines.push(f), warn: (_m, f) => lines.push(f), info: () => {} };
it("hides internal details and returns a correlation id", async () => {
const res = await request(app(log)).get("/boom");
expect(res.status).toBe(500);
expect(JSON.stringify(res.body)).not.toMatch(/hunter2|10\.0\.3\.7|at /);
expect(res.body.error.correlationId).toMatch(/^[0-9a-f-]{36}$/);
});
it("passes through deliberate public messages", async () => {
const res = await request(app(log)).get("/nope");
expect(res.body.error).toMatchObject({ code: "forbidden", message: "You cannot do that." });
});
it("denies when the policy service throws", async () => {
policy.check = async () => { throw new Error("timeout"); };
expect(await canEdit("u1", "d1", log)).toBe(false);
});
});05Extensions, follow-ups, how to say it
- Security events: send authentication, authorisation and admin events to a separate stream with longer retention for detection and audit.
- Redaction as a library: a logger that redacts sensitive keys and token patterns by default beats reviewers spotting every call site (covered later in this track).
- Fail open on purpose: some non-security features (recommendations, analytics) should fail open; write the choice down per dependency instead of letting it fall out of a catch block.
- Error budgets: alert on spikes of 5xx and of denied decisions; a sudden rise in either is a signal.
Q1The policy service is down. Should the app fail open to stay available?+
Not for authorisation. Failing open hands access to whoever notices the outage. Keep availability with a local cache of recent decisions or a degraded read-only mode, and page someone.
Q2Why not show the exception message to the client if it is short?+
Messages from libraries contain hostnames, SQL, file paths and sometimes secrets. Only messages your code wrote for the client, such as AppError.publicMessage, are safe.
Q3How does support match a user report to a log line?+
The correlation id in the error body is also in every log line for that request, ideally propagated from the edge in a request id header so it spans services.
"Security checks return deny unless they get a positive answer, and every exception path logs and denies. One error handler at the edge maps known errors to a status, a stable code and a safe message, and everything else to a generic 500, always with a correlation id. Logs are structured JSON with the cause chain and an allow-list of fields, so no tokens, passwords or raw URLs. Login failures are identical in message, status and timing."
An access check is written as `try { return await policy.allows(u, r) } catch { return true }`. The policy service starts timing out. What happens?