@sanlam-fintech-digital/mfe-platform-cli 0.0.1

package/README.md

@@ -0,0 +1,271 @@
+# Sanlam Platform CLI
+
+A bootstrapping and orchestration CLI for the Sanlam Fintech Digital platform.
+
+## Overview
+
+**@sanlam-fintech-digital/mfe-platform-cli** initializes new developer machines by:
+
+- Configuring `.npmrc` with scoped, private npm registries
+- Authenticating registries using OAuth device flow (Azure DevOps, GitHub)
+- Automatically generating Personal Access Tokens for Azure DevOps (one per organization)
+- Providing pass-through access to internal CLI tools (future capability)
+
+## Installation
+
+### Global Install
+
+```bash
+npm install -g @sanlam-fintech-digital/mfe-platform-cli
+```
+
+### One-off Execution
+
+```bash
+npx @sanlam-fintech-digital/mfe-platform-cli init --config <source>
+```
+
+## Usage
+
+### Initialize Your Machine
+
+The `init` command sets up your local npm registry configuration with automatic OAuth authentication:
+
+```bash
+# From remote URL
+sft-mfe-platform init --config https://example.com/registry-config.json
+
+# From local file
+sft-mfe-platform init --config ./registry-config.json
+
+# Dry-run to preview changes
+sft-mfe-platform init --config ./registry-config.json --dry-run
+```
+
+This will:
+
+1. Load registry configuration from URL or file
+2. Store the config source for later updates
+3. Authenticate via OAuth (GitHub device flow, Azure DevOps PKCE)
+4. Backup your existing `.npmrc` file (just before modifying)
+5. Update `.npmrc` with registry URLs and authenticated tokens
+
+### Update Registry Configuration
+
+After initial setup, update your registry configuration:
+
+```bash
+# Uses the stored config source and auth options from init
+sft-mfe-platform update
+
+# Or specify a different source
+sft-mfe-platform update --config https://example.com/registry-config.json
+
+# Override stored auth options if needed
+sft-mfe-platform update --config-client-id <new-client-id>
+```
+
+**Note**: The `update` command automatically reuses the config source URL and authentication options (if any) from your initial `init` command. You only need to provide `--config-auth-*` options if you want to override the stored authentication settings.
+
+## NuGet Feed Support
+
+The CLI supports configuring NuGet feeds alongside npm registries using a unified configuration.
+
+### Configuration Example
+
+```json
+{
+  "authGroups": [
+    {
+      "provider": "azure-devops",
+      "clientId": "your-client-id",
+      "tenantId": "your-tenant-id",
+      "registries": [
+        {
+          "scope": "@myorg",
+          "url": "https://pkgs.dev.azure.com/myorg/_packaging/feed/npm/registry/",
+          "feedType": "npm"
+        },
+        {
+          "scope": "MyOrgNuGet",
+          "url": "https://pkgs.dev.azure.com/myorg/_packaging/feed/nuget/v3/index.json",
+          "feedType": "nuget"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Feed Types
+
+- **npm** (default): npm registries configured in `~/.npmrc`
+- **nuget**: NuGet feeds configured in platform-specific nuget.config:
+  - Windows: `%AppData%\NuGet\NuGet.Config`
+  - macOS/Linux: `~/.config/NuGet/NuGet.Config`
+
+### Authentication
+
+**Azure DevOps**: Same PAT works for both npm and NuGet feeds (`vso.packaging` scope)
+
+**GitHub**: OAuth device flow token works for both npm and NuGet feeds (`read:packages` scope)
+
+### Backward Compatibility
+
+Existing configurations work unchanged. The `feedType` field is optional and defaults to `"npm"`.
+
+### Authenticated Config URL
+
+If the config URL requires authentication, use these options:
+
+```bash
+## Device flow (when using /devicecode)
+sft-mfe-platform init \
+  --config https://example.com/registry-config.json \
+  --config-auth-endpoint https://login.microsoft.com/<tenantId>/oauth2/v2.0/devicecode \
+  --config-token-endpoint https://login.microsoft.com/<tenantId>/oauth2/v2.0/token \
+  --config-client-id <client-id> \
+  --config-token-kind access \
+  --config-auth-scope <scope>
+
+## PKCE (when using /authorize)
+sft-mfe-platform init \
+  --config https://example.com/registry-config.json \
+  --config-auth-endpoint https://login.microsoft.com/<tenantId>/oauth2/v2.0/authorize \
+  --config-token-endpoint https://login.microsoft.com/<tenantId>/oauth2/v2.0/token \
+  --config-client-id <client-id> \
+  --config-token-kind access \
+  --config-auth-scope <scope>
+```
+
+> **Authentication options are automatically stored**: When you provide `--config-auth-*` options during `init`, they are saved to `~/.sft-mfe-platform/config-source.json` and automatically reused by the `update` command. You don't need to provide them again unless you want to override them.
+>
+> If `--config-token-endpoint` is omitted, it is derived from the auth endpoint when possible (e.g., replacing `/devicecode` or `/authorize` with `/token`, GitHub `/device/code` → `/oauth/access_token`).
+> The default token kind is `access` for all providers, unless overridden.
+> If `--config-auth-endpoint` points to GitHub, the default scope is `repo read:packages` unless overridden.
+> If `--config-auth-endpoint` points to Entra ID (login.microsoftonline.com), the default scope is `499b84ac-1321-427f-aa17-267ca6975798/.default` unless overridden.
+> Use `--config-token-kind id` to send the ID token as the bearer token instead of the access token.
+
+## Configuration Format
+
+The registry configuration file (JSON) defines authentication groups and optional public registries:
+
+```json
+{
+  "authGroups": [
+    {
+      "provider": "github",
+      "clientId": "Iv1.1234567890abcdef",
+      "registries": [
+        {
+          "scope": "@github-project",
+          "url": "https://npm.pkg.github.com"
+        }
+      ]
+    },
+    {
+      "provider": "azure-devops",
+      "clientId": "your-azure-client-id",
+      "tenantId": "your-azure-tenant-id",
+      "registries": [
+        {
+          "scope": "@some-scope",
+          "url": "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/npm/registry/"
+        },
+        {
+          "scope": "@other-scope",
+          "url": "https://pkgs.dev.azure.com/my-org/_packaging/other-feed/npm/registry/"
+        }
+      ]
+    }
+  ],
+  "registries": [
+    {
+      "scope": "@public-scope",
+      "url": "https://registry.npmjs.org"
+    }
+  ]
+}
+```
+
+### Configuration Structure
+
+#### `authGroups` (optional)
+
+Array of authentication groups, each with:
+
+- **provider**: Registry provider type (`"azure-devops"` or `"github"`)
+- **clientId**: OAuth client ID for the provider
+- **tenantId**: Azure AD tenant ID (required for `azure-devops` provider only)
+- **registries**: Array of registries sharing this authentication
+  - **scope**: npm scope (e.g., `@your-org`)
+  - **url**: Registry URL (Azure DevOps Artifacts or GitHub Packages)
+
+**Important Limitations**:
+
+- **GitHub**: Only one GitHub auth group is allowed per configuration (GitHub uses a single `_authToken` for `npm.pkg.github.com`)
+- **Azure DevOps**: Multiple auth groups supported; one PAT generated per organization
+
+#### `registries` (optional)
+
+Array of public registries that do not require authentication:
+
+- **scope**: npm scope
+- **url**: Registry URL
+
+## Authentication
+
+Authentication is handled automatically during `init` using OAuth 2.0 (GitHub device flow, Azure DevOps PKCE):
+
+### GitHub Authentication
+
+1. User runs `sft-mfe-platform init`
+2. CLI displays a device code and verification URL
+3. User signs in and enters the device code
+4. CLI receives access token and stores in `.npmrc`
+5. All GitHub registries in the auth group use the same token
+
+**Permissions**: Read-only access to GitHub Packages (`read:packages`)
+
+**Limitation**: Only one GitHub auth group is allowed per configuration because GitHub uses a single authentication token for `npm.pkg.github.com`. All GitHub package registries must be grouped together.
+
+### Azure DevOps Authentication
+
+1. User runs `sft-mfe-platform init`
+2. CLI opens or prints a browser URL for PKCE login
+3. User signs in via Entra ID and the browser redirects to the registered `redirectUri`
+4. CLI exchanges the authorization code for an access token
+5. CLI generates a Personal Access Token (PAT) for each organization
+6. PAT is stored in `.npmrc` for each registry
+
+**Details**:
+
+- Uses Entra ID (Azure AD) OAuth 2.0 Authorization Code with PKCE
+- One PAT is generated per Azure DevOps organization
+- PAT display name format: `mfe-platform-cli-{organization}-{timestamp}` (visible in Azure DevOps token management)
+- PAT expires after 1 year; re-run `sft-mfe-platform init` to refresh
+- Permissions: Read-only access to package feeds (`vso.packaging`)
+
+### Dynamic Port & Relay Support
+
+By default, the CLI listens on port `53682` for the PKCE callback (`http://localhost:53682/callback`).
+
+To support environments where fixed ports are problematic or to use a public relay service:
+
+1. **CLI Option**: Use `--config-redirect-uri <url>`
+
+   ```bash
+   sft-mfe-platform init --config ... --config-redirect-uri https://relay.example.com/callback
+   ```
+
+2. **Configuration**: Add `redirectUri` to your Azure DevOps auth group in the config JSON.
+
+**How it works**:
+
+- If a custom redirect URI is provided (non-localhost), the CLI finds a random available local port.
+- It sends the port in the `state` parameter as a JSON string (e.g. `{"id":"...","port":12345}`).
+- The relay service is expected to parse this JSON state to extract the port and redirect the callback to `http://localhost:<port>/callback`.
+
+## License
+
+ISC

