npm - @blackbelt-technology/pi-agent-dashboard - Versions diffs - 0.2.0 - Mend

@blackbelt-technology/pi-agent-dashboard 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (212) hide show

package/AGENTS.md +342 -0
package/README.md +619 -0
package/docs/architecture.md +646 -0
package/package.json +92 -0
package/packages/extension/package.json +33 -0
package/packages/extension/src/__tests__/ask-user-tool.test.ts +85 -0
package/packages/extension/src/__tests__/command-handler.test.ts +712 -0
package/packages/extension/src/__tests__/connection.test.ts +344 -0
package/packages/extension/src/__tests__/credentials-updated.test.ts +26 -0
package/packages/extension/src/__tests__/dev-build.test.ts +79 -0
package/packages/extension/src/__tests__/event-forwarder.test.ts +89 -0
package/packages/extension/src/__tests__/git-info.test.ts +112 -0
package/packages/extension/src/__tests__/git-link-builder.test.ts +102 -0
package/packages/extension/src/__tests__/openspec-activity-detector.test.ts +232 -0
package/packages/extension/src/__tests__/openspec-poller.test.ts +119 -0
package/packages/extension/src/__tests__/process-metrics.test.ts +47 -0
package/packages/extension/src/__tests__/process-scanner.test.ts +202 -0
package/packages/extension/src/__tests__/prompt-expander.test.ts +54 -0
package/packages/extension/src/__tests__/server-auto-start.test.ts +167 -0
package/packages/extension/src/__tests__/server-launcher.test.ts +44 -0
package/packages/extension/src/__tests__/server-probe.test.ts +25 -0
package/packages/extension/src/__tests__/session-switch.test.ts +139 -0
package/packages/extension/src/__tests__/session-sync.test.ts +55 -0
package/packages/extension/src/__tests__/source-detector.test.ts +73 -0
package/packages/extension/src/__tests__/stats-extractor.test.ts +92 -0
package/packages/extension/src/__tests__/ui-proxy.test.ts +583 -0
package/packages/extension/src/__tests__/watchdog.test.ts +161 -0
package/packages/extension/src/ask-user-tool.ts +63 -0
package/packages/extension/src/bridge-context.ts +64 -0
package/packages/extension/src/bridge.ts +926 -0
package/packages/extension/src/command-handler.ts +538 -0
package/packages/extension/src/connection.ts +204 -0
package/packages/extension/src/dev-build.ts +39 -0
package/packages/extension/src/event-forwarder.ts +40 -0
package/packages/extension/src/flow-event-wiring.ts +102 -0
package/packages/extension/src/git-info.ts +65 -0
package/packages/extension/src/git-link-builder.ts +112 -0
package/packages/extension/src/model-tracker.ts +56 -0
package/packages/extension/src/pi-env.d.ts +23 -0
package/packages/extension/src/process-metrics.ts +70 -0
package/packages/extension/src/process-scanner.ts +396 -0
package/packages/extension/src/prompt-expander.ts +87 -0
package/packages/extension/src/provider-register.ts +276 -0
package/packages/extension/src/server-auto-start.ts +87 -0
package/packages/extension/src/server-launcher.ts +82 -0
package/packages/extension/src/server-probe.ts +33 -0
package/packages/extension/src/session-sync.ts +154 -0
package/packages/extension/src/source-detector.ts +26 -0
package/packages/extension/src/ui-proxy.ts +269 -0
package/packages/extension/tsconfig.json +11 -0
package/packages/server/package.json +37 -0
package/packages/server/src/__tests__/auth-plugin.test.ts +117 -0
package/packages/server/src/__tests__/auth.test.ts +224 -0
package/packages/server/src/__tests__/auto-attach.test.ts +246 -0
package/packages/server/src/__tests__/auto-resume.test.ts +135 -0
package/packages/server/src/__tests__/auto-shutdown.test.ts +136 -0
package/packages/server/src/__tests__/browse-endpoint.test.ts +104 -0
package/packages/server/src/__tests__/bulk-archive-handler.test.ts +15 -0
package/packages/server/src/__tests__/cli-parse.test.ts +73 -0
package/packages/server/src/__tests__/client-discovery.test.ts +39 -0
package/packages/server/src/__tests__/config-api.test.ts +104 -0
package/packages/server/src/__tests__/cors.test.ts +48 -0
package/packages/server/src/__tests__/directory-service.test.ts +240 -0
package/packages/server/src/__tests__/editor-detection.test.ts +60 -0
package/packages/server/src/__tests__/editor-endpoints.test.ts +26 -0
package/packages/server/src/__tests__/editor-manager.test.ts +73 -0
package/packages/server/src/__tests__/editor-registry.test.ts +151 -0
package/packages/server/src/__tests__/event-status-extraction-flow.test.ts +55 -0
package/packages/server/src/__tests__/event-status-extraction.test.ts +58 -0
package/packages/server/src/__tests__/extension-register.test.ts +61 -0
package/packages/server/src/__tests__/file-endpoint.test.ts +49 -0
package/packages/server/src/__tests__/force-kill-handler.test.ts +109 -0
package/packages/server/src/__tests__/git-operations.test.ts +251 -0
package/packages/server/src/__tests__/headless-pid-registry.test.ts +233 -0
package/packages/server/src/__tests__/headless-shutdown-fallback.test.ts +109 -0
package/packages/server/src/__tests__/health-endpoint.test.ts +35 -0
package/packages/server/src/__tests__/heartbeat-ack.test.ts +63 -0
package/packages/server/src/__tests__/json-store.test.ts +70 -0
package/packages/server/src/__tests__/localhost-guard.test.ts +149 -0
package/packages/server/src/__tests__/memory-event-store.test.ts +260 -0
package/packages/server/src/__tests__/memory-session-manager.test.ts +80 -0
package/packages/server/src/__tests__/meta-persistence.test.ts +107 -0
package/packages/server/src/__tests__/migrate-persistence.test.ts +180 -0
package/packages/server/src/__tests__/npm-search-proxy.test.ts +153 -0
package/packages/server/src/__tests__/oauth-callback-server.test.ts +165 -0
package/packages/server/src/__tests__/openspec-archive.test.ts +87 -0
package/packages/server/src/__tests__/package-manager-wrapper.test.ts +163 -0
package/packages/server/src/__tests__/package-routes.test.ts +172 -0
package/packages/server/src/__tests__/pending-fork-registry.test.ts +69 -0
package/packages/server/src/__tests__/pending-load-manager.test.ts +144 -0
package/packages/server/src/__tests__/pending-resume-registry.test.ts +130 -0
package/packages/server/src/__tests__/pi-resource-scanner.test.ts +235 -0
package/packages/server/src/__tests__/preferences-store.test.ts +108 -0
package/packages/server/src/__tests__/process-manager.test.ts +184 -0
package/packages/server/src/__tests__/provider-auth-handlers.test.ts +93 -0
package/packages/server/src/__tests__/provider-auth-routes.test.ts +143 -0
package/packages/server/src/__tests__/provider-auth-storage.test.ts +114 -0
package/packages/server/src/__tests__/resolve-path.test.ts +38 -0
package/packages/server/src/__tests__/ring-buffer.test.ts +45 -0
package/packages/server/src/__tests__/server-pid.test.ts +89 -0
package/packages/server/src/__tests__/session-api.test.ts +244 -0
package/packages/server/src/__tests__/session-diff.test.ts +138 -0
package/packages/server/src/__tests__/session-file-dedup.test.ts +102 -0
package/packages/server/src/__tests__/session-file-reader.test.ts +85 -0
package/packages/server/src/__tests__/session-lifecycle-logging.test.ts +138 -0
package/packages/server/src/__tests__/session-order-manager.test.ts +135 -0
package/packages/server/src/__tests__/session-ordering-integration.test.ts +102 -0
package/packages/server/src/__tests__/session-scanner.test.ts +199 -0
package/packages/server/src/__tests__/shutdown-endpoint.test.ts +42 -0
package/packages/server/src/__tests__/skip-wipe.test.ts +123 -0
package/packages/server/src/__tests__/sleep-aware-heartbeat.test.ts +126 -0
package/packages/server/src/__tests__/smoke-integration.test.ts +175 -0
package/packages/server/src/__tests__/spa-fallback.test.ts +68 -0
package/packages/server/src/__tests__/subscription-handler.test.ts +155 -0
package/packages/server/src/__tests__/terminal-gateway.test.ts +61 -0
package/packages/server/src/__tests__/terminal-manager.test.ts +257 -0
package/packages/server/src/__tests__/trusted-networks-config.test.ts +84 -0
package/packages/server/src/__tests__/tunnel.test.ts +206 -0
package/packages/server/src/__tests__/ws-ping-pong.test.ts +112 -0
package/packages/server/src/auth-plugin.ts +302 -0
package/packages/server/src/auth.ts +323 -0
package/packages/server/src/browse.ts +55 -0
package/packages/server/src/browser-gateway.ts +495 -0
package/packages/server/src/browser-handlers/directory-handler.ts +137 -0
package/packages/server/src/browser-handlers/handler-context.ts +45 -0
package/packages/server/src/browser-handlers/session-action-handler.ts +271 -0
package/packages/server/src/browser-handlers/session-meta-handler.ts +95 -0
package/packages/server/src/browser-handlers/subscription-handler.ts +154 -0
package/packages/server/src/browser-handlers/terminal-handler.ts +37 -0
package/packages/server/src/cli.ts +347 -0
package/packages/server/src/config-api.ts +130 -0
package/packages/server/src/directory-service.ts +162 -0
package/packages/server/src/editor-detection.ts +60 -0
package/packages/server/src/editor-manager.ts +352 -0
package/packages/server/src/editor-proxy.ts +134 -0
package/packages/server/src/editor-registry.ts +108 -0
package/packages/server/src/event-status-extraction.ts +131 -0
package/packages/server/src/event-wiring.ts +589 -0
package/packages/server/src/extension-register.ts +92 -0
package/packages/server/src/git-operations.ts +200 -0
package/packages/server/src/headless-pid-registry.ts +207 -0
package/packages/server/src/idle-timer.ts +61 -0
package/packages/server/src/json-store.ts +32 -0
package/packages/server/src/localhost-guard.ts +117 -0
package/packages/server/src/memory-event-store.ts +193 -0
package/packages/server/src/memory-session-manager.ts +123 -0
package/packages/server/src/meta-persistence.ts +64 -0
package/packages/server/src/migrate-persistence.ts +195 -0
package/packages/server/src/npm-search-proxy.ts +143 -0
package/packages/server/src/oauth-callback-server.ts +177 -0
package/packages/server/src/openspec-archive.ts +60 -0
package/packages/server/src/package-manager-wrapper.ts +200 -0
package/packages/server/src/pending-fork-registry.ts +53 -0
package/packages/server/src/pending-load-manager.ts +110 -0
package/packages/server/src/pending-resume-registry.ts +69 -0
package/packages/server/src/pi-gateway.ts +419 -0
package/packages/server/src/pi-resource-scanner.ts +369 -0
package/packages/server/src/preferences-store.ts +116 -0
package/packages/server/src/process-manager.ts +311 -0
package/packages/server/src/provider-auth-handlers.ts +438 -0
package/packages/server/src/provider-auth-storage.ts +200 -0
package/packages/server/src/resolve-path.ts +12 -0
package/packages/server/src/routes/editor-routes.ts +86 -0
package/packages/server/src/routes/file-routes.ts +116 -0
package/packages/server/src/routes/git-routes.ts +89 -0
package/packages/server/src/routes/openspec-routes.ts +99 -0
package/packages/server/src/routes/package-routes.ts +172 -0
package/packages/server/src/routes/provider-auth-routes.ts +244 -0
package/packages/server/src/routes/provider-routes.ts +101 -0
package/packages/server/src/routes/route-deps.ts +23 -0
package/packages/server/src/routes/session-routes.ts +91 -0
package/packages/server/src/routes/system-routes.ts +271 -0
package/packages/server/src/server-pid.ts +84 -0
package/packages/server/src/server.ts +554 -0
package/packages/server/src/session-api.ts +330 -0
package/packages/server/src/session-bootstrap.ts +80 -0
package/packages/server/src/session-diff.ts +178 -0
package/packages/server/src/session-discovery.ts +134 -0
package/packages/server/src/session-file-reader.ts +135 -0
package/packages/server/src/session-order-manager.ts +73 -0
package/packages/server/src/session-scanner.ts +233 -0
package/packages/server/src/session-stats-reader.ts +99 -0
package/packages/server/src/terminal-gateway.ts +51 -0
package/packages/server/src/terminal-manager.ts +241 -0
package/packages/server/src/tunnel.ts +329 -0
package/packages/server/tsconfig.json +11 -0
package/packages/shared/package.json +15 -0
package/packages/shared/src/__tests__/config.test.ts +358 -0
package/packages/shared/src/__tests__/deriveChangeState.test.ts +95 -0
package/packages/shared/src/__tests__/mdns-discovery.test.ts +80 -0
package/packages/shared/src/__tests__/protocol.test.ts +243 -0
package/packages/shared/src/__tests__/resolve-jiti.test.ts +17 -0
package/packages/shared/src/__tests__/server-identity.test.ts +73 -0
package/packages/shared/src/__tests__/session-meta.test.ts +125 -0
package/packages/shared/src/archive-types.ts +11 -0
package/packages/shared/src/browser-protocol.ts +534 -0
package/packages/shared/src/config.ts +245 -0
package/packages/shared/src/diff-types.ts +41 -0
package/packages/shared/src/editor-types.ts +18 -0
package/packages/shared/src/mdns-discovery.ts +248 -0
package/packages/shared/src/openspec-activity-detector.ts +109 -0
package/packages/shared/src/openspec-poller.ts +96 -0
package/packages/shared/src/protocol.ts +369 -0
package/packages/shared/src/resolve-jiti.ts +43 -0
package/packages/shared/src/rest-api.ts +255 -0
package/packages/shared/src/server-identity.ts +51 -0
package/packages/shared/src/session-meta.ts +86 -0
package/packages/shared/src/state-replay.ts +174 -0
package/packages/shared/src/stats-extractor.ts +54 -0
package/packages/shared/src/terminal-types.ts +18 -0
package/packages/shared/src/types.ts +351 -0
package/packages/shared/tsconfig.json +8 -0

