@checkstack/satellite-backend 0.4.0 → 0.5.0

package/src/run-secret-resolver.ts

@@ -0,0 +1,66 @@
+import { secretEnvMappingSchema } from "@checkstack/secrets-common";
+import type { SecretResolverService } from "@checkstack/secrets-backend";
+import type { SatelliteAssignment } from "@checkstack/satellite-common";
+
+/**
+ * Resolve a satellite collector run's secrets just-in-time.
+ *
+ * Security model (least-privilege, decision 5): the satellite asks by
+ * `configId` + `collectorId` only. Core reads the `secretEnv` mapping from
+ * the satellite's OWN persisted assignment for that collector — the
+ * satellite does not get to choose which secrets — and resolves ONLY those
+ * refs via the central resolver. So a compromised satellite cannot request
+ * arbitrary secrets; it can only obtain what its assignment already
+ * declares it needs.
+ *
+ * Returns the resolved env map. Throws a clear error when the collector
+ * isn't in the satellite's assignments, when the collector declares no
+ * `secretEnv` (nothing to resolve — caller should not have asked), or when
+ * a referenced secret can't be resolved. The values are never persisted.
+ */
+export async function resolveSatelliteRunSecrets({
+  satelliteId,
+  configId,
+  collectorId,
+  getAssignmentsForSatellite,
+  resolver,
+}: {
+  satelliteId: string;
+  configId: string;
+  collectorId: string;
+  getAssignmentsForSatellite: (
+    satelliteId: string,
+  ) => Promise<SatelliteAssignment[]>;
+  resolver: SecretResolverService;
+}): Promise<Record<string, string>> {
+  const assignments = await getAssignmentsForSatellite(satelliteId);
+  const assignment = assignments.find((a) => a.configId === configId);
+  if (!assignment) {
+    throw new Error(
+      `No assignment "${configId}" for this satellite; cannot deliver secrets.`,
+    );
+  }
+
+  const collector = (assignment.collectors ?? []).find(
+    (c) => c.id === collectorId || c.collectorId === collectorId,
+  );
+  if (!collector) {
+    throw new Error(
+      `Collector "${collectorId}" not found in assignment "${configId}".`,
+    );
+  }
+
+  // The declared mapping lives inside the collector's config. Validate it so
+  // a malformed config can't smuggle non-template values through.
+  const parsed = secretEnvMappingSchema.safeParse(
+    (collector.config as { secretEnv?: unknown }).secretEnv,
+  );
+  if (!parsed.success || Object.keys(parsed.data).length === 0) {
+    throw new Error(
+      `Collector "${collectorId}" declares no secretEnv; nothing to resolve.`,
+    );
+  }
+
+  const { env } = await resolver.resolveForRun({ secretEnv: parsed.data });
+  return env;
+}

package/src/satellite-ws-handler.test.ts

@@ -2,10 +2,12 @@ import { describe, it, expect, mock, beforeEach } from "bun:test";
 import {
   SatelliteWsHandler,
   type SatelliteResultHandler,
+  type SatelliteScriptPackageSink,
 } from "./satellite-ws-handler";
 import { createMockLogger } from "@checkstack/test-utils-backend";
 import type { SatelliteService } from "./service";
 import type { ConfigRelay } from "./config-relay";
+import type { SatelliteConnectionEvent } from "./entity";
 import type { SatelliteWithStatus } from "@checkstack/satellite-common";
 
 const MOCK_SATELLITE: SatelliteWithStatus = {
@@ -262,4 +264,269 @@ describe("SatelliteWsHandler", () => {
       await handler.pushConfigUpdate("non-existent");
     });
   });
+
+  describe("script-package distribution", () => {
+    function makeSink(
+      lockfileHash: string | null,
+    ): {
+      sink: SatelliteScriptPackageSink;
+      reports: Parameters<SatelliteScriptPackageSink["reportSyncState"]>[0][];
+    } {
+      const reports: Parameters<
+        SatelliteScriptPackageSink["reportSyncState"]
+      >[0][] = [];
+      return {
+        reports,
+        sink: {
+          getDesiredLockfileHash: mock(async () => lockfileHash),
+          reportSyncState: mock(async (input) => {
+            reports.push(input);
+          }),
+          getManifest: mock(async () => [
+            { name: "leftpad", version: "0.0.1", integrity: "sha-1" },
+          ]),
+          getBlobBase64: mock(async () => "YmxvYg=="),
+        },
+      };
+    }
+
+    async function authedHandlerWithSink(lockfileHash: string | null) {
+      const { sink, reports } = makeSink(lockfileHash);
+      const h = new SatelliteWsHandler(
+        service,
+        configRelay,
+        resultHandler,
+        logger,
+        undefined,
+        sink,
+      );
+      const ws = createMockWs();
+      const { onMessage } = h.onConnection(ws);
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_valid-token",
+        }),
+      );
+      return { h, ws, onMessage, reports };
+    }
+
+    it("carries the desired lockfile hash in the authenticated payload", async () => {
+      const { ws } = await authedHandlerWithSink("hash-123");
+      const auth = JSON.parse(ws.messages[0]);
+      expect(auth.type).toBe("authenticated");
+      expect(auth.scriptPackagesLockfileHash).toBe("hash-123");
+    });
+
+    it("omits the hash entirely when no sink is wired (version-skew safe)", async () => {
+      // Default `handler` has no script-package sink.
+      const ws = createMockWs();
+      const { onMessage } = handler.onConnection(ws);
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_valid-token",
+        }),
+      );
+      const auth = JSON.parse(ws.messages[0]);
+      expect("scriptPackagesLockfileHash" in auth).toBe(false);
+    });
+
+    it("fans refresh_script_packages out to every connected satellite", async () => {
+      const { h, ws } = await authedHandlerWithSink("hash-123");
+      ws.messages.length = 0;
+
+      h.pushRefreshScriptPackagesToAll("hash-456");
+
+      expect(ws.messages).toHaveLength(1);
+      const msg = JSON.parse(ws.messages[0]);
+      expect(msg.type).toBe("refresh_script_packages");
+      expect(msg.lockfileHash).toBe("hash-456");
+    });
+
+    it("persists a satellite's reported sync state", async () => {
+      const { onMessage, reports } = await authedHandlerWithSink("hash-123");
+      await onMessage(
+        JSON.stringify({
+          type: "script_package_sync_state",
+          lockfileHash: "hash-123",
+          status: "ready",
+        }),
+      );
+      expect(reports).toHaveLength(1);
+      expect(reports[0]).toMatchObject({
+        satelliteId: "sat-1",
+        lockfileHash: "hash-123",
+        status: "ready",
+      });
+    });
+
+    it("answers a manifest request over the WS channel", async () => {
+      const { ws, onMessage } = await authedHandlerWithSink("hash-123");
+      ws.messages.length = 0;
+      await onMessage(
+        JSON.stringify({
+          type: "request_script_package_manifest",
+          lockfileHash: "hash-123",
+        }),
+      );
+      const reply = JSON.parse(ws.messages[0]);
+      expect(reply.type).toBe("script_package_manifest");
+      expect(reply.entries[0].name).toBe("leftpad");
+    });
+
+    it("answers a blob request over the WS channel", async () => {
+      const { ws, onMessage } = await authedHandlerWithSink("hash-123");
+      ws.messages.length = 0;
+      await onMessage(
+        JSON.stringify({
+          type: "request_script_package_blob",
+          integrity: "sha-1",
+        }),
+      );
+      const reply = JSON.parse(ws.messages[0]);
+      expect(reply.type).toBe("script_package_blob");
+      expect(reply.data).toBe("YmxvYg==");
+    });
+  });
+
+  describe("connection-state entity mirror", () => {
+    function makeEntitySink() {
+      const mirrors: Array<{
+        satelliteId: string;
+        lastEvent: SatelliteConnectionEvent;
+        lastHeartbeatAt: Date | null;
+      }> = [];
+      return {
+        sink: {
+          mirror: mock(
+            async (input: {
+              satelliteId: string;
+              lastEvent: SatelliteConnectionEvent;
+              lastHeartbeatAt: Date | null;
+            }) => {
+              mirrors.push(input);
+            },
+          ),
+        },
+        mirrors,
+      };
+    }
+
+    it("drives the connected edge with lastHeartbeatAt=now on successful authentication", async () => {
+      const { sink, mirrors } = makeEntitySink();
+      const h = new SatelliteWsHandler(
+        service,
+        configRelay,
+        resultHandler,
+        logger,
+        sink,
+      );
+      const ws = createMockWs();
+      const { onMessage } = h.onConnection(ws);
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_valid-token",
+        }),
+      );
+
+      expect(mirrors).toHaveLength(1);
+      expect(mirrors[0]!.satelliteId).toBe("sat-1");
+      expect(mirrors[0]!.lastEvent).toBe("connected");
+      // lastHeartbeatAt = now (non-null) so the computed status reads online.
+      expect(mirrors[0]!.lastHeartbeatAt).toBeInstanceOf(Date);
+    });
+
+    it("does NOT also call updateHeartbeat on connect when a sink is wired (the mirror writes the heartbeat)", async () => {
+      const { sink } = makeEntitySink();
+      const h = new SatelliteWsHandler(
+        service,
+        configRelay,
+        resultHandler,
+        logger,
+        sink,
+      );
+      const ws = createMockWs();
+      const { onMessage } = h.onConnection(ws);
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_valid-token",
+        }),
+      );
+      // The connect-time heartbeat is written by the mirror's apply, not by a
+      // separate updateHeartbeat call.
+      expect(service.updateHeartbeat).not.toHaveBeenCalled();
+    });
+
+    it("writes the connect heartbeat directly when NO sink is wired", async () => {
+      // The default `handler` has no sink: it must still record the heartbeat.
+      const ws = createMockWs();
+      const { onMessage } = handler.onConnection(ws);
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_valid-token",
+        }),
+      );
+      expect(service.updateHeartbeat).toHaveBeenCalledWith("sat-1", {});
+    });
+
+    it("drives the disconnected edge with lastHeartbeatAt=null (immediate offline) when the socket closes", async () => {
+      const { sink, mirrors } = makeEntitySink();
+      const h = new SatelliteWsHandler(
+        service,
+        configRelay,
+        resultHandler,
+        logger,
+        sink,
+      );
+      const ws = createMockWs();
+      const { onMessage, onClose } = h.onConnection(ws);
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_valid-token",
+        }),
+      );
+      onClose?.();
+      // onClose fires the mirror fire-and-forget; flush the microtask queue.
+      await Promise.resolve();
+      await Promise.resolve();
+
+      const disconnected = mirrors.find((m) => m.lastEvent === "disconnected");
+      expect(disconnected).toBeDefined();
+      // Clearing lastHeartbeatAt makes the computed status flip offline at once.
+      expect(disconnected!.lastHeartbeatAt).toBeNull();
+      expect(disconnected!.satelliteId).toBe("sat-1");
+    });
+
+    it("does not mirror on a failed authentication", async () => {
+      const { sink, mirrors } = makeEntitySink();
+      const h = new SatelliteWsHandler(
+        service,
+        configRelay,
+        resultHandler,
+        logger,
+        sink,
+      );
+      const ws = createMockWs();
+      const { onMessage } = h.onConnection(ws);
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_invalid-token",
+        }),
+      );
+      expect(mirrors).toHaveLength(0);
+    });
+  });
 });