deepdebug-local-agent 1.6.0 → 1.8.0

package/tools/interop/LaV2NodeFileListE2ETest.java

@@ -0,0 +1,369 @@
+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-07c end to end, WITHOUT any patch on either side: HTTP ({@code POST /api/v1/content/file.list/query} and the id-bearing calls
+ * that follow) -> the REAL {@link ContentRelayController} and {@link ContentRelayService} -> the REAL {@link AgentWebSocketHandler} /
+ * {@link LaV2Session} behind a Reactor Netty WebSocket on loopback, real Ed25519 signer -> the REAL Node Local Agent
+ * (tools/interop/la-interop-list-client.mjs: real content handlers, DLP enforce, path guard). The agent mints NO id by itself here:
+ * every id the test uses came out of a {@code file.list} answer (the producer).
+ *
+ * <p>Copy it next to the other byoc tests of the gateway and run (JDK 21; node >= 18; {@code npm ci} in the LA repo; gateway branch
+ * with the F3-07c contract, i.e. the {@code file.list} kind and the {@code content.file.list} capability gate):
+ * <pre>
+ *   cp tools/interop/LaV2NodeFileListE2ETest.java \
+ *      &lt;gateway&gt;/src/test/java/io/visionhammer/gateway/cloud/infrastructure/byoc/
+ *   LA_REPO=/path/to/deepdebug-local-agent mvn -o test -Dtest=LaV2NodeFileListE2ETest
+ * </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, two gateway instances, load, a tenant of QA/PROD.
+ */
+class LaV2NodeFileListE2ETest {
+
+    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-list-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 fx = await(events, "fixture", 20);
+            await(events, "ready", 15);
+            assertThat(handler.isAgentConnected(TENANT)).isTrue();
+            String ghp = fx.path("ghp").asText();
+            boolean hardLinked = fx.path("hardLinked").asBoolean();
+
+            // 1. the root: names the agent may serve, dirs first; nothing that is a credential, not even its name
+            var rootRes = http.post().uri(BASE + "file.list/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", "root", "workspaceId", "ws-1")).exchange()
+                    .expectStatus().isOk().expectHeader().contentType("application/json").expectHeader().valueEquals("Cache-Control", "no-store")
+                    .expectBody().returnResult();
+            String rootBody = new String(rootRes.getResponseBody(), StandardCharsets.UTF_8);
+            JsonNode root = OM.readTree(rootBody);
+            List<String> names = new ArrayList<>();
+            root.path("entries").forEach(e -> names.add(e.path("name").asText()));
+            assertThat(names).containsExactly("docs", "src", "README.md", "credentials.service.ts", "mid.txt");
+            for (String never : List.of(".env", ".envrc", "credentials.json", "secrets", "id_rsa", "link-out", "link-env", "hard.txt", "SECRET", "outside")) {
+                assertThat(rootBody).as("never in the listing: " + never).doesNotContain(never);
+            }
+            assertThat(rootBody).doesNotContain(ghp);
+            assertThat(root.has("nextRef")).isFalse();
+            Map<String, JsonNode> byName = new java.util.HashMap<>();
+            root.path("entries").forEach(e -> {
+                assertThat(e.path("id").asText()).matches(ID43);
+                assertThat(e.path("type").asText()).isIn("file", "dir");
+                assertThat(e.path("mtime").asText()).matches("^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9:]{8}(\\.[0-9]{1,6})?Z$");
+                byName.put(e.path("name").asText(), e);
+            });
+            assertThat(byName.get("src").path("type").asText()).isEqualTo("dir");
+            assertThat(byName.get("credentials.service.ts").path("size").asInt()).isEqualTo(
+                    "export class CredentialsService { token = 'x'; }\n".getBytes(StandardCharsets.UTF_8).length);
+
+            // 2. content.index: the gateway learned every id the listing minted (a dir as file.list, a file as file), size included
+            String credId = byName.get("credentials.service.ts").path("id").asText();
+            awaitTrue(() -> index.find(TENANT, "ws-1", ContentKind.FILE, credId).isPresent(), 10, "content.index reached the gateway registry");
+            for (String n : List.of("README.md", "credentials.service.ts", "mid.txt")) {
+                assertThat(index.find(TENANT, "ws-1", ContentKind.FILE, byName.get(n).path("id").asText())).as("announced " + n).isPresent();
+            }
+            assertThat(index.find(TENANT, "ws-1", ContentKind.FILE_LIST, byName.get("src").path("id").asText())).as("a folder id is a file.list id").isPresent();
+            assertThat(index.find(TENANT, "ws-1", ContentKind.FILE, byName.get("src").path("id").asText())).isEmpty();
+            assertThat(index.find(TENANT, "ws-1", ContentKind.FILE, credId).get().size()).isEqualTo(byName.get("credentials.service.ts").path("size").asLong());
+            assertThat(index.find(UUID.randomUUID().toString(), "ws-1", ContentKind.FILE, credId)).as("other tenant").isEmpty();
+
+            // 3. the ids of the listing open the files (masked) through the normal file route; the code file named credentials.* is served
+            String cred = http.get().uri(BASE + "file/" + credId + "?workspaceId=ws-1").exchange().expectStatus().isOk()
+                    .expectBody(String.class).returnResult().getResponseBody();
+            assertThat(cred).contains("CredentialsService");
+            String readme = new String(http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", byName.get("README.md").path("id").asText(), "workspaceId", "ws-1")).exchange()
+                    .expectStatus().isOk().expectBody().returnResult().getResponseBody(), StandardCharsets.UTF_8);
+            assertThat(readme).contains("# readme").contains("[REDACTED:github_token]").doesNotContain(ghp);
+            String mid = new String(http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", byName.get("mid.txt").path("id").asText(), "workspaceId", "ws-1")).exchange()
+                    .expectStatus().isOk().expectBody().returnResult().getResponseBody(), StandardCharsets.UTF_8);
+            assertThat(mid).contains("[REDACTED:github_token]").doesNotContain(ghp.substring(0, 12));
+
+            // 4. a folder id lists the folder (and GET works as POST); the sub folder named credentials is listable, its code is served
+            String srcId = byName.get("src").path("id").asText();
+            JsonNode src = OM.readTree(http.get().uri(BASE + "file.list/" + srcId + "?workspaceId=ws-1").exchange().expectStatus().isOk()
+                    .expectBody().returnResult().getResponseBody());
+            List<String> srcNames = new ArrayList<>();
+            src.path("entries").forEach(e -> srcNames.add(e.path("name").asText()));
+            assertThat(srcNames).containsExactly("credentials", "main.ts");
+            String credDirId = src.path("entries").get(0).path("id").asText();
+            JsonNode credDir = OM.readTree(http.post().uri(BASE + "file.list/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", credDirId, "workspaceId", "ws-1")).exchange().expectStatus().isOk().expectBody().returnResult().getResponseBody());
+            assertThat(credDir.path("entries").get(0).path("name").asText()).isEqualTo("index.ts");
+
+            // 5. paging: limit 2 over the 5 root entries = 3 pages by nextRef; the pages add up, and the nextRef is an id too
+            List<String> paged = new ArrayList<>();
+            String ref = "root";
+            int pages = 0;
+            while (ref != null && pages < 10) {
+                JsonNode page = OM.readTree(http.post().uri(BASE + "file.list/query").contentType(MediaType.APPLICATION_JSON)
+                        .bodyValue(Map.of("ref", ref, "workspaceId", "ws-1", "limit", 2)).exchange().expectStatus().isOk().expectBody().returnResult().getResponseBody());
+                page.path("entries").forEach(e -> paged.add(e.path("name").asText()));
+                ref = page.has("nextRef") ? page.path("nextRef").asText() : null;
+                if (ref != null) {
+                    assertThat(ref).matches(ID43);
+                }
+                pages++;
+            }
+            assertThat(pages).isEqualTo(3);
+            assertThat(paged).isEqualTo(names);
+
+            // 6. the gateway and the agent refuse what they must: kinds do not mix, a path, a foreign workspace, an id never minted, root for another kind
+            http.post().uri(BASE + "file.list/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", credId, "workspaceId", "ws-1")).exchange().expectStatus().isNotFound();            // a file id is not a folder id
+            http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", srcId, "workspaceId", "ws-1")).exchange().expectStatus().isNotFound();             // a folder id is not a file id
+            http.post().uri(BASE + "file.list/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", "A".repeat(43), "workspaceId", "ws-1")).exchange().expectStatus().isNotFound();
+            http.post().uri(BASE + "file.list/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", srcId, "workspaceId", "ws-of-somebody-else")).exchange().expectStatus().isNotFound();
+            http.post().uri(BASE + "file.list/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", "src", "workspaceId", "ws-1")).exchange().expectStatus().isBadRequest();
+            http.post().uri(BASE + "file.list/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", "../..", "workspaceId", "ws-1")).exchange().expectStatus().isBadRequest();
+            http.post().uri(BASE + "file/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", "root", "workspaceId", "ws-1")).exchange().expectStatus().isBadRequest();
+            http.post().uri(BASE + "file.list/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", "root")).exchange().expectStatus().isBadRequest();                                  // workspaceId is required
+            http.post().uri(BASE + "file.list/query").contentType(MediaType.APPLICATION_JSON)
+                    .bodyValue(Map.of("ref", "root", "workspaceId", "ws-1", "offset", 0, "length", 10)).exchange().expectStatus().isBadRequest();
+
+            // 7. the agent's counters: everything announced was accepted, nothing the agent sent was refused by the real session
+            // (the ids minted by the last requests are announced after a 100 ms batch delay: ask until they are in)
+            JsonNode stats = null;
+            for (int i = 0; i < 40; i++) {
+                send(stdin, "stats");
+                stats = await(events, "stats", 10);
+                if (stats.path("index").path("accepted").asInt() >= 15 && stats.path("pending").asInt() == 0) {
+                    break;
+                }
+                Thread.sleep(100);
+            }
+            assertThat(stats.path("index").path("rejected").asInt()).isZero();
+            // exactly every id the listings handed out: 5 (root) + 2 (src) + 1 (src/credentials) + 5 entries and 2 continuation ids of the 3 pages
+            assertThat(stats.path("index").path("accepted").asInt()).isEqualTo(15);
+            assertThat(rejected).as("frames the real LaV2Session rejected: %s", rejected).isEmpty();
+            // nothing in what the agent printed (events, warnings) carries content, a name or a path of the workspace
+            String printed = String.join("\n", transcript.stream().filter(l -> !l.contains("\"evt\":\"fixture\"")).toList());
+            for (String leak : List.of("OUTSIDE-SECRET", "SECRET-ENV", "credentials.service", "README", "f307c-list-", "mid.txt", "src")) {
+                assertThat(printed).as("agent output: " + leak).doesNotContain(leak);
+            }
+            System.out.println("FILE LIST E2E OK: hardLinked=" + hardLinked + " index accepted=" + 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

@@ -36,3 +36,19 @@ boundary never appears, whole or in part; an id swapped for a link to a file out
 `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.
+
+## F3-07c: `file.list`, the producer of the ids, against the real gateway
+
+`la-interop-list-client.mjs` is a Local Agent with the REAL content handlers that mints NO id itself (the only source of ids is the
+`file.list` handler); `LaV2NodeFileListE2ETest.java` drives it from HTTP: `POST /api/v1/content/file.list/query` -> controller ->
+`LaV2Session` -> Node. Needs the gateway branch with the `file.list` kind and the `content.file.list` capability gate.
+
+```bash
+cp tools/interop/LaV2NodeFileListE2ETest.java <gateway>/src/test/java/io/visionhammer/gateway/cloud/infrastructure/byoc/
+LA_REPO=/path/to/deepdebug-local-agent mvn -o test -Dtest=LaV2NodeFileListE2ETest   # JDK 21
+```
+
+It checks: the root lists `credentials.service.ts` (code) and not `.env`, `.envrc`, `credentials.json`, `secrets/`, `id_rsa`, a link out of the
+workspace, a link to `.env`, a hard link (nor their names); the ids of the listing open the files (token masked, also across a 32 KiB
+boundary); folder ids list folders; paging by `nextRef`; kinds do not mix; the gateway registry learned every id (dirs as `file.list`, files as
+`file`, size included) and the agent announced exactly the ids it handed out; no name or path in the agent's output or the gateway's logs.

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

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// F3-07c interoperability client: the REAL Local Agent content handlers around the real v2 link, against the real gateway (driven by
+// LaV2NodeFileListE2ETest: HTTP -> ContentRelayController -> LaV2Session -> this client). Unlike the F3-07b client it does NOT mint any
+// id itself: the only source of ids is the `file.list` handler (the producer), exactly as in production. Nothing is faked on the agent
+// side except the workspace manager (one temp workspace). It prepares a folder with files that may and may not be listed (.env,
+// credentials.json, credentials.service.ts, links, a hard link, a secret in the middle of a file) and prints facts, one JSON per line.
+//
+//   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(), "f307c-list-"));
+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); };
+
+export const GH = "ghp_" + "A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8";
+// a secret in the middle of a file that straddles two 32 KiB chunks, as in the F3-07b client
+const straddle = "a".repeat(32766 - 20 - 1) + "\n" + `k=${GH}\n` + "z\n".repeat(60000);
+
+put("README.md", `# readme\ntoken = "${GH}"\nend\n`);
+put("mid.txt", straddle);
+put("credentials.service.ts", "export class CredentialsService { token = 'x'; }\n");
+put("src/main.ts", "export {};\n");
+put("src/credentials/index.ts", "export {};\n");
+put("docs/guide.md", "# guide\n");
+// what must never be listed, nor named
+put(".env", "API=SECRET-ENV-VALUE-123456\n");
+put(".envrc", "export API=SECRET-ENVRC-VALUE-123\n");
+put("credentials.json", '{"token":"SECRET-CREDENTIALS-JSON-123"}');
+put("secrets/api.txt", "SECRET-IN-SECRETS-DIR");
+put("id_rsa", "SECRET-PRIVATE-KEY");
+fs.writeFileSync(path.join(base, "outside-secret.txt"), "OUTSIDE-SECRET-CONTENT");
+fs.symlinkSync(path.join(base, "outside-secret.txt"), path.join(ROOT, "link-out.txt"));
+fs.symlinkSync(path.join(ROOT, ".env"), path.join(ROOT, "link-env.txt"));
+let hardLinked = true;
+try { fs.linkSync(path.join(base, "outside-secret.txt"), path.join(ROOT, "hard.txt")); } catch { hardLinked = false; }
+
+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 }));
+
+out({ evt: "fixture", hardLinked, ghp: GH, root: ROOT, base });
+
+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);