@fractary/core 0.3.2 → 0.4.0

package/dist/auth/github-app-auth.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @fractary/core - GitHub App Authentication
+ *
+ * Full GitHub App authentication with JWT generation, token exchange, and caching.
+ */
+import type { GitHubAppConfig } from './types';
+/**
+ * GitHub App authentication handler
+ *
+ * Handles the complete GitHub App authentication flow:
+ * 1. Generates JWT signed with the app's private key
+ * 2. Exchanges JWT for an installation access token via GitHub API
+ * 3. Caches tokens and auto-refreshes before expiration
+ *
+ * @example
+ * ```typescript
+ * const auth = new GitHubAppAuth({
+ *   id: '123456',
+ *   installation_id: '789012',
+ *   private_key_path: '/path/to/private-key.pem'
+ * });
+ *
+ * const token = await auth.getInstallationToken();
+ * ```
+ */
+export declare class GitHubAppAuth {
+    private readonly config;
+    private readonly privateKey;
+    private cachedToken;
+    /** In-flight token request promise (for race condition prevention) */
+    private pendingTokenRequest;
+    /** Token refresh buffer - refresh 5 minutes before expiration */
+    private static readonly REFRESH_BUFFER_MS;
+    /** JWT expiration time - 10 minutes (GitHub's maximum) */
+    private static readonly JWT_EXPIRATION_SECONDS;
+    /**
+     * Create a new GitHub App authentication handler
+     *
+     * @param config GitHub App configuration
+     * @throws AuthenticationError if private key cannot be loaded
+     */
+    constructor(config: GitHubAppConfig);
+    /**
+     * Load private key from file or environment variable
+     *
+     * @returns The PEM-encoded private key
+     * @throws AuthenticationError if private key cannot be loaded
+     */
+    private loadPrivateKey;
+    /**
+     * Generate a JWT for GitHub App authentication
+     *
+     * The JWT is signed with the app's private key using RS256.
+     *
+     * @returns Signed JWT string
+     */
+    private generateJWT;
+    /**
+     * Exchange JWT for an installation access token
+     *
+     * @returns Installation access token response from GitHub
+     * @throws AuthenticationError if token exchange fails
+     */
+    private exchangeJWTForToken;
+    /**
+     * Check if the cached token is still valid
+     *
+     * A token is considered valid if it exists and won't expire within
+     * the refresh buffer window (5 minutes).
+     *
+     * @returns true if cached token is valid and not near expiration
+     */
+    private isCachedTokenValid;
+    /**
+     * Get a valid installation access token
+     *
+     * Returns a cached token if still valid, otherwise generates a new one.
+     * Tokens are automatically refreshed 5 minutes before expiration.
+     *
+     * Thread-safe: concurrent calls will share the same pending request
+     * to prevent redundant API calls and potential rate limiting.
+     *
+     * @returns Installation access token string
+     * @throws AuthenticationError if token cannot be obtained
+     */
+    getInstallationToken(): Promise<string>;
+    /**
+     * Internal method to fetch and cache token
+     * Separated from getInstallationToken to enable promise sharing
+     */
+    private fetchAndCacheToken;
+    /**
+     * Clear the cached token
+     *
+     * Forces the next getInstallationToken() call to fetch a fresh token.
+     * Note: Does not cancel any in-flight request.
+     */
+    clearCache(): void;
+    /**
+     * Get information about the cached token (for debugging)
+     *
+     * @returns Object with cache status, or null if no cached token
+     */
+    getCacheInfo(): {
+        expiresAt: Date;
+        isValid: boolean;
+    } | null;
+}
+//# sourceMappingURL=github-app-auth.d.ts.map

