@codelitdev/oauth-server-kit 0.9.0 → 0.11.0

package/README.md

@@ -31,12 +31,19 @@ import {
 
 import {
     createOAuthProviderOptions,
+    isRecentlyAuthenticated,
     resolveBetterAuthSession,
+    secureCookieOptions,
+    secureEmailAndPasswordOptions,
+    secureSessionOptions,
+    sessionCookieName,
 } from "@codelitdev/oauth-server-kit/better-auth";
 
 import {
+    createClientIpMiddleware,
     createOAuthBearerMiddleware,
     createOAuthPagesRouter,
+    parseTrustProxy,
 } from "@codelitdev/oauth-server-kit/express";
 
 import { createMcpOAuthDiscoveryRoutes } from "@codelitdev/oauth-server-kit/mcp";
@@ -57,9 +64,33 @@ application.
 - Ordinary-login redirects are restricted to configured origins.
 - Hosted pages reject framing and clear configured stale host-only cookies at
   both `/login` and `/oauth/login`.
+- Session cookies are `__Host-<prefix>.session_token` (Secure, `Path=/`, no
+  `Domain`) over https through `secureCookieOptions`; with cross-subdomain
+  cookies they stay `__Secure-`, and over http (local dev) they are plain.
+  Products keep their own `cookiePrefix` and pass it to the helper.
+- `secureSessionOptions()` turns the session cookie cache off, so a revoked
+  session stops working on the next request.
+- `secureEmailAndPasswordOptions()` keeps password sign-up off; a product
+  that opts in with `{ enabled: true }` also requires a verified email before
+  sign-in, so nobody can claim an address they don't own.
+- `createClientIpMiddleware` resolves the client address from a trusted proxy
+  chain (`req.ip`, which ignores the attacker-controlled left of
+  `X-Forwarded-For`) into an internal header, and `secureCookieOptions`'
+  `clientIpHeader` makes Better Auth read only that header.
+- Session identities carry `authenticatedAt`; `isRecentlyAuthenticated`
+  supports step-up checks. OAuth identities never count as recent.
 - Product claims such as `team_id`, roles, or permissions are not returned as
   trusted package identity fields.
 
+Known limitation: `@better-auth/oauth-provider`'s RP-initiated logout
+confirmation cookie (`<session cookie>.oauth_logout_confirmation`) is set on
+`/api/auth/oauth2/end-session/confirm`. Browsers reject a `__Host-` cookie with a
+path other than `/`, so under `__Host-` that confirmation step (shown when an
+OAuth client calls end-session without a valid `id_token_hint`) cannot complete.
+Neither the plugin options nor `advanced.cookies` can change that cookie's name
+or path. Use cross-subdomain mode (`__Secure-`) if a product needs the flow.
+See [ADR 0018](../../docs/decisions/0018-secure-session-cookies-and-client-ip.md).
+
 See [docs/integration.md](docs/integration.md) for full web, mobile, REST, and
 MCP setup, and [docs/architecture.md](docs/architecture.md) for the normative
 product requirements and public contract.

package/dist/better-auth.d.mts

@@ -1,5 +1,5 @@
 import { OAuthOptions } from '@better-auth/oauth-provider';
-import { A as AuthenticationResult } from './types-DJxCmhYu.mjs';
+import { A as AuthenticationResult, a as AuthenticatedIdentity } from './types-sqdNO7Nc.mjs';
 import '@better-auth/oauth-provider/resource-client';
 
 type BetterAuthSession = {
@@ -11,6 +11,8 @@ type BetterAuthSession = {
     session: {
         id: string;
         expiresAt: Date;
+        /** When the session was created, i.e. when the user signed in. */
+        createdAt: Date | string;
     };
 };
 interface BetterAuthSessionApi {
@@ -37,4 +39,107 @@ interface CreateOAuthProviderOptionsInput {
 }
 declare function createOAuthProviderOptions(input: CreateOAuthProviderOptionsInput): OAuthOptions<string[]>;
 
-export { type BetterAuthSession, type BetterAuthSessionApi, type CreateOAuthProviderOptionsInput, type ResolveBetterAuthSessionOptions, createOAuthProviderOptions, resolveBetterAuthSession };
+interface IsRecentlyAuthenticatedOptions {
+    maxAgeMs: number;
+    now?: Date;
+}
+/**
+ * Whether the identity is a browser session that signed in within `maxAgeMs`.
+ * OAuth identities never count: a bearer token carries no interactive
+ * sign-in. Products choose which actions require this (step-up checks).
+ */
+declare function isRecentlyAuthenticated(identity: AuthenticatedIdentity, options: IsRecentlyAuthenticatedOptions): boolean;
+
+interface SecureCookieOptionsInput {
+    /** Public URL Better Auth is served from (its `baseURL`). */
+    baseURL: string;
+    /** Product-specific prefix, e.g. `courselit`. Must not already carry `__Host-`/`__Secure-`. */
+    cookiePrefix: string;
+    /** Pass through only when cookies must be shared across sibling subdomains. */
+    crossSubDomainCookies?: {
+        enabled: boolean;
+        domain?: string;
+    };
+    /**
+     * Name of an internal header the app's edge sets to the trusted client
+     * address (see `createClientIpMiddleware`). Better Auth then reads the
+     * address only from it, never from `X-Forwarded-For`.
+     */
+    clientIpHeader?: string;
+}
+/** The subset of Better Auth's `advanced` options these helpers produce. */
+interface SecureCookieAdvancedOptions {
+    cookiePrefix: string;
+    useSecureCookies?: boolean;
+    defaultCookieAttributes?: {
+        secure: boolean;
+        path: string;
+    };
+    crossSubDomainCookies?: {
+        enabled: boolean;
+        domain?: string;
+    };
+    ipAddress?: {
+        ipAddressHeaders: string[];
+    };
+}
+/**
+ * Better Auth `advanced` options for hardened session cookies. Spread them
+ * into your own config: `advanced: { ...secureCookieOptions({...}) }`.
+ *
+ * - https, no cross-subdomain cookies: the session cookie is
+ *   `__Host-<prefix>.session_token` (Secure, `Path=/`, no `Domain`), so a
+ *   sibling subdomain cannot plant or shadow it. Better Auth only knows
+ *   `__Secure-` and would produce `__Secure-__Host-...`, so `__Host-` is
+ *   folded into `cookiePrefix` and Secure is set via `defaultCookieAttributes`.
+ * - https with cross-subdomain cookies: `__Host-` forbids `Domain`, so the
+ *   cookie keeps Better Auth's `__Secure-` prefix and is shared as configured.
+ * - http (local development): plain `<prefix>.session_token`.
+ *
+ * Known limitation: `@better-auth/oauth-provider` stores a short-lived
+ * RP-initiated-logout confirmation cookie named
+ * `<session cookie name>.oauth_logout_confirmation` on the path
+ * `/api/auth/oauth2/end-session/confirm`. Browsers reject a `__Host-` cookie
+ * with any path but `/`, so that cookie is dropped under `__Host-` and the
+ * logout confirmation step (shown when an OAuth client calls end-session
+ * without a valid `id_token_hint`) cannot complete. Neither the plugin's
+ * options nor `advanced.cookies` can change its name or path. Products that
+ * need that flow must use cross-subdomain mode (`__Secure-`) or accept it.
+ */
+declare function secureCookieOptions(input: SecureCookieOptionsInput): SecureCookieAdvancedOptions;
+/**
+ * The exact session-token cookie name Better Auth produces for options built
+ * by `secureCookieOptions`, for products that choose credentials by cookie
+ * name. Pass the object `secureCookieOptions` returned.
+ */
+declare function sessionCookieName(advanced: Pick<SecureCookieAdvancedOptions, "cookiePrefix" | "useSecureCookies">): string;
+/**
+ * Better Auth `session` options with the cookie cache off: every request
+ * checks the session row, so a revoked session stops working immediately
+ * instead of until the cached cookie expires (5 minutes by default).
+ */
+declare function secureSessionOptions(): {
+    cookieCache: {
+        enabled: false;
+    };
+};
+interface SecureEmailAndPasswordInput {
+    /** Turn password sign-in on. Off by default: products sign people in
+     * with email codes, social providers or OAuth. */
+    enabled?: boolean;
+}
+/**
+ * Better Auth `emailAndPassword` settings. Password sign-up is off unless a
+ * product opts in: with it on and no verification, anyone can register an
+ * address they don't own and sit on it until the real owner shows up. When
+ * a product does enable passwords, the address must be verified before the
+ * account can sign in.
+ */
+declare function secureEmailAndPasswordOptions(input?: SecureEmailAndPasswordInput): {
+    enabled: false;
+} | {
+    enabled: true;
+    requireEmailVerification: true;
+};
+
+export { type BetterAuthSession, type BetterAuthSessionApi, type CreateOAuthProviderOptionsInput, type IsRecentlyAuthenticatedOptions, type ResolveBetterAuthSessionOptions, type SecureCookieAdvancedOptions, type SecureCookieOptionsInput, type SecureEmailAndPasswordInput, createOAuthProviderOptions, isRecentlyAuthenticated, resolveBetterAuthSession, secureCookieOptions, secureEmailAndPasswordOptions, secureSessionOptions, sessionCookieName };

package/dist/better-auth.d.ts

@@ -1,5 +1,5 @@
 import { OAuthOptions } from '@better-auth/oauth-provider';
-import { A as AuthenticationResult } from './types-DJxCmhYu.js';
+import { A as AuthenticationResult, a as AuthenticatedIdentity } from './types-sqdNO7Nc.js';
 import '@better-auth/oauth-provider/resource-client';
 
 type BetterAuthSession = {
@@ -11,6 +11,8 @@ type BetterAuthSession = {
     session: {
         id: string;
         expiresAt: Date;
+        /** When the session was created, i.e. when the user signed in. */
+        createdAt: Date | string;
     };
 };
 interface BetterAuthSessionApi {
@@ -37,4 +39,107 @@ interface CreateOAuthProviderOptionsInput {
 }
 declare function createOAuthProviderOptions(input: CreateOAuthProviderOptionsInput): OAuthOptions<string[]>;
 
-export { type BetterAuthSession, type BetterAuthSessionApi, type CreateOAuthProviderOptionsInput, type ResolveBetterAuthSessionOptions, createOAuthProviderOptions, resolveBetterAuthSession };
+interface IsRecentlyAuthenticatedOptions {
+    maxAgeMs: number;
+    now?: Date;
+}
+/**
+ * Whether the identity is a browser session that signed in within `maxAgeMs`.
+ * OAuth identities never count: a bearer token carries no interactive
+ * sign-in. Products choose which actions require this (step-up checks).
+ */
+declare function isRecentlyAuthenticated(identity: AuthenticatedIdentity, options: IsRecentlyAuthenticatedOptions): boolean;
+
+interface SecureCookieOptionsInput {
+    /** Public URL Better Auth is served from (its `baseURL`). */
+    baseURL: string;
+    /** Product-specific prefix, e.g. `courselit`. Must not already carry `__Host-`/`__Secure-`. */
+    cookiePrefix: string;
+    /** Pass through only when cookies must be shared across sibling subdomains. */
+    crossSubDomainCookies?: {
+        enabled: boolean;
+        domain?: string;
+    };
+    /**
+     * Name of an internal header the app's edge sets to the trusted client
+     * address (see `createClientIpMiddleware`). Better Auth then reads the
+     * address only from it, never from `X-Forwarded-For`.
+     */
+    clientIpHeader?: string;
+}
+/** The subset of Better Auth's `advanced` options these helpers produce. */
+interface SecureCookieAdvancedOptions {
+    cookiePrefix: string;
+    useSecureCookies?: boolean;
+    defaultCookieAttributes?: {
+        secure: boolean;
+        path: string;
+    };
+    crossSubDomainCookies?: {
+        enabled: boolean;
+        domain?: string;
+    };
+    ipAddress?: {
+        ipAddressHeaders: string[];
+    };
+}
+/**
+ * Better Auth `advanced` options for hardened session cookies. Spread them
+ * into your own config: `advanced: { ...secureCookieOptions({...}) }`.
+ *
+ * - https, no cross-subdomain cookies: the session cookie is
+ *   `__Host-<prefix>.session_token` (Secure, `Path=/`, no `Domain`), so a
+ *   sibling subdomain cannot plant or shadow it. Better Auth only knows
+ *   `__Secure-` and would produce `__Secure-__Host-...`, so `__Host-` is
+ *   folded into `cookiePrefix` and Secure is set via `defaultCookieAttributes`.
+ * - https with cross-subdomain cookies: `__Host-` forbids `Domain`, so the
+ *   cookie keeps Better Auth's `__Secure-` prefix and is shared as configured.
+ * - http (local development): plain `<prefix>.session_token`.
+ *
+ * Known limitation: `@better-auth/oauth-provider` stores a short-lived
+ * RP-initiated-logout confirmation cookie named
+ * `<session cookie name>.oauth_logout_confirmation` on the path
+ * `/api/auth/oauth2/end-session/confirm`. Browsers reject a `__Host-` cookie
+ * with any path but `/`, so that cookie is dropped under `__Host-` and the
+ * logout confirmation step (shown when an OAuth client calls end-session
+ * without a valid `id_token_hint`) cannot complete. Neither the plugin's
+ * options nor `advanced.cookies` can change its name or path. Products that
+ * need that flow must use cross-subdomain mode (`__Secure-`) or accept it.
+ */
+declare function secureCookieOptions(input: SecureCookieOptionsInput): SecureCookieAdvancedOptions;
+/**
+ * The exact session-token cookie name Better Auth produces for options built
+ * by `secureCookieOptions`, for products that choose credentials by cookie
+ * name. Pass the object `secureCookieOptions` returned.
+ */
+declare function sessionCookieName(advanced: Pick<SecureCookieAdvancedOptions, "cookiePrefix" | "useSecureCookies">): string;
+/**
+ * Better Auth `session` options with the cookie cache off: every request
+ * checks the session row, so a revoked session stops working immediately
+ * instead of until the cached cookie expires (5 minutes by default).
+ */
+declare function secureSessionOptions(): {
+    cookieCache: {
+        enabled: false;
+    };
+};
+interface SecureEmailAndPasswordInput {
+    /** Turn password sign-in on. Off by default: products sign people in
+     * with email codes, social providers or OAuth. */
+    enabled?: boolean;
+}
+/**
+ * Better Auth `emailAndPassword` settings. Password sign-up is off unless a
+ * product opts in: with it on and no verification, anyone can register an
+ * address they don't own and sit on it until the real owner shows up. When
+ * a product does enable passwords, the address must be verified before the
+ * account can sign in.
+ */
+declare function secureEmailAndPasswordOptions(input?: SecureEmailAndPasswordInput): {
+    enabled: false;
+} | {
+    enabled: true;
+    requireEmailVerification: true;
+};
+
+export { type BetterAuthSession, type BetterAuthSessionApi, type CreateOAuthProviderOptionsInput, type IsRecentlyAuthenticatedOptions, type ResolveBetterAuthSessionOptions, type SecureCookieAdvancedOptions, type SecureCookieOptionsInput, type SecureEmailAndPasswordInput, createOAuthProviderOptions, isRecentlyAuthenticated, resolveBetterAuthSession, secureCookieOptions, secureEmailAndPasswordOptions, secureSessionOptions, sessionCookieName };

package/dist/better-auth.js

@@ -49,7 +49,8 @@ async function resolveBetterAuthSession(options, headers) {
         subject: session.user.id,
         email: session.user.email,
         name: session.user.name,
-        scopes: []
+        scopes: [],
+        authenticatedAt: new Date(session.session.createdAt)
       }
     };
   } catch (cause) {
@@ -124,6 +125,87 @@ function createOAuthProviderOptions(input) {
     allowUnauthenticatedClientRegistration: (_b = input.allowUnauthenticatedDynamicClientRegistration) != null ? _b : false
   }, clientRegistrationDefaultScopes ? { clientRegistrationDefaultScopes } : {}), clientRegistrationAllowedScopes ? { clientRegistrationAllowedScopes } : {});
 }
+function isRecentlyAuthenticated(identity, options) {
+  var _a, _b;
+  if (identity.method !== "session") return false;
+  const signedInAt = (_a = identity.authenticatedAt) == null ? void 0 : _a.getTime();
+  if (signedInAt === void 0 || !Number.isFinite(signedInAt)) return false;
+  const age = ((_b = options.now) != null ? _b : /* @__PURE__ */ new Date()).getTime() - signedInAt;
+  return age >= -6e4 && age <= options.maxAgeMs;
+}
+
+// src/secure-cookies.ts
+var COOKIE_PREFIX_PATTERN = /^[A-Za-z0-9_-]+$/;
+var HOST_PREFIX = "__Host-";
+var SECURE_PREFIX = "__Secure-";
+var SESSION_TOKEN_SUFFIX = ".session_token";
+function assertBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch (e) {
+    throw new Error("baseURL must be an absolute URL");
+  }
+  if (!["http:", "https:"].includes(url.protocol)) {
+    throw new Error("baseURL must use http or https");
+  }
+  return url;
+}
+function assertCookiePrefix(value) {
+  if (!COOKIE_PREFIX_PATTERN.test(value)) {
+    throw new Error(
+      "cookiePrefix must be non-empty and contain only letters, digits, '_' or '-'"
+    );
+  }
+  if (value.startsWith(HOST_PREFIX) || value.startsWith(SECURE_PREFIX)) {
+    throw new Error(
+      "cookiePrefix must not include __Host- or __Secure-; the kit adds it"
+    );
+  }
+}
+function secureCookieOptions(input) {
+  var _a, _b;
+  const url = assertBaseUrl(input.baseURL);
+  assertCookiePrefix(input.cookiePrefix);
+  const clientIpHeader = (_a = input.clientIpHeader) == null ? void 0 : _a.trim().toLowerCase();
+  if (input.clientIpHeader !== void 0 && !clientIpHeader) {
+    throw new Error("clientIpHeader must not be empty");
+  }
+  const ipAddress = clientIpHeader ? { ipAddress: { ipAddressHeaders: [clientIpHeader] } } : {};
+  const crossSubdomain = ((_b = input.crossSubDomainCookies) == null ? void 0 : _b.enabled) === true;
+  if (url.protocol !== "https:") {
+    return __spreadValues(__spreadValues({
+      cookiePrefix: input.cookiePrefix
+    }, input.crossSubDomainCookies ? { crossSubDomainCookies: input.crossSubDomainCookies } : {}), ipAddress);
+  }
+  if (crossSubdomain) {
+    return __spreadValues({
+      cookiePrefix: input.cookiePrefix,
+      useSecureCookies: true,
+      crossSubDomainCookies: input.crossSubDomainCookies
+    }, ipAddress);
+  }
+  return __spreadValues({
+    cookiePrefix: `${HOST_PREFIX}${input.cookiePrefix}`,
+    useSecureCookies: false,
+    defaultCookieAttributes: { secure: true, path: "/" }
+  }, ipAddress);
+}
+function sessionCookieName(advanced) {
+  const secure = advanced.useSecureCookies === true ? SECURE_PREFIX : "";
+  return `${secure}${advanced.cookiePrefix}${SESSION_TOKEN_SUFFIX}`;
+}
+function secureSessionOptions() {
+  return { cookieCache: { enabled: false } };
+}
+function secureEmailAndPasswordOptions(input = {}) {
+  return input.enabled === true ? { enabled: true, requireEmailVerification: true } : { enabled: false };
+}
 
 exports.createOAuthProviderOptions = createOAuthProviderOptions;