package/dist/auth/constants.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_REDIRECT_URI = "http://localhost:53682/callback";

package/dist/auth/constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REDIRECT_URI = void 0;
+exports.DEFAULT_REDIRECT_URI = 'http://localhost:53682/callback';

package/dist/auth/device-flow.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Device authorization response from OAuth provider
+ */
+export interface DeviceAuthResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    expires_in: number;
+    interval: number;
+    message?: string;
+}
+/**
+ * Token response from OAuth provider
+ */
+export interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope: string;
+}
+/**
+ * Token error response during polling
+ */
+export interface TokenErrorResponse {
+    error: 'authorization_pending' | 'slow_down' | 'expired_token' | 'access_denied' | string;
+    error_description?: string;
+}
+/**
+ * Initiate device authorization flow
+ */
+export declare function initiateDeviceFlow(endpoint: string, clientId: string, scope: string): Promise<DeviceAuthResponse>;
+/**
+ * Display user instructions for device flow authentication
+ */
+export declare function displayUserInstructions(userCode: string, verificationUri: string, providerName: string): void;
+/**
+ * Poll for access token after device authorization
+ */
+export declare function pollForToken(tokenEndpoint: string, clientId: string, deviceCode: string, interval: number, expiresIn: number): Promise<TokenResponse>;