package/dist/auth/github-app-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app-auth.d.ts","sourceRoot":"","sources":["../../src/auth/github-app-auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAW/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,WAAW,CAA4B;IAE/C,sEAAsE;IACtE,OAAO,CAAC,mBAAmB,CAAgC;IAE3D,iEAAiE;IACjE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAiB;IAE1D,0DAA0D;IAC1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAO;IAErD;;;;;OAKG;gBACS,MAAM,EAAE,eAAe;IAKnC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAoDtB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAenB;;;;;OAKG;YACW,mBAAmB;IAiCjC;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;;;;;;;;;;OAWG;IACG,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC;IAuB7C;;;OAGG;YACW,kBAAkB;IAahC;;;;;OAKG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;OAIG;IACH,YAAY,IAAI;QAAE,SAAS,EAAE,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;CAQ7D"}

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

@@ -0,0 +1,262 @@
+"use strict";
+/**
+ * @fractary/core - GitHub App Authentication
+ *
+ * Full GitHub App authentication with JWT generation, token exchange, and caching.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubAppAuth = void 0;
+const fs = __importStar(require("fs"));
+const jwt = __importStar(require("jsonwebtoken"));
+const errors_1 = require("../common/errors");
+/**
+ * GitHub App authentication handler
+ *
+ * Handles the complete GitHub App authentication flow:
+ * 1. Generates JWT signed with the app's private key
+ * 2. Exchanges JWT for an installation access token via GitHub API
+ * 3. Caches tokens and auto-refreshes before expiration
+ *
+ * @example
+ * ```typescript
+ * const auth = new GitHubAppAuth({
+ *   id: '123456',
+ *   installation_id: '789012',
+ *   private_key_path: '/path/to/private-key.pem'
+ * });
+ *
+ * const token = await auth.getInstallationToken();
+ * ```
+ */
+class GitHubAppAuth {
+    config;
+    privateKey;
+    cachedToken = null;
+    /** In-flight token request promise (for race condition prevention) */
+    pendingTokenRequest = null;
+    /** Token refresh buffer - refresh 5 minutes before expiration */
+    static REFRESH_BUFFER_MS = 5 * 60 * 1000;
+    /** JWT expiration time - 10 minutes (GitHub's maximum) */
+    static JWT_EXPIRATION_SECONDS = 600;
+    /**
+     * Create a new GitHub App authentication handler
+     *
+     * @param config GitHub App configuration
+     * @throws AuthenticationError if private key cannot be loaded
+     */
+    constructor(config) {
+        this.config = config;
+        this.privateKey = this.loadPrivateKey();
+    }
+    /**
+     * Load private key from file or environment variable
+     *
+     * @returns The PEM-encoded private key
+     * @throws AuthenticationError if private key cannot be loaded
+     */
+    loadPrivateKey() {
+        // Try loading from file path first
+        if (this.config.private_key_path) {
+            try {
+                const keyPath = this.config.private_key_path;
+                if (!fs.existsSync(keyPath)) {
+                    throw new errors_1.AuthenticationError('github-app', `Private key file not found: ${keyPath}`);
+                }
+                return fs.readFileSync(keyPath, 'utf-8');
+            }
+            catch (error) {
+                if (error instanceof errors_1.AuthenticationError)
+                    throw error;
+                throw new errors_1.AuthenticationError('github-app', `Failed to read private key file: ${error.message}`);
+            }
+        }
+        // Try loading from environment variable (base64-encoded)
+        if (this.config.private_key_env_var) {
+            const envValue = process.env[this.config.private_key_env_var];
+            if (!envValue) {
+                throw new errors_1.AuthenticationError('github-app', `Environment variable ${this.config.private_key_env_var} is not set`);
+            }
+            try {
+                // Decode base64-encoded private key
+                const decoded = Buffer.from(envValue, 'base64').toString('utf-8');
+                if (!decoded.includes('-----BEGIN')) {
+                    throw new Error('Decoded value does not appear to be a PEM key');
+                }
+                return decoded;
+            }
+            catch (error) {
+                throw new errors_1.AuthenticationError('github-app', `Failed to decode private key from ${this.config.private_key_env_var}: ${error.message}`);
+            }
+        }
+        throw new errors_1.AuthenticationError('github-app', 'GitHub App config must specify either private_key_path or private_key_env_var');
+    }
+    /**
+     * Generate a JWT for GitHub App authentication
+     *
+     * The JWT is signed with the app's private key using RS256.
+     *
+     * @returns Signed JWT string
+     */
+    generateJWT() {
+        const now = Math.floor(Date.now() / 1000);
+        const payload = {
+            // Issued at time (60 seconds in the past to account for clock drift)
+            iat: now - 60,
+            // Expiration time (10 minutes from now)
+            exp: now + GitHubAppAuth.JWT_EXPIRATION_SECONDS,
+            // GitHub App's identifier
+            iss: this.config.id,
+        };
+        return jwt.sign(payload, this.privateKey, { algorithm: 'RS256' });
+    }
+    /**
+     * Exchange JWT for an installation access token
+     *
+     * @returns Installation access token response from GitHub
+     * @throws AuthenticationError if token exchange fails
+     */
+    async exchangeJWTForToken() {
+        const jwtToken = this.generateJWT();
+        const url = `https://api.github.com/app/installations/${this.config.installation_id}/access_tokens`;
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Accept': 'application/vnd.github+json',
+                    'Authorization': `Bearer ${jwtToken}`,
+                    'X-GitHub-Api-Version': '2022-11-28',
+                },
+            });
+            if (!response.ok) {
+                const errorBody = await response.text();
+                throw new errors_1.AuthenticationError('github-app', `GitHub API returned ${response.status}: ${errorBody}`);
+            }
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            if (error instanceof errors_1.AuthenticationError)
+                throw error;
+            throw new errors_1.AuthenticationError('github-app', `Failed to exchange JWT for installation token: ${error.message}`);
+        }
+    }
+    /**
+     * Check if the cached token is still valid
+     *
+     * A token is considered valid if it exists and won't expire within
+     * the refresh buffer window (5 minutes).
+     *
+     * @returns true if cached token is valid and not near expiration
+     */
+    isCachedTokenValid() {
+        if (!this.cachedToken)
+            return false;
+        const now = new Date();
+        const expirationWithBuffer = new Date(this.cachedToken.expiresAt.getTime() - GitHubAppAuth.REFRESH_BUFFER_MS);
+        return now < expirationWithBuffer;
+    }
+    /**
+     * Get a valid installation access token
+     *
+     * Returns a cached token if still valid, otherwise generates a new one.
+     * Tokens are automatically refreshed 5 minutes before expiration.
+     *
+     * Thread-safe: concurrent calls will share the same pending request
+     * to prevent redundant API calls and potential rate limiting.
+     *
+     * @returns Installation access token string
+     * @throws AuthenticationError if token cannot be obtained
+     */
+    async getInstallationToken() {
+        // Return cached token if still valid
+        if (this.isCachedTokenValid()) {
+            return this.cachedToken.token;
+        }
+        // If there's already a pending request, wait for it
+        // This prevents multiple concurrent calls from triggering multiple API requests
+        if (this.pendingTokenRequest) {
+            return this.pendingTokenRequest;
+        }
+        // Create a new token request and track it
+        this.pendingTokenRequest = this.fetchAndCacheToken();
+        try {
+            return await this.pendingTokenRequest;
+        }
+        finally {
+            // Clear the pending request once complete (success or failure)
+            this.pendingTokenRequest = null;
+        }
+    }
+    /**
+     * Internal method to fetch and cache token
+     * Separated from getInstallationToken to enable promise sharing
+     */
+    async fetchAndCacheToken() {
+        // Exchange JWT for new installation token
+        const response = await this.exchangeJWTForToken();
+        // Cache the token
+        this.cachedToken = {
+            token: response.token,
+            expiresAt: new Date(response.expires_at),
+        };
+        return response.token;
+    }
+    /**
+     * Clear the cached token
+     *
+     * Forces the next getInstallationToken() call to fetch a fresh token.
+     * Note: Does not cancel any in-flight request.
+     */
+    clearCache() {
+        this.cachedToken = null;
+        this.pendingTokenRequest = null;
+    }
+    /**
+     * Get information about the cached token (for debugging)
+     *
+     * @returns Object with cache status, or null if no cached token
+     */
+    getCacheInfo() {
+        if (!this.cachedToken)
+            return null;
+        return {
+            expiresAt: this.cachedToken.expiresAt,
+            isValid: this.isCachedTokenValid(),
+        };
+    }
+}
+exports.GitHubAppAuth = GitHubAppAuth;
+//# sourceMappingURL=github-app-auth.js.map

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

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

