pilotswarm-web 0.1.0

package/README.md

@@ -0,0 +1,144 @@
+# pilotswarm-web
+
+Web portal for PilotSwarm — browser-based durable agent orchestration UI.
+
+Full feature parity with the TUI: session management, real-time chat, agent
+splash screens (ASCII art), sequence diagrams, node maps, worker logs,
+artifact downloads, and keyboard shortcuts.
+
+## Quick Start
+
+```bash
+# Install
+npm install pilotswarm-web
+
+# Run (starts server + serves React app)
+npx pilotswarm-web --env .env.remote
+npx pilotswarm-web --env .env.remote --plugin ./plugin
+
+# Development (Vite HMR)
+cd packages/portal
+npm run dev              # React app at http://localhost:5173
+node server.js           # API server at http://localhost:3001
+```
+
+## Portal Customization
+
+The web portal reads app-facing customization from `plugin.json` in your app
+plugin directory. Pass the plugin path with `--plugin` or set `PLUGIN_DIRS`
+so the portal process can see the same metadata the TUI and worker use.
+
+Supported keys:
+
+```json
+{
+  "tui": {
+    "title": "DevOps Command Center",
+    "splashFile": "./tui-splash.txt"
+  },
+  "portal": {
+    "branding": {
+      "title": "DevOps Command Center",
+      "pageTitle": "DevOps Command Center Portal",
+      "splashFile": "./tui-splash.txt",
+      "logoFile": "./assets/logo.svg",
+      "faviconFile": "./assets/favicon.png"
+    },
+    "ui": {
+      "loadingMessage": "Preparing the DevOps workspace",
+      "loadingCopy": "Connecting dashboards, session feeds, and orchestration state..."
+    },
+    "auth": {
+      "provider": "entra",
+      "signInTitle": "Sign in to DevOps Command Center",
+      "signInMessage": "Use your organization's identity provider to open the shared operations workspace.",
+      "signInLabel": "Sign In"
+    }
+  }
+}
+```
+
+Notes:
+
+- Preferred schema is nested: `portal.branding`, `portal.ui`, and `portal.auth`.
+- Flat legacy keys such as `portal.title` and `portal.loadingMessage` are still accepted for backwards compatibility.
+- `portal.auth.provider` selects the active auth provider when the deployment does not override it with `PORTAL_AUTH_PROVIDER`.
+- `branding.logoFile` is used on the loading splash, sign-in card, and signed-in header.
+- If `branding.faviconFile` is omitted, the browser tab icon reuses `branding.logoFile`.
+- Keep logo assets inside the plugin directory so the portal image can package and serve them alongside `plugin.json`.
+
+Fallback order:
+
+- `portal.branding.*` / `portal.ui.*` / `portal.auth.*`
+- flat `portal.*`
+- `tui.title` / `tui.splash` / `tui.splashFile`
+- built-in `PilotSwarm` defaults
+
+Named-agent creation in the portal comes from the same plugin metadata surface.
+If the portal process cannot see your plugin directory, the web UI falls back
+to generic sessions even when the worker supports named agents.
+
+## Auth Add-Ons
+
+Portal authentication is provider-based.
+
+- Default: `none`
+- Built-in optional provider: `entra`
+- AuthZ is common across providers and currently supports Phase 1 group-based admission control
+
+Enable Entra ID with env vars:
+
+```bash
+PORTAL_AUTH_PROVIDER=entra
+PORTAL_AUTH_ENTRA_TENANT_ID=<tenant-id>
+PORTAL_AUTH_ENTRA_CLIENT_ID=<client-id>
+PORTAL_AUTHZ_ADMIN_GROUPS=admin1@contoso.com,admin2@contoso.com
+PORTAL_AUTHZ_USER_GROUPS=user1@contoso.com,user2@contoso.com
+```
+
+Notes:
+
+- `PORTAL_AUTHZ_ADMIN_GROUPS` and `PORTAL_AUTHZ_USER_GROUPS` are currently comma-delimited email allowlists despite the historical variable names.
+- If no admin/user groups are configured, any successfully authenticated user is allowed in as the default `user` role.
+- Phase 1 keeps `admin` and `user` permissions the same inside the portal; the email allowlists act as an admission gate and role assignment surface.
+
+The portal core no longer assumes Entra specifically. New providers can plug
+into the same browser/server provider interfaces, while sharing the same common
+authz layer.
+
+## Architecture
+
+```
+Browser (React + Vite)
+  │
+  ├── WebSocket ──► Portal Server (Express + ws)
+  │                    │
+  │                    ├── PilotSwarmClient
+  │                    ├── PilotSwarmManagementClient
+  │                    └── PilotSwarmWorker (embedded or remote)
+  │
+  └── REST (session list, models, artifacts)
+```
+
+Same public API boundary as the TUI — only `PilotSwarmClient`,
+`PilotSwarmManagementClient`, and `PilotSwarmWorker` APIs. No internal
+module imports.
+
+## Package Relationship
+
+```
+pilotswarm-web         (this package)
+  ├── pilotswarm-cli   (shared node/runtime host glue)
+  │   ├── pilotswarm-sdk
+  │   ├── pilotswarm-ui-core
+  │   └── pilotswarm-ui-react
+  ├── express
+  ├── ws
+  ├── react, react-dom
+  └── vite             (devDependency)
+```
+
+`pilotswarm-web` now consumes a small supported portal-facing surface from
+`pilotswarm-cli` rather than importing monorepo-relative source files. That
+keeps the publishable package graph explicit and lets the portal reuse the same
+Node transport and plugin-config behavior as the TUI.

