125 lines
6.4 KiB
Markdown
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`.
|