package/dist/auth/github-app-token-provider.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @fractary/core - GitHub App Token Provider
+ *
+ * TokenProvider implementation that wraps GitHubAppAuth.
+ */
+import type { TokenProvider, GitHubAppConfig } from './types';
+/**
+ * GitHub App token provider
+ *
+ * Implements the TokenProvider interface using GitHub App authentication.
+ * Wraps GitHubAppAuth to provide automatic token caching and refresh.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GitHubAppTokenProvider({
+ *   id: '123456',
+ *   installation_id: '789012',
+ *   private_key_path: '/path/to/private-key.pem'
+ * });
+ *
+ * const token = await provider.getToken();
+ * ```
+ */
+export declare class GitHubAppTokenProvider implements TokenProvider {
+    private readonly auth;
+    /**
+     * Create a new GitHub App token provider
+     *
+     * @param config GitHub App configuration
+     * @throws AuthenticationError if private key cannot be loaded
+     */
+    constructor(config: GitHubAppConfig);
+    /**
+     * Get a valid authentication token
+     *
+     * Delegates to GitHubAppAuth.getInstallationToken() which handles
+     * caching and automatic refresh.
+     *
+     * @returns Promise resolving to the installation access token
+     * @throws AuthenticationError if token cannot be obtained
+     */
+    getToken(): Promise<string>;
+    /**
+     * Clear the token cache
+     *
+     * Forces the next getToken() call to fetch a fresh token.
+     */
+    clearCache(): void;
+    /**
+     * Get cache information (for debugging)
+     *
+     * @returns Cache status or null if no cached token
+     */
+    getCacheInfo(): {
+        expiresAt: Date;
+        isValid: boolean;
+    } | null;
+}
+//# sourceMappingURL=github-app-token-provider.d.ts.map

