rootnode-academy/docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md

RootNode Academy — Phase 2A: Gateway & Student Flow

Status: IMPLEMENTED and end-to-end tested, 2026-08-18. Builds on docs/LAB_ARCHITECTURE.md and docs/PHASE1_PLATFORM_FOUNDATION.md (Phase 1 milestone a15897c78f7012c59ea3629a74dd8b1425f6f7f2). This doc covers the three Phase 2A workstreams: fixing the real Lab image, the Gateway, and the student frontend flow.

---

1. node-pty root cause and fix

Symptom: the real Lab image's backend crashed at startup with Error: Failed to load native module: pty.node, checked: build/Release, build/Debug, prebuilds/linux-x64: Cannot find module './prebuilds/linux-x64//pty.node'.

What it looked like vs. what it was: node-pty's own error handling collapses whatever actually went wrong at each candidate path into one generic "module not found" message using only the last path it tried — this made a link-time failure look like a missing-file problem.

Root cause, confirmed empirically (not guessed):

1. node-gyp generates an incorrect config.gypi. For this NodeSource-packaged Node 20 build, node-gyp's downloaded headers/config reference reports node_shared: true (a shared libnode.so build), but the actual installed Node is statically linked — there is no libnode.so.<abi> anywhere on the system (confirmed: find / -iname 'libnode*' → nothing; process.config.variables.node_shared on the real running Node → false). Node-gyp trusted the wrong config and linked node-pty's native addon against -lnode, producing a binary that fails at require() time with libnode.so.127: cannot open shared object file — confirmed by loading the compiled .node file directly, bypassing node-pty's own path-search/error-masking logic.
2. A second, independent bug compounded it: the repo had no .dockerignore. A host-side npm install (run earlier in this project for unrelated backend testing) left a backend/node_modules/ on disk, built against the host's environment. The Dockerfile's COPY backend/ ./backend/ (placed after the npm-install RUN layer, for build-cache efficiency) then silently overwrote the correctly-built-in-container node_modules with that host copy — including after a first .dockerignore fix that used the pattern node_modules/, which (a real gotcha) only matches a node_modules directory at the build context root in Docker's matching rules, not backend/node_modules at any depth.

Fix (Dockerfile, .dockerignore):

ENV npm_config_node_shared=false        # image-level, not a one-off RUN prefix — applies no
                                          # matter when/how often a native module gets built
...
RUN cd backend && npm install --production \
    && node -e "require('./node_modules/node-pty'); console.log('node-pty loads OK')"

The node -e require(...) line makes this a hard build failure if it ever regresses again, instead of a silent runtime failure discovered later — not a workaround for the terminal, a real build-time verification of a real native dependency.

# .dockerignore
**/node_modules/     # NOT `node_modules/` — that only matches the context root
frontend/dist/
.git/
*.db
*.db-journal

Nothing else changed. No terminal architecture change, no fake shell, no rewrite of backend/server.js's PTY handling. RootNode branding and upstream KubeKosh attribution untouched. The single-container dev workflow (docker build -t rootnode-academy:test .) is the same command as before — it now just works.

Verified against the real image, not a stand-in (see §8 for full results): image builds → container starts → k3s reaches Ready → backend starts (API server running on :4000, no crash) → nginx starts → browser UI returns 200 → terminal WebSocket opens and shows the RootNode banner → kubectl get nodes run through the terminal returns real cluster state → deploy-nginx scenario solved via the terminal and validated via POST /api/scenarios/deploy-nginx/validate → all 5 checks pass.

---

2. Gateway architecture

New component: platform/gateway/. The only student-facing path to disposable Lab environments — browsers never talk to a Lab container, the Provisioner, or Postgres directly.

Browser
  │  (one stable origin — the Gateway)
  ▼
