@@ -0,0 +1,15 @@
+---
+'@objectstack/plugin-auth': patch
+---
+
+fix(plugin-auth): a session stores its client address in RFC 5952 text, and is born with `last_activity_at`
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+Setup › Sessions printed a localhost session's IP as `0000:0000:0000:0000:0000:0000:0000:0000` and left Last Activity empty until the session's first request. Both are fixed in the data a sign-in stores; the list still prints the columns as plain text.
+
+- **The address is the client's, in RFC 5952 text.** `sys_session.ip_address` is now the address the server established for the request (the client-address trust rule: forwarded headers only under `server.trustProxy`, the connection's peer otherwise), with IPv6 compressed — `::1`, `2001:db8::1` — and IPv4 unchanged. better-auth's own reader used to fill the column with its rate-limit bucket instead: every IPv6 address expanded to eight groups and masked to its /64 network, so `::1` read as `0000:…:0000` and `2001:db8::1` as `2001:0db8:0000:0000:0000:0000:0000:0000`. An IPv4-mapped address is stored as the IPv4 address it maps (`::ffff:203.0.113.7` → `203.0.113.7`), so an IPv4 client reads the same whether a dual-stack or an IPv4 listener accepted it; `last_login_ip` and the refused-sign-in audit rows, which carried the mapped text, now carry that one too. A session minted with no established address (a programmatic `auth.api.*` call) keeps better-auth's value, in the same text. An unparseable value is stored as it came.
+- **One text on every row of a sign-in.** The `login_failed` / `account_locked` audit rows and `sys_user.last_login_ip` carry the same text as the session row and its `login` row. `signInClientFingerprint(ctx, establishedAddress?)` takes the established address as an optional second argument.
+- **`last_activity_at` is written at creation**, equal to `created_at`. The activity heartbeat is unchanged; its first write now comes on the first request more than a minute after sign-in rather than on the very first request.
+- **Unchanged:** better-auth's per-address rate limiter still keys on its own bucket, the ADR-0069 D5 allow-list still judges the trust rule's answer as it came, and existing session rows are not rewritten.
@@ -56,6 +56,8 @@ import {
 import { withSystemReadContext } from './objectql-adapter.js';
 import { emitAuthSessionAuditEvent, loginEventFor, logoutEventFor } from './auth-session-audit.js';
 import { holdPrincipalSessionExpiry } from './principal-session-mint.js';
+import { canonicalClientAddress } from './client-address-canonical.js';
+import { readRequestClientAddress } from './request-client-address.js';
 
 /**
  * The `AuthManager` members the functions below read — every one of them, and
@@ -266,7 +268,7 @@ export function composeDatabaseHooks(
       return; // never break session create
     }
   };
-  const sessionBefore =
+  const sessionActiveOrgBefore =
     this.config.autoActiveOrganization !== false
       ? async (session: any, ctx: any) => {
           let draft = session;
@@ -282,12 +284,37 @@ export function composeDatabaseHooks(
         }
       : hostSessionBefore;
 
+  // [#26638] The session row's `ip_address` is the address the server
+  // established for this request (the client-address trust rule,
+  // `client-address.ts`, carried in the request state by `handleRequest`), in
+  // its stored text (`client-address-canonical.ts`). better-auth fills the
+  // field from its own reader, which re-derives that address and stores its
+  // rate-limit bucket instead: an IPv6 address expanded and masked to its /64
+  // network, an IPv4-mapped one unmapped. No established address (a
+  // programmatic `auth.api.*` call) ⇒ better-auth's value, in the same text.
+  // It runs FIRST, so the steps below — the host's included — see the
+  // captured address, and a host that sets `ipAddress` itself still wins.
+  const captureSessionAddress = async (session: any) => {
+    const derived = typeof session?.ipAddress === 'string' ? session.ipAddress : undefined;
+    const ipAddress = canonicalClientAddress((await readRequestClientAddress()) ?? derived);
+    return ipAddress === derived ? session : { ...session, ipAddress };
+  };
+  const sessionBefore = async (session: any, ctx: any) => {
+    const captured = await captureSessionAddress(session);
+    const result = sessionActiveOrgBefore ? await sessionActiveOrgBefore(captured, ctx) : undefined;
+    if (result === false) return false;
+    if (result && typeof result === 'object' && 'data' in result) {
+      return { data: { ...captured, ...(result as any).data } };
+    }
+    return captured === session ? result : { data: captured };
+  };
+
   // [#8144] The `login` / `logout` audit writers (#7675 sub-issue A). See
   // `auth-session-audit.ts` for why these two hooks and no others, and why
   // logout reads the endpoint path from the hook's own `ctx` argument rather
   // than from the ambient auth context.
   //
-  // Host hooks chain FIRST and keep their result, exactly as `sessionBefore`
+  // Host hooks chain FIRST and keep their result, exactly as `sessionActiveOrgBefore`
   // above does: the audit row is an observation, never a participant in what
   // better-auth decides. Both emitters are awaited but cannot throw
   // (`emitAuthSessionAuditEvent` swallows), so neither can turn a valid
@@ -378,7 +405,7 @@ export function composeDatabaseHooks(
   // `user.create.before` is a seam only a CREATION traverses, so a later
   // email UPDATE to the owner address structurally cannot inherit the
   // stamp. Host hook chains FIRST and keeps its result shape, exactly as
-  // `sessionBefore` above does; a host `false` (refuse the creation) is
+  // `sessionActiveOrgBefore` above does; a host `false` (refuse the creation) is
   // honoured before the stamp is even consumed.
   const hostUserBefore = (host as any)?.user?.create?.before;
   const userBefore = async (user: any, ctx: any) => {
@@ -426,10 +453,7 @@ export function composeDatabaseHooks(
       ...((host as any)?.session ?? {}),
       create: {
         ...((host as any)?.session?.create ?? {}),
-        // `sessionBefore` is undefined only when `autoActiveOrganization` is
-        // off AND the host supplied none — spread it in conditionally so the
-        // key is absent rather than explicitly `undefined`.
-        ...(sessionBefore ? { before: sessionBefore } : {}),
+        before: sessionBefore,
         after: sessionCreateAfter,
       },
       update: {
 
@@ -47,6 +47,8 @@ import {
   signInFailureEventFor,
   SIGN_IN_EMAIL_PATH,
 } from './auth-session-audit.js';
+import { canonicalClientAddress } from './client-address-canonical.js';
+import { readRequestClientAddress } from './request-client-address.js';
 
 /**
  * The `AuthManager` members the functions below read — every one of them, and
@@ -87,7 +89,7 @@ export async function assertAccountNotLocked(this: Pick<SignInLockoutHost, 'conf
         signInFailureEventFor(lockedUserId, {
           path: SIGN_IN_EMAIL_PATH,
           reason: 'ACCOUNT_LOCKED',
-          fingerprint: signInClientFingerprint(ctx),
+          fingerprint: signInClientFingerprint(ctx, await readRequestClientAddress()),
         }),
       );
     }
@@ -164,7 +166,7 @@ export async function auditRefusedSignIn(
   if (!sink) return;
   const userId = lockStamped?.userId ?? (await this.resolveSignInAccountId(email));
   if (!userId) return;
-  const fingerprint = signInClientFingerprint(ctx);
+  const fingerprint = signInClientFingerprint(ctx, await readRequestClientAddress());
   await emitAuthSessionAuditEvent(
     sink,
     signInFailureEventFor(userId, {
@@ -242,9 +244,11 @@ export async function stampLastLogin(this: Pick<SignInLockoutHost, 'getDataEngin
   try {
     const SYSTEM_CTX = { isSystem: true, attributedUserId: userId, positions: [], permissions: [] };
     const patch: Record<string, unknown> = { id: userId, last_login_at: new Date() };
-    // Cap to the column width (IPv6 textual max 45) — a malformed/oversized
-    // forwarded header must not blow up the write.
-    if (ip) patch.last_login_ip = ip.slice(0, 45);
+    // [#26638] In the RFC 5952 text the session row stores for the same
+    // sign-in (`client-address-canonical.ts`). Cap to the column width (IPv6
+    // textual max 45) — a malformed/oversized forwarded header must not blow
+    // up the write.
+    if (ip) patch.last_login_ip = canonicalClientAddress(ip).slice(0, 45);
     await engine.update('sys_user', patch, { context: SYSTEM_CTX } as any);
   } catch (e) {
     // Never break the auth response. [#12981] But this write is the ONLY
 
@@ -5078,7 +5078,10 @@ describe('AuthManager', () => {
         dataEngine: makeEngine([OWNER_ROW]),
         autoActiveOrganization: false,
       });
-      expect(hooks.session?.create?.before).toBeUndefined();
+      // [#26638] `create.before` is always installed (it stamps the session's
+      // client address); with the default off it fills no organization.
+      const result = await hooks.session.create.before({ userId: 'u1' });
+      expect(result?.data?.activeOrganizationId).toBeUndefined();
     });
 
     it('never breaks session create on engine errors', async () => {
 
@@ -68,6 +68,7 @@ import { registerLastAdminGuard } from './last-admin-guard.js';
 import { registerApiKeyRestoreGuard } from './api-key-restore-guard.js';
 import { registerMembershipEndedSessionTrigger } from './membership-ended-session.js';
 import { registerMemberRoleCanonicalization } from './member-role-canonical.js';
+import { registerSessionFirstActivity } from './session-first-activity.js';
 import { registerExternalMembershipGuard } from './external-membership.js';
 import { SYS_USER_PROFILE_EDIT_FIELDS } from './sys-user-writable-fields.js';
 import { MANAGED_EXTENSION_EDITABLE_FIELDS } from './managed-extension-fields.js';
@@ -999,6 +1000,20 @@ export class AuthPlugin implements Plugin {
       }
     }
 
+    // [#26638] A session is born with `last_activity_at` = the `created_at`
+    // it is stored with, after ObjectQL's own stamp (session-first-activity.ts).
+    // Registered here rather than on `kernel:ready`: the development admin
+    // seed's sign-up, itself a `kernel:ready` hook, mints a session as well.
+    // An engine that cannot take hooks (mock mode) stores no session row.
+    try {
+      const ql = ctx.getService<IObjectQLEngine>('objectql');
+      if (ql && typeof ql.registerHook === 'function') {
+        registerSessionFirstActivity(ql, { packageId: 'com.objectstack.plugin-auth.session-first-activity' });
+      }
+    } catch {
+      // No `objectql` service (mock mode): nothing to register on.
+    }
+
     // [#8009] Move any provider row still holding a CLEARTEXT OIDC client
     // secret in `oidc_config` into the encrypted column. Registered
     // unconditionally (not under `registerRoutes`) because the disposition of
 
@@ -158,11 +158,10 @@ describe('[#8144] session.create.after records a login', () => {
     expect(recordAuthEvent).toHaveBeenCalledTimes(1);
   });
 
-  it('is wired even when autoActiveOrganization is off (which removes create.before)', async () => {
+  it('is wired even when autoActiveOrganization is off (which removes the active-organization default)', async () => {
     const { hooks, recordAuthEvent } = hooksWithSink({ autoActiveOrganization: false });
     // The pre-#8144 shape omitted the whole `session` block when there was no
     // `before` hook to install — the audit writer must not inherit that gate.
-    expect(hooks.session?.create?.before).toBeUndefined();
     await hooks.session.create.after(SESSION, { path: '/sign-in/email' });
     expect(recordAuthEvent).toHaveBeenCalledTimes(1);
   });
 
@@ -70,8 +70,8 @@
  *
  * Both name the account the sign-in resolved to, the outcome (the action plus
  * the refusal's machine code), and the client fingerprint read by the same rule
- * better-auth applies when it stamps a session row — so a refused attempt and a
- * successful one from the same client carry the same `ip_address`.
+ * the session hook applies when it stamps a session row — so a refused attempt
+ * and a successful one from the same client carry the same `ip_address`.
  *
  * ⛔ Neither event carries anything the caller typed. The password is never
  * read here, and the submitted identifier is never recorded either: the row
@@ -81,6 +81,7 @@
  */
 
 import { getIP } from '@better-auth/core/utils/ip';
+import { canonicalClientAddress } from './client-address-canonical.js';
 
 /**
  * The audit sink's shape, declared LOCALLY so plugin-auth takes no runtime
@@ -205,26 +206,32 @@ export interface SignInClientFingerprint {
 }
 
 /**
- * Read the client fingerprint of a sign-in request by better-auth's OWN rule —
- * the one `internalAdapter.createSession` applies when it stamps a session row
- * (`getIP(headers, options)` over the endpoint's headers, and the
- * `user-agent` header), which is where every `login` row's `ip_address` comes
- * from. A refused sign-in mints no session row to copy them from, so the same
+ * Read the client fingerprint of a sign-in request by the rule a session row
+ * is stamped by, which is where every `login` row's `ip_address` comes from:
+ * `establishedAddress` — the address the server established for the request,
+ * which the caller reads from `handleRequest`'s request state
+ * (`readRequestClientAddress`) — else better-auth's own
+ * `getIP(headers, options)` over the endpoint's headers, either in its
+ * RFC 5952 text (`client-address-canonical.ts`); and the `user-agent` header.
+ * A refused sign-in mints no session row to copy them from, so the same
  * resolution is applied to the same request instead. ⛔ Not a second IP rule:
- * whatever better-auth's `advanced.ipAddress` configuration answers for a
- * session row, it answers here.
+ * the session hook (`auth-manager-database-hooks.ts`, `session.create.before`)
+ * answers the same two sources in the same order.
  */
-export function signInClientFingerprint(ctx: unknown): SignInClientFingerprint {
+export function signInClientFingerprint(ctx: unknown, establishedAddress?: string): SignInClientFingerprint {
   const c = ctx as { headers?: unknown; request?: { headers?: unknown }; context?: { options?: unknown } } | null;
   const headers = (c?.headers ?? c?.request?.headers) as Headers | undefined;
   if (!headers || typeof (headers as Headers).get !== 'function') return {};
-  let ipAddress: string | undefined;
-  try {
-    const options = c?.context?.options as Parameters<typeof getIP>[1] | undefined;
-    ipAddress = options ? str(getIP(headers, options)) : undefined;
-  } catch {
-    ipAddress = undefined;
+  let ipAddress = str(establishedAddress);
+  if (!ipAddress) {
+    try {
+      const options = c?.context?.options as Parameters<typeof getIP>[1] | undefined;
+      ipAddress = options ? str(getIP(headers, options)) : undefined;
+    } catch {
+      ipAddress = undefined;
+    }
   }
+  ipAddress = canonicalClientAddress(ipAddress);
   const userAgent = str(headers.get('user-agent'));
   return {
     ...(ipAddress ? { ipAddress } : {}),
 
@@ -0,0 +1,54 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// The stored text of a client address (`./client-address-canonical.ts`):
+// an IPv4-mapped address unmapped, RFC 5952 for other IPv6, the value as it
+// came otherwise. The integration half —
+// that every seam storing a sign-in's address goes through it — is
+// `session-client-address-capture.test.ts`.
+
+import { describe, it, expect } from 'vitest';
+import { canonicalClientAddress } from './client-address-canonical';
+
+describe('canonicalClientAddress', () => {
+  it.each([
+    // The four forms the card names.
+    ['the unspecified address in full', '0000:0000:0000:0000:0000:0000:0000:0000', '::'],
+    ['loopback in full', '0000:0000:0000:0000:0000:0000:0000:0001', '::1'],
+    ['a documentation address with a zero run', '2001:0db8:0000:0000:0000:0000:0000:0001', '2001:db8::1'],
+    ['IPv4', '203.0.113.7', '203.0.113.7'],
+    // RFC 5952 §4.
+    ['uppercase hexadecimal (§4.3)', '2001:DB8::ABCD', '2001:db8::abcd'],
+    ['leading zeros in a group (§4.1)', '2001:0db8::0001', '2001:db8::1'],
+    ['the longest zero run, not the first (§4.2.3)', '2001:0:0:1:0:0:0:1', '2001:0:0:1::1'],
+    ['the first of two equal runs (§4.2.3)', '2001:db8:0:0:1:0:0:1', '2001:db8::1:0:0:1'],
+    ['a single zero group is not compressed (§4.2.2)', '2001:db8:0:1:1:1:1:1', '2001:db8:0:1:1:1:1:1'],
+    ['a misplaced :: is moved to the longest run', '2001:db8::1:0:0:0:1', '2001:db8:0:1::1'],
+    ['already canonical', '::1', '::1'],
+    // An IPv4-mapped address is the IPv4 address it maps.
+    ['IPv4-mapped', '::ffff:203.0.113.7', '203.0.113.7'],
+    ['IPv4-mapped loopback (a local dual-stack listener)', '::ffff:127.0.0.1', '127.0.0.1'],
+    ['IPv4-mapped in hexadecimal', '0:0:0:0:0:FFFF:CB00:7107', '203.0.113.7'],
+    ['IPv4-mapped in full, uppercase', '0000:0000:0000:0000:0000:FFFF:203.0.113.7', '203.0.113.7'],
+    ['IPv4-mapped with a zone drops the zone', '::ffff:203.0.113.7%eth0', '203.0.113.7'],
+    ['::ffff:0:0/96 only: the IPv4-translated prefix is not unmapped', '::ffff:0:203.0.113.7', '::ffff:0:cb00:7107'],
+    ['an embedded IPv4 that is not mapped is written in hexadecimal', '64:ff9b::203.0.113.7', '64:ff9b::cb00:7107'],
+    // A zone identifier is kept as it came.
+    ['a zone identifier', 'FE80:0:0:0:0:0:0:1%eth0', 'fe80::1%eth0'],
+  ])('%s: %s → %s', (_label, input, expected) => {
+    expect(canonicalClientAddress(input)).toBe(expected);
+  });
+
+  it.each([
+    ['an unparseable string', 'not-an-address'],
+    ['a bracketed address', '[::1]'],
+    ['an address with a port', '203.0.113.7:443'],
+    ['surrounding whitespace', ' ::1 '],
+    ['the empty string', ''],
+  ])('%s is returned exactly as it came', (_label, input) => {
+    expect(canonicalClientAddress(input)).toBe(input);
+  });
+
+  it('undefined stays undefined', () => {
+    expect(canonicalClientAddress(undefined)).toBeUndefined();
+  });
+});