station-kit 1.0.9 → 2.0.0

package/src/config/schema.ts

@@ -1,16 +1,20 @@
 import type { SignalQueueAdapter } from "station-signal";
 import type { BroadcastQueueAdapter } from "station-broadcast";
+import type { BeaconStateAdapter } from "station-beacon";
 import type { ScheduleAdapter } from "station-schedules";
+import type { EnvStorageAdapter } from "station-env";
 import type { ApiKeyStorageAdapter } from "../server/auth/keys.js";
+import type { LogStorageAdapter } from "../server/log-store.js";
 
 export interface AuthConfig {
   username: string;
   password: string;
   sessionTtlMs?: number;
   /**
-   * Pluggable storage backend for API keys. Defaults to a SQLite store at
-   * `<dataDir>/station-keys.db`. Provide a custom adapter to host keys in
-   * Postgres, MySQL, Redis, etc.
+   * Pluggable storage backend for API keys. Defaults to a JSON file at
+   * `<dataDir>/station-keys.json` (no native dependencies required).
+   * Provide a custom adapter to host keys in SQLite, Postgres, MySQL,
+   * Redis, etc.
    */
   keyStorage?: ApiKeyStorageAdapter;
 }
@@ -35,13 +39,37 @@ export interface StationConfig {
   host: string;
   adapter?: SignalQueueAdapter;
   broadcastAdapter?: BroadcastQueueAdapter;
+  /**
+   * Optional beacon supervision-state adapter. When provided (or when
+   * `beaconsDir` is set), the dashboard supervises long-running beacons and
+   * exposes them under `/api/beacons`.
+   */
+  beaconAdapter?: BeaconStateAdapter;
   /**
    * Optional schedule storage adapter. When provided, runtime-editable
    * schedules are persisted here and reconciled by both runners.
    */
   scheduleAdapter?: ScheduleAdapter;
+  /**
+   * Pluggable storage backend for runtime environment variables. Defaults to a
+   * JSON file at `<dataDir>/station-env.json` (no native dependencies). When
+   * set — or by default — signals/beacons can require env vars via `.env()`,
+   * and variables defined here (globally or scoped to specific targets) are
+   * injected into runs. For multi-process deployments pass a durable adapter
+   * from a `station-adapter-*` package's `/env` subpath.
+   */
+  envStorage?: EnvStorageAdapter;
+  /**
+   * Pluggable storage backend for run logs. Defaults to a `FileLogStorage`
+   * (append-only JSONL file at `<dataDir>/station-logs.jsonl`, no native
+   * dependencies). The default is single-process only — for multi-process
+   * deployments or guaranteed durability, implement `LogStorageAdapter`
+   * against Postgres, MySQL, Redis, S3, etc., and pass it here.
+   */
+  logStorage?: LogStorageAdapter;
   signalsDir?: string;
   broadcastsDir?: string;
+  beaconsDir?: string;
   stationDir: string;
   runner: RunnerConfig;
   broadcastRunner: BroadcastRunnerConfig;
@@ -98,9 +126,13 @@ export function resolveConfig(input: StationUserConfig): StationConfig {
     host: input.host ?? envHost ?? DEFAULTS.host,
     adapter: input.adapter,
     broadcastAdapter: input.broadcastAdapter,
+    beaconAdapter: input.beaconAdapter,
     scheduleAdapter: input.scheduleAdapter,
+    envStorage: input.envStorage,
+    logStorage: input.logStorage,
     signalsDir: input.signalsDir,
     broadcastsDir: input.broadcastsDir,
+    beaconsDir: input.beaconsDir,
     stationDir: input.stationDir ?? DEFAULTS.stationDir,
     runner: {
       pollIntervalMs: input.runner?.pollIntervalMs ?? DEFAULTS.runner.pollIntervalMs,

package/src/index.ts

@@ -7,3 +7,15 @@ export function defineConfig(config: StationUserConfig): StationUserConfig {
 export type { StationConfig, StationUserConfig, AuthConfig, DeployConfig } from "./config/schema.js";
 export { resolveConfig } from "./config/schema.js";
 export { loadConfig } from "./config/loader.js";
+
+// Re-export the runtime env store surface so consumers can construct custom
+// storage or the store itself without a separate `station-env` import.
+export {
+  EnvStore,
+  MemoryEnvStorage,
+  FileEnvStorage,
+  type EnvStorageAdapter,
+  type EnvVar,
+  type EnvVarPublic,
+  type EnvTarget,
+} from "station-env";

package/src/server/auth/keys.ts

@@ -1,5 +1,17 @@
 import crypto from "node:crypto";
-import Database from "better-sqlite3";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
 
 export interface ApiKey {
   id: string;
@@ -29,7 +41,123 @@ export interface ApiKeyStorageAdapter {
   close?(): Promise<void> | void;
 }
 
-// ─── SQLite default ─────────────────────────────────────────────────
+// ─── JSON file default ──────────────────────────────────────────────
+
+export interface FileKeyStorageOptions {
+  filePath: string;
+}
+
+/**
+ * Default ApiKeyStorageAdapter backed by a JSON file. Used by the Station
+ * server when no `keyStorage` is configured. Has no native dependencies —
+ * works on any Node 18+ install without compiling bindings.
+ *
+ * Crash-safety: writes go through a fsync'd tmp-file + rename, with a
+ * second fsync on the parent directory so the rename itself survives
+ * power loss. The keys file is created with `0o600` and the parent dir
+ * with `0o700` so a default umask doesn't expose key metadata.
+ *
+ * Single-process only: do not point two `createStation` instances at
+ * the same file or last-rename-wins will silently clobber writes. For
+ * multi-process or high-volume deployments, implement
+ * `ApiKeyStorageAdapter` against Postgres / MySQL / Redis.
+ */
+export class FileKeyStorage implements ApiKeyStorageAdapter {
+  private filePath: string;
+  private records = new Map<string, ApiKey>();
+
+  constructor(options: FileKeyStorageOptions) {
+    this.filePath = options.filePath;
+    mkdirSync(dirname(this.filePath), { recursive: true, mode: 0o700 });
+    this.load();
+  }
+
+  private load(): void {
+    if (!existsSync(this.filePath)) return;
+    try {
+      const raw = readFileSync(this.filePath, "utf8");
+      const data = JSON.parse(raw) as ApiKey[];
+      if (Array.isArray(data)) {
+        for (const r of data) this.records.set(r.id, r);
+      }
+    } catch {
+      // Corrupt or unreadable file — start fresh rather than throwing.
+    }
+  }
+
+  private flush(): void {
+    const tmp = `${this.filePath}.tmp`;
+    const body = JSON.stringify(Array.from(this.records.values()), null, 2);
+    // Write tmp file with fsync so its bytes are durable before rename.
+    const fd = openSync(tmp, "w", 0o600);
+    try {
+      writeSync(fd, body);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(tmp, this.filePath);
+    // fsync the parent directory so the rename's directory entry survives
+    // a crash. Best-effort: opening a directory for fsync isn't supported
+    // on every platform (notably Windows), so swallow errors.
+    try {
+      const dirFd = openSync(dirname(this.filePath), "r");
+      try {
+        fsyncSync(dirFd);
+      } finally {
+        closeSync(dirFd);
+      }
+    } catch {
+      // Platform doesn't support directory fsync; rename + tmp fsync
+      // already give us most of the durability we can offer.
+    }
+  }
+
+  insert(record: ApiKey): void {
+    this.records.set(record.id, { ...record });
+    this.flush();
+  }
+
+  findByHash(keyHash: string): ApiKey | null {
+    for (const r of this.records.values()) {
+      if (r.keyHash === keyHash) return { ...r };
+    }
+    return null;
+  }
+
+  list(): ApiKeyPublic[] {
+    return Array.from(this.records.values())
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+      .map((r) => {
+        const { keyHash: _h, ...rest } = r;
+        return rest;
+      });
+  }
+
+  touch(id: string, lastUsedIso: string): void {
+    const r = this.records.get(id);
+    if (!r) return;
+    const prev = r.lastUsed ? Date.parse(r.lastUsed) : 0;
+    r.lastUsed = lastUsedIso;
+    // lastUsed is advisory. flush() rewrites and fsyncs the whole file
+    // synchronously — doing that on every authenticated request stalls the
+    // event loop, so only persist when the value moves by at least a minute.
+    // Reads stay fresh because list() serves from memory.
+    if (Date.parse(lastUsedIso) - prev >= 60_000) {
+      this.flush();
+    }
+  }
+
+  revoke(id: string): boolean {
+    const r = this.records.get(id);
+    if (!r) return false;
+    r.revoked = true;
+    this.flush();
+    return true;
+  }
+}
+
+// ─── SQLite (optional) ──────────────────────────────────────────────
 
 export interface SqliteKeyStorageOptions {
   dbPath: string;
@@ -37,13 +165,42 @@ export interface SqliteKeyStorageOptions {
   tableName?: string;
 }
 
+// Loaded lazily from `better-sqlite3` so the package isn't required at
+// install time. Users who don't construct SqliteKeyStorage never pay for it.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type BetterSqlite3Module = any;
+let cachedBetterSqlite3: BetterSqlite3Module | null = null;
+
+function loadBetterSqlite3(): BetterSqlite3Module {
+  if (cachedBetterSqlite3) return cachedBetterSqlite3;
+  try {
+    const requireFn = createRequire(import.meta.url);
+    cachedBetterSqlite3 = requireFn("better-sqlite3");
+    return cachedBetterSqlite3;
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `SqliteKeyStorage requires the optional 'better-sqlite3' package, ` +
+        `which isn't installed. Install it with:\n` +
+        `  npm install better-sqlite3\n` +
+        `Or use FileKeyStorage (default) / MemoryKeyStorage instead.\n` +
+        `Underlying error: ${reason}`,
+    );
+  }
+}
+
 /**
- * Default ApiKeyStorageAdapter backed by better-sqlite3. Used by the Station
- * server when no `keyStorage` is configured. For Postgres / MySQL / Redis,
- * implement `ApiKeyStorageAdapter` and pass it to `KeyStore` directly.
+ * Optional ApiKeyStorageAdapter backed by better-sqlite3. Requires the
+ * `better-sqlite3` package to be installed separately — Station Kit no
+ * longer ships it as a hard dependency.
+ *
+ * Prefer `FileKeyStorage` (the default) unless you specifically need
+ * sqlite features (concurrent reads from multiple processes, large
+ * key catalogs, etc.).
  */
 export class SqliteKeyStorage implements ApiKeyStorageAdapter {
-  private db: Database.Database;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private db: any;
   private table: string;
 
   constructor(options: SqliteKeyStorageOptions) {
@@ -52,6 +209,7 @@ export class SqliteKeyStorage implements ApiKeyStorageAdapter {
       throw new Error(`Invalid table name "${tableName}"`);
     }
     this.table = tableName;
+    const Database = loadBetterSqlite3();
     this.db = new Database(options.dbPath);
     this.db.pragma("journal_mode = WAL");
     this.db.exec(`
@@ -113,7 +271,15 @@ export class SqliteKeyStorage implements ApiKeyStorageAdapter {
     }));
   }
 
+  /** Last persisted lastUsed per key id, to skip per-request UPDATEs. */
+  private lastTouched = new Map<string, number>();
+
   touch(id: string, lastUsedIso: string): void {
+    // lastUsed is advisory — throttle writes to once a minute per key.
+    const prev = this.lastTouched.get(id) ?? 0;
+    const next = Date.parse(lastUsedIso);
+    if (next - prev < 60_000) return;
+    this.lastTouched.set(id, next);
     this.db.prepare(`UPDATE ${this.table} SET last_used = ? WHERE id = ?`).run(lastUsedIso, id);
   }
 
@@ -181,27 +347,57 @@ export class MemoryKeyStorage implements ApiKeyStorageAdapter {
 
 // ─── KeyStore — owns crypto, delegates persistence ──────────────────
 
+export interface KeyStoreOptions {
+  /**
+   * Server-side secret ("pepper") mixed into stored key hashes via HMAC.
+   * Defense-in-depth: a leaked key file alone can't be brute-forced or
+   * precomputed against without also stealing this secret. Optional — when
+   * omitted, keys are hashed with plain SHA-256 (legacy behavior). Existing
+   * plain-SHA-256 keys keep verifying after a pepper is added (see verify()).
+   */
+  pepper?: string;
+}
+
 export class KeyStore {
   private storage: ApiKeyStorageAdapter;
+  private pepper?: Buffer;
 
   /**
    * Pass an `ApiKeyStorageAdapter` for any backend. The string overload is
-   * retained for backwards compatibility — it constructs a SqliteKeyStorage
-   * at the given path.
+   * retained for backwards compatibility — it constructs a FileKeyStorage
+   * at the given path. (Previously this returned a SqliteKeyStorage; SQLite
+   * is now opt-in to avoid native build dependencies.)
    */
-  constructor(storageOrDbPath: ApiKeyStorageAdapter | string) {
-    if (typeof storageOrDbPath === "string") {
-      this.storage = new SqliteKeyStorage({ dbPath: storageOrDbPath });
+  constructor(storageOrPath: ApiKeyStorageAdapter | string, options?: KeyStoreOptions) {
+    if (typeof storageOrPath === "string") {
+      const filePath = storageOrPath.endsWith(".db")
+        ? storageOrPath.replace(/\.db$/, ".json")
+        : storageOrPath;
+      this.storage = new FileKeyStorage({ filePath });
     } else {
-      this.storage = storageOrDbPath;
+      this.storage = storageOrPath;
+    }
+    if (options?.pepper) this.pepper = Buffer.from(options.pepper, "utf8");
+  }
+
+  /** Peppered hash for new keys — HMAC-SHA256 when a pepper is set, else SHA-256. */
+  private hashKey(rawKey: string): string {
+    if (this.pepper) {
+      return crypto.createHmac("sha256", this.pepper).update(rawKey).digest("hex");
     }
+    return crypto.createHash("sha256").update(rawKey).digest("hex");
+  }
+
+  /** Unpeppered SHA-256 — used to verify keys stored before a pepper was configured. */
+  private legacyHashKey(rawKey: string): string {
+    return crypto.createHash("sha256").update(rawKey).digest("hex");
   }
 
   /** Generate a new API key. Returns the full key (only shown once) and the stored record. */
   async create(name: string, scopes: string[] = ["trigger", "read"]): Promise<{ key: string; record: ApiKey }> {
     const id = crypto.randomUUID();
     const rawKey = `sk_live_${crypto.randomBytes(16).toString("hex")}`;
-    const keyHash = crypto.createHash("sha256").update(rawKey).digest("hex");
+    const keyHash = this.hashKey(rawKey);
     const keyPrefix = rawKey.slice(0, 12);
     const createdAt = new Date().toISOString();
 
@@ -215,8 +411,12 @@ export class KeyStore {
 
   /** Verify an API key. Returns the key record if valid, null otherwise. */
   async verify(rawKey: string): Promise<ApiKey | null> {
-    const keyHash = crypto.createHash("sha256").update(rawKey).digest("hex");
-    const record = await this.storage.findByHash(keyHash);
+    let record = await this.storage.findByHash(this.hashKey(rawKey));
+    // Fall back to the unpeppered hash for keys created before the pepper was
+    // configured, so enabling a pepper doesn't invalidate existing keys.
+    if (!record && this.pepper) {
+      record = await this.storage.findByHash(this.legacyHashKey(rawKey));
+    }
     if (!record) return null;
     if (record.revoked) return null;
     if (record.expiresAt && new Date(record.expiresAt) < new Date()) return null;

package/src/server/auth/session.ts

@@ -8,17 +8,45 @@ export interface SessionConfig {
   sessionTtlMs?: number;
 }
 
-/** HMAC-sign a token. The secret is derived from the password. */
-function sign(payload: string, secret: string): string {
-  const hmac = crypto.createHmac("sha256", secret);
+/**
+ * Derive the HMAC signing key from the password via HKDF instead of using
+ * the cleartext password as the key directly — issued cookies should not be
+ * HMACs keyed with the literal admin credential. Cached because HKDF per
+ * request would be wasted CPU.
+ */
+const secretCache = new Map<string, Buffer>();
+function sessionSecret(config: SessionConfig): Buffer {
+  let secret = secretCache.get(config.password);
+  if (!secret) {
+    secret = Buffer.from(
+      crypto.hkdfSync("sha256", config.password, "station-kit", "session-token-v1", 32),
+    );
+    secretCache.set(config.password, secret);
+  }
+  return secret;
+}
+
+function sign(payload: string, config: SessionConfig): string {
+  const hmac = crypto.createHmac("sha256", sessionSecret(config));
   hmac.update(payload);
   return hmac.digest("hex");
 }
 
+/**
+ * Timing-safe string comparison that doesn't leak length: both inputs are
+ * hashed to a fixed size before `timingSafeEqual` (which requires equal
+ * lengths and would otherwise short-circuit on a length check).
+ */
+function safeEqual(a: string, b: string): boolean {
+  const ha = crypto.createHash("sha256").update(a).digest();
+  const hb = crypto.createHash("sha256").update(b).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+
 export function createSessionToken(config: SessionConfig): string {
   const exp = Date.now() + (config.sessionTtlMs ?? SESSION_TTL_MS);
   const payload = `${config.username}:${exp}`;
-  const signature = sign(payload, config.password);
+  const signature = sign(payload, config);
   return Buffer.from(`${payload}:${signature}`).toString("base64url");
 }
 
@@ -31,18 +59,17 @@ export function verifySessionToken(token: string, config: SessionConfig): boolea
     const exp = parseInt(expStr, 10);
     if (isNaN(exp) || Date.now() > exp) return false;
     if (username !== config.username) return false;
-    const expected = sign(`${username}:${expStr}`, config.password);
-    return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
+    const expected = sign(`${username}:${expStr}`, config);
+    return safeEqual(sig, expected);
   } catch {
     return false;
   }
 }
 
 export function verifyCredentials(username: string, password: string, config: SessionConfig): boolean {
-  // Use timing-safe comparison to prevent timing attacks
-  const userMatch = username.length === config.username.length &&
-    crypto.timingSafeEqual(Buffer.from(username), Buffer.from(config.username));
-  const passMatch = password.length === config.password.length &&
-    crypto.timingSafeEqual(Buffer.from(password), Buffer.from(config.password));
+  // Evaluate both comparisons unconditionally so a valid username isn't
+  // distinguishable from an invalid one by response time.
+  const userMatch = safeEqual(username, config.username);
+  const passMatch = safeEqual(password, config.password);
   return userMatch && passMatch;
 }