Pass the browser's address to the mail server, and trust IPv4 proxies on a dual-stack socket #115

Merged
jcoffey-dev merged 2 commits from feat/forward-client-ip into main 2026-11-19 03:00:29 +00:00
12 changed files with 156 additions and 19 deletions

No files matched your search

+25
View File
@@ -65,6 +65,31 @@ trailing newline is dropped. The webmail won't start if both forms are set, or
if the file can't be read or is empty. The error names the variable and the
file, never the secret.
### Several replicas
The webmail's own limits count per replica: `LOGIN_RATE_LIMIT` on password
sign-ins (memory mode only), twenty times that on starting and finishing a
sign-in through the server, `API_RATE_LIMIT` per session, and the limit on
password changes. With several replicas behind a load balancer, a client can
get up to that many times each. They are a first line, nothing more.
The limits that hold across replicas are the mail server's. With
`SESSION_BACKEND=cookie` people type their password on the server's own
page, never the webmail's. The server counts failed sign-ins per address and
per account name across all of its nodes, and bans an address after too many
(inbuxa: 100 a day by default). It also limits requests that aren't signed in
yet, including the first use of each new token, per address.
For those to count people rather than the webmail, the webmail tells the
server who each request is for: it sends `X-Forwarded-For` with the client
address it worked out (with `TRUSTED_PROXIES`), replacing any the browser
sent. The server has to believe it, from the webmail and from your ingress.
On inbuxa that means both connect from trusted proxies (private addresses by
default, or `INBUXA_HTTP_TRUSTED_PROXIES`) and `INBUXA_HTTP_USE_FORWARDED=true`
is set, or "Use X-Forwarded-For" is on in the console. The Helm chart does
this. Without it, the server sees all of a replica's users as one address,
and enough wrong passwords between them ban it for everyone.
### Read-only root filesystem
The image runs with a read-only root. The only thing it writes is
+2 -1
View File
@@ -1,6 +1,7 @@
import { config } from "./config.js";
import { absoluteUpstream, UpstreamError, type UpstreamSession } from "./upstream.js";
import { generateSecret, otpauthUrl, parseOtpauthUrl, verifyTotp } from "./totp.js";
import { upstreamFetch } from "./clientcontext.js";
/**
* Self-service credential management, over Stalwart's JMAP registry:
@@ -65,7 +66,7 @@ function accountId(ctx: Ctx): string {
type Invocation = [string, Record<string, unknown>, string];
async function jmap(ctx: Ctx, methodCalls: Invocation[]): Promise<{ methodResponses?: [string, unknown, string][] }> {
const res = await fetch(absoluteUpstream(ctx.session.apiUrl, ctx.session.baseUrl), {
const res = await upstreamFetch(absoluteUpstream(ctx.session.apiUrl, ctx.session.baseUrl), {
method: "POST",
headers: { authorization: ctx.authorization, "content-type": "application/json", accept: "application/json" },
body: JSON.stringify({ using: [JMAP_CORE, STALWART_CAP], methodCalls }),
+9 -6
View File
@@ -49,6 +49,7 @@ import { icsProxyHandler } from "./icsproxy.js";
import { staticHandler } from "./static.js";
import { mailNode, webmailNode } from "./nodes.js";
import { ADD_REFUSED, MAX_ACCOUNTS, mayAddAccounts, parseOthers, serializeOthers } from "./accounts.js";
import { upstreamFetch, withClientIp } from "./clientcontext.js";
type Env = { Variables: { session: LiveSession } };
@@ -429,7 +430,7 @@ async function inboxUnread(session: LiveSession): Promise<number | null> {
const upstream = await getUpstreamSession(session.id, session.authorization, upstreamFor(session.username));
const accountId = upstream.primaryAccounts?.["urn:ietf:params:jmap:mail"];
if (!accountId) return null;
const res = await fetch(absoluteUpstream(upstream.apiUrl, upstream.baseUrl), {
const res = await upstreamFetch(absoluteUpstream(upstream.apiUrl, upstream.baseUrl), {
method: "POST",
headers: { authorization: session.authorization, "content-type": "application/json", accept: "application/json" },
body: JSON.stringify({
@@ -518,6 +519,8 @@ function upstreamFailure(c: Context, err: unknown) {
*/
export function createApp(basePath = config.basePath): Hono<Env> {
const app = new Hono<Env>();
// The browser's address, for the mail server (clientcontext.ts)
app.use("*", (c, next) => withClientIp(clientIp(c), next));
app.use("*", securityHeaders);
app.use("*", compressResponses(basePath));
@@ -920,7 +923,7 @@ export function createApp(basePath = config.basePath): Hono<Env> {
if (!session) return c.json({ error: "unauthenticated" }, 401);
try {
const upstream = await getUpstreamSession(session.id, session.authorization, upstreamFor(session.username));
const res = await fetch(absoluteUpstream(upstream.apiUrl, upstream.baseUrl), {
const res = await upstreamFetch(absoluteUpstream(upstream.apiUrl, upstream.baseUrl), {
method: "POST",
headers: { authorization: session.authorization, "content-type": "application/json", accept: "application/json" },
body: JSON.stringify({ using, methodCalls: calls }),
@@ -1227,7 +1230,7 @@ export function createApp(basePath = config.basePath): Hono<Env> {
}
try {
const upstream = await getUpstreamSession(session.id, session.authorization, upstreamFor(session.username));
const res = await fetch(absoluteUpstream(upstream.apiUrl, upstream.baseUrl), {
const res = await upstreamFetch(absoluteUpstream(upstream.apiUrl, upstream.baseUrl), {
method: "POST",
headers: {
authorization: session.authorization,
@@ -1286,7 +1289,7 @@ export function createApp(basePath = config.basePath): Hono<Env> {
try {
const upstream = await getUpstreamSession(session.id, session.authorization, upstreamFor(session.username));
const url = absoluteUpstream(expandTemplate(upstream.uploadUrl, { accountId }), upstream.baseUrl);
const res = await fetch(url, {
const res = await upstreamFetch(url, {
method: "POST",
headers: {
authorization: session.authorization,
@@ -1315,7 +1318,7 @@ export function createApp(basePath = config.basePath): Hono<Env> {
// A PDF viewer or a video element asks for pieces; pass that on. A server
// that ignores it answers with the whole file, as it did before.
const range = c.req.header("range");
const res = await fetch(url, {
const res = await upstreamFetch(url, {
// Ask for the bytes as they are. undici would otherwise negotiate gzip
// on our behalf and hand back a decompressed body whose content-length
// header still describes the compressed one -- see forwardedContentLength.
@@ -1398,7 +1401,7 @@ export function createApp(basePath = config.basePath): Hono<Env> {
if (config.rawPushRelay) return relayPushRaw(c, url, session.authorization, session.username);
const controller = new AbortController();
c.req.raw.signal.addEventListener("abort", () => controller.abort());
const upstreamRes = fetch(url, {
const upstreamRes = upstreamFetch(url, {
headers: { authorization: session.authorization, accept: "text/event-stream" },
signal: controller.signal,
});
+54
View File
@@ -0,0 +1,54 @@
import { test } from "node:test";
import assert from "node:assert/strict";
import { createServer, type IncomingHttpHeaders } from "node:http";
import type { AddressInfo } from "node:net";
/** A stand-in mail server that records the headers of every request. */
const seen: IncomingHttpHeaders[] = [];
const upstream = createServer((req, res) => {
seen.push(req.headers);
res.writeHead(404);
res.end();
});
await new Promise<void>((resolve) => upstream.listen(0, "127.0.0.1", resolve));
const base = `http://127.0.0.1:${(upstream.address() as AddressInfo).port}`;
process.env.MAIL_SERVER_URL = base;
process.env.APP_SECRET = "test-secret-for-client-context";
// The webmail believes X-Forwarded-For from loopback, as from an ingress
process.env.TRUSTED_PROXIES = "127.0.0.1/32,::1/128";
const { upstreamFetch, withClientIp } = await import("./clientcontext.js");
const { createApp } = await import("./app.js");
const { clearLogoCache } = await import("./logo.js");
test.after(() => upstream.close());
test("a request to the mail server carries the browser's address, replacing what it sent", async () => {
await withClientIp("203.0.113.7", () => upstreamFetch(`${base}/x`, { headers: { "x-forwarded-for": "198.51.100.1" } }));
assert.equal(seen.at(-1)!["x-forwarded-for"], "203.0.113.7");
});
test("outside a request, or with no usable address, nothing is added", async () => {
await upstreamFetch(`${base}/x`);
assert.equal(seen.at(-1)!["x-forwarded-for"], undefined);
await withClientIp("unknown", () => upstreamFetch(`${base}/x`));
assert.equal(seen.at(-1)!["x-forwarded-for"], undefined);
});
test("the app passes on the address it resolved for the request", async () => {
const { serve } = await import("@hono/node-server");
const server = serve({ fetch: createApp().fetch, port: 0, hostname: "127.0.0.1" });
await new Promise<void>((resolve) => server.once("listening", () => resolve()));
try {
clearLogoCache();
const port = (server.address() as AddressInfo).port;
// As through an ingress: the browser's spoof first, the ingress's view last
await fetch(`http://127.0.0.1:${port}/api/logo?domain=example.org`, {
headers: { "x-forwarded-for": "198.51.100.1, 203.0.113.9", "sec-fetch-dest": "image" },
});
const logo = seen.findLast((h) => h["x-forwarded-for"] !== undefined);
assert.equal(logo?.["x-forwarded-for"], "203.0.113.9");
} finally {
server.close();
}
});
+36
View File
@@ -0,0 +1,36 @@
import { AsyncLocalStorage } from "node:async_hooks";
import { isIP } from "node:net";
/*
* inbuxa K-W3: the browser's address, passed on to the mail server.
*
* Every request the webmail makes for its users comes from the webmail's own
* address. Without this, the server's limits and bans for failed sign-ins and
* anonymous requests count all of a replica's users as one client: a hundred
* new tokens a minute, or a hundred wrong passwords in a day, would lock
* everyone on that replica out. With it, each person counts as themselves --
* on a server that believes the header from the webmail (inbuxa: trusted
* proxies and INBUXA_HTTP_USE_FORWARDED, or "Use X-Forwarded-For" on).
*
* Only requests to the mail server carry it. Fetches for remote images and
* calendars go through imageproxy.ts and never do.
*/
const clientAddress = new AsyncLocalStorage<string>();
/** Runs `fn` with `ip` as the address the mail server is told about. */
export function withClientIp<T>(ip: string, fn: () => T): T {
return clientAddress.run(ip, fn);
}
/**
* fetch(), to the mail server: X-Forwarded-For set to the client the webmail
* resolved (clientip.ts), replacing anything the browser sent. Outside a
* request -- push, a background refresh -- no header is added.
*/
export function upstreamFetch(input: string | URL, init: RequestInit = {}): Promise<Response> {
const ip = clientAddress.getStore();
if (!ip || !isIP(ip)) return fetch(input, init);
const headers = new Headers(init.headers);
headers.set("x-forwarded-for", ip);
return fetch(input, { ...init, headers });
}
+8
View File
@@ -92,3 +92,11 @@ test("an explicit trusted list replaces the defaults", () => {
test("a chain of nothing but our own proxies still yields an address", () => {
assert.equal(resolveClientIp("127.0.0.1", { forwardedFor: "10.0.0.2, 10.0.0.3" }, cfg), "10.0.0.2");
});
// The image listens on ::, where Node reports an IPv4 peer as ::ffff:a.b.c.d
test("a proxy reaching us over IPv4 on a dual-stack socket is still trusted", () => {
assert.equal(resolveClientIp("::ffff:10.244.1.5", { forwardedFor: "203.0.113.7" }, cfg), "203.0.113.7");
assert.equal(resolveClientIp("::ffff:127.0.0.1", { forwardedFor: "203.0.113.7" }, cfg), "203.0.113.7");
// ...and an untrusted one is named in its plain form
assert.equal(resolveClientIp("::ffff:198.51.100.4", { forwardedFor: "203.0.113.7" }, cfg), "198.51.100.4");
});
+6 -1
View File
@@ -81,7 +81,12 @@ export interface ForwardHeaders {
* which is the only part nobody downstream can forge.
*/
export function resolveClientIp(peer: string, headers: ForwardHeaders, cfg: TrustConfig): string {
if (!cfg.trustProxy || !peer || peer === "unknown") return peer || "unknown";
if (!peer || peer === "unknown") return "unknown";
// Listening on :: (the image does), Node reports an IPv4 peer as
// ::ffff:10.0.0.5, which no IPv4 range matches: every IPv4 proxy looked
// untrusted and became "the client" for all of its users.
peer = peer.replace(/^::ffff:(?=\d+\.\d+\.\d+\.\d+$)/i, "");
if (!cfg.trustProxy) return peer;
// A peer we do not run is not allowed to tell us who its client is.
if (!isTrustedProxy(peer, cfg)) return peer;
const chain = (headers.forwardedFor ?? "")
+2 -1
View File
@@ -29,6 +29,7 @@
import type { Context } from "hono";
import { config } from "./config.js";
import { upstreamFor } from "./upstream.js";
import { upstreamFetch } from "./clientcontext.js";
/** How long an answer is kept, here and in the browser. */
const TTL_MS = 5 * 60_000;
@@ -57,7 +58,7 @@ async function ask(base: string, domain: string, dark: boolean): Promise<Answer>
if (dark) params.set("theme", "dark");
const query = params.toString();
try {
const res = await fetch(`${base}/logo${query ? `?${query}` : ""}`, {
const res = await upstreamFetch(`${base}/logo${query ? `?${query}` : ""}`, {
// The server redirects to a URL logo only for an image load
headers: { "sec-fetch-dest": "image", accept: "image/*" },
redirect: "manual",
+5 -4
View File
@@ -28,6 +28,7 @@ import { createHash } from "node:crypto";
import { config } from "./config.js";
import { open, randomToken, safeEqual, seal, signInKey } from "./crypto.js";
import { UpstreamError, absoluteUpstream } from "./upstream.js";
import { upstreamFetch } from "./clientcontext.js";
export interface TokenSet {
access: string;
@@ -74,7 +75,7 @@ const metadataCache = new Map<string, { metadata: Metadata; fetchedAt: number }>
async function metadataFor(base: string): Promise<Metadata> {
const cached = metadataCache.get(base);
if (cached && Date.now() - cached.fetchedAt < METADATA_TTL_MS) return cached.metadata;
const res = await fetch(`${base}/.well-known/oauth-authorization-server`, {
const res = await upstreamFetch(`${base}/.well-known/oauth-authorization-server`, {
headers: { accept: "application/json" },
signal: AbortSignal.timeout(config.upstreamTimeout),
});
@@ -179,7 +180,7 @@ export async function start(params: { username: string; base: string; remember:
* the password has matched.
*/
export async function passwordConfirms(params: { base: string; username: string; password: string }): Promise<boolean> {
const res = await fetch(absoluteUpstream("/api/auth", params.base), {
const res = await upstreamFetch(absoluteUpstream("/api/auth", params.base), {
method: "POST",
headers: { "content-type": "application/json", accept: "application/json" },
body: JSON.stringify({
@@ -242,7 +243,7 @@ export async function refreshTokens(base: string, tokens: TokenSet): Promise<Tok
}
async function tokenRequest(endpoint: string, fields: Record<string, string>): Promise<TokenSet | null> {
const res = await fetch(endpoint, {
const res = await upstreamFetch(endpoint, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
body: new URLSearchParams({ ...fields, client_id: config.oauthClientId, client_secret: config.oauthClientSecret }),
@@ -281,7 +282,7 @@ export async function revokeTokens(base: string, tokens: TokenSet): Promise<bool
if (!endpoint) return false;
const revoke = async (token: string, hint: string) => {
try {
const res = await fetch(endpoint!, {
const res = await upstreamFetch(endpoint!, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
body: new URLSearchParams({ token, token_type_hint: hint, client_id: config.oauthClientId, client_secret: config.oauthClientSecret }),
+2 -1
View File
@@ -1,5 +1,6 @@
import { gunzipSync } from "node:zlib";
import { config } from "./config.js";
import { upstreamFetch } from "./clientcontext.js";
/**
* Stalwart's list of permissions, for the Roles screen's picker.
@@ -52,7 +53,7 @@ export function parseSchemaBody(bytes: Uint8Array): unknown {
export async function fetchPermissions(authorization: string, baseUrl: string): Promise<PermissionInfo[] | null> {
const hit = cache.get(baseUrl);
if (hit && Date.now() - hit.at < CACHE_MS) return hit.list;
const res = await fetch(`${baseUrl}/api/schema`, {
const res = await upstreamFetch(`${baseUrl}/api/schema`, {
headers: { authorization, accept: "application/json" },
signal: AbortSignal.timeout(config.upstreamTimeout),
});
+2 -1
View File
@@ -27,6 +27,7 @@ import { createHash, randomBytes } from "node:crypto";
import type { ServerResponse } from "node:http";
import { config } from "./config.js";
import { absoluteUpstream, getUpstreamSession, upstreamFor } from "./upstream.js";
import { upstreamFetch } from "./clientcontext.js";
const USING = ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"];
const RENEW_BEFORE_MS = 60 * 60_000; // renew an hour before Stalwart expires it
@@ -80,7 +81,7 @@ function keyFor(base: string, username: string) { return `${base} ${username}`;
async function jmap(entry: AccountPush, calls: unknown[]) {
const authorization = await entry.credential.get();
const upstream = await getUpstreamSession(entry.key, authorization, entry.base);
const res = await fetch(absoluteUpstream(upstream.apiUrl, upstream.baseUrl), {
const res = await upstreamFetch(absoluteUpstream(upstream.apiUrl, upstream.baseUrl), {
method: "POST",
headers: { authorization, "content-type": "application/json", accept: "application/json" },
body: JSON.stringify({ using: USING, methodCalls: calls }),
+5 -4
View File
@@ -1,5 +1,6 @@
import { config } from "./config.js";
import { grantsAdministration } from "./adminGate.js";
import { upstreamFetch } from "./clientcontext.js";
export interface UpstreamSession {
capabilities: Record<string, unknown>;
@@ -137,7 +138,7 @@ async function detectAdminUrl(authorization: string, session: UpstreamSession):
let prefix: string | null = DEFAULT_ADMIN_PREFIX;
if (accountId) {
try {
const res = await fetch(absoluteUpstream(session.apiUrl, session.baseUrl), {
const res = await upstreamFetch(absoluteUpstream(session.apiUrl, session.baseUrl), {
method: "POST",
headers: { authorization, "content-type": "application/json", accept: "application/json" },
body: JSON.stringify({
@@ -166,7 +167,7 @@ export function wellKnownUrl(base: string = config.stalwartUrl): string {
* header. Throws UpstreamError(401) on bad credentials.
*/
export async function fetchUpstreamSession(authorization: string, base: string = config.stalwartUrl): Promise<UpstreamSession> {
const res = await fetch(wellKnownUrl(base), {
const res = await upstreamFetch(wellKnownUrl(base), {
headers: { authorization, accept: "application/json" },
redirect: "follow",
signal: AbortSignal.timeout(config.upstreamTimeout),
@@ -335,7 +336,7 @@ async function fetchAccountInfo(authorization: string, session: UpstreamSession)
if (!accountId) return EMPTY_INFO;
// Against the server that issued this session, not the default: with a
// domain mapped elsewhere, the default has never heard of the account.
const res = await fetch(absoluteUpstream(session.apiUrl, session.baseUrl), {
const res = await upstreamFetch(absoluteUpstream(session.apiUrl, session.baseUrl), {
method: "POST",
headers: { authorization, "content-type": "application/json", accept: "application/json" },
body: JSON.stringify({
@@ -393,7 +394,7 @@ export function normalizePermission(name: string): string {
*/
async function fetchServerAccount(authorization: string, base: string): Promise<Pick<AccountInfo, "edition" | "permissions">> {
try {
const res = await fetch(`${base}/api/account`, {
const res = await upstreamFetch(`${base}/api/account`, {
headers: { authorization, accept: "application/json" },
signal: AbortSignal.timeout(config.upstreamTimeout),
});