kandev/docs/plans/session-ip-refresh/plan.md

---
spec: docs/specs/auth/requirements/session-ip-refresh.md
created: 2026-08-19
status: complete
---

# Implementation Plan: Session IP Refresh

## Overview

Refresh a browser session's recorded IP on the existing throttled touch path
instead of pinning it at login. The service's `ResolveSessionToken` gains a
client-IP parameter; on the touch interval it passes the request IP to
`Store.TouchSession`, which refreshes the `ip` column only when the value is
non-empty. The single production caller — the global auth middleware
(`httpmw.ResolveRequest`) — supplies `c.ClientIP()`, so every
COOKIE-authenticated HTTP and WebSocket request benefits. PAT-authenticated
requests (including `?token=` WS upgrades, which resolve via
`AuthPolicy.ResolveToken`, never `ResolveRequest`) carry no session IP and
are unchanged. The HTTP surface and the UI are unchanged.

Order: Task 01 lands the store + service behavior (signature changes and
their tests, including mechanical call-site updates in the `auth` package);
Task 02 wires `c.ClientIP()` through the middleware and proves the full chain
with an integration test.

## Backend

### Store (`apps/backend/internal/auth/store/store.go`)

- `TouchSession(ctx, id, lastSeen, expires)` → `TouchSession(ctx, id,
  lastSeen, expires, ip string)`. Single UPDATE keeps refreshing timestamps
  and conditionally the IP:

  ```sql
  UPDATE auth_sessions
  SET last_seen_at = ?, expires_at = ?,
      ip = CASE WHEN ? = '' THEN ip ELSE ? END
  WHERE id = ?
  ```

  Contract: timestamps always update; `ip` refreshes the stored value only
  when non-empty (empty never clobbers). The service decides *whether* a
  refresh is wanted by passing the request IP only when it differs from the
  stored value; the `CASE` is the store's defense against empty clobbering.

### Service (`apps/backend/internal/auth/service_credentials.go`)

- `ResolveSessionToken(ctx, token)` → `ResolveSessionToken(ctx, token, ip
  string)`. Inside the existing `now.Sub(sess.LastSeenAt) > sessionTouchInterval`
  gate:

  ```go
  refreshIP := ""
  if ip != "" && ip != sess.IP {
      refreshIP = ip
  }
  _ = s.store.TouchSession(ctx, sess.ID, now, now.Add(s.SessionTTL()), refreshIP)
  ```

  Same-IP and empty-IP requests pass `""` (timestamps still update; IP
  preserved). Different non-empty IPs ride the same one-minute throttle —
  no per-request writes. Note: the `ip != sess.IP` comparison is a
  write-avoidance optimization, not an observable contract — an
  always-write service (passing `ip` unconditionally) is behaviorally
  equivalent because the store `CASE` guard and the touch throttle still
  bound writes; the planned tests deliberately do not discriminate it
  (only a test-only counting wrapper over the store could observe the `ip`
  argument, and the same-IP case correctly pins the observable — stored IP
  unchanged while timestamps advance, since a literal "no IP write"
  assertion would contradict the sliding-expiry touch).

### Middleware (`apps/backend/internal/auth/httpmw/middleware.go`)

- Task 01 performs the mechanical signature update
  (`svc.ResolveSessionToken(ctx, cookie)` → `svc.ResolveSessionToken(ctx,
  cookie, "")`) so `internal/httpmw` keeps compiling and the full
  `internal/auth` suite stays green at the Task 01 boundary.
