Skip to content

Commit 8bcff5c

Browse files
eshurakoveshurakov
committed
feat(cloud-agent-next): contain managed SCM credentials
1 parent 6b28b9d commit 8bcff5c

35 files changed

Lines changed: 5469 additions & 347 deletions

‎.plans/cloud-agent-commit-as-user.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Cloud Agent SCM credentials: catch-all outbound walking skeleton
2+
3+
## Goal
4+
5+
Deliver a reviewed managed-SCM containment walking skeleton for Cloud Agent sandboxes: use one catch-all outbound handler, preserve managed GitHub support with default-HTTPS LFS repository-control validation, add GitLab HTTPS support without host preregistration, and enable DIND only after proving nested routing and propagation of Cloudflare's private runtime HTTPS-interception CA/trusted bundle.
6+
7+
## Current State
8+
9+
- The walking skeleton is implemented, independently reviewed task by task, fixed where required, and locally validated.
10+
- The walking skeleton is committed as `ab4fe320e`. The standalone `services/git-session-proxy` foundation is parked on the `quilled-meteoroid` worktree for possible later relay hardening; this active branch removes it and relies on Cloudflare outbound HTTP(S) interception rather than proxy-service wiring.
11+
- Deployment order is mandatory: provision the SCM capability secret, deploy `git-token-service`, then deploy `cloud-agent-next`.
12+
13+
## Implemented Architecture
14+
15+
Eligible sandboxes use one HTTP(S) boundary:
16+
17+
```ts
18+
Sandbox.outbound = handleManagedScmOutbound;
19+
```
20+
21+
| Request class | Implemented behavior |
22+
|---|---|
23+
| Unmatched request | Pass through unchanged. |
24+
| Recognized Kilo capability carrier | Redeem server-side; fail closed when invalid, including malformed whitespace/tab carrier cases. |
25+
| Redeemed managed request | Replace sandbox-visible capability auth with redeemed provider auth outside the sandbox. |
26+
| Redirect from redeemed request | Follow manually so managed auth is forwarded only after target validation. |
27+
| Cross-provider or unsupported recognized carrier | Fail closed rather than falling back to raw forwarding. |
28+
29+
Provider-issued signed LFS action URLs and headers intentionally remain visible to the sandbox in this skeleton.
30+
31+
## Implemented Provider Coverage
32+
33+
| Surface | GitHub | GitLab |
34+
|---|---|---|
35+
| Capability | `kgh1.<opaque>` marker with one-hour encrypted claims. | `kgl1.<opaque>` marker with one-hour encrypted claims, separate GitLab purpose, and the shared encryption secret. |
36+
| Origin | Existing GitHub origins. | `gitlab.com` and active self-managed standard HTTPS integration origins on port `443`. |
37+
| Repository path | Exact GitHub repository validation. | Exact nested namespace project validation, for example `group/subgroup/project`. |
38+
| Git smart HTTP | Repository-bound. | Repository-bound. |
39+
| LFS control | Repository-bound `POST .../.git/info/lfs/objects/batch` and `POST .../.git/info/lfs/locks/verify`. | Repository-bound batch and lock verification. |
40+
| CLI API | Existing broad `api.github.com` compatibility for `gh`. | Broad `/api/v4/**` and `/api/graphql` compatibility for `glab`. |
41+
| Managed auth rewrite | Redeemed GitHub auth. | Basic, Bearer, and `PRIVATE-TOKEN` rewriting for managed OAuth/PAT auth. |
42+
| Explicit profile token | Outside managed containment. | Pass through unchanged as intentional user-controlled auth. |
43+
44+
GitLab integration handling uses sanitized refresh logging and per-use database clients. Eligible GitLab session preparation emits a canonical `.git` remote URL, trusted `GITLAB_HOST`, and a capability-backed `GITLAB_TOKEN`; raw managed-auth fallback has been removed.
45+
46+
## Capability Marker Decision
47+
48+
| Provider | Capability marker |
49+
|---|---|
50+
| GitHub | `kgh1.<opaque>` |
51+
| GitLab | `kgl1.<opaque>` |
52+
53+
The short prefix routes the provider codec, fails closed for unsupported formats, and versions the marker. It is not the security boundary: authenticated AES-GCM claims remain authoritative. The `kgh1.` / `kgl1.` rollout intentionally invalidates previously issued verbose-marker capabilities. Coordinate rollout in the required order - provision the SCM capability secret, deploy `git-token-service`, then deploy `cloud-agent-next` - or accept up to one hour of transient failures for in-flight old capabilities.
54+
55+
Fresh capabilities are issued on every dispatched message or command. Remotes and environment are refreshed before prompt delivery, so timer refresh is unnecessary for the skeleton. Only autonomous turns or terminal usage extending beyond one hour remain edge cases.
56+
57+
## DIND Result
58+
59+
The nested-DIND real-Git rewrite probe proved that `--network=host` supplies routing to the catch-all boundary and that nested devcontainers require propagation of Cloudflare's private runtime HTTPS-interception CA/trusted bundle.
60+
61+
`SandboxDIND` catch-all interception is enabled. Managed GitHub and GitLab DIND preparation/wrapper paths use capabilities. Devcontainer setup copies the outer trusted CA bundle to a stable session-home path and injects trust environment variables. This does not imply that provider certificates are the production issue or that the runtime interception certificate is necessarily self-signed. The local missing-bundle negative control empirically returned a TLS rejection matching `server certificate verification failed|SSL certificate problem|certificate verify failed|self-signed certificate in certificate chain`; preserve that as observed probe output rather than a production certificate diagnosis. Probes clean up invocation artifacts.
62+
63+
## Completion Record
64+
65+
| Gate | Status | Evidence |
66+
|---|---|---|
67+
| Task 1: catch-all and GitHub LFS | Complete, reviewed, fixed | Catch-all `Sandbox.outbound`; GitHub LFS batch and lock verification; fail-closed recognized carriers including whitespace/tab; signed actions remain sandbox-visible. |
68+
| Task 2: GitLab token service | Complete, reviewed | One-hour GitLab codec/issue/redeem; active self-managed HTTPS origin; nested namespaces; Git/LFS repo control; broad `glab` REST/GraphQL; sanitized refresh logging; per-use DB clients. |
69+
| Task 3: Cloud Agent GitLab | Complete, reviewed, fixed | Capability-backed canonical `.git` remotes, `GITLAB_TOKEN`, trusted `GITLAB_HOST`; Basic/Bearer/`PRIVATE-TOKEN` rewrites; no raw fallback; cross-provider and unsupported recognized carriers fail closed. |
70+
| Capability markers | Approved | GitHub `kgh1.<opaque>`; GitLab `kgl1.<opaque>`; short routing/fail-closed/version prefix only; AES-GCM claims remain authoritative; dispatch refresh makes one-hour expiry a long-running edge case. |
71+
| Task 4/4b: DIND | Complete, reviewed | Probe proved host-network routing and nested propagation of Cloudflare's private runtime HTTPS-interception CA/trusted bundle; `SandboxDIND` catch-all enabled; GitHub/GitLab DIND paths use capabilities; devcontainer trust injection and probe cleanup implemented. |
72+
| Final validation | Complete | Token service `102` tests; Cloud Agent `1545` passed, `3` skipped; changed-package typecheck `10/53`; both probes passed; whitespace clean; no review blockers remain. |
73+
74+
## Validation Caveat
75+
76+
Full Cloud Agent wrapper validation encountered an unchanged committed baseline timing-sensitive flake in `wrapper/src/lifecycle.test.ts`: `clears aborted state when activity cancels an aborted drain`. Its fixed `50 ms` wait races a real branch subprocess. Marker-focused and package checks pass. Track wrapper test stabilization separately rather than bundling it into the SCM diff.
77+
78+
## Containment Claims
79+
80+
| Path | Skeleton claim |
81+
|---|---|
82+
| Managed GitHub, eligible sandbox including DIND | Contained for recognized capability-bearing smart HTTP, broad `gh` API, and repository-bound LFS control requests. |
83+
| Managed GitLab OAuth/PAT, eligible sandbox including DIND | Contained for recognized capability-bearing smart HTTP, broad `glab` API, and repository-bound LFS control requests on claimed standard HTTPS origins. |
84+
| Provider-issued signed LFS actions | Not contained; action URLs and provider headers remain sandbox-visible. |
85+
| Explicit profile tokens | Not contained; intentional pass-through. |
86+
87+
## Follow-up Discussions
88+
89+
These are explicit follow-ups, not blockers for this walking skeleton:
90+
91+
| Area | Follow-up |
92+
|---|---|
93+
| Provider-signed LFS actions | Use the standalone relay parked on `quilled-meteoroid` later if a stronger boundary is required. |
94+
| Self-managed GitLab origins | Add SSRF hardening and admin allowlisting for active-integration approval. |
95+
| GitLab instance shape | Discuss nonstandard ports and subpath-hosted instances. |
96+
| GitLab token semantics | Resolve project-access-token semantics discrepancy. |
97+
| GitLab OAuth | Add refresh concurrency handling and provision default GitLab OAuth client environment values. |
98+
| Capability continuity | Add refresh within long-running autonomous turns or terminal sessions that outlive the one-hour capability lifetime; dispatched messages and commands already refresh remotes and environment before prompt delivery. |
99+
| Wrapper test stability | Stabilize the unchanged baseline timing-sensitive lifecycle test separately from the SCM diff. |
100+
| Capability carriers | Harden query/body carrier handling. |
101+
| Nested trust | Cover propagation of Cloudflare's private runtime HTTPS-interception CA/trusted bundle into Dockerfile build stages, unusual custom images/trust stores, CA rotation, and non-host nested networks. |
102+
| Cleanup behavior | Cover abrupt cleanup. The stale `dev/local` standalone proxy WIP is isolated on `quilled-meteoroid`. |

