Files
kandev/docs/plans/fix-multi-instance-cookie-isolation/task-06-docs-and-stale-references.md
T
2026-08-24 11:09:03 +00:00

125 lines
6.4 KiB
Markdown

---
id: "06-docs-and-stale-references"
title: "Deployment note and stale cookie-name references"
status: done
wave: 3
depends_on: ["02-session-cookie-port-scope-backend", "04-workspace-cookie-port-scope-frontend"]
plan: "plan.md"
spec: "../../specs/auth/requirements/fix-multi-instance-cookie-isolation.md"
---
# Task 06: Deployment note and stale cookie-name references
## Acceptance
- `docs/public/authentication.md` gains an operator note: multiple
auth-enabled instances on one host (same IP, different ports) are isolated
per port via port-scoped cookie names. Reverse proxies: the CORS/WS origin
gate compares the browser `Origin` hostname with the request `Host` and
ignores `X-Forwarded-Host`, so the proxy MUST preserve the browser
**hostname**; it may either preserve the full `Host` (host:port) or rewrite
only the port and forward a correct `X-Forwarded-Host` (the resolver takes
the public port from XFH) — rewriting a non-loopback hostname 403s before
auth (loopback-alias rewrites such as `localhost` → `127.0.0.1` pass the
existing origin gate and are unchanged).
**Session-cookie migration** (scoped to auth sessions; workspace cookies
are separate): old auth-enabled builds conflict with other old builds via
the shared unprefixed `kandev_session`; an upgraded instance ignores the
legacy session token and requires one re-login (guaranteed on rollback and
re-upgrade because the new build never reads the unprefixed session
cookie); workspace selections keep their validated legacy read fallback, so
a pre-upgrade selection survives. Custom `auth.cookieName` values disable
automatic port isolation and must be unique per cookie host. Instances on
the same host at default ports over different schemes (HTTP :80 + HTTPS
:443) keep the plain names and are not isolated.
- `docs/public/configuration.md` documents `auth.cookieName` with its
canonical environment override `KANDEV_AUTH_COOKIE_NAME` (explicit
`BindEnv`; the automatic camelCase mapping would expose the undocumented
`KANDEV_AUTH_COOKIENAME`), plus config.yaml and precedence
(env over file over default).
- Stale references that pin the literal `kandev_session` cookie name are
updated to describe "the session cookie (name derived from the request
host)" or "base name `kandev_session`; effective name request-host-derived":
- `apps/web/e2e/helpers/auth.ts` (doc comment, ~lines 6-8)
- `apps/web/components/app-sidebar/app-sidebar-workspace-navigation.ts`
(comment ~lines 30-34: "office paths read the legacy cookie... kept in
step" — legacy names are now read-only fallback, writes are scoped)
- `apps/web/app/office/layout.tsx` (comment ~lines 154-157: the office
cookie "is set by the setup wizard and workspace rail" — now writes the
port-scoped name)
- `docs/specs/plugins/requirements/plugins.md` (~lines 223-234, external-login section)
- `docs/decisions/0050-plugin-external-auth-capability.md`
- `docs/decisions/2026-07-24-opt-in-authentication.md`
- `apps/backend/AGENTS.md`
- `apps/backend/internal/backendapp/auth.go` (plugin SSO bridge doc
comment, ~lines 21-24)
- `apps/backend/internal/auth/service_sso.go` (comment)
- `apps/backend/internal/plugins/auth_login.go` (comment)
- `apps/backend/internal/auth/store/models.go` (comment)
- **No-op verification targets** (already amended by this package; keep in
the audit grep, do NOT edit): `docs/specs/auth/requirements/auth.md` (already states
base name + request-host-derived effective names) and
`docs/decisions/2026-08-15-office-mode-follows-active-workspace.md`
(already states the legacy office cookie is read-only fallback and writes
are port-scoped).
- No behavioral code change in this task; `gofmt`/lint still clean (comments
only).
## Verification
```bash
rg -n "kandev_session" docs/specs/auth/requirements/auth.md docs/specs/plugins/requirements/plugins.md docs/decisions/0050-plugin-external-auth-capability.md docs/decisions/2026-07-24-opt-in-authentication.md apps/backend/AGENTS.md apps/backend/internal/auth apps/backend/internal/plugins apps/backend/internal/backendapp/auth.go apps/web/e2e/helpers/auth.ts apps/web/components/app-sidebar/app-sidebar-workspace-navigation.ts apps/web/app/office/layout.tsx
rg -n "office-active-workspace" docs/decisions/0023-active-workspace-cookie.md docs/decisions/2026-08-15-office-mode-follows-active-workspace.md docs/decisions/2026-07-24-opt-in-authentication.md
# every path listed in the stale-reference acceptance must appear above; remaining hits must be intentional (e.g. the legacy-cookie no-fallback note in the fix spec)
cd apps/backend && go build ./...
```
## Files likely touched
- `docs/public/authentication.md`
- `docs/public/configuration.md` (new `auth.cookieName` row + env name)
- `docs/specs/plugins/requirements/plugins.md`
- `apps/web/e2e/helpers/auth.ts` (doc comment)
- `apps/web/components/app-sidebar/app-sidebar-workspace-navigation.ts`
- `apps/web/app/office/layout.tsx`
- `docs/decisions/0050-plugin-external-auth-capability.md`
- `docs/decisions/2026-07-24-opt-in-authentication.md`
- `apps/backend/AGENTS.md`
- `apps/backend/internal/backendapp/auth.go`
- `apps/backend/internal/auth/service_sso.go`
- `apps/backend/internal/plugins/auth_login.go`
- `apps/backend/internal/auth/store/models.go`
Audit-only (do NOT edit; already amended by this package, keep in the
verification grep): `docs/specs/auth/requirements/auth.md`,
`docs/decisions/2026-08-15-office-mode-follows-active-workspace.md`.
## Dependencies
The behavior contract from tasks 02 and 04 (docs describe shipped behavior).
## Parallelism
Wave 3, parallel-safe with `task-05` (docs vs e2e specs; disjoint).
## Inputs
- Spec: `Failure modes` (proxy, mixed-version), `Out of scope`.
- Plan: `Docs`.
- Existing pattern: `docs/public/plugins-authoring.md` already describes the
request-host-derived name; mirror that wording.
## Risks
- Some hits are intentional (the fix spec's legacy-fallback note, the auth
spec's port-scoped bullet); do not rewrite the fix package itself. Only
prose that implies a fixed literal name is in scope.
- Comments in `service_sso.go` / `auth_login.go` sit next to the SSO bridge
code changed in task 02; coordinate wording with that task's diff.
## Output contract
Report the deployment note placement, the updated references, the remaining
intentional `kandev_session` hits, changed files, exact commands and results,
blockers/risks, then mark this task `done` and update `plan.md`.