package/dist/auth/device-flow.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initiateDeviceFlow = initiateDeviceFlow;
+exports.displayUserInstructions = displayUserInstructions;
+exports.pollForToken = pollForToken;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+/**
+ * Initiate device authorization flow
+ */
+async function initiateDeviceFlow(endpoint, clientId, scope) {
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: 'application/json',
+        },
+        body: new URLSearchParams({
+            client_id: clientId,
+            scope,
+        }),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Device authorization failed: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+    const data = (await response.json());
+    return data;
+}
+/**
+ * Display user instructions for device flow authentication
+ */
+function displayUserInstructions(userCode, verificationUri, providerName) {
+    console.log('\n' + chalk_1.default.bold.cyan(`${providerName} Authentication Required`));
+    console.log(chalk_1.default.gray('─'.repeat(50)));
+    console.log(`\n${chalk_1.default.bold('Please visit:')} ${chalk_1.default.green.underline(verificationUri)}\n` +
+        `${chalk_1.default.bold('Enter code:')} ${chalk_1.default.yellow.bold(userCode)}\n`);
+    console.log(chalk_1.default.gray('Waiting for authentication to complete...'));
+}
+/**
+ * Poll for access token after device authorization
+ */
+async function pollForToken(tokenEndpoint, clientId, deviceCode, interval, expiresIn) {
+    const startTime = Date.now();
+    let currentInterval = interval * 1000; // Convert to milliseconds
+    const spinner = (0, ora_1.default)('Waiting for authorization...').start();
+    try {
+        while (true) {
+            await sleep(currentInterval);
+            // Check timeout
+            if ((Date.now() - startTime) / 1000 > expiresIn) {
+                spinner.fail('Device authorization expired');
+                throw new Error('Device authorization expired. Please try again.');
+            }
+            const response = await fetch(tokenEndpoint, {
+                method: 'POST',
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: 'application/json',
+                },
+                body: new URLSearchParams({
+                    client_id: clientId,
+                    device_code: deviceCode,
+                    grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                }),
+            });
+            // Parse response - Entra ID returns 400 for authorization_pending
+            const data = (await response.json());
+            // Check if response is a success with access_token
+            if ('access_token' in data && data.access_token) {
+                spinner.succeed('Authorization successful');
+                return data;
+            }
+            // Handle OAuth error responses (may have non-200 status codes)
+            if ('error' in data) {
+                const error = data;
+                if (error.error === 'authorization_pending') {
+                    // Keep polling
+                    continue;
+                }
+                else if (error.error === 'slow_down') {
+                    // Increase polling interval
+                    currentInterval += 5000; // Add 5 seconds
+                    spinner.text = 'Slowing down polling...';
+                    continue;
+                }
+                else if (error.error === 'expired_token') {
+                    spinner.fail('Device code expired');
+                    throw new Error('Device code expired. Please try again.');
+                }
+                else if (error.error === 'access_denied') {
+                    spinner.fail('Authorization denied');
+                    throw new Error('User denied authorization');
+                }
+                else {
+                    spinner.fail('Token request failed');
+                    throw new Error(`Token request failed: ${error.error} - ${error.error_description || ''}`);
+                }
+            }
+            // Unexpected response format
+            if (!response.ok) {
+                spinner.fail('Token request failed');
+                throw new Error(`Token request failed: ${response.status} ${response.statusText}`);
+            }
+        }
+    }
+    catch (error) {
+        if (spinner.isSpinning) {
+            spinner.fail('Authorization failed');
+        }
+        throw error;
+    }
+}
+/**
+ * Sleep utility
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/auth/orchestrator.d.ts

@@ -0,0 +1,6 @@
+import { AuthGroup } from '../types/config.js';
+/**
+ * Orchestrate authentication across all auth groups
+ * Returns a map of registry URL → token for writing to .npmrc
+ */
+export declare function orchestrateAuthentication(authGroups: AuthGroup[] | undefined, redirectUri?: string): Promise<Map<string, string>>;