package/auth/authz/engine.js

@@ -0,0 +1,139 @@
+function normalizeRole(role) {
+    const normalized = String(role || "").trim().toLowerCase();
+    if (normalized === "admin") return "admin";
+    if (normalized === "user") return "user";
+    if (normalized === "anonymous") return "anonymous";
+    return null;
+}
+
+function firstRoleMatch(roles = []) {
+    for (const role of roles) {
+        const normalized = normalizeRole(role);
+        if (normalized === "admin") return "admin";
+    }
+    for (const role of roles) {
+        const normalized = normalizeRole(role);
+        if (normalized === "user") return "user";
+    }
+    return null;
+}
+
+function normalizeIdentifier(value) {
+    return String(value || "").trim().toLowerCase();
+}
+
+function intersectIdentifier(value, allowed = []) {
+    const normalizedValue = normalizeIdentifier(value);
+    if (!normalizedValue) return [];
+
+    const allowedSet = new Set((allowed || []).map(normalizeIdentifier).filter(Boolean));
+    return allowedSet.has(normalizedValue) ? [normalizedValue] : [];
+}
+
+export function authorizePrincipal(principal, policy = {}) {
+    const defaultRole = normalizeRole(policy.defaultRole) || "user";
+    const adminGroups = Array.isArray(policy.adminGroups) ? policy.adminGroups : [];
+    const userGroups = Array.isArray(policy.userGroups) ? policy.userGroups : [];
+    const allowUnauthenticated = policy.allowUnauthenticated === true;
+
+    if (!principal) {
+        if (allowUnauthenticated) {
+            return {
+                allowed: true,
+                role: "anonymous",
+                reason: "Authentication disabled",
+                matchedGroups: [],
+            };
+        }
+        return {
+            allowed: false,
+            role: null,
+            reason: "Authentication required",
+            matchedGroups: [],
+        };
+    }
+
+    const principalEmail = String(principal.email || "").trim();
+    const principalRoles = Array.isArray(principal.roles) ? principal.roles : [];
+    const matchedAdminGroups = intersectIdentifier(principalEmail, adminGroups);
+    const matchedUserGroups = intersectIdentifier(principalEmail, userGroups);
+
+    if (adminGroups.length === 0 && userGroups.length === 0) {
+        return {
+            allowed: true,
+            role: firstRoleMatch(principalRoles) || defaultRole,
+            reason: "No email allowlists configured",
+            matchedGroups: [],
+        };
+    }
+
+    if (matchedAdminGroups.length > 0) {
+        return {
+            allowed: true,
+            role: "admin",
+            reason: "Matched admin email allowlist",
+            matchedGroups: matchedAdminGroups,
+        };
+    }
+
+    if (matchedUserGroups.length > 0) {
+        return {
+            allowed: true,
+            role: "user",
+            reason: "Matched user email allowlist",
+            matchedGroups: matchedUserGroups,
+        };
+    }
+
+    if (!principalEmail) {
+        return {
+            allowed: false,
+            role: null,
+            reason: "Authenticated token did not include a usable email claim",
+            matchedGroups: [],
+        };
+    }
+
+    return {
+        allowed: false,
+        role: null,
+        reason: "Authenticated principal email is not in an allowed admin/user list",
+        matchedGroups: [],
+    };
+}
+
+export function getPublicAuthContext(authContext) {
+    if (!authContext) {
+        return {
+            principal: null,
+            authorization: {
+                allowed: false,
+                role: null,
+                reason: "Unauthenticated",
+                matchedGroups: [],
+            },
+        };
+    }
+
+    const principal = authContext.principal
+        ? {
+            provider: authContext.principal.provider,
+            subject: authContext.principal.subject,
+            email: authContext.principal.email ?? null,
+            displayName: authContext.principal.displayName ?? null,
+            tenantId: authContext.principal.tenantId ?? null,
+            groups: [...(authContext.principal.groups || [])],
+            roles: [...(authContext.principal.roles || [])],
+        }
+        : null;
+
+    return {
+        principal,
+        authorization: {
+            allowed: authContext.authorization?.allowed === true,
+            role: authContext.authorization?.role ?? null,
+            reason: authContext.authorization?.reason ?? null,
+            matchedGroups: [...(authContext.authorization?.matchedGroups || [])],
+        },
+    };
+}

