deepdebug-local-agent 1.4.0 → 1.6.0

package/tools/interop/LaV2NodeContentRelayE2ETest.java

@@ -0,0 +1,374 @@
+package io.visionhammer.gateway.cloud.infrastructure.byoc;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.micrometer.core.instrument.MeterRegistry;
+import io.visionhammer.gateway.cloud.api.content.ContentRelayController;
+import io.visionhammer.gateway.cloud.application.byoc.LocalAgentSessionRegistry;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaProtocolV2Properties;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2InboundListener;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2Metrics;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2Session;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2SessionStore;
+import io.visionhammer.gateway.cloud.application.byoc.v2.LaV2TestKit;
+import io.visionhammer.gateway.cloud.application.content.ContentBufferBudget;
+import io.visionhammer.gateway.cloud.application.content.ContentIndexRegistry;
+import io.visionhammer.gateway.cloud.application.content.ContentKind;
+import io.visionhammer.gateway.cloud.application.content.ContentRelayLogStore;
+import io.visionhammer.gateway.cloud.application.content.ContentRelayProperties;
+import io.visionhammer.gateway.cloud.application.content.ContentRelayService;
+import io.visionhammer.gateway.governance.application.DataPlanePolicy;
+import io.visionhammer.gateway.identity.application.AgentAuthorizationEntity;
+import io.visionhammer.gateway.identity.application.AgentAuthorizationStore;
+import io.visionhammer.gateway.security.AuthenticatedUser;
+import io.visionhammer.gateway.security.TenantAccessGuard;
+import io.visionhammer.gateway.shared.localagent.AgentRequestSigner;
+import io.visionhammer.gateway.workspace.application.WorkspaceEntity;
+import io.visionhammer.gateway.workspace.application.WorkspaceRepository;
+import io.visionhammer.gateway.workspace.application.WorkspaceRowStore;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.ObjectProvider;
+import org.springframework.http.MediaType;
+import org.springframework.http.server.reactive.HttpHandler;
+import org.springframework.http.server.reactive.ReactorHttpHandlerAdapter;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.test.web.reactive.server.SecurityMockServerConfigurers;
+import org.springframework.security.web.reactive.result.method.annotation.AuthenticationPrincipalArgumentResolver;
+import org.springframework.test.web.reactive.server.WebTestClient;
+import org.springframework.web.reactive.socket.server.WebSocketService;
+import org.springframework.web.reactive.socket.server.support.HandshakeWebSocketService;
+import org.springframework.web.reactive.socket.server.upgrade.ReactorNettyRequestUpgradeStrategy;
+import org.springframework.web.server.adapter.WebHttpHandlerBuilder;
+import reactor.core.publisher.Mono;
+import reactor.core.scheduler.Schedulers;
+import reactor.netty.DisposableServer;
+import reactor.netty.http.server.HttpServer;
+
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.time.Clock;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HexFormat;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.LinkedBlockingQueue;
+import java.util.concurrent.TimeUnit;
+
+import static io.visionhammer.gateway.cloud.application.byoc.v2.LaV2TestKit.OM;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assumptions.assumeTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * F3-07b end to end, WITHOUT any patch on either side: HTTP ({@code GET} and {@code POST /api/v1/content/{kind}...}) -> the
+ * REAL {@link ContentRelayController} and {@link ContentRelayService} (real {@code ContentRef} validation, real
+ * {@code TenantAccessGuard.requireOwnedWorkspace}) -> the REAL {@link AgentWebSocketHandler} / {@link LaV2Session} behind a
+ * Reactor Netty WebSocket on loopback, real system clock, real Ed25519 signer -> the REAL Node Local Agent
+ * (tools/interop/la-interop-content-client.mjs: real content handlers, DLP enforce, path guard, git diff, content.index).
+ * The ids are the 43-char ones the Local Agent minted and announced; the diff of the work tree uses {@code worktree}.
+ *
+ * <p>Copy it next to the other byoc tests of the gateway (it needs package access to nothing, but it lives with them) and run
+ * (JDK 21; node >= 18; {@code npm ci} done in the LA repo; gateway branch with F3-06b + F3-07b):
+ * <pre>
+ *   cp tools/interop/LaV2NodeContentRelayE2ETest.java \
+ *      &lt;gateway&gt;/src/test/java/io/visionhammer/gateway/cloud/infrastructure/byoc/
+ *   LA_REPO=/path/to/deepdebug-local-agent mvn -o test -Dtest=LaV2NodeContentRelayE2ETest
+ * </pre>
+ * Skipped when LA_REPO is not set. Still mocked: the workspace store, the data plane policy (tenant in {@code client}), the
+ * log store, the JWT (a principal). Not proven: Cloud Run / LB / TLS, Memorystore EU (AUTH + TLS 6378), two gateway
+ * instances, load, a tenant of QA/PROD.
+ */
+class LaV2NodeContentRelayE2ETest {
+
+    private static final String TENANT = LaV2TestKit.TENANT;
+    private static final String AGENT = LaV2TestKit.AGENT;
+    private static final UUID USER = UUID.fromString("33333333-3333-4333-8333-333333333333");
+    private static final String BASE = "/api/v1/content/";
+    private static final String ID43 = "^[A-Za-z0-9_-]{43}$";
+
+    private static Authentication principal(String role) {
+        AuthenticatedUser user = AuthenticatedUser.builder().userId(USER).tenantId(UUID.fromString(TENANT)).role(role)
+                .email("ana@acme.com").build();
+        return new UsernamePasswordAuthenticationToken(user, "n/a", List.of());
+    }
+
+    @SuppressWarnings("unchecked")
+    @Test
+    void httpToControllerToLaV2SessionToTheRealNodeAgent() throws Exception {
+        String laRepo = System.getenv("LA_REPO");
+        assumeTrue(laRepo != null && !laRepo.isBlank(), "LA_REPO not set");
+
+        // ---- the gateway side: real session store + real handler, the content.index registry as the sink --------------------------
+        Clock clock = Clock.systemUTC();
+        LaProtocolV2Properties props = new LaProtocolV2Properties();
+        props.setEnabled(true);
+        ContentRelayProperties relayProps = new ContentRelayProperties();
+        relayProps.setEnabled(true);
+        ContentIndexRegistry index = new ContentIndexRegistry(relayProps, null, System::currentTimeMillis);
+        List<String> rejected = Collections.synchronizedList(new ArrayList<>());
+        LaV2Metrics metrics = new LaV2Metrics() {
+            @Override public void rejected(String code) { rejected.add(code); }
+        };
+        LaV2InboundListener listener = (t, a, type, rid, payload) -> { };
+        AgentRequestSigner signer = new AgentRequestSigner(LaV2TestKit.PEM, "k1", clock);
+        LaV2Session.Env env = new LaV2Session.Env(LaV2TestKit.CONTRACT, props, signer, OM, clock, metrics, Schedulers.parallel(), List.of(listener), index);
+
+        AgentAuthorizationStore store = mock(AgentAuthorizationStore.class);
+        WorkspaceRepository workspaceRepo = mock(WorkspaceRepository.class);
+        DataPlanePolicy policy = mock(DataPlanePolicy.class);
+        when(workspaceRepo.findDefaultByTenantId(anyString())).thenReturn(Mono.empty());
+        when(store.save(any())).thenAnswer(i -> Mono.just(i.getArgument(0)));
+        when(store.touchLastSeen(any())).thenReturn(Mono.just(1));
+        when(policy.requiresEnforcedSigning(anyString())).thenReturn(Mono.just(true));
+        when(policy.modeWire(anyString())).thenReturn(Mono.just("client"));
+        AgentAuthorizationEntity auth = new AgentAuthorizationEntity();
+        auth.setId(UUID.fromString(AGENT));
+        auth.setTenantId(UUID.fromString(TENANT));
+        auth.setAuthorizationToken("tok");
+        when(store.findByAuthorizationToken("tok")).thenReturn(Mono.just(auth));
+        AgentWebSocketHandler handler = new AgentWebSocketHandler(OM, workspaceRepo, store, signer, null, null, null,
+                new LaV2SessionStore(env), props, policy);
+
+        // ---- the HTTP side: the real controller over the real service, the handler as the LocalAgentContentGateway ---------------------
+        ContentRelayLogStore logStore = mock(ContentRelayLogStore.class);
+        when(logStore.insert(any())).thenReturn(Mono.empty());
+        ObjectProvider<MeterRegistry> noMeters = mock(ObjectProvider.class);
+        ObjectProvider<LocalAgentSessionRegistry> noRegistry = mock(ObjectProvider.class);
+        ObjectProvider<ContentIndexRegistry> indexProvider = mock(ObjectProvider.class);
+        when(indexProvider.getIfAvailable()).thenReturn(index);
+        WorkspaceRowStore workspaces = mock(WorkspaceRowStore.class);
+        WorkspaceEntity ws1 = new WorkspaceEntity();
+        ws1.setId("ws-1");
+        ws1.setTenantId(TENANT);
+        when(workspaces.findByTenantIdAndId(TENANT, "ws-1")).thenReturn(Mono.just(ws1));
+        when(workspaces.findByTenantIdAndId(anyString(), anyString())).thenAnswer(i ->
+                TENANT.equals(i.getArgument(0)) && "ws-1".equals(i.getArgument(1)) ? Mono.just(ws1) : Mono.empty());
+
+        ContentRelayService service = new ContentRelayService(handler, policy, logStore, relayProps, noMeters, noRegistry, indexProvider);
+        ContentRelayController controller = new ContentRelayController(service, new TenantAccessGuard(workspaces), new ObjectMapper(),
+                new ContentBufferBudget(relayProps, null));
+        WebTestClient http = WebTestClient.bindToController(controller)
+                .argumentResolvers(r -> r.addCustomResolver(
+                        new AuthenticationPrincipalArgumentResolver(new org.springframework.core.ReactiveAdapterRegistry())))
+                .controllerAdvice(new io.visionhammer.gateway.web.GlobalExceptionAdvice())
+                .apply(SecurityMockServerConfigurers.springSecurity())
+                .configureClient().codecs(c -> c.defaultCodecs().maxInMemorySize(8 << 20)).responseTimeout(Duration.ofSeconds(45)).build()
+                .mutateWith(SecurityMockServerConfigurers.mockAuthentication(principal("admin")));
+
+        WebSocketService wsService = new HandshakeWebSocketService(new ReactorNettyRequestUpgradeStrategy());
+        HttpHandler wsHttp = WebHttpHandlerBuilder.webHandler(exchange -> wsService.handleRequest(exchange, handler)).build();
+        DisposableServer server = reactor.netty.http.server.HttpServer.create().host("127.0.0.1").port(0).handle(new ReactorHttpHandlerAdapter(wsHttp)).bindNow();
+
+        // ---- the real Node Local Agent --------------------------------------------------------------------------------------------
+        ProcessBuilder pb = new ProcessBuilder("node", laRepo + "/tools/interop/la-interop-content-client.mjs");
+        pb.environment().putAll(Map.of(
+                "GW_URL", "ws://127.0.0.1:" + server.port() + "/api/v1/agent/ws", "TOKEN", "tok", "TENANT", TENANT, "AGENT", AGENT,
+                "KEY_ID", "k1", "PUBLIC_KEY", LaV2TestKit.PUB, "MODE", "enforce",
+                "LOCAL_AGENT_DLP_MODE", System.getenv().getOrDefault("LA_DLP_MODE", "enforce")));
+        pb.redirectErrorStream(true);
+        Process proc = pb.start();
+        BlockingQueue<JsonNode> events = new LinkedBlockingQueue<>();
+        List<String> transcript = Collections.synchronizedList(new ArrayList<>());
+        Thread reader = new Thread(() -> {
+            try (BufferedReader r = new BufferedReader(new InputStreamReader(proc.getInputStream(), StandardCharsets.UTF_8))) {
+                String line;
+                while ((line = r.readLine()) != null) {
+                    transcript.add(line);
+                    try {
+                        events.add(OM.readTree(line));
+                    } catch (Exception ignored) {
+                        // node warnings
+                    }
+                }
+            } catch (Exception ignored) {
+                // process ended
+            }
+        });
+        reader.setDaemon(true);
+        reader.start();
+        java.io.Writer stdin = new java.io.OutputStreamWriter(proc.getOutputStream(), StandardCharsets.UTF_8);
+
+        try {
+            JsonNode refsEvt = await(events, "refs", 20);
+            await(events, "ready", 15);
+            assertThat(handler.isAgentConnected(TENANT)).isTrue();
+            JsonNode refs = refsEvt.path("refs");
+            String ghp = refsEvt.path("ghp").asText();
+            for (String k : List.of("app", "big", "mid", "swapped", "bin", "diffFile")) {
+                assertThat(refs.path(k).asText()).as("id minted by the LA: " + k).matches(ID43);
+            }
+            assertThat(refs.path("envFile").isNull()).isTrue();
+            assertThat(refs.path("envBackup").isNull()).isTrue();
+
+            // 0. content.index: the gateway learned the ids the agent announced (kind + workspace + id), nothing else
+            String appId = refs.path("app").asText();
+            awaitTrue(() -> index.find(TENANT, "ws-1", ContentKind.FILE, appId).isPresent(), 10, "content.index reached the gateway registry");
+            for (String k : List.of("app", "big", "mid", "swapped", "bin")) {
+                assertThat(index.find(TENANT, "ws-1", ContentKind.FILE, refs.path(k).asText())).as("announced " + k).isPresent();
+            }
+            assertThat(index.find(TENANT, "ws-1", ContentKind.DIFF, refs.path("diffFile").asText())).isPresent();
+            assertThat(index.find(TENANT, "ws-1", ContentKind.FILE, appId).get().size()).isEqualTo(
+                    ("first line\ntoken = \"" + ghp + "\"\nlast line\n").getBytes(StandardCharsets.UTF_8).length);
+            assertThat(index.find(UUID.randomUUID().toString(), "ws-1", ContentKind.FILE, appId)).as("other tenant").isEmpty();
+            assertThat(index.find(TENANT, "ws-2", ContentKind.FILE, appId)).as("other workspace").isEmpty();
+
+            // 1. GET with the minted id: served, token masked (DLP enforce), the rest intact; Content-Type from the agent
+            String body = new String(http.get().uri(BASE + "file/" + appId + "?workspaceId=ws-1").exchange()
+                    .expectStatus().isOk().expectHeader().valueEquals("Cache-Control", "no-store")
+                    .expectBody().returnResult().getResponseBody(), StandardCharsets.UTF_8);
+            assertThat(body).contains("first line").contains("[REDACTED:github_token]").contains("last line").doesNotContain(ghp);
+
+            // 2. POST (the id in the body, not in the URL): the same
+            String viaPost = new String(http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", appId, "workspaceId", "ws-1")).exchange()
+                    .expectStatus().isOk().expectBody().returnResult().getResponseBody(), StandardCharsets.UTF_8);
+            assertThat(viaPost).isEqualTo(body);
+
+            // 3. 1 MiB byte for byte through the whole chain (32 chunks), by GET and by SSE
+            byte[] big = http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", refs.path("big").asText(), "workspaceId", "ws-1")).exchange()
+                    .expectStatus().isOk().expectBody().returnResult().getResponseBody();
+            assertThat(big).hasSize(refsEvt.path("bigBytes").asInt());
+            assertThat(HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(big))).isEqualTo(refsEvt.path("bigSha256").asText());
+            String sse = new String(http.post().uri(BASE + "file/query").accept(MediaType.TEXT_EVENT_STREAM).contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", refs.path("big").asText(), "workspaceId", "ws-1")).exchange()
+                    .expectStatus().isOk().expectBody().returnResult().getResponseBody(), StandardCharsets.UTF_8);
+            assertThat(sse.split("event: chunk", -1).length - 1).as("SSE chunk events").isEqualTo(32);
+            assertThat(sse).contains("event: done").doesNotContain("event: error");
+
+            // 4. a token straddling the 32 KiB boundary is never visible, whole or in part
+            String mid = new String(http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", refs.path("mid").asText(), "workspaceId", "ws-1")).exchange()
+                    .expectStatus().isOk().expectBody().returnResult().getResponseBody(), StandardCharsets.UTF_8);
+            assertThat(mid).contains("[REDACTED:github_token]").doesNotContain(ghp.substring(0, 12));
+
+            // 5. the symbolic ref worktree (kind diff, needs the workspace): GET and POST; masked, without .env
+            for (String diff : List.of(
+                    new String(http.get().uri(BASE + "diff/worktree?workspaceId=ws-1").exchange().expectStatus().isOk()
+                            .expectHeader().contentType("text/x-diff").expectBody().returnResult().getResponseBody(), StandardCharsets.UTF_8),
+                    new String(http.post().uri(BASE + "diff/query").contentType(MediaType.APPLICATION_JSON)
+                            .bodyValue(Map.of("ref", "worktree", "workspaceId", "ws-1")).exchange().expectStatus().isOk()
+                            .expectBody().returnResult().getResponseBody(), StandardCharsets.UTF_8))) {
+                assertThat(diff).contains("tracked.js").contains("[REDACTED:github_token]").doesNotContain(ghp)
+                        .doesNotContain("SECRET-ENV-VALUE").doesNotContain("EDITOR-BACKUP-SECRET").doesNotContain(".env");
+            }
+            http.get().uri(BASE + "diff/worktree").exchange().expectStatus().isBadRequest();                       // needs a workspace
+            http.get().uri(BASE + "file/worktree?workspaceId=ws-1").exchange().expectStatus().isBadRequest();      // diff only
+            assertThat(new String(http.post().uri(BASE + "diff/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", refs.path("diffFile").asText(), "workspaceId", "ws-1")).exchange().expectStatus().isOk()
+                    .expectBody().returnResult().getResponseBody(), StandardCharsets.UTF_8)).contains("tracked.js");
+
+            // 6. the agent is the authority: link swapped to a file outside the workspace = 403; binary in enforce = 403;
+            //    a hard link to a file outside the workspace = 403 (F3-07b); an id the agent never minted = 404
+            http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", refs.path("swapped").asText(), "workspaceId", "ws-1")).exchange()
+                    .expectStatus().isForbidden().expectBody(String.class).value(b -> assertThat(b).doesNotContain("OUTSIDE-SECRET"));
+            http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", refs.path("bin").asText(), "workspaceId", "ws-1")).exchange().expectStatus().isForbidden();
+            if (refsEvt.path("hardLinked").asBoolean()) {
+                http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                        .bodyValue(Map.of("ref", refs.path("hard").asText(), "workspaceId", "ws-1")).exchange()
+                        .expectStatus().isForbidden().expectBody(String.class).value(b -> assertThat(b).doesNotContain("OUTSIDE-SECRET"));
+            }
+            http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", "A".repeat(43), "workspaceId", "ws-1")).exchange().expectStatus().isNotFound();
+
+            // 7. the gateway refuses before asking the agent: the F3-07 id of 26 chars, a path, a foreign workspace
+            http.get().uri(BASE + "file/cr1_AAAAAAAAAAAAAAAAAAAAAA?workspaceId=ws-1").exchange().expectStatus().isBadRequest();
+            http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", "../../etc/passwd", "workspaceId", "ws-1")).exchange().expectStatus().isBadRequest();
+            http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", appId, "workspaceId", "ws-of-somebody-else")).exchange().expectStatus().isNotFound();
+
+            // 8. the same id with the agent's other tenant's role: the viewer is stopped by the permission filter in the full app
+            //    (ContentRelayPermissionTest, gateway side); here the controller only needs a principal of THIS tenant: another tenant has no agent
+            WebTestClient other = http.mutateWith(SecurityMockServerConfigurers.mockAuthentication(
+                    new UsernamePasswordAuthenticationToken(AuthenticatedUser.builder().userId(USER).tenantId(UUID.fromString(LaV2TestKit.OTHER_TENANT))
+                            .role("admin").email("eve@evil.com").build(), "n/a", List.of())));
+            other.get().uri(BASE + "file/" + appId).exchange().expectStatus().is5xxServerError(); // 503 agent_offline: no agent for that tenant
+
+            // 9. a kind the agent does not serve (the id is a UUID of an incident): not a 200, and nothing about the files leaks
+            http.get().uri(BASE + "incident.detail/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee?workspaceId=ws-1").exchange()
+                    .expectStatus().value(s -> assertThat(s).isGreaterThanOrEqualTo(400));
+
+            // 10. require-known-ref ON (one instance only): an id the agent announced passes; one it never announced is refused
+            //     by the gateway itself, before the agent is asked
+            ContentRelayProperties strict = new ContentRelayProperties();
+            strict.setEnabled(true);
+            strict.setRequireKnownRef(true);
+            ContentRelayService strictService = new ContentRelayService(handler, policy, logStore, strict, noMeters, noRegistry, indexProvider);
+            WebTestClient strictHttp = WebTestClient.bindToController(new ContentRelayController(strictService, new TenantAccessGuard(workspaces),
+                            new ObjectMapper(), new ContentBufferBudget(strict, null)))
+                    .argumentResolvers(r -> r.addCustomResolver(new AuthenticationPrincipalArgumentResolver(new org.springframework.core.ReactiveAdapterRegistry())))
+                    .controllerAdvice(new io.visionhammer.gateway.web.GlobalExceptionAdvice())
+                    .apply(SecurityMockServerConfigurers.springSecurity()).configureClient().codecs(c -> c.defaultCodecs().maxInMemorySize(8 << 20)).responseTimeout(Duration.ofSeconds(45)).build()
+                    .mutateWith(SecurityMockServerConfigurers.mockAuthentication(principal("admin")));
+            strictHttp.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", appId, "workspaceId", "ws-1")).exchange().expectStatus().isOk();
+            strictHttp.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", "A".repeat(43), "workspaceId", "ws-1")).exchange().expectStatus().isNotFound();
+
+            // 11. the content.index counters of the agent: everything announced was accepted; nothing the agent put on the wire was refused
+            send(stdin, "stats");
+            JsonNode stats = await(events, "stats", 10);
+            assertThat(stats.path("index").path("rejected").asInt()).isZero();
+            assertThat(stats.path("index").path("accepted").asInt()).isGreaterThanOrEqualTo(6);
+            assertThat(rejected).as("frames the real LaV2Session rejected: %s", rejected).isEmpty();
+            // nothing in what the agent printed (events, warnings) carries content, a path or the full id of a file
+            String printed = String.join("\n", transcript.stream().filter(l -> !l.contains("\"evt\":\"refs\"")).toList());
+            assertThat(printed).doesNotContain("OUTSIDE-SECRET").doesNotContain("SECRET-ENV-VALUE").doesNotContain("EDITOR-BACKUP").doesNotContain("f307-interop-");
+            System.out.println("CONTENT RELAY E2E OK: index entries=" + stats.path("index").path("accepted").asInt() + " rejected=" + rejected);
+        } finally {
+            try {
+                send(stdin, "quit");
+            } catch (Exception ignored) {
+                // gone
+            }
+            proc.waitFor(5, TimeUnit.SECONDS);
+            proc.destroyForcibly();
+            server.disposeNow();
+        }
+    }
+
+    private static void send(java.io.Writer w, String line) throws Exception {
+        w.write(line + "\n");
+        w.flush();
+    }
+
+    private static void awaitTrue(java.util.function.BooleanSupplier cond, int seconds, String what) throws Exception {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(seconds);
+        while (System.nanoTime() < deadline) {
+            if (cond.getAsBoolean()) {
+                return;
+            }
+            Thread.sleep(50);
+        }
+        throw new AssertionError("timed out: " + what);
+    }
+
+    private static JsonNode await(BlockingQueue<JsonNode> q, String evt, int seconds) throws Exception {
+        long deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(seconds);
+        List<String> seen = new ArrayList<>();
+        while (System.nanoTime() < deadline) {
+            JsonNode n = q.poll(100, TimeUnit.MILLISECONDS);
+            if (n == null) {
+                continue;
+            }
+            if (evt.equals(n.path("evt").asText())) {
+                return n;
+            }
+            seen.add(n.path("evt").asText() + (n.has("code") ? ":" + n.path("code").asText() : "") + (n.has("m") ? ":" + n.path("m").asText() : ""));
+        }
+        throw new AssertionError("no '" + evt + "' event from the Node LA within " + seconds + " s; saw " + seen);
+    }
+}

