Concept

Data contracts

@enclave/shared is the single source of truth for the wire format — pure TypeScript types, no runtime. The control plane, SDK, MCP server, console, and demo all import them, so the pieces can't drift.

CreateSessionRequest#

The request to create and run a session. Only code is required.

Field	Type	Description
code	string	The untrusted source-code blob the sandbox will execute.
language?	"python" \| "node"	Runtime of the blob. Defaults to python.
limits?	SessionLimits	Per-session CPU / memory / wall-clock / pids quotas. Control plane fills defaults.
egress?	EgressPolicy	Egress policy. Defaults to deny_all.
serviceBindings?	string[]	Ids of service bindings to grant — secrets injected at the egress proxy, never in the sandbox.
webhookUrl?	string	URL to receive the result event on completion.
labels?	Record<string,string>	Free-form operator labels (shown in the console).

Session#

The public view of a session. No brokered secret is ever present — the type has no token field at all.

Field	Type	Description
id	string	Session id.
orgId	string	Owning org — the tenancy boundary. Every session belongs to exactly one org.
createdBy	string	User id (JWT sub) or API-key id of the principal that created it.
phase	SessionPhase	pending \| running \| succeeded \| failed \| killed \| torn_down.
language	"python" \| "node"	Runtime that ran the workload.
limits	Required<SessionLimits>	The effective quotas after defaults.
egress	EgressPolicy	The effective egress policy.
killReason?	KillReason	Set when phase === killed.
result?	SessionResult	Present once terminal.
backend	string	"simulator" \| "kubernetes" \| "docker".
labels	Record<string,string>	Free-form operator labels carried through from the request.
createdAt / startedAt / finishedAt	string (ISO)	Lifecycle timestamps.

Invariant 1

The Session type has no token field, and publicView() is structuredClone(session) — so it structurally cannot leak a brokered secret. Tests assert no eyJ… JWT appears in any response.

SessionResult#

Field	Type	Description
exitCode	number \| null	Process exit code, or null if killed before exit.
stdout	string	Captured standard output.
stderr	string	Captured standard error.
json?	unknown	Parsed JSON the workload wrote via `enclave.result()`.
durationMs	number	Wall-clock duration in milliseconds.

EgressPolicy & SessionLimits#

Field	Type	Description
egress.mode	"deny_all" \| "allowlist"	deny_all is the secure default — empty NetworkPolicy egress, also blocking the metadata IP.
egress.allow?	string[]	When allowlist, the permitted CIDRs. Empty == deny_all.
limits.cpuMillis?	number	CPU limit in millicores (default 500).
limits.memoryMiB?	number	Memory limit in MiB (default 256).
limits.wallClockSeconds?	number	Job activeDeadlineSeconds (default 30).
limits.pidsLimit?	number	Max process count — fork-bomb guard (default 128).

AuditEvent#

Recorded immutably per session. The type is one of: session_created, sandbox_started, egress_allowed, egress_denied, quota_killed, workload_exited, result_collected, webhook_delivered, webhook_failed, session_torn_down.

Field	Type	Description
ts	string (ISO)	When the event occurred.
sessionId	string	The session it belongs to.
type	AuditEventType	The event category (see above).
message	string	Human-readable summary.
data?	Record<string,unknown>	Structured context (host, exitCode, reason). Never contains secrets.

StreamFrame#

The SSE frame type — a discriminated union on kind, emitted on GET /sessions/:id/stream.

shared/src/index.tsts

type StreamFrame =
  | { kind: "phase";  phase: SessionPhase; ts: string }
  | { kind: "stdout"; chunk: string; ts: string }
  | { kind: "stderr"; chunk: string; ts: string }
  | { kind: "audit";  event: AuditEvent }
  | { kind: "result"; result: SessionResult; ts: string }
  | { kind: "end";    phase: SessionPhase; ts: string };

Auth contract#

The identity types shared by console-api (which mints) and the control plane (which verifies). Helpers signUserJwt, verifyUserJwt, and parseApiKey live alongside them.

Field	Type	Description
Role	"owner" \| "admin" \| "developer" \| "viewer"	Membership role within an org.
Scope	"sessions:read" \| "sessions:write" \| "audit:read"	Capability strings carried by a principal.
Principal.userId	string	Stable subject id — the JWT sub, or the API-key id.
Principal.orgId	string	The org the request is scoped to.
Principal.role	Role	The principal's role within orgId.
Principal.kind	"user" \| "apiKey"	How the principal authenticated.
Principal.email?	string	Email, when known (user JWTs carry it).
Principal.scopes	Scope[]	Resolved capabilities.