Refactor portal module discovery flow

Consume module registry metadata from the portal LOGIN_SUCCESS response, route admin remotes to their new server topology, and remove the browser REST registry dependency.\n\nCo-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: heswell

vuu-ui/docs/authentication-refactor-proposal.md

@@ -38,6 +38,8 @@ do not authenticate directly and do not contain identity-provider integration.
    authenticate or open websocket connections.
 10. Authentication failure for one remote does not terminate the portal or
     other remotes.
+11. The portal returns the module registry in
+    `LOGIN_SUCCESS.moduleRegistry`; remote servers omit it.
 
 ## Terminology
 
@@ -280,9 +282,10 @@ uses the explicit mode.
 5. Acquires the shared portal connection-registry entry.
 6. Opens the portal websocket with the portal VUU token when it is not already
    connected.
-7. Publishes the handler, authenticated identity, portal VUU session, and
+7. Captures the module registry returned by the portal `LOGIN_SUCCESS`.
+8. Publishes the handler, authenticated identity, portal VUU session, and
    active `connectionId`.
-8. Renders children only after authentication and portal connection succeed.
+9. Renders children only after authentication and portal connection succeed.
 
 The portal is therefore authenticated before `PortalShell` or any remote
 feature is reachable.
@@ -516,28 +519,29 @@ required. Missing values produce a configuration error before token exchange.
 
 ### Registry example
 
-Remote using the portal VUU server:
+Module admin uses the portal VUU server because module discovery is hosted by
+`vuu-portal`:
 
 ```json
 {
-  "mfScope": "UserAdmin",
-  "mfComponent": "UserAdmin",
-  "mfUrl": "http://localhost:5007",
+  "mfScope": "moduleAdmin",
+  "mfComponent": "ModuleAdmin",
+  "mfUrl": "http://localhost:5008",
   "vuu": {
     "connectionId": "portal"
   }
 }
 ```
 
-Remote using a separate VUU server:
+User admin uses its standalone VUU server:
 
 ```json
 {
-  "mfScope": "moduleAdmin",
-  "mfComponent": "ModuleAdmin",
-  "mfUrl": "http://localhost:5008",
+  "mfScope": "userAdmin",
+  "mfComponent": "UserAdmin",
+  "mfUrl": "http://localhost:5007",
   "vuu": {
-    "connectionId": "module-admin",
+    "connectionId": "user-admin",
     "restUrl": "https://localhost:8444/api/authn",
     "websocketUrl": "wss://localhost:8092/websocket"
   }
@@ -572,7 +576,7 @@ sequenceDiagram
   Registry->>PortalREST: exchange identity token
   PortalREST-->>Registry: portal VUU session
   Registry->>PortalWS: connect(VUU token)
-  PortalWS-->>Registry: connected
+  PortalWS-->>Registry: LOGIN_SUCCESS with moduleRegistry
   Registry-->>Identity: portal VUU session
   Identity-->>Browser: render portal runtime
 ```
@@ -686,6 +690,8 @@ because both identity and VUU tokens may be used as bearer tokens.
 9. Identity failure blocks the portal.
 10. Remote connection failure is isolated to the affected feature.
 11. Logout terminates the identity session and all VUU connections.
+12. Portal module discovery does not make a separate module-registry REST
+    request.
 
 ## Validation
 
@@ -708,3 +714,4 @@ The implementation includes automated coverage for:
 - connection-aware data-source construction
 - remote failure isolation
 - logout of all VUU connections and the Keycloak session
+- module registry propagation from portal `LOGIN_SUCCESS`

vuu-ui/docs/multi-module-requirements.md

@@ -22,7 +22,7 @@ This document is intended to be implementable without additional clarification.
 ### Out of scope (this phase)
 
 - Scala server implementation changes.
-- Replacing static `module-registry.json` with a dynamic registry service.
+- Persistent module-registry storage and administration.
 - Multi-server routing *within* a single remote module (assume one module -> one VUU server).
 
 ---
@@ -35,7 +35,6 @@ This document is intended to be implementable without additional clarification.
 4. Host config (`config.json`) currently includes:
    - `ssl`
    - `authUrl`
-   - `moduleRegistryUrl`
    - `restUrl`
    - `websocketUrl`
 
@@ -75,8 +74,9 @@ This document is intended to be implementable without additional clarification.
 
 ## 4.4 Discovery model
 
