pilotswarm 0.0.1 → 0.4.1

package/web/auth/authz/engine.js

@@ -0,0 +1,204 @@
+function normalizeRole(role) {
+    const normalized = String(role || "").trim().toLowerCase();
+    if (normalized === "admin") return "admin";
+    if (normalized === "user") return "user";
+    if (normalized === "anonymous") return "anonymous";
+    if (normalized === "none") return "none";
+    return null;
+}
+
+// Match `principalRoles` to an engine role using case-insensitive equality
+// against the two canonical role values `admin` and `user`. See Spec.md
+// FR-001..FR-005.
+//
+// Convention: the PilotSwarm app reg defines exactly two app roles with
+// `value: "admin"` and `value: "user"` (see deploy/scripts/auth/Setup-PortalAuth.ps1
+// `Build-AppRolesJson`). These are the canonical, prescriptive values —
+// the engine matches only these. If you need additional gate-keeping beyond
+// admin/user (e.g. an auditor role), define a new app role and check it
+// explicitly in code against the JWT `roles` claim — do not alias arbitrary
+// role values onto the built-in admin/user buckets here.
+//
+// Order: admin-before-user precedence is preserved — if a principal carries
+// both an admin role and a user role, the engine resolves to `admin`
+// (CodeResearch §8a).
+//
+// Empty / whitespace-only role tokens are filtered out before comparison
+// (mirrors `toStringArray` semantics in `normalize/entra.js`).
+//
+// Returns "admin", "user", or null.
+//
+// Note: `createNoAuthUnknownPrincipal()` produces `roles: ["anonymous"]` but is
+// never reachable here — the no-auth path passes `principal=null` to the engine
+// (CodeResearch §6). This matcher correctly returns null for "anonymous"
+// since it equals neither "admin" nor "user".
+function matchEngineRole(principalRoles) {
+    const rawTokens = Array.isArray(principalRoles) ? principalRoles : [];
+    const tokens = rawTokens
+        .map((t) => (typeof t === "string" ? t.trim().toLowerCase() : ""))
+        .filter(Boolean);
+    if (tokens.length === 0) return null;
+
+    // Admin pass first to preserve admin-before-user precedence.
+    if (tokens.includes("admin")) return "admin";
+    if (tokens.includes("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 = {}) {
+    // Secure-by-default: when no PORTAL_AUTHZ_DEFAULT_ROLE is configured,
+    // unmatched authenticated principals are denied rather than silently
+    // granted `user`. Set `PORTAL_AUTHZ_DEFAULT_ROLE=user` to restore the
+    // pre-v0.1.33 "any tenant user gets `user`" behavior.
+    const defaultRole = normalizeRole(policy.defaultRole) || "none";
+    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);
+
+    // Role-authoritative branch (Spec.md FR-001..FR-009): when the JWT carries a
+    // non-empty `roles[]` claim, decide solely from roles and bypass the email
+    // allowlist. Admin-before-user precedence is preserved by `matchEngineRole`.
+    const hasRoleTokens = principalRoles.some(
+        (t) => typeof t === "string" && t.trim().length > 0,
+    );
+    if (hasRoleTokens) {
+        const matched = matchEngineRole(principalRoles);
+        if (matched) {
+            return {
+                allowed: true,
+                role: matched,
+                reason: `Matched ${matched} role`,
+                matchedGroups: [],
+            };
+        }
+        return {
+            allowed: false,
+            role: null,
+            reason: "Roles present but no admin/user role matched",
+            matchedGroups: [],
+        };
+    }
+
+    if (adminGroups.length === 0 && userGroups.length === 0) {
+        // No email allowlists configured and the principal carries no role tokens
+        // (the role-authoritative branch above already handled non-empty roles).
+        if (defaultRole === "none") {
+            return {
+                allowed: false,
+                role: null,
+                reason: "No email allowlists configured and PORTAL_AUTHZ_DEFAULT_ROLE is not set (deny by default)",
+                matchedGroups: [],
+            };
+        }
+        return {
+            allowed: true,
+            role: 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/web/auth/config.js

@@ -0,0 +1,115 @@
+import path from "node:path";
+import { getPluginDirsFromEnv, readPluginMetadata } from "pilotswarm/host";
+
+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 = "none") {
+    const normalized = String(value || "").trim().toLowerCase();
+    if (normalized === "admin") return "admin";
+    if (normalized === "user") return "user";
+    if (normalized === "none") return "none";
+    return 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 }),
+} = {}) {
+    // Secure-by-default: deny when PORTAL_AUTHZ_DEFAULT_ROLE is not set.
+    // Accepted values: "admin" | "user" | "none". Default: "none" (deny).
+    const defaultRole = normalizeRole(env.PORTAL_AUTHZ_DEFAULT_ROLE, "none");
+    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/web/auth/index.js

@@ -0,0 +1,175 @@
+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,
+};
+
+const NO_AUTH_UNKNOWN_PRINCIPAL = Object.freeze({
+    provider: "none",
+    subject: "unknown",
+    email: null,
+    displayName: "Unknown User",
+    groups: Object.freeze([]),
+    roles: Object.freeze(["anonymous"]),
+    rawClaims: Object.freeze({}),
+});
+
+let cachedBundle = null;
+
+export function createNoAuthUnknownPrincipal() {
+    return {
+        provider: NO_AUTH_UNKNOWN_PRINCIPAL.provider,
+        subject: NO_AUTH_UNKNOWN_PRINCIPAL.subject,
+        email: NO_AUTH_UNKNOWN_PRINCIPAL.email,
+        displayName: NO_AUTH_UNKNOWN_PRINCIPAL.displayName,
+        groups: [...NO_AUTH_UNKNOWN_PRINCIPAL.groups],
+        roles: [...NO_AUTH_UNKNOWN_PRINCIPAL.roles],
+        rawClaims: { ...NO_AUTH_UNKNOWN_PRINCIPAL.rawClaims },
+    };
+}
+
+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: createNoAuthUnknownPrincipal(),
+        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/web/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/web/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/web/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/web/auth.js

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