package/auth/config.js

@@ -0,0 +1,110 @@
+import path from "node:path";
+import { getPluginDirsFromEnv, readPluginMetadata } from "pilotswarm-cli/portal";
+
+function getObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+
+function firstNonEmptyString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim()) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+
+function parseCsv(value) {
+    return String(value || "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+
+function parseBoolean(value, defaultValue = false) {
+    if (value == null || value === "") return defaultValue;
+    const normalized = String(value).trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized)) return true;
+    if (["0", "false", "no", "off"].includes(normalized)) return false;
+    return defaultValue;
+}
+
+function normalizeRole(value, defaultRole = "user") {
+    const normalized = String(value || "").trim().toLowerCase();
+    return normalized === "admin" ? "admin" : defaultRole;
+}
+
+export function resolvePluginAuthConfigFromPluginDirs(pluginDirs = getPluginDirsFromEnv()) {
+    for (const pluginDir of pluginDirs) {
+        const pluginMeta = readPluginMetadata(path.resolve(pluginDir));
+        if (!pluginMeta) continue;
+        const portal = getObject(pluginMeta.portal);
+        const portalAuth = getObject(portal.auth);
+        if (Object.keys(portalAuth).length === 0 && typeof portal.provider !== "string") {
+            continue;
+        }
+        return portalAuth;
+    }
+    return {};
+}
+
+export function inferAuthProviderId(env = process.env) {
+    if (
+        env.PORTAL_AUTH_ENTRA_TENANT_ID
+        || env.PORTAL_AUTH_ENTRA_CLIENT_ID
+    ) {
+        return "entra";
+    }
+    return "none";
+}
+
+export function resolveAuthProviderId({
+    env = process.env,
+    pluginAuthConfig = resolvePluginAuthConfigFromPluginDirs(),
+} = {}) {
+    const explicitProvider = firstNonEmptyString(env.PORTAL_AUTH_PROVIDER);
+    if (explicitProvider) return explicitProvider.toLowerCase();
+
+    const pluginProvider = firstNonEmptyString(pluginAuthConfig?.provider);
+    if (pluginProvider) return pluginProvider.toLowerCase();
+
+    return inferAuthProviderId(env);
+}
+
+function getProviderScopedGroupEnv({ env, providerId, groupKind }) {
+    const normalizedProvider = String(providerId || "").trim().toUpperCase();
+    const normalizedKind = String(groupKind || "").trim().toUpperCase();
+    return firstNonEmptyString(env[`PORTAL_AUTH_${normalizedProvider}_${normalizedKind}_GROUPS`]);
+}
+
+export function loadAuthorizationPolicy({
+    env = process.env,
+    providerId = resolveAuthProviderId({ env }),
+} = {}) {
+    const defaultRole = normalizeRole(env.PORTAL_AUTHZ_DEFAULT_ROLE, "user");
+    const adminGroups = parseCsv(
+        firstNonEmptyString(
+            env.PORTAL_AUTHZ_ADMIN_GROUPS,
+            getProviderScopedGroupEnv({ env, providerId, groupKind: "ADMIN" }),
+        ),
+    );
+    const userGroups = parseCsv(
+        firstNonEmptyString(
+            env.PORTAL_AUTHZ_USER_GROUPS,
+            getProviderScopedGroupEnv({ env, providerId, groupKind: "USER" }),
+        ),
+    );
+    const allowUnauthenticated = parseBoolean(
+        env.PORTAL_AUTH_ALLOW_UNAUTHENTICATED,
+        providerId === "none",
+    );
+
+    return {
+        defaultRole,
+        adminGroups,
+        userGroups,
+        allowUnauthenticated,
+    };
+}

