@digitalpaws/starr 0.0.1

package/src/types/plugin.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { ContentTypeDescriptor } from "@digitalpaws/starr-types-core";
+
+export interface PluginMeta {
+  id: string;
+  version: string;
+  starrApiVersion: string;
+}
+
+export interface ConnectionTestResult {
+  ok: boolean;
+  message?: string;
+}
+
+export interface PluginLifecycle {
+  start?(): void | Promise<void>;
+  stop?(): void | Promise<void>;
+  testConnection?(
+    values: Record<string, unknown>,
+  ): ConnectionTestResult | Promise<ConnectionTestResult>;
+}
+
+export interface Logger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+  child(tag: string): Logger;
+}
+
+export interface StarrEvent<P = unknown> {
+  readonly type: string;
+  readonly id: string;
+  readonly traceId: string;
+  readonly correlationId?: string;
+  readonly source: string;
+  readonly timestamp: string;       // ISO 8601
+  readonly schemaVersion: number;
+  readonly payload: P;
+  /** Convenience: emit a correlated reply. */
+  reply<R>(type: string, payload: R): void;
+}
+
+export interface EmitOpts {
+  correlationId?: string;
+}
+
+export interface RequestOpts {
+  responseType: string;
+  windowMs: number;
+  max?: number;
+}
+
+export type Unsubscribe = () => void;
+
+export type EventHandler<P = unknown> = (event: StarrEvent<P>) => void | Promise<void>;
+
+export interface EventBus {
+  emit<P>(type: string, payload: P, opts?: EmitOpts): void;
+  on<P>(type: string, handler: EventHandler<P>): Unsubscribe;
+  request<Res>(type: string, payload: unknown, opts: RequestOpts): Promise<StarrEvent<Res>[]>;
+}
+
+export interface PluginStorage {
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  /** List all keys (optionally filtered by prefix), sorted lexically. */
+  list<T>(prefix?: string): Promise<Array<{ key: string; value: T }>>;
+  /** Delete all keys for this plugin's namespace. Used during rollback. */
+  deleteAll(): Promise<void>;
+}
+
+export interface ContentTypeRegistry {
+  /**
+   * Register a content-type descriptor. Throws on:
+   * - Malformed descriptor (empty identity, list without itemType,
+   *   enum without options)
+   * - Duplicate id already registered by another plugin
+   */
+  register(descriptor: ContentTypeDescriptor): void;
+}
+
+export interface ConfigField {
+  type: string;
+  label: string;
+  required?: boolean;
+  default?: unknown;
+  options?: string[];
+  description?: string;
+  group?: string;
+}
+
+export type ConfigSchema<T> = { [K in keyof T]: ConfigField };
+
+export interface PluginContext {
+  readonly apiVersion: string;
+  define(meta: PluginMeta): void;
+  config<T>(schema: ConfigSchema<T>): Readonly<T>;
+  events: EventBus;
+  storage: PluginStorage;
+  contentTypes: ContentTypeRegistry;
+  logger: Logger;
+}
+
+export type RegisterFn = (
+  ctx: PluginContext
+) => void | PluginLifecycle | Promise<void | PluginLifecycle>;

