Add auth plugin to allow configurable auth strategy to CLI - finos#2453 (finos#2452)

* feat(cli): add initial auth plugin loader code

* feat(cli): auth plugin work

* feat(cli): make auth plugin work

* feat(cli): use auth plugin in other calm commands

* fix(shared): tests

* feat(cli): tests

* fix(cli): remove unused test auth plugin

* fix(cli): improve linting and error logging

* fix(cli): fix test fixtures

* fix(cli): fix issue with clashing versions for docify

* fix(cli): lockfile

* fix(cli): proper tests for loading plugins

* docs(cli): add docs for auth plugins

* fix(cli): try removing dependency change

* feat(cli): remove TS compilation of auth plugins

Author: willosborne

cli/README.md

@@ -418,3 +418,26 @@ and
 
 This differs:
 {{ block-architecture render-node-type-shapes=false }}
+```
+
+## Authentication plugins
+
+The CLI supports an external authentication plugin to allow authentication to CalmHub in enterprise environments, where seamless auth will likely require specific logic.
+
+### Writing an authentication plugin
+
+Authentication plugins are JavaScript files. You can find an example in [the test fixtures](./test_fixtures/test-auth-plugin.js).
+
+Plugins must export a default class implementing the [`AuthPlugin`](../shared/src/auth/auth-plugin.ts) interface, i.e. a `getAuthHeaders(url, requestBody)` method that returns a `Promise<Record<string, string>>`.
+
+The function `getAuthHeaders` will be invoked with the request URL and body for every request made to CalmHub by the CLI.
+
+### Using an authentication plugin
+
+To configure your CLI to use an auth plugin, use `~/.calm.json` in the same fashion as configuring a CalmHub URL:
+
+```
+{
+  "calmHubUrl": "http://calmhub.com",
+  "authPluginPath": "~/plugins/auth-plugin.js"
+}

cli/src/cli-config.spec.ts

@@ -1,21 +1,32 @@
 import { fs, vol } from 'memfs';
-import { loadCliConfig } from './cli-config';
+import { loadCliConfig, loadAuthPlugin } from './cli-config';
+import { resolve } from 'path';
+import { homedir } from 'os';
+
 
 vi.mock('fs/promises', async () => {
     const memfs: { fs: typeof fs } = await vi.importActual('memfs');
 
     return memfs.fs.promises;
 });
 
+vi.mock('fs', async () => {
+    const memfs: { fs: typeof fs } = await vi.importActual('memfs');
+    return memfs.fs;
+});
+
 vi.mock('os', () => ({
-    homedir: () => '/home/user'
+    homedir: vi.fn(() => '/home/user')
 }));
 
 const exampleConfig = {
     calmHubUrl: 'https://example.com/calmhub',
-    allowedRemoteHosts: ['schemas.example.com']
+    allowedRemoteHosts: ['schemas.example.com'],
+    authPluginPath: './auth-plugin.js'
 };
 
