@heswell/vuu-portal 2.1.2 → 2.2.0

package/195.js

@@ -1,7 +1,8 @@
-import { ConfigFactory, EditSessionRpcHandler, ModuleFactory, Provider, TableDef, VUU_DEFAULT_COLUMNS, ViewPortDef, createConfiguredAuthProviders, createVuuServerApplication } from "@heswell/vuu-server";
+import { ConfigFactory, EditSessionRpcHandler, ModuleFactory, Provider, TableDef, VUU_DEFAULT_COLUMNS, ViewPortDef, createConfiguredAuthProviders, createVuuServerApplication, getLogger } from "@heswell/vuu-server";
 import { MODULE_ADMIN_RPC, executeModuleAdminRpc, managedModuleColumnValues, managedModulePermissionValues, validateModuleConfig } from "@heswell/module-admin";
 import node_fs from "node:fs";
 import node_path from "node:path";
+import { fileURLToPath } from "node:url";
 function moduleClientIdentifier(name) {
     const kebab = name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
     return kebab.startsWith("vuu-") ? kebab : `vuu-${kebab}`;
@@ -424,11 +425,69 @@ function columnsFor(table) {
 function valuesToRow(table, values) {
     return table.columns.map(({ name })=>values[name] ?? "");
 }
+const here = node_path.dirname(fileURLToPath(import.meta.url));
+const BUNDLED_CONFIG_FILE = [
+    node_path.resolve(here, "../config/application.conf"),
+    node_path.resolve(here, "config/application.conf")
+].find((candidate)=>node_fs.existsSync(candidate));
+const existingFile = (file, source)=>{
+    if (!node_fs.existsSync(file)) throw new Error(`Config file not found at '${file}' (from ${source})`);
+    return file;
+};
+function resolvePortalConfig({ configFile, cwd = process.cwd(), env = process.env } = {}) {
+    if (configFile) return {
+        configFile: existingFile(node_path.resolve(cwd, configFile), "--config"),
+        source: "--config"
+    };
+    const envFile = env.VUU_CONFIG_FILE?.trim();
+    if (envFile) return {
+        configFile: existingFile(node_path.resolve(cwd, envFile), "VUU_CONFIG_FILE"),
+        source: "VUU_CONFIG_FILE"
+    };
+    const appName = env.VUU_APP?.trim();
+    if (appName) return {
+        configFile: existingFile(node_path.resolve(cwd, "packages", appName, "application.conf"), "VUU_APP"),
+        source: "VUU_APP"
+    };
+    const cwdFile = node_path.resolve(cwd, "application.conf");
+    if (node_fs.existsSync(cwdFile)) return {
+        configFile: cwdFile,
+        source: "cwd"
+    };
+    if (!BUNDLED_CONFIG_FILE) throw new Error("Unable to locate application.conf: pass --config, or set VUU_CONFIG_FILE or VUU_APP.");
+    const overrides = {
+        "vuu.portal.modulesFile": node_path.resolve(cwd, env.VUU_PORTAL_MODULES_FILE?.trim() || "modules.yaml")
+    };
+    for (const [key, envName] of BUNDLED_PATH_ENV){
+        const value = env[envName]?.trim();
+        if (value) overrides[key] = node_path.resolve(cwd, value);
+    }
+    return {
+        configFile: BUNDLED_CONFIG_FILE,
+        source: "bundled",
+        overrides
+    };
+}
+const BUNDLED_PATH_ENV = [
+    [
+        "vuu.certPath",
+        "VUU_CERT_PATH"
+    ],
+    [
+        "vuu.keyPath",
+        "VUU_KEY_PATH"
+    ],
+    [
+        "vuu.portal.defaultModulesFile",
+        "VUU_PORTAL_DEFAULT_MODULES_FILE"
+    ]
+];
+const log = getLogger("vuu.portal");
 const PORTAL_DEFAULT_HTTPS_PORT = 8443;
 const PORTAL_DEFAULT_WEBSOCKET_PATH = "/websocket-portal";
 const PORTAL_DEFAULT_WEBSOCKET_PORT = 8091;
 function createPortalApplication({ config, configFile } = {}) {
-    const portalConfig = config ?? ConfigFactory.load(configFile);
+    const portalConfig = config ?? loadPortalConfig(configFile);
     return createVuuServerApplication({
         authProviders: createConfiguredAuthProviders(portalConfig),
         config: portalConfig,
@@ -445,4 +504,16 @@ function createPortalApplication({ config, configFile } = {}) {
         ]
     });
 }
-export { DEFAULT_MODULE_ADMIN_ROLE, InMemoryModuleStore, ModuleDiscoveryModule, ModuleState, PORTAL_DEFAULT_WEBSOCKET_PATH, YamlModuleStore, createModuleRegistry, createModuleState, createPortalApplication, loadDefaultModules, loadModuleAdminRole, loadModuleState, moduleClientIdentifier };
+function loadPortalConfig(configFile) {
+    const resolved = resolvePortalConfig({
+        configFile
+    });
+    const config = ConfigFactory.load(resolved.configFile, {
+        overrides: resolved.overrides
+    });
+    log.info(`using ${resolved.configFile} (from ${resolved.source})`);
+    if (config.getBoolean("vuu.ssl", false) && !(config.has("vuu.certPath") && config.has("vuu.keyPath"))) throw new Error(`vuu.ssl=true needs vuu.certPath and vuu.keyPath (set VUU_CERT_PATH and VUU_KEY_PATH, or set them in ${resolved.configFile})`);
+    if ("bundled" === resolved.source) log.warn(`no application.conf given: using the bundled default (vuu.auth.mode=${config.getString("vuu.auth.mode", "")}, vuu.ssl=${config.getBoolean("vuu.ssl", false)}). Pass --config or set VUU_CONFIG_FILE for anything but local development. Module catalogue: ${config.getPath("vuu.portal.modulesFile")}`);
+    return config;
+}
+export { BUNDLED_CONFIG_FILE, DEFAULT_MODULE_ADMIN_ROLE, InMemoryModuleStore, ModuleDiscoveryModule, ModuleState, PORTAL_DEFAULT_WEBSOCKET_PATH, YamlModuleStore, createModuleRegistry, createModuleState, createPortalApplication, loadDefaultModules, loadModuleAdminRole, loadModuleState, moduleClientIdentifier, resolvePortalConfig };

package/README.md

@@ -49,11 +49,13 @@ Root exports:
 
 ## Starting the portal
 
-Everything is configured in `application.conf`. Point the portal at your own
-conf and run the stock entry unchanged:
+Everything is configured in `application.conf`. With no conf, the portal starts
+from the default bundled with the package, for local development. Point it at
+your own conf to run the stock entry unchanged:
 
 ```sh
 # bin
+bunx vuu-portal   # bundled default conf
 bunx vuu-portal --config ./path/to/application.conf
 VUU_CONFIG_FILE=./path/to/application.conf bunx vuu-portal
 
@@ -70,6 +72,31 @@ The conf file is located in this order:
 3. `$VUU_APP`, which selects `packages/$VUU_APP/application.conf` under the
    current directory.
 4. `./application.conf`.
+5. The conf bundled with the package,
+   [`config/application.conf`](./config/application.conf).
+
+The portal logs which conf it used (logger `vuu.portal`).
+
+### The bundled default conf
+
+`config/application.conf` is meant for zero-config local development, and the
+portal logs a warning when it is used:
+
+- `vuu.auth.mode="permissive"`: any username and password may log in.
+- `vuu.ssl=false`: the websocket is `ws://` and the REST server `http://`. No
+  certificate or key is shipped; for TLS set `VUU_SSL=true`, `VUU_CERT_PATH`
+  and `VUU_KEY_PATH`. `vuu.ssl=true` without both paths fails at startup.
+- Websocket on 8091 (`/websocket-portal`), REST on 8443.
+- No Keycloak secret is shipped; set `VUU_KEYCLOAK_CLIENT_SECRET` (and
+  `VUU_KEYCLOAK_URL`) with `VUU_AUTH_MODE=keycloak`.
+- The seed catalogue, [`config/default-modules.yaml`](./config/default-modules.yaml),
+  is empty. The writable `modules.yaml` is kept in the current directory (or at
+  `$VUU_PORTAL_MODULES_FILE`), never in the installed package.
+  `VUU_PORTAL_MODULES_FILE`, `VUU_PORTAL_DEFAULT_MODULES_FILE`,
+  `VUU_CERT_PATH` and `VUU_KEY_PATH` resolve against the current directory.
+
+Every setting has a `VUU_*` override; see the comments in the file, or
+`vuu-portal --help`. For anything else, copy it and pass `--config`.
 
 In this repository, `npm run start:portal` starts it with
 `VUU_APP=vuu-portal`, which uses [`application.conf`](./application.conf).

package/bin.js

@@ -6,7 +6,13 @@ Starts the Vuu portal server. All settings (ports, websocket path, auth,
 module catalogue files, module admin role) come from application.conf.
 
 Without --config the conf is located via $VUU_CONFIG_FILE, then $VUU_APP
-(packages/<app>/application.conf), then ./application.conf.`;
+(packages/<app>/application.conf), then ./application.conf, then the
+conf bundled with the package. The bundled conf is for local development:
+permissive auth, no TLS (ws:// and http://), websocket on 8091 and REST on
+8443, and modules.yaml in the current directory. Override it with
+VUU_AUTH_MODE, VUU_SSL, VUU_CERT_PATH, VUU_KEY_PATH, VUU_WEBSOCKET_PORT,
+VUU_HTTPS_PORT, VUU_WEBSOCKET_PATH, VUU_PORTAL_MODULES_FILE,
+VUU_PORTAL_DEFAULT_MODULES_FILE, VUU_CORS_ALLOWED_ORIGINS, VUU_LOG_LEVEL.`;
 const parseConfigFile = (args)=>{
     let configFile;
     for(let index = 0; index < args.length; index++){

package/config/application.conf

@@ -0,0 +1,69 @@
+# Default vuu-portal configuration, bundled with the package. It is used when
+# no conf is given: no --config, VUU_CONFIG_FILE or VUU_APP, and no
+# ./application.conf in the current directory.
+#
+# Local development only: any username and password may log in, and the
+# websocket and REST servers run without TLS. Every setting can be changed
+# with the VUU_* environment variable next to it, or copy this file, edit it
+# and pass --config.
+#
+# Relative paths in this file resolve against this directory (inside the
+# installed package). The writable module catalogue (modules.yaml) is kept in
+# the current directory instead, and VUU_PORTAL_MODULES_FILE, VUU_CERT_PATH,
+# VUU_KEY_PATH and VUU_PORTAL_DEFAULT_MODULES_FILE resolve against the
+# current directory.
+
+vuu.auth.mode="permissive"
+vuu.auth.mode=${?VUU_AUTH_MODE}
+vuu.auth.path="/api/authn"
+# Comma-separated username:password entries (or a bare username, for a user
+# that may use any password). Empty allows any username with any password.
+vuu.auth.permissive.users=""
+vuu.auth.permissive.users=${?VUU_AUTH_PERMISSIVE_USERS}
+
+# TLS is off by default: ws:// and http://. No certificate is shipped. To use
+# TLS set VUU_SSL=true, VUU_CERT_PATH and VUU_KEY_PATH. vuu.ssl=false is only
+# allowed with vuu.auth.mode="permissive".
+vuu.ssl=false
+vuu.ssl=${?VUU_SSL}
+vuu.certPath=${?VUU_CERT_PATH}
+vuu.keyPath=${?VUU_KEY_PATH}
+
+vuu.websocket.path="/websocket-portal"
+vuu.websocket.path=${?VUU_WEBSOCKET_PATH}
+vuu.websocket.port=8091
+vuu.websocket.port=${?VUU_WEBSOCKET_PORT}
+vuu.https.port=8443
+vuu.https.port=${?VUU_HTTPS_PORT}
+
+# Browser origins allowed to call the REST auth endpoint (CORS).
+# VUU_CORS_ALLOWED_ORIGINS replaces the list with a comma-separated list.
+vuu.auth.cors.allowedOrigins=["http://localhost:5173", "http://127.0.0.1:5173", "http://localhost:5001", "http://127.0.0.1:5001"]
+vuu.auth.cors.allowedOrigins=${?VUU_CORS_ALLOWED_ORIGINS}
+
+# Keycloak, used only with VUU_AUTH_MODE=keycloak. No secret is shipped.
+vuu.keycloak.url=${?VUU_KEYCLOAK_URL}
+vuu.keycloak.realm="vuu"
+vuu.keycloak.realm=${?VUU_KEYCLOAK_REALM}
+vuu.keycloak.allowSelfSignedCert=false
+vuu.keycloak.allowSelfSignedCert=${?VUU_KEYCLOAK_ALLOW_SELF_SIGNED_CERT}
+vuu.auth.keycloak.clientId="vuu-portal-server"
+vuu.auth.keycloak.clientId=${?VUU_KEYCLOAK_CLIENT_ID}
+vuu.auth.keycloak.audience="vuu-portal-server"
+vuu.auth.keycloak.audience=${?VUU_KEYCLOAK_AUDIENCE}
+vuu.auth.keycloak.audiencePolicy="require-audience"
+vuu.auth.keycloak.authorizationClientId="vuu-portal"
+vuu.auth.keycloak.expectedAuthorizedParty="vuu-portal"
+vuu.auth.keycloak.tokenExchangeEnabled=false
+vuu.auth.keycloak.clientSecret=${?VUU_KEYCLOAK_CLIENT_SECRET}
+
+# The module catalogue. defaultModulesFile (read-only, in this directory)
+# seeds modulesFile on first startup; runtime edits are saved to modulesFile.
+vuu.portal.defaultModulesFile="default-modules.yaml"
+vuu.portal.modulesFile="modules.yaml"
+vuu.portal.moduleAdminRole="module-admin-access"
+vuu.portal.moduleAdminRole=${?VUU_PORTAL_MODULE_ADMIN_ROLE}
+
+# Log level: trace, debug, info, warn, error or silent.
+vuu.log.level="info"
+vuu.log.level=${?VUU_LOG_LEVEL}

package/config/default-modules.yaml

@@ -0,0 +1,22 @@
+# Default portal modules for the bundled application.conf. Seeds modules.yaml
+# (in the current directory) on first startup; add modules there, or with the
+# module admin service. To ship your own defaults, point
+# VUU_PORTAL_DEFAULT_MODULES_FILE at a file like this one.
+#
+# Example entry:
+#
+#   - id: 1
+#     version: 1
+#     parentModuleId: 0
+#     name: "moduleAdmin"
+#     title: "Manage remote modules"
+#     description: "Create new remote module, update existing modules"
+#     enabled: true
+#     location: "/Modules/Manage Modules"
+#     path: "/modules/admin"
+#     mfComponent: "ModuleAdmin"
+#     mfScope: "moduleAdmin"
+#     mfUrl: "http://localhost:5002"
+#     navIconUrl: ""
+#     accessRole: "module-admin-access"
+modules: []

package/index.js

@@ -1,4 +1,4 @@
 var src_PORTAL_DEFAULT_HTTPS_PORT = 8443;
 var src_PORTAL_DEFAULT_WEBSOCKET_PORT = 8091;
-export { DEFAULT_MODULE_ADMIN_ROLE, InMemoryModuleStore, ModuleDiscoveryModule, ModuleState, PORTAL_DEFAULT_WEBSOCKET_PATH, YamlModuleStore, createModuleRegistry, createModuleState, createPortalApplication, loadDefaultModules, loadModuleAdminRole, loadModuleState, moduleClientIdentifier } from "./195.js";
+export { BUNDLED_CONFIG_FILE, DEFAULT_MODULE_ADMIN_ROLE, InMemoryModuleStore, ModuleDiscoveryModule, ModuleState, PORTAL_DEFAULT_WEBSOCKET_PATH, YamlModuleStore, createModuleRegistry, createModuleState, createPortalApplication, loadDefaultModules, loadModuleAdminRole, loadModuleState, moduleClientIdentifier, resolvePortalConfig } from "./195.js";
 export { src_PORTAL_DEFAULT_HTTPS_PORT as PORTAL_DEFAULT_HTTPS_PORT, src_PORTAL_DEFAULT_WEBSOCKET_PORT as PORTAL_DEFAULT_WEBSOCKET_PORT };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heswell/vuu-portal",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "VUU portal server with remote module discovery",
   "type": "module",
   "main": "./index.js",
@@ -51,6 +51,7 @@
   "files": [
     "*.js",
     "src/**/*.d.ts",
-    "README.md"
+    "README.md",
+    "config"
   ]
 }

package/src/PortalApplication.d.ts

@@ -7,8 +7,9 @@ export type PortalApplicationOptions = {
     config?: Config;
     /**
      * Path to the portal's application.conf, resolved against the current
-     * directory. Defaults to ConfigFactory's lookup: $VUU_CONFIG_FILE, then
-     * $VUU_APP, then ./application.conf.
+     * directory. Defaults to $VUU_CONFIG_FILE, then $VUU_APP
+     * (packages/<app>/application.conf), then ./application.conf, then the
+     * conf bundled with the package (see resolvePortalConfig).
      */
     configFile?: string;
 };

package/src/index.d.ts

@@ -3,3 +3,4 @@ export { loadModuleAdminRole, loadModuleState, ModuleDiscoveryModule, ModuleStat
 export { createModuleState, InMemoryModuleStore, loadDefaultModules, type ModuleStore, YamlModuleStore, } from "./modules/ModuleDiscovery/ModuleStore.js";
 export { DEFAULT_MODULE_ADMIN_ROLE } from "./modules/ModuleDiscovery/ModuleAdminService.js";
 export { createPortalApplication, PORTAL_DEFAULT_HTTPS_PORT, PORTAL_DEFAULT_WEBSOCKET_PATH, PORTAL_DEFAULT_WEBSOCKET_PORT, type PortalApplicationOptions, } from "./PortalApplication.js";
+export { BUNDLED_CONFIG_FILE, type PortalConfigSource, type ResolvedPortalConfig, type ResolvePortalConfigOptions, resolvePortalConfig, } from "./resolvePortalConfig.js";

package/src/resolvePortalConfig.d.ts

@@ -0,0 +1,31 @@
+import type { ConfigValue } from "@heswell/vuu-server";
+export type PortalConfigSource = "--config" | "VUU_CONFIG_FILE" | "VUU_APP" | "cwd" | "bundled";
+export type ResolvedPortalConfig = {
+    /** Absolute path of the application.conf to load. */
+    configFile: string;
+    source: PortalConfigSource;
+    /**
+     * Config overrides. Only set for the bundled conf: the writable module
+     * catalogue (vuu.portal.modulesFile) goes in the current directory, or at
+     * $VUU_PORTAL_MODULES_FILE, never inside the installed package; and
+     * $VUU_CERT_PATH, $VUU_KEY_PATH and $VUU_PORTAL_DEFAULT_MODULES_FILE
+     * resolve against the current directory.
+     */
+    overrides?: Record<string, ConfigValue>;
+};
+export type ResolvePortalConfigOptions = {
+    configFile?: string;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+};
+/**
+ * The application.conf shipped in the package's config/ directory. Source
+ * modules live in src/, the built entries at the package root.
+ */
+export declare const BUNDLED_CONFIG_FILE: string;
+/**
+ * Locates the portal's application.conf: --config, then $VUU_CONFIG_FILE,
+ * then $VUU_APP (packages/<app>/application.conf), then ./application.conf,
+ * then the conf bundled with the package.
+ */
+export declare function resolvePortalConfig({ configFile, cwd, env, }?: ResolvePortalConfigOptions): ResolvedPortalConfig;