package/tools/interop/README.md

@@ -19,3 +19,20 @@ a type with no handler -> rejected ack `protocol_unsupported`; 20 `job.event` in
 with the same session id and consecutive seq; content after the resume; zero frames refused by the gateway.
 It is skipped when `LA_REPO` is not set. It does not prove Cloud Run / the load balancer / TLS / Memorystore /
 two gateway instances.
+
+## F3-07: content handlers against the real `LaV2Session`
+
+`la-interop-content-client.mjs` is a Local Agent with the REAL content handlers (opaque ids, path guard, DLP `enforce`,
+git diff, chunking) on a temp workspace; `LaV2NodeContentInteropTest.java` drives it through `AgentWebSocketHandler.requestContent`.
+
+```bash
+cp tools/interop/LaV2NodeContentInteropTest.java <gateway>/src/test/java/io/visionhammer/gateway/cloud/infrastructure/byoc/
+LA_REPO=/path/to/deepdebug-local-agent mvn -o test -Dtest=LaV2NodeContentInteropTest   # JDK 21
+```
+
+It checks: a token masked in a served file; 1 MiB = 32 chunks byte for byte (sha256); a token straddling the 32 KiB
+boundary never appears, whole or in part; an id swapped for a link to a file outside the workspace -> `forbidden`;
+`../../etc/passwd`, `/etc/passwd`, a plain relative path and a made-up id -> `not_found`; binary -> `forbidden` in enforce;
+`report` -> `error` + `protocol_unsupported`; the diff of the work tree masked and without `.env`; the consumer cancels
+after the first chunk and the next request still works; zero frames refused by the gateway; nothing printed by the agent
+carries content or a path. Negative control: with the DLP step disabled in the agent the test fails.

