ced4568
40692926ee
New docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md covers the schema, persistent session design, instructor accounts, the full RBAC matrix, cohort scoping (including the documented raw-environment-id simplification), student session hardening (explicitly still classroom/pilot identification, not production auth), CSRF, rate limiting, audit logging, the API inventory, a security hardening checklist, test results, known limitations, the future OIDC path, and production HTTPS/cookie expectations — with an explicit BUILT NOW vs. FUTURE split. Updates ENGINEERING_SOP.md (new §9/§10, closing a stale '(§9)' forward-reference that dated back to Phase 2B), LAB_ARCHITECTURE.md status line, README.md, platform/README.md, and platform/api/README.md (bootstrap-owner usage, new config vars, no more ADMIN_PASSWORD).
70 lines
4.2 KiB
Markdown
70 lines
4.2 KiB
Markdown
# RootNode Academy — Platform
|
|
|
|
The full multi-student platform, layered on top of the unmodified Lab image at the repo root.
|
|
Start here, then go to the component you need:
|
|
|
|
- `provisioner/` — Postgres-backed environment registry and lifecycle. Design:
|
|
`docs/LAB_ARCHITECTURE.md`, `docs/PHASE1_PLATFORM_FOUNDATION.md`. Operational reference:
|
|
`provisioner/README.md`.
|
|
- `api/` — the lightweight Platform API: students, cohorts, enrollments, curriculum, progress,
|
|
scenario attempts, per-instructor accounts, persistent student/instructor sessions, RBAC,
|
|
audit logging, and the instructor/admin control plane. No k3s, no `--privileged` — this
|
|
replaced Phase 2A's "identity" instance, which was a full Lab image booting an unused k3s
|
|
cluster just to serve these APIs. Design: `docs/PHASE2B_ADMIN_AND_PLATFORM_DATA.md` (split +
|
|
Postgres migration), `docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md` (sessions, accounts,
|
|
RBAC, audit). Operational reference: `api/README.md`.
|
|
- `gateway/` — the only student-facing path to a Lab (HTTP + WebSocket proxy, environment-aware
|
|
routing derived from a server-controlled session — not a client-suppliable header/param).
|
|
Design: `docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md` (routing), `docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md` (persistent sessions, CSRF).
|
|
- `egress-proxy/` — shared allowlisting proxy every Lab's outbound traffic passes through.
|
|
- `docker-compose.dev.yml` — the full stack (Postgres, egress proxy, Provisioner, Platform API,
|
|
Gateway) on one machine. This is the Phase 1/2A/2B **local dev exception** — production is
|
|
the two-VM Proxmox split described in `docs/LAB_ARCHITECTURE.md` §1.
|
|
|
|
## Running the full stack locally
|
|
|
|
```bash
|
|
cd platform
|
|
echo "PROVISIONER_SHARED_SECRET=$(openssl rand -hex 32)" > .env
|
|
docker compose -f docker-compose.dev.yml build
|
|
docker compose -f docker-compose.dev.yml up -d
|
|
|
|
# First run only — create the owner account (no ADMIN_PASSWORD anymore, see
|
|
# docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md):
|
|
cd api
|
|
PLATFORM_DB_URL=postgres://postgres:postgres@localhost:5433/rootnode_platform \
|
|
node bootstrap-owner.js [email protected] "Your Name" "a-real-password-12-chars-plus"
|
|
```
|
|
|
|
No k3s boot to wait for at this layer anymore (Platform API starts instantly) — the whole
|
|
platform is reachable at `http://localhost:4200` (the Gateway) right away: students at `/`,
|
|
instructors at `/admin` (sign in with the owner account you just bootstrapped, then create
|
|
further instructor accounts from the Instructors tab).
|
|
|
|
## Tests
|
|
|
|
- `provisioner/test/run.js` — fast, isolated Provisioner tests (network/container/firewall
|
|
mechanics, no Gateway/Platform API involved). Run against `provisioner/docker-compose.dev.yml`.
|
|
- `test/e2e-phase2a.js` — student-flow regression through real session cookies: roster → login
|
|
→ curriculum → launch → Gateway routing → cross-student rejection → progress relay → reset.
|
|
- `test/e2e-phase2b.js` — the classroom acceptance workflow: instructor creates a cohort, adds
|
|
students, assigns curriculum, Prepare Labs (concurrent), students complete different
|
|
scenarios, instructor resets one, instructor destroys all cohort Labs after class — progress
|
|
survives every step.
|
|
- `test/e2e-phase3a.js` — persistent sessions (including a real Platform API restart), instructor
|
|
auth (no enumeration, rate limiting), RBAC across owner/admin/instructor, cohort-scoped
|
|
instructor access, CSRF enforcement, password change, and audit logging.
|
|
|
|
All three e2e suites need `OWNER_EMAIL` / `OWNER_PASSWORD` set to a real bootstrapped instructor
|
|
account (see "Running the full stack locally" above) — the old `ADMIN_PASSWORD` mechanism is
|
|
gone. They're slow (real k3s boots) and need the full stack up. None of them substitute for the
|
|
manual real-Lab-image checks (node-pty, terminal WebSocket, `kubectl`, scenario validation) in
|
|
`docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md` §8 — those need a browser-equivalent client and
|
|
aren't automated here.
|
|
|
|
## Known limitations
|
|
|
|
See `provisioner/README.md` (Phase 1), `docs/PHASE2A_GATEWAY_AND_STUDENT_FLOW.md` §9 (Phase
|
|
2A), and `docs/PHASE3A_IDENTITY_AND_INSTRUCTOR_ACCESS.md` (Phase 3A, supersedes Phase 2B's
|
|
identity limitations) for the full, honest lists.
|