GET /log returns each row's client (ua, ipHash, referer), and logs where Cloudflare places it (city/region/asOrg)

`d1AuditQuery().recent()` now also selects `ua`, `ip_hash` and `referer`, which were already recorded. `requestMeta` reads `request.cf.{city, region, asOrganization}` into three new nullable columns (`migrations/0002_access_log_location.sql`, additive). IPs stay HMAC'd and are never stored raw. Spec from disk-tree m3, moved to `specs/done/`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DyJyzSYpRxJuL6x6NyjpG3

Author: ryan-williams

README.md

@@ -61,7 +61,7 @@ Peer deps are all optional and only needed for what you use: `@cloudflare/worker
 
 ## Migrations
 
-`migrations/0001_init.sql` is the whole schema. A fresh database applies it (`wrangler d1 migrations apply` with `migrations_dir` pointed at the package's `migrations/`, as the demo does, or its content copied into your own sequence alongside your app's tables).
+`migrations/0001_init.sql` is the baseline schema, and `0002_access_log_location.sql` adds the log's location columns. A fresh database applies it (`wrangler d1 migrations apply` with `migrations_dir` pointed at the package's `migrations/`, as the demo does, or its content copied into your own sequence alongside your app's tables).
 
 **Pre-1.0, migrations are squashed**: a schema change lands as a new numbered file, and once every known database has applied it, the directory is collapsed back into one baseline rather than kept as history. To move an existing database across a squash, bring it to the previous head (apply the pre-squash files from the SHA you're on), then mark the new files applied without running them:
 
@@ -157,7 +157,7 @@ A verified address that policy rejects redirects with `?denied=<email>` rather t
 
 `gate.update(id, patch)` changes a link's terms after the fact — expiry, cap, TTL, memo — so extending a deadline doesn't mean minting and re-sending a second link. (`sessionTtlS` is baked into the cookie at redeem, so it only affects future redemptions.)
 
-**The access log** is one store for auth-lifecycle events and (optionally) views, so "who viewed what" joins to `grants` natively. Lifecycle events always log; `view` events are deduped per (session, path, hour) by a partial unique index, and are **off by default** — turn them on alongside the "access is logged" disclosure copy, not silently. Client IPs are never stored, only `HMAC(ip, secret)`.
+**The access log** is one store for auth-lifecycle events and (optionally) views, so "who viewed what" joins to `grants` natively. Lifecycle events always log; `view` events are deduped per (session, path, hour) by a partial unique index, and are **off by default** — turn them on alongside the "access is logged" disclosure copy, not silently. Client IPs are never stored, only `HMAC(ip, secret)`. In their place each row keeps where Cloudflare places the client (`request.cf` city, region, and network operator, e.g. "Comcast"), alongside the country, user agent and referer; `GET <basePath>/log` returns all of them, so an admin can tell whether a redeem came from the person the link was sent to.
 
 **Magic links / passwordless sign-up.** `anyEmailPolicy` auto-approves any address, mints a grant bound to it, and hands it to `notify` — which becomes a real sign-in flow once `notify` can send mail:
 

migrations/0002_access_log_location.sql

@@ -0,0 +1,6 @@
+-- Where a client is, from Cloudflare's `request.cf`, in place of its address
+-- (which stays an HMAC in `ip_hash`). Additive: no table rebuild, so a
+-- consumer's prod D1 takes it in place.
+ALTER TABLE access_log ADD COLUMN city TEXT;
+ALTER TABLE access_log ADD COLUMN region TEXT;
+ALTER TABLE access_log ADD COLUMN as_org TEXT;  -- network operator (`cf.asOrganization`)

specs/log-client-fields.md specs/done/log-client-fields.mdspecs/log-client-fields.md renamed to specs/done/log-client-fields.md

@@ -27,3 +27,11 @@ Ryan's call: keep IPs hashed, never stored raw, and log the location and network
 ## Consumer
 
 disk-tree's `GrantLog` already renders `ua` / `ip_hash` when present (hidden columns otherwise); it will add `city`/`region`/`as_org` beside `country`. Once this ships as a dist build, disk-tree bumps `@open-athena/auth` in `site/package.json` and applies the new migration to its D1.
+
+## As built (auth, 2026-10-07)
+
+- `StoredEvent` (from `d1AuditQuery().recent()`, so `GET /log`) gains `ua`, `ipHash`, `referer`, `city`, `region`, `asOrg`, all nullable.
+- `migrations/0002_access_log_location.sql`: three `ALTER TABLE access_log ADD COLUMN`s (`city`, `region`, `as_org`). Additive, so a prod D1 takes it in place. It stays a separate file until the next pre-1.0 squash.
+- `requestMeta` reads `request.cf.{city, region, asOrganization}` (null off Cloudflare). It already feeds every logged event, so redeem, deny, view, request and sign-in rows all carry them. `access_log_daily` rollups are unchanged and still keyed by country.
+- Tests: `routes.test.ts` "returns each row's client…" (a request with a `cf` object lands all three fields; one without leaves them null), and `schema.test.mjs` pins the new columns and file.
+- disk-tree: bump `@open-athena/auth` to the dist build of this commit, then `wrangler d1 migrations apply` (or apply `0002` by hand if its D1 copies the package's SQL into its own sequence).

src/adapters/d1.ts

@@ -431,7 +431,8 @@ export function d1AuditQuery(db: D1Database): AuditQuery {
       }
       const { results } = await db
         .prepare(
-          `SELECT l.id, l.ts, l.event, l.grant_id, l.session_sub, l.path, l.reason, l.country
+          `SELECT l.id, l.ts, l.event, l.grant_id, l.session_sub, l.path, l.reason, l.country,
+                  l.city, l.region, l.as_org, l.ua, l.ip_hash, l.referer
              FROM access_log l ${join}
              ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
             ORDER BY l.id DESC LIMIT ?`,