+const FIXTURES_DIR = resolve(__dirname, '../test_fixtures');
+const JS_FIXTURE = resolve(FIXTURES_DIR, 'test-auth-plugin.js');
 
 describe('cli-config', () => {
     beforeEach(() => {
@@ -24,6 +35,7 @@ describe('cli-config', () => {
 
     afterEach(() => {
         vol.reset();
+        vi.mocked(homedir).mockReturnValue('/home/user');
     });
 
     it('loads user config from .calm.json in home dir', async () => {
@@ -45,4 +57,48 @@ describe('cli-config', () => {
         });
         await expect(loadCliConfig()).resolves.toBeNull();
     });
+
+    it('replaces homedir in auth plugin path', async () => {
+        vol.fromJSON({
+            '/home/user/.calm.json': JSON.stringify({
+                authPluginPath: '~/my-auth-plugin.js'
+            })
+        });
+
+        const config = await loadCliConfig();
+        expect(config).toEqual({
+            authPluginPath: '~/my-auth-plugin.js'
+        });
+    });
+
+    it('loads JavaScript auth plugin from absolute path', async () => {
+        vol.fromJSON({
+            '/home/user/.calm.json': JSON.stringify({ authPluginPath: JS_FIXTURE }),
+            // just register this file exists. the actual loading mechanism, import(), will be handled by node which is mocked in the test environment to return a valid auth plugin.
+            [JS_FIXTURE]: '',
+        });
+
+        const config = await loadCliConfig();
+        expect(config).toEqual({ authPluginPath: JS_FIXTURE });
+
+        const authPlugin = await loadAuthPlugin(config!.authPluginPath!, false);
+        expect(authPlugin.getAuthHeaders).toBeDefined();
+    });
+
+    it('loads JavaScript auth plugin with tilde path', async () => {
+        // Point homedir at FIXTURES_DIR so ~/test-auth-plugin.js resolves to the real fixture file
+        vi.mocked(homedir).mockReturnValue(FIXTURES_DIR);
+
+        vol.fromJSON({
+            [resolve(FIXTURES_DIR, '.calm.json')]: JSON.stringify({ authPluginPath: '~/test-auth-plugin.js' }),
+            [JS_FIXTURE]: '',
+        });
+
+        const config = await loadCliConfig();
+        expect(config).toEqual({ authPluginPath: '~/test-auth-plugin.js' });
+
+        const authPlugin = await loadAuthPlugin(config!.authPluginPath!, false);
+        expect(authPlugin.getAuthHeaders).toBeDefined();
+    });
+
 });

cli/src/cli-config.ts

@@ -1,11 +1,14 @@
-import { initLogger } from '@finos/calm-shared';
 import { readFile, writeFile } from 'fs/promises';
+import { initLogger, AuthPlugin } from '@finos/calm-shared';
+import { existsSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
+import { pathToFileURL } from 'url';
 
 export interface CLIConfig {
     calmHubUrl?: string
     allowedRemoteHosts?: string[]
+    authPluginPath?: string
 }
 
 export function getUserConfigLocation(): string {
@@ -38,3 +41,43 @@ export async function loadCliConfig(): Promise<CLIConfig | null> {
         return null;
     }
 }
+
+export function resolveHomeDir(path: string): string {
+    if (path.startsWith('~')) {
+        return join(homedir(), path.slice(1));
+    }
+    return path;
+}
+
+export async function loadAuthPlugin(filename: string, debug: boolean): Promise<AuthPlugin> {
+    const logger = initLogger(debug, 'auth-plugin');
+
+    filename = resolveHomeDir(filename);
+    
+    if (!existsSync(filename)) {
+        logger.error(`❌ Auth plugin file not found: ${filename}`);
+        throw new Error(`❌ Auth plugin file not found: ${filename}`);
+    }
+    if (!filename.endsWith('.js')) {
+        logger.error(`❌ Auth plugin file must have a .js extension: ${filename}`);
+        throw new Error(`❌ Auth plugin file must have a .js extension: ${filename}`);
+    }
+    logger.info(`🔍 Loading auth plugin: ${filename}`);
+
+    try {
+        const url = pathToFileURL(filename).href;
+        const mod = await import(/* @vite-ignore */ url);
+        const AuthPluginClass = mod.default;
+        if (typeof AuthPluginClass !== 'function') {
+            throw new Error('❌ Auth plugin must export a default class. Did you forget to export default?');
+        }
+        const instance = new AuthPluginClass() as AuthPlugin;
+        if (typeof instance.getAuthHeaders !== 'function') {
+            throw new Error('❌ Auth plugin class must implement getAuthHeaders(url, requestBody): Promise<Record<string, string>>');
+        }
+        return instance;
+    } catch (error) {
+        logger.error(`❌ Error loading auth plugin: ${error}`);
+        throw new Error(`❌ Error loading auth plugin: ${error}`);
+    }
+}

cli/src/cli.ts

@@ -293,6 +293,19 @@ export async function parseDocumentLoaderConfig(
         logger.info('Using CALMHub URL from config file: ' + userConfig.calmHubUrl);
         docLoaderOpts.calmHubUrl = userConfig.calmHubUrl;
     }
+    
+    // if we have an auth plugin and we have calmHub configured
+    if (userConfig && userConfig.authPluginPath) {
+        logger.info('Loading auth plugin from config file: ' + userConfig.authPluginPath);
+        try {
+            const authPlugin = await cliConfig.loadAuthPlugin(userConfig.authPluginPath, !!options.verbose);
+            docLoaderOpts.authPlugin = authPlugin;
+            logger.debug('Auth plugin loaded successfully');
+        } catch (err) {
+            logger.error('Failed to load auth plugin: ' + (err instanceof Error ? err.message : String(err)));
+        }
+    }
+
     if (userConfig && userConfig.allowedRemoteHosts && !options.allowedRemoteHosts) {
         logger.info('Using allowed remote hosts from config file');
         docLoaderOpts.allowedRemoteHosts = userConfig.allowedRemoteHosts;

cli/test_fixtures/test-auth-plugin.js

@@ -0,0 +1,8 @@
+export default class TestAuthPlugin {
+    async getAuthHeaders(url, requestBody) {
+        console.log(`AUTH PLUGIN: Calling URL: ${url} with request body: ${JSON.stringify(requestBody)}`);
+        return {
+            'Test-Header': 'TestValue'
+        };
+    }
+}

cli/test_fixtures/test-auth-plugin.ts

@@ -0,0 +1,10 @@
+import type { AuthPlugin } from '@finos/calm-shared'
+
+export default class TestAuthPlugin implements AuthPlugin {
+    async getAuthHeaders(url: string, requestBody: unknown): Promise<Record<string, string>> {
+        console.log(`Generating auth headers for URL: ${url} with request body: ${JSON.stringify(requestBody)}`);
+        return {
+            'Test-Header': 'TestValue'
+        };
+    }
+}

conferences/osff-ln-2025/workshop/architecture/conference-signup.arch.json

@@ -132,5 +132,5 @@
       }
     }
   ],
-  "$schema": "https://calm.finos.org/workshop/conference-signup.pattern.json"
+  "$schema": "calm://calm.finos.org/calm/namespaces/workshop/patterns/1/versions/1.0.0"
 }