Skip to content

Commit 2604658

Browse files
committed
fix(plugin-auth): the vendored auth library's client-address source follows server.trustProxy
better-auth resolves a request's client address with its own header reader, which knows neither the transport's peer address nor server.trustProxy. The auth instance now tells it to read one platform-owned header, and AuthManager.handleRequest -- the one door to the library's HTTP handler -- writes that header from the address the client-address trust rule established, after dropping any copy the caller sent. With no address established, the library is handed none. Claude-Session: https://claude.ai/code/session_01UmqzD97e14iws6hmVhgZ5y Co-authored-by: Claude <noreply@anthropic.com>
1 parent 7c2eab9 commit 2604658

6 files changed

Lines changed: 372 additions & 20 deletions

File tree

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
'@objectstack/plugin-auth': patch
3+
---
4+
5+
fix(plugin-auth): the vendored auth library records and keys on the client address the server established (#24799)
6+
7+
Clause-②: no
8+
9+
better-auth reads a request's client address with its own reader, and three things are keyed on what it reads: a session's `ip_address` (and the `login` / `logout` audit rows copied from it), the address on the `login_failed` / `account_locked` audit rows, and the key of better-auth's own per-address rate limiter. That reader did not follow `server.trustProxy`. It now follows the same rule as the `allowed_ip_ranges` allow-list and `last_login_ip`: `X-Forwarded-For` (its first entry), then `X-Real-IP`, count only when the stack declares `server.trustProxy`. Otherwise the address is the connection's peer address. When neither is available, better-auth is handed no address.
10+
11+
**For operators:**
12+
13+
- Behind a reverse proxy or load balancer, declare `server: { trustProxy: true }` in the stack. Without it, sessions and audit rows record the proxy's own address, and better-auth's per-address rate limit counts every client behind the proxy as one client.
14+
- With `server.trustProxy` declared, a forwarded chain (`client, proxy`) now resolves to its first entry. Before, better-auth read a multi-entry header as no address.
15+
- A request whose client address cannot be established records no address, and better-auth's rate limiter counts it in one shared bucket.
16+
17+
**For hosts:** `AuthManager.handleRequest` now drops any `x-objectstack-client-address` request header a caller sends. The platform writes that header itself, from the address it established, and better-auth reads no other header for the client address. A programmatic `auth.api.*` call is handed whatever headers its caller passes. Route a client's request through `handleRequest` instead.

‎packages/plugins/plugin-auth/src/auth-manager.test.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
44
import { AuthManager, ipMatchesRange } from './auth-manager';
5+
import { vendorClientAddressOptions } from './client-address-vendor';
56
import { assertEngineDeleteDispatch, assertEngineUpdateDispatch, assertEngineFindOnePredicate, type EngineFindOneQueryInput } from '@objectstack/objectql';
67

78
// Mock better-auth so we can control the handler behaviour
@@ -2116,6 +2117,7 @@ describe('AuthManager', () => {
21162117
domain: '.objectos.app',
21172118
},
21182119
useSecureCookies: true,
2120+
ipAddress: vendorClientAddressOptions(),
21192121
});
21202122
});
21212123

@@ -2142,7 +2144,7 @@ describe('AuthManager', () => {
21422144
expect(capturedConfig.advanced.cookiePrefix).toBe('objectos');
21432145
});
21442146

