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

package/CHANGELOG.md

@@ -0,0 +1,209 @@
+# Changelog
+
+All notable changes to the GitHub App Plugin will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0-alpha.1] - 2025-10-26
+
+### Added
+
+#### Core Features
+- GitHub App installation flow with CSRF protection using state parameter
+- JWT signing with RSA private key (RS256 algorithm)
+- Automatic detection of PKCS#1 and PKCS#8 private key formats
+- Installation access token management with automatic caching (55-minute TTL)
+- Automatic token refresh when expired
+- Webhook integration with HMAC-SHA256 signature validation
+- Constant-time comparison for security-critical validations
+- GitHub API client wrapper with automatic token injection
+- Repository access verification
+- Standalone plugin architecture (works without JWT Auth Plugin)
+
+#### Database
+- `GitHubAppSessionRepo` for CSRF session storage with TTL index (default: 10 minutes)
+- `GitHubInstallationRepo` for installation-to-user mappings
+- `GitHubWebhookEventRepo` for optional webhook event logging
+- Configurable collection names for all repositories
+- Automatic TTL index creation for session cleanup
+
+#### API Handlers
+- `GET /github-app/install` - Initiate GitHub App installation
+- `GET /github-app/callback` - Handle installation callback
+- `POST /github-app/webhook` - Receive and validate webhook events
+- `DELETE /github-app/installation/:id` - Uninstall GitHub App
+- Optional handler registration via `registerRoutes` config option
+
+#### Context API
+- `getClient(installationId)` - Get GitHub API client for installation
+- `getInstallation(userId)` - Get first installation for user
+- `getInstallations(userId)` - Get all installations for user
+- `deleteInstallation(userId, installationId)` - Delete installation
+- `hasRepositoryAccess(userId, owner, repo)` - Verify repository access
+- `getInstallationToken(installationId)` - Get raw installation token (advanced usage)
+- `clearTokenCache()` - Clear all cached installation tokens
+- `options` - Read-only access to plugin configuration
+
+#### GitHub API Client Methods
+- `getRepositories()` - List accessible repositories
+- `getRepository(owner, repo)` - Get repository details
+- `getContents(owner, repo, path)` - Get file contents
+- `createIssue(owner, repo, params)` - Create GitHub issue
+- `request(method, endpoint, data)` - Generic API request with retry logic
+
+#### Configuration Options
+- Required: `appId`, `privateKey`, `webhookSecret`, `clientId`, `clientSecret`
+- Optional: `appSlug`, `baseUrl` (default: https://api.github.com)
+- Callbacks: `onInstallationSuccess` (required), `onInstallationError`, `onWebhookEvent`
+- Database: `sessionsCollectionName`, `installationsCollectionName`, `webhookEventsCollectionName`
+- Cache: `tokenCacheTTL` (default: 3300 seconds), `sessionTTL` (default: 600 seconds)
+- Features: `registerRoutes` (default: true), `logWebhookEvents` (default: false)
+
+#### Security Features
+- Private key validation on plugin initialization
+- CSRF protection with cryptographically secure state parameter (32 bytes)
+- Webhook signature validation using HMAC-SHA256
+- Constant-time comparison for state and signature validation
+- Installation tokens cached in memory only (never in database)
+- One-time use sessions (deleted after successful callback)
+- Automatic session expiration via MongoDB TTL indexes
+
+#### Error Handling
+- Kebab-case error codes for frontend translation
+- Comprehensive error codes: `invalid-state`, `session-expired`, `installation-not-found`, `invalid-private-key`, `jwt-signing-failed`, `token-exchange-failed`, `webhook-signature-invalid`, `webhook-payload-invalid`, `repository-not-accessible`, `installation-suspended`, `installation-not-owned`, `api-rate-limit`, `network-error`, `server-error`
+- User-friendly error messages with actionable hints
+- Detailed error logging for debugging
+- Graceful handling of GitHub API failures
+- Retry logic with exponential backoff for rate limits
+
+#### Documentation
+- Comprehensive README.md with step-by-step guides
+- SECURITY.md covering all security considerations
+- 8 complete usage examples:
+  - `basic-installation.ts` - Basic GitHub App installation with standalone auth
+  - `webhook-handling.ts` - Process webhook events (push, PR, installation)
+  - `repository-access.ts` - Access repositories via API client
+  - `create-issue.ts` - Create GitHub issue with permission check
+  - `with-jwt-auth.ts` - Optional integration with JWT Auth Plugin
+  - `organization-installation.ts` - Organization-level installation
+  - `error-handling.ts` - Comprehensive error handling
+  - `multi-event-webhook.ts` - Handle multiple webhook event types
+- JSDoc comments on all public interfaces
+- TypeScript type exports for all schemas and interfaces
+
+#### Testing
+- Project initialization tests
+- Schema and repository tests
+- JWT utilities tests (PKCS#1 and PKCS#8 support)
+- Webhook signature validation tests
+- Token cache tests
+- Error utilities tests
+- Authentication service tests
+- API client tests
+- Handler tests (installation flow, callbacks, webhooks)
+- Plugin initialization tests
+- Integration tests for end-to-end flows
+- Security tests for CSRF and signature validation
+
+### Features Highlights
+
+#### Standalone Architecture
+- **No dependencies on JWT Auth Plugin** - Works with any authentication system
+- Plugin agnostic about authentication mechanism
+- Developers can use sessions, custom tokens, or any auth system
+- Optional integration with JWT Auth Plugin available
+
+#### Token Management
+- **Automatic caching** - Reduces GitHub API calls
+- **Smart expiration** - Caches for 55 minutes (tokens expire at 60 minutes)
+- **Automatic refresh** - Seamless token renewal
+- **Memory-only storage** - Enhanced security
+
+#### Webhook Security
+- **Signature validation** - HMAC-SHA256 with constant-time comparison
+- **Automatic validation** - No manual verification needed
+- **Rejection of invalid webhooks** - Returns 401 for invalid signatures
+
+#### Developer Experience
+- **TypeScript-first** - Full type safety
+- **Auto-registration** - Handlers, repos, and jobs automatically registered
+- **Comprehensive examples** - 8 working examples covering all use cases
+- **Clear error messages** - Actionable error codes with hints
+- **Flexible configuration** - Sensible defaults, customizable when needed
+
+### Known Limitations
+
+- Single GitHub App per Flink application (multi-tenant support deferred to future)
+- No proactive token refresh before expiration (refreshes on-demand when expired)
+- GitHub Enterprise Server support via `baseUrl` option but not explicitly tested
+- No GraphQL API support (REST API only)
+- No advanced rate limit handling with queuing (basic retry logic included)
+- No webhook event replay mechanism
+- No repository permission auditing features
+
+### Breaking Changes
+
+None (initial release)
+
+### Migration Guide
+
+Not applicable (initial release)
+
+### Deprecations
+
+None (initial release)
+
+## Roadmap
+
+### Planned for v0.2.0
+- Multi-tenant support (multiple GitHub Apps per Flink application)
+- Proactive token refresh before expiration
+- Enhanced rate limit handling with request queuing
+- Webhook event replay mechanism for failed deliveries
+- GitHub Actions integration
+- GraphQL API support
+
+### Planned for v0.3.0
+- Repository permission auditing
+- Installation analytics and reporting
+- Batch operations for multiple repositories
+- Advanced webhook event filtering
+- Custom event processors registry
+- Webhook event transformation pipeline
+
+### Planned for v1.0.0
+- Production-ready stability
+- Comprehensive GitHub Enterprise Server testing
+- Performance optimizations
+- Advanced caching strategies
+- Complete test coverage (>90%)
+- Security audit and hardening
+
+### Future Considerations
+- GitHub Packages integration
+- Container Registry support
+- Deployment status integration
+- Check runs and check suites support
+- Team management features
+- Marketplace integration
+
+## Support
+
+- **Documentation:** [README.md](./README.md)
+- **Security:** [SECURITY.md](./SECURITY.md)
+- **Examples:** [examples/](./examples/)
+- **Issues:** [GitHub Issues](https://github.com/your-org/flink-framework/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/your-org/flink-framework/discussions)
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
+
+## License
+
+MIT
+
+---
+
+[0.1.0-alpha.1]: https://github.com/your-org/flink-framework/releases/tag/github-app-plugin-v0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Frost Experience AB https://www.frost.se
+
+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.