station-kit 1.0.9 → 2.0.0

package/src/server/index.ts

@@ -1,30 +1,36 @@
 import { Hono } from "hono";
 import { createMiddleware } from "hono/factory";
+import { bodyLimit } from "hono/body-limit";
 import { serve } from "@hono/node-server";
 import { resolve } from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import type { Server } from "node:http";
 import { SignalRunner, MemoryAdapter, parseInterval } from "station-signal";
 import { BroadcastRunner, BroadcastMemoryAdapter } from "station-broadcast";
+import { BeaconRunner, BeaconMemoryAdapter } from "station-beacon";
 import type { SignalQueueAdapter } from "station-signal";
 import type { BroadcastQueueAdapter } from "station-broadcast";
+import type { BeaconStateAdapter } from "station-beacon";
 import {
   ScheduleReconciler,
   type Schedule,
   type ScheduleAdapter,
 } from "station-schedules";
+import { EnvStore, FileEnvStorage } from "station-env";
 import type { StationConfig } from "../config/schema.js";
 import { ensureStationDir } from "../station-dir.js";
 import { WebSocketHub } from "./ws.js";
 import { SSEHub } from "./sse.js";
 import { LogBuffer } from "./log-buffer.js";
-import { LogStore } from "./log-store.js";
-import { StationSignalSubscriber, StationBroadcastSubscriber } from "./subscriber.js";
+import { LogStore, FileLogStorage } from "./log-store.js";
+import { StationSignalSubscriber, StationBroadcastSubscriber, StationBeaconSubscriber } from "./subscriber.js";
 import { healthRoutes } from "./routes/health.js";
 import { signalRoutes } from "./routes/signals.js";
 import { runRoutes } from "./routes/runs.js";
 import { broadcastRoutes } from "./routes/broadcasts.js";
-import { KeyStore, SqliteKeyStorage } from "./auth/keys.js";
+import { beaconRoutes } from "./routes/beacons.js";
+import { KeyStore, FileKeyStorage } from "./auth/keys.js";
 import { verifySessionToken, verifyCredentials, createSessionToken, type SessionConfig } from "./auth/session.js";
 import { authResolver } from "./middleware/auth.js";
 import { requireScope } from "./middleware/scope-guard.js";
@@ -39,10 +45,12 @@ import { v1AuthRoutes } from "./routes/v1/auth.js";
 import { v1EventRoutes } from "./routes/v1/events.js";
 import { v1DefinitionRoutes, v1DefinitionReadRoutes } from "./routes/v1/definitions.js";
 import { v1ScheduleRoutes, v1ScheduleReadRoutes } from "./routes/v1/schedules.js";
+import { v1EnvRoutes, v1EnvReadRoutes } from "./routes/v1/env.js";
 import { v1ExpressionRoutes } from "./routes/v1/expressions.js";
 
 export {
   KeyStore,
+  FileKeyStorage,
   SqliteKeyStorage,
   MemoryKeyStorage,
 } from "./auth/keys.js";
@@ -50,8 +58,19 @@ export type {
   ApiKey,
   ApiKeyPublic,
   ApiKeyStorageAdapter,
+  FileKeyStorageOptions,
   SqliteKeyStorageOptions,
 } from "./auth/keys.js";
+export {
+  LogStore,
+  FileLogStorage,
+  MemoryLogStorage,
+} from "./log-store.js";
+export type {
+  LogStorageAdapter,
+  FileLogStorageOptions,
+} from "./log-store.js";
+export type { LogEntry } from "./log-buffer.js";
 
 export interface StationInstance {
   start(): Promise<void>;
@@ -66,13 +85,29 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   const signalAdapter: SignalQueueAdapter = config.adapter ?? new MemoryAdapter();
   const broadcastAdapter: BroadcastQueueAdapter | undefined =
     config.broadcastAdapter ?? (config.broadcastsDir ? new BroadcastMemoryAdapter() : undefined);
+  const beaconAdapter: BeaconStateAdapter | undefined =
+    config.beaconAdapter ?? (config.beaconsDir ? new BeaconMemoryAdapter() : undefined);
 
   const { dataDir } = ensureStationDir(cwd, config.stationDir);
 
+  warnIfLegacySqliteFiles(dataDir);
+
   const wsHub = new WebSocketHub();
   const sseHub = new SSEHub();
   const logBuffer = new LogBuffer();
-  const logStore = new LogStore(resolve(dataDir, "station-logs.db"));
+  const logStore = new LogStore(
+    config.logStorage ?? new FileLogStorage({
+      filePath: resolve(dataDir, "station-logs.jsonl"),
+      onError: (err) => console.error("[station] log write failed:", err),
+    }),
+  );
+
+  // Runtime env store: defaults to a JSON file so `.env()` requirements and
+  // dashboard-defined variables work out of the box. Pass a durable adapter
+  // via `envStorage` for multi-process deployments.
+  const envStore = new EnvStore(
+    config.envStorage ?? new FileEnvStorage({ filePath: resolve(dataDir, "station-env.json") }),
+  );
 
   // Auth: create KeyStore and SessionConfig if auth is configured
   let keyStore: KeyStore | undefined;
@@ -80,8 +115,8 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
 
   if (config.auth) {
     const storage = config.auth.keyStorage
-      ?? new SqliteKeyStorage({ dbPath: resolve(dataDir, "station-keys.db") });
-    keyStore = new KeyStore(storage);
+      ?? new FileKeyStorage({ filePath: resolve(dataDir, "station-keys.json") });
+    keyStore = new KeyStore(storage, { pepper: resolveKeyPepper(dataDir) });
     sessionConfig = {
       username: config.auth.username,
       password: config.auth.password,
@@ -102,17 +137,26 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
       ? resolve(cwd, "broadcasts")
       : undefined;
 
+  const beaconsDir = config.beaconsDir
+    ? resolve(cwd, config.beaconsDir)
+    : existsSync(resolve(cwd, "beacons"))
+      ? resolve(cwd, "beacons")
+      : undefined;
+
   // Create subscribers (always — they collect metadata)
   const stationSignalSub = new StationSignalSubscriber(wsHub, logBuffer, logStore);
   const stationBroadcastSub = new StationBroadcastSubscriber(wsHub);
+  const stationBeaconSub = new StationBeaconSubscriber(wsHub, logBuffer, logStore);
 
   // Wire SSE hub into subscribers so events reach both WS and SSE clients
   stationSignalSub.setSSEHub(sseHub);
   stationBroadcastSub.setSSEHub(sseHub);
+  stationBeaconSub.setSSEHub(sseHub);
 
   // Create runners if enabled
   let signalRunner: SignalRunner | undefined;
   let broadcastRunner: BroadcastRunner | undefined;
+  let beaconRunner: BeaconRunner | undefined;
   const scheduleAdapter: ScheduleAdapter | undefined = config.scheduleAdapter;
 
   if (config.runRunners) {
@@ -139,6 +183,7 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
       retryBackoffMs: config.runner.retryBackoffMs,
       subscribers: [stationSignalSub],
       scheduleReconciler: signalScheduleReconciler,
+      envProvider: envStore,
     });
 
     if (broadcastsDir || broadcastAdapter) {
@@ -163,11 +208,30 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
         scheduleReconciler: broadcastScheduleReconciler,
       });
     }
+
+    if (beaconsDir || beaconAdapter) {
+      beaconRunner = new BeaconRunner({
+        beaconsDir,
+        adapter: beaconAdapter ?? new BeaconMemoryAdapter(),
+        signalRunner, // beacons can trigger signals into the shared queue
+        subscribers: [stationBeaconSub],
+        envProvider: envStore,
+      });
+    }
   }
 
   // Build Hono app
   const app = new Hono();
 
+  // Bound request bodies so oversized payloads can't be parsed/stored.
+  app.use("/api/*", bodyLimit({
+    maxSize: 5 * 1024 * 1024,
+    onError: (c) => c.json({ error: "payload_too_large", message: "Request body too large." }, 413),
+  }));
+
+  // Brute-force protection for the dashboard login (the v1 login is limited below).
+  app.use("/api/auth/login", rateLimiter({ windowMs: 60_000, max: 10 }));
+
   // ── Dashboard auth routes (always accessible) ──────────────────────
   app.get("/api/auth/check", async (c) => {
     if (!sessionConfig) {
@@ -229,15 +293,18 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   app.route("/api", signalRoutes({ signalRunner, signalAdapter, signalSubscriber: stationSignalSub }));
   app.route("/api", runRoutes({ signalRunner, signalAdapter, logBuffer, logStore, signalSubscriber: stationSignalSub }));
   app.route("/api", broadcastRoutes({ broadcastRunner, broadcastAdapter, broadcastSubscriber: stationBroadcastSub, logBuffer, logStore }));
+  app.route("/api", beaconRoutes({ beaconRunner, beaconAdapter, logBuffer, logStore }));
 
   // ── v1 API routes (authenticated) ──────────────────────────────────
 
   // Public v1 routes (no auth required)
   app.route("/api/v1", v1HealthRoutes({ signalAdapter, broadcastAdapter }));
 
-  // Auth routes: public but rate-limited to prevent brute force
+  // Auth routes: public but rate-limited to prevent brute force. The limiter
+  // is scoped to /auth/* — a "/*" limiter here would run for every /api/v1
+  // route mounted after this app and throttle the whole API to 10 req/min.
   const authApp = new Hono();
-  authApp.use("/*", rateLimiter({ windowMs: 60_000, max: 10 }));
+  authApp.use("/auth/*", rateLimiter({ windowMs: 60_000, max: 10 }));
   authApp.route("/", v1AuthRoutes({ sessionConfig }));
   app.route("/api/v1", authApp);
 
@@ -245,9 +312,22 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   const v1 = new Hono();
   v1.use("/*", authResolver({ keyStore, sessionConfig }));
 
+  // Hono runs a sub-app's `use("/*")` middleware for routes that sibling
+  // sub-apps mount LATER under the same prefix, so per-group scope guards
+  // stack instead of isolating (a trigger-only key would be rejected by the
+  // read group's guard before reaching /trigger). Attach the guard to each
+  // route individually instead.
+  const guarded = (scope: string, group: Hono): Hono => {
+    const out = new Hono();
+    const guard = requireScope(scope);
+    for (const r of group.routes) {
+      out.on(r.method, r.path, guard, r.handler);
+    }
+    return out;
+  };
+
   // Read-scope routes
   const readRoutes = new Hono();
-  readRoutes.use("/*", requireScope("read"));
   readRoutes.route("/", v1SignalRoutes({ signalRunner, signalSubscriber: stationSignalSub }));
   readRoutes.route("/", v1RunRoutes({ signalRunner, signalAdapter, logBuffer, logStore }));
   readRoutes.route("/", v1BroadcastRoutes({ broadcastRunner, broadcastAdapter, broadcastSubscriber: stationBroadcastSub }));
@@ -255,23 +335,21 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
   readRoutes.route("/", v1ExpressionRoutes());
   // Schedule GET + preview are read-scoped; mutating routes are mounted under admin below.
   readRoutes.route("/", v1ScheduleReadRoutes({ scheduleAdapter }));
+  // Env GET is read-scoped (secret values redacted); mutations are admin-only below.
+  readRoutes.route("/", v1EnvReadRoutes({ envStore }));
   readRoutes.route("/", v1DefinitionReadRoutes({
     broadcastRunner,
     broadcastAdapter,
     signalRunner,
     signalSubscriber: stationSignalSub,
   }));
-  v1.route("/", readRoutes);
+  v1.route("/", guarded("read", readRoutes));
 
   // Trigger-scope routes
-  const triggerRoutes = new Hono();
-  triggerRoutes.use("/*", requireScope("trigger"));
-  triggerRoutes.route("/", v1TriggerRoutes({ signalRunner, signalAdapter, broadcastRunner, broadcastAdapter, signalSubscriber: stationSignalSub }));
-  v1.route("/", triggerRoutes);
+  v1.route("/", guarded("trigger", v1TriggerRoutes({ signalRunner, signalAdapter, broadcastRunner, broadcastAdapter, signalSubscriber: stationSignalSub })));
 
   // Cancel-scope routes — only the cancel endpoints
   const cancelRoutes = new Hono();
-  cancelRoutes.use("/*", requireScope("cancel"));
   cancelRoutes.post("/runs/:id/cancel", async (c) => {
     const id = c.req.param("id");
     if (!signalRunner) {
@@ -294,11 +372,10 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
     }
     return c.json({ data: { cancelled: true } });
   });
-  v1.route("/", cancelRoutes);
+  v1.route("/", guarded("cancel", cancelRoutes));
 
   // Admin-scope routes — destructive / mutating endpoints
   const adminRoutes = new Hono();
-  adminRoutes.use("/*", requireScope("admin"));
   adminRoutes.route("/", v1KeyRoutes({ keyStore }));
   adminRoutes.route("/", v1DefinitionRoutes({
     broadcastRunner,
@@ -307,7 +384,8 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
     signalSubscriber: stationSignalSub,
   }));
   adminRoutes.route("/", v1ScheduleRoutes({ scheduleAdapter }));
-  v1.route("/", adminRoutes);
+  adminRoutes.route("/", v1EnvRoutes({ envStore }));
+  v1.route("/", guarded("admin", adminRoutes));
 
   app.route("/api/v1", v1);
 
@@ -365,6 +443,14 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
     keyStore,
     dataDir,
     async start() {
+      if (!config.auth && !isLoopbackHost(config.host)) {
+        console.warn(
+          `[station] WARNING: no auth configured while binding to ${config.host} — ` +
+          "anyone who can reach this port can view logs and trigger, cancel, or rerun jobs. " +
+          "Set auth (STATION_AUTH_USERNAME/STATION_AUTH_PASSWORD) or bind to 127.0.0.1.",
+        );
+      }
+
       // Start runners (non-blocking — they have internal poll loops)
       if (config.runRunners) {
         if (signalRunner) {
@@ -377,6 +463,11 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
             console.error("[station] Broadcast runner error:", err);
           });
         }
+        if (beaconRunner) {
+          beaconRunner.start().catch((err: unknown) => {
+            console.error("[station] Beacon runner error:", err);
+          });
+        }
       }
 
       // Start Hono server
@@ -387,12 +478,31 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
         },
       ) as unknown as Server;
 
-      // Attach WebSocket to the HTTP server
-      wsHub.attach(httpServer);
+      // Attach WebSocket to the HTTP server. The upgrade path never passes
+      // through Hono middleware, so it enforces auth itself: session cookie
+      // or a read-scoped API key, mirroring the SSE endpoint.
+      wsHub.attach(httpServer, async (req) => {
+        if (!sessionConfig && !keyStore) return true;
+        const cookie = req.headers.cookie;
+        if (cookie && sessionConfig) {
+          const match = cookie.match(/station_session=([^;]+)/);
+          if (match && verifySessionToken(match[1], sessionConfig)) return true;
+        }
+        const authHeader = req.headers.authorization;
+        if (authHeader?.startsWith("Bearer ") && keyStore) {
+          const key = await keyStore.verify(authHeader.slice(7));
+          if (key?.scopes.includes("read")) return true;
+        }
+        return false;
+      });
     },
 
     async stop() {
-      // Stop broadcast runner first — it queries the DB during graceful shutdown
+      // Stop beacons first — they are producers that may trigger signals.
+      if (beaconRunner) {
+        await beaconRunner.stop({ graceful: true, timeoutMs: 5000 });
+      }
+      // Stop broadcast runner next — it queries the DB during graceful shutdown
       if (broadcastRunner) {
         await broadcastRunner.stop({ graceful: true, timeoutMs: 5000 });
       }
@@ -401,11 +511,70 @@ export async function createStation(config: StationConfig, cwd: string, nextPort
       }
       wsHub.close();
       sseHub.close();
-      logStore.close();
+      await logStore.close();
       await keyStore?.close();
+      await envStore.close();
       if (httpServer) {
         httpServer.close();
       }
     },
   };
 }
+
+// Existing deployments that ran older Station versions persisted keys
+// to `station-keys.db` (SQLite) and run logs to `station-logs.db`. The
+// new defaults are `station-keys.json` and `station-logs.jsonl`; the
+// legacy files are NOT auto-migrated. Emit a one-time warning so an
+// upgrade doesn't silently appear to wipe a user's API keys.
+function isLoopbackHost(host: string): boolean {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1" || host === "[::1]";
+}
+
+/**
+ * Resolve the API-key pepper (a server-side secret mixed into stored key
+ * hashes). Priority: STATION_KEY_PEPPER env var, else a persisted per-install
+ * secret at `<dataDir>/station-key-pepper` (generated with 0600 on first run).
+ * Persisting it means existing peppered keys keep verifying across restarts.
+ */
+function resolveKeyPepper(dataDir: string): string {
+  const fromEnv = process.env.STATION_KEY_PEPPER;
+  if (fromEnv) return fromEnv;
+
+  const pepperPath = resolve(dataDir, "station-key-pepper");
+  try {
+    if (existsSync(pepperPath)) {
+      const existing = readFileSync(pepperPath, "utf8").trim();
+      if (existing) return existing;
+    }
+  } catch {
+    // Unreadable — fall through and regenerate.
+  }
+  const pepper = randomBytes(32).toString("hex");
+  try {
+    writeFileSync(pepperPath, pepper, { mode: 0o600 });
+  } catch (err) {
+    // If we can't persist it, warn: keys created this run won't verify after
+    // a restart (a new pepper would be generated). Better than failing boot.
+    console.warn(`[station] Could not persist key pepper to ${pepperPath}:`, err);
+  }
+  return pepper;
+}
+
+function warnIfLegacySqliteFiles(dataDir: string): void {
+  const legacy: { file: string; replacement: string }[] = [
+    { file: "station-keys.db", replacement: "station-keys.json" },
+    { file: "station-logs.db", replacement: "station-logs.jsonl" },
+  ];
+  for (const { file, replacement } of legacy) {
+    const legacyPath = resolve(dataDir, file);
+    if (!existsSync(legacyPath)) continue;
+    const replacementPath = resolve(dataDir, replacement);
+    if (existsSync(replacementPath)) continue;
+    console.warn(
+      `[station] Legacy ${file} detected at ${legacyPath} but no ${replacement} found. ` +
+      `Station no longer reads SQLite-backed defaults; data in ${file} will not be loaded. ` +
+      `If you need the contents, export them with the better-sqlite3 CLI before upgrading. ` +
+      `To suppress this warning, delete or rename ${file}.`,
+    );
+  }
+}

package/src/server/log-store.ts

@@ -1,56 +1,207 @@
-import Database from "better-sqlite3";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import type { LogEntry } from "./log-buffer.js";
 
-export class LogStore {
-  private db: Database.Database;
-  private insertStmt: Database.Statement;
-  private selectStmt: Database.Statement;
-
-  constructor(dbPath: string) {
-    this.db = new Database(dbPath);
-    this.db.pragma("journal_mode = WAL");
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS logs (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        run_id TEXT NOT NULL,
-        signal_name TEXT NOT NULL,
-        level TEXT NOT NULL,
-        message TEXT NOT NULL,
-        timestamp TEXT NOT NULL
-      )
-    `);
-    this.db.exec(`CREATE INDEX IF NOT EXISTS idx_logs_run_id ON logs(run_id)`);
-
-    this.insertStmt = this.db.prepare(
-      `INSERT INTO logs (run_id, signal_name, level, message, timestamp) VALUES (?, ?, ?, ?, ?)`,
-    );
-    this.selectStmt = this.db.prepare(
-      `SELECT run_id, signal_name, level, message, timestamp FROM logs WHERE run_id = ? ORDER BY id`,
+/**
+ * Pluggable storage backend for run logs. Implementations only persist
+ * and query records — bounded in-memory buffering for live UI streams
+ * lives in `LogBuffer`. May be sync or async; the LogStore wrapper
+ * normalizes both.
+ *
+ * Contract for implementers:
+ *
+ * - **`add(entry)`** is treated as fire-and-forget at the LogStore
+ *   boundary. Signal runners never block on log writes. Adapters that
+ *   need durability guarantees (queues, retries, batching) should
+ *   implement that internally; thrown errors and rejected promises are
+ *   caught and surfaced via the LogStore's `onError` hook (if set) but
+ *   never rethrown to the caller.
+ * - **`get(runId)`** must return entries for that run in append order
+ *   (oldest first). Routes that aggregate across runs may re-sort by
+ *   timestamp, but per-run ordering is the adapter's responsibility.
+ * - **`close?()`** is called once on graceful shutdown. Use it to flush
+ *   any in-flight buffers. It is NOT called on `SIGKILL` / OOM kill —
+ *   adapters that must guarantee durability per write should not rely
+ *   on it.
+ *
+ * Single-process semantics: the built-in `FileLogStorage` is safe for a
+ * single Node process. Running multiple processes against the same file
+ * path WILL produce interleaved bytes and lost entries — use a real
+ * database adapter (Postgres, MySQL, Redis, etc.) for multi-process or
+ * distributed deployments.
+ */
+export interface LogStorageAdapter {
+  add(entry: LogEntry): Promise<void> | void;
+  get(runId: string): Promise<LogEntry[]> | LogEntry[];
+  close?(): Promise<void> | void;
+}
+
+// ─── File-backed default ────────────────────────────────────────────
+
+export interface FileLogStorageOptions {
+  filePath: string;
+  /**
+   * Called when a background write to the underlying file fails. Use
+   * this to surface persistence problems (disk full, permission denied,
+   * etc.) to your monitoring system. If unset, write failures are
+   * silently dropped — acceptable for local dev, NOT for production.
+   */
+  onError?: (err: unknown) => void;
+}
+
+/**
+ * File-backed log storage using append-only JSONL framing. Each line is
+ * a JSON-serialized `LogEntry`; existing entries are loaded into memory
+ * on construction; appends are serialized through an async write queue
+ * so concurrent writers can't interleave bytes within one process.
+ *
+ * No native dependencies — works on any Node 18+ install.
+ *
+ * **Production caveats** (in order of severity):
+ *
+ * 1. **Single-process only.** Two Node processes appending to the same
+ *    file WILL interleave bytes once individual JSON lines exceed the
+ *    OS pipe buffer (4 KB on Linux), corrupting the file.
+ * 2. **Best-effort durability.** Writes are queued and flushed via
+ *    `fs.appendFile`; on `SIGKILL` / OOM kill, in-flight writes are lost.
+ *    Set `onError` to surface fs failures.
+ * 3. **Unbounded memory on replay.** The whole file is loaded into a
+ *    Map on startup. For high-volume deployments (gigabytes of logs)
+ *    use a database-backed adapter instead.
+ *
+ * For multi-process, distributed, or high-durability deployments,
+ * implement `LogStorageAdapter` against Postgres / MySQL / Redis / S3.
+ */
+export class FileLogStorage implements LogStorageAdapter {
+  private path: string;
+  private byRunId = new Map<string, LogEntry[]>();
+  private writeQueue: Promise<void> = Promise.resolve();
+  private onError: (err: unknown) => void;
+
+  constructor(options: FileLogStorageOptions) {
+    // Backwards compat: callers used to pass `.db` paths for the sqlite store.
+    // Transparently swap to `.jsonl` so existing config files keep working.
+    this.path = options.filePath.endsWith(".db")
+      ? options.filePath.replace(/\.db$/, ".jsonl")
+      : options.filePath;
+    this.onError = options.onError ?? (() => {});
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    this.replay();
+  }
+
+  private replay(): void {
+    if (!existsSync(this.path)) return;
+    let content: string;
+    try {
+      content = readFileSync(this.path, "utf8");
+    } catch (err) {
+      this.onError(err);
+      return;
+    }
+    const lines = content.split("\n");
+    for (const line of lines) {
+      if (!line) continue;
+      try {
+        const entry = JSON.parse(line) as LogEntry;
+        this.indexEntry(entry);
+      } catch {
+        // Skip malformed line; a partial write may have left a truncated tail.
+      }
+    }
+  }
+
+  private indexEntry(entry: LogEntry): void {
+    let entries = this.byRunId.get(entry.runId);
+    if (!entries) {
+      entries = [];
+      this.byRunId.set(entry.runId, entries);
+    }
+    entries.push(entry);
+  }
+
+  add(entry: LogEntry): void {
+    this.indexEntry(entry);
+    const line = JSON.stringify(entry) + "\n";
+    this.writeQueue = this.writeQueue.then(
+      () => appendFile(this.path, line, { mode: 0o600 }).catch((err) => {
+        this.onError(err);
+      }),
     );
   }
 
+  get(runId: string): LogEntry[] {
+    return this.byRunId.get(runId) ?? [];
+  }
+
+  async close(): Promise<void> {
+    await this.writeQueue;
+  }
+}
+
+// ─── In-memory storage for tests / ephemeral deployments ────────────
+
+export class MemoryLogStorage implements LogStorageAdapter {
+  private byRunId = new Map<string, LogEntry[]>();
+
   add(entry: LogEntry): void {
-    this.insertStmt.run(entry.runId, entry.signalName, entry.level, entry.message, entry.timestamp);
+    let entries = this.byRunId.get(entry.runId);
+    if (!entries) {
+      entries = [];
+      this.byRunId.set(entry.runId, entries);
+    }
+    entries.push(entry);
   }
 
   get(runId: string): LogEntry[] {
-    const rows = this.selectStmt.all(runId) as Array<{
-      run_id: string;
-      signal_name: string;
-      level: string;
-      message: string;
-      timestamp: string;
-    }>;
-    return rows.map((row) => ({
-      runId: row.run_id,
-      signalName: row.signal_name,
-      level: row.level as "stdout" | "stderr",
-      message: row.message,
-      timestamp: row.timestamp,
-    }));
-  }
-
-  close(): void {
-    this.db.close();
+    return this.byRunId.get(runId) ?? [];
+  }
+}
+
+// ─── LogStore — thin wrapper that delegates to an adapter ───────────
+
+/**
+ * LogStore is the consumer-facing handle that wraps a `LogStorageAdapter`.
+ * It exists so signal runners and route handlers can interact with a
+ * single concrete type, while the underlying persistence is swappable.
+ *
+ * `add` is fire-and-forget — adapter promises are caught at this boundary
+ * so a slow or failing log backend can never block (or crash) a signal
+ * runner. `get` always returns a Promise so callers can transparently
+ * support async backends (Postgres, Redis, etc.).
+ */
+export class LogStore {
+  private storage: LogStorageAdapter;
+
+  /**
+   * Pass a `LogStorageAdapter` for any backend. The string overload is
+   * a shortcut for `new FileLogStorage({ filePath })` — useful for
+   * local dev and the default Station data directory.
+   */
+  constructor(storageOrPath: LogStorageAdapter | string) {
+    if (typeof storageOrPath === "string") {
+      this.storage = new FileLogStorage({ filePath: storageOrPath });
+    } else {
+      this.storage = storageOrPath;
+    }
+  }
+
+  add(entry: LogEntry): void {
+    try {
+      const result = this.storage.add(entry);
+      if (result && typeof (result as Promise<void>).catch === "function") {
+        (result as Promise<void>).catch(() => {});
+      }
+    } catch {
+      // Swallow sync throws; a broken log adapter must not crash signal runs.
+    }
+  }
+
+  async get(runId: string): Promise<LogEntry[]> {
+    return await this.storage.get(runId);
+  }
+
+  async close(): Promise<void> {
+    if (this.storage.close) await this.storage.close();
   }
 }

package/src/server/metadata.ts

@@ -24,6 +24,8 @@ export interface SignalMeta {
   maxConcurrency: number | null;
   hasSteps: boolean;
   stepNames: string[];
+  /** Env var keys this signal requires (declared via `.env()`). */
+  requiredEnv: string[];
 }
 
 export interface BroadcastMeta {