Gateway
  ├── /api/environment/*   → calls the Provisioner internally (shared secret never
  │                           leaves the Gateway process)
  ├── /lab/<token>/*        → HTTP + WS proxy into that specific student's Lab
  │                           container, resolved by opaque token via the Provisioner
  └── everything else       → proxied to the persistent "identity" backend (roster,
                               login, curriculum, progress, and the platform-shell
                               frontend) — OR to the student's own Lab, if a valid
                               lab-session cookie is present (see §5 for why)

Why a persistent "identity" instance exists, and what it is: the roster/curriculum/ progress SQLite data (built in the pre-Phase-2A slice) needs to be reachable before a student has a Lab — they pick their name and see their curriculum before ever clicking Launch Lab. That data can't live inside an ephemeral, disposable-by-design Lab container. Phase 2A runs it as one plain, non-ephemeral instance of the existing, unmodified Lab image (identity in platform/docker-compose.dev.yml) — same image, same code, just never destroyed/reset by the Provisioner, the same way Postgres or the egress proxy are infrastructure rather than per-student resources. This is a deliberate zero-new-code choice (see §9 known limitations for its cost).

Provisioner addition: GET /environments/by-token/:token (small, internal-only, same shared-secret auth as every other Provisioner route) — resolves a routing token to its environment for the Gateway. This is the only change to platform/provisioner/.

What the Gateway never does: expose a Lab container's port publicly, expose the Docker API, expose the Provisioner's shared secret to a browser, or trust a client-supplied environment ID for anything without checking it against the Provisioner's own record.

---

3. Student flow

A. Entry screen (frontend/src/platform/EntryScreen.jsx) — cohort dropdown → name dropdown (existing GET /api/roster/cohorts / GET /api/roster?cohort=) → POST /api/login. No password. A visible note states this is pilot identity, not production auth.

B. Session — student_id stored in localStorage only (frontend/src/platform/api.js), sent as X-Student-Id on every subsequent platform request. Every authenticated call throws if no student is stored, rather than silently going out anonymously — this is what "prevent accidental anonymous progress writes" means in practice.

C. Dashboard / "Up Next" (StudentDashboard.jsx) — renders GET /api/curriculum/path as-is: the existing RootNode path (Foundation → Workloads → Networking → Configuration → Troubleshooting → Real Ops → Capstone), no new structure invented. Capstone stays the locked placeholder from the earlier slice.

D. Launch Lab — POST /api/environment/launch (Gateway): reuses a non-terminal environment if one exists, otherwise provisions one via the Provisioner. UI states map directly to environment status: none → provisioning/resetting (polled every 2.5s while in flight) → running → error, each rendered distinctly (EnvironmentPanel in StudentDashboard.jsx). On running, the browser navigates to launch_path (/lab/<token>/), with the student_id attached as a ?sid= query param for the Gateway's ownership check (see §5).

E. Lab session — the existing, completely unmodified Lab UI (App.jsx and everything under frontend/src/components/). It has no student-identity awareness and needs none — identity and progress stay entirely in the Platform layer, per the explicit requirement not to inject student identity into the privileged Lab container.

F. Reset/Recreate — one button, "Recreate Lab," calling POST /api/environment/reset (destroy + provision against the same environment row, per the Phase 1 lifecycle — same environment_id, fresh container). No raw destroy-without-recreate control is exposed to students; that keeps the surface to exactly what's safe, per the explicit requirement.

---

4. API routes added

All on the Gateway (platform/gateway/src/server.js), all internal glue — the Provisioner's own API remains unreachable from the browser:

Method & path	Auth	Purpose
GET /api/environment/status	X-Student-Id	Current environment state for this student, or {status:'none'}
POST /api/environment/launch	X-Student-Id	Reuse or provision; blocks until running/error (matches the Provisioner's own synchronous provisioning)
POST /api/environment/reset	X-Student-Id	Destroy + recreate, same environment identity
GET/POST/* /lab/:token/*	opaque token (+ optional ?sid=)	Proxy into that student's Lab

Plus one Provisioner addition: GET /environments/by-token/:token (internal-only).

Responses to the browser never include internal_ip, container_id, network_id, lab_host_id, environment_id, or the raw routing token beyond its one legitimate use as a navigation path segment (launch_path) — see §6.

---

5. Routing design — HTTP/WebSocket, and why there's a cookie

The problem this solves: the existing Lab UI makes root-relative calls (fetch('/api/scenarios'), new WebSocket(${proto}//${location.host}/shell-ws)) — it has no idea it might be served under a /lab/<token>/ prefix, and it shouldn't have to (preserving the existing architecture unmodified was an explicit requirement). Naively prefix-stripping only the first request would leave every subsequent asset/API/WS call unrouted.

Solution: the Gateway sets an HttpOnly, SameSite=Lax, Path=/ cookie (rn_lab, 8h max-age) on the first /lab/<token>/ response. Every later request from that browser — regardless of path — carries it automatically. Routing priority:

1. /lab/<token>/* (explicit) → resolve token, strip prefix, proxy, (re)set the cookie.
2. /api/environment/* → always the Gateway's own routes, never affected by the cookie — this is what keeps "student is inside their lab" from accidentally hijacking the dashboard's own environment-status calls.
3. Anything else, unprefixed → if the rn_lab cookie is present and resolves to a running environment, proxy there (unprefixed) — this is what makes the existing, unmodified Lab UI's own /api/scenarios, /shell-ws, static assets, etc. resolve correctly once a browser has navigated into a lab session, with zero changes to that UI's code. Otherwise, proxy to the identity backend (this is what serves /, the platform-shell bundle, /api/roster, /api/curriculum/path, etc.).

WebSocket upgrades follow the identical priority (server.on('upgrade', ...) in gateway/src/server.js), so the terminal's /shell-ws connection is routed the same way as any other request.

Stable URL, even across recreate: the student-facing URL is always /lab/<routing_token>/ — the token lives on the environments row and does not change across reset (same row, new container/network/IP). A bookmarked or previously-loaded lab URL keeps working after a recreate without the student needing a new link.

---

6. Security — environment ownership, and what Phase 2A does not claim

• Token as bearer capability for the proxy path. A /lab/<token>/ request is authorized by possession of the token itself (CSPRNG, 32 bytes, never guessable) — the same trust model as a signed download link. This is a deliberate, stated design choice, not an oversight.
• ?sid= as an additional check where it's available. A full top-level browser navigation cannot carry a custom header, so the Dashboard's "Launch/Continue Lab" link appends ?sid=<student_id> to the URL. If present, the Gateway compares it against the environment's actual owning student_id (from the Provisioner) and rejects (403) on mismatch. This is strictly additive security on top of token-alone — its absence (e.g., a bookmarked link without the param) falls back to token-only trust, not a hole opened by omitting it.
• /api/environment/* ownership is checked against the Provisioner's own record, not assumed from the header — listForStudent/reset always re-verify env.student_id.
• Explicitly not production auth. Per the governing requirement: routing-token-alone, student-supplied-environment-ID-alone, and X-Student-Id-alone are each individually insufficient and documented as such — Phase 2A's actual security property is the combination, appropriate for a supervised pilot, not a claim of production-grade identity. Production SSO/OIDC is explicitly future work (§9).
• Nothing sensitive reaches the browser: no internal Docker IPs, no Docker/Provisioner endpoints, no shared secret, no Postgres credentials — verified by inspecting every Gateway response shape in server.js's publicEnvView().

---

7. Reset/recreate and reaper recovery semantics

• Recreate Lab (student-initiated) = the Provisioner's existing reset: destroy + recreate against the same environments row. Same environment_id/routing token, same /lab/<token>/ URL, fresh container/network/IP. Academic progress is untouched because it never lived in the Lab container to begin with (Phase 1 property, unchanged).
• Reaper-caused expiry (idle timeout, no student action): the environment transitions to destroyed. GET /api/environment/status correctly reports none/destroyed afterward — the Dashboard's "Launch Lab" button provisions a new environment (new environment_id, new token, new URL) rather than trying to resurrect the old row, matching the Provisioner's actual lifecycle model. Progress survives because, again, it was never in the Lab.
• Unexpected Lab death (crash, not reaped): the Gateway's isReachable() check (status==='running' && internal_ip present) fails closed — a dead container never gets silently proxied to. The student sees the error state with a "Try Again" action.

---

8. Testing — results

(Filled in after the full end-to-end run against platform/docker-compose.dev.yml; see the Phase 2A final report for the authoritative results table. Summary below.)

• Lab image: node-pty load, k3s Ready, terminal, kubectl, scenario validation — all pass, §1 above.
• Gateway HTTP/WS proxying, two-student isolation, cross-student rejection, stable URL across recreate, reaper recovery, existing single-container dev mode, scenario files untouched, frontend/backend builds, Provisioner test suite — see final report for the full table and exact commands run.

---

9. Known limitations / Phase 2B

BUILT NOW:

• Real Lab image boots reliably (node-pty fixed at the actual root cause).
• Gateway: HTTP + WS proxying, environment-aware routing, ownership checks, no public Lab ports, no exposed Docker/Provisioner internals.
• Student entry (roster pick-name) → dashboard (curriculum + environment status) → Launch Lab → Lab session → Reset/Recreate, all wired through the Gateway as the single origin.
• Reaper-recovery and reset semantics correctly reflected in the student-facing states.

FUTURE (explicit Phase 2A non-goals, unchanged):

• Instructor dashboard, production SSO/OIDC, public signup, billing, parent portal, email notifications, multi-host scheduling, full SQLite→Postgres migration, production observability, capstone engine, production Proxmox deployment, certificates, self-paced public enrollment, the six held scenarios, namespace-only isolation.

Known limitations found during this phase, not previously documented:

• The identity instance boots a full, unused k3s cluster just to serve as the roster/ curriculum/progress backend — it's the existing image running exactly as designed, but it's real wasted resource. A Phase 2B optimization is a slimmed identity-only variant of the image (skip k3s entirely) — not done here, to keep this phase at zero changes to the Lab image's own runtime behavior beyond the node-pty fix.
• identity requires network_mode: bridge explicitly in docker-compose.dev.yml — under Compose's own auto-created bridge network, k3s failed with "no default routes found in /proc/net/route" at startup. Root cause not fully chased down (a Compose-network-vs-classic- bridge routing-table timing/detection difference); the explicit network_mode: bridge workaround is confirmed reliable and is what's shipped. Worth a deeper look before this matters for a real deployment (bridge mode isn't compatible with a per-student isolated network model anyway — the production identity service placement needs its own design pass).
• The Gateway's environment-lookup cache (5s TTL) is in-memory and per-process — fine for one Gateway instance (Phase 2A's actual topology), would need a shared cache (or none) if the Gateway is ever horizontally scaled.
• ?sid= ownership verification only covers the initial /lab/<token>/ navigation, not every subsequent proxied request (by design, per §6) — acceptable for the stated pilot threat model, revisit if this graduates past pilot use.