package/auth/index.js

@@ -0,0 +1,153 @@
+import { createNoAuthProvider } from "./providers/none.js";
+import { createEntraAuthProvider } from "./providers/entra.js";
+import { authorizePrincipal } from "./authz/engine.js";
+import { loadAuthorizationPolicy, resolveAuthProviderId, resolvePluginAuthConfigFromPluginDirs } from "./config.js";
+
+const PROVIDERS = {
+    none: createNoAuthProvider,
+    entra: createEntraAuthProvider,
+};
+
+let cachedBundle = null;
+
+function getProviderBundle() {
+    if (cachedBundle) return cachedBundle;
+
+    const pluginAuthConfig = resolvePluginAuthConfigFromPluginDirs();
+    const providerId = resolveAuthProviderId({ pluginAuthConfig });
+    const factory = PROVIDERS[providerId];
+    if (!factory) {
+        throw new Error(`Unsupported portal auth provider: ${providerId}`);
+    }
+
+    cachedBundle = {
+        providerId,
+        pluginAuthConfig,
+        provider: factory({ pluginAuthConfig }),
+        policy: loadAuthorizationPolicy({ providerId }),
+    };
+    return cachedBundle;
+}
+
+function buildDeniedResult({ status, error, principal = null, authorization = null }) {
+    return {
+        ok: false,
+        status,
+        error,
+        principal,
+        authorization,
+    };
+}
+
+export function getAuthProvider() {
+    return getProviderBundle().provider;
+}
+
+export function getAuthorizationPolicy() {
+    return getProviderBundle().policy;
+}
+
+export function getResolvedAuthProviderId() {
+    return getProviderBundle().providerId;
+}
+
+export async function getAuthConfig(req) {
+    return getAuthProvider().getPublicConfig(req);
+}
+
+export async function validateToken(token, req) {
+    return getAuthProvider().authenticateRequest(token, req);
+}
+
+export async function authenticateToken(token, req) {
+    const provider = getAuthProvider();
+    const policy = getAuthorizationPolicy();
+
+    if (provider.enabled) {
+        if (!token) {
+            return buildDeniedResult({
+                status: 401,
+                error: "Unauthorized",
+                authorization: {
+                    allowed: false,
+                    role: null,
+                    reason: "Authentication required",
+                    matchedGroups: [],
+                },
+            });
+        }
+
+        const principal = await validateToken(token, req);
+        if (!principal) {
+            return buildDeniedResult({
+                status: 401,
+                error: "Unauthorized",
+                authorization: {
+                    allowed: false,
+                    role: null,
+                    reason: "Token validation failed",
+                    matchedGroups: [],
+                },
+            });
+        }
+
+        const authorization = authorizePrincipal(principal, policy);
+        if (!authorization.allowed) {
+            return buildDeniedResult({
+                status: 403,
+                error: authorization.reason || "Forbidden",
+                principal,
+                authorization,
+            });
+        }
+
+        return {
+            ok: true,
+            status: 200,
+            principal,
+            authorization,
+        };
+    }
+
+    const authorization = authorizePrincipal(null, policy);
+    if (!authorization.allowed) {
+        return buildDeniedResult({
+            status: 401,
+            error: authorization.reason || "Unauthorized",
+            authorization,
+        });
+    }
+
+    return {
+        ok: true,
+        status: 200,
+        principal: null,
+        authorization,
+    };
+}
+
+export async function authenticateRequest(req) {
+    return authenticateToken(extractToken(req), req);
+}
+
+/**
+ * Extract Bearer token from various sources.
+ * Checks: Authorization header, then sec-websocket-protocol header.
+ */
+export function extractToken(req) {
+    const authHeader = req.headers["authorization"];
+    if (authHeader?.startsWith("Bearer ")) {
+        return authHeader.slice(7);
+    }
+
+    const protocols = req.headers["sec-websocket-protocol"];
+    if (protocols) {
+        const parts = protocols.split(",").map((segment) => segment.trim());
+        const tokenIndex = parts.indexOf("access_token");
+        if (tokenIndex >= 0 && parts[tokenIndex + 1]) {
+            return parts[tokenIndex + 1];
+        }
+    }
+
+    return null;
+}

package/auth/normalize/entra.js

