# Seven-Day Clinic Web Session

## Background and goal

Clinic web sessions currently expire 24 hours after a successful OAuth login. Frequent users must therefore authenticate again every day, interrupting their work. The goal is to keep newly issued Clinic web sessions valid for exactly seven days while preserving the existing fixed-expiration model and all unrelated authentication behavior.

## Current behavior

- `POST /clinic/api/v1/login/oauth/:name/validate` exchanges the OAuth authorization code for a Clinic session.
- `pkg/auth/session` signs the session as an HS256 JWT whose standard `exp` claim is 24 hours after issuance.
- The same package writes the JWT to the `clinic.session_id` browser cookie with a matching 24-hour `Max-Age`.
- Clinic and the Clinic Kong authentication plugin validate the JWT signature and standard expiration claim on subsequent requests.
- Logout clears the browser cookie. Existing sessions are stateless and retain the expiration embedded when they were issued.

## Target contract

- Newly issued Clinic web-session JWTs expire seven days, or 168 hours, after issuance.
- The `clinic.session_id` cookie has `Max-Age=604800`, matching the JWT lifetime.
- Expiration remains fixed at login; requests do not renew or slide the expiration.
- Existing sessions retain their embedded expiration and are neither extended nor invalidated by deployment.
- Missing, invalid, expired, and explicitly cleared sessions retain the existing unauthorized, redirect, and logout behavior.
- The existing gateway plugin continues to validate the standard JWT `exp` claim without a code or configuration change.

## Affected modules and routes

- Go module: repository root, `github.com/pingcap-inc/clinic`.
- Package: `pkg/auth/session`.
- Direct consumer: `pkg/api/login`.
- Entrypoint: `cmd/server/main.go`.
- Route: `POST /clinic/api/v1/login/oauth/:name/validate`.
- Produced image: `clinic`.

Deployment chain: root module -> `cmd/server` -> `clinic` image -> Clinic CD `components=clinic` -> app-delivery `clinic-api` -> Clinic Deployment/app `clinic`.

No app-delivery configuration change is required. The `api-gateway`, Internal API, Task Manager, Importer, Uploader, NGM, Clinic Data Service, and Cloud Server images do not require deployment. The Clinic Kong plugin already reads and validates the expiration embedded in the token, so it has no separate session-duration setting to update.

## Implementation steps

1. Change the shared `sessionTimeout` from 24 hours to seven days so JWT issuance and browser-cookie retention remain aligned.
2. Add a focused test that creates and cryptographically validates a signed session JWT, then verifies that its `exp` claim is seven days after issuance.
3. Add a focused test that emits the Clinic session cookie through Gin and verifies its name, value, and exact seven-day `Max-Age`.
4. Run focused session and login-package tests, Go vet, and diff validation.

## Exclusions and compatibility

- Do not add sliding expiration, activity-based renewal, refresh tokens, or server-side session storage.
- Do not make the lifetime environment-configurable.
- Do not change OAuth state-token expiration, API keys, internal credentials, user-debug credentials, CSRF validation, JWT signing, session-secret handling, or secure-cookie behavior.
- Do not change the gateway plugin or app-delivery configuration.
- Do not backfill, rewrite, or invalidate sessions issued before deployment.
- The longer fixed lifetime intentionally extends the validity window of a copied session token; token revocation and cookie-hardening changes are outside this PR.

## Test plan

- `go test ./pkg/auth/session ./pkg/api/login -count=1`
- `go test ./pkg/auth/session -count=100`
- `go test -race ./pkg/auth/session`
- `go test ./pkg/api_gateway/auth/session -count=1`
- `go vet ./pkg/auth/session ./pkg/api/login ./pkg/api_gateway/auth/session`
- `git diff --check origin/master...HEAD`
- Confirm CI build, module, Swagger, lint, and test checks complete successfully.

## Staging verification

- Dispatch Clinic CD from the feature branch with `environment=staging` and `components=clinic` after authorization.
- Wait for the generated app-delivery staging PR to merge and for GitOps reconciliation; do not treat the source CD run alone as rollout completion.
- Verify a successful OAuth login returns a valid Clinic JWT whose `exp` is seven days after issuance and writes `clinic.session_id` with `Max-Age=604800`.
- Verify the new cookie authenticates a follow-up Clinic request through the deployed gateway.
- Verify invalid and expired sessions remain unauthorized and logout clears the browser cookie.
- When approved EKS access is available, confirm the Clinic Pod is Ready, has no unexpected restarts, and runs the expected feature image. Record when this live-state inspection cannot be performed.

## Release boundary

- The Clinic source PR requires all repository checks and reviews plus explicit user authorization before merge.
- Staging deployment uses Clinic CD `environment=staging` and `components=clinic`; it does not authorize merging the source PR.
- Production requires a separate, explicitly authorized Clinic CD dispatch with `environment=prod-cloud` and `components=clinic` after merge.
- The generated production app-delivery PR requires normal checks, review, and separate explicit merge authorization.
- `prod-op` is intentionally out of scope.