package/dist/auth/github-app-token-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app-token-provider.d.ts","sourceRoot":"","sources":["../../src/auth/github-app-token-provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG9D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAuB,YAAW,aAAa;IAC1D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IAErC;;;;;OAKG;gBACS,MAAM,EAAE,eAAe;IAInC;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAIjC;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAIlB;;;;OAIG;IACH,YAAY,IAAI;QAAE,SAAS,EAAE,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;CAG7D"}

package/dist/auth/github-app-token-provider.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * @fractary/core - GitHub App Token Provider
+ *
+ * TokenProvider implementation that wraps GitHubAppAuth.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubAppTokenProvider = void 0;
+const github_app_auth_1 = require("./github-app-auth");
+/**
+ * GitHub App token provider
+ *
+ * Implements the TokenProvider interface using GitHub App authentication.
+ * Wraps GitHubAppAuth to provide automatic token caching and refresh.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GitHubAppTokenProvider({
+ *   id: '123456',
+ *   installation_id: '789012',
+ *   private_key_path: '/path/to/private-key.pem'
+ * });
+ *
+ * const token = await provider.getToken();
+ * ```
+ */
+class GitHubAppTokenProvider {
+    auth;
+    /**
+     * Create a new GitHub App token provider
+     *
+     * @param config GitHub App configuration
+     * @throws AuthenticationError if private key cannot be loaded
+     */
+    constructor(config) {
+        this.auth = new github_app_auth_1.GitHubAppAuth(config);
+    }
+    /**
+     * Get a valid authentication token
+     *
+     * Delegates to GitHubAppAuth.getInstallationToken() which handles
+     * caching and automatic refresh.
+     *
+     * @returns Promise resolving to the installation access token
+     * @throws AuthenticationError if token cannot be obtained
+     */
+    async getToken() {
+        return this.auth.getInstallationToken();
+    }
+    /**
+     * Clear the token cache
+     *
+     * Forces the next getToken() call to fetch a fresh token.
+     */
+    clearCache() {
+        this.auth.clearCache();
+    }
+    /**
+     * Get cache information (for debugging)
+     *
+     * @returns Cache status or null if no cached token
+     */
+    getCacheInfo() {
+        return this.auth.getCacheInfo();
+    }
+}
+exports.GitHubAppTokenProvider = GitHubAppTokenProvider;
+//# sourceMappingURL=github-app-token-provider.js.map

