google / google/capsem

Move OCI container control and port exposure behind one authenticated HTTP path; retire the CLI's direct VM-owner channel

Open
#207 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
72
Forks
13
Avg merge
1d 2h
Merged PRs (30d)
5

Description

## Problem

PR #200 gives the Rust CLI a working OCI path, but its final control step is not an authenticated gateway HTTP operation. The CLI pulls and uploads the image, then reads `ProvisionResponse.uds_path` and connects directly to the per-VM owner. `container_image::Channel` uses that private IPC channel for port publication and attached execution. A remote SDK, browser client, or `@capsem/mcp` cannot safely use that path.

## Outcome

One authenticated HTTP control path for OCI workloads and port exposure, with the Rust CLI migrated onto it and its container-specific direct connection to the VM owner retired:

- [ ] Stop returning `ProvisionResponse.uds_path` as a general client capability (if another internal owner needs it, make that ownership explicit).
- [ ] Remove `container_image::Channel::open()`.
- [ ] Stop sending `ServiceToProcess::PublishPort` directly from the CLI.
- [ ] Move attached container control behind an authenticated HTTP contract.
- [ ] No parallel CLI and HTTP OCI workflows remain.

## Prototype to review

An HTTP-first container, exposure, preview, security, and audit prototype exists on local branch `worktree/gateway-sdk-runtime-draft` (base `8fbad2a3a`, tip `9529f1711`). It predates #200's L2 switch refactor and is an implementation sketch: review it commit by commit; do not merge or cherry-pick the range. SDK-only commits are out of scope.

| Commit | Prototype behavior | Review concern |
|---|---|---|
| `454c38b52` | Typed container creation contract | Decide whether image pull belongs to the service before retaining this wire shape. |
| `e0d8df769` | Service-owned OCI pull, stage, and launch | Cancellation, transient credentials, restart ownership, registry confinement. |
| `1dfb4da96` | Container runtime status endpoint | Report actual runtime readiness, not successful staging. |
| `fa3122e06` | Setup cancellation and partial cleanup | Deletion and generation changes must prevent late completion. |
| `0d476c832` | Typed exposure lifecycle | Explicit targets; never fall back between VM and container namespaces. |
| `13e7a652e` | Explicit guest target routing | Review the IPC change against the VM-owner and guest-bridge boundaries. |
| `421891f0c` | Streaming HTTP and WebSocket previews | Gateway coordinates preview HTTP; the confined router carries workload bytes. |
| `7e6720c4a` | Exposure-scoped browser sessions | Separate origins, single-use bootstrap tokens, scoped HttpOnly cookies, credential stripping. |
| `94dc83654`, `90f72cfdf` | Existing policy engine on control and preview admission | No second evaluator, no route-local allow fallback. |
| `60b14130f`, `f4d02da5a` | Correlated control audit records | Logger stays the only DB owner; client trace data is correlation metadata, not identity. |
| `b4435c84f` | Fail-closed audit and redaction test sketch | Unit proof only; the real-fixture proof never completed. |

Accepted, modified, and rejected slices are each recorded before their files are edited.

## Boundaries to preserve

- Gateway authenticates explicit control and preview routes.
- Service coordinates lifecycle and resolves authorized targets without forwarding workload bytes.
- VM owner retains trusted identity, generation checks, and guest control.
- The confined router carries approved traffic under existing quotas; the guest bridge connects only to the declared VM or container target.
- The existing security engine is the only policy/plugin evaluator.
- The existing credential sanitizer handles secrets before persistence.
- The logger owns connections, buffering, flush barriers, queries, and retention.
- Workers receive scoped descriptors and configuration only: no admin token, registry credential, CA private key, unrestricted filesystem, or virtualization entitlement.

## Suggested order

1. Record every responsibility of #200's `container_image::Channel`.
2. Finalize the smallest authenticated HTTP contracts for container setup, status, and exposure, reusing #200's types and owners.
3. Move one orchestration owner behind HTTP and migrate the CLI to it in the same series; delete the duplicate direct UDS behavior.
4. Add preview sessions only after exposure authorization and teardown are proven.
5. Reuse existing policy, sanitizer, logger, cancellation, quota, generation, and teardown infrastructure.

## Required proof (TDD, real macOS VM acceptance through the repository gates)

- Verified image pull, environment, command override, runtime readiness, startup failure.
- Deletion during pull/staging; service and VM-owner restart cleanup; fork behavior.
- Loopback port allocation, target/destination isolation, revocation, quotas.
- Browser assets, forms, redirects, streaming, WebSocket upgrades, scoped authentication, cross-exposure denial.
- Policy denial reaching zero destination bytes.
- Audit-admission failure refusing control and forwarding.
- Transient credential handling; secret absence from logs and ledgers after the logger flush barrier.

The prototype is not VM, Linux, or KVM proof. macOS acceptance does not claim Linux/KVM proof.

## Out of scope

SDK generation and `@capsem/mcp` integration stay in PR #199, after this HTTP contract is final.

## Depends on

PR #200 landing on main; this work starts from main.

Contributor guide

Open the contributing guide

Research direction

Start with PR #200 and record the responsibilities of container_image::Channel, ProvisionResponse.uds_path, and ServiceToProcess::PublishPort. Review the listed prototype commits commit by commit without merging them, then run the repository's real macOS VM acceptance gates. Done means authenticated HTTP owns OCI control and exposure, the CLI uses it, and the direct VM-owner channel is retired with the required lifecycle, security, and audit proof.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api, backend, infrastructure, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.