-1. Host MUST discover remotes from `moduleRegistryUrl` (currently static JSON).
-2. The registry remains file-based in this phase.
+1. Host MUST discover remotes from the portal websocket
+   `LOGIN_SUCCESS.moduleRegistry` payload.
+2. The registry is produced by the portal server's module-discovery module.
 3. Registry entries MUST include enough data to:
    - locate and load the remote module bundle
    - identify target VUU connection/server details for that module
@@ -118,7 +118,6 @@ Host config MUST continue to support:
 {
   "ssl": true,
   "authUrl": "http://localhost:5001",
-  "moduleRegistryUrl": "/module-registry.json",
   "restUrl": "https://localhost:8443",
   "websocketUrl": "wss://localhost:8090/websocket"
 }
@@ -129,9 +128,8 @@ Semantics:
 - `authUrl`: IdP entry point (Keycloak target, simple-login-app dev).
 - `restUrl`: Portal REST base used for token exchange.
 - `websocketUrl`: Default portal websocket endpoint.
-- `moduleRegistryUrl`: location of remote module descriptor list.
 
-## 6.2 Module registry schema (phase 1 file-based)
+## 6.2 Module registry schema
 
 Each remote descriptor MUST provide:
 
@@ -181,7 +179,7 @@ Notes:
 
 ## 7.3 Host + remote composition
 
-1. Host loads module descriptors from `moduleRegistryUrl`.
+1. Host loads module descriptors from the authenticated portal VUU session.
 2. Host registers available remotes and presents them in navigation similarly to current feature model.
 3. On remote activation/load:
    - resolve module descriptor
@@ -215,7 +213,8 @@ Notes:
 3. At least two remote modules can be loaded where each uses a distinct websocket endpoint.
 4. A connection failure in one remote does not terminate other active module connections.
 5. Existing feature flows still work in legacy single-endpoint config with no remote VUU override.
-6. Module discovery is driven by `moduleRegistryUrl` JSON (no hard-coded module list in app code).
+6. Module discovery is driven by the portal `LOGIN_SUCCESS` registry (no
+   hard-coded module list or browser REST request).
 7. Users can still drag a listed feature onto the workspace and instantiate a remote feature UI through the existing `Feature.tsx`-based layout flow.
 
 ---
@@ -226,10 +225,10 @@ Notes:
 
 - Multi-connection registry + compatibility facade.
 - `RemoteModule` boundary and connection scoping.
-- Static file-based module registry ingestion.
+- Portal-login module registry ingestion.
 - Token exchange + reuse model wired in host runtime.
 
 ## Phase 2 (later session)
 
-- Replace static `module-registry.json` with dynamic registry service.
+- Persist and administer module registry entries as needed.
 - Extend token refresh/re-auth and remote authorization policies as needed.

vuu-ui/packages/core/src/RemoteModuleDescriptor.ts

@@ -1,25 +1 @@
-import type { RemoteModuleConnection } from "./auth";
-
-export interface RemoteModuleDescriptor {
-  description: string;
-  id: string;
-  location: string;
-  name: string;
-  /**
-   * Module federation - the name of remote component to be imported
-   */
-  mfComponent: string;
-  /**
-   * Module federation - the identifier of remote module
-   */
-  mfScope: string;
-  /**
-   * Module federation - the url of remote module manifest
-   */
-  mfUrl: string;
-  moduleRegistryUrl?: string;
-  path: string;
-  title: string;
-  vuu?: RemoteModuleConnection;
-  version: number;
-}
+export type { VuuModuleDescriptor as RemoteModuleDescriptor } from "@vuu-ui/vuu-protocol-types";

vuu-ui/packages/core/src/auth/AuthenticationProvider.tsx

@@ -3,6 +3,7 @@ import type {
   DataSourceConstructorProps,
   RemoteModuleConnection,
 } from "@vuu-ui/vuu-data-types";