package/dist/auth/github-app-token-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app-token-provider.js","sourceRoot":"","sources":["../../src/auth/github-app-token-provider.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAGH,uDAAkD;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,sBAAsB;IAChB,IAAI,CAAgB;IAErC;;;;;OAKG;IACH,YAAY,MAAuB;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,+BAAa,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,QAAQ;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,UAAU;QACR,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;IAClC,CAAC;CACF;AA3CD,wDA2CC"}

package/dist/auth/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fractary/core - Authentication Module
+ *
+ * Provides token providers and utilities for GitHub authentication.
+ * Supports both Personal Access Token (PAT) and GitHub App authentication.
+ */
+export type { TokenProvider, GitHubAppConfig, GitHubConfig } from './types';
+export { StaticTokenProvider } from './static-token-provider';
+export { GitHubAppAuth } from './github-app-auth';
+export { GitHubAppTokenProvider } from './github-app-token-provider';
+import type { TokenProvider, GitHubConfig } from './types';
+/**
+ * Create a token provider from GitHub configuration
+ *
+ * Priority order:
+ * 1. If config.app has id + installation_id → GitHubAppTokenProvider
+ * 2. If GITHUB_TOKEN env var or config.token → StaticTokenProvider
+ * 3. Otherwise throws AuthenticationError
+ *
+ * @param config GitHub configuration object
+ * @returns TokenProvider instance
+ * @throws AuthenticationError if no valid authentication method is found
+ *
+ * @example
+ * ```typescript
+ * // GitHub App authentication
+ * const provider = createTokenProvider({
+ *   app: {
+ *     id: '123456',
+ *     installation_id: '789012',
+ *     private_key_path: '/path/to/key.pem'
+ *   }
+ * });
+ *
+ * // PAT authentication
+ * const provider = createTokenProvider({
+ *   token: 'ghp_xxxx'
+ * });
+ *
+ * // Environment variable (GITHUB_TOKEN)
+ * const provider = createTokenProvider({});
+ * ```
+ */
+export declare function createTokenProvider(config?: GitHubConfig): TokenProvider;
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAK3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,YAAiB,GAAG,aAAa,CA6B5E"}