+exports.isRecentlyAuthenticated = isRecentlyAuthenticated;
 exports.resolveBetterAuthSession = resolveBetterAuthSession;
+exports.secureCookieOptions = secureCookieOptions;
+exports.secureEmailAndPasswordOptions = secureEmailAndPasswordOptions;
+exports.secureSessionOptions = secureSessionOptions;
+exports.sessionCookieName = sessionCookieName;

package/dist/better-auth.mjs

@@ -32,7 +32,8 @@ async function resolveBetterAuthSession(options, headers) {
         subject: session.user.id,
         email: session.user.email,
         name: session.user.name,
-        scopes: []
+        scopes: [],
+        authenticatedAt: new Date(session.session.createdAt)
       }
     };
   } catch (cause) {
@@ -107,5 +108,81 @@ function createOAuthProviderOptions(input) {
     allowUnauthenticatedClientRegistration: (_b = input.allowUnauthenticatedDynamicClientRegistration) != null ? _b : false
   }, clientRegistrationDefaultScopes ? { clientRegistrationDefaultScopes } : {}), clientRegistrationAllowedScopes ? { clientRegistrationAllowedScopes } : {});
 }
+function isRecentlyAuthenticated(identity, options) {
+  var _a, _b;
+  if (identity.method !== "session") return false;
+  const signedInAt = (_a = identity.authenticatedAt) == null ? void 0 : _a.getTime();
+  if (signedInAt === void 0 || !Number.isFinite(signedInAt)) return false;
+  const age = ((_b = options.now) != null ? _b : /* @__PURE__ */ new Date()).getTime() - signedInAt;
+  return age >= -6e4 && age <= options.maxAgeMs;
+}
+
+// src/secure-cookies.ts
+var COOKIE_PREFIX_PATTERN = /^[A-Za-z0-9_-]+$/;
+var HOST_PREFIX = "__Host-";
+var SECURE_PREFIX = "__Secure-";
+var SESSION_TOKEN_SUFFIX = ".session_token";
+function assertBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch (e) {
+    throw new Error("baseURL must be an absolute URL");
+  }
+  if (!["http:", "https:"].includes(url.protocol)) {
+    throw new Error("baseURL must use http or https");
+  }
+  return url;
+}
+function assertCookiePrefix(value) {
+  if (!COOKIE_PREFIX_PATTERN.test(value)) {
+    throw new Error(
+      "cookiePrefix must be non-empty and contain only letters, digits, '_' or '-'"
+    );
+  }
+  if (value.startsWith(HOST_PREFIX) || value.startsWith(SECURE_PREFIX)) {
+    throw new Error(
+      "cookiePrefix must not include __Host- or __Secure-; the kit adds it"
+    );
+  }
+}
+function secureCookieOptions(input) {
+  var _a, _b;
+  const url = assertBaseUrl(input.baseURL);
+  assertCookiePrefix(input.cookiePrefix);
+  const clientIpHeader = (_a = input.clientIpHeader) == null ? void 0 : _a.trim().toLowerCase();
+  if (input.clientIpHeader !== void 0 && !clientIpHeader) {
+    throw new Error("clientIpHeader must not be empty");
+  }
+  const ipAddress = clientIpHeader ? { ipAddress: { ipAddressHeaders: [clientIpHeader] } } : {};
+  const crossSubdomain = ((_b = input.crossSubDomainCookies) == null ? void 0 : _b.enabled) === true;
+  if (url.protocol !== "https:") {
+    return __spreadValues(__spreadValues({
+      cookiePrefix: input.cookiePrefix
+    }, input.crossSubDomainCookies ? { crossSubDomainCookies: input.crossSubDomainCookies } : {}), ipAddress);
+  }
+  if (crossSubdomain) {
+    return __spreadValues({
+      cookiePrefix: input.cookiePrefix,
+      useSecureCookies: true,
+      crossSubDomainCookies: input.crossSubDomainCookies
+    }, ipAddress);
+  }
+  return __spreadValues({
+    cookiePrefix: `${HOST_PREFIX}${input.cookiePrefix}`,
+    useSecureCookies: false,
+    defaultCookieAttributes: { secure: true, path: "/" }
+  }, ipAddress);
+}
+function sessionCookieName(advanced) {
+  const secure = advanced.useSecureCookies === true ? SECURE_PREFIX : "";
+  return `${secure}${advanced.cookiePrefix}${SESSION_TOKEN_SUFFIX}`;
+}
+function secureSessionOptions() {
+  return { cookieCache: { enabled: false } };
+}
+function secureEmailAndPasswordOptions(input = {}) {
+  return input.enabled === true ? { enabled: true, requireEmailVerification: true } : { enabled: false };
+}
 