package/packages/server/src/auth-plugin.ts ADDED Viewed

@@ -0,0 +1,302 @@
+/**
+ * Fastify plugin that registers OAuth auth routes and the onRequest hook.
+ * Only registered when auth is configured.
+ */
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import cookie from "@fastify/cookie";
+import crypto from "node:crypto";
+import type { AuthConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import {
+  type ResolvedProvider,
+  type TokenPayload,
+  buildProviderRegistry,
+  ensureAuthSecret,
+  signToken,
+  verifyToken,
+  parseAuthCookie,
+  isUserAllowed,
+  buildRedirectUri,
+  buildAuthorizeUrl,
+  exchangeCode,
+  fetchUserInfo,
+  COOKIE_NAME,
+} from "./auth.js";
+import { isLoopback, isBypassedHost } from "./localhost-guard.js";
+/**
+ * Returns true if the request URL matches any of the configured bypass prefixes.
+ * Exported for unit testing.
+ */
+export function isBypassed(url: string, bypassUrls: string[]): boolean {
+  return bypassUrls.some((prefix) => url.startsWith(prefix));
+}
+/** Escape HTML special characters to prevent XSS in server-rendered pages. */
+export function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+export interface AuthPluginOptions {
+  authConfig: AuthConfig;
+  port: number;
+  /** Merged trusted networks (top-level + auth.bypassHosts) */
+  resolvedTrustedNetworks?: string[];
+}
+/**
+ * State parameter encoding: encodes the return URL + CSRF nonce.
+ */
+function encodeState(returnUrl: string): string {
+  const nonce = crypto.randomBytes(8).toString("hex");
+  return Buffer.from(JSON.stringify({ returnUrl, nonce })).toString("base64url");
+}
+function decodeState(state: string): { returnUrl: string } {
+  try {
+    const parsed = JSON.parse(Buffer.from(state, "base64url").toString());
+    return { returnUrl: parsed.returnUrl || "/" };
+  } catch {
+    return { returnUrl: "/" };
+  }
+}
+/**
+ * Simple login page HTML with provider links.
+ */
+function renderLoginPage(providers: ResolvedProvider[], error?: string): string {
+  const providerLinks = providers
+    .map((p) => `<a href="/auth/start/${p.key}" style="display:block;margin:10px 0;padding:12px 24px;background:#2563eb;color:#fff;text-decoration:none;border-radius:6px;text-align:center;font-size:16px;">Sign in with ${p.name}</a>`)
+    .join("\n");
+  const errorHtml = error
+    ? `<div style="color:#ef4444;margin-bottom:16px;">${error}</div>`
+    : "";
+  return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>PI Dashboard — Sign In</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#0f172a;color:#e2e8f0;}
+.card{background:#1e293b;padding:40px;border-radius:12px;max-width:400px;width:100%;text-align:center;}
+h1{margin:0 0 24px;font-size:24px;}</style>
+</head><body><div class="card"><h1>🔐 PI Dashboard</h1>${errorHtml}${providerLinks}</div></body></html>`;
+}
+/**
+ * Access denied page HTML.
+ */
+function renderDeniedPage(email: string): string {
+  const safeEmail = escapeHtml(email);
+  return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>PI Dashboard — Access Denied</title>
+<style>body{font-family:system-ui,sans-serif;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;background:#0f172a;color:#e2e8f0;}
+.card{background:#1e293b;padding:40px;border-radius:12px;max-width:400px;width:100%;text-align:center;}
+h1{margin:0 0 16px;font-size:24px;color:#ef4444;}</style>
+</head><body><div class="card"><h1>Access Denied</h1><p>The email <strong>${safeEmail}</strong> is not authorized to access this dashboard.</p>
+<a href="/auth/login" style="color:#60a5fa;">Try a different account</a></div></body></html>`;
+}
+export async function registerAuthPlugin(
+  fastify: FastifyInstance,
+  options: AuthPluginOptions,
+): Promise<void> {
+  const { authConfig, port, resolvedTrustedNetworks } = options;
+  // Mutable auth state — can be rebuilt at runtime via reloadAuth()
+  const authState = {
+    secret: ensureAuthSecret(authConfig),
+    providerRegistry: await buildProviderRegistry(authConfig.providers),
+    allowedUsers: authConfig.allowedUsers,
+    bypassUrls: authConfig.bypassUrls ?? [],
+    bypassHosts: resolvedTrustedNetworks ?? authConfig.bypassHosts ?? [],
+  };
+  if (authState.providerRegistry.size === 0) {
+    console.warn("Auth configured but no providers resolved — auth disabled");
+    return;
+  }
+  // Expose reload function on the fastify instance for runtime config updates
+  (fastify as any)._reloadAuth = async (newConfig: AuthConfig) => {
+    authState.secret = ensureAuthSecret(newConfig);
+    authState.providerRegistry = await buildProviderRegistry(newConfig.providers);
+    authState.allowedUsers = newConfig.allowedUsers;
+    authState.bypassUrls = newConfig.bypassUrls ?? [];
+    authState.bypassHosts = newConfig.bypassHosts ?? [];
+    const names = Array.from(authState.providerRegistry.values()).map((p) => p.name);
+    console.log(`🔐 Auth reloaded with providers: ${names.join(", ")}`);
+  };
+  // Tag requests with authentication status (read by createNetworkGuard)
+  fastify.decorateRequest("isAuthenticated", false);
+  // Register cookie plugin
+  await fastify.register(cookie);
+  // ─── Auth Routes ────────────────────────────────────────────────────────
+  // GET /auth/login — provider picker or auto-redirect
+  fastify.get("/auth/login", async (request, reply) => {
+    const providers = Array.from(authState.providerRegistry.values());
+    const error = (request.query as any)?.error;
+    if (providers.length === 1 && !error) {
+      // Auto-redirect to single provider
+      const p = providers[0];
+      const redirectUri = buildRedirectUri(p.key, port);
+      const returnUrl = (request.query as any)?.return || "/";
+      const state = encodeState(returnUrl);
+      const url = buildAuthorizeUrl(p, redirectUri, state);
+      return reply.redirect(url);
+    }
+    return reply.type("text/html").send(renderLoginPage(providers, error));
+  });
+  // GET /auth/start/:provider — redirect to provider's authorize URL
+  fastify.get("/auth/start/:provider", async (request, reply) => {
+    const providerKey = (request.params as any).provider;
+    const provider = authState.providerRegistry.get(providerKey);
+    if (!provider) {
+      return reply.code(404).send({ error: "Unknown provider" });
+    }
+    const redirectUri = buildRedirectUri(providerKey, port);
+    const returnUrl = (request.query as any)?.return || "/";
+    const state = encodeState(returnUrl);
+    const url = buildAuthorizeUrl(provider, redirectUri, state);
+    return reply.redirect(url);
+  });
+  // GET /auth/callback/:provider — OAuth callback
+  fastify.get("/auth/callback/:provider", async (request, reply) => {
+    const providerKey = (request.params as any).provider;
+    const provider = authState.providerRegistry.get(providerKey);
+    if (!provider) {
+      return reply.code(404).send({ error: "Unknown provider" });
+    }
+    const query = request.query as any;
+    const code = query.code;
+    const stateParam = query.state || "";
+    if (!code) {
+      return reply.redirect("/auth/login?error=Missing+authorization+code");
+    }
+    const redirectUri = buildRedirectUri(providerKey, port);
+    const accessToken = await exchangeCode(provider, code, redirectUri);
+    if (!accessToken) {
+      return reply.redirect("/auth/login?error=Token+exchange+failed");
+    }
+    const userInfo = await fetchUserInfo(provider, accessToken);
+    if (!userInfo) {
+      return reply.redirect("/auth/login?error=Failed+to+fetch+user+info");
+    }
+    if (!isUserAllowed(userInfo.email, userInfo.username, authState.allowedUsers)) {
+      return reply.code(403).type("text/html").send(renderDeniedPage(userInfo.email));
+    }
+    const token = signToken(
+      { sub: userInfo.email, name: userInfo.name, username: userInfo.username, provider: providerKey },
+      authState.secret,
+    );
+    const { returnUrl } = decodeState(stateParam);
+    reply.setCookie(COOKIE_NAME, token, {
+      path: "/",
+      httpOnly: true,
+      secure: request.protocol === "https",
+      sameSite: "lax",
+      maxAge: 7 * 24 * 60 * 60, // 7 days in seconds
+    });
+    return reply.redirect(returnUrl);
+  });
+  // POST /auth/logout
+  fastify.post("/auth/logout", async (_request, reply) => {
+    reply.clearCookie(COOKIE_NAME, { path: "/" });
+    return reply.redirect("/auth/login");
+  });
+  // GET /auth/status — no auth required
+  fastify.get("/auth/status", async (request, reply) => {
+    const cookieToken = (request.cookies as any)?.[COOKIE_NAME];
+    if (cookieToken) {
+      const payload = verifyToken(cookieToken, authState.secret);
+      if (payload) {
+        return { authenticated: true, user: { name: payload.name, email: payload.sub, provider: payload.provider } };
+      }
+    }
+    return { authenticated: false };
+  });
+  // ─── onRequest Hook ─────────────────────────────────────────────────────
+  fastify.addHook("onRequest", async (request: FastifyRequest, reply: FastifyReply) => {
+    // Localhost bypass
+    if (isLoopback(request.ip)) return;
+    // Skip auth routes
+    if (request.url.startsWith("/auth/")) return;
+    // Skip health endpoint
+    if (request.url === "/api/health") return;
+    // Skip configured bypass URL prefixes
+    if (isBypassed(request.url, authState.bypassUrls)) return;
+    // Skip configured bypass hosts (trusted source IPs)
+    if (isBypassedHost(request.ip, authState.bypassHosts)) return;
+    // Validate JWT cookie
+    const cookieToken = (request.cookies as any)?.[COOKIE_NAME];
+    if (cookieToken) {
+      const payload = verifyToken(cookieToken, authState.secret);
+      if (payload) {
+        (request as any).isAuthenticated = true;
+        return;
+      }
+      // Invalid/expired — clear cookie
+      reply.clearCookie(COOKIE_NAME, { path: "/" });
+    }
+    // Not authenticated — redirect or 401
+    const accept = request.headers.accept || "";
+    if (accept.includes("text/html")) {
+      const returnUrl = encodeURIComponent(request.url);
+      return reply.redirect(`/auth/login?return=${returnUrl}`);
+    }
+    return reply.code(401).send({ error: "Authentication required" });
+  });
+  const providerNames = Array.from(authState.providerRegistry.values()).map((p) => p.name);
+  console.log(`🔐 Auth enabled with providers: ${providerNames.join(", ")}`);
+}
+/**
+ * Validate auth for a WebSocket upgrade request.
+ * Returns true if the request is allowed, false if it should be rejected.
+ */
+export function validateWsUpgrade(
+  cookieHeader: string | undefined,
+  remoteAddress: string,
+  secret: string,
+  trustedNetworks: string[] = [],
+): boolean {
+  if (isLoopback(remoteAddress)) return true;
+  if (trustedNetworks.length > 0 && isBypassedHost(remoteAddress, trustedNetworks)) return true;
+  const token = parseAuthCookie(cookieHeader);
+  if (!token) return false;
+  return verifyToken(token, secret) !== null;
+}

package/packages/server/src/auth.ts ADDED Viewed

@@ -0,0 +1,323 @@
+/**
+ * OAuth2 authentication module for the dashboard server.
+ * Supports GitHub, Google, Keycloak, and generic OIDC providers.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import jwt from "jsonwebtoken";
+import type { AuthConfig, AuthProviderConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { CONFIG_FILE } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { getTunnelUrl } from "./tunnel.js";
+// ─── Types ───────────────────────────────────────────────────────────────────
+export interface ResolvedProvider {
+  key: string;
+  name: string;
+  authorizeUrl: string;
+  tokenUrl: string;
+  userInfoUrl: string;
+  scopes: string;
+  clientId: string;
+  clientSecret: string;
+}
+export interface AuthUser {
+  sub: string; // email
+  name: string;
+  username: string;
+  provider: string;
+}
+export interface TokenPayload extends AuthUser {
+  exp: number;
+}
+// ─── Built-in provider endpoints ─────────────────────────────────────────────
+const GITHUB_ENDPOINTS = {
+  authorizeUrl: "https://github.com/login/oauth/authorize",
+  tokenUrl: "https://github.com/login/oauth/access_token",
+  userInfoUrl: "https://api.github.com/user",
+  scopes: "user:email",
+};
+const GOOGLE_ISSUER = "https://accounts.google.com";
+// ─── OIDC Discovery ─────────────────────────────────────────────────────────
+interface OIDCDiscovery {
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint: string;
+}
+export async function fetchOIDCDiscovery(issuerUrl: string): Promise<OIDCDiscovery> {
+  const url = `${issuerUrl.replace(/\/$/, "")}/.well-known/openid-configuration`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`OIDC discovery failed for ${issuerUrl}: ${res.status}`);
+  }
+  const data = await res.json();
+  return {
+    authorization_endpoint: data.authorization_endpoint,
+    token_endpoint: data.token_endpoint,
+    userinfo_endpoint: data.userinfo_endpoint,
+  };
+}
+// ─── Provider Registry ──────────────────────────────────────────────────────
+export async function buildProviderRegistry(
+  providers: Record<string, AuthProviderConfig>,
+): Promise<Map<string, ResolvedProvider>> {
+  const registry = new Map<string, ResolvedProvider>();
+  for (const [key, config] of Object.entries(providers)) {
+    try {
+      const resolved = await resolveProvider(key, config);
+      if (resolved) registry.set(key, resolved);
+    } catch (err: any) {
+      console.warn(`Failed to resolve OAuth provider "${key}": ${err.message}`);
+    }
+  }
+  return registry;
+}
+async function resolveProvider(
+  key: string,
+  config: AuthProviderConfig,
+): Promise<ResolvedProvider | null> {
+  const base = { key, clientId: config.clientId, clientSecret: config.clientSecret };
+  if (key === "github") {
+    return {
+      ...base,
+      name: config.name ?? "GitHub",
+      ...GITHUB_ENDPOINTS,
+    };
+  }
+  // Google, Keycloak, or generic OIDC — all use OIDC discovery
+  const issuerUrl = key === "google" ? GOOGLE_ISSUER : config.issuerUrl;
+  if (!issuerUrl) {
+    console.warn(`OAuth provider "${key}" requires issuerUrl`);
+    return null;
+  }
+  const discovery = await fetchOIDCDiscovery(issuerUrl);
+  const defaultNames: Record<string, string> = {
+    google: "Google",
+    keycloak: "Keycloak",
+    oidc: "OIDC",
+  };
+  return {
+    ...base,
+    name: config.name ?? defaultNames[key] ?? key,
+    authorizeUrl: discovery.authorization_endpoint,
+    tokenUrl: discovery.token_endpoint,
+    userInfoUrl: discovery.userinfo_endpoint,
+    scopes: "openid email profile",
+  };
+}
+// ─── Auth Secret Management ─────────────────────────────────────────────────
+/**
+ * Ensure the auth config has a secret. If missing, generate one and persist.
+ * Returns the secret string.
+ */
+export function ensureAuthSecret(authConfig: AuthConfig): string {
+  if (authConfig.secret) return authConfig.secret;
+  const secret = crypto.randomBytes(16).toString("hex"); // 32-char hex
+  authConfig.secret = secret;
+  // Persist back to config file
+  try {
+    const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed.auth) {
+      parsed.auth.secret = secret;
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(parsed, null, 2) + "\n");
+  } catch (err: any) {
+    console.warn(`Failed to persist auth secret: ${err.message}`);
+  }
+  return secret;
+}
+// ─── JWT Token Helpers ──────────────────────────────────────────────────────
+const TOKEN_EXPIRY = "7d";
+export const COOKIE_NAME = "pi_dash_token";
+export function signToken(user: AuthUser, secret: string): string {
+  return jwt.sign(
+    { sub: user.sub, name: user.name, username: user.username, provider: user.provider },
+    secret,
+    { expiresIn: TOKEN_EXPIRY },
+  );
+}
+export function verifyToken(token: string, secret: string): TokenPayload | null {
+  try {
+    const payload = jwt.verify(token, secret) as TokenPayload;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+// ─── Cookie Parsing ─────────────────────────────────────────────────────────
+/**
+ * Parse the auth token from a raw cookie header string.
+ */
+export function parseAuthCookie(cookieHeader: string | undefined): string | null {
+  if (!cookieHeader) return null;
+  const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${COOKIE_NAME}=([^;]*)`));
+  return match ? match[1] : null;
+}
+// ─── Email Allowlist ────────────────────────────────────────────────────────
+/**
+ * Check if an email is allowed by the allowedEmails list.
+ * Supports exact matches and domain wildcards (*@domain.com).
+ * Returns true if no allowedEmails is configured (allow all).
+ */
+/**
+ * Check if a user is allowed by the allowedUsers list.
+ * Matches against email, username, or domain wildcards (*@domain.com).
+ * Returns true if no allowedUsers is configured (allow all).
+ */
+export function isUserAllowed(email: string, username: string, allowedUsers?: string[]): boolean {
+  if (!allowedUsers || allowedUsers.length === 0) return true;
+  const lowerEmail = email.toLowerCase();
+  const lowerUsername = username.toLowerCase();
+  return allowedUsers.some((pattern) => {
+    const p = pattern.toLowerCase();
+    if (p.startsWith("*@")) {
+      const domain = p.slice(1); // "@domain.com"
+      return lowerEmail.endsWith(domain);
+    }
+    // Match against email or username
+    return lowerEmail === p || lowerUsername === p;
+  });
+}
+// ─── Redirect URI Builder ───────────────────────────────────────────────────
+export function buildRedirectUri(provider: string, port: number): string {
+  const base = getTunnelUrl() ?? `http://localhost:${port}`;
+  return `${base}/auth/callback/${provider}`;
+}
+// ─── OAuth Flow Helpers ─────────────────────────────────────────────────────
+/**
+ * Build the authorize URL to redirect the user to.
+ */
+export function buildAuthorizeUrl(
+  provider: ResolvedProvider,
+  redirectUri: string,
+  state: string,
+): string {
+  const params = new URLSearchParams({
+    client_id: provider.clientId,
+    redirect_uri: redirectUri,
+    scope: provider.scopes,
+    state,
+    response_type: "code",
+  });
+  return `${provider.authorizeUrl}?${params.toString()}`;
+}
+/**
+ * Exchange an authorization code for an access token.
+ */
+export async function exchangeCode(
+  provider: ResolvedProvider,
+  code: string,
+  redirectUri: string,
+): Promise<string | null> {
+  try {
+    const body = new URLSearchParams({
+      client_id: provider.clientId,
+      client_secret: provider.clientSecret,
+      code,
+      redirect_uri: redirectUri,
+      grant_type: "authorization_code",
+    });
+    const headers: Record<string, string> = {
+      "Content-Type": "application/x-www-form-urlencoded",
+    };
+    // GitHub needs Accept header to get JSON response
+    if (provider.key === "github") {
+      headers["Accept"] = "application/json";
+    }
+    const res = await fetch(provider.tokenUrl, {
+      method: "POST",
+      headers,
+      body: body.toString(),
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.access_token ?? null;
+  } catch {
+    return null;
+  }
+}
+/**
+ * Fetch user info from the provider using an access token.
+ * Returns { email, name } or null on failure.
+ */
+export async function fetchUserInfo(
+  provider: ResolvedProvider,
+  accessToken: string,
+): Promise<{ email: string; name: string; username: string } | null> {
+  try {
+    const res = await fetch(provider.userInfoUrl, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (provider.key === "github") {
+      // GitHub: name may be null, email may be null (private)
+      const name = data.name || data.login || "Unknown";
+      let email = data.email;
+      if (!email) {
+        // Fetch email from /user/emails endpoint
+        const emailRes = await fetch("https://api.github.com/user/emails", {
+          headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (emailRes.ok) {
+          const emails = await emailRes.json();
+          const primary = emails.find((e: any) => e.primary) ?? emails[0];
+          email = primary?.email;
+        }
+      }
+      const username = data.login || "";
+      return email ? { email, name, username } : null;
+    }
+    // OIDC providers: standard claims
+    const email = data.email;
+    const name = data.name || data.preferred_username || data.sub || "Unknown";
+    const username = data.preferred_username || data.sub || "";
+    return email ? { email, name, username } : null;
+  } catch {
+    return null;
+  }
+}

package/packages/server/src/browse.ts ADDED Viewed

@@ -0,0 +1,55 @@
+/**
+ * Directory browsing logic for the browse API endpoint.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import type { BrowseEntry, BrowseResult } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+const MAX_ENTRIES = 200;
+/**
+ * List subdirectories of a given path.
+ * Excludes hidden directories (starting with ".").
+ * Detects .git and .pi subdirectories for visual hints.
+ * Caps at 200 entries, sorted alphabetically.
+ */
+export async function listDirectories(dirPath?: string): Promise<BrowseResult> {
+  const resolved = dirPath ?? os.homedir();
+  // Verify the directory exists and is a directory
+  const stat = await fs.stat(resolved);
+  if (!stat.isDirectory()) {
+    throw new Error("not a directory");
+  }
+  const rawEntries = await fs.readdir(resolved, { withFileTypes: true });
+  // Filter: directories only, no hidden dirs
+  const dirs = rawEntries.filter(
+    (e) => e.isDirectory() && !e.name.startsWith(".")
+  );
+  // Sort alphabetically
+  dirs.sort((a, b) => a.name.localeCompare(b.name));
+  // Cap at MAX_ENTRIES
+  const capped = dirs.slice(0, MAX_ENTRIES);
+  // Build entries with isGit/isPi detection
+  const entries: BrowseEntry[] = await Promise.all(
+    capped.map(async (d) => {
+      const fullPath = path.join(resolved, d.name);
+      const [isGit, isPi] = await Promise.all([
+        fs.access(path.join(fullPath, ".git")).then(() => true, () => false),
+        fs.access(path.join(fullPath, ".pi")).then(() => true, () => false),
+      ]);
+      return { name: d.name, path: fullPath, isGit, isPi };
+    })
+  );
+  // Parent: null for root
+  const parent = resolved === "/" ? null : path.dirname(resolved);
+  return { entries, parent, current: resolved };
+}