station-kit 1.1.0 → 2.0.0

package/src/app/hooks/use-api.ts

@@ -70,6 +70,26 @@ export interface SignalMeta {
   maxConcurrency: number | null;
   hasSteps: boolean;
   stepNames: string[];
+  requiredEnv?: string[];
+}
+
+export type EnvTargetKind = "signal" | "beacon";
+
+export interface EnvTarget {
+  kind: EnvTargetKind;
+  name: string;
+}
+
+export interface EnvVar {
+  id: string;
+  key: string;
+  /** Null when the variable is secret (write-only). */
+  value: string | null;
+  secret: boolean;
+  targets: EnvTarget[];
+  createdAt: string;
+  updatedAt: string;
+  createdBy?: string;
 }
 
 export interface BroadcastMeta {
@@ -81,6 +101,47 @@ export interface BroadcastMeta {
   interval: string | null;
 }
 
+export type BeaconStatus =
+  | "stopped" | "starting" | "running" | "stopping" | "backoff" | "errored";
+
+export interface BeaconInstance {
+  beaconName: string;
+  status: BeaconStatus;
+  desiredState: "running" | "stopped";
+  incarnation: number;
+  restartCount: number;
+  pid?: number;
+  config?: string;
+  startedAt?: string;
+  readyAt?: string;
+  lastHeartbeatAt?: string;
+  lastExitAt?: string;
+  lastExitReason?: "clean" | "failure" | "stopped" | "stalled";
+  lastError?: string;
+  nextRestartAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface BeaconListItem {
+  name: string;
+  filePath: string;
+  mode: "run" | "poll";
+  restartPolicy: string;
+  autoStart: boolean;
+  requiredEnv?: string[];
+  instance: BeaconInstance | null;
+}
+
+export interface BeaconEvent {
+  id: string;
+  beaconName: string;
+  incarnation: number;
+  type: string;
+  message?: string;
+  at: string;
+}
+
 // ─── Dynamic broadcasts / schedules / expressions ───────────────────
 
 export type ScheduleKind = "signal" | "broadcast-static" | "broadcast-dynamic";
@@ -174,6 +235,16 @@ export function useApi() {
     cancelBroadcastRun: (id: string) => fetchApi<{ cancelled: boolean }>(`/broadcast-runs/${id}/cancel`, { method: "POST" }),
     rerunBroadcastRun: (id: string) => fetchApi<{ id: string; broadcastName: string; status: string }>(`/broadcast-runs/${id}/rerun`, { method: "POST" }),
 
+    // Beacons
+    getBeacons: () => fetchApi<BeaconListItem[]>("/beacons"),
+    getBeacon: (name: string) => fetchApi<BeaconListItem>(`/beacons/${encodeURIComponent(name)}`),
+    getBeaconEvents: (name: string) => fetchApi<BeaconEvent[]>(`/beacons/${encodeURIComponent(name)}/events`),
+    getBeaconLogs: (name: string) =>
+      fetchApi<Array<{ runId: string; signalName: string; level: string; message: string; timestamp: string }>>(`/beacons/${encodeURIComponent(name)}/logs`),
+    startBeacon: (name: string) => fetchApi<{ started: boolean }>(`/beacons/${encodeURIComponent(name)}/start`, { method: "POST" }),
+    stopBeacon: (name: string) => fetchApi<{ stopped: boolean }>(`/beacons/${encodeURIComponent(name)}/stop`, { method: "POST" }),
+    restartBeacon: (name: string) => fetchApi<{ restarted: boolean }>(`/beacons/${encodeURIComponent(name)}/restart`, { method: "POST" }),
+
     // Dynamic broadcast definitions (v1)
     getBroadcastDefinitions: () =>
       fetchApi<DynamicBroadcastSpec[]>("/v1/broadcast-definitions"),
@@ -246,6 +317,15 @@ export function useApi() {
         body: JSON.stringify({ source }),
       }),
 
+    // Environment variables (v1 — GET is read-scoped, mutations admin-scoped)
+    getEnvVars: () => fetchApi<EnvVar[]>("/v1/env"),
+    createEnvVar: (input: { key: string; value: string; secret?: boolean; targets?: EnvTarget[] }) =>
+      fetchApi<EnvVar>("/v1/env", { method: "POST", body: JSON.stringify(input) }),
+    updateEnvVar: (id: string, patch: Partial<{ value: string; secret: boolean; targets: EnvTarget[] }>) =>
+      fetchApi<EnvVar>(`/v1/env/${id}`, { method: "PATCH", body: JSON.stringify(patch) }),
+    deleteEnvVar: (id: string) =>
+      fetchApi<{ deleted: boolean }>(`/v1/env/${id}`, { method: "DELETE" }),
+
     // API Keys (v1 admin routes — session cookie provides admin scope)
     getApiKeys: () => fetchApi<Array<{ id: string; name: string; keyPrefix: string; scopes: string[]; createdAt: string; lastUsed: string | null; expiresAt: string | null; revoked: boolean }>>("/v1/keys"),
     createApiKey: (name: string, scopes: string[]) =>

package/src/config/schema.ts

@@ -1,6 +1,8 @@
 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";
 
@@ -37,11 +39,26 @@ 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
@@ -52,6 +69,7 @@ export interface StationConfig {
   logStorage?: LogStorageAdapter;
   signalsDir?: string;
   broadcastsDir?: string;
+  beaconsDir?: string;
   stationDir: string;
   runner: RunnerConfig;
   broadcastRunner: BroadcastRunnerConfig;
@@ -108,10 +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

@@ -137,8 +137,15 @@ export class FileKeyStorage implements ApiKeyStorageAdapter {
   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;
-    this.flush();
+    // 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 {
@@ -264,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);
   }
 
@@ -332,8 +347,20 @@ 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
@@ -341,7 +368,7 @@ export class KeyStore {
    * at the given path. (Previously this returned a SqliteKeyStorage; SQLite
    * is now opt-in to avoid native build dependencies.)
    */
-  constructor(storageOrPath: ApiKeyStorageAdapter | string) {
+  constructor(storageOrPath: ApiKeyStorageAdapter | string, options?: KeyStoreOptions) {
     if (typeof storageOrPath === "string") {
       const filePath = storageOrPath.endsWith(".db")
         ? storageOrPath.replace(/\.db$/, ".json")
@@ -350,13 +377,27 @@ export class KeyStore {
     } else {
       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();
 
@@ -370,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;
 }