package/web/bin/serve.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * pilotswarm-web — Starts the Express + WebSocket server and serves the
+ * built React portal.  In development, use `npm run dev` (Vite) with the
+ * server running separately via `node server.js`.
+ *
+ * Usage:
+ *   npx pilotswarm-web --env .env.remote
+ *   npx pilotswarm-web --port 3001
+ *   npx pilotswarm-web --plugin ./plugin
+ *   npx pilotswarm-web --workers 4          # embedded workers
+ *   npx pilotswarm-web --workers 0          # remote workers (AKS)
+ */
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Load env file if --env flag provided
+const envIdx = process.argv.indexOf("--env");
+if (envIdx !== -1 && process.argv[envIdx + 1]) {
+  const envPath = path.resolve(process.argv[envIdx + 1]);
+  // Node 24+ supports --env-file natively; for programmatic loading we
+  // read the file and set process.env entries manually.
+  const { readFileSync } = await import("node:fs");
+  for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const val = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+    if (!process.env[key]) process.env[key] = val;
+  }
+}
+
+// Dynamically import the server (after env is loaded)
+const { startServer } = await import("../server.js");
+
+const portFlag = process.argv.indexOf("--port");
+const port = portFlag !== -1 ? parseInt(process.argv[portFlag + 1], 10) : 3001;
+
+const pluginFlag = process.argv.indexOf("--plugin");
+if (pluginFlag !== -1 && process.argv[pluginFlag + 1]) {
+  process.env.PLUGIN_DIRS = path.resolve(process.argv[pluginFlag + 1]);
+}
+
+const workersFlag = process.argv.indexOf("--workers");
+const workers = workersFlag !== -1 ? parseInt(process.argv[workersFlag + 1], 10) : 4;
+
+startServer({ port, workers });