-export { createOAuthProviderOptions, resolveBetterAuthSession };
+export { createOAuthProviderOptions, isRecentlyAuthenticated, resolveBetterAuthSession, secureCookieOptions, secureEmailAndPasswordOptions, secureSessionOptions, sessionCookieName };

package/dist/express.d.mts

@@ -1,8 +1,39 @@
 import { RequestHandler, Router } from 'express';
-import { a as AuthenticatedIdentity, A as AuthenticationResult } from './types-DJxCmhYu.mjs';
+import { a as AuthenticatedIdentity, A as AuthenticationResult } from './types-sqdNO7Nc.mjs';
 import { VerifyOAuthAccessTokenOptions } from './index.mjs';
 import '@better-auth/oauth-provider/resource-client';
 
+/**
+ * Private networks: the cluster and local development. Fine when clients come
+ * from the public internet. If clients can reach the app from a private
+ * network too, set `TRUST_PROXY` to your proxies' actual addresses or subnet,
+ * or those clients could forge their address (Better Auth gives the same
+ * advice for its own `trustedProxies`).
+ */
+declare const DEFAULT_TRUST_PROXY = "loopback, linklocal, uniquelocal";
+/**
+ * Parses a `TRUST_PROXY` value into what Express's `trust proxy` setting
+ * accepts: a hop count (`1`), `true`/`false`, or a comma-separated list of
+ * addresses, CIDRs and the names `loopback`, `linklocal`, `uniquelocal`.
+ * Empty means {@link DEFAULT_TRUST_PROXY}.
+ */
+declare function parseTrustProxy(raw?: string): boolean | number | string;
+interface CreateClientIpMiddlewareOptions {
+    /** Internal header to carry the resolved client address. */
+    header: string;
+}
+/**
+ * Sets `req.headers[header]` to the client address, overwriting anything the
+ * client sent. Pair it with `secureCookieOptions({ clientIpHeader })` so
+ * Better Auth's rate limiting and session IP never read `X-Forwarded-For`.
+ *
+ * The app must call `app.set("trust proxy", parseTrustProxy(process.env.TRUST_PROXY))`
+ * first and mount this before Better Auth's handler. `req.ip` then walks
+ * `X-Forwarded-For` from the right, skipping trusted proxy hops, so the
+ * attacker-controlled left side never counts.
+ */
+declare function createClientIpMiddleware(options: CreateClientIpMiddlewareOptions): RequestHandler;
+
 declare global {
     namespace Express {
         interface Request {
@@ -45,4 +76,4 @@ interface CreateOAuthPagesRouterOptions {
 }
 declare function createOAuthPagesRouter(rawOptions: CreateOAuthPagesRouterOptions): Router;
 
-export { type CreateOAuthBearerMiddlewareOptions, type CreateOAuthPagesRouterOptions, type HostedLoginCaptcha, type HostedLoginMethod, createOAuthBearerMiddleware, createOAuthPagesRouter };
+export { type CreateClientIpMiddlewareOptions, type CreateOAuthBearerMiddlewareOptions, type CreateOAuthPagesRouterOptions, DEFAULT_TRUST_PROXY, type HostedLoginCaptcha, type HostedLoginMethod, createClientIpMiddleware, createOAuthBearerMiddleware, createOAuthPagesRouter, parseTrustProxy };

package/dist/express.d.ts

@@ -1,8 +1,39 @@
 import { RequestHandler, Router } from 'express';
-import { a as AuthenticatedIdentity, A as AuthenticationResult } from './types-DJxCmhYu.js';
+import { a as AuthenticatedIdentity, A as AuthenticationResult } from './types-sqdNO7Nc.js';
 import { VerifyOAuthAccessTokenOptions } from './index.js';
 import '@better-auth/oauth-provider/resource-client';
 
+/**
+ * Private networks: the cluster and local development. Fine when clients come
+ * from the public internet. If clients can reach the app from a private
+ * network too, set `TRUST_PROXY` to your proxies' actual addresses or subnet,
+ * or those clients could forge their address (Better Auth gives the same
+ * advice for its own `trustedProxies`).
+ */
+declare const DEFAULT_TRUST_PROXY = "loopback, linklocal, uniquelocal";
+/**
+ * Parses a `TRUST_PROXY` value into what Express's `trust proxy` setting
+ * accepts: a hop count (`1`), `true`/`false`, or a comma-separated list of
+ * addresses, CIDRs and the names `loopback`, `linklocal`, `uniquelocal`.
+ * Empty means {@link DEFAULT_TRUST_PROXY}.
+ */
+declare function parseTrustProxy(raw?: string): boolean | number | string;
+interface CreateClientIpMiddlewareOptions {
+    /** Internal header to carry the resolved client address. */
+    header: string;
+}
+/**
+ * Sets `req.headers[header]` to the client address, overwriting anything the
+ * client sent. Pair it with `secureCookieOptions({ clientIpHeader })` so
+ * Better Auth's rate limiting and session IP never read `X-Forwarded-For`.
+ *
+ * The app must call `app.set("trust proxy", parseTrustProxy(process.env.TRUST_PROXY))`
+ * first and mount this before Better Auth's handler. `req.ip` then walks
+ * `X-Forwarded-For` from the right, skipping trusted proxy hops, so the
+ * attacker-controlled left side never counts.
+ */
+declare function createClientIpMiddleware(options: CreateClientIpMiddlewareOptions): RequestHandler;
+
 declare global {
     namespace Express {
         interface Request {
@@ -45,4 +76,4 @@ interface CreateOAuthPagesRouterOptions {
 }
 declare function createOAuthPagesRouter(rawOptions: CreateOAuthPagesRouterOptions): Router;
 
-export { type CreateOAuthBearerMiddlewareOptions, type CreateOAuthPagesRouterOptions, type HostedLoginCaptcha, type HostedLoginMethod, createOAuthBearerMiddleware, createOAuthPagesRouter };
+export { type CreateClientIpMiddlewareOptions, type CreateOAuthBearerMiddlewareOptions, type CreateOAuthPagesRouterOptions, DEFAULT_TRUST_PROXY, type HostedLoginCaptcha, type HostedLoginMethod, createClientIpMiddleware, createOAuthBearerMiddleware, createOAuthPagesRouter, parseTrustProxy };

package/dist/express.js

@@ -34,6 +34,25 @@ var __objRest = (source, exclude) => {
   return target;
 };
 
+// src/client-ip.ts
+var DEFAULT_TRUST_PROXY = "loopback, linklocal, uniquelocal";
+function parseTrustProxy(raw) {
+  const value = raw == null ? void 0 : raw.trim();
+  if (!value) return DEFAULT_TRUST_PROXY;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (/^\d+$/.test(value)) return Number.parseInt(value, 10);
+  return value;
+}
+function createClientIpMiddleware(options) {
+  const header = options.header.trim().toLowerCase();
+  if (!header) throw new Error("header must not be empty");
+  return (req, _res, next) => {
+    req.headers[header] = req.ip || req.socket.remoteAddress || "unknown";
+    next();
+  };
+}
+
 // src/verify-access-token.ts
 function requireAbsoluteUrl(value, field) {
   let url;
@@ -433,5 +452,8 @@ function createOAuthPagesRouter(rawOptions) {
   return router;
 }
 
+exports.DEFAULT_TRUST_PROXY = DEFAULT_TRUST_PROXY;
+exports.createClientIpMiddleware = createClientIpMiddleware;
 exports.createOAuthBearerMiddleware = createOAuthBearerMiddleware;
 exports.createOAuthPagesRouter = createOAuthPagesRouter;
+exports.parseTrustProxy = parseTrustProxy;

package/dist/express.mjs

@@ -2,6 +2,25 @@ import { verifyOAuthAccessToken, validateOAuthVerificationOptions } from './chun
 import { __objRest, __spreadProps, __spreadValues } from './chunk-FWCSY2DS.mjs';
 import { Router } from 'express';
 
+// src/client-ip.ts
+var DEFAULT_TRUST_PROXY = "loopback, linklocal, uniquelocal";
+function parseTrustProxy(raw) {
+  const value = raw == null ? void 0 : raw.trim();
+  if (!value) return DEFAULT_TRUST_PROXY;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (/^\d+$/.test(value)) return Number.parseInt(value, 10);
+  return value;
+}
+function createClientIpMiddleware(options) {
+  const header = options.header.trim().toLowerCase();
+  if (!header) throw new Error("header must not be empty");
+  return (req, _res, next) => {
+    req.headers[header] = req.ip || req.socket.remoteAddress || "unknown";
+    next();
+  };
+}
+
 // src/express.ts
 function setBearerChallenge(response, resourceMetadataUrl) {
   if (resourceMetadataUrl) {
@@ -320,4 +339,4 @@ function createOAuthPagesRouter(rawOptions) {
   return router;
 }
 
-export { createOAuthBearerMiddleware, createOAuthPagesRouter };
+export { DEFAULT_TRUST_PROXY, createClientIpMiddleware, createOAuthBearerMiddleware, createOAuthPagesRouter, parseTrustProxy };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { O as OAuthResourceClient, A as AuthenticationResult } from './types-DJxCmhYu.mjs';
-export { a as AuthenticatedIdentity } from './types-DJxCmhYu.mjs';
+import { O as OAuthResourceClient, A as AuthenticationResult } from './types-sqdNO7Nc.mjs';
+export { a as AuthenticatedIdentity } from './types-sqdNO7Nc.mjs';
 import '@better-auth/oauth-provider/resource-client';
 
 interface VerifyOAuthAccessTokenOptions {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { O as OAuthResourceClient, A as AuthenticationResult } from './types-DJxCmhYu.js';
-export { a as AuthenticatedIdentity } from './types-DJxCmhYu.js';
+import { O as OAuthResourceClient, A as AuthenticationResult } from './types-sqdNO7Nc.js';
+export { a as AuthenticatedIdentity } from './types-sqdNO7Nc.js';
 import '@better-auth/oauth-provider/resource-client';
 
 interface VerifyOAuthAccessTokenOptions {

package/dist/mcp.d.mts

@@ -1,5 +1,5 @@
 import { Router } from 'express';
-import { O as OAuthResourceClient } from './types-DJxCmhYu.mjs';
+import { O as OAuthResourceClient } from './types-sqdNO7Nc.mjs';
 import '@better-auth/oauth-provider/resource-client';
 
 interface BetterAuthMetadataApi {

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { Router } from 'express';
-import { O as OAuthResourceClient } from './types-DJxCmhYu.js';
+import { O as OAuthResourceClient } from './types-sqdNO7Nc.js';
 import '@better-auth/oauth-provider/resource-client';
 
 interface BetterAuthMetadataApi {

package/dist/{types-DJxCmhYu.d.mts → types-sqdNO7Nc.d.mts}

@@ -7,6 +7,8 @@ type AuthenticatedIdentity = {
     email: string;
     name?: string | null;
     scopes: [];
+    /** When the session was created (the sign-in time), for step-up checks. */
+    authenticatedAt: Date;
 } | {
     method: "oauth";
     issuer: string;

package/dist/{types-DJxCmhYu.d.ts → types-sqdNO7Nc.d.ts}

@@ -7,6 +7,8 @@ type AuthenticatedIdentity = {
     email: string;
     name?: string | null;
     scopes: [];
+    /** When the session was created (the sign-in time), for step-up checks. */
+    authenticatedAt: Date;
 } | {
     method: "oauth";
     issuer: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codelitdev/oauth-server-kit",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Lean Better Auth OAuth authentication framework for web, mobile, REST, and MCP surfaces.",
   "author": "CodeLit",
   "license": "MIT",
@@ -79,20 +79,20 @@
     "tag": "latest"
   },
   "peerDependencies": {
-    "@better-auth/oauth-provider": "^1.7.2",
-    "better-auth": "^1.7.2",
+    "@better-auth/oauth-provider": "^1.7.16",
+    "better-auth": "^1.7.16",
     "express": "^4.21.2"
   },
   "devDependencies": {
-    "@better-auth/core": "1.7.2",
-    "@better-auth/oauth-provider": "1.7.2",
-    "@better-auth/utils": "0.4.2",
-    "@better-fetch/fetch": "1.3.1",
+    "@better-auth/core": "1.7.22",
+    "@better-auth/oauth-provider": "1.7.22",
+    "@better-auth/utils": "0.5.1",
+    "@better-fetch/fetch": "1.3.3",
     "@types/express": "^4.17.20",
     "@types/node": "^22.14.1",
     "@types/bun": "^1.4.1",
-    "better-auth": "1.7.2",
-    "better-call": "1.4.0",
+    "better-auth": "1.7.22",
+    "better-call": "1.4.5",
     "express": "^4.21.2",
     "rimraf": "^5.0.0",
     "tsup": "^8.3.0",