package/dist/auth/orchestrator.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orchestrateAuthentication = orchestrateAuthentication;
+const chalk_1 = __importDefault(require("chalk"));
+const azure_devops_js_1 = require("./providers/azure-devops.js");
+const github_js_1 = require("./providers/github.js");
+const auth_token_cache_js_1 = require("../config/auth-token-cache.js");
+/**
+ * Orchestrate authentication across all auth groups
+ * Returns a map of registry URL → token for writing to .npmrc
+ */
+async function orchestrateAuthentication(authGroups, redirectUri) {
+    const tokenMap = new Map();
+    if (!authGroups || authGroups.length === 0) {
+        console.log(chalk_1.default.gray('No authentication groups configured'));
+        return tokenMap;
+    }
+    console.log(chalk_1.default.bold(`\nAuthenticating ${authGroups.length} auth group(s)...\n`));
+    for (let i = 0; i < authGroups.length; i++) {
+        const group = authGroups[i];
+        console.log(chalk_1.default.cyan(`[${i + 1}/${authGroups.length}] Authenticating ${group.provider} (${group.registries.length} ${group.registries.length === 1 ? 'registry' : 'registries'})`));
+        try {
+            let groupTokens;
+            switch (group.provider) {
+                case 'azure-devops':
+                    // Use command-line redirectUri if provided, otherwise fall back to group config or undefined
+                    // Priority: CLI > Config Group > Default
+                    const finalRedirectUri = redirectUri || group.redirectUri;
+                    groupTokens = await authenticateAzureDevOpsWithCache(group.clientId, group.tenantId, group.registries, finalRedirectUri);
+                    break;
+                case 'github':
+                    groupTokens = await authenticateGitHubWithCache(group.clientId, group.registries);
+                    break;
+                default:
+                    throw new Error(`Unsupported provider: ${group.provider}`);
+            }
+            // Merge tokens into main map
+            for (const [url, token] of groupTokens) {
+                tokenMap.set(url, token);
+            }
+            console.log(chalk_1.default.green(`✓ ${group.provider} authentication complete\n`));
+        }
+        catch (error) {
+            console.error(chalk_1.default.red(`✗ Failed to authenticate ${group.provider}: ${error instanceof Error ? error.message : String(error)}\n`));
+            throw error;
+        }
+    }
+    console.log(chalk_1.default.green.bold(`\n✓ All authentications complete (${tokenMap.size} ${tokenMap.size === 1 ? 'token' : 'tokens'} acquired)\n`));
+    return tokenMap;
+}
+async function authenticateGitHubWithCache(clientId, registries) {
+    const cached = (0, auth_token_cache_js_1.getCachedConfigAuthToken)();
+    if (cached && cached.providerHint === 'github' && cached.clientId === clientId && cached.accessToken) {
+        const tokenMap = new Map();
+        for (const registry of registries) {
+            tokenMap.set(registry.url, cached.accessToken);
+        }
+        return tokenMap;
+    }
+    return (0, github_js_1.authenticateGitHub)(clientId, registries);
+}
+async function authenticateAzureDevOpsWithCache(clientId, tenantId, registries, redirectUri) {
+    const cached = (0, auth_token_cache_js_1.getCachedConfigAuthToken)();
+    if (cached
+        && cached.providerHint === 'entra'
+        && cached.clientId === clientId
+        && cached.tenantId === tenantId
+        && cached.accessToken
+        && cached.scopes?.includes(azure_devops_js_1.AZURE_DEVOPS_OAUTH_SCOPE)) {
+        return (0, azure_devops_js_1.authenticateAzureDevOpsWithOAuthToken)(cached.accessToken, registries);
+    }
+    return (0, azure_devops_js_1.authenticateAzureDevOps)(clientId, tenantId, registries, redirectUri);
+}