package/tools/interop/la-interop-content-client.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// F3-07 / F3-07b interoperability client: the REAL Local Agent content handlers (src/la-protocol-v2/content-handlers, DLP, path
+// guard, opaque ids of 43 chars, content.index) around the real v2 link, against the real gateway (driven by
+// LaV2NodeContentInteropTest = straight into LaV2Session, and LaV2NodeContentRelayE2ETest = HTTP -> ContentRelayController ->
+// LaV2Session -> this client). Nothing is faked on the agent side except the workspace manager (one temp workspace). It
+// prepares files, mints the opaque ids the way a future inventory would (link.content.mintRef: the SAME 43-char ids the
+// control plane sees, announced to it in `content.index`) and prints them, one JSON per line, for the test.
+//
+//   env: GW_URL TOKEN TENANT AGENT KEY_ID PUBLIC_KEY MODE(enforce) LOCAL_AGENT_DLP_MODE ... (LOCAL_AGENT_CONTENT_HANDLERS is forced on)
+//        LOCAL_AGENT_DLP_MODE must be enforce: otherwise the handlers are NOT registered (F3-07b) and every content.request is refused
+//   stdin: "stats" (prints the content.index counters) | "quit"
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { execFileSync } from "node:child_process";
+import WebSocket from "ws";
+import { buildV2Link } from "../../src/la-protocol-v2/runtime.js";
+import { resolveSigningConfig } from "../../src/utils/request-signing.js";
+
+const { GW_URL, TOKEN, TENANT, AGENT, KEY_ID, PUBLIC_KEY, MODE = "enforce" } = process.env;
+const out = (o) => process.stdout.write(JSON.stringify(o) + "\n");
+
+const base = fs.mkdtempSync(path.join(os.tmpdir(), "f307-interop-"));
+const ROOT = path.join(base, "ws");
+fs.mkdirSync(ROOT);
+const put = (rel, data) => { const p = path.join(ROOT, rel); fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, data); };
+const git = (...a) => execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "-c", "commit.gpgsign=false", ...a], { cwd: ROOT, stdio: "ignore" });
+
+export const GH = "ghp_" + "A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8";
+// letters only: the DLP phone rule masks long digit runs, which would make 1 MiB grow past the limit
+const bigText = Buffer.from("alpha beta gamma delta epsilon zeta eta theta\n".repeat(30000)).subarray(0, 1024 * 1024);
+const straddle = "a".repeat(32766 - 20 - 1) + "\n" + `k=${GH}\n` + "z\n".repeat(60000);
+
+put("src/app.txt", `first line\ntoken = "${GH}"\nlast line\n`);
+put("big.txt", bigText);
+put("mid.txt", straddle);
+put("swapped.txt", "innocent");
+put("bin.png", Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0]), crypto.randomBytes(4000)]));
+put(".env", "API=SECRET-ENV-VALUE-123456\n");
+put("tracked.js", "const a = 1;\n");
+put(".env~", "EDITOR-BACKUP-SECRET-123\n");
+fs.writeFileSync(path.join(base, "outside-secret.txt"), "OUTSIDE-SECRET-CONTENT");
+// a second name (hard link) of a file OUTSIDE the workspace: refused by default (F3-07b), whatever its name
+let hardLinked = true;
+try { fs.linkSync(path.join(base, "outside-secret.txt"), path.join(ROOT, "hard.txt")); } catch { hardLinked = false; }
+git("init", "-q", "-b", "main"); git("add", "-f", "-A"); git("commit", "-q", "-m", "init");
+put("tracked.js", `const a = 2;\nconst t = "${GH}";\n`);
+
+const signing = resolveSigningConfig({
+    LOCAL_AGENT_SIGNATURE_MODE: MODE, LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `${KEY_ID}=${PUBLIC_KEY}`, LOCAL_AGENT_TENANT_ID: TENANT,
+}, { defaultFile: null, fileCfg: {} });
+
+const env = { ...process.env, LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_PROTOCOL_V2: "true" };
+const link = await buildV2Link({
+    tenantId: TENANT, agentId: AGENT, signing, getWorkspaceRoot: () => ROOT, env,
+    wsManager: { list: () => [{ id: "ws-1", root: ROOT, tenantId: TENANT }] },
+    log: { info: () => {}, log: () => {}, warn: (m) => out({ evt: "warn", m }) },
+});
+const session = link.session;
+session.on("ready", (i) => out({ evt: "ready", resumed: i.resumed, sessionId: i.sessionId }));
+session.on("refused", (c) => out({ evt: "refused", code: c }));
+session.on("peer-error", (c) => out({ evt: "peer-error", code: c }));
+
+const mint = (kind, rel) => link.content.mintRef({ workspaceId: "ws-1", kind, rel })?.id ?? null;
+const refs = {
+    app: mint("file", "src/app.txt"), big: mint("file", "big.txt"), mid: mint("file", "mid.txt"), swapped: mint("file", "swapped.txt"),
+    bin: mint("file", "bin.png"), envFile: mint("file", ".env"), envBackup: mint("file", ".env~"), diffFile: mint("diff", "tracked.js"),
+    hard: hardLinked ? mint("file", "hard.txt") : null,
+};
+// after the id was handed out the file becomes a link to a file OUTSIDE the workspace
+fs.rmSync(path.join(ROOT, "swapped.txt"));
+fs.symlinkSync(path.join(base, "outside-secret.txt"), path.join(ROOT, "swapped.txt"));
+out({ evt: "refs", hardLinked, refs, bigSha256: crypto.createHash("sha256").update(bigText).digest("hex"), bigBytes: bigText.length, ghp: GH });
+
+let ws;
+let quitting = false;
+function connect() {
+    ws = new WebSocket(GW_URL, { headers: { Authorization: `Bearer ${TOKEN}` } });
+    const mine = ws;
+    ws.on("open", () => {
+        const legacy = () => { out({ evt: "legacy-register" }); mine.send(JSON.stringify({ type: "register", tenantId: TENANT, port: 5055, workspacePath: null })); };
+        if (!link.begin(mine, legacy)) legacy();
+        const hb = setInterval(() => { if (mine.readyState === 1) mine.send("ping"); else clearInterval(hb); }, 5000);
+    });
+    ws.on("message", (data, isBinary) => {
+        const text = data.toString();
+        if (text === "pong") return;
+        if (link.handleMessage(mine, text, isBinary)) return;
+        out({ evt: "v1-message" });
+    });
+    ws.on("close", (code) => { out({ evt: "closed", code }); link.onClose(mine); if (!quitting) setTimeout(connect, 100); });
+    ws.on("error", () => {});
+}
+connect();
+
+const done = () => { quitting = true; try { ws.terminate(); } catch { /* gone */ } link.close(); fs.rmSync(base, { recursive: true, force: true }); process.exit(0); };
+readline.createInterface({ input: process.stdin }).on("line", (l) => {
+    if (l.trim() === "stats") out({ evt: "stats", index: { ...link.content.indexer.stats }, announced: link.content.indexer.announcedCount, pending: link.content.indexer.pending });
+    if (l.trim() === "quit") done();
+}).on("close", done);