deepdebug-local-agent 1.5.0 → 1.7.0

package/tools/interop/LaV2NodeContentInteropTest.java

@@ -8,6 +8,8 @@ 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.ContentIndexRegistry;
+import io.visionhammer.gateway.cloud.application.content.ContentRelayProperties;
 import io.visionhammer.gateway.governance.application.DataPlanePolicy;
 import io.visionhammer.gateway.identity.application.AgentAuthorizationEntity;
 import io.visionhammer.gateway.identity.application.AgentAuthorizationStore;
@@ -56,7 +58,8 @@ import static org.mockito.Mockito.when;
  *
  *   LA_REPO=/path/to/deepdebug-local-agent mvn -o test -Dtest=LaV2NodeContentInteropTest
  *
- * Skipped when LA_REPO is not set. Not proven here: Cloud Run / LB / TLS, Memorystore, two gateway instances, the HTTP
+ * Skipped when LA_REPO is not set. LA_DLP_MODE=off is the negative control: the agent then registers NO content handler
+ * (F3-07b) and the test fails at the first request. Not proven here: Cloud Run / LB / TLS, Memorystore, two gateway instances, the HTTP
  * relay endpoint (F3-06) in front of this session.
  */
 class LaV2NodeContentInteropTest {
@@ -82,7 +85,12 @@ class LaV2NodeContentInteropTest {
         };
         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));
+        // F3-07b: the agent announces its ids with content.index; the gateway keeps them in this registry (without a sink it would answer
+        // `rejected protocol_unsupported`, which the metrics below count)
+        ContentRelayProperties relayProps = new ContentRelayProperties();
+        relayProps.setEnabled(true);
+        ContentIndexRegistry index = new ContentIndexRegistry(relayProps, null, System::currentTimeMillis);
+        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 workspaces = mock(WorkspaceRepository.class);
@@ -106,7 +114,8 @@ class LaV2NodeContentInteropTest {
         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", "enforce"));
+                "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<>();
@@ -137,6 +146,11 @@ class LaV2NodeContentInteropTest {
             JsonNode refs = refsEvt.path("refs");
             String ghp = refsEvt.path("ghp").asText();
             assertThat(refs.path("envFile").isNull()).as("no id is minted for .env").isTrue();
+            assertThat(refs.path("envBackup").isNull()).as("no id is minted for .env~ (F3-07b)").isTrue();
+            // F3-07b: the ids are the 43-char base64url ones the gateway requires
+            for (String k : List.of("app", "big", "mid", "swapped", "bin", "diffFile")) {
+                assertThat(refs.path(k).asText()).as(k).matches("^[A-Za-z0-9_-]{43}$");
+            }
 
             // 1. a file with a token: served, the token masked (DLP enforce), the rest intact
             List<LaV2Chunk> app = content("file", refs.path("app").asText(), handler);
@@ -167,7 +181,7 @@ class LaV2NodeContentInteropTest {
             assertThat(swapped.get(0).data()).isEmpty();
 
             // 5. paths are never ids: traversal, absolute, plain relative -> not_found; nothing else comes back
-            for (String ref : List.of("../../etc/passwd", "/etc/passwd", "src/app.txt", "..%2f..%2fetc%2fpasswd", "cr1_AAAAAAAAAAAAAAAAAAAAAA")) {
+            for (String ref : List.of("../../etc/passwd", "/etc/passwd", "src/app.txt", "..%2f..%2fetc%2fpasswd", "cr1_AAAAAAAAAAAAAAAAAAAAAA", "A".repeat(43))) {
                 List<LaV2Chunk> r = content("file", ref, handler);
                 assertThat(r).hasSize(1);
                 assertThat(r.get(0).status()).as(ref).isEqualTo("not_found");

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);
+    }
+}