[DT-3629] Enable Postgres, Session, and Cookie plugins

[rushtong]

Addresses

https://broadworkbench.atlassian.net/browse/DT-3629

Summary

Phase 1 of the BFF migration: server-side, PostgreSQL-backed session infrastructure for the Fastify server. No user-visible changes — the infrastructure is inert until users are routed to it by the Phase 2 auth routes.

The DB/cookie/session plugins register only when the deployment provides the database configuration (DUOS_DB_HOST etc.), so the legacy client-side auth flow is completely unaffected until an environment is configured for the BFF — and every pod of a deployment behaves identically, with no network dependency at boot.

Changes

Session infrastructure (server/src/)

• index.ts: registers @fastify/postgres, @fastify/cookie, and @fastify/session only when DUOS_DB_HOST is set. Validates DUOS_SESSION_SECRET (32+ chars) with an actionable error. Sets trustProxy: 1 so request.protocol honors the reverse proxy's X-Forwarded-Proto — without it, secure cookies silently never persist behind TLS-terminating proxies.
• session/pgStore.ts: a thin typed SessionStore (get/set/destroy) against the user_sessions table. Expiry is computed in SQL from the same clock get filters with, so app/DB clock drift can't shorten or extend sessions. No rolling expiry — sessions get a fixed maxAge; Phase 2 adds throttled sliding expiry instead of a DB write per request.
• types/session.ts: module augmentation typing the session payload (tokens live only server-side, never sent to the browser).
• Postgres TLS is secure-by-default: DUOS_DB_SSL must be explicitly set to false for loopback transports (Cloud SQL Proxy sidecar, local compose), and doing so logs a warning.

Client config serving

• config.ts: /config.json is now served by the server (via an onRequest hook, to avoid colliding with @fastify/vite's static route for the same file), with DUOS_API_URL overriding the static file's apiUrl. Deployed environments already carry the matching value via terra-helmfile; locally there's now one place to point at a different consent API.

Local development

• docker-compose.yaml is split into a shared base plus two overlays: docker-compose.override.yaml (standalone — bundled Postgres stands in for the consent DB, auto-merged by Compose) and docker-compose.consent.yaml (shares a local consent compose stack's database, avoiding port collisions with its sqlproxy and app).
• New .env.example template; both compose modes and pnpm start:server read .env.local.
• DEVNOTES.md: full walkthrough of both modes, including the consent-DB sharing setup.

Deployment notes

• Requires https://github.com/broadinstitute/terra-helmfile/pull/6462 (DUOS_DB_SSL: "false" for the Cloud SQL Proxy sidecar). The X-Forwarded-Proto + duos_api_url changes already landed in https://github.com/broadinstitute/terra-helmfile/pull/6460.
• This branch (with the helmfile updates) is deployed to a BEE: https://duos.grushton-dt-3629.bee.envs-terra.bio/

---

Have you read Terra's Contributing Guide lately? If not, do that first.

• Label PR with a Jira ticket number and include a link to the ticket
• Label PR with a security risk modifier [no, low, medium, high]
• PR describes scope of changes
• Get a minimum of one thumbs worth of review, preferably two if enough team members are available
• Get PO sign-off for all non-trivial UI or workflow changes
• Verify all tests go green
• Test this change deployed correctly and works on dev environment after deployment

[github-actions]

Coverage Report for DUOS Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	85.74%	9908 / 11556
🔵	Statements	85.18%	10507 / 12335
🔵	Functions	81.73%	2885 / 3530
🔵	Branches	77.13%	6000 / 7779

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
server/src/config.ts	100%	100%	100%	100%
server/src/index.ts	78.57%	67.3%	83.33%	78.43%	87, 171, 184-196
server/src/session/pgStore.ts	100%	100%	100%	100%
server/src/types/session.ts	100%	100%	100%	100%

Generated in workflow #6291 for commit 584eded by the Vitest Coverage Report Action

[Copilot]

Pull request overview

Adds the Phase 1 “server foundation” pieces for the BFF migration by introducing PostgreSQL-backed server sessions in the Fastify server, and gating all DB/cookie/session startup behind the consent-served BFF_ENABLED feature flag so the existing client-side auth flow remains unaffected until rollout.

Changes:

• Introduces a Postgres-backed @fastify/session store (createPgSessionStore) and session type augmentation for server-side auth state.
• Gates Postgres + cookie + session plugin registration behind isBffEnabled() (fetched from {DUOS_API_URL}/feature/BFF_ENABLED), and adds /config.json interception to support DUOS_API_URL overrides.
• Adds Vitest coverage for the session store, feature flag behavior, and client config behavior; updates local-dev Docker Compose files and DEVNOTES accordingly.

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
server/test/session.test.ts	New integration-ish test exercising cookie/session behavior end-to-end with an in-memory PG stand-in.
server/test/pgStore.test.ts	New unit tests validating SQL and expiry behavior for the Postgres session store.
server/test/index.test.ts	Extends server bootstrap tests to cover /config.json override and BFF flag gating.
server/test/featureFlags.test.ts	New tests for isBffEnabled() behavior and request shape.
server/test/clientConfig.test.ts	New tests for config path resolution and DUOS_API_URL override behavior.
server/src/types/session.ts	Adds Fastify Session module augmentation for typed session fields.
server/src/session/pgStore.ts	Implements the Postgres-backed session store used by @fastify/session.
server/src/index.ts	Gates DB/cookie/session startup behind BFF_ENABLED, enables trustProxy, and intercepts /config.json.
server/src/featureFlags.ts	Adds consent-backed feature flag fetcher for BFF_ENABLED.
server/src/config.ts	Removes legacy config loader/caching module (superseded by clientConfig flow).
server/src/clientConfig.ts	Adds config.json path resolution + runtime read with optional DUOS_API_URL override.
docs/plans/BFF_Overview.md	Marks Phase 1 as complete.
docker-compose.yaml	Refactors base compose file and documents the two local dev modes and env var strategy.
docker-compose.override.yaml	Adds “standalone” mode overlay with a bundled Postgres container.
docker-compose.consent.yaml	Adds overlay for running against a local consent stack’s Postgres/proxy.
DEVNOTES.md	Updates Docker run instructions and documents the two compose modes and DB host behavior.
.gitignore	Ignores .env and the local consent DB dump used by the bundled DB container.
.env.example	Adds a template env file for local BFF-related configuration.

[fboulnois]

A few suggestions. Claude has also flagged that the way we do feature flags isn't optimal. This is a preexisting issue, but worthwhile to think about:

await isBffEnabled(...) runs once in buildApp() and is never re-checked. A transient consent blip or >5s response during a rolling deploy makes a pod come up with no DB/session plugins for its entire lifetime, silently serving legacy auth even after consent recovers and flipping the flag on requires restarting every pod. During rollout this yields per-pod inconsistency visible only in logs.

[rushtong]

Great feedback @fboulnois - I'm going to revisit the plan and make some fundamental changes and hope to address all of the feedback in one go.

[rushtong]

@fboulnois thanks for the review — the feature-flag concern was the important one, and it exposed a deeper problem: the plan defines BFF_ENABLED as a client-side rollout gate, so the server checking it at boot was a divergence, with exactly the failure modes you described (a consent blip permanently downgrades a pod; flag flips need restarts).

1fcde3b removes the boot-time flag check entirely. The server now registers its DB/cookie/session plugins whenever the deployment provides the database config (DUOS_DB_HOST), so every pod of a deployment behaves identically with no network dependency at startup — a half-configured pod (DB host set, session secret missing) fails loud instead of silently booting legacy. The infrastructure is inert until users are routed to it (saveUninitialized: false, no auth routes yet). BFF_ENABLED goes back to its planned role: the client-side flag deciding which sign-in flow users get, flippable with no redeploys. The two-switch model is documented in docs/plans/BFF_Overview.md.

Also in that commit, per the inline threads: secure-by-default Postgres TLS with an explicit coerced opt-out, rolling dropped (throttled sliding expiry planned for Phase 2), session expiry computed on Postgres's clock with a non-positive-maxAge guard, and the store methods collapsed through a single run() helper.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud