@checkstack/satellite-common 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @checkstack/satellite-common
 
+## 0.7.0
+
+### Minor Changes
+
+- 270ef29: Extend the satellite protocol for script-package distribution: the
+  `authenticated` / `config_updated` payloads now carry an optional
+  `scriptPackagesLockfileHash` (the durable convergence backstop), a new
+  `refresh_script_packages { lockfileHash }` core->satellite control push,
+  and a new `script_package_sync_state` satellite->core report message. All
+  additions are optional / additive, so existing satellites and protocol
+  tests are unaffected.
+- 270ef29: Satellite-side script-package reconciliation over the WS channel.
+
+  - `satellite-common`: WS request/reply messages for pulling the manifest +
+    blobs from core (`request_script_package_manifest` /
+    `request_script_package_blob` -> `script_package_manifest` /
+    `script_package_blob`).
+  - `satellite-backend`: the WS handler answers those requests from the
+    script-packages store (satellites pull from core, never the registry).
+  - `@checkstack/satellite`: the client gains request/reply plumbing + a
+    `SatelliteScriptPackages` manager that reuses the Phase 2 reconciler
+    (`reconcileToHash` + `createReconcileFsDeps`) over the WS transport. It
+    reconciles on a `refresh_script_packages` push and on the
+    assignment-carried hash (startup / reconnect backstop), pulls only missing
+    blobs (delta), materializes via `bun install --offline`, atomically flips
+    `current`, reports sync state back, and degrades cleanly (error state, no
+    stale tree, no registry access) when a blob can't be fetched. Reconciles
+    are serialized + coalesced + idempotent.
+
+- 270ef29: Secrets platform Phase 3: just-in-time secret delivery to satellites + source-side masking, and central-execution injection for healthcheck collectors.
+
+  - New satellite WS messages `request_run_secrets` / `run_secrets`: just
+    before a satellite runs a collector that declares a `secretEnv`, it asks
+    core for that collector's resolved env; core resolves ONLY the secrets the
+    collector's OWN persisted assignment declares (least-privilege — the
+    satellite cannot choose) and replies with the env map (or a clear error).
+    The satellite injects it memory-only for the run and drops it on
+    completion. Secrets never ride the persisted assignment and never touch
+    disk.
+  - Source-side masking: the satellite runs `maskSecrets` over the collector's
+    stdout/stderr/result/error using the run's delivered values BEFORE the
+    result leaves the satellite (defense in depth).
+  - `CollectorStrategy.execute` gains an optional `secretEnv`. The
+    inline-script and shell collectors inject it into the runner
+    (`process.env` / `$VAR`) and mask the values out of their output.
+  - Healthcheck collectors running centrally (the queue executor) also resolve
+    - inject `secretEnv` via `secretResolverRef`, closing the gap where a
+      centrally-run secretEnv collector got no secrets. A missing required
+      secret fails the run clearly in all paths.
+
+### Patch Changes
+
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+  - @checkstack/healthcheck-common@1.4.0
+
 ## 0.6.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/satellite-common",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -9,16 +9,16 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.11.0",
-    "@checkstack/healthcheck-common": "1.2.0",
-    "@checkstack/signal-common": "0.2.4",
+    "@checkstack/common": "0.12.0",
+    "@checkstack/healthcheck-common": "1.3.0",
+    "@checkstack/signal-common": "0.2.5",
     "@orpc/contract": "^1.13.14",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "typescript": "^5.7.2",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.3"
+    "@checkstack/scripts": "0.3.4"
   },
   "scripts": {
     "typecheck": "tsgo -b",

package/src/index.ts

@@ -29,6 +29,14 @@ export {
   type AuthFailedMessage,
   type ConfigUpdatedMessage,
   type ShutdownMessage,
+  type ScriptPackageSyncStateMessage,
+  type RefreshScriptPackagesMessage,
+  type ScriptPackageManifestMessage,
+  type ScriptPackageBlobMessage,
+  type RequestScriptPackageManifestMessage,
+  type RequestScriptPackageBlobMessage,
+  type RequestRunSecretsMessage,
+  type RunSecretsMessage,
 } from "./protocol";
 export {
   SATELLITE_STATUS_CHANGED,

package/src/protocol.test.ts

@@ -1,5 +1,9 @@
 import { describe, test, expect } from "bun:test";
-import { SatelliteAssignmentSchema } from "./protocol";
+import {
+  SatelliteAssignmentSchema,
+  CoreToSatelliteMessageSchema,
+  SatelliteToCoreMessageSchema,
+} from "./protocol";
 
 describe("SatelliteAssignmentSchema", () => {
   const base = {
@@ -28,3 +32,119 @@ describe("SatelliteAssignmentSchema", () => {
     expect(parsed.systemName).toBeUndefined();
   });
 });
+
+describe("script-packages protocol extensions", () => {
+  test("authenticated carries an optional scriptPackagesLockfileHash", () => {
+    const withHash = CoreToSatelliteMessageSchema.parse({
+      type: "authenticated",
+      satelliteId: "sat-1",
+      assignments: [],
+      scriptPackagesLockfileHash: "abc123",
+    });
+    expect(withHash.type).toBe("authenticated");
+    if (withHash.type === "authenticated") {
+      expect(withHash.scriptPackagesLockfileHash).toBe("abc123");
+    }
+  });
+
+  test("authenticated WITHOUT the hash still parses (version-skew safe)", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "authenticated",
+      satelliteId: "sat-1",
+      assignments: [],
+    });
+    expect(parsed.type).toBe("authenticated");
+    if (parsed.type === "authenticated") {
+      expect(parsed.scriptPackagesLockfileHash).toBeUndefined();
+    }
+  });
+
+  test("config_updated carries the optional hash", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "config_updated",
+      assignments: [],
+      scriptPackagesLockfileHash: null,
+    });
+    if (parsed.type === "config_updated") {
+      expect(parsed.scriptPackagesLockfileHash).toBeNull();
+    }
+  });
+
+  test("refresh_script_packages round-trips", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "refresh_script_packages",
+      lockfileHash: "deadbeef",
+    });
+    expect(parsed.type).toBe("refresh_script_packages");
+    if (parsed.type === "refresh_script_packages") {
+      expect(parsed.lockfileHash).toBe("deadbeef");
+    }
+  });
+
+  test("script_package_sync_state round-trips (satellite -> core)", () => {
+    const parsed = SatelliteToCoreMessageSchema.parse({
+      type: "script_package_sync_state",
+      lockfileHash: "abc",
+      status: "ready",
+    });
+    expect(parsed.type).toBe("script_package_sync_state");
+    if (parsed.type === "script_package_sync_state") {
+      expect(parsed.status).toBe("ready");
+      expect(parsed.lockfileHash).toBe("abc");
+    }
+  });
+
+  test("script_package_sync_state carries an error", () => {
+    const parsed = SatelliteToCoreMessageSchema.parse({
+      type: "script_package_sync_state",
+      lockfileHash: null,
+      status: "error",
+      errorMessage: "blob fetch failed",
+    });
+    if (parsed.type === "script_package_sync_state") {
+      expect(parsed.status).toBe("error");
+      expect(parsed.errorMessage).toBe("blob fetch failed");
+    }
+  });
+});
+
+describe("run-secrets request/reply (Phase 3 JIT delivery)", () => {
+  test("parses request_run_secrets", () => {
+    const parsed = SatelliteToCoreMessageSchema.parse({
+      type: "request_run_secrets",
+      requestId: "req-1",
+      configId: "config-1",
+      collectorId: "inline-script",
+      runId: "run-1",
+    });
+    expect(parsed.type).toBe("request_run_secrets");
+    if (parsed.type === "request_run_secrets") {
+      expect(parsed.requestId).toBe("req-1");
+      expect(parsed.collectorId).toBe("inline-script");
+    }
+  });
+
+  test("parses run_secrets reply with env", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "run_secrets",
+      requestId: "req-1",
+      env: { API_TOKEN: "resolved-value" },
+    });
+    if (parsed.type === "run_secrets") {
+      expect(parsed.env).toEqual({ API_TOKEN: "resolved-value" });
+      expect(parsed.error).toBeUndefined();
+    }
+  });
+
+  test("parses run_secrets reply with error (no env)", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "run_secrets",
+      requestId: "req-1",
+      error: "required secret not available",
+    });
+    if (parsed.type === "run_secrets") {
+      expect(parsed.error).toBe("required secret not available");
+      expect(parsed.env).toBeUndefined();
+    }
+  });
+});

package/src/protocol.ts

@@ -78,6 +78,64 @@ const StrategyErrorMessageSchema = z.object({
   message: z.string(),
 });
 
+/**
+ * Reports the satellite's script-package reconcile state back to the core,
+ * which persists it in `script_package_satellite_state` for the admin UI.
+ * Sent after a reconcile attempt (success or failure).
+ */
+const ScriptPackageSyncStateMessageSchema = z.object({
+  type: z.literal("script_package_sync_state"),
+  /** Active lockfile hash this satellite has materialized, or null. */
+  lockfileHash: z.string().nullable(),
+  /** "pending" | "syncing" | "ready" | "error" */
+  status: z.enum(["pending", "syncing", "ready", "error"]),
+  errorMessage: z.string().optional(),
+});
+
+/**
+ * Satellite -> core request for the manifest of a lockfile hash, so the
+ * satellite can diff against its local cache. The core replies with a
+ * `script_package_manifest` message. Delivered over the existing
+ * authenticated WS channel (no separate satellite HTTP auth surface).
+ */
+const RequestScriptPackageManifestMessageSchema = z.object({
+  type: z.literal("request_script_package_manifest"),
+  lockfileHash: z.string(),
+});
+
+/**
+ * Satellite -> core request for one content-addressed blob by integrity.
+ * The core replies with a `script_package_blob` message (base64 bytes).
+ */
+const RequestScriptPackageBlobMessageSchema = z.object({
+  type: z.literal("request_script_package_blob"),
+  integrity: z.string(),
+});
+
+/**
+ * Satellite -> core just-in-time request for a collector run's resolved
+ * secret env, sent right before the satellite executes a collector that
+ * declares a `secretEnv` mapping. The core resolves ONLY that collector's
+ * declared `secretEnv` (read from the persisted assignment — the satellite
+ * does not get to choose which secrets), and replies with a `run_secrets`
+ * message carrying the env map (or an error).
+ *
+ * Secrets NEVER ride the persisted assignment payload; they are delivered
+ * over this authenticated channel per-run and held in satellite memory only
+ * for the lifetime of the run. `requestId` correlates the reply (a config
+ * can run repeatedly; `runId` is for logging/audit).
+ */
+const RequestRunSecretsMessageSchema = z.object({
+  type: z.literal("request_run_secrets"),
+  /** Correlation id for the reply. */
+  requestId: z.string(),
+  /** The assignment/collector whose declared secretEnv to resolve. */
+  configId: z.string(),
+  collectorId: z.string(),
+  /** Opaque per-run id for audit/logging on the core side. */
+  runId: z.string(),
+});
+
 /**
  * Discriminated union of all messages that a satellite can send to the core.
  */
@@ -86,6 +144,10 @@ export const SatelliteToCoreMessageSchema = z.discriminatedUnion("type", [
   HeartbeatMessageSchema,
   ResultMessageSchema,
   StrategyErrorMessageSchema,
+  ScriptPackageSyncStateMessageSchema,
+  RequestScriptPackageManifestMessageSchema,
+  RequestScriptPackageBlobMessageSchema,
+  RequestRunSecretsMessageSchema,
 ]);
 
 export type SatelliteToCoreMessage = z.infer<
@@ -97,6 +159,18 @@ export type AuthenticateMessage = z.infer<typeof AuthenticateMessageSchema>;
 export type HeartbeatMessage = z.infer<typeof HeartbeatMessageSchema>;
 export type ResultMessage = z.infer<typeof ResultMessageSchema>;
 export type StrategyErrorMessage = z.infer<typeof StrategyErrorMessageSchema>;
+export type ScriptPackageSyncStateMessage = z.infer<
+  typeof ScriptPackageSyncStateMessageSchema
+>;
+export type RequestScriptPackageManifestMessage = z.infer<
+  typeof RequestScriptPackageManifestMessageSchema
+>;
+export type RequestScriptPackageBlobMessage = z.infer<
+  typeof RequestScriptPackageBlobMessageSchema
+>;
+export type RequestRunSecretsMessage = z.infer<
+  typeof RequestRunSecretsMessageSchema
+>;
 
 // =============================================================================
 // CORE → SATELLITE MESSAGES
@@ -106,6 +180,13 @@ const AuthenticatedMessageSchema = z.object({
   type: z.literal("authenticated"),
   satelliteId: z.string(),
   assignments: z.array(SatelliteAssignmentSchema),
+  /**
+   * Desired script-package lockfile hash. Carried alongside assignments as
+   * the durable convergence backstop: a satellite that booted after (or
+   * missed) a `refresh_script_packages` push still converges on connect.
+   * Optional for version-skew safety; null means "no packages installed".
+   */
+  scriptPackagesLockfileHash: z.string().nullable().optional(),
 });
 
 const AuthFailedMessageSchema = z.object({
@@ -116,6 +197,8 @@ const AuthFailedMessageSchema = z.object({
 const ConfigUpdatedMessageSchema = z.object({
   type: z.literal("config_updated"),
   assignments: z.array(SatelliteAssignmentSchema),
+  /** See {@link AuthenticatedMessageSchema.scriptPackagesLockfileHash}. */
+  scriptPackagesLockfileHash: z.string().nullable().optional(),
 });
 
 const ShutdownMessageSchema = z.object({
@@ -123,6 +206,60 @@ const ShutdownMessageSchema = z.object({
   reason: z.string(),
 });
 
+/**
+ * Control push telling the satellite to reconcile its script packages to a
+ * new lockfile hash. Sent by each core instance's `script-packages.changed`
+ * broadcast handler to its currently-connected satellites. Best-effort
+ * liveness; the assignment-carried `scriptPackagesLockfileHash` is the
+ * durable backstop.
+ */
+const RefreshScriptPackagesMessageSchema = z.object({
+  type: z.literal("refresh_script_packages"),
+  lockfileHash: z.string(),
+});
+
+/** One resolved package in a manifest reply. */
+const ManifestEntryWireSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  integrity: z.string(),
+});
+
+/** Core reply to `request_script_package_manifest`. */
+const ScriptPackageManifestMessageSchema = z.object({
+  type: z.literal("script_package_manifest"),
+  lockfileHash: z.string(),
+  entries: z.array(ManifestEntryWireSchema),
+});
+
+/** Core reply to `request_script_package_blob` (base64 compressed bytes). */
+const ScriptPackageBlobMessageSchema = z.object({
+  type: z.literal("script_package_blob"),
+  integrity: z.string(),
+  /** base64-encoded compressed blob bytes, or null if not found. */
+  data: z.string().nullable(),
+});
+
+/**
+ * Core reply to `request_run_secrets`. Carries the resolved env map on
+ * success, or an `error` when a required secret could not be resolved /
+ * the collector was not found. The satellite injects `env` memory-only for
+ * the run and drops it on completion; on `error` it fails the run clearly
+ * rather than running without the secret.
+ *
+ * The env map never persists on the core side and is never written to disk
+ * on the satellite.
+ */
+const RunSecretsMessageSchema = z.object({
+  type: z.literal("run_secrets"),
+  /** Correlates with the originating `request_run_secrets`. */
+  requestId: z.string(),
+  /** Resolved env, present only on success. */
+  env: z.record(z.string(), z.string()).optional(),
+  /** Set when resolution failed; `env` is then absent. */
+  error: z.string().optional(),
+});
+
 /**
  * Discriminated union of all messages that the core can send to a satellite.
  */
@@ -131,6 +268,10 @@ export const CoreToSatelliteMessageSchema = z.discriminatedUnion("type", [
   AuthFailedMessageSchema,
   ConfigUpdatedMessageSchema,
   ShutdownMessageSchema,
+  RefreshScriptPackagesMessageSchema,
+  ScriptPackageManifestMessageSchema,
+  ScriptPackageBlobMessageSchema,
+  RunSecretsMessageSchema,
 ]);
 
 export type CoreToSatelliteMessage = z.infer<
@@ -142,3 +283,13 @@ export type AuthenticatedMessage = z.infer<typeof AuthenticatedMessageSchema>;
 export type AuthFailedMessage = z.infer<typeof AuthFailedMessageSchema>;
 export type ConfigUpdatedMessage = z.infer<typeof ConfigUpdatedMessageSchema>;
 export type ShutdownMessage = z.infer<typeof ShutdownMessageSchema>;
+export type RefreshScriptPackagesMessage = z.infer<
+  typeof RefreshScriptPackagesMessageSchema
+>;
+export type ScriptPackageManifestMessage = z.infer<
+  typeof ScriptPackageManifestMessageSchema
+>;
+export type ScriptPackageBlobMessage = z.infer<
+  typeof ScriptPackageBlobMessageSchema
+>;
+export type RunSecretsMessage = z.infer<typeof RunSecretsMessageSchema>;