@robinmordasiewicz/f5xc-auth 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Robin Mordasiewicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @robinmordasiewicz/f5xc-auth
+
+Shared authentication library for F5 Distributed Cloud MCP servers. Provides XDG-compliant profile management and credential handling.
+
+## Installation
+
+```bash
+npm install @robinmordasiewicz/f5xc-auth
+```
+
+## Features
+
+- **XDG-compliant profile storage** - Profiles stored in `~/.config/f5xc/profiles/`
+- **Multiple authentication methods** - API token, P12 certificate, or cert/key pair
+- **Environment variable priority** - Override profile settings with environment variables
+- **URL normalization** - Handles various F5XC tenant URL formats
+- **TLS configuration** - Custom CA bundles and insecure mode for staging
+
+## Usage
+
+### Basic Authentication
+
+```typescript
+import { CredentialManager } from '@robinmordasiewicz/f5xc-auth';
+
+const credentialManager = new CredentialManager();
+await credentialManager.initialize();
+
+if (credentialManager.isAuthenticated()) {
+  console.log(`Authenticated as: ${credentialManager.getTenant()}`);
+  console.log(`API URL: ${credentialManager.getApiUrl()}`);
+  console.log(`Namespace: ${credentialManager.getNamespace()}`);
+}
+```
+
+### Profile Management
+
+```typescript
+import { getProfileManager } from '@robinmordasiewicz/f5xc-auth';
+
+const profileManager = getProfileManager();
+
+// List all profiles
+const profiles = await profileManager.list();
+
+// Get active profile
+const active = await profileManager.getActiveProfile();
+
+// Save a new profile
+await profileManager.save({
+  name: 'production',
+  apiUrl: 'https://mytenant.console.ves.volterra.io',
+  apiToken: 'my-api-token',
+  defaultNamespace: 'my-namespace'
+});
+
+// Switch profiles
+await profileManager.setActive('production');
+```
+
+### HTTP Client
+
+```typescript
+import { CredentialManager, createHttpClient } from '@robinmordasiewicz/f5xc-auth';
+
+const credentialManager = new CredentialManager();
+await credentialManager.initialize();
+
+const httpClient = createHttpClient(credentialManager, {
+  timeout: 30000,
+  debug: true
+});
+
+if (httpClient.isAvailable()) {
+  const response = await httpClient.get('/web/namespaces');
+  console.log(response.data);
+}
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `F5XC_API_URL` | F5 XC tenant URL |
+| `F5XC_API_TOKEN` | API token for authentication |
+| `F5XC_P12_BUNDLE` | Path to P12 certificate bundle |
+| `F5XC_CERT` | Path to certificate file |
+| `F5XC_KEY` | Path to private key file |
+| `F5XC_NAMESPACE` | Default namespace |
+| `F5XC_TLS_INSECURE` | Disable TLS verification (staging only) |
+| `F5XC_CA_BUNDLE` | Path to custom CA bundle |
+
+Environment variables take priority over profile settings.
+
+## Credential Priority
+
+1. **Environment variables** (highest priority)
+2. **Active profile** from `~/.config/f5xc/`
+3. **Documentation mode** (no credentials - lowest priority)
+
+## Profile Format
+
+Profiles are stored as JSON files in `~/.config/f5xc/profiles/`:
+
+```json
+{
+  "name": "production",
+  "apiUrl": "https://mytenant.console.ves.volterra.io",
+  "apiToken": "your-api-token",
+  "defaultNamespace": "my-namespace"
+}
+```
+
+### Authentication Methods
+
+**API Token:**
+```json
+{
+  "name": "token-auth",
+  "apiUrl": "https://mytenant.console.ves.volterra.io",
+  "apiToken": "your-api-token"
+}
+```
+
+**P12 Certificate:**
+```json
+{
+  "name": "p12-auth",
+  "apiUrl": "https://mytenant.console.ves.volterra.io",
+  "p12Bundle": "/path/to/certificate.p12"
+}
+```
+
+**Cert + Key:**
+```json
+{
+  "name": "cert-auth",
+  "apiUrl": "https://mytenant.console.ves.volterra.io",
+  "cert": "/path/to/certificate.pem",
+  "key": "/path/to/private-key.pem"
+}
+```
+
+## Security
+
+- Profile files are created with `0o600` permissions (owner read/write only)
+- Config directory uses `0o700` permissions
+- Tokens are masked when displayed (showing only last 4 characters)
+- TLS insecure mode requires explicit opt-in
+
+## License
+
+MIT

package/dist/auth/credential-manager.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Credential Manager for F5 Distributed Cloud API
+ *
+ * Handles authentication configuration and URL normalization.
+ * Supports dual-mode operation:
+ * - Documentation mode: No credentials required
+ * - Execution mode: API token or P12/Certificate authentication
+ *
+ * Uses XDG-compliant profile storage at ~/.config/f5xc/
+ */
+/**
+ * Authentication modes supported by the server
+ */
+export declare enum AuthMode {
+    /** No authentication - documentation mode only */
+    NONE = "none",
+    /** API token authentication */
+    TOKEN = "token",
+    /** P12 certificate authentication (mTLS) */
+    CERTIFICATE = "certificate"
+}
+/**
+ * Environment variable names for authentication
+ * These take priority over profile settings
+ */
+export declare const AUTH_ENV_VARS: {
+    readonly API_URL: "F5XC_API_URL";
+    readonly API_TOKEN: "F5XC_API_TOKEN";
+    readonly P12_BUNDLE: "F5XC_P12_BUNDLE";
+    readonly CERT: "F5XC_CERT";
+    readonly KEY: "F5XC_KEY";
+    readonly NAMESPACE: "F5XC_NAMESPACE";
+    readonly TLS_INSECURE: "F5XC_TLS_INSECURE";
+    readonly CA_BUNDLE: "F5XC_CA_BUNDLE";
+};
+/**
+ * Credential configuration for API access
+ */
+export interface Credentials {
+    /** Authentication mode */
+    mode: AuthMode;
+    /** Normalized API URL */
+    apiUrl: string | null;
+    /** API token (for token auth) */
+    token: string | null;
+    /** P12 certificate buffer (for cert auth) */
+    p12Certificate: Buffer | null;
+    /** Certificate content (for mTLS) */
+    cert: string | null;
+    /** Private key content (for mTLS) */
+    key: string | null;
+    /** Default namespace */
+    namespace: string | null;
+    /** Disable TLS certificate verification (staging/development only) */
+    tlsInsecure: boolean;
+    /** Custom CA bundle for TLS verification */
+    caBundle: Buffer | null;
+}
+/**
+ * Normalize F5XC tenant URL to standard API endpoint format
+ *
+ * Handles various input formats:
+ * - tenant.volterra.us -> tenant.console.ves.volterra.io/api (production)
+ * - tenant.staging.volterra.us -> tenant.staging.volterra.us/api (staging - keep as-is)
+ * - tenant.console.ves.volterra.io -> tenant.console.ves.volterra.io/api
+ * - Any of the above with trailing slashes or /api suffix
+ *
+ * @param input - Raw URL from user configuration
+ * @returns Normalized API URL
+ */
+export declare function normalizeApiUrl(input: string): string;
+/**
+ * Extract tenant name from a normalized URL
+ *
+ * @param url - Normalized API URL
+ * @returns Tenant name or null if not parseable
+ */
+export declare function extractTenantFromUrl(url: string): string | null;
+/**
+ * Credential Manager
+ *
+ * Manages authentication credentials for F5 Distributed Cloud API.
+ * Supports credential loading with priority:
+ * 1. Environment variables (highest priority - overrides all)
+ * 2. Active profile from ~/.config/f5xc/ (XDG Base Directory compliant)
+ * 3. No credentials (documentation mode - lowest priority)
+ */
+export declare class CredentialManager {
+    private credentials;
+    private activeProfileName;
+    private initialized;
+    constructor();
+    /**
+     * Initialize credentials asynchronously
+     * Must be called before using credentials
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load credentials from environment variables
+     */
+    private loadFromEnvironment;
+    /**
+     * Load credentials from active profile
+     */
+    private loadFromProfile;
+    /**
+     * Build credentials object from profile data
+     */
+    private buildCredentials;
+    /**
+     * Load credentials with priority order:
+     * 1. Environment variables (highest)
+     * 2. Active profile from ~/.config/f5xc/
+     * 3. No credentials - documentation mode (lowest)
+     */
+    private loadCredentials;
+    /**
+     * Get the active profile name (if any)
+     * Returns null if credentials are from environment variables or no profile is active
+     */
+    getActiveProfile(): string | null;
+    /**
+     * Get the current authentication mode
+     */
+    getAuthMode(): AuthMode;
+    /**
+     * Check if the server is in authenticated mode
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get the normalized API URL
+     */
+    getApiUrl(): string | null;
+    /**
+     * Get the tenant name
+     */
+    getTenant(): string | null;
+    /**
+     * Get API token (for token authentication)
+     */
+    getToken(): string | null;
+    /**
+     * Get P12 certificate buffer (for certificate authentication)
+     */
+    getP12Certificate(): Buffer | null;
+    /**
+     * Get certificate content (for mTLS)
+     */
+    getCert(): string | null;
+    /**
+     * Get private key content (for mTLS)
+     */
+    getKey(): string | null;
+    /**
+     * Get default namespace
+     */
+    getNamespace(): string | null;
+    /**
+     * Check if TLS certificate verification is disabled
+     * WARNING: Only use for staging/development environments
+     */
+    getTlsInsecure(): boolean;
+    /**
+     * Get custom CA bundle for TLS verification
+     */
+    getCaBundle(): Buffer | null;
+    /**
+     * Get full credentials object
+     */
+    getCredentials(): Readonly<Credentials>;
+    /**
+     * Reload credentials from environment/profile
+     * Useful for testing or when credentials change
+     */
+    reload(): Promise<void>;
+}
+//# sourceMappingURL=credential-manager.d.ts.map

package/dist/auth/credential-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-manager.d.ts","sourceRoot":"","sources":["../../src/auth/credential-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;GAEG;AACH,oBAAY,QAAQ;IAClB,kDAAkD;IAClD,IAAI,SAAS;IACb,+BAA+B;IAC/B,KAAK,UAAU;IACf,4CAA4C;IAC5C,WAAW,gBAAgB;CAC5B;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;;;;;CAUhB,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,yBAAyB;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,iCAAiC;IACjC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6CAA6C;IAC7C,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qCAAqC;IACrC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,qCAAqC;IACrC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,wBAAwB;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sEAAsE;IACtE,WAAW,EAAE,OAAO,CAAC;IACrB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA8BrD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG/D;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,iBAAiB,CAAuB;IAChD,OAAO,CAAC,WAAW,CAAS;;IAiB5B;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA8B3B;;OAEG;YACW,eAAe;IAmB7B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiGxB;;;;;OAKG;YACW,eAAe;IA4C7B;;;OAGG;IACH,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACH,WAAW,IAAI,QAAQ;IAIvB;;OAEG;IACH,eAAe,IAAI,OAAO;IAI1B;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B;;OAEG;IACH,QAAQ,IAAI,MAAM,GAAG,IAAI;IAIzB;;OAEG;IACH,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAIlC;;OAEG;IACH,OAAO,IAAI,MAAM,GAAG,IAAI;IAIxB;;OAEG;IACH,MAAM,IAAI,MAAM,GAAG,IAAI;IAIvB;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B;;;OAGG;IACH,cAAc,IAAI,OAAO;IAIzB;;OAEG;IACH,WAAW,IAAI,MAAM,GAAG,IAAI;IAI5B;;OAEG;IACH,cAAc,IAAI,QAAQ,CAAC,WAAW,CAAC;IAIvC;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAK9B"}