@@ -0,0 +1,22 @@
+function toStringArray(value) {
+    return Array.isArray(value)
+        ? value.map((entry) => String(entry || "").trim()).filter(Boolean)
+        : [];
+}
+
+export function normalizeEntraPrincipal(payload = {}) {
+    const subject = String(payload.oid || payload.sub || "").trim();
+    if (!subject) return null;
+
+    return {
+        provider: "entra",
+        subject,
+        email: String(payload.preferred_username || payload.email || payload.upn || "").trim() || null,
+        displayName: String(payload.name || "").trim() || null,
+        groups: toStringArray(payload.groups),
+        roles: toStringArray(payload.roles),
+        tenantId: String(payload.tid || "").trim() || null,
+        rawClaims: payload,
+    };
+}
+

package/auth/providers/entra.js

@@ -0,0 +1,76 @@
+import * as jose from "jose";
+import { normalizeEntraPrincipal } from "../normalize/entra.js";
+
+const JWKS_CACHE = new Map();
+
+function getEntraConfig(pluginAuthConfig = {}) {
+    const tenantId = process.env.PORTAL_AUTH_ENTRA_TENANT_ID;
+    const clientId = process.env.PORTAL_AUTH_ENTRA_CLIENT_ID;
+    const displayName = String(
+        pluginAuthConfig?.providers?.entra?.displayName
+        || pluginAuthConfig?.displayName
+        || "Entra ID",
+    ).trim() || "Entra ID";
+    if (!tenantId || !clientId) return null;
+    return { tenantId, clientId, displayName };
+}
+
+async function ensureJwks(tenantId) {
+    const cached = JWKS_CACHE.get(tenantId);
+    if (cached) return cached;
+
+    const issuer = `https://login.microsoftonline.com/${tenantId}/v2.0`;
+    const jwks = jose.createRemoteJWKSet(new URL(`https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`));
+    const bundle = { issuer, jwks };
+    JWKS_CACHE.set(tenantId, bundle);
+    return bundle;
+}
+
+async function validateToken(token, config) {
+    const { issuer, jwks } = await ensureJwks(config.tenantId);
+    const { payload } = await jose.jwtVerify(token, jwks, {
+        issuer,
+        audience: config.clientId,
+    });
+    return normalizeEntraPrincipal(payload);
+}
+
+export function createEntraAuthProvider({ pluginAuthConfig } = {}) {
+    const config = getEntraConfig(pluginAuthConfig);
+
+    return {
+        id: "entra",
+        enabled: Boolean(config),
+        displayName: config?.displayName || "Entra ID",
+        async authenticateRequest(token) {
+            if (!config || !token) return null;
+            try {
+                return await validateToken(token, config);
+            } catch (error) {
+                console.error("[portal-auth:entra] Token validation failed:", error?.message || String(error));
+                return null;
+            }
+        },
+        async getPublicConfig(req) {
+            if (!config) {
+                return {
+                    enabled: false,
+                    provider: "entra",
+                    displayName: config?.displayName || "Entra ID",
+                    client: null,
+                };
+            }
+            const host = req?.get?.("x-forwarded-host") || req?.get?.("host") || "";
+            return {
+                enabled: true,
+                provider: "entra",
+                displayName: config.displayName,
+                client: {
+                    clientId: config.clientId,
+                    authority: `https://login.microsoftonline.com/${config.tenantId}`,
+                    redirectUri: `${req?.protocol || "https"}://${host}`,
+                },
+            };
+        },
+    };
+}

package/auth/providers/none.js

@@ -0,0 +1,24 @@
+export function createNoAuthProvider({ pluginAuthConfig } = {}) {
+    const displayName = String(
+        pluginAuthConfig?.providers?.none?.displayName
+        || pluginAuthConfig?.displayName
+        || "No auth",
+    ).trim() || "No auth";
+
+    return {
+        id: "none",
+        enabled: false,
+        displayName,
+        async authenticateRequest() {
+            return null;
+        },
+        async getPublicConfig() {
+            return {
+                enabled: false,
+                provider: "none",
+                displayName,
+                client: null,
+            };
+        },
+    };
+}

package/auth.js

@@ -0,0 +1,10 @@
+export {
+    authenticateRequest,
+    authenticateToken,
+    extractToken,
+    getAuthConfig,
+    getAuthProvider,
+    getAuthorizationPolicy,
+    getResolvedAuthProviderId,
+    validateToken,
+} from "./auth/index.js";