rfc-app/docs/design/2026-06-07-deployed-env-e2e-harness.md

# Deployed-environment E2E harness (PPE)

**Date:** 2026-06-07 · **Version:** v0.52.0 · **Status:** implemented

## Why

The §9 deployment pipeline is `localhost + E2E → PPE + E2E → prod`. The
middle stage — running the Playwright E2E suite against a *deployed*
pre-prod host (`https://rfc-ppe.wiggleverse.org`) — was unreachable
because the suite (`e2e/metadata.spec.js`, SLICE-3/4/5 of the
configurable-collection-metadata work) was bound to three scaffolds that
exist only in the local Tier-1 docker stack:

1. **A faceted `bdd` collection**, seeded into a throwaway Gitea by
   `testing/seed-gitea.sh`.
2. **A granted-owner identity** (`e2e-owner@example.test`), injected
   directly into SQLite by the docker-compose `backend-seed` step.
3. **Mailpit**, the SMTP sink the OTC sign-in reads the one-time code
   from.

PPE has none of these: it runs against the real `git.wiggleverse.org`
(shared with prod), has no direct DB access, and has no mail sink. This
note records how each coupling is replaced so the *same* spec runs green
against both localhost and PPE.

## The three seams

### 1. Auth — a gated test-login endpoint (the framework change)

A new backend route, `POST /auth/test/login`, replaces both the Mailpit
OTC dance *and* the SQLite owner injection with one gesture: it mints an
authenticated **owner** session for a single pre-configured identity.

It is the framework's only auth bypass, so it is **fail-closed** and must
never function in production:

- **Off by default.** It returns `404` unless **both**
  `E2E_TEST_AUTH_SECRET` and `E2E_TEST_AUTH_EMAIL` are set. A production
  deployment sets neither, so the route is invisible and inert.
- **Secret-gated.** The caller must present `E2E_TEST_AUTH_SECRET` in the
  `X-Test-Auth-Secret` header, compared in constant time. A wrong/absent
  secret returns `404` (it does not advertise the route's existence).
- **Single identity.** It will only mint the one configured
  `E2E_TEST_AUTH_EMAIL` (case-insensitive); any other address is `403`.
  So an enabled PPE exposes exactly one throwaway owner, with the secret
  as the trust boundary.
- **Loud at startup.** When enabled, the app logs a `WARNING` at boot, so
  an accidental prod enablement is visible rather than silent.

On success it provision-or-links the row (reusing `otc.provision_or_link_user`),
forces it to `role='owner', permission_state='granted'` (the deployed
equivalent of the Tier-1 owner-seed), and stores the session exactly like
the OTC verify path.

**Why an endpoint rather than alternatives.** Reading the OTC code from
the VM's journald (the email adapter logs the envelope to stdout when
SMTP is unconfigured) would couple the test harness to `gcloud` SSH at
runtime — slow, brittle, and operator-cred-bound. Running Mailpit on the
VM and exposing its API publicly is more infra and its own exposure
surface. A default-off, secret-gated endpoint is the portable engineering
seam: it works for *any* deployed environment, needs no SSH, and the
secrets rule (§6.3) is honored — the secret is a Secret Manager ref
injected as VM env, never a literal.

The hard-secrets caveat: the E2E runner presents the secret by resolving
it from Secret Manager at runtime (command substitution), never echoing
it.

### 2. Content — a dedicated PPE registry + content repo

PPE shares the prod Gitea org (`wiggleverse`) and, until now, prod's
registry (`rfc-registry`) and default project (`ohm`). Seeding a faceted
test collection into that shared registry would surface it on **prod**.

So PPE gets its **own**, prod-untouching fixtures:

- `wiggleverse/rfc-registry-ppe` — PPE's project registry. Prod keeps
  `rfc-registry`, so prod is never affected.
- `wiggleverse/rfc-app-ppe-content` — one project `ohm` (document) with a
  default collection entry plus a faceted `bdd` named collection
  (`priority` enum + `tags`) and three entries, mirroring the Tier-1
  seed. The E2E path `/p/ohm/c/bdd` therefore resolves identically on
  both environments.

PPE is pointed at it with `overlay set rfc-app-ppe
REGISTRY_REPO=rfc-registry-ppe`. The startup reconciler sweep loads the
content into `cached_rfcs` (incl. `meta_json` for facets) on the next
deploy — no webhook needed for the initial load. The seed is scripted in
`testing/seed-ppe.sh` (idempotent; `RESEED=1` restores entry values for a
re-run). Repo *creation* is a one-time operator gesture (the
`write:repository` Keychain token cannot create org repos; create the two
empty repos in the Gitea UI or re-scope the PAT).

### 3. Parameterization — one spec, two environments

- `e2e/playwright.config.js` already honors `BASE_URL`
  (default `http://localhost:8080`); PPE sets
  `BASE_URL=https://rfc-ppe.wiggleverse.org`.
- `e2e/lib/auth.js` branches on `E2E_TEST_AUTH_SECRET`: set → use
  `/auth/test/login`; unset → the original Mailpit OTC path. `OWNER_EMAIL`
  reads `E2E_OWNER_EMAIL` (PPE points it at `E2E_TEST_AUTH_EMAIL`) or the
  Tier-1 default. The spec itself is unchanged, so the localhost Tier-1
  path keeps working.

## PPE version

The harness *requires* the test-login endpoint to exist in the deployed
build, so PPE must run a framework version that contains it — **v0.52.0**,
not v0.51.1. PPE is pinned ahead of prod via its own
`ben/ohm-rfc/.rfc-app-version.ppe` (prod stays on `.rfc-app-version`),
realizing the "PPE stages newer versions first" note the
`deployment.ppe.toml` always anticipated.

## Known limitations

- **Re-runnability.** SLICE-4/5 mutate the seeded entries (commit
  sidecars). A clean run needs seed-state preconditions; re-run after
  `RESEED=1` + a cache refresh (next reconciler sweep or a redeploy).
  Unlike Tier-1's `make e2e-fresh`, PPE has no per-run teardown.
- **smoke.spec.js** stays Tier-1-only (anonymous OTC smoke through
  Mailpit); only `metadata.spec.js` runs against PPE.