@@ -446,6 +447,12 @@ export function d1AuditQuery(db: D1Database): AuditQuery {
           path: string | null
           reason: string | null
           country: string | null
+          city: string | null
+          region: string | null
+          as_org: string | null
+          ua: string | null
+          ip_hash: string | null
+          referer: string | null
         }>()
       return results.map(r => ({
         id: r.id,
@@ -456,6 +463,12 @@ export function d1AuditQuery(db: D1Database): AuditQuery {
         path: r.path,
         reason: r.reason,
         country: r.country,
+        city: r.city,
+        region: r.region,
+        asOrg: r.as_org,
+        ua: r.ua,
+        ipHash: r.ip_hash,
+        referer: r.referer,
       }))
     },
   }
@@ -481,8 +494,8 @@ export function d1AuditSink(db: D1Database): AuditSink {
       const bucket = dedupe ? Math.floor(e.ts / 3600) : null
       await db
         .prepare(
-          `INSERT INTO access_log (ts, event, grant_id, session_sub, path, status, ip_hash, ua, country, referer, reason, bucket)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          `INSERT INTO access_log (ts, event, grant_id, session_sub, path, status, ip_hash, ua, country, city, region, as_org, referer, reason, bucket)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
            ON CONFLICT DO NOTHING`,
         )
         .bind(
@@ -495,6 +508,9 @@ export function d1AuditSink(db: D1Database): AuditSink {
           e.ipHash ?? null,
           e.ua ?? null,
           e.country ?? null,
+          e.city ?? null,
+          e.region ?? null,
+          e.asOrg ?? null,
           e.referer ?? null,
           e.reason ?? null,
           bucket,

src/core/audit.ts

@@ -34,6 +34,11 @@ export interface AccessEvent {
   ipHash?: string | null
   ua?: string | null
   country?: string | null
+  /** Where and on what network the client is, from Cloudflare's `request.cf`: enough to tell "the person I sent it to" from "someone else", without keeping an address. */
+  city?: string | null
+  region?: string | null
+  /** The client's network operator (`cf.asOrganization`), e.g. "Comcast" or "Amazon.com". */
+  asOrg?: string | null
   referer?: string | null
   /**
    * Event detail. On `deny`: `expired`, `revoked`, `disabled`, `exhausted`,
@@ -56,21 +61,37 @@ export interface RequestMeta {
   ipHash: string | null
   ua: string | null
   country: string | null
+  city: string | null
+  region: string | null
+  asOrg: string | null
   referer: string | null
 }
 
+/** The slice of Cloudflare's `request.cf` that gets logged. */
+interface CfLocation {
+  city?: string
+  region?: string
+  asOrganization?: string
+}
+
 /**
- * Pull the loggable request metadata. Header-based (not `request.cf`) so this
- * stays runtime-agnostic; CF populates `CF-Connecting-IP`/`CF-IPCountry` for free.
+ * Pull the loggable request metadata. The address and country come from
+ * headers, which CF populates (`CF-Connecting-IP`/`CF-IPCountry`) and other
+ * runtimes can set. City, region and network come from `request.cf` and are
+ * null off Cloudflare.
  */
 export async function requestMeta(req: Request, ipSecret: string): Promise<RequestMeta> {
   const h = req.headers
+  const cf = (req as Request & { cf?: CfLocation }).cf
   const ip = h.get('CF-Connecting-IP') ?? h.get('X-Forwarded-For')?.split(',')[0]?.trim() ?? null
   return {
     path: new URL(req.url).pathname,
     ipHash: ip ? await hashIp(ip, ipSecret) : null,
     ua: h.get('User-Agent'),
     country: h.get('CF-IPCountry'),
+    city: cf?.city || null,
+    region: cf?.region || null,
+    asOrg: cf?.asOrganization || null,
     referer: h.get('Referer'),
   }
 }

src/core/store.ts

@@ -202,6 +202,13 @@ export interface StoredEvent {
   path: string | null
   reason: string | null
   country: string | null
+  city: string | null
+  region: string | null
+  asOrg: string | null
+  ua: string | null
+  /** The keyed hash of the client's address: equal across one client's rows, unreadable as an address. */
+  ipHash: string | null
+  referer: string | null
 }
 
 /** Convenience: what a store needs from `mintGrant` before it has an id/timestamps. */

test/routes.test.ts

@@ -4,6 +4,7 @@ import { createGate } from '../src/core/gate.js'
 import { adminPolicy, anyEmailPolicy, firstMatch } from '../src/core/policy.js'
 import { authRoutes } from '../src/core/routes.js'
 import type { Auth } from '../src/core/types.js'
+import { hashIp } from '../src/core/tokens.js'
 import { bytesToDataUri, gravatarUrl } from '../src/core/avatar.js'
 import { type MemoryAssetStore, memoryAssetStore } from '../src/testing/index.js'
 import { testDb } from './d1-shim.js'
@@ -515,6 +516,58 @@ describe('access log routes', () => {
     expect(res!.status).toBe(501)
   })
 
+  it("returns each row's client: browser, hashed address, and where Cloudflare places it", async () => {
+    const cookie = await asAdmin()
+    const minted = await post('/grants', { name: 'Bob', scopes: ['reports'] }, cookie)
+    const id: string = minted.body.grant.id
+    const exchange = (headers: Record<string, string>, cf?: object) => {
+      const req = new Request(url('/exchange'), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...headers },
+        body: JSON.stringify({ token: minted.body.token }),
+      })
+      return handle(cf ? Object.assign(req, { cf }) : req)
+    }
+    await exchange(
+      {
+        'CF-Connecting-IP': '203.0.113.7',
+        'CF-IPCountry': 'US',
+        'User-Agent': 'Mozilla/5.0 (Macintosh) Chrome/141',
+        Referer: 'https://mail.example.com/',
+      },
+      { city: 'Brooklyn', region: 'New York', asOrganization: 'Comcast', colo: 'EWR' },
+    )
+    // Off Cloudflare (or a client it can't place): no `cf`, so no location.
+    await exchange({ 'User-Agent': 'curl/8.7' })
+
+    const log = await call(`/log?grant=${id}`, {}, cookie)
+    const client = ({ event, country, city, region, asOrg, ua, ipHash, referer }: Record<string, unknown>) => ({
+      event,
+      country,
+      city,
+      region,
+      asOrg,
+      ua,
+      ipHash,
+      referer,
+    })
+    expect(log.body.events.map(client)).toEqual([
+      { event: 'redeem', country: null, city: null, region: null, asOrg: null, ua: 'curl/8.7', ipHash: null, referer: null },
+      {
+        event: 'redeem',
+        country: 'US',
+        city: 'Brooklyn',
+        region: 'New York',
+        asOrg: 'Comcast',
+        ua: 'Mozilla/5.0 (Macintosh) Chrome/141',
+        ipHash: await hashIp('203.0.113.7', SECRET),
+        referer: 'https://mail.example.com/',
+      },
+      // The admin's mint went through `call`, which sends none of these.
+      { event: 'mint', country: null, city: null, region: null, asOrg: null, ua: null, ipHash: null, referer: null },
+    ])
+  })
+
   it('returns a link’s trail and its activity summary', async () => {
     const cookie = await asAdmin()
     const minted = await post('/grants', { name: 'Bob', scopes: ['reports'] }, cookie)

test/schema.test.mjs

@@ -21,8 +21,9 @@ const tables = () => {
 }
 
 describe('migrations/', () => {
-  it('is one baseline file', () => {
-    expect(migrationFiles(dir)).toEqual(['0001_init.sql'])
+  // Pre-1.0: one baseline, plus any additions not yet squashed into it.
+  it('is the baseline plus unsquashed additions', () => {
+    expect(migrationFiles(dir)).toEqual(['0001_init.sql', '0002_access_log_location.sql'])
   })
 
   it('builds exactly these tables and columns', () => {
@@ -62,6 +63,9 @@ describe('migrations/', () => {
         'referer TEXT',
         'reason TEXT',
         'bucket INTEGER',
+        'city TEXT',
+        'region TEXT',
+        'as_org TEXT',
       ],
       access_log_daily: [
         'day INTEGER NOT NULL PK#1',