‎services/cloud-agent-next/src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
export { default } from './server.js';
2-
export { Sandbox, Sandbox as SandboxSmall, Sandbox as SandboxDIND } from '@cloudflare/sandbox';
2+
export { Sandbox, SandboxSmall, SandboxDIND, ContainerProxy } from './sandbox-outbound.js';
33
export { CloudAgentSession } from './persistence/CloudAgentSession.js';

‎services/cloud-agent-next/src/kilo/devcontainer.test.ts‎

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,10 @@ import {
1616
bringUpDevContainer,
1717
buildRestoreCommand,
1818
buildOverrideConfig,
19+
buildDevContainerTrustedCaBundleSetupCommand,
1920
detectDevContainer,
2021
getDevContainerOverridePath,
22+
getDevContainerTrustedCaBundlePath,
2123
KILO_AGENT_SESSION_LABEL,
2224
KILO_WRAPPER_PORT_LABEL,
2325
mergeDevContainerConfig,
@@ -197,6 +199,9 @@ describe('bringUpDevContainer', () => {
197199
const commands = execCalls.map(([cmd]) => cmd);
198200
const bootstrapCall = execCalls.find(([cmd]) => cmd.includes('nvm install --lts'));
199201
expect(preflightCount).toBe(2);
202+
expect(commands).toContain(
203+
"source=${GIT_SSL_CAINFO:-/etc/ssl/certs/ca-certificates.crt} && test -f \"$source\" && mkdir -p '/home/agent_xyz/.kilocode/platform' && cp \"$source\" '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt' && chmod 444 '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt'"
204+
);
200205
expect(commands.some(cmd => cmd.includes('bun --version'))).toBe(true);
201206
expect(commands.some(cmd => cmd.includes('nvm install --lts'))).toBe(true);
202207
expect(commands.some(cmd => cmd.includes('nvm use --lts'))).toBe(false);
@@ -328,6 +333,7 @@ describe('buildOverrideConfig', () => {
328333
expect(cfg.mounts).toEqual([
329334
'source=/opt/kilo-cloud,target=/opt/kilo-cloud,type=bind,readonly',
330335
'source=/home/agent_xyz,target=/home/agent_xyz,type=bind',
336+
'source=/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt,target=/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt,type=bind,readonly',
331337
]);
332338
});
333339

@@ -344,11 +350,21 @@ describe('buildOverrideConfig', () => {
344350
]);
345351
});
346352

347-
it('sets HOME without exposing the outer Docker socket', () => {
353+
it('sets platform-owned nested trust env for lifecycle hooks and remote execution', () => {
348354
const cfg = buildOverrideConfig(baseOpts);
355+
const trustedCaBundle = '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt';
356+
const platformTrustEnv = {
357+
GIT_SSL_CAINFO: trustedCaBundle,
358+
SSL_CERT_FILE: trustedCaBundle,
359+
CURL_CA_BUNDLE: trustedCaBundle,
360+
REQUESTS_CA_BUNDLE: trustedCaBundle,
361+
NODE_EXTRA_CA_CERTS: trustedCaBundle,
362+
};
363+
expect(cfg.containerEnv).toEqual(platformTrustEnv);
349364
expect(cfg.remoteEnv).toEqual({
350365
HOME: '/home/agent_xyz',
351366
KILO_CLOUD_AGENT: '1',
367+
...platformTrustEnv,
352368
});
353369
});
354370

@@ -364,6 +380,9 @@ describe('writeMergedOverrideConfig', () => {
364380
expect(cmd).toContain('const outputPath = "/tmp/merged-devcontainer.json"');
365381
expect(cmd).toContain('source=/opt/kilo-cloud,target=/opt/kilo-cloud,type=bind,readonly');
366382
expect(cmd).toContain('source=/home/agent_xyz,target=/home/agent_xyz,type=bind');
383+
expect(cmd).toContain(
384+
'source=/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt,target=/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt,type=bind,readonly'
385+
);
367386
expect(cmd).toContain(`${KILO_AGENT_SESSION_LABEL}=agent_xyz`);
368387
expect(cmd).toContain(`${KILO_WRAPPER_PORT_LABEL}=5050`);
369388
return { exitCode: 0 };
@@ -414,6 +433,7 @@ describe('mergeDevContainerConfig', () => {
414433
'source=/user,target=/user,type=bind',
415434
'source=/opt/kilo-cloud,target=/opt/kilo-cloud,type=bind,readonly',
416435
'source=/home/agent_xyz,target=/home/agent_xyz,type=bind',
436+
'source=/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt,target=/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt,type=bind,readonly',
417437
]);
418438
expect(merged.runArgs).toEqual([
419439
'--env',
@@ -426,10 +446,22 @@ describe('mergeDevContainerConfig', () => {
426446
'--label',
427447
`${KILO_WRAPPER_PORT_LABEL}=5050`,
428448
]);
449+
expect(merged.containerEnv).toEqual({
450+
GIT_SSL_CAINFO: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
451+
SSL_CERT_FILE: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
452+
CURL_CA_BUNDLE: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
453+
REQUESTS_CA_BUNDLE: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
454+
NODE_EXTRA_CA_CERTS: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
455+
});
429456
expect(merged.remoteEnv).toEqual({
430457
USER_ENV: '1',
431458
HOME: '/home/agent_xyz',
432459
KILO_CLOUD_AGENT: '1',
460+
GIT_SSL_CAINFO: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
461+
SSL_CERT_FILE: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
462+
CURL_CA_BUNDLE: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
463+
REQUESTS_CA_BUNDLE: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
464+
NODE_EXTRA_CA_CERTS: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
433465
});
434466
});
435467

@@ -442,6 +474,26 @@ describe('mergeDevContainerConfig', () => {
442474
expect(merged.remoteUser).toBe('root');
443475
});
444476

477+
it('preserves user env while ensuring platform trust paths win', () => {
478+
const merged = mergeDevContainerConfig(
479+
{
480+
image: 'debian:bookworm',
481+
containerEnv: { USER_CONTAINER_ENV: '1', GIT_SSL_CAINFO: '/user/container-ca.crt' },
482+
remoteEnv: { USER_REMOTE_ENV: '1', GIT_SSL_CAINFO: '/user/remote-ca.crt' },
483+
},
484+
{ sessionHome: '/home/agent_xyz', wrapperPort: 5050, agentSessionId: 'agent_xyz' }
485+
);
486+
487+
expect(merged.containerEnv).toMatchObject({
488+
USER_CONTAINER_ENV: '1',
489+
GIT_SSL_CAINFO: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
490+
});
491+
expect(merged.remoteEnv).toMatchObject({
492+
USER_REMOTE_ENV: '1',
493+
GIT_SSL_CAINFO: '/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt',
494+
});
495+
});
496+
445497
it('removes host-side initializeCommand while preserving in-container lifecycle hooks', () => {
446498
const merged = mergeDevContainerConfig(
447499
{
@@ -473,6 +525,7 @@ describe('mergeDevContainerConfig', () => {
473525
'source=/workspace/cache,target=/cache,type=bind',
474526
'source=/opt/kilo-cloud,target=/opt/kilo-cloud,type=bind,readonly',
475527
'source=/home/agent_xyz,target=/home/agent_xyz,type=bind',
528+
'source=/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt,target=/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt,type=bind,readonly',
476529
]);
477530
});
478531

@@ -651,6 +704,26 @@ describe('buildRestoreCommand', () => {
651704
});
652705
});
653706

707+
describe('nested devcontainer trusted CA bundle', () => {
708+
it('uses a stable path inside the session-home bind mount', () => {
709+
expect(getDevContainerTrustedCaBundlePath('/home/agent_xyz')).toBe(
710+
'/home/agent_xyz/.kilocode/platform/outer-trusted-ca-bundle.crt'
711+
);
712+
});
713+
714+
it('copies the effective outer bundle with safe shell quoting and read-only permissions', () => {
715+
const command = buildDevContainerTrustedCaBundleSetupCommand("/home/agent_'xyz");
716+
expect(command).toContain('source=${GIT_SSL_CAINFO:-/etc/ssl/certs/ca-certificates.crt}');
717+
expect(command).toContain("mkdir -p '/home/agent_'\\''xyz/.kilocode/platform'");
718+
expect(command).toContain(
719+
"cp \"$source\" '/home/agent_'\\''xyz/.kilocode/platform/outer-trusted-ca-bundle.crt'"
720+
);
721+
expect(command).toContain(
722+
"chmod 444 '/home/agent_'\\''xyz/.kilocode/platform/outer-trusted-ca-bundle.crt'"
723+
);
724+
});
725+
});
726+
654727
describe('getDevContainerOverridePath', () => {
655728
it('falls back to the legacy deterministic temp path without config metadata', () => {
656729
expect(getDevContainerOverridePath('agent_xyz')).toBe(

0 commit comments

Comments
 (0)