kandev/docs/plans/fix-multi-instance-cookie-isolation/task-06-docs-and-stale-references.md

id, title, status, wave, depends_on, plan, spec

id	title	status	wave	depends_on	plan	spec
06-docs-and-stale-references	Deployment note and stale cookie-name references	done	3	02-session-cookie-port-scope-backend 04-workspace-cookie-port-scope-frontend	plan.md	../../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

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.