control-plane

The control plane is the single place session logic lives. It boots in src/index.ts, registers routes in server.ts, and delegates the lifecycle to orchestrator.ts; backends live under src/backends/.

Every session route is authenticated and scope-guarded. Full detail on the REST API page.

The Orchestrator owns the session lifecycle end to end. Every accessor funnels through an org-scoped ownedBy() check — the single tenancy enforcement point.

createSession(req: CreateSessionRequest, principal: Principal): Promise<Session>

getSession(id, principal) · listSessions(principal)

getAudit(id, principal) · teardown(id, principal)

publicView(session): Session  // = structuredClone(session)

The whole control plane is backend-pluggable behind one interface. The orchestrator builds a LaunchSpec and reports progress via a BackendEventSink — both backend-agnostic.

interface SessionBackend {
  readonly name: string;
  // Launch the session; returns once accepted, runs async via the sink.
  launch(spec: LaunchSpec, sink: BackendEventSink): Promise<void>;
  // Reclaim all resources for a session. Idempotent.
  teardown(sessionId: string): Promise<void>;
  // Optional readiness probe.
  health?(): Promise<{ ok: boolean; detail?: string }>;
}

interface LaunchSpec {
  sessionId: string;
  code: string;
  language: "python" | "node";
  limits: Required<SessionLimits>;
  egress: EgressPolicy;
  serviceBindings?: string[];   // injected at the egress proxy, not in the sandbox
}

interface BackendEventSink {
  phase(phase: SessionPhase, info?: { killReason?: KillReason }): void;
  stdout(chunk: string): void;
  stderr(chunk: string): void;
  egress(host: string, allowed: boolean): void;
  result(result: SessionResult): void;
}

For a private-repo git source, the broker mints a short-lived scoped git token. It is mounted only on the clone init-container, withheld from the workload pod, and never returned to the caller. No token is ever placed on the public Session.

issueGitToken(sessionId, scopes, ttlSeconds?): { token: string }

An auth hook verifies a user JWT (HS256, ENCLAVE_JWT_SECRET) or an API key (introspected against console-api) and sets req.principal. Each route then calls authorize(req, reply, scope) before doing work, and the orchestrator filters by orgId. A dev bypass exists only when ENCLAVE_AUTH_DISABLED=1, is never the default, and is loudly logged.