Admin: Configure protected pull-request previews and an isolated production release

[gekichumai-admin]

Phase / step: Phase 5 — Delivery / Step 5
Parent: #301
Depends on: #333, #336, #337, #340, #342, gekichumai/dxdata-assembly-line#46

Context and goal

The administrator SPA should be reviewable before merge and releasable independently of the public frontend and backend. Preview and production origins must remain behind the approved identity-aware access policy and must not expose private configuration through static assets.

Scope and implementation notes

• Add immutable production builds for apps/admin with environment validation, SPA fallback routing, appropriate cache rules for hashed assets versus the HTML shell, and a lightweight deployment-health check.
• Deploy eligible pull requests to isolated preview origins only after required build/test checks. Protect every preview with the approved identity-aware access policy and its MFA requirement; do not rely on an unguessable URL as access control.
• Give each admin preview a contract-compatible non-production backend: either an isolated backend/database deployment from the same pull request or a protected staging backend pinned to the preview's private-contract compatibility identifier. A preview must fail closed on a mismatch and must never send administrator traffic, mutations, sessions, or test data to production.
• Configure the production admin origin and the existing backend's exact /api/admin path behind the matching MFA-enforcing Access application/policy (or a documented same-origin proxy with the same guarantees). Ensure the edge forwards the assertion/audience B09 validates while ordinary public API paths and chart-report submission remain outside this policy. Keep release promotion/rollback independent from apps/web and the backend so an admin-only release does not redeploy unrelated services.
• Change the repository's release dispatcher and affected-path/change-set rules so an admin-only change does not create a public-web release tag or build/deploy apps/web, while a public-web-only change does not release apps/admin. Document and test how shared-package and backend changes select affected applications, including the coordinated path for a private-contract change.
• Separate preview and production backend origins, OAuth callback configuration, Sentry environments/releases, and public runtime configuration. Never place backend credentials, access-provider secrets, or storage credentials in VITE_* variables or generated assets.
• Ensure backend CORS, trusted-origin, cookie, and OAuth settings recognize only the intended admin origins through the corresponding backend configuration issue.
• Publish a preview link and expiration/status on the pull request without disclosing access-policy internals. Remove or expire previews according to the hosting platform's supported lifecycle.
• Add a documented release and rollback procedure based on previously built immutable assets. Include verification of sign-in, one read-only admin route, security headers, and error reporting before completing a production promotion.
• For an intentional breaking private-contract change, require the backend and @gekichumai/admin updates in the same pull request and document a release order with a compatible overlap or another rollback-safe transition. Exercise the compatibility handshake with a cached old shell/open tab so independent deployability does not create an avoidable broken-admin interval.
• Support the planned dark launch: initially admit only the allowlisted super-administrator cohort through the outer Cloudflare Access policy, while application RBAC remains authoritative after entry; then enable the administrator cohort after validation without rebuilding the SPA.

Acceptance criteria

• Eligible pull requests receive an isolated preview only after required checks pass.
• Every preview uses a matching isolated or contract-pinned staging backend, fails closed on incompatibility, and is mechanically prevented from targeting the production backend.
• Preview and production admin origins require the approved identity-aware access policy with MFA enforced before the SPA is served.
• Preview and production /api/admin traffic passes through the matching Access audience/assertion path expected by B09, while public API/report routes remain reachable under their existing policy.
• The SPA supports direct nested-route refresh and serves long-lived immutable hashed assets with a safely revalidated HTML shell.
• When the private contract is unchanged, admin production releases and rollbacks do not require redeploying the public frontend or backend.
• Release-dispatch tests prove admin-only changes do not tag/build/deploy apps/web, public-web-only changes do not release apps/admin, and shared/backend changes follow the documented affected-app rule.
• Preview/production configuration and telemetry environments are isolated, and generated assets contain no protected secrets.
• Only explicitly allowed admin origins are accepted by backend CORS/trusted-origin/cookie/OAuth configuration.
• A documented smoke check verifies sign-in, authorization, a read-only route, CSP/security headers, and Sentry release association.
• A previous immutable build can be restored through the documented rollback path.
• Breaking private-contract releases have a tested, rollback-safe backend/frontend sequence; a cached old client receives the safe incompatibility flow instead of malformed data.
• Dark launch can restrict the outer Access policy to the super-administrator cohort and later admit administrators without a frontend rebuild or using Access identity as application authorization.

Out of scope

• Deploying or changing the public web application.
• Coupling backend/database rollout to every admin frontend release.
• Publishing infrastructure identifiers, credentials, or access-policy membership in repository files.
• Phone-specific deployment or native applications.