package/dist/auth/pkce-flow.d.ts

@@ -0,0 +1,9 @@
+export interface PkceFlowOptions {
+    authorizeEndpoint: string;
+    tokenEndpoint: string;
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    providerName: string;
+}
+export declare function runPkceFlow(options: PkceFlowOptions): Promise<import("./pkce").PkceTokenResponse>;

package/dist/auth/pkce-flow.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPkceFlow = runPkceFlow;
+const device_flow_1 = require("./device-flow");
+const pkce_1 = require("./pkce");
+async function runPkceFlow(options) {
+    const redirectUrl = new URL(options.redirectUri);
+    const isLocalhost = redirectUrl.hostname === 'localhost' || redirectUrl.hostname === '127.0.0.1';
+    let listenPort;
+    let expectedPath;
+    // Use an object for state to allow flexibility (e.g. adding port)
+    const stateObj = {
+        id: `pkce-${Date.now()}`
+    };
+    if (isLocalhost) {
+        // If port is explicitly provided in redirectUri, use it
+        // Otherwise, find a free unprivileged port to avoid requiring admin privileges
+        listenPort = Number(redirectUrl.port) || await (0, pkce_1.findFreePort)();
+    }
+    else {
+        // Relay mode: find a dynamic port
+        listenPort = await (0, pkce_1.findFreePort)();
+        // Add port to state so relay knows where to redirect
+        stateObj.port = listenPort;
+        // We expect the relay to redirect to http://localhost:port/callback
+        expectedPath = '/callback';
+    }
+    const state = JSON.stringify(stateObj);
+    const codeVerifier = (0, pkce_1.generateCodeVerifier)();
+    const codeChallenge = await (0, pkce_1.generateCodeChallenge)(codeVerifier);
+    const authorizeUrl = (0, pkce_1.buildAuthorizeUrl)({
+        authorizeEndpoint: options.authorizeEndpoint,
+        clientId: options.clientId,
+        redirectUri: options.redirectUri,
+        scope: options.scope,
+    }, codeChallenge, state);
+    (0, device_flow_1.displayUserInstructions)('Open your browser', authorizeUrl, options.providerName);
+    const authCode = await (0, pkce_1.waitForAuthCode)(options.redirectUri, state, listenPort, expectedPath);
+    return (0, pkce_1.exchangeCodeForTokenWithEndpoint)(options.tokenEndpoint, options.clientId, options.redirectUri, authCode, codeVerifier, options.scope);
+}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,36 @@
+export interface PkceRequest {
+    authorizeEndpoint: string;
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+}
+export interface PkceTokenResponse {
+    access_token?: string;
+    id_token?: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+    error?: string;
+    error_description?: string;
+}
+export declare function buildAuthorizeUrl(request: PkceRequest, codeChallenge: string, state: string): string;
+export declare function generateCodeVerifier(): string;
+export declare function generateCodeChallenge(codeVerifier: string): Promise<string>;
+export declare function waitForAuthCode(redirectUri: string, state: string, listenPort?: number, expectedPath?: string, timeoutMs?: number, maxRetries?: number): Promise<string>;
+/**
+ * Finds a free port by binding to port 0 and returning the OS-assigned port.
+ *
+ * **Race Condition Warning**: There is a small window between when this function
+ * closes the temporary server and when the caller attempts to bind to the returned port.
+ * During this window, another process could potentially claim the port.
+ *
+ * To handle this race condition, callers should implement retry logic with exponential
+ * backoff when binding fails with EADDRINUSE. The `waitForAuthCode` function already
+ * implements this retry mechanism.
+ *
+ * @returns A promise that resolves to a free port number
+ * @throws Error if unable to find a free port within the timeout period
+ */
+export declare function findFreePort(): Promise<number>;
+export declare function exchangeCodeForTokenWithEndpoint(tokenEndpoint: string, clientId: string, redirectUri: string, code: string, codeVerifier: string, scope: string): Promise<PkceTokenResponse>;