@fractary/faber-cli 1.3.2 → 1.3.4

package/dist/lib/github-app-auth.js

@@ -0,0 +1,294 @@
+/**
+ * GitHub App Authentication Module
+ *
+ * Provides JWT generation, installation token exchange, and token caching
+ * for GitHub App authentication in FABER CLI.
+ */
+import jwt from 'jsonwebtoken';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+/**
+ * Private Key Loader
+ *
+ * Loads private keys from file path or environment variable
+ */
+export class PrivateKeyLoader {
+    /**
+     * Load private key from configured sources.
+     * Priority: env var > file path
+     *
+     * @param config - GitHub App configuration
+     * @returns The private key content
+     * @throws Error if private key cannot be loaded
+     */
+    static async load(config) {
+        // Try environment variable first (priority)
+        if (config.private_key_env_var) {
+            const envValue = process.env[config.private_key_env_var];
+            if (envValue) {
+                try {
+                    // Decode base64-encoded key
+                    const decoded = Buffer.from(envValue, 'base64').toString('utf-8');
+                    if (PrivateKeyLoader.validate(decoded)) {
+                        return decoded;
+                    }
+                }
+                catch {
+                    // Invalid base64, fall through to file path
+                }
+            }
+        }
+        // Try file path
+        if (config.private_key_path) {
+            try {
+                // Expand ~ to home directory
+                const expandedPath = config.private_key_path.startsWith('~')
+                    ? config.private_key_path.replace('~', os.homedir())
+                    : config.private_key_path;
+                const resolvedPath = path.resolve(expandedPath);
+                const key = await fs.readFile(resolvedPath, 'utf-8');
+                if (PrivateKeyLoader.validate(key)) {
+                    return key;
+                }
+                throw new Error('Invalid private key format. Expected PEM-encoded RSA private key');
+            }
+            catch (error) {
+                if (error instanceof Error && error.message.includes('ENOENT')) {
+                    throw new Error(`GitHub App private key not found at '${config.private_key_path}'. ` +
+                        `Check 'private_key_path' in config or set ${config.private_key_env_var || 'GITHUB_APP_PRIVATE_KEY'} env var`);
+                }
+                throw error;
+            }
+        }
+        throw new Error('GitHub App private key not found. ' +
+            "Configure 'private_key_path' in .fractary/settings.json or set GITHUB_APP_PRIVATE_KEY env var");
+    }
+    /**
+     * Validate private key format.
+     *
+     * @param key - The private key content
+     * @returns true if valid PEM format
+     */
+    static validate(key) {
+        // Check for PEM format (RSA or PKCS#8)
+        const trimmed = key.trim();
+        return ((trimmed.startsWith('-----BEGIN RSA PRIVATE KEY-----') &&
+            trimmed.endsWith('-----END RSA PRIVATE KEY-----')) ||
+            (trimmed.startsWith('-----BEGIN PRIVATE KEY-----') &&
+                trimmed.endsWith('-----END PRIVATE KEY-----')));
+    }
+}
+/**
+ * GitHub App Authentication
+ *
+ * Handles JWT generation, installation token exchange, and caching
+ */
+export class GitHubAppAuth {
+    constructor(config) {
+        this.cache = new Map();
+        this.refreshPromise = null;
+        this.config = config;
+    }
+    /**
+     * Get a valid installation token.
+     * Returns cached token if still valid, otherwise generates new one.
+     *
+     * @returns Installation access token
+     */
+    async getToken() {
+        const cacheKey = this.config.installation_id;
+        const cached = this.cache.get(cacheKey);
+        if (cached && !this.isExpired(cached) && !this.isExpiringSoon(cached)) {
+            return cached.token;
+        }
+        // If token is expiring soon but still valid, trigger background refresh
+        if (cached && !this.isExpired(cached) && this.isExpiringSoon(cached)) {
+            this.triggerBackgroundRefresh();
+            return cached.token;
+        }
+        // Token expired or missing, must refresh synchronously
+        return this.refreshToken();
+    }
+    /**
+     * Force refresh the token.
+     *
+     * @returns New installation access token
+     */
+    async refreshToken() {
+        // Deduplicate concurrent refresh requests
+        if (this.refreshPromise) {
+            return this.refreshPromise;
+        }
+        this.refreshPromise = this.doRefresh();
+        try {
+            return await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    /**
+     * Check if token needs refresh (within 5 minutes of expiration).
+     *
+     * @returns true if token should be refreshed
+     */
+    isTokenExpiringSoon() {
+        const cached = this.cache.get(this.config.installation_id);
+        return cached ? this.isExpiringSoon(cached) : true;
+    }
+    /**
+     * Validate the configuration and private key.
+     *
+     * @throws Error if configuration is invalid
+     */
+    async validate() {
+        // Validate required fields
+        if (!this.config.id) {
+            throw new Error("GitHub App ID is required. Configure 'app.id' in .fractary/settings.json");
+        }
+        if (!this.config.installation_id) {
+            throw new Error("GitHub App Installation ID is required. Configure 'app.installation_id' in .fractary/settings.json");
+        }
+        // Validate private key can be loaded
+        await PrivateKeyLoader.load(this.config);
+        // Attempt to generate JWT to validate key
+        await this.generateJWT();
+    }
+    /**
+     * Perform the actual token refresh
+     */
+    async doRefresh() {
+        const jwtToken = await this.generateJWT();
+        const installationToken = await this.exchangeForInstallationToken(jwtToken);
+        // Cache the token
+        this.cache.set(this.config.installation_id, {
+            token: installationToken.token,
+            expires_at: new Date(installationToken.expires_at),
+            installation_id: this.config.installation_id,
+        });
+        return installationToken.token;
+    }
+    /**
+     * Generate a JWT for GitHub App authentication
+     */
+    async generateJWT() {
+        const privateKey = await PrivateKeyLoader.load(this.config);
+        const now = Math.floor(Date.now() / 1000);
+        const payload = {
+            iat: now - 60, // Issued 60 seconds ago to allow for clock drift
+            exp: now + GitHubAppAuth.JWT_EXPIRY_SECONDS,
+            iss: this.config.id,
+        };
+        try {
+            return jwt.sign(payload, privateKey, { algorithm: 'RS256' });
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to generate JWT: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Exchange JWT for installation access token
+     */
+    async exchangeForInstallationToken(jwtToken) {
+        const url = `${GitHubAppAuth.GITHUB_API_URL}/app/installations/${this.config.installation_id}/access_tokens`;
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    Accept: 'application/vnd.github+json',
+                    Authorization: `Bearer ${jwtToken}`,
+                    'X-GitHub-Api-Version': '2022-11-28',
+                },
+            });
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to connect to GitHub API: ${error.message}`);
+            }
+            throw error;
+        }
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => 'Unknown error');
+            if (response.status === 401) {
+                throw new Error('Failed to authenticate with GitHub App. Verify App ID and private key are correct.');
+            }
+            if (response.status === 404) {
+                throw new Error(`GitHub App installation not found (ID: ${this.config.installation_id}). ` +
+                    'Verify the Installation ID is correct and the app is installed.');
+            }
+            if (response.status === 403) {
+                // Check for rate limiting
+                const rateLimitRemaining = response.headers.get('x-ratelimit-remaining');
+                const rateLimitReset = response.headers.get('x-ratelimit-reset');
+                if (rateLimitRemaining === '0' && rateLimitReset) {
+                    const resetTime = new Date(parseInt(rateLimitReset) * 1000);
+                    const secondsUntilReset = Math.ceil((resetTime.getTime() - Date.now()) / 1000);
+                    throw new Error(`GitHub API rate limited. Retry after ${secondsUntilReset} seconds.`);
+                }
+            }
+            throw new Error(`Failed to get installation token: ${response.status} ${errorBody}`);
+        }
+        return response.json();
+    }
+    /**
+     * Check if token is expired
+     */
+    isExpired(cached) {
+        return cached.expires_at.getTime() <= Date.now();
+    }
+    /**
+     * Check if token is expiring soon
+     */
+    isExpiringSoon(cached) {
+        return cached.expires_at.getTime() - Date.now() < GitHubAppAuth.REFRESH_THRESHOLD_MS;
+    }
+    /**
+     * Trigger background token refresh (non-blocking)
+     */
+    triggerBackgroundRefresh() {
+        if (this.refreshPromise) {
+            return; // Already refreshing
+        }
+        // Fire and forget - errors logged but not thrown
+        this.refreshToken().catch(error => {
+            console.error('[GitHubAppAuth] Background token refresh failed:', error.message);
+        });
+    }
+}
+// Token refresh threshold (5 minutes before expiration)
+GitHubAppAuth.REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
+// JWT validity period (10 minutes max for GitHub)
+GitHubAppAuth.JWT_EXPIRY_SECONDS = 600;
+// GitHub API base URL
+GitHubAppAuth.GITHUB_API_URL = 'https://api.github.com';
+/**
+ * Static Token Provider
+ *
+ * Simple provider for static PAT tokens
+ */
+export class StaticTokenProvider {
+    constructor(token) {
+        this.token = token;
+    }
+    async getToken() {
+        return this.token;
+    }
+}
+/**
+ * GitHub App Token Provider
+ *
+ * Provider that uses GitHubAppAuth for dynamic token generation
+ */
+export class GitHubAppTokenProvider {
+    constructor(auth) {
+        this.auth = auth;
+    }
+    async getToken() {
+        return this.auth.getToken();
+    }
+}

package/dist/lib/github-app-setup.d.ts

@@ -0,0 +1,142 @@
+/**
+ * GitHub App Manifest Flow for Automated Setup
+ *
+ * Provides functions for creating GitHub Apps via the App Manifest flow,
+ * which simplifies setup from 15+ manual steps to a single CLI command.
+ */
+/**
+ * Configuration for generating an app manifest
+ */
+export interface ManifestConfig {
+    organization: string;
+    repository: string;
+    appName?: string;
+}
+/**
+ * GitHub App Manifest structure
+ * @see https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest
+ */
+export interface GitHubAppManifest {
+    name: string;
+    url: string;
+    hook_attributes: {
+        url: string;
+    };
+    redirect_url?: string;
+    callback_urls?: string[];
+    setup_url?: string;
+    description: string;
+    public: boolean;
+    default_permissions: {
+        contents: 'read' | 'write';
+        issues: 'read' | 'write';
+        pull_requests: 'read' | 'write';
+        metadata: 'read';
+    };
+    default_events: string[];
+}
+/**
+ * Response from GitHub App Manifest conversion API
+ * @see https://docs.github.com/en/rest/apps/apps#create-a-github-app-from-a-manifest
+ */
+export interface ManifestConversionResponse {
+    id: number;
+    slug: string;
+    node_id: string;
+    owner: {
+        login: string;
+        id: number;
+    };
+    name: string;
+    description: string;
+    external_url: string;
+    html_url: string;
+    created_at: string;
+    updated_at: string;
+    permissions: {
+        contents?: string;
+        issues?: string;
+        metadata?: string;
+        pull_requests?: string;
+    };
+    events: string[];
+    installations_count: number;
+    client_id: string;
+    client_secret: string;
+    webhook_secret: string | null;
+    pem: string;
+}
+/**
+ * App credentials extracted from manifest conversion
+ */
+export interface AppCredentials {
+    id: string;
+    installation_id: string;
+    private_key: string;
+    app_slug: string;
+    app_name: string;
+}
+/**
+ * Generate GitHub App manifest with FABER's required permissions
+ */
+export declare function generateAppManifest(config: ManifestConfig): GitHubAppManifest;
+/**
+ * Generate HTML content for manifest submission
+ *
+ * The GitHub App Manifest flow requires POSTing a form to GitHub.
+ * Since CLI cannot POST directly, we generate an HTML file that the user
+ * opens in their browser and clicks to submit.
+ *
+ * @param manifest - The app manifest to submit
+ * @param organization - GitHub organization name
+ * @returns HTML content ready to save to file
+ */
+export declare function generateManifestHtml(manifest: GitHubAppManifest, organization: string): string;
+/**
+ * Generate GitHub App creation URL (legacy - prefer generateManifestHtml)
+ *
+ * @deprecated Use generateManifestHtml() instead for proper manifest flow
+ */
+export declare function getManifestCreationUrl(manifest: GitHubAppManifest): string;
+/**
+ * Exchange manifest code for app credentials
+ *
+ * @param code - The code from the GitHub redirect URL
+ * @returns App credentials from GitHub
+ * @throws Error if code is invalid or API request fails
+ */
+export declare function exchangeCodeForCredentials(code: string): Promise<ManifestConversionResponse>;
+/**
+ * Validate app credentials from manifest conversion
+ *
+ * @param response - The manifest conversion response
+ * @throws Error if response is invalid
+ */
+export declare function validateAppCredentials(response: ManifestConversionResponse): void;
+/**
+ * Fetch installation ID for the app in the specified organization
+ *
+ * @param appId - The GitHub App ID
+ * @param privateKey - The app's private key in PEM format
+ * @param organization - The GitHub organization name
+ * @returns The installation ID
+ * @throws Error if installation not found or authentication fails
+ */
+export declare function getInstallationId(appId: string, privateKey: string, organization: string): Promise<string>;
+/**
+ * Save private key to secure location
+ *
+ * @param privateKey - The private key content
+ * @param organization - The organization name (for filename)
+ * @returns Path to the saved private key file
+ * @throws Error if file cannot be saved
+ */
+export declare function savePrivateKey(privateKey: string, organization: string): Promise<string>;
+/**
+ * Format permissions for display
+ *
+ * @param manifest - The app manifest
+ * @returns Formatted permissions string
+ */
+export declare function formatPermissionsDisplay(manifest: GitHubAppManifest): string;
+//# sourceMappingURL=github-app-setup.d.ts.map

package/dist/lib/github-app-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app-setup.d.ts","sourceRoot":"","sources":["../../src/lib/github-app-setup.ts"],"names":[],"mappings":"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"}