package/dist/auth/index.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * @fractary/core - Authentication Module
+ *
+ * Provides token providers and utilities for GitHub authentication.
+ * Supports both Personal Access Token (PAT) and GitHub App authentication.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubAppTokenProvider = exports.GitHubAppAuth = exports.StaticTokenProvider = void 0;
+exports.createTokenProvider = createTokenProvider;
+// Providers
+var static_token_provider_1 = require("./static-token-provider");
+Object.defineProperty(exports, "StaticTokenProvider", { enumerable: true, get: function () { return static_token_provider_1.StaticTokenProvider; } });
+var github_app_auth_1 = require("./github-app-auth");
+Object.defineProperty(exports, "GitHubAppAuth", { enumerable: true, get: function () { return github_app_auth_1.GitHubAppAuth; } });
+var github_app_token_provider_1 = require("./github-app-token-provider");
+Object.defineProperty(exports, "GitHubAppTokenProvider", { enumerable: true, get: function () { return github_app_token_provider_1.GitHubAppTokenProvider; } });
+const static_token_provider_2 = require("./static-token-provider");
+const github_app_token_provider_2 = require("./github-app-token-provider");
+const errors_1 = require("../common/errors");
+/**
+ * Create a token provider from GitHub configuration
+ *
+ * Priority order:
+ * 1. If config.app has id + installation_id → GitHubAppTokenProvider
+ * 2. If GITHUB_TOKEN env var or config.token → StaticTokenProvider
+ * 3. Otherwise throws AuthenticationError
+ *
+ * @param config GitHub configuration object
+ * @returns TokenProvider instance
+ * @throws AuthenticationError if no valid authentication method is found
+ *
+ * @example
+ * ```typescript
+ * // GitHub App authentication
+ * const provider = createTokenProvider({
+ *   app: {
+ *     id: '123456',
+ *     installation_id: '789012',
+ *     private_key_path: '/path/to/key.pem'
+ *   }
+ * });
+ *
+ * // PAT authentication
+ * const provider = createTokenProvider({
+ *   token: 'ghp_xxxx'
+ * });
+ *
+ * // Environment variable (GITHUB_TOKEN)
+ * const provider = createTokenProvider({});
+ * ```
+ */
+function createTokenProvider(config = {}) {
+    // Priority 1: GitHub App authentication
+    if (config.app?.id && config.app?.installation_id) {
+        if (!config.app.private_key_path && !config.app.private_key_env_var) {
+            throw new errors_1.AuthenticationError('github-app', 'GitHub App config must specify either private_key_path or private_key_env_var');
+        }
+        return new github_app_token_provider_2.GitHubAppTokenProvider(config.app);
+    }
+    // Priority 2: PAT from config
+    if (config.token) {
+        return new static_token_provider_2.StaticTokenProvider(config.token);
+    }
+    // Priority 3: PAT from environment variable
+    const envToken = process.env.GITHUB_TOKEN;
+    if (envToken) {
+        return new static_token_provider_2.StaticTokenProvider(envToken);
+    }
+    // No valid authentication method found
+    throw new errors_1.AuthenticationError('github', 'No GitHub authentication configured. Set GITHUB_TOKEN environment variable, ' +
+        'provide a token in config, or configure GitHub App authentication.');
+}
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAgDH,kDA6BC;AAxED,YAAY;AACZ,iEAA8D;AAArD,4HAAA,mBAAmB,OAAA;AAC5B,qDAAkD;AAAzC,gHAAA,aAAa,OAAA;AACtB,yEAAqE;AAA5D,mIAAA,sBAAsB,OAAA;AAI/B,mEAA8D;AAC9D,2EAAqE;AACrE,6CAAuD;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAgB,mBAAmB,CAAC,SAAuB,EAAE;IAC3D,wCAAwC;IACxC,IAAI,MAAM,CAAC,GAAG,EAAE,EAAE,IAAI,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,CAAC;QAClD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,gBAAgB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC;YACpE,MAAM,IAAI,4BAAmB,CAC3B,YAAY,EACZ,+EAA+E,CAChF,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,kDAAsB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IAED,8BAA8B;IAC9B,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,IAAI,2CAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/C,CAAC;IAED,4CAA4C;IAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAC1C,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,IAAI,2CAAmB,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,uCAAuC;IACvC,MAAM,IAAI,4BAAmB,CAC3B,QAAQ,EACR,8EAA8E;QAC9E,oEAAoE,CACrE,CAAC;AACJ,CAAC"}