- Task 02 replaces `""` with `c.ClientIP()`:
  `svc.ResolveSessionToken(ctx, cookie, c.ClientIP())`. This is the only
  production call site. WebSocket upgrades refresh IPs through this same
  global middleware on the `/ws` route (`ResolveRequest` runs before the
  deferred-path check, and the gateway's `requireConnectionAuth` only
  consumes the already-resolved identity); the gateway itself never calls
  `ResolveRequest` — PAT `?token=` upgrades go through
  `AuthPolicy.ResolveToken` instead. The same refresh path holds for every
  other deferred path — `/port-proxy/`, `/terminal/`, `/lsp/`, `/vscode/`,
  `/mcp`, office-with-bearer, and the SPA-shell branch: cookie-authenticated
  requests to them resolve and refresh through the global middleware BEFORE
  the deferred-path check, while capability-authenticated proxy requests
  (no `kandev_session` cookie) and `?token=` PAT upgrades correctly never
  touch. Do NOT gate the
  `ResolveRequest` call on `isDeferredPath` — a "skip resolve for deferred
  paths" optimization would silently kill WS + proxy-subtree refresh while
  leaving every OTHER planned test green — task-02 sub-case (d) covers
  this exact regression. Task 02 also corrects the stale doc
  comment block on `httpmw/middleware.go:57-58` ("Shared with the WS
  gateway's upgrade-time check"): no WS caller of `ResolveRequest` exists,
  so the comment misleads implementers into wiring the upgrade path
  separately (now in Task 02's Acceptance and TDD step 2 so it cannot be
  silently dropped).

### Call-site updates (mechanical, same packages)

- `apps/backend/internal/auth/service_test.go` and `service_sso_test.go`:
  every `ResolveSessionToken(ctx, token)` call gains a trailing `""`.
- `apps/backend/internal/auth/store/store_test.go`:
  `TouchSession(ctx, id, lastSeen, expires)` gains a trailing `""` in
  `TestSessionLifecycle`.

## Frontend

No UI changes. `GET /api/v1/auth/sessions` keeps returning the `ip` field;
`Settings > Account > Security` renders the refreshed value.

## Tests

- **Store IP semantics** (`store_test.go`, new `TestTouchSessionIPRefresh`):
  create a session with IP `1.1.1.1`; touch with `2.2.2.2` → read back
  `2.2.2.2` with updated timestamps; touch with `""` → IP stays `2.2.2.2`;
  session created with an EMPTY stored IP, touch with `2.2.2.2` → backfilled
  (spec scenario 4).
- **Service refresh behavior** (`service_test.go`, new
  `TestResolveSessionTokenRefreshesChangedIP`): the store is reachable from
  package-auth tests as `f.svc.store` (no fixture change); tests age a
  session by creating it directly via `GenerateSessionToken()` (unqualified
  — `service_test.go` is package `auth`) + `f.svc.store.CreateSession`
  with `LastSeenAt: now.Add(-2*time.Hour)` (≥2
  minutes in the past — a seed under 60s keeps the strict `>` gate closed
  and fails the aged cases spuriously as a fixture defect). Cases: different
  IP on touch → stored IP updated (read back via `svc.ListSessions`); empty
  stored IP + non-empty request IP → backfilled; same IP → unchanged AND
  `last_seen_at` ADVANCED past the aged value; empty request IP → unchanged
  AND `last_seen_at` ADVANCED — the last_seen-advance pins discriminate a
  refresh-gated touch that stalls sliding expiry (task-01); DIFFERENT IP
  within the touch interval → IP unchanged AND `LastSeenAt` still equals
  the (truncated-to-second) future seed — the within-interval resolve
  passes a different IP (`2.2.2.2`) so the case exercises spec scenario 5's
  observable directly, and always-touch variants self-reveal (a touch
  without the gate either writes the different IP, caught by the IP
  assertion, or bumps `last_seen_at` from the future seed, caught by the
  pin); the required aged-extension (same different IP after aging →
  updated) completes spec scenario 5's post-interval transition. The within-interval service case creates its session
  with `LastSeenAt: now.Truncate(time.Second).Add(10*sessionTouchInterval)`
  — package `auth` can name the constant; the truncation matches the
  `Equal()` convention — so the gate (strict `now.Sub(LastSeenAt) >
  sessionTouchInterval` on a seed 10 intervals in the future) stays closed
  for ~11 minutes of wall-clock regardless of host slowness (the gate
  opens at `D > 660s − f`, where `f ∈ [0,1s)` is the fractional second the
  truncation dropped from the seed, i.e. between 659s and 660s) while
  preserving the
  always-touch discriminator. (The middleware-level sub-cases in Task 02
  cannot name the constant from package `httpmw` and keep the "≥2 minutes
  in the past" recipe.)
- **Middleware integration** (`middleware_test.go`, new
  `TestSessionIPRefreshedThroughMiddleware`): full chain gin → middleware →
  service → store, in three transport sub-cases plus a deferred-path
  sub-case (see task-02): (a) cleared
  proxies + RemoteAddr-only; (b) trusted peer `10.0.0.0/8` +
  `X-Forwarded-For` (a RemoteAddr-wired middleware fails); (c) cleared
  proxies + `X-Forwarded-For` (a raw-header-wired middleware fails); (d) a
  deferred-path request (`GET /ws`, 404-after-resolution is fine) with
  cookie + RemoteAddr → still refreshes (closes the
  skip-resolve-for-deferred-paths regression) —
  (b)+(c) pin the spec's "same `ClientIP()` value that records the IP at
  login, including `KANDEV_TRUSTED_PROXIES` resolution"), plus a real-route
  `GET /api/v1/auth/sessions` read-back in (a). `newTestService` gains an
  out-return for the store; each sub-case creates an aged session with IP
  `1.1.1.1` on a FRESH fixture and requests `/api/v1/probe` with the
  session cookie, asserting `svc.ListSessions` reports the expected IP.
  The `RemoteAddr` differs per sub-case: `2.2.2.2:1234` for (a) (no
  forwarded headers, so `ClientIP()` = RemoteAddr → expect `2.2.2.2`),
  `10.0.0.5:1234` (inside the trusted `10.0.0.0/8`) with
  `X-Forwarded-For: 2.2.2.2` AND `X-Real-IP: 9.9.9.9` for (b) → expect
  `2.2.2.2` (the third header pins XFF-over-X-Real-IP precedence, so
  header-order and X-Real-IP-wired bugs fail deterministically), and
  `10.0.0.5:1234` with `X-Forwarded-For: 2.2.2.2` on the cleared-proxy
  router for (c) → expect `10.0.0.5`. A sub-case (b) that reuses RemoteAddr
  `2.2.2.2` would pass vacuously (untrusted peer, header ignored) and let a
  RemoteAddr-wired middleware through — the exact bug (b) exists to catch.
- Spec scenario coverage: scenario 1 → service different-IP case +
  middleware integration; 2 → service same-IP case; 3 → service empty-IP
  case; 4 → empty-STORED-IP backfill (store + service cases); 5 → service
  within-interval case; 6 → the login-time recording
  regression net is the trusted-proxies suite `TestLoginSessionIP*` in
  `apps/backend/internal/auth/httpapi/handlers_test.go` (`loginSessionIP`
  helper). Task 02 step 3 hardens the helper so its read-back
  `GET /api/v1/auth/sessions` re-applies the login request's FULL transport
  mutator closure (RemoteAddr + `X-Forwarded-For` + `X-Real-IP`), making the
  new touch-based refresh idempotent on that read in all six cases — without
  it, a >60s gap between login and the read would overwrite the asserted IP
  (with the GET's default `httptest` RemoteAddr, or with the fixture's
  RemoteAddr where the stored IP came from a forwarded header), adding a
  timing sensitivity the suite did not have before. Name the suite
  explicitly so it is not mistaken for pass-through coverage of the
  refresh.
- No E2E: no user-facing flow changes and a browser cannot change its own
  client IP mid-session (see spec "Out of scope").

## E2E Tests

None — the change is backend-only with no UI delta; see the Tests section and
spec "Out of scope" for the justification.

## Verification Results

Task 01 and Task 02 landed (see each task's `## Results` for per-step RED/GREEN
evidence). Commands and outcomes:

```bash
# Task 01 — store + service
cd apps/backend && go test ./internal/auth/store -run '^TestTouchSessionIPRefresh' -count=1   # PASS
cd apps/backend && go test ./internal/auth -run '^TestResolveSessionTokenRefreshesChangedIP' -count=1   # PASS, 5 sub-cases
cd apps/backend && go test ./internal/auth/... -count=1   # PASS (auth, httpapi, httpmw, store)

# Task 02 — middleware wiring
cd apps/backend && go test ./internal/auth/httpmw -run '^TestSessionIPRefreshedThroughMiddleware$' -count=1   # PASS, 4 sub-cases
cd apps/backend && go test ./internal/auth/httpapi -run '^TestLoginSessionIP' -count=1   # PASS, 6 tests
cd apps/backend && go test ./internal/auth/... -count=1   # PASS
go test -race -count=1 ./internal/auth/...   # PASS

# Repo gates
make fmt                                        # PASS, no unrelated churn
make -C apps/backend vet                        # PASS
make typecheck                                  # PASS (after generating apps/web/generated/{changelog,release-notes}.json, build-time fixtures absent in a fresh worktree)
make -C apps/backend lint                       # PASS, 0 issues (golangci-lint; run with GOCACHE/GOTMPDIR relocated off quota'd ~/.kandev/cache and ~/.cache)
make lint-web lint-harness lint-architecture    # PASS
```

Environment notes (all verified pre-existing on a clean tree via `git stash`):
- Full backend `go test ./...` initially hit `disk quota exceeded` compile
  failures because the sandbox's `~/.kandev/cache` and `~/.cache` carry quotas;
  relocating `GOCACHE`/`GOTMPDIR` to `~/{gocache,gotmp}` fixed the compile
  failures. Remaining backend failures are fixture/environment-bound:
  `internal/agentctl/server/{api,process,config}` (agent binaries, workspace
  fixtures, missing `/tmp/cargo/env`), `internal/launcher` (systemd/launchd
  unavailable), `internal/plugins/runtime` (install-state fixture) — identical
  failure sets with and without this change.
- Web vitest: 1501/1506 files pass; `lib/http-git-server.test.ts` requires a
  Docker daemon (absent here); the other failures were 5s/10s timeouts under
  load and pass on re-run. Zero frontend files changed by this feature.
- `make test` at root therefore reports the pre-existing environmental
  failures above; no auth-package test fails.

## Implementation Waves And Parallel Candidates

```text
Wave 1:
- [x] [task-01-store-service-refresh](task-01-store-service-refresh.md)

Wave 2:
- [x] [task-02-middleware-wiring](task-02-middleware-wiring.md)
```

Task 02 depends on Task 01 (the new `ResolveSessionToken` signature), so the
waves are sequential. Both are small and stay in the primary conversation;
no subagent execution is authorized by this plan.

## Open Questions

None.