The browser product has two honest modes:
| Mode | Launch | Identity/persistence | Official state |
|---|---|---|---|
| Curriculum preview | Static build or maintainer preview server | None | Never shown |
| Local passport | gh passport open inside the learner's public fork |
Gitignored local navigation | Fresh controller state validated by the launcher |
Every page has a mode strip. Static output says Curriculum preview and links
to first contact; it must never use "resume" or imply that a sample mission is
assigned. A validated local endpoint changes the strip to Your local
passport, names the learner and exact assessment branch, and changes the
primary action to the local dashboard. The dashboard also retains its detailed
Preview: no learner identity, persistence, or official progress banner. A
404 local endpoint selects preview mode, not a simulated learner. A non-404
endpoint or validated-context error fails closed as a local passport error.
Build#
PNPM=pnpm python3 scripts/build_web.py --source-ref "$(git rev-parse HEAD)"
The compiler validates Markdown, routes, active HTML, URLs, duplicate routes, source links and deterministic content. Astro then type-checks and builds the current student/maintainer pages. The build validator checks links, anchors, source-map absence, forbidden output patterns, and JavaScript budget.
For a launcher release, use scripts/package_passport_cli.py; it replaces the
committed development fallback under tools/passport-cli/internal/webdist/
with the exact compiled web/dist tree before cross-compilation.
Local Bridge Rules#
- Bind only to
127.0.0.1on a random port. - Start through an unguessable one-time URL that sets an HttpOnly SameSite
cookie, then redirect to
/passport/. - Reject wrong Host, wrong Origin on mutations, missing session, oversized or unknown JSON fields, unsupported methods, and paths outside embedded assets.
- Serve no repository-controlled JavaScript and expose no arbitrary file, shell, Git, URL-fetch, or HTTP-proxy endpoint.
- Write only strict bounded files under a real, non-symlinked
.passport-local/directory that Git confirms is ignored. - Never expose a GitHub token, full local path, evidence text, command output, or cache file in browser responses.
- Treat disk cache as learner-editable. Only a status validated during the current process may use official colors/labels.
gh passport doctor is read-only. Its explicit --bundle option writes only a
redacted report under the gitignored local-state directory. gh passport open never installs software,
commits, pushes, submits Euler jobs, runs learner commands, or changes SSH
configuration.
Browser Qualification#
Run:
cd web
pnpm test:browser
The suite covers Chromium, Firefox, and WebKit for the front door, dependency route, a scrolled desktop-route overlap regression, no-JavaScript mission fallback, result-specific symptom search, honest preview/local mode labels, local non-authoritative state, mobile menu, accessibility and 404. Chromium additionally checks every generated page at 320, 390, 768, and 1024 CSS pixels for one H1, unique IDs, and zero document overflow.
Go tests cover state permissions/corruption, symlink escape, remote identity,
wrong App, wrong SHA, session/origin/Host enforcement, static traversal, and
forged-cache downgrade. Run go test -race ./... in tools/passport-cli/.
Print and manual desktop/mobile inspection remain release checks. Automated browser tests cannot prove comprehension, aesthetic appeal across a future population, or identical behavior of every OS security prompt.