2145-
it('should NOT include advanced when not provided', async () => {
2147+
it('carries only the library client-address source when no advanced option is provided', async () => {
21462148
let capturedConfig: any;
21472149
(betterAuth as any).mockImplementation((config: any) => {
21482150
capturedConfig = config;
@@ -2157,7 +2159,7 @@ describe('AuthManager', () => {
21572159
await manager.getAuthInstance();
21582160
warnSpy.mockRestore();
21592161

2160-
expect(capturedConfig).not.toHaveProperty('advanced');
2162+
expect(capturedConfig.advanced).toEqual({ ipAddress: vendorClientAddressOptions() });
21612163
});
21622164
});
21632165

‎packages/plugins/plugin-auth/src/auth-manager.ts‎

Lines changed: 35 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,7 @@ import {
134134
import { isPlaceholderEmail } from './placeholder-email.js';
135135
import { readAccountInvitation, settleImportResetDelivery } from './account-invitation-marker.js';
136136
import { resolveClientAddress } from './client-address.js';
137+
import { vendorClientAddressOptions, withVendorClientAddress } from './client-address-vendor.js';
137138
import { clientAddressStateEntries, readRequestClientAddress } from './request-client-address.js';
138139
import {
139140
REVOKE_SESSION_NOT_FOUND_CODE,
@@ -1058,9 +1059,13 @@ export interface AuthManagerOptions extends Partial<AuthConfig> {
10581059
* The deployment's `server.trustProxy`: believe `X-Forwarded-For` /
10591060
* `X-Real-IP` when establishing a request's client address for the ADR-0069
10601061
* D5 allow-list ({@link allowedIpRanges}) and the D7 login audit
1061-
* (`last_login_ip`). The same authored value the runtime's inbound rate
1062-
* limiter reads; `objectstack serve` passes it to both. A host that composes
1063-
* `AuthPlugin` itself passes the value it gives the dispatcher.
1062+
* (`last_login_ip`) — and for what the vendored auth library records and
1063+
* keys on by client address (session `ip_address`, the sign-in audit
1064+
* fingerprint, its own per-address {@link rateLimit}), which is handed that
1065+
* same address (`client-address-vendor.ts`). The same authored value the
1066+
* runtime's inbound rate limiter reads; `objectstack serve` passes it to
1067+
* both. A host that composes `AuthPlugin` itself passes the value it gives
1068+
* the dispatcher.
10641069
* @default false
10651070
*/
10661071
trustProxy?: boolean;
@@ -3075,19 +3080,23 @@ export class AuthManager {
30753080
return origins.length ? { trustedOrigins: origins } : {};
30763081
})(),
30773082

3078-
// Advanced options (cross-subdomain cookies, secure cookies, CSRF, etc.)
3079-
...(this.config.advanced ? {
3080-
advanced: {
3081-
...(this.config.advanced.crossSubDomainCookies
3082-
? { crossSubDomainCookies: this.config.advanced.crossSubDomainCookies } : {}),
3083-
...(this.config.advanced.useSecureCookies != null
3084-
? { useSecureCookies: this.config.advanced.useSecureCookies } : {}),
3085-
...(this.config.advanced.disableCSRFCheck != null
3086-
? { disableCSRFCheck: this.config.advanced.disableCSRFCheck } : {}),
3087-
...(this.config.advanced.cookiePrefix != null
3088-
? { cookiePrefix: this.config.advanced.cookiePrefix } : {}),
3089-
},
3090-
} : {}),
3083+
// Advanced options (cross-subdomain cookies, secure cookies, CSRF, etc.),
3084+
// and — always — the library's own client-address source: the one
3085+
// platform-owned header `handleRequest` writes from the address the
3086+
// client-address trust rule established (`client-address-vendor.ts`).
3087+
// Never left at the library's default reader, which knows neither the
3088+
// transport's peer address nor `server.trustProxy`.
3089+
advanced: {
3090+
...(this.config.advanced?.crossSubDomainCookies
3091+
? { crossSubDomainCookies: this.config.advanced.crossSubDomainCookies } : {}),
3092+
...(this.config.advanced?.useSecureCookies != null
3093+
? { useSecureCookies: this.config.advanced.useSecureCookies } : {}),
3094+
...(this.config.advanced?.disableCSRFCheck != null
3095+
? { disableCSRFCheck: this.config.advanced.disableCSRFCheck } : {}),
3096+
...(this.config.advanced?.cookiePrefix != null
3097+
? { cookiePrefix: this.config.advanced.cookiePrefix } : {}),
3098+
ipAddress: vendorClientAddressOptions(),
3099+
},
30913100
};
30923101

30933102
const auth = betterAuth(betterAuthConfig);
@@ -6490,7 +6499,8 @@ export class AuthManager {
64906499
* `Request` does not carry: `remoteAddress` is its peer address
64916500
* (`IHttpRequest.remoteAddress`). Omitted, the request's client address is
64926501
* established from trusted forwarded headers alone, and is undetermined
6493-
* when `trustProxy` is not declared.
6502+
* when `trustProxy` is not declared. Either way the vendored library is
6503+
* handed that address and no other (`client-address-vendor.ts`).
64946504
* @returns Web standard Response object
64956505
*/
64966506
async handleRequest(request: Request, transport?: { remoteAddress?: string }): Promise<Response> {
@@ -6507,6 +6517,14 @@ export class AuthManager {
65076517
...(transport?.remoteAddress ? { remoteAddress: transport.remoteAddress } : {}),
65086518
});
65096519

6520+
// The vendored library's OWN client-address reader (session `ip_address`,
6521+
// the sign-in audit fingerprint, its per-address rate limiter) reads only
6522+
// the platform-owned header (`vendorClientAddressOptions`, composed in
6523+
// `createAuthInstance`). Written HERE, from the address just established,
6524+
// after dropping any copy the caller sent — so the library answers the same
6525+
// address the D5 allow-list judged, or none. See `client-address-vendor.ts`.
6526+
request = withVendorClientAddress(request, clientAddress);
6527+
65106528
// Dev DX: better-auth's CSRF protection rejects state-changing requests
65116529
// (e.g. `/sign-in/email`) with a 403 when neither `Origin` nor `Referer`
65126530
// is present. Browsers always send one; non-browser API clients (curl,
Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
//
3+
// The vendored auth library's OWN client-address source follows the
4+
// platform's client-address trust rule (`./client-address.ts`), the rule the
5+
// ADR-0069 D5 allow-list judges with and the D7 login audit stamps by:
6+
//
7+
// - forwarded headers count only when the deployment declares
8+
// `server.trustProxy` (`AuthManagerOptions.trustProxy`);
9+
// - otherwise the address is the transport's peer (`IHttpRequest.remoteAddress`);
10+
// - neither available ⇒ the library is handed NO address.
11+
//
12+
// One pin per branch. Each reads, off one composition, the three things the
13+
// library keys on a client address (`client-address-vendor.ts`): the session
14+
// row's `ip_address`, the refused-sign-in audit fingerprint, and the key its
15+
// per-address rate limiter consumes. The fixture is the D5/D7 suite's
16+
// (`client-ip-allow-list-trust-rule.test.ts`): `AuthPlugin.registerAuthRoutes`
17+
// mounted on a real Hono app in front of a real `AuthManager` on the installed
18+
// better-auth, with the transport peer supplied the way `@hono/node-server`
19+
// supplies it, as the Node request on `c.env.incoming`.
20+
//
21+
// Every request also carries the platform-owned header itself, set by the
22+
// caller: in no branch may a caller's copy reach the library.
23+
//
24+
// ADR-0112 is `code` AND `status`; the refused sign-in asserts both, so a
25+
// refusal from anywhere but the credential check cannot stand in for it.
26+
27+
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
28+
import { Hono } from 'hono';
29+
import { AuthManager } from './auth-manager';
30+
import { AuthPlugin } from './auth-plugin';
31+
import { VENDOR_CLIENT_ADDRESS_HEADER } from './client-address-vendor';
32+
import { createMemoryEngine } from './impersonation-bearer-rotation.test';
33+
import { inviteForAudienceGate } from './audience-gate-test-support';
34+
import type { PluginContext } from '@objectstack/core';
35+
36+
const SECRET = 'test-secret-at-least-32-chars-long!!';
37+
const PASSWORD = 'S3cure!Passw0rd-24799';
38+
const ORIGIN = 'http://localhost:3000';
39+
const BASE = '/api/v1/auth';
40+
const EMAIL = 'member.24799@example.com';
41+
42+
/** Documentation ranges (RFC 5737), and one private proxy hop. */
43+
const CLIENT = '203.0.113.7';
44+
const OTHER = '198.51.100.9';
45+
const PROXY_HOP = '10.0.0.2';
46+
47+
/** The credential check's own refusal (ADR-0112 `code` + `status`). */
48+
const CREDENTIAL_REFUSAL = { status: 401, code: 'INVALID_EMAIL_OR_PASSWORD' };
49+
50+
const mockCtx = () =>
51+
({
52+
registerService: vi.fn(),
53+
getService: vi.fn((name: string) => (name === 'manifest' ? { register: vi.fn() } : undefined)),
54+
getServices: vi.fn(() => new Map()),
55+
hook: vi.fn(),
56+
trigger: vi.fn(),
57+
logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn(), debug: vi.fn() },
58+
getKernel: vi.fn(),
59+
}) as unknown as PluginContext;
60+
61+
async function verdict(res: Response): Promise<{ status: number; code?: string }> {
62+
const text = await res.text();
63+
let code: string | undefined;
64+
try {
65+
const parsed = JSON.parse(text);
66+
code = parsed?.error?.code ?? parsed?.code;
67+
} catch {
68+
/* non-JSON body → no code */
69+
}
70+
return { status: res.status, code };
71+
}
72+
73+
/** What the library keyed on one client address, per seam. */
74+
interface Observed {
75+
/** `sys_session.ip_address` of the session the successful sign-in minted. */
76+
session: unknown;
77+
/** The `login_failed` audit event's address, for the refused sign-in. */
78+
refused: unknown;
79+
/** The address half of every rate-limit key consumed across both sign-ins. */
80+
limiterKeys: string[];
81+
/** ADR-0069 D7 `last_login_ip` after the successful sign-in. */
82+
lastLoginIp: unknown;
83+
}
84+
85+
/** One deployment, served through the REAL mount chain. */
86+
async function serve(deployment: { trustProxy?: boolean }) {
87+
const engine = createMemoryEngine();
88+
const events: Array<{ action: string; ipAddress?: string }> = [];
89+
const consumedKeys: string[] = [];
90+
const manager = new AuthManager({
91+
secret: SECRET,
92+
baseUrl: ORIGIN,
93+
dataEngine: engine,
94+
getAuditSink: () => ({
95+
recordAuthEvent: async (event: { action: string; ipAddress?: string }) => {
96+
events.push(event);
97+
},
98+
}),
99+
// The library's limiter is on by default only in production; switch it on
100+
// and record every key it consumes, admitting every request.
101+
rateLimit: { enabled: true },
102+
rateLimitStorage: {
103+
consume: async (key: string) => {
104+
consumedKeys.push(key);
105+
return { allowed: true, retryAfter: null };
106+
},
107+
},
108+
...deployment,
109+
} as any);
110+
111+
const ctx = mockCtx();
112+
const plugin = new AuthPlugin({ secret: SECRET });
113+
await plugin.init(ctx);
114+
(plugin as any).authManager = manager;
115+
const app = new Hono();
116+
(plugin as any).registerAuthRoutes({ getRawApp: () => app, getPort: () => 0 }, ctx);
117+
118+
const signIn = (peer: string | undefined, headers: Record<string, string>, password: string) =>
119+
app.request(
120+
`${ORIGIN}${BASE}/sign-in/email`,
121+
{
122+
method: 'POST',
123+
headers: { 'content-type': 'application/json', origin: ORIGIN, ...headers },
124+
body: JSON.stringify({ email: EMAIL, password }),
125+
},
126+
peer ? { incoming: { socket: { remoteAddress: peer } } } : {},
127+
);
128+
129+
await inviteForAudienceGate(manager, EMAIL);
130+
const signUp = await manager.handleRequest(
131+
new Request(`${ORIGIN}${BASE}/sign-up/email`, {
132+
method: 'POST',
133+
headers: { 'content-type': 'application/json', origin: ORIGIN },
134+
body: JSON.stringify({ email: EMAIL, password: PASSWORD, name: 'Client Address Member' }),
135+
}),
136+
);
137+
expect(signUp.status, `sign-up: ${await signUp.clone().text()}`).toBe(200);
138+
139+
/** A refused, then a successful, sign-in from `peer` carrying `headers`. */
140+
const observe = async (peer: string | undefined, headers: Record<string, string>): Promise<Observed> => {
141+
const sessionsBefore = (engine.tables.get('sys_session') ?? []).length;
142+
const eventsBefore = events.length;
143+
const keysBefore = consumedKeys.length;
144+
145+
const refusedRes = await signIn(peer, headers, `${PASSWORD}-wrong`);
146+
expect(await verdict(refusedRes)).toEqual(CREDENTIAL_REFUSAL);
147+
const okRes = await signIn(peer, headers, PASSWORD);
148+
expect(okRes.status, await okRes.clone().text()).toBe(200);
149+
150+
const minted = ((engine.tables.get('sys_session') ?? []) as any[]).slice(sessionsBefore);
151+
expect(minted, 'one session minted by the successful sign-in').toHaveLength(1);
152+
const refused = events.slice(eventsBefore).filter((e) => e.action === 'login_failed');
153+
expect(refused, 'one login_failed event for the refused sign-in').toHaveLength(1);
154+
const limiterKeys = consumedKeys.slice(keysBefore).map((key) => key.split('|')[0]!);
155+
expect(limiterKeys, 'the library limiter consumed a key for each sign-in').toHaveLength(2);
156+
const user = ((engine.tables.get('sys_user') ?? []) as any[]).find((r) => r.email === EMAIL);
157+
158+
return {
159+
session: minted[0]?.ip_address,
160+
refused: refused[0]?.ipAddress,
161+
limiterKeys,
162+
lastLoginIp: user?.last_login_ip,
163+
};
164+
};
165+
166+
return { observe };
167+
}
168+
169+
beforeEach(() => {
170+
vi.spyOn(console, 'warn').mockImplementation(() => {});
171+
vi.spyOn(console, 'error').mockImplementation(() => {});
172+
});
173+
afterEach(() => {
174+
vi.restoreAllMocks();
175+
});
176+
177+
describe('the vendored auth library keys on the client address the server established, and no other', () => {
178+
it('behind a declared trusted proxy, it records and keys on the forwarded client address', async () => {
179+
const d = await serve({ trustProxy: true });
180+
181+
const seen = await d.observe(PROXY_HOP, {
182+
'x-forwarded-for': `${CLIENT}, ${PROXY_HOP}`,
183+
[VENDOR_CLIENT_ADDRESS_HEADER]: OTHER,
184+
});
185+
186+
expect(seen.session).toBe(CLIENT);
187+
expect(seen.refused).toBe(CLIENT);
188+
expect(seen.limiterKeys).toEqual([CLIENT, CLIENT]);
189+
// The same address the D7 login audit stamped.
190+
expect(seen.lastLoginIp).toBe(CLIENT);
191+
});
192+
193+
it('without a declared trusted proxy, it records and keys on the connection peer, whatever the request headers say', async () => {
194+
const d = await serve({});
195+
196+
const seen = await d.observe(CLIENT, {
197+
'x-forwarded-for': OTHER,
198+
'x-real-ip': OTHER,
199+
[VENDOR_CLIENT_ADDRESS_HEADER]: OTHER,
200+
});
201+
202+
expect(seen.session).toBe(CLIENT);
203+
expect(seen.refused).toBe(CLIENT);
204+
expect(seen.limiterKeys).toEqual([CLIENT, CLIENT]);
205+
expect(seen.lastLoginIp).toBe(CLIENT);
206+
});
207+
208+
it('when the server established no address, it is handed none, whatever the request headers say', async () => {
209+
// What the library answers when it is handed no address is its own,
210+
// environment-dependent behaviour (nothing in production, a loopback
211+
// placeholder in development and test) — so each deployment's answer to a
212+
// request carrying no header at all is the control, never a literal.
213+
for (const deployment of [{}, { trustProxy: true }]) {
214+
const d = await serve(deployment);
215+
const control = await d.observe(undefined, {});
216+
const seen = await d.observe(undefined, {
217+
...(deployment.trustProxy ? {} : { 'x-forwarded-for': OTHER, 'x-real-ip': OTHER }),
218+
[VENDOR_CLIENT_ADDRESS_HEADER]: OTHER,
219+
});
220+
221+
const label = deployment.trustProxy ? 'trusted proxy, nothing forwarded' : 'no trusted proxy';
222+
expect(seen.session, label).toEqual(control.session);
223+
expect(seen.refused, label).toEqual(control.refused);
224+
expect(seen.limiterKeys, label).toEqual(control.limiterKeys);
225+
expect([seen.session, seen.refused, ...seen.limiterKeys], label).not.toContain(OTHER);
226+
// …and the D7 login audit stamped none either.
227+
expect(seen.lastLoginIp, label).toBeUndefined();
228+
}
229+
});
230+
});

0 commit comments

Comments
 (0)