package/src/web/index.ts

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import Fastify from "fastify";
+import fastifyStatic from "@fastify/static";
+import fastifyCookie from "@fastify/cookie";
+import fastifyFormbody from "@fastify/formbody";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Logger } from "../types/plugin.js";
+import type { AuthService } from "../auth/auth-service.js";
+import type { OidcProviderService } from "../auth/oidc/oidc-provider-service.js";
+import type { OidcFlow } from "../auth/oidc/oidc-flow.js";
+import type { UserService } from "../auth/oidc/user-service.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ── Deferred AuthService reference ───────────────────────
+// Set by main.ts via initAuthService() after AuthService is created.
+let authService: AuthService | null = null;
+
+export function initAuthService(auth: AuthService): void {
+  authService = auth;
+}
+
+// ── Deferred OIDC service references ─────────────────────
+let oidcProviderService: OidcProviderService | null = null;
+let oidcFlow: OidcFlow | null = null;
+let userService: UserService | null = null;
+
+export function initOidcServices(
+  oidcProviders: OidcProviderService,
+  flow: OidcFlow,
+  users: UserService,
+): void {
+  oidcProviderService = oidcProviders;
+  oidcFlow = flow;
+  userService = users;
+}
+
+// ── Server factory ───────────────────────────────────────
+
+export async function createWebServer(logger: Logger) {
+  // forceCloseConnections ensures SSE and other persistent connections
+  // are forcefully torn down on close(), preventing shutdown hangs
+  // that keep the port bound (the root cause of EADDRINUSE on restart).
+  const server = Fastify({ logger: false, forceCloseConnections: true });
+
+  // Parse cookies (needed for session)
+  await server.register(fastifyCookie);
+
+  // Parse form/multipart bodies (needed for auth, config)
+  await server.register(fastifyFormbody);
+
+  // ---- AUTH HOOK ----
+  // All /api/* routes require a valid session, except an explicit
+  // allowlist of public endpoints (login, setup, OIDC initiation, etc.).
+  // Non-API routes (static files) are always public.
+  server.addHook("onRequest", async (request, reply) => {
+    // Non-API routes (static files) are always public
+    if (!request.url.startsWith("/api/")) {
+      return;
+    }
+
+    // Public paths that don't require authentication
+    const publicPaths = [
+      "/api/auth/login",
+      "/api/auth/setup",
+      "/api/auth/needs-setup",
+      "/api/auth/status",
+      "/api/auth/logout",          // safe — only clears cookie
+      "/api/oidc/providers",       // login page needs this before auth
+      "/api/oidc/login/",          // initiates OIDC flow
+      "/api/oidc/callback/",       // OIDC provider redirects here
+    ];
+
+    for (const pub of publicPaths) {
+      if (request.url === pub || request.url.startsWith(pub)) {
+        return;  // skip auth for public paths
+      }
+    }
+
+    // All other /api/* routes require a valid session
+    const sid = request.cookies["starr_sid"];
+    if (!sid) {
+      reply.status(401).send({ error: "Unauthorized" });
+      return;
+    }
+
+    if (!authService) {
+      reply.status(500).send({ error: "auth service not available" });
+      return;
+    }
+
+    const result = authService.validateToken(sid);
+    if (!result) {
+      reply.status(401).send({ error: "Invalid session" });
+      return;
+    }
+
+    // Attach user info including role and id
+    (request as any).user = {
+      id: result.userId,
+      username: result.userId,
+      role: result.role ?? "user",
+    };
+  });
+
+  // ---- REGISTER API ROUTES ----
+  // Each route module is registered as a Fastify plugin.
+  // Dynamic import with try/catch means a missing route module won't crash the server.
+
+  const routeModules = [
+    "./routes/auth.js",
+    "./routes/discovery.js",
+    "./routes/content-types.js",
+    "./routes/requests.js",
+    "./routes/config.js",
+    "./routes/activity.js",
+    "./routes/sse.js",
+    "./routes/oidc.js",
+    "./routes/library.js",
+    "./routes/library-management.js",
+    "./routes/library-import.js",
+  ];
+
+  for (const modPath of routeModules) {
+    try {
+      const mod = await import(modPath);
+      await server.register(mod.default);
+    } catch (err: any) {
+      if (err.code === "ERR_MODULE_NOT_FOUND") {
+        logger.warn(`route module not found (skipping): ${modPath}`);
+      } else {
+        logger.error(`failed to register route module: ${modPath}`, { error: String(err) });
+      }
+    }
+  }
+
+  // ---- INIT OIDC ROUTES ----
+  // OIDC routes need the services hooked up after registration
+  try {
+    const { initOidcRoutes } = await import("./routes/oidc.js");
+    if (authService && oidcProviderService && oidcFlow && userService) {
+      initOidcRoutes(authService, oidcProviderService, oidcFlow, userService);
+    } else {
+      logger.warn("OIDC services not fully initialized — skipping OIDC route init");
+    }
+  } catch (err: any) {
+    logger.error("failed to init OIDC routes", { error: String(err) });
+  }
+
+  // ---- STATIC FILE SERVING (SPA) ----
+  // In production, the Svelte build output is at ../../web-ui/dist
+  // In development, the Vite dev server proxies to the host; static files aren't served.
+  const spaDist = path.resolve(__dirname, "../../../web-ui/dist");
+  try {
+    await server.register(fastifyStatic, {
+      root: spaDist,
+      prefix: "/",
+      wildcard: false,
+    });
+
+    // SPA fallback: serve index.html for any non-API, non-file route
+    server.setNotFoundHandler(async (request, reply) => {
+      if (request.url.startsWith("/api/")) {
+        reply.status(404).send({ error: "not found" });
+        return;
+      }
+      // Serve index.html for client-side routing
+      await reply.sendFile("index.html");
+    });
+  } catch {
+    logger.warn(
+      "SPA static files not found (web-ui/dist missing); " +
+      "run `pnpm --filter starr-web-ui build` first"
+    );
+  }
+
+  logger.info("web server created");
+  return server;
+}

