@flink-app/github-app-plugin 0.12.1-alpha.38

package/SECURITY.md

@@ -0,0 +1,498 @@
+# Security Considerations
+
+This document outlines the security measures, best practices, and considerations when using the GitHub App Plugin.
+
+## Table of Contents
+
+- [Private Key Management](#private-key-management)
+- [JWT Signing Security](#jwt-signing-security)
+- [Webhook Signature Validation](#webhook-signature-validation)
+- [CSRF Protection](#csrf-protection)
+- [Token Caching Security](#token-caching-security)
+- [HTTPS Requirements](#https-requirements)
+- [Secrets Management](#secrets-management)
+- [Security Checklist](#security-checklist)
+- [Reporting Security Issues](#reporting-security-issues)
+
+## Private Key Management
+
+### Storage
+
+**Environment Variables (Required for Production):**
+
+```bash
+# .env
+GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
+MIIEpAIBAAKCAQEA...
+...
+-----END RSA PRIVATE KEY-----"
+```
+
+**DO NOT:**
+- Commit private keys to version control
+- Store keys in application code
+- Share keys via email or messaging
+- Store keys in plain text files in production
+- Include keys in client-side code
+
+**DO:**
+- Store keys in environment variables
+- Use secret management services (AWS Secrets Manager, Azure Key Vault, etc.)
+- Rotate keys periodically (recommended: every 90 days)
+- Use different keys for different environments (dev, staging, prod)
+- Restrict access to keys using IAM policies
+
+### PEM Format
+
+The plugin automatically detects and supports both PEM formats:
+
+**PKCS#1 Format:**
+```
+-----BEGIN RSA PRIVATE KEY-----
+MIIEpAIBAAKCAQEA...
+-----END RSA PRIVATE KEY-----
+```
+
+**PKCS#8 Format:**
+```
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBK...
+-----END PRIVATE KEY-----
+```
+
+### Key Validation
+
+The plugin validates the private key on initialization:
+
+- Checks PEM format (BEGIN/END markers)
+- Verifies key can sign JWTs
+- Tests signature generation
+- Fails fast with clear error messages
+
+### Key Rotation
+
+To rotate your GitHub App private key:
+
+1. Generate new private key in GitHub App settings
+2. Download new key
+3. Update environment variable with new key
+4. Restart application
+5. Revoke old key in GitHub App settings
+6. Monitor for errors
+
+## JWT Signing Security
+
+### Algorithm
+
+The plugin uses **RS256** (RSA Signature with SHA-256) for JWT signing:
+
+- Industry standard algorithm
+- Asymmetric encryption (private key signs, public key verifies)
+- More secure than symmetric algorithms (HS256)
+- GitHub requires RS256 for GitHub Apps
+
+### JWT Structure
+
+```typescript
+{
+  iat: <timestamp>,        // Issued at time
+  exp: <timestamp + 600>,  // Expires at time (10 minutes)
+  iss: <appId>            // Issuer (GitHub App ID)
+}
+```
+
+### Token Expiration
+
+- JWTs expire after **10 minutes** (600 seconds)
+- Short expiration reduces risk of token compromise
+- Tokens are only used to obtain installation access tokens
+- Installation access tokens are cached separately
+
+### Best Practices
+
+- Never expose JWTs to client-side code
+- Validate JWT expiration before use
+- Use HTTPS for all API calls
+- Monitor JWT generation errors
+- Implement rate limiting on authentication endpoints
+
+## Webhook Signature Validation
+
+### HMAC-SHA256
+
+The plugin validates webhook signatures using HMAC-SHA256:
+
+```typescript
+// Signature generation (by GitHub)
+signature = HMAC-SHA256(secret, payload)
+
+// Signature validation (by plugin)
+expectedSignature = HMAC-SHA256(webhookSecret, rawBody)
+isValid = constantTimeCompare(signature, expectedSignature)
+```
+
+### Constant-Time Comparison
+
+The plugin uses `crypto.timingSafeEqual()` for signature comparison:
+
+- Prevents timing attacks
+- Ensures comparison takes same time for valid and invalid signatures
+- Required for security-critical comparisons
+
+**Vulnerable Code (DO NOT USE):**
+```typescript
+// Timing attack vulnerable
+if (signature === expectedSignature) { ... }
+```
+
+**Secure Code (USED BY PLUGIN):**
+```typescript
+// Timing attack resistant
+if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) { ... }
+```
+
+### Signature Header
+
+Webhooks include `X-Hub-Signature-256` header:
+
+```
+X-Hub-Signature-256: sha256=<signature>
+```
+
+The plugin:
+1. Extracts signature from header
+2. Reads raw request body (before JSON parsing)
+3. Computes expected signature using webhook secret
+4. Compares using constant-time comparison
+5. Rejects webhook if signatures don't match (401 status)
+
+### Webhook Secret
+
+**Generate Secure Webhook Secret:**
+
+```bash
+# Generate random 32-byte secret
+openssl rand -hex 32
+```
+
+**Store in Environment Variables:**
+
+```bash
+GITHUB_WEBHOOK_SECRET=your-webhook-secret-here
+```
+
+**Configure in GitHub App:**
+
+1. Go to GitHub App settings
+2. Find "Webhook secret" field
+3. Enter the same secret used in plugin configuration
+4. Save changes
+
+## CSRF Protection
+
+### State Parameter
+
+The plugin implements CSRF protection using state parameter:
+
+**Flow:**
+
+1. User initiates installation
+2. Plugin generates cryptographically secure state (32 bytes)
+3. Plugin stores state in session (MongoDB) with TTL
+4. Plugin redirects to GitHub with state parameter
+5. GitHub redirects back with state parameter
+6. Plugin validates state using constant-time comparison
+7. Plugin deletes session (one-time use)
+
+**State Generation:**
+
+```typescript
+// Cryptographically secure random generation
+const state = crypto.randomBytes(32).toString('hex');
+```
+
+### Session Management
+
+**Session Schema:**
+
+```typescript
+{
+  sessionId: string;     // Unique session ID
+  state: string;         // CSRF state parameter
+  userId?: string;       // Optional user ID
+  createdAt: Date;       // Session creation time
+}
+```
+
+**Session TTL:**
+
+- Default: **10 minutes** (600 seconds)
+- Configurable via `sessionTTL` option
+- Automatic cleanup via MongoDB TTL index
+- One-time use: deleted after successful callback
+
+### State Validation
+
+**Validation Steps:**
+
+1. Extract state from query parameter
+2. Find session in database
+3. Compare state using constant-time comparison
+4. Check session hasn't expired
+5. Delete session (prevent replay attacks)
+
+**Security Properties:**
+
+- One-time use (session deleted after validation)
+- Time-limited (TTL expiration)
+- Constant-time comparison (timing attack resistant)
+- Unpredictable (32-byte random value)
+
+## Token Caching Security
+
+### In-Memory Only
+
+Installation access tokens are cached **in-memory only**:
+
+**DO:**
+- Cache tokens in memory for performance
+- Clear cache periodically
+- Limit cache size
+
+**DO NOT:**
+- Store tokens in database
+- Log tokens to files
+- Send tokens to client
+- Store tokens in browser storage
+
+### Cache Structure
+
+```typescript
+// In-memory cache (Map)
+{
+  [installationId]: {
+    token: string,
+    expiresAt: number  // Unix timestamp
+  }
+}
+```
+
+### Token Expiration
+
+- Installation access tokens expire after **60 minutes**
+- Plugin caches tokens for **55 minutes** (5-minute safety margin)
+- Automatic refresh when expired
+- Manual cache clearing via `clearTokenCache()`
+
+### Cache Clearing
+
+**When to Clear Cache:**
+
+- Application shutdown
+- Security incident
+- Force token refresh
+- Memory pressure
+
+**How to Clear Cache:**
+
+```typescript
+ctx.plugins.githubApp.clearTokenCache();
+```
+
+### Token Security
+
+- Tokens never exposed to client
+- Tokens automatically expire
+- Tokens scoped to installation
+- Tokens revoked if installation deleted
+
+## HTTPS Requirements
+
+### Production Requirements
+
+**All endpoints MUST use HTTPS in production:**
+
+- GitHub App callback URL
+- Webhook URL
+- API calls to GitHub
+- All client-facing endpoints
+
+### Why HTTPS is Required
+
+- Prevents man-in-the-middle attacks
+- Protects tokens in transit
+- Required by GitHub for OAuth and webhooks
+- Industry best practice
+
+### Development
+
+For local development, you can use:
+
+- ngrok for HTTPS tunneling
+- localhost with self-signed certificates
+- Development-only HTTP (not recommended)
+
+**ngrok Example:**
+
+```bash
+ngrok http 3000
+# Use ngrok URL for GitHub App callback and webhook URLs
+```
+
+## Secrets Management
+
+### Environment Variables
+
+**Required Secrets:**
+
+```bash
+GITHUB_APP_ID=123456
+GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."
+GITHUB_WEBHOOK_SECRET=your-webhook-secret
+GITHUB_APP_CLIENT_ID=Iv1.abc123
+GITHUB_APP_CLIENT_SECRET=your-client-secret
+```
+
+### Production Best Practices
+
+**Use Secret Management Services:**
+
+- **AWS Secrets Manager** - Rotate secrets automatically
+- **Azure Key Vault** - Centralized secret management
+- **Google Secret Manager** - GCP native solution
+- **HashiCorp Vault** - Open-source option
+
+**DO NOT:**
+- Commit secrets to version control
+- Share secrets via email or chat
+- Store secrets in plain text files
+- Include secrets in error messages
+- Log secrets to console or files
+
+**DO:**
+- Use environment variables
+- Rotate secrets regularly
+- Use different secrets per environment
+- Implement least privilege access
+- Monitor secret access
+
+### .gitignore
+
+Ensure your `.gitignore` includes:
+
+```gitignore
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+secrets/
+```
+
+### Secret Rotation
+
+**Regular Rotation Schedule:**
+
+- Private key: Every 90 days
+- Webhook secret: Every 90 days
+- Client secret: Every 90 days
+
+**Emergency Rotation:**
+
+- Immediately if compromised
+- After security incident
+- After employee departure
+- After third-party breach
+
+## Security Checklist
+
+### Pre-Deployment
+
+- [ ] All secrets stored in environment variables
+- [ ] No secrets committed to version control
+- [ ] HTTPS enabled for all endpoints
+- [ ] Webhook signature validation enabled
+- [ ] CSRF protection enabled
+- [ ] Private key validated on startup
+- [ ] Token caching configured properly
+- [ ] Session TTL configured appropriately
+- [ ] MongoDB connection secured with authentication
+- [ ] Error messages don't expose sensitive information
+
+### Production
+
+- [ ] Webhook secret is cryptographically secure
+- [ ] Private key rotated within 90 days
+- [ ] HTTPS certificates are valid and not expired
+- [ ] Rate limiting configured
+- [ ] Monitoring and alerting configured
+- [ ] Logs don't contain secrets
+- [ ] IAM policies restrict secret access
+- [ ] Backup and disaster recovery plan in place
+
+### Monitoring
+
+- [ ] Monitor webhook signature failures
+- [ ] Monitor JWT generation errors
+- [ ] Monitor token cache hit rate
+- [ ] Monitor installation creation/deletion
+- [ ] Alert on repeated authentication failures
+- [ ] Alert on unexpected webhook deliveries
+
+### Incident Response
+
+- [ ] Rotate all secrets immediately
+- [ ] Clear token cache
+- [ ] Review audit logs
+- [ ] Identify compromised installations
+- [ ] Notify affected users
+- [ ] Document incident and lessons learned
+
+## Reporting Security Issues
+
+If you discover a security vulnerability in this plugin, please report it responsibly:
+
+**DO NOT:**
+- Open public GitHub issues for security vulnerabilities
+- Disclose vulnerabilities publicly before patch is available
+- Exploit vulnerabilities in production systems
+
+**DO:**
+- Email security concerns to: [Your security email]
+- Provide detailed reproduction steps
+- Wait for response before public disclosure
+- Follow responsible disclosure practices
+
+**Expected Response Time:**
+
+- Initial response: Within 48 hours
+- Status update: Within 1 week
+- Patch release: Varies based on severity
+
+### Security Updates
+
+Subscribe to security updates:
+
+- Watch GitHub repository for security advisories
+- Follow release notes for security patches
+- Enable GitHub Dependabot alerts
+
+## Additional Resources
+
+- [GitHub App Security Best Practices](https://docs.github.com/en/developers/apps/getting-started-with-apps/best-practices-for-creating-a-github-app)
+- [Webhook Security](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks)
+- [JWT Best Practices](https://tools.ietf.org/html/rfc8725)
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [MongoDB Security Checklist](https://docs.mongodb.com/manual/administration/security-checklist/)
+
+## Conclusion
+
+Security is a shared responsibility. This plugin implements industry best practices for GitHub App integration, but you must also:
+
+- Follow the guidelines in this document
+- Keep dependencies up to date
+- Monitor your application
+- Rotate secrets regularly
+- Respond quickly to incidents
+
+If you have questions about security, please reach out through the appropriate channels.

package/dist/GitHubAppInternalContext.d.ts

@@ -0,0 +1,44 @@
+import { FlinkContext } from "@flink-app/flink";
+import { GitHubAuthService } from "./services/GitHubAuthService";
+import { WebhookValidator } from "./services/WebhookValidator";
+import GitHubAppSessionRepo from "./repos/GitHubAppSessionRepo";
+import GitHubInstallationRepo from "./repos/GitHubInstallationRepo";
+import GitHubWebhookEventRepo from "./repos/GitHubWebhookEventRepo";
+import { GitHubAppPluginOptions } from "./GitHubAppPluginOptions";
+/**
+ * Internal context interface with private methods and services
+ *
+ * This interface extends the base FlinkContext with GitHub App Plugin-specific
+ * repositories, services, and configuration. It's used internally by handlers,
+ * services, and the plugin itself.
+ */
+export interface GitHubAppInternalContext extends FlinkContext {
+    /**
+     * GitHub App Session Repository
+     * Manages temporary installation sessions for CSRF protection
+     */
+    repos: FlinkContext['repos'] & {
+        githubAppSessionRepo: GitHubAppSessionRepo;
+        githubInstallationRepo: GitHubInstallationRepo;
+        githubWebhookEventRepo?: GitHubWebhookEventRepo;
+    };
+    /**
+     * Internal plugin state and services
+     */
+    _githubAppInternal: {
+        /**
+         * GitHub Authentication Service
+         * Handles JWT generation and installation token management
+         */
+        authService: GitHubAuthService;
+        /**
+         * Webhook Validator
+         * Validates webhook signatures and parses payloads
+         */
+        webhookValidator: WebhookValidator;
+        /**
+         * Plugin configuration options
+         */
+        options: GitHubAppPluginOptions;
+    };
+}

package/dist/GitHubAppInternalContext.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/GitHubAppPlugin.d.ts

@@ -0,0 +1,45 @@
+import { FlinkPlugin } from "@flink-app/flink";
+import { GitHubAppPluginOptions } from "./GitHubAppPluginOptions";
+/**
+ * GitHub App Plugin Factory Function
+ *
+ * Creates a Flink plugin for GitHub App integration with:
+ * - Installation management
+ * - JWT-based authentication with private key signing
+ * - Installation access token management with automatic refresh and caching
+ * - Webhook integration with signature validation
+ * - GitHub API client wrapper
+ *
+ * @param options - GitHub App plugin configuration options
+ * @returns FlinkPlugin instance
+ *
+ * @example
+ * ```typescript
+ * import { githubAppPlugin } from '@flink-app/github-app-plugin';
+ *
+ * const app = new FlinkApp({
+ *   plugins: [
+ *     githubAppPlugin({
+ *       appId: process.env.GITHUB_APP_ID!,
+ *       privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
+ *       webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+ *       clientId: process.env.GITHUB_APP_CLIENT_ID!,
+ *       clientSecret: process.env.GITHUB_APP_CLIENT_SECRET!,
+ *       onInstallationSuccess: async ({ installationId, repositories, account }, ctx) => {
+ *         const userId = getLoggedInUserId(req); // App-defined function
+ *         return {
+ *           userId,
+ *           redirectUrl: '/dashboard/repos'
+ *         };
+ *       },
+ *       onWebhookEvent: async ({ event, payload, installationId }, ctx) => {
+ *         if (event === 'push') {
+ *           // Process push event
+ *         }
+ *       }
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+export declare function githubAppPlugin(options: GitHubAppPluginOptions): FlinkPlugin;