+import type { VuuModuleRegistry } from "@vuu-ui/vuu-protocol-types";
 import { DataProvider } from "../context-definitions/DataProvider";
 import {
   createContext,
@@ -72,6 +73,7 @@ interface IdentityContextValue {
   authHandler: AuthHandler;
   getIdentityToken: () => Promise<string>;
   logout: () => Promise<void>;
+  moduleRegistry?: VuuModuleRegistry;
   portalTarget: VuuAuthTarget;
   registry: VuuConnectionRegistry;
   user: User;
@@ -299,6 +301,7 @@ const AuthenticatedIdentityProvider = ({
       authHandler,
       getIdentityToken,
       logout,
+      moduleRegistry: session?.moduleRegistry,
       portalTarget,
       registry,
       user: identity.user,
@@ -310,6 +313,7 @@ const AuthenticatedIdentityProvider = ({
       logout,
       portalTarget,
       registry,
+      session?.moduleRegistry,
     ],
   );
 
@@ -392,6 +396,26 @@ export const useIdentityToken = () => {
   return identity.getIdentityToken;
 };
 
+export const useModuleRegistry = () => {
+  const identity = useContext(IdentityContext);
+  if (!identity) {
+    throw new AuthenticationConfigurationError(
+      "No identity AuthenticationProvider has been installed",
+    );
+  }
+  if (!identity.moduleRegistry) {
+    throw new AuthenticationConfigurationError(
+      "Portal LOGIN_SUCCESS did not include a module registry",
+    );
+  }
+  if (!Array.isArray(identity.moduleRegistry.modules)) {
+    throw new AuthenticationConfigurationError(
+      "Portal LOGIN_SUCCESS module registry did not include a modules array",
+    );
+  }
+  return identity.moduleRegistry;
+};
+
 export const usePortalVuuAuthTarget = () => {
   const identity = useContext(IdentityContext);
   if (!identity) {

vuu-ui/packages/core/src/auth/VuuConnectionRegistry.ts

@@ -1,6 +1,7 @@
 import {
   ConnectionManager,
   type ConnectionStatus,
+  type VuuConnectionResult,
 } from "@vuu-ui/vuu-data-remote";
 import type { AuthHandler } from "./AuthHandler";
 import {
@@ -39,11 +40,11 @@ type ConnectionRegistryEntry = {
 };
 
 export interface VuuConnectionClient {
-  connectTo(
+  connectWithLoginResponseTo(
     connectionId: string,
     options: { token: string; url: string },
     throwOnRejected?: boolean,
-  ): Promise<ConnectionStatus | "rejected">;
+  ): Promise<VuuConnectionResult>;
   connectedFor(connectionId: string): boolean;
   destroyConnection(connectionId: string): Promise<void>;
   onConnectionStatus(
@@ -204,22 +205,28 @@ export class VuuConnectionRegistry {
       entry.target,
     );
     entry.state = "connecting";
-    const status = await this.#connectionClient.connectTo(
-      entry.target.connectionId,
-      {
-        token: session.token,
-        url: entry.target.websocketUrl,
-      },
-      true,
-    );
+    const connectionResult =
+      await this.#connectionClient.connectWithLoginResponseTo(
+        entry.target.connectionId,
+        {
+          token: session.token,
+          url: entry.target.websocketUrl,
+        },
+        true,
+      );
+    const { status } = connectionResult;
     if (status !== "connected" && status !== "reconnected") {
       entry.state = "failed";
       throw Error(
         `VUU websocket connection ${entry.target.connectionId} failed with ${status}`,
       );
     }
 
-    entry.session = session;
+    const connectedSession = {
+      ...session,
+      moduleRegistry: connectionResult.loginResponse.moduleRegistry,
+    };
+    entry.session = connectedSession;
     entry.state = "connected";
     entry.unsubscribeStatus ??= this.#connectionClient.onConnectionStatus(
       entry.target.connectionId,
@@ -234,9 +241,9 @@ export class VuuConnectionRegistry {
       },
     );
     entry.listeners.forEach((listener) => {
-      listener(session);
+      listener(connectedSession);
     });
-    return session;
+    return connectedSession;
   }
 
   #reconnect(entry: ConnectionRegistryEntry) {

vuu-ui/packages/core/src/auth/VuuTokenExchange.ts

@@ -1,4 +1,5 @@
 import type { User } from "./AuthHandler";
+import type { VuuModuleRegistry } from "@vuu-ui/vuu-protocol-types";
 import { parseVuuUserFromToken } from "./VuuUser";
 
 export interface VuuAuthTarget {
@@ -9,6 +10,7 @@ export interface VuuAuthTarget {
 
 export interface VuuSession {
   authorizations: string[];
+  moduleRegistry?: VuuModuleRegistry;
   token: string;
   user: User;
 }

vuu-ui/packages/core/src/auth/index.ts

@@ -7,6 +7,7 @@ export {
 export {
   AuthenticationConfigurationError, AuthenticationProvider, normalizeVuuAuthTarget, useAuthenticatedUser,
   useIdentityToken,
+  useModuleRegistry,
   useLogout,
   useOptionalVuuConnectionId,
   usePortalVuuAuthTarget,