station-kit 1.0.0

package/src/server/log-store.ts

@@ -0,0 +1,56 @@
+import Database from "better-sqlite3";
+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`,
+    );
+  }
+
+  add(entry: LogEntry): void {
+    this.insertStmt.run(entry.runId, entry.signalName, entry.level, entry.message, entry.timestamp);
+  }
+
+  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();
+  }
+}

package/src/server/metadata.ts

@@ -0,0 +1,180 @@
+/**
+ * Zod schema serializer and metadata types for station API.
+ * Introspects Zod schema internals to produce JSON-serializable descriptions.
+ */
+
+// ── Types ──
+
+export interface SchemaField {
+  type: string;
+  required: boolean;
+  properties?: Record<string, SchemaField>;
+  items?: SchemaField;
+  values?: string[];
+}
+
+export interface SignalMeta {
+  name: string;
+  filePath: string;
+  inputSchema: SchemaField | null;
+  outputSchema: SchemaField | null;
+  interval: string | null;
+  timeout: number;
+  maxAttempts: number;
+  maxConcurrency: number | null;
+  hasSteps: boolean;
+  stepNames: string[];
+}
+
+export interface BroadcastMeta {
+  name: string;
+  filePath: string;
+  nodes: Array<{ name: string; signalName: string; dependsOn: string[] }>;
+  failurePolicy: string;
+  timeout: number | null;
+  interval: string | null;
+}
+
+// ── Zod Schema Serializer ──
+
+/**
+ * Resolves the type identifier and def from a Zod schema.
+ * Supports both Zod v3 (_def.typeName) and Zod v4 (_zod.def.type).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function zodDef(schema: any): { type: string; def: any } | null {
+  if (schema?._zod?.def?.type) {
+    return { type: schema._zod.def.type, def: schema._zod.def };
+  }
+  if (schema?._def?.typeName) {
+    return { type: schema._def.typeName, def: schema._def };
+  }
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function serializeZodSchema(schema: any): SchemaField {
+  const z = zodDef(schema);
+  if (!z) return { type: "unknown", required: true };
+
+  const { type, def } = z;
+
+  switch (type) {
+    case "object":
+    case "ZodObject": {
+      const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+      const properties: Record<string, SchemaField> = {};
+      if (shape && typeof shape === "object") {
+        for (const [key, value] of Object.entries(shape)) {
+          properties[key] = serializeZodSchema(value);
+        }
+      }
+      return { type: "object", required: true, properties };
+    }
+
+    case "string":
+    case "ZodString":
+      return { type: "string", required: true };
+
+    case "number":
+    case "ZodNumber":
+      return { type: "number", required: true };
+
+    case "boolean":
+    case "ZodBoolean":
+      return { type: "boolean", required: true };
+
+    case "array":
+    case "ZodArray":
+      return {
+        type: "array",
+        required: true,
+        items: (def.element ?? def.type) ? serializeZodSchema(def.element ?? def.type) : undefined,
+      };
+
+    case "optional":
+    case "ZodOptional":
+      return { ...serializeZodSchema(def.innerType), required: false };
+
+    case "nullable":
+    case "ZodNullable": {
+      const inner = serializeZodSchema(def.innerType);
+      return { ...inner, type: inner.type + " | null" };
+    }
+
+    case "default":
+    case "ZodDefault":
+      return { ...serializeZodSchema(def.innerType), required: false };
+
+    case "enum":
+    case "ZodEnum": {
+      // v4: def.entries is {a:'a', b:'b'}; v3: def.values is string[]
+      let vals: string[] | undefined;
+      if (def.entries && typeof def.entries === "object") {
+        vals = Object.values(def.entries) as string[];
+      } else if (Array.isArray(def.values)) {
+        vals = def.values as string[];
+      }
+      return { type: "enum", required: true, values: vals };
+    }
+
+    case "literal":
+    case "ZodLiteral": {
+      // v4: def.values is [value]; v3: def.value
+      const val = Array.isArray(def.values) ? def.values[0] : def.value;
+      return { type: `"${String(val)}"`, required: true };
+    }
+
+    case "union":
+    case "ZodUnion": {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const opts = (def.options as any[])?.map((o: any) => serializeZodSchema(o).type);
+      return { type: opts?.join(" | ") ?? "unknown", required: true };
+    }
+
+    case "record":
+    case "ZodRecord":
+      return { type: "record", required: true };
+
+    case "any":
+    case "ZodAny":
+      return { type: "any", required: true };
+
+    case "void":
+    case "undefined":
+    case "ZodVoid":
+    case "ZodUndefined":
+      return { type: "void", required: true };
+
+    default:
+      return { type: "unknown", required: true };
+  }
+}
+
+// ── Template Generator ──
+
+export function generateTemplate(field: SchemaField): unknown {
+  switch (field.type) {
+    case "object":
+      if (field.properties) {
+        const obj: Record<string, unknown> = {};
+        for (const [key, f] of Object.entries(field.properties)) {
+          obj[key] = generateTemplate(f);
+        }
+        return obj;
+      }
+      return {};
+    case "string":
+      return "";
+    case "number":
+      return 0;
+    case "boolean":
+      return false;
+    case "array":
+      return [];
+    case "enum":
+      return field.values?.[0] ?? "";
+    default:
+      return null;
+  }
+}

package/src/server/middleware/auth.ts

@@ -0,0 +1,50 @@
+import { createMiddleware } from "hono/factory";
+import type { KeyStore } from "../auth/keys.js";
+import { verifySessionToken, type SessionConfig } from "../auth/session.js";
+
+export interface AuthDeps {
+  keyStore?: KeyStore;
+  sessionConfig?: SessionConfig;
+}
+
+/** Sets c.get("authType"), c.get("apiKeyId"), c.get("scopes") */
+export function authResolver(deps: AuthDeps) {
+  return createMiddleware(async (c, next) => {
+    // Check for API key in Authorization header
+    const authHeader = c.req.header("authorization");
+    if (authHeader?.startsWith("Bearer ") && deps.keyStore) {
+      const token = authHeader.slice(7);
+      if (token.startsWith("sk_")) {
+        const key = deps.keyStore.verify(token);
+        if (key) {
+          c.set("authType", "api-key");
+          c.set("apiKeyId", key.id);
+          c.set("scopes", key.scopes);
+          return next();
+        }
+        return c.json({ error: "unauthorized", message: "Invalid or revoked API key." }, 401);
+      }
+    }
+
+    // Check for session cookie
+    const cookie = c.req.header("cookie");
+    if (cookie && deps.sessionConfig) {
+      const match = cookie.match(/station_session=([^;]+)/);
+      if (match) {
+        const valid = verifySessionToken(match[1], deps.sessionConfig);
+        if (valid) {
+          c.set("authType", "session");
+          c.set("apiKeyId", undefined);
+          c.set("scopes", ["trigger", "read", "cancel", "admin"]);
+          return next();
+        }
+      }
+    }
+
+    // No auth
+    c.set("authType", "none");
+    c.set("apiKeyId", undefined);
+    c.set("scopes", []);
+    return next();
+  });
+}

package/src/server/middleware/rate-limit.ts

@@ -0,0 +1,61 @@
+import { createMiddleware } from "hono/factory";
+import type { Context } from "hono";
+
+interface RateLimitOptions {
+  /** Time window in ms. Default: 60_000 (1 minute). */
+  windowMs?: number;
+  /** Max requests per window. Default: 100. */
+  max?: number;
+  /** Function to derive the rate limit key from request. Default: API key ID or IP. */
+  keyFn?: (c: Context) => string;
+}
+
+interface BucketEntry {
+  count: number;
+  resetAt: number;
+}
+
+export function rateLimiter(options: RateLimitOptions = {}) {
+  const windowMs = options.windowMs ?? 60_000;
+  const max = options.max ?? 100;
+  const keyFn = options.keyFn ?? ((c: Context) => {
+    return (c.get("apiKeyId") as string) ?? c.req.header("x-forwarded-for") ?? "anonymous";
+  });
+
+  const buckets = new Map<string, BucketEntry>();
+
+  // Cleanup old entries periodically
+  const cleanup = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of buckets) {
+      if (now > entry.resetAt) buckets.delete(key);
+    }
+  }, windowMs * 2);
+  cleanup.unref();
+
+  return createMiddleware(async (c, next) => {
+    const key = keyFn(c);
+    const now = Date.now();
+
+    let entry = buckets.get(key);
+    if (!entry || now > entry.resetAt) {
+      entry = { count: 0, resetAt: now + windowMs };
+      buckets.set(key, entry);
+    }
+
+    entry.count++;
+
+    c.header("X-RateLimit-Limit", String(max));
+    c.header("X-RateLimit-Remaining", String(Math.max(0, max - entry.count)));
+    c.header("X-RateLimit-Reset", String(Math.ceil(entry.resetAt / 1000)));
+
+    if (entry.count > max) {
+      return c.json(
+        { error: "rate_limited", message: "Too many requests. Try again later." },
+        429,
+      );
+    }
+
+    return next();
+  });
+}

package/src/server/middleware/scope-guard.ts

@@ -0,0 +1,20 @@
+import { createMiddleware } from "hono/factory";
+
+/** Require at least one of the specified scopes. */
+export function requireScope(...requiredScopes: string[]) {
+  return createMiddleware(async (c, next) => {
+    const authType = c.get("authType") as string | undefined;
+    if (!authType || authType === "none") {
+      return c.json({ error: "unauthorized", message: "Authentication required." }, 401);
+    }
+    const scopes = (c.get("scopes") as string[]) ?? [];
+    const hasScope = requiredScopes.some((s) => scopes.includes(s));
+    if (!hasScope) {
+      return c.json(
+        { error: "forbidden", message: `Required scope: ${requiredScopes.join(" or ")}.` },
+        403,
+      );
+    }
+    return next();
+  });
+}

package/src/server/routes/broadcasts.ts

@@ -0,0 +1,160 @@
+import { Hono } from "hono";
+import type { BroadcastRunner, BroadcastQueueAdapter } from "station-broadcast";
+import type { StationBroadcastSubscriber } from "../subscriber.js";
+
+export interface BroadcastDeps {
+  broadcastRunner?: BroadcastRunner;
+  broadcastAdapter?: BroadcastQueueAdapter;
+  broadcastSubscriber?: StationBroadcastSubscriber;
+  logBuffer?: import("../log-buffer.js").LogBuffer;
+  logStore?: import("../log-store.js").LogStore;
+}
+
+export function broadcastRoutes(deps: BroadcastDeps) {
+  const app = new Hono();
+
+  // GET /broadcasts — list all broadcasts with metadata
+  app.get("/broadcasts", async (c) => {
+    if (deps.broadcastSubscriber) {
+      const meta = deps.broadcastSubscriber.getAllBroadcastMeta();
+      if (meta.length > 0) {
+        return c.json({ data: meta });
+      }
+    }
+
+    // Fallback to registry
+    if (!deps.broadcastRunner) {
+      return c.json({ data: [] });
+    }
+    const result = deps.broadcastRunner.listRegistered();
+    return c.json({ data: result });
+  });
+
+  // GET /broadcasts/:name — single broadcast metadata
+  app.get("/broadcasts/:name", async (c) => {
+    const name = c.req.param("name");
+
+    if (deps.broadcastSubscriber) {
+      const meta = deps.broadcastSubscriber.getBroadcastMeta(name);
+      if (meta) {
+        return c.json({ data: meta });
+      }
+    }
+
+    // Fallback: check registry
+    if (deps.broadcastRunner) {
+      const entry = deps.broadcastRunner.listRegistered().find((b) => b.name === name);
+      if (entry) {
+        return c.json({ data: entry });
+      }
+    }
+
+    return c.json({ error: "not_found", message: `Broadcast "${name}" not found.` }, 404);
+  });
+
+  // POST /broadcasts/:name/trigger
+  app.post("/broadcasts/:name/trigger", async (c) => {
+    const name = c.req.param("name");
+    if (!deps.broadcastRunner) {
+      return c.json({ error: "read_only", message: "Station is in read-only mode." }, 403);
+    }
+
+    const body = await c.req.json().catch(() => ({}));
+    const input = body.input ?? {};
+
+    try {
+      const id = await deps.broadcastRunner.trigger(name, input);
+      return c.json({ data: { id } });
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      return c.json({ error: "trigger_failed", message }, 400);
+    }
+  });
+
+  // GET /broadcasts/:name/runs
+  app.get("/broadcasts/:name/runs", async (c) => {
+    const name = c.req.param("name");
+    if (!deps.broadcastAdapter) {
+      return c.json({ data: [], meta: { total: 0 } });
+    }
+    const runs = await deps.broadcastAdapter.listBroadcastRuns(name);
+    return c.json({
+      data: runs.map(serializeBroadcastRun),
+      meta: { total: runs.length },
+    });
+  });
+
+  // GET /broadcast-runs/:id
+  app.get("/broadcast-runs/:id", async (c) => {
+    const id = c.req.param("id");
+    if (!deps.broadcastAdapter) {
+      return c.json({ error: "not_found", message: "No broadcast adapter configured." }, 404);
+    }
+    const run = await deps.broadcastAdapter.getBroadcastRun(id);
+    if (!run) {
+      return c.json({ error: "not_found", message: "Broadcast run not found." }, 404);
+    }
+    return c.json({ data: serializeBroadcastRun(run) });
+  });
+
+  // GET /broadcast-runs/:id/nodes
+  app.get("/broadcast-runs/:id/nodes", async (c) => {
+    const id = c.req.param("id");
+    if (!deps.broadcastAdapter) {
+      return c.json({ data: [] });
+    }
+    const nodes = await deps.broadcastAdapter.getNodeRuns(id);
+    return c.json({
+      data: nodes.map((nr) => ({
+        ...nr,
+        startedAt: nr.startedAt?.toISOString?.() ?? nr.startedAt,
+        completedAt: nr.completedAt?.toISOString?.() ?? nr.completedAt,
+      })),
+    });
+  });
+
+  // GET /broadcast-runs/:id/logs — aggregate logs from all node signal runs
+  app.get("/broadcast-runs/:id/logs", async (c) => {
+    const id = c.req.param("id");
+    if (!deps.broadcastAdapter || (!deps.logStore && !deps.logBuffer)) {
+      return c.json({ data: [] });
+    }
+    const nodes = await deps.broadcastAdapter.getNodeRuns(id);
+    const allLogs: Array<{ runId: string; signalName: string; level: string; message: string; timestamp: string; nodeName: string }> = [];
+    for (const nr of nodes) {
+      if (nr.signalRunId) {
+        const logs = deps.logStore?.get(nr.signalRunId) ?? deps.logBuffer?.get(nr.signalRunId) ?? [];
+        for (const log of logs) {
+          allLogs.push({ ...log, nodeName: nr.nodeName });
+        }
+      }
+    }
+    allLogs.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    return c.json({ data: allLogs });
+  });
+
+  // POST /broadcast-runs/:id/cancel
+  app.post("/broadcast-runs/:id/cancel", async (c) => {
+    const id = c.req.param("id");
+    if (!deps.broadcastRunner) {
+      return c.json({ error: "read_only", message: "Station is in read-only mode." }, 403);
+    }
+    const success = await deps.broadcastRunner.cancel(id);
+    if (!success) {
+      return c.json({ error: "cannot_cancel", message: "Broadcast run cannot be cancelled." }, 400);
+    }
+    return c.json({ data: { cancelled: true } });
+  });
+
+  return app;
+}
+
+function serializeBroadcastRun(run: any): Record<string, unknown> {
+  return {
+    ...run,
+    nextRunAt: run.nextRunAt?.toISOString?.() ?? run.nextRunAt,
+    startedAt: run.startedAt?.toISOString?.() ?? run.startedAt,
+    completedAt: run.completedAt?.toISOString?.() ?? run.completedAt,
+    createdAt: run.createdAt?.toISOString?.() ?? run.createdAt,
+  };
+}

package/src/server/routes/health.ts

@@ -0,0 +1,37 @@
+import { Hono } from "hono";
+import type { SignalQueueAdapter } from "station-signal";
+import type { BroadcastQueueAdapter } from "station-broadcast";
+
+export interface HealthDeps {
+  signalAdapter: SignalQueueAdapter;
+  broadcastAdapter?: BroadcastQueueAdapter;
+}
+
+export function healthRoutes(deps: HealthDeps) {
+  const app = new Hono();
+
+  app.get("/health", async (c) => {
+    let signalOk = false;
+    let broadcastOk = false;
+
+    try {
+      signalOk = await deps.signalAdapter.ping();
+    } catch {}
+
+    if (deps.broadcastAdapter) {
+      try {
+        broadcastOk = await deps.broadcastAdapter.ping();
+      } catch {}
+    }
+
+    return c.json({
+      data: {
+        ok: signalOk && (!deps.broadcastAdapter || broadcastOk),
+        signal: signalOk,
+        broadcast: deps.broadcastAdapter ? broadcastOk : null,
+      },
+    });
+  });
+
+  return app;
+}