platform-gateway/README.md

platform-gateway

Bun + Hono service for mobility platform access control.

This service is intentionally separate from LMS APIs. LMS decides education-domain eligibility, while this gateway owns platform access grants, session ownership, agent command proxying, connection status, monitoring events, release, and emergency-stop workflows.

Run

bun install
bun run dev

Default URL: http://localhost:4500

Core APIs

• GET /health
• GET /api/platforms
• GET /api/platforms/:id/status
• GET /api/connections
• POST /api/platform-access-grants
• DELETE /api/platform-access-grants/:grantId
• POST /api/platform-sessions
• POST /api/platforms/:id/commands
• POST /api/platforms/:id/release
• POST /api/platforms/:id/emergency-stop
• GET /api/events

Network Model

Students and instructors never connect directly to Headscale/Tailscale device endpoints. Clients call this gateway only. The gateway verifies auth, checks platform grants/session ownership, records audit context, and proxies allowed operations to the mobility agent running on each platform node.

Kubernetes Tailscale Sidecar

The Kubernetes deployment runs a Tailscale sidecar in the same network namespace as the gateway. Create the one-time Headscale key secret before the first deployment:

kubectl -n studio-system create secret generic platform-gateway-tailscale-auth \
  --from-literal=authkey='tskey-auth-...'

The sidecar persists its machine state in platform-gateway-tailscale-state, so subsequent Gateway pod restarts do not consume another pre-auth key.