--- spec: docs/specs/session-hostname-resolution/spec.md created: 2026-08-16 status: draft --- # Implementation Plan: Optional reverse-DNS hostnames for account sessions ## Outcome A per-user **Resolve device hostnames** toggle on `/settings/account/security`, off by default. Enabling it shows a Hostname column on the sessions table; the backend reverse-resolves the user's session IPs through the OS resolver (`net.LookupAddr`) in the background, caches results per IP in the configured database, and streams changed values to the page over the existing WebSocket gateway. No-answer IPs and generic `.in-addr.arpa` / `.ip6.arpa` answers render `N/A`. Disabling hides the column; re-enabling restores cached values instantly and streams only deltas. ## Fixed decisions - Wire setting `resolve_session_hostnames: boolean`; frontend state `userSettings.resolveSessionHostnames`. Missing stored values and initial payloads default to `false`; PATCH omission preserves the current value. - Turning the setting on publishes the persisted user-settings event. The hostname resolver consumes that event and starts background resolution for the user's session IPs. The sessions list response also triggers resolution for uncached/new IPs and carries the cached `hostname` per session. - New cache table `auth_hostname_cache`, owned by the hostnames cache store (`internal/auth/hostnames/store.go`) whose `initSchema` creates it (new table, so `CREATE TABLE IF NOT EXISTS` suffices; no `ADD COLUMN` migration). - Cache is global by IP; `hostname == ""` means no answer and is cached. `recentResolveWindow = 30s` skips re-query of freshly resolved IPs; `lookupTimeout = 3s`; `lookupWorkers = 4`; in-flight IPs are deduplicated with an interested-user set per IP. - Streaming: the internal event-bus event is `auth.session.hostname.resolved` with payload `{user_id, ip, hostname, resolved_at}` (fixed 9-digit RFC3339 UTC or null) — the `UserEventBroadcaster` routes by `user_id` and strips it — and the WS action `auth.session.hostname.resolved` carries the reduced `{ip, hostname, resolved_at}` to the client; published only when the hostname value changed versus the cache. Every successful lookup (valid or `IsNotFound`) persists and refreshes `resolved_at` via `Set` even when the hostname is unchanged, so `recentResolveWindow` engages for stable and no-answer rows. Cache/job keys are canonical IPs; the event `ip` is each interested (user, raw stored session-IP spelling) pair so frontend row matching needs no IP parsing; one user with two spellings of the same IP gets events for both. The sessions response carries `hostname` and `hostname_resolved_at` per session so the frontend can order snapshots against streamed events. - Frontend keeps an in-memory per-IP streamed map in the auth store slice as a **top-level `sessionHostnames` sibling of `auth`** (never nested, never addressed as `auth.sessionHostnames`; also wired through `default-state.ts` and `store-overrides.ts` so caller-supplied maps survive store construction). Entries are `{hostname, resolvedAt}` (fixed 9-digit RFC3339 UTC or null). It survives disable/enable and same-identity refreshes and is **cleared when the authenticated identity changes** (setAuthState with a different user, logout, and the 401/clearAuthenticated path). The The SessionsCard shows the Hostname column only while the toggle is on; cell resolution compares `resolved_at` (**newer wins; durable beats transient; ties to non-empty; both empty → `N/A`**), which reconciles the retained map against newer list snapshots after a WebSocket gap while still letting a fresh streamed event beat an in-flight stale response. The SAME comparator lives in `setSessionHostname` (not a blind upsert) so a delayed older event can never overwrite a newer map entry. There is **no pending spinner**: empty values always render `N/A`. A first absent → no-answer resolution IS a change and publishes (an `IsNotFound` negative with a persisted `resolved_at`; a transient DNS error over an absent cache with `resolved_at: null`); a subsequent same-value cached no-answer only refreshes `resolved_at` via `Set` and publishes nothing, so an unchanged settled no-answer row emits no further events and renders `N/A` **until its freshness expires (`recentResolveWindow`) and a retry replaces the empty with a valid answer, which publishes the changed hostname**. A `false -> true` setting transition (same tab or cross-tab) refetches the sessions list once (single guarded effect with trailing coalescing — a trigger during an in-flight fetch schedules exactly one post-settle reload — and a generation guard that discards stale responses), so backend-cached hostnames render even when the list was last loaded while off; the list also refetches on window focus with the same protocol. No session-created push event. - The settings gate fails closed: a settings read error behaves exactly like the toggle being off (empty hostname map, no lookups, logged) — DNS must never run while opt-in is unknown. - DNS errors are classified: `*net.DNSError` with `IsNotFound` (NXDOMAIN / no PTR, the common no-answer case) is a successful negative answer persisted as `hostname = ""`; timeout/temporary/server errors are never persisted and are published `""` only for IPs with no cache entry (never over an existing cached value, which would mask it client-side). - Resolver API contract: `HostnamesForSessionIPs(ctx, userID string, ips []string) map[string]CacheEntry` — raw-input-keyed, `ErrNotFound` treated as a successful absent baseline, all degradations (settings/cache errors) logged internally, never returns an error and never fails the sessions handler. - Production wiring calls `Start(ctx)` explicitly, registers `Close` as cleanup, queue-subscribes the resolver to the persisted `UserSettingsUpdated` event, and threads the resolver to `registerRoutes` via the `Services` struct (`types.go`). - The toggle hook is fire-and-forget: `TriggerUserSessionsResolved(userID)` enqueues on a resolver-owned trigger queue and returns immediately (PATCH never blocks on settings/session/cache reads); the trigger goroutine and workers run on the resolver-owned context and `Close` joins them. - The lookup function is injectable for tests; default is `net.DefaultResolver.LookupAddr`. No HTTP/API calls in the lookup path. - The resolver depends on a narrow `Cache` interface (`GetMany`/`Get`/`Set` over `CacheEntry{Hostname string, ResolvedAt *time.Time}`, absent rows absent from results, `ErrNotFound` treated as a successful absent baseline) for deterministic error injection and `recentResolveWindow`; timestamps are fixed 9-digit fractional-second RFC3339 UTC text (lexicographically comparable, so same-millisecond changes still order). A `Set` error publishes **nothing** (changed-only semantics; the next trigger retries the persist, and a later successful `Set` that changes the cache publishes); `resolved_at: null` in events is reserved for transient DNS errors over an absent cache (empty strings), never for failed writes. Admission records the observed cache value per pending IP; a worker that finds an IP fresh within `recentResolveWindow` still publishes the current value to interested users when it differs from what the requester saw (stale-read → concurrent completion → enqueue must not silently drop the update), and re-checks the settings gate at dequeue so **DNS never runs while the toggle is off** (disabled users' interests are dropped; a job with no enabled interested users is skipped). Session-IP providers return raw validated spellings; canonicalization stays inside the resolver. Gateway tests assert `resolved_at` (fixed-width RFC3339 and null) survives both memory and NATS transports; a frontend router integration test pins `registerSessionHostnamesHandlers` in `registerWsHandlers`. ## Backend ### Task 01 — portable setting contract - `AppStatusBarEnabled`-style field `ResolveSessionHostnames bool` in `internal/user/models/models.go`. - Response + PATCH `*bool` in `internal/user/dto/dto.go`, controller mapping, `applyBasicSettings` in `internal/user/service/service.go`, event payload key `resolve_session_hostnames` in `publishUserSettingsEvent`. - Store: default false, JSON marshal key, `*bool` scan decode, overwrite only when present (`internal/user/store/sqlite.go`). - Boot mapping `resolveSessionHostnames` in `internal/backendapp/boot_state_routes.go`. - Frontend: HTTP types (`http-user-settings.ts`), `UserSettingsState` field, shared mapper in `lib/ssr/user-settings.ts` (default false, omission preserves), revision-ordered WS handler fixture updates. - Tests: model/DTO/service/store/boot/event round trip; frontend mapper and WS handler tests. ### Task 02 — backend reverse-DNS service - New package `internal/auth/hostnames`: - `store.go`: database-portable cache store (`auth_hostname_cache`), `Get`/`Set`; - `normalize.go`: `NormalizeHostname([]string) string` (first-valid-record: strip trailing dot, reject empty and `.in-addr.arpa`/`.ip6.arpa` suffixes); - `resolver.go`: `Resolver` with `Start`/`Close` worker pool (goleak), in-flight + interested-user dedup, `recentResolveWindow` guard, `HostnamesForSessionIPs(ctx, userID, ips)` (enabled gate, cached values, schedules lookups) and fire-and-forget `TriggerUserSessionsResolved(userID)` (owned trigger queue, PATCH never blocks); changed-only event publishing with `IsNotFound` persisting as a cached no-answer and timeout/error → `""` not persisted. - `auth.Service.SessionIPs(ctx, userID)` (distinct raw spellings of the user's sessions, skipping empty/invalid). - `events` constant `AuthSessionHostnameResolved`. - `pkg/websocket/actions.go`: `ActionSessionHostnameResolved`. - `gateway/websocket/user_notifications.go`: subscribe the new event to the new action. - `auth/httpapi`: `RegisterRoutes(router, svc, resolver, log)`; `listSessions` returns per-session `hostname` and schedules resolution. - `user/service`: publish the complete persisted setting through the existing `UserSettingsUpdated` event. - `backendapp`: construct the resolver (store over `dbPool`, session-IPs = `authSvc`, settings gate over `repos.User`, event bus, log), subscribe it to setting updates, and pass it to `authhttpapi.RegisterRoutes`. - Tests: store, normalize, resolver (dedup, changed-only, interested-user routing, disabled gate, recent-window, timeout-not-persisted), goleak, httpapi sessions payload, and persisted settings event handling. ## Frontend ### Task 03 — streaming and UI - `AuthSession` type gains `hostname: string` and `hostname_resolved_at: string | null` (fixed 9-digit timestamp or null). - `BackendMessageMap` entry + `SessionHostnameResolvedPayload` (`{ip, hostname, resolved_at}`); WS handler `lib/ws/handlers/session-hostnames.ts` registered in `router.ts` updating top-level `sessionHostnames`; router integration test pins the registration. - Auth slice: `sessionHostnames: Record` with `SessionHostnameEntry = { hostname: string; resolvedAt: string | null }` and `setSessionHostname(ip, hostname, resolvedAt)` (default empty). - `security-settings.tsx`: toggle card (Switch, direct save via `updateUserSettings`, `data-testid`), SessionsCard Hostname column gated on the setting, cell resolution by `resolved_at` (newer wins, durable beats transient, ties to non-empty, both empty → `N/A`; lexicographic string comparison, never `Date.parse`). - i18n: `account.json` keys (`resolveDeviceHostnames`, `resolveDeviceHostnamesDescription`, `hostname`, `hostnameNotAvailable`) in all catalogs; regenerate pseudo. - Tests: auth slice action, WS handler, router registration, mapper, component test for toggle + column rendering + streamed update + resolved_at ordering (WS-gap reconciliation, same-millisecond ordering) + N/A. ## E2E and verification ### Task 04 — E2E and final verification - Playwright spec under `apps/web/e2e/tests/auth/` — files there run in the `auth` project (backend restarted with `KANDEV_FEATURES_AUTH: true`). **Setup is `setupAdmin(...)` only for the main flow** (`/auth/setup` creates the admin session and sets the cookie, so the baseline is exactly one row — do NOT call `login` before navigation, which would create a second baseline row); the second `login(...)` is reserved for the focus-refetch step. Reset the setting to `false` in `afterEach`: toggle off default (no Hostname column), toggle on (column appears immediately; each row's cell is hostname-or-`N/A` — no WS-event waits, the worker backend cache persists across tests and e2e logins share one loopback IP so first-resolution events are not guaranteed), toggle off (column hidden), toggle on again (column reappears with cached values), setting survives reload, and focus-refetch discovers a second login (login again through the same context's request client, navigate a second same-context page, `bringToFront` page 1, row count grows by one). - Mobile: `tests/auth/mobile-account-security-hostnames.spec.ts` (runs in the `mobile-chrome` project; the auth project's `testIgnore` excludes `mobile-*`) covering the same enable/disable/re-enable flow and column rendering at Pixel 5 viewport. - Run backend focused tests + lint, frontend focused tests, `i18n:check` + `i18n:ratchet`, typecheck, lint, targeted E2E (auth + mobile-chrome projects), `git diff --check`. ## Implementation waves Execution is sequential in the primary conversation. | Wave | Task | Status | Gate | |---|---|---|---| | 1 | [01 portable setting contract](task-01-portable-setting-contract.md) | pending | `resolve_session_hostnames` round trips backend→boot→frontend with default false. | | 2 | [02 backend reverse-DNS service](task-02-backend-reverse-dns-service.md) | pending | Lookup, cache (GetMany/CacheEntry), changed-only streaming and sessions `hostname`/`hostname_resolved_at` fields green (fail-closed settings gate, IsNotFound negative caching, ErrNotFound-as-absent, transient-error masking rule, fire-and-forget trigger, off-state empty map, pending-set admission, resolver-owned contexts, IP canonicalization + raw-IP event keys, Cache-interface error semantics, production Start wiring + settings-event subscription, gateway routing tests, schema replay); toggle still has no UI. | | 3 | [03 frontend streaming and UI](task-03-frontend-streaming-and-ui.md) | pending | Toggle + Hostname column (empty always N/A, no spinner) + streamed updates + focus-refetch, desktop and mobile. | | 4 | [04 E2E and final verification](task-04-e2e-and-final-verification.md) | pending | Auth-project desktop E2E + mobile-chrome E2E (persistence/column behavior, no WS-event waits) and full checks pass. | Task 02 depends on Task 01 (the resolver reads the setting); Task 03 depends on 01 + 02; Task 04 depends on 03. No tasks are parallel-safe. ## Verification order If `apps/node_modules` is absent, run once before frontend checks: ```sh (cd apps && pnpm install --frozen-lockfile) ``` Each task runs its focused commands. Final verification: ```sh (cd apps/backend && go test ./internal/auth/... ./internal/user/... ./internal/gateway/websocket/... ./internal/backendapp/... ./pkg/websocket/...) make -C apps/backend lint (cd apps/web && pnpm run i18n:check) (cd apps/web && pnpm run i18n:ratchet) (cd apps/web && pnpm run typecheck) (cd apps/web && pnpm run lint) (cd apps/web && pnpm exec vitest run lib/ssr/user-settings.test.ts lib/ws/handlers/session-hostnames.test.ts lib/state/slices/auth/auth-slice.test.ts components/settings/account/security-settings.test.tsx) (cd apps/web && pnpm e2e:run --project auth tests/auth/account-security-hostnames.spec.ts) (cd apps/web && pnpm e2e:run --project mobile-chrome tests/auth/mobile-account-security-hostnames.spec.ts) git diff --check ``` ## Risks - A backend or frontend default that stays `true` would resolve IPs for users who never opted in. Pin default-false at every boundary (store, boot, mapper, state), and gate the sessions-response map so cached hostnames never leak while the toggle is off. - Forgetting the sessions-response `hostname` field or the event key in the complete settings event breaks hydration/streaming silently; pin both in tests. - DNS behavior varies by environment (no PTR, `localhost`, synthesized names); E2E must assert column presence/absence and hostname-or-`N/A` cells, never an exact hostname, and must NOT wait for WS events (fresh cache and unchanged results intentionally emit nothing). - Multi-user: streaming must be routed per user; the interested-user set prevents user B from missing updates when user A's lookup for a shared IP completes. - Rapid toggle cycles must not hammer DNS; the `recentResolveWindow` guard and in-flight dedup cover this. Admission must never drop a required IP: workers drain a pending set rather than a drop-on-full queue. - Lookups must run on a resolver-owned context (canceled by `Close`), never a request context, or they die with the HTTP response. - The auth slice's `sessionHostnames` map must be a top-level sibling of `auth` (never nested, never `auth.sessionHostnames`), or `setAuthState` (login/me refresh) erases it; `store.ts` must be updated with the slice shape. - A cache interface that cannot distinguish absent from cached-empty or expose `ResolvedAt` makes no-answer caching and `recentResolveWindow` unimplementable; the resolver's `Cache` returns `CacheEntry` and absent rows are absent from `GetMany` results. - Raw session-IP spellings must survive to the event payload (per user, per spelling), or hook-triggered resolutions publish canonical `ip` values the frontend cannot match; providers return raw validated spellings and only the resolver canonicalizes for job/cache keys. - A settings-gate read error must fail closed (no lookups, empty map); a default-to-enabled fallback would run DNS while opt-in is unknown. - A pending spinner is not representable (cached no-answer rows emit no event): empty always renders `N/A`, and E2E must not depend on WS events (the worker backend cache persists across tests and e2e logins share one loopback IP, so first-resolution/changed events are not guaranteed). - The pending set needs the complete-then-recheck invariant: workers must re-drain after every completion or IPs admitted while all workers are busy strand forever. - Without the enable-transition refetch, enabling after a list load that happened while off shows `N/A` forever (the off-state response carried no cached hostnames and changed-only events may never come); the single guarded effect watching the setting is the fix. - The in-memory map must clear on identity change (different user or logout) or one user's session IPs seed another user's rows; keep the disable/enable survival separate and test both. - `createAppStore({ sessionHostnames })` silently drops the map unless the field is added to `default-state.ts` and `store-overrides.ts` (slices spread after the default state). - E2E focus-refetch needs a second page in the same context that actually navigates (the `login` helper never focuses a page), then page 1 `bringToFront`; it must not be skippable. - The common no-PTR case surfaces as `*net.DNSError` with `IsNotFound`, not as records; failing to classify it means no-answer IPs are never cached and re-queried on every trigger. Persist `IsNotFound` as a cached no-answer and only treat timeout/temporary/server errors as non-persisted. - Transient failures must not mask durable values: the backend publishes transient `""` only for IPs with no cache entry, and the frontend orders by `resolved_at` (newer wins, durable beats transient), or a stale-cache + transient-error + re-enable cycle pins rows to `N/A`. - Without a per-IP timestamp, the retained streamed map can permanently override a newer sessions response after a WS gap (events during a disconnect are lost and never replayed); both the API and the WS payload must carry `resolved_at` and cells must compare it. - `ErrNotFound` must be treated as an absent baseline (never as a generic cache error) or first-resolution transient behavior and negative caching break; pin the distinction in resolver tests. - A same-value successful lookup that skips `Set` never refreshes `resolved_at`, so `recentResolveWindow` never engages and stable/no-answer rows re-query on every trigger; successful lookups always persist and refresh the timestamp, while publishing stays changed-only. - A missing `UserSettingsUpdated` subscription lets a successful PATCH stop before it starts lookup work. The resolver event-handler test pins that boundary without adding feature knowledge to the user settings service. - Clearing `sessionHostnames` on identity change is not enough: a delayed WS frame from the prior user (the gateway strips `user_id`) can repopulate the cleared map. Fence the stream with a `sessionHostnamesEpoch` handler guard plus WS client recreation on identity change, and pin the stale-event regression test. Client - Client recreation must be reactive (an identity selector in `WebSocketConnector` / `useWebSocket` deps — a `store.getState()` read inside the effect does not rerender), must cover user-id-only transitions (the auth gate does not unmount the connector on those), and must re-establish client-held subscriptions — and the disposed client's status callbacks (`onclose` AND `onerror`) must be fenced (detached or generation-guarded) so a delayed callback cannot overwrite the replacement's `connected` status. Hook-owned subscriptions obtained via `getWebSocketClient()` (system metrics, office run live sync, others) must include the reactive client generation in their deps or they silently stay on the disposed client. - Streamed hostname notifications fan out to the user's own WS connections (all tabs); the spec's non-goal is rendering-scoped — only the security page renders the data, other tabs retain but never show it (this is what powers instant re-enable/cross-tab cached results). - The enable-transition refetch must run after the PATCH commits (apply the PATCH response to the store, no optimistic flip), or the refetch GET can race a still-false settings gate and permanently miss cached hostnames and DNS scheduling. - A `Set`-error publish without explicit semantics makes an unpersisted value look durable (or linger transient); publish nothing on `Set` error and let the retry persist-then-publish. - The interested-user set must be snapshot+cleared exactly once on every job terminal path (publish, no-change, dequeue-gate skip, cache errors, nil bus) or stale routing state accumulates unboundedly under session/IP/user churn; in-flight merges are the only retained interests. - The timestamp formatter must be an exported `hostnames` API (`FormatTimestamp`/`ParseTimestamp`) used by the store, resolver, and httpapi handler — unexported helpers would force layout duplication across packages and drift the fixed-width ordering contract. - The controller's field-by-field PATCH mapping can silently drop `resolve_session_hostnames` while DTO/service/store tests pass; pin the pointer mapping in `controller_test.go`. - A forgotten production `Start(ctx)` passes every unit test (they call Start themselves) and every E2E (which tolerates `N/A`); the backendapp wiring smoke test is the only guard. - A missing router registration (`registerSessionHostnamesHandlers`) passes direct-handler tests and `N/A`-tolerant E2E while the streaming path is dead; the router integration test is the guard. - Without a dequeue-time settings recheck, DNS can run after the toggle is disabled for work admitted while it was on; re-check at dequeue, drop disabled users' interests, and skip jobs with no enabled users. - `Date.parse`/`RFC3339Nano` cannot order same-millisecond changes; the fixed-width 9-digit fraction keeps timestamps lexicographically comparable in Go and JS. - The desktop E2E must use an isolated `KANDEV_DATABASE_PATH` like the mobile spec; the auth worker is serial/shared and `backend.restart` preserves the DB, so leaked sessions/cache/admin state makes row-count and setup assertions order-dependent. - A synchronous hook or a naive goroutine in `UpdateUserSettings` blocks the PATCH or dies with the request context; the hook must enqueue on the resolver-owned trigger queue and return immediately. - E2E focus-refetch must create the second session by calling `login` again through the same context's request client (navigation alone reuses the cookie and adds no session row), then navigate a second same-context page for a real blur/focus, then `bringToFront` page 1; it must not be skippable. - The mobile spec runs in `mobile-chrome`, which does not inherit the auth project's backend restart; it must restart auth-enabled with an isolated DB itself or the page never loads sessions. - The sessions-list refetch must use trailing coalescing + generation guard: a trigger dropped during an in-flight fetch loses the only refresh for that event, and an older slow response can overwrite newer rows. - E2E specs under `tests/auth/` only run in the `auth` project; auth-mode setup (`setupAdmin`/`login`) and per-test cleanup are required, and the mobile spec must be a separate `mobile-*.spec.ts` file for the `mobile-chrome` project.