fix(frontend): DEPLOY_ENV single source of truth + env-mismatch guard (fixes staging session_expired)

[Darkest-Teddy]

Why

Login on staging.saplinglearn.com bounces to /?error=session_expired. This is the footgun documented in ADR 0020 — the frontend's environment config (backend origin + session-cookie Domain) can drift from the environment the worker is actually serving, so staging ends up validating a session cookie signed with the wrong SESSION_SECRET and treats every visitor as logged out.

The fix was written on fix/staging-deploy-env but never landed on main (that branch also carries unrelated RAG changes). This PR cherry-picks only the frontend/deploy hardening + the ADR — nothing else.

What

Make DEPLOY_ENV the single knob that drives every environment-specific value, with the explicit vars kept as backward-compatible fallbacks (deployGuard.resolveFrontendEnv):

• middleware.ts — derives API_URL via resolveFrontendEnv, and on a protected route calls detectHostConfigMismatch(host, apiUrl). A worker serving one env's host while wired to another's backend now logs a loud server error and redirects with a distinct env_misconfig code instead of the misleading session_expired.
• app/api/auth/session/route.ts — derives the cookie Domain from resolveFrontendEnv, so a staging build can't mint a .saplinglearn.com cookie that leaks into prod.
• next.config.ts — derives the build-time BACKEND_URL (the /api rewrite) and inlined NEXT_PUBLIC_API_URL/COOKIE_DOMAIN from DEPLOY_ENV.
• wrangler.toml — DEPLOY_ENV = "production" in [vars], DEPLOY_ENV = "staging" in [env.staging.vars]; documents the Build-command vs Deploy-command distinction.
• SignInModal.tsx — user-facing copy for env_misconfig.
• ADR 0020 — records the root cause and the operational follow-up.

⚠️ Operational follow-up (code alone does NOT fix staging)

Per ADR 0020, the running staging worker still needs a real redeploy:

1. Set DEPLOY_ENV=staging as a build variable on the frontend-staging Workers Build (build command stays npm run cf:build — never a deploy line).
2. Ensure the new version is actually activated (the deploy step is wrangler versions upload, which uploads but doesn't promote — promote it, or switch the deploy command to wrangler deploy --env staging).
3. Verify: curl -sSI https://staging.saplinglearn.com/dashboard → Location: https://api.staging.saplinglearn.com/api/auth/google.

Testing

• deployGuard.test.ts extended (132 lines) — runs under npm test on CI (Node 22).
• tsc --noEmit ✅ and eslint ✅ on changed files.
• Verified the core runtime logic locally (vitest can't start on Node 20.12 — repo pins Node 22) by executing the compiled module: resolveFrontendEnv derivation for staging/production/unset, and detectHostConfigMismatch flagging staging-host→prod-backend while leaving previews/localhost alone. All assertions passed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved environment detection to prevent staging and production configuration mismatches.
  • Sign-in now shows a clear configuration error instead of an expired-session message when deployment settings conflict.
  • Session cookies and API routing now use the correct environment-specific settings.

• Documentation

  • Added deployment guidance covering environment configuration, staging verification, and redeployment requirements.

• Tests

  • Expanded coverage for environment resolution, host detection, and configuration mismatch handling.

[AndresL230]

Code review

Found 1 issue:

1. The DEPLOY_ENV derivation in next.config.ts runs beforecheckFrontendDeployEnv, unconditionally overwriting BACKEND_URL/NEXT_PUBLIC_API_URL/COOKIE_DOMAIN with values derived from DEPLOY_ENV — so the explicit-var cross-check (deployGuard's "explicit lock" branch, unit-tested as catching "all-staging values on a prod deploy") can never fire once DEPLOY_ENV is set, which this PR's own wrangler.toml change guarantees. The documented fail-loud layer becomes a silent auto-correct: a wrong DEPLOY_ENV pasted into the other environment's build panel bakes the wrong backend URL and cookie domain into the build with no error, where pre-PR the explicit vars would have won. Reproduced: check-then-derive returns the mismatch error; derive-then-check returns []. Fix: run the cross-check against the original env before the derivation mutates it. (bug due to frontend/next.config.ts — const RESOLVED = resolveFrontendEnv(process.env); if (RESOLVED.derived) { process.env.BACKEND_URL = ... } preceding checkFrontendDeployEnv(process.env))

Sapling/frontend/next.config.ts

Lines 13 to 20 in ed0839e

	// legacy build that sets BACKEND_URL directly).
	constRESOLVED=resolveFrontendEnv(process.env);
	if(RESOLVED.derived){
	process.env.BACKEND_URL=RESOLVED.apiUrl;
	process.env.NEXT_PUBLIC_API_URL=RESOLVED.apiUrl;
	if(RESOLVED.cookieDomain)process.env.COOKIE_DOMAIN=RESOLVED.cookieDomain;
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

The ordering issue from the review above is fixed in the latest push: checkFrontendDeployEnv now runs against the operator-provided env BEFORE the DEPLOY_ENV derivation mutates it, restoring the fail-loud explicit-lock layer; the post-derive duplicate check was removed and wrangler.toml's ADR pointer updated to 0022.

[Darkest-Teddy]

Why

Login on staging.saplinglearn.com bounces to /?error=session_expired. This is the footgun documented in ADR 0020 — the frontend's environment config (backend origin + session-cookie Domain) can drift from the environment the worker is actually serving, so staging ends up validating a session cookie signed with the wrong SESSION_SECRET and treats every visitor as logged out.

The fix was written on fix/staging-deploy-env but never landed on main (that branch also carries unrelated RAG changes). This PR cherry-picks only the frontend/deploy hardening + the ADR — nothing else.

What

Make DEPLOY_ENV the single knob that drives every environment-specific value, with the explicit vars kept as backward-compatible fallbacks (deployGuard.resolveFrontendEnv):

• middleware.ts — derives API_URL via resolveFrontendEnv, and on a protected route calls detectHostConfigMismatch(host, apiUrl). A worker serving one env's host while wired to another's backend now logs a loud server error and redirects with a distinct env_misconfig code instead of the misleading session_expired.
• app/api/auth/session/route.ts — derives the cookie Domain from resolveFrontendEnv, so a staging build can't mint a .saplinglearn.com cookie that leaks into prod.
• next.config.ts — derives the build-time BACKEND_URL (the /api rewrite) and inlined NEXT_PUBLIC_API_URL/COOKIE_DOMAIN from DEPLOY_ENV.
• wrangler.toml — DEPLOY_ENV = "production" in [vars], DEPLOY_ENV = "staging" in [env.staging.vars]; documents the Build-command vs Deploy-command distinction.
• SignInModal.tsx — user-facing copy for env_misconfig.
• ADR 0020 — records the root cause and the operational follow-up.

⚠️ Operational follow-up (code alone does NOT fix staging)

Per ADR 0020, the running staging worker still needs a real redeploy:

1. Set DEPLOY_ENV=staging as a build variable on the frontend-staging Workers Build (build command stays npm run cf:build — never a deploy line).
2. Ensure the new version is actually activated (the deploy step is wrangler versions upload, which uploads but doesn't promote — promote it, or switch the deploy command to wrangler deploy --env staging).
3. Verify: curl -sSI https://staging.saplinglearn.com/dashboard → Location: https://api.staging.saplinglearn.com/api/auth/google.

Testing

• deployGuard.test.ts extended (132 lines) — runs under npm test on CI (Node 22).
• tsc --noEmit ✅ and eslint ✅ on changed files.
• Verified the core runtime logic locally (vitest can't start on Node 20.12 — repo pins Node 22) by executing the compiled module: resolveFrontendEnv derivation for staging/production/unset, and detectHostConfigMismatch flagging staging-host→prod-backend while leaving previews/localhost alone. All assertions passed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved environment detection to prevent staging and production configuration mismatches.
  • Sign-in now shows a clear configuration error instead of an expired-session message when deployment settings conflict.
  • Session cookies and API routing now use the correct environment-specific settings.

• Documentation

  • Added deployment guidance covering environment configuration, staging verification, and redeployment requirements.

• Tests

  • Expanded coverage for environment resolution, host detection, and configuration mismatch handling.

[AndresL230]

Code review

Found 1 issue:

1. The DEPLOY_ENV derivation in next.config.ts runs beforecheckFrontendDeployEnv, unconditionally overwriting BACKEND_URL/NEXT_PUBLIC_API_URL/COOKIE_DOMAIN with values derived from DEPLOY_ENV — so the explicit-var cross-check (deployGuard's "explicit lock" branch, unit-tested as catching "all-staging values on a prod deploy") can never fire once DEPLOY_ENV is set, which this PR's own wrangler.toml change guarantees. The documented fail-loud layer becomes a silent auto-correct: a wrong DEPLOY_ENV pasted into the other environment's build panel bakes the wrong backend URL and cookie domain into the build with no error, where pre-PR the explicit vars would have won. Reproduced: check-then-derive returns the mismatch error; derive-then-check returns []. Fix: run the cross-check against the original env before the derivation mutates it. (bug due to frontend/next.config.ts — const RESOLVED = resolveFrontendEnv(process.env); if (RESOLVED.derived) { process.env.BACKEND_URL = ... } preceding checkFrontendDeployEnv(process.env))

Sapling/frontend/next.config.ts

Lines 13 to 20 in ed0839e

	// legacy build that sets BACKEND_URL directly).
	constRESOLVED=resolveFrontendEnv(process.env);
	if(RESOLVED.derived){
	process.env.BACKEND_URL=RESOLVED.apiUrl;
	process.env.NEXT_PUBLIC_API_URL=RESOLVED.apiUrl;
	if(RESOLVED.cookieDomain)process.env.COOKIE_DOMAIN=RESOLVED.cookieDomain;
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

The ordering issue from the review above is fixed in the latest push: checkFrontendDeployEnv now runs against the operator-provided env BEFORE the DEPLOY_ENV derivation mutates it, restoring the fail-loud explicit-lock layer; the post-derive duplicate check was removed and wrangler.toml's ADR pointer updated to 0022.

[Darkest-Teddy]

Why

Login on staging.saplinglearn.com bounces to /?error=session_expired. This is the footgun documented in ADR 0020 — the frontend's environment config (backend origin + session-cookie Domain) can drift from the environment the worker is actually serving, so staging ends up validating a session cookie signed with the wrong SESSION_SECRET and treats every visitor as logged out.

The fix was written on fix/staging-deploy-env but never landed on main (that branch also carries unrelated RAG changes). This PR cherry-picks only the frontend/deploy hardening + the ADR — nothing else.

What

Make DEPLOY_ENV the single knob that drives every environment-specific value, with the explicit vars kept as backward-compatible fallbacks (deployGuard.resolveFrontendEnv):

• middleware.ts — derives API_URL via resolveFrontendEnv, and on a protected route calls detectHostConfigMismatch(host, apiUrl). A worker serving one env's host while wired to another's backend now logs a loud server error and redirects with a distinct env_misconfig code instead of the misleading session_expired.
• app/api/auth/session/route.ts — derives the cookie Domain from resolveFrontendEnv, so a staging build can't mint a .saplinglearn.com cookie that leaks into prod.
• next.config.ts — derives the build-time BACKEND_URL (the /api rewrite) and inlined NEXT_PUBLIC_API_URL/COOKIE_DOMAIN from DEPLOY_ENV.
• wrangler.toml — DEPLOY_ENV = "production" in [vars], DEPLOY_ENV = "staging" in [env.staging.vars]; documents the Build-command vs Deploy-command distinction.
• SignInModal.tsx — user-facing copy for env_misconfig.
• ADR 0020 — records the root cause and the operational follow-up.

⚠️ Operational follow-up (code alone does NOT fix staging)

Per ADR 0020, the running staging worker still needs a real redeploy:

1. Set DEPLOY_ENV=staging as a build variable on the frontend-staging Workers Build (build command stays npm run cf:build — never a deploy line).
2. Ensure the new version is actually activated (the deploy step is wrangler versions upload, which uploads but doesn't promote — promote it, or switch the deploy command to wrangler deploy --env staging).
3. Verify: curl -sSI https://staging.saplinglearn.com/dashboard → Location: https://api.staging.saplinglearn.com/api/auth/google.

Testing

• deployGuard.test.ts extended (132 lines) — runs under npm test on CI (Node 22).
• tsc --noEmit ✅ and eslint ✅ on changed files.
• Verified the core runtime logic locally (vitest can't start on Node 20.12 — repo pins Node 22) by executing the compiled module: resolveFrontendEnv derivation for staging/production/unset, and detectHostConfigMismatch flagging staging-host→prod-backend while leaving previews/localhost alone. All assertions passed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved environment detection to prevent staging and production configuration mismatches.
  • Sign-in now shows a clear configuration error instead of an expired-session message when deployment settings conflict.
  • Session cookies and API routing now use the correct environment-specific settings.

• Documentation

  • Added deployment guidance covering environment configuration, staging verification, and redeployment requirements.

• Tests

  • Expanded coverage for environment resolution, host detection, and configuration mismatch handling.

[AndresL230]

Code review

Found 1 issue:

1. The DEPLOY_ENV derivation in next.config.ts runs beforecheckFrontendDeployEnv, unconditionally overwriting BACKEND_URL/NEXT_PUBLIC_API_URL/COOKIE_DOMAIN with values derived from DEPLOY_ENV — so the explicit-var cross-check (deployGuard's "explicit lock" branch, unit-tested as catching "all-staging values on a prod deploy") can never fire once DEPLOY_ENV is set, which this PR's own wrangler.toml change guarantees. The documented fail-loud layer becomes a silent auto-correct: a wrong DEPLOY_ENV pasted into the other environment's build panel bakes the wrong backend URL and cookie domain into the build with no error, where pre-PR the explicit vars would have won. Reproduced: check-then-derive returns the mismatch error; derive-then-check returns []. Fix: run the cross-check against the original env before the derivation mutates it. (bug due to frontend/next.config.ts — const RESOLVED = resolveFrontendEnv(process.env); if (RESOLVED.derived) { process.env.BACKEND_URL = ... } preceding checkFrontendDeployEnv(process.env))

Sapling/frontend/next.config.ts

Lines 13 to 20 in ed0839e

	// legacy build that sets BACKEND_URL directly).
	constRESOLVED=resolveFrontendEnv(process.env);
	if(RESOLVED.derived){
	process.env.BACKEND_URL=RESOLVED.apiUrl;
	process.env.NEXT_PUBLIC_API_URL=RESOLVED.apiUrl;
	if(RESOLVED.cookieDomain)process.env.COOKIE_DOMAIN=RESOLVED.cookieDomain;
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

The ordering issue from the review above is fixed in the latest push: checkFrontendDeployEnv now runs against the operator-provided env BEFORE the DEPLOY_ENV derivation mutates it, restoring the fail-loud explicit-lock layer; the post-derive duplicate check was removed and wrangler.toml's ADR pointer updated to 0022.

[Darkest-Teddy]

Why

Login on staging.saplinglearn.com bounces to /?error=session_expired. This is the footgun documented in ADR 0020 — the frontend's environment config (backend origin + session-cookie Domain) can drift from the environment the worker is actually serving, so staging ends up validating a session cookie signed with the wrong SESSION_SECRET and treats every visitor as logged out.

The fix was written on fix/staging-deploy-env but never landed on main (that branch also carries unrelated RAG changes). This PR cherry-picks only the frontend/deploy hardening + the ADR — nothing else.

What

Make DEPLOY_ENV the single knob that drives every environment-specific value, with the explicit vars kept as backward-compatible fallbacks (deployGuard.resolveFrontendEnv):

• middleware.ts — derives API_URL via resolveFrontendEnv, and on a protected route calls detectHostConfigMismatch(host, apiUrl). A worker serving one env's host while wired to another's backend now logs a loud server error and redirects with a distinct env_misconfig code instead of the misleading session_expired.
• app/api/auth/session/route.ts — derives the cookie Domain from resolveFrontendEnv, so a staging build can't mint a .saplinglearn.com cookie that leaks into prod.
• next.config.ts — derives the build-time BACKEND_URL (the /api rewrite) and inlined NEXT_PUBLIC_API_URL/COOKIE_DOMAIN from DEPLOY_ENV.
• wrangler.toml — DEPLOY_ENV = "production" in [vars], DEPLOY_ENV = "staging" in [env.staging.vars]; documents the Build-command vs Deploy-command distinction.
• SignInModal.tsx — user-facing copy for env_misconfig.
• ADR 0020 — records the root cause and the operational follow-up.

⚠️ Operational follow-up (code alone does NOT fix staging)

Per ADR 0020, the running staging worker still needs a real redeploy:

1. Set DEPLOY_ENV=staging as a build variable on the frontend-staging Workers Build (build command stays npm run cf:build — never a deploy line).
2. Ensure the new version is actually activated (the deploy step is wrangler versions upload, which uploads but doesn't promote — promote it, or switch the deploy command to wrangler deploy --env staging).
3. Verify: curl -sSI https://staging.saplinglearn.com/dashboard → Location: https://api.staging.saplinglearn.com/api/auth/google.

Testing

• deployGuard.test.ts extended (132 lines) — runs under npm test on CI (Node 22).
• tsc --noEmit ✅ and eslint ✅ on changed files.
• Verified the core runtime logic locally (vitest can't start on Node 20.12 — repo pins Node 22) by executing the compiled module: resolveFrontendEnv derivation for staging/production/unset, and detectHostConfigMismatch flagging staging-host→prod-backend while leaving previews/localhost alone. All assertions passed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved environment detection to prevent staging and production configuration mismatches.
  • Sign-in now shows a clear configuration error instead of an expired-session message when deployment settings conflict.
  • Session cookies and API routing now use the correct environment-specific settings.

• Documentation

  • Added deployment guidance covering environment configuration, staging verification, and redeployment requirements.

• Tests

  • Expanded coverage for environment resolution, host detection, and configuration mismatch handling.

[AndresL230]

Code review

Found 1 issue:

1. The DEPLOY_ENV derivation in next.config.ts runs beforecheckFrontendDeployEnv, unconditionally overwriting BACKEND_URL/NEXT_PUBLIC_API_URL/COOKIE_DOMAIN with values derived from DEPLOY_ENV — so the explicit-var cross-check (deployGuard's "explicit lock" branch, unit-tested as catching "all-staging values on a prod deploy") can never fire once DEPLOY_ENV is set, which this PR's own wrangler.toml change guarantees. The documented fail-loud layer becomes a silent auto-correct: a wrong DEPLOY_ENV pasted into the other environment's build panel bakes the wrong backend URL and cookie domain into the build with no error, where pre-PR the explicit vars would have won. Reproduced: check-then-derive returns the mismatch error; derive-then-check returns []. Fix: run the cross-check against the original env before the derivation mutates it. (bug due to frontend/next.config.ts — const RESOLVED = resolveFrontendEnv(process.env); if (RESOLVED.derived) { process.env.BACKEND_URL = ... } preceding checkFrontendDeployEnv(process.env))

Sapling/frontend/next.config.ts

Lines 13 to 20 in ed0839e

	// legacy build that sets BACKEND_URL directly).
	constRESOLVED=resolveFrontendEnv(process.env);
	if(RESOLVED.derived){
	process.env.BACKEND_URL=RESOLVED.apiUrl;
	process.env.NEXT_PUBLIC_API_URL=RESOLVED.apiUrl;
	if(RESOLVED.cookieDomain)process.env.COOKIE_DOMAIN=RESOLVED.cookieDomain;
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

The ordering issue from the review above is fixed in the latest push: checkFrontendDeployEnv now runs against the operator-provided env BEFORE the DEPLOY_ENV derivation mutates it, restoring the fail-loud explicit-lock layer; the post-derive duplicate check was removed and wrangler.toml's ADR pointer updated to 0022.

[Darkest-Teddy]

Why

Login on staging.saplinglearn.com bounces to /?error=session_expired. This is the footgun documented in ADR 0020 — the frontend's environment config (backend origin + session-cookie Domain) can drift from the environment the worker is actually serving, so staging ends up validating a session cookie signed with the wrong SESSION_SECRET and treats every visitor as logged out.

The fix was written on fix/staging-deploy-env but never landed on main (that branch also carries unrelated RAG changes). This PR cherry-picks only the frontend/deploy hardening + the ADR — nothing else.

What

Make DEPLOY_ENV the single knob that drives every environment-specific value, with the explicit vars kept as backward-compatible fallbacks (deployGuard.resolveFrontendEnv):

• middleware.ts — derives API_URL via resolveFrontendEnv, and on a protected route calls detectHostConfigMismatch(host, apiUrl). A worker serving one env's host while wired to another's backend now logs a loud server error and redirects with a distinct env_misconfig code instead of the misleading session_expired.
• app/api/auth/session/route.ts — derives the cookie Domain from resolveFrontendEnv, so a staging build can't mint a .saplinglearn.com cookie that leaks into prod.
• next.config.ts — derives the build-time BACKEND_URL (the /api rewrite) and inlined NEXT_PUBLIC_API_URL/COOKIE_DOMAIN from DEPLOY_ENV.
• wrangler.toml — DEPLOY_ENV = "production" in [vars], DEPLOY_ENV = "staging" in [env.staging.vars]; documents the Build-command vs Deploy-command distinction.
• SignInModal.tsx — user-facing copy for env_misconfig.
• ADR 0020 — records the root cause and the operational follow-up.

⚠️ Operational follow-up (code alone does NOT fix staging)

Per ADR 0020, the running staging worker still needs a real redeploy:

1. Set DEPLOY_ENV=staging as a build variable on the frontend-staging Workers Build (build command stays npm run cf:build — never a deploy line).
2. Ensure the new version is actually activated (the deploy step is wrangler versions upload, which uploads but doesn't promote — promote it, or switch the deploy command to wrangler deploy --env staging).
3. Verify: curl -sSI https://staging.saplinglearn.com/dashboard → Location: https://api.staging.saplinglearn.com/api/auth/google.

Testing

• deployGuard.test.ts extended (132 lines) — runs under npm test on CI (Node 22).
• tsc --noEmit ✅ and eslint ✅ on changed files.
• Verified the core runtime logic locally (vitest can't start on Node 20.12 — repo pins Node 22) by executing the compiled module: resolveFrontendEnv derivation for staging/production/unset, and detectHostConfigMismatch flagging staging-host→prod-backend while leaving previews/localhost alone. All assertions passed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved environment detection to prevent staging and production configuration mismatches.
  • Sign-in now shows a clear configuration error instead of an expired-session message when deployment settings conflict.
  • Session cookies and API routing now use the correct environment-specific settings.

• Documentation

  • Added deployment guidance covering environment configuration, staging verification, and redeployment requirements.

• Tests

  • Expanded coverage for environment resolution, host detection, and configuration mismatch handling.

[AndresL230]

Code review

Found 1 issue:

1. The DEPLOY_ENV derivation in next.config.ts runs beforecheckFrontendDeployEnv, unconditionally overwriting BACKEND_URL/NEXT_PUBLIC_API_URL/COOKIE_DOMAIN with values derived from DEPLOY_ENV — so the explicit-var cross-check (deployGuard's "explicit lock" branch, unit-tested as catching "all-staging values on a prod deploy") can never fire once DEPLOY_ENV is set, which this PR's own wrangler.toml change guarantees. The documented fail-loud layer becomes a silent auto-correct: a wrong DEPLOY_ENV pasted into the other environment's build panel bakes the wrong backend URL and cookie domain into the build with no error, where pre-PR the explicit vars would have won. Reproduced: check-then-derive returns the mismatch error; derive-then-check returns []. Fix: run the cross-check against the original env before the derivation mutates it. (bug due to frontend/next.config.ts — const RESOLVED = resolveFrontendEnv(process.env); if (RESOLVED.derived) { process.env.BACKEND_URL = ... } preceding checkFrontendDeployEnv(process.env))

Sapling/frontend/next.config.ts

Lines 13 to 20 in ed0839e

	// legacy build that sets BACKEND_URL directly).
	constRESOLVED=resolveFrontendEnv(process.env);
	if(RESOLVED.derived){
	process.env.BACKEND_URL=RESOLVED.apiUrl;
	process.env.NEXT_PUBLIC_API_URL=RESOLVED.apiUrl;
	if(RESOLVED.cookieDomain)process.env.COOKIE_DOMAIN=RESOLVED.cookieDomain;
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

The ordering issue from the review above is fixed in the latest push: checkFrontendDeployEnv now runs against the operator-provided env BEFORE the DEPLOY_ENV derivation mutates it, restoring the fail-loud explicit-lock layer; the post-derive duplicate check was removed and wrangler.toml's ADR pointer updated to 0022.

[Darkest-Teddy]

Why

Login on staging.saplinglearn.com bounces to /?error=session_expired. This is the footgun documented in ADR 0020 — the frontend's environment config (backend origin + session-cookie Domain) can drift from the environment the worker is actually serving, so staging ends up validating a session cookie signed with the wrong SESSION_SECRET and treats every visitor as logged out.

The fix was written on fix/staging-deploy-env but never landed on main (that branch also carries unrelated RAG changes). This PR cherry-picks only the frontend/deploy hardening + the ADR — nothing else.

What

Make DEPLOY_ENV the single knob that drives every environment-specific value, with the explicit vars kept as backward-compatible fallbacks (deployGuard.resolveFrontendEnv):

• middleware.ts — derives API_URL via resolveFrontendEnv, and on a protected route calls detectHostConfigMismatch(host, apiUrl). A worker serving one env's host while wired to another's backend now logs a loud server error and redirects with a distinct env_misconfig code instead of the misleading session_expired.
• app/api/auth/session/route.ts — derives the cookie Domain from resolveFrontendEnv, so a staging build can't mint a .saplinglearn.com cookie that leaks into prod.
• next.config.ts — derives the build-time BACKEND_URL (the /api rewrite) and inlined NEXT_PUBLIC_API_URL/COOKIE_DOMAIN from DEPLOY_ENV.
• wrangler.toml — DEPLOY_ENV = "production" in [vars], DEPLOY_ENV = "staging" in [env.staging.vars]; documents the Build-command vs Deploy-command distinction.
• SignInModal.tsx — user-facing copy for env_misconfig.
• ADR 0020 — records the root cause and the operational follow-up.

⚠️ Operational follow-up (code alone does NOT fix staging)

Per ADR 0020, the running staging worker still needs a real redeploy:

1. Set DEPLOY_ENV=staging as a build variable on the frontend-staging Workers Build (build command stays npm run cf:build — never a deploy line).
2. Ensure the new version is actually activated (the deploy step is wrangler versions upload, which uploads but doesn't promote — promote it, or switch the deploy command to wrangler deploy --env staging).
3. Verify: curl -sSI https://staging.saplinglearn.com/dashboard → Location: https://api.staging.saplinglearn.com/api/auth/google.

Testing

• deployGuard.test.ts extended (132 lines) — runs under npm test on CI (Node 22).
• tsc --noEmit ✅ and eslint ✅ on changed files.
• Verified the core runtime logic locally (vitest can't start on Node 20.12 — repo pins Node 22) by executing the compiled module: resolveFrontendEnv derivation for staging/production/unset, and detectHostConfigMismatch flagging staging-host→prod-backend while leaving previews/localhost alone. All assertions passed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved environment detection to prevent staging and production configuration mismatches.
  • Sign-in now shows a clear configuration error instead of an expired-session message when deployment settings conflict.
  • Session cookies and API routing now use the correct environment-specific settings.

• Documentation

  • Added deployment guidance covering environment configuration, staging verification, and redeployment requirements.

• Tests

  • Expanded coverage for environment resolution, host detection, and configuration mismatch handling.

[AndresL230]

Code review

Found 1 issue:

1. The DEPLOY_ENV derivation in next.config.ts runs beforecheckFrontendDeployEnv, unconditionally overwriting BACKEND_URL/NEXT_PUBLIC_API_URL/COOKIE_DOMAIN with values derived from DEPLOY_ENV — so the explicit-var cross-check (deployGuard's "explicit lock" branch, unit-tested as catching "all-staging values on a prod deploy") can never fire once DEPLOY_ENV is set, which this PR's own wrangler.toml change guarantees. The documented fail-loud layer becomes a silent auto-correct: a wrong DEPLOY_ENV pasted into the other environment's build panel bakes the wrong backend URL and cookie domain into the build with no error, where pre-PR the explicit vars would have won. Reproduced: check-then-derive returns the mismatch error; derive-then-check returns []. Fix: run the cross-check against the original env before the derivation mutates it. (bug due to frontend/next.config.ts — const RESOLVED = resolveFrontendEnv(process.env); if (RESOLVED.derived) { process.env.BACKEND_URL = ... } preceding checkFrontendDeployEnv(process.env))

Sapling/frontend/next.config.ts

Lines 13 to 20 in ed0839e

	// legacy build that sets BACKEND_URL directly).
	constRESOLVED=resolveFrontendEnv(process.env);
	if(RESOLVED.derived){
	process.env.BACKEND_URL=RESOLVED.apiUrl;
	process.env.NEXT_PUBLIC_API_URL=RESOLVED.apiUrl;
	if(RESOLVED.cookieDomain)process.env.COOKIE_DOMAIN=RESOLVED.cookieDomain;
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

The ordering issue from the review above is fixed in the latest push: checkFrontendDeployEnv now runs against the operator-provided env BEFORE the DEPLOY_ENV derivation mutates it, restoring the fail-loud explicit-lock layer; the post-derive duplicate check was removed and wrangler.toml's ADR pointer updated to 0022.

[Darkest-Teddy]

Why

Login on staging.saplinglearn.com bounces to /?error=session_expired. This is the footgun documented in ADR 0020 — the frontend's environment config (backend origin + session-cookie Domain) can drift from the environment the worker is actually serving, so staging ends up validating a session cookie signed with the wrong SESSION_SECRET and treats every visitor as logged out.

The fix was written on fix/staging-deploy-env but never landed on main (that branch also carries unrelated RAG changes). This PR cherry-picks only the frontend/deploy hardening + the ADR — nothing else.

What

Make DEPLOY_ENV the single knob that drives every environment-specific value, with the explicit vars kept as backward-compatible fallbacks (deployGuard.resolveFrontendEnv):

• middleware.ts — derives API_URL via resolveFrontendEnv, and on a protected route calls detectHostConfigMismatch(host, apiUrl). A worker serving one env's host while wired to another's backend now logs a loud server error and redirects with a distinct env_misconfig code instead of the misleading session_expired.
• app/api/auth/session/route.ts — derives the cookie Domain from resolveFrontendEnv, so a staging build can't mint a .saplinglearn.com cookie that leaks into prod.
• next.config.ts — derives the build-time BACKEND_URL (the /api rewrite) and inlined NEXT_PUBLIC_API_URL/COOKIE_DOMAIN from DEPLOY_ENV.
• wrangler.toml — DEPLOY_ENV = "production" in [vars], DEPLOY_ENV = "staging" in [env.staging.vars]; documents the Build-command vs Deploy-command distinction.
• SignInModal.tsx — user-facing copy for env_misconfig.
• ADR 0020 — records the root cause and the operational follow-up.

⚠️ Operational follow-up (code alone does NOT fix staging)

Per ADR 0020, the running staging worker still needs a real redeploy:

1. Set DEPLOY_ENV=staging as a build variable on the frontend-staging Workers Build (build command stays npm run cf:build — never a deploy line).
2. Ensure the new version is actually activated (the deploy step is wrangler versions upload, which uploads but doesn't promote — promote it, or switch the deploy command to wrangler deploy --env staging).
3. Verify: curl -sSI https://staging.saplinglearn.com/dashboard → Location: https://api.staging.saplinglearn.com/api/auth/google.

Testing

• deployGuard.test.ts extended (132 lines) — runs under npm test on CI (Node 22).
• tsc --noEmit ✅ and eslint ✅ on changed files.
• Verified the core runtime logic locally (vitest can't start on Node 20.12 — repo pins Node 22) by executing the compiled module: resolveFrontendEnv derivation for staging/production/unset, and detectHostConfigMismatch flagging staging-host→prod-backend while leaving previews/localhost alone. All assertions passed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved environment detection to prevent staging and production configuration mismatches.
  • Sign-in now shows a clear configuration error instead of an expired-session message when deployment settings conflict.
  • Session cookies and API routing now use the correct environment-specific settings.

• Documentation

  • Added deployment guidance covering environment configuration, staging verification, and redeployment requirements.

• Tests

  • Expanded coverage for environment resolution, host detection, and configuration mismatch handling.

[AndresL230]

Code review

Found 1 issue:

1. The DEPLOY_ENV derivation in next.config.ts runs beforecheckFrontendDeployEnv, unconditionally overwriting BACKEND_URL/NEXT_PUBLIC_API_URL/COOKIE_DOMAIN with values derived from DEPLOY_ENV — so the explicit-var cross-check (deployGuard's "explicit lock" branch, unit-tested as catching "all-staging values on a prod deploy") can never fire once DEPLOY_ENV is set, which this PR's own wrangler.toml change guarantees. The documented fail-loud layer becomes a silent auto-correct: a wrong DEPLOY_ENV pasted into the other environment's build panel bakes the wrong backend URL and cookie domain into the build with no error, where pre-PR the explicit vars would have won. Reproduced: check-then-derive returns the mismatch error; derive-then-check returns []. Fix: run the cross-check against the original env before the derivation mutates it. (bug due to frontend/next.config.ts — const RESOLVED = resolveFrontendEnv(process.env); if (RESOLVED.derived) { process.env.BACKEND_URL = ... } preceding checkFrontendDeployEnv(process.env))

Sapling/frontend/next.config.ts

Lines 13 to 20 in ed0839e

	// legacy build that sets BACKEND_URL directly).
	constRESOLVED=resolveFrontendEnv(process.env);
	if(RESOLVED.derived){
	process.env.BACKEND_URL=RESOLVED.apiUrl;
	process.env.NEXT_PUBLIC_API_URL=RESOLVED.apiUrl;
	if(RESOLVED.cookieDomain)process.env.COOKIE_DOMAIN=RESOLVED.cookieDomain;
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

The ordering issue from the review above is fixed in the latest push: checkFrontendDeployEnv now runs against the operator-provided env BEFORE the DEPLOY_ENV derivation mutates it, restoring the fail-loud explicit-lock layer; the post-derive duplicate check was removed and wrangler.toml's ADR pointer updated to 0022.

[Darkest-Teddy]

Why

Login on staging.saplinglearn.com bounces to /?error=session_expired. This is the footgun documented in ADR 0020 — the frontend's environment config (backend origin + session-cookie Domain) can drift from the environment the worker is actually serving, so staging ends up validating a session cookie signed with the wrong SESSION_SECRET and treats every visitor as logged out.

The fix was written on fix/staging-deploy-env but never landed on main (that branch also carries unrelated RAG changes). This PR cherry-picks only the frontend/deploy hardening + the ADR — nothing else.

What

Make DEPLOY_ENV the single knob that drives every environment-specific value, with the explicit vars kept as backward-compatible fallbacks (deployGuard.resolveFrontendEnv):

• middleware.ts — derives API_URL via resolveFrontendEnv, and on a protected route calls detectHostConfigMismatch(host, apiUrl). A worker serving one env's host while wired to another's backend now logs a loud server error and redirects with a distinct env_misconfig code instead of the misleading session_expired.
• app/api/auth/session/route.ts — derives the cookie Domain from resolveFrontendEnv, so a staging build can't mint a .saplinglearn.com cookie that leaks into prod.
• next.config.ts — derives the build-time BACKEND_URL (the /api rewrite) and inlined NEXT_PUBLIC_API_URL/COOKIE_DOMAIN from DEPLOY_ENV.
• wrangler.toml — DEPLOY_ENV = "production" in [vars], DEPLOY_ENV = "staging" in [env.staging.vars]; documents the Build-command vs Deploy-command distinction.
• SignInModal.tsx — user-facing copy for env_misconfig.
• ADR 0020 — records the root cause and the operational follow-up.

⚠️ Operational follow-up (code alone does NOT fix staging)

Per ADR 0020, the running staging worker still needs a real redeploy:

1. Set DEPLOY_ENV=staging as a build variable on the frontend-staging Workers Build (build command stays npm run cf:build — never a deploy line).
2. Ensure the new version is actually activated (the deploy step is wrangler versions upload, which uploads but doesn't promote — promote it, or switch the deploy command to wrangler deploy --env staging).
3. Verify: curl -sSI https://staging.saplinglearn.com/dashboard → Location: https://api.staging.saplinglearn.com/api/auth/google.

Testing

• deployGuard.test.ts extended (132 lines) — runs under npm test on CI (Node 22).
• tsc --noEmit ✅ and eslint ✅ on changed files.
• Verified the core runtime logic locally (vitest can't start on Node 20.12 — repo pins Node 22) by executing the compiled module: resolveFrontendEnv derivation for staging/production/unset, and detectHostConfigMismatch flagging staging-host→prod-backend while leaving previews/localhost alone. All assertions passed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved environment detection to prevent staging and production configuration mismatches.
  • Sign-in now shows a clear configuration error instead of an expired-session message when deployment settings conflict.
  • Session cookies and API routing now use the correct environment-specific settings.

• Documentation

  • Added deployment guidance covering environment configuration, staging verification, and redeployment requirements.

• Tests

  • Expanded coverage for environment resolution, host detection, and configuration mismatch handling.

[AndresL230]

Code review

Found 1 issue:

1. The DEPLOY_ENV derivation in next.config.ts runs beforecheckFrontendDeployEnv, unconditionally overwriting BACKEND_URL/NEXT_PUBLIC_API_URL/COOKIE_DOMAIN with values derived from DEPLOY_ENV — so the explicit-var cross-check (deployGuard's "explicit lock" branch, unit-tested as catching "all-staging values on a prod deploy") can never fire once DEPLOY_ENV is set, which this PR's own wrangler.toml change guarantees. The documented fail-loud layer becomes a silent auto-correct: a wrong DEPLOY_ENV pasted into the other environment's build panel bakes the wrong backend URL and cookie domain into the build with no error, where pre-PR the explicit vars would have won. Reproduced: check-then-derive returns the mismatch error; derive-then-check returns []. Fix: run the cross-check against the original env before the derivation mutates it. (bug due to frontend/next.config.ts — const RESOLVED = resolveFrontendEnv(process.env); if (RESOLVED.derived) { process.env.BACKEND_URL = ... } preceding checkFrontendDeployEnv(process.env))

Sapling/frontend/next.config.ts

Lines 13 to 20 in ed0839e

	// legacy build that sets BACKEND_URL directly).
	constRESOLVED=resolveFrontendEnv(process.env);
	if(RESOLVED.derived){
	process.env.BACKEND_URL=RESOLVED.apiUrl;
	process.env.NEXT_PUBLIC_API_URL=RESOLVED.apiUrl;
	if(RESOLVED.cookieDomain)process.env.COOKIE_DOMAIN=RESOLVED.cookieDomain;
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[AndresL230]

The ordering issue from the review above is fixed in the latest push: checkFrontendDeployEnv now runs against the operator-provided env BEFORE the DEPLOY_ENV derivation mutates it, restoring the fail-loud explicit-lock layer; the post-derive duplicate check was removed and wrangler.toml's ADR pointer updated to 0022.