package/src/web/routes/activity.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { FastifyPluginAsync } from "fastify";
+import type { Starr } from "../../host.js";
+
+let starrInstance: Starr | null = null;
+
+export function initActivityRoutes(starr: Starr): void {
+  starrInstance = starr;
+}
+
+const activityRoutes: FastifyPluginAsync = async (server) => {
+  server.get<{ Params: { id: string } }>(
+    "/api/requests/:id/activity",
+    async (request, reply) => {
+      if (!starrInstance) {
+        reply.status(500).send({ error: "host not available" });
+        return;
+      }
+
+      const req = starrInstance.getStateStore().getByRequestId(request.params.id);
+      if (!req) {
+        reply.status(404).send({ error: "request not found" });
+        return;
+      }
+
+      // Use the trace-store wrapper module (Task 020 data surface).
+      // Gracefully degrades to empty array if the wrapper isn't wired yet.
+      try {
+        const { getTraceEvents } = await import("../../state/trace-store.js");
+        const events = getTraceEvents(req.requestId);
+        return { requestId: req.requestId, events };
+      } catch {
+        return { requestId: req.requestId, events: [] };
+      }
+    },
+  );
+};
+
+export default activityRoutes;

package/src/web/routes/auth.ts

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { FastifyPluginAsync } from "fastify";
+import type { AuthService } from "../../auth/auth-service.js";
+import { rateLimit } from "../../auth/rate-limiter.js";
+
+/**
+ * This module needs access to the AuthService.
+ * We provide it via a module-level setter called from main.ts.
+ */
+let authService: AuthService | null = null;
+
+export function initAuthRoutes(auth: AuthService): void {
+  authService = auth;
+}
+
+const SESSION_COOKIE = "starr_sid";
+const COOKIE_OPTS = {
+  httpOnly: true,
+  sameSite: "strict" as const,
+  path: "/",
+  secure: false,
+  // TTL from env or default 7 days (matches AuthService default)
+  maxAge: parseInt(process.env.STARR_SESSION_TTL_HOURS ?? "168", 10) * 3600,
+};
+
+const authRoutes: FastifyPluginAsync = async (server) => {
+  // GET /api/auth/needs-setup — check if admin account exists
+  server.get("/api/auth/needs-setup", async (_request, _reply) => {
+    const needsSetup = authService?.needsSetup() ?? true;
+    return { needsSetup };
+  });
+
+  // GET /api/auth/status — check if logged in
+  server.get("/api/auth/status", async (request, reply) => {
+    const sid = request.cookies[SESSION_COOKIE];
+    if (!sid || !authService) {
+      reply.status(401).send({ error: "Unauthorized" });
+      return;
+    }
+    const result = authService.validateToken(sid);
+    if (!result) {
+      reply.status(401).send({ error: "Invalid session" });
+      return;
+    }
+    // Return richer user info (display name, avatar, role)
+    const userInfo = authService.getUserInfo(result.userId);
+    return {
+      user: result.userId,
+      displayName: userInfo?.displayName ?? result.userId,
+      avatarUrl: userInfo?.avatarUrl ?? null,
+      role: result.role ?? "user",
+    };
+  });
+
+  // POST /api/auth/setup — first-run admin creation
+  server.post<{ Body: { username?: string; password?: string } }>(
+    "/api/auth/setup",
+    async (request, reply) => {
+      if (!authService) {
+        reply.status(500).send({ error: "auth service not available" });
+        return;
+      }
+      const { username, password } = request.body;
+      if (!username || !password) {
+        reply.status(400).send({ error: "username and password are required" });
+        return;
+      }
+
+      try {
+        await authService.setup(username, password);
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : "Setup failed";
+        if (msg.includes("already exists")) {
+          reply.status(403).send({ error: msg });
+          return;
+        }
+        reply.status(400).send({ error: msg });
+        return;
+      }
+
+      // Log in immediately after setup
+      const jwt = await authService.login(username, password);
+      if (jwt) {
+        reply.setCookie(SESSION_COOKIE, jwt, COOKIE_OPTS);
+        return { ok: true };
+      }
+      reply.status(500).send({ error: "Account created but login failed" });
+    },
+  );
+
+  // POST /api/auth/login — rate-limited (5 attempts per minute per IP)
+  server.post<{ Body: { username?: string; password?: string } }>(
+    "/api/auth/login",
+    { preHandler: rateLimit(5, 1) },
+    async (request, reply) => {
+      if (!authService) {
+        reply.status(500).send({ error: "auth service not available" });
+        return;
+      }
+      const { username, password } = request.body;
+      if (!username || !password) {
+        reply.status(400).send({ error: "username and password are required" });
+        return;
+      }
+
+      const jwt = await authService.login(username, password);
+      if (!jwt) {
+        reply.status(401).send({ error: "Invalid credentials" });
+        return;
+      }
+
+      reply.setCookie(SESSION_COOKIE, jwt, COOKIE_OPTS);
+      return { ok: true };
+    },
+  );
+
+  // POST /api/auth/logout
+  server.post("/api/auth/logout", async (request, reply) => {
+    const sid = request.cookies[SESSION_COOKIE];
+    if (sid && authService) {
+      const result = authService.validateToken(sid);
+      if (result) {
+        authService.logout(result.sessionId);
+      }
+    }
+    reply.clearCookie(SESSION_COOKIE, { path: "/" });
+    return { ok: true };
+  });
+
+  // POST /api/auth/change-password
+  server.post<{ Body: { currentPassword?: string; newPassword?: string } }>(
+    "/api/auth/change-password",
+    async (request, reply) => {
+      if (!authService) {
+        reply.status(500).send({ error: "auth service not available" });
+        return;
+      }
+
+      const { currentPassword, newPassword } = request.body;
+      if (!currentPassword || !newPassword) {
+        reply.status(400).send({ error: "currentPassword and newPassword are required" });
+        return;
+      }
+
+      const user = (request as any).user;
+      const username = user?.username;
+
+      if (!username) {
+        reply.status(401).send({ error: "Unauthorized" });
+        return;
+      }
+
+      try {
+        await authService.changePassword(username, currentPassword, newPassword);
+        // Create a new session with the new password context
+        const newJwt = await authService.login(username, newPassword);
+        if (newJwt) {
+          reply.setCookie(SESSION_COOKIE, newJwt, COOKIE_OPTS);
+        }
+        return { ok: true };
+      } catch (err: unknown) {
+        reply.status(400).send({ error: err instanceof Error ? err.message : "Password change failed" });
+      }
+    },
+  );
+};
+
+export default authRoutes;