@flink-app/oauth-plugin 0.12.1-alpha.43 → 0.12.1-alpha.45

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flink-app/oauth-plugin",
-    "version": "0.12.1-alpha.43",
+    "version": "0.12.1-alpha.45",
     "description": "Flink plugin for OAuth 2.0 authentication with GitHub and Google providers",
     "scripts": {
         "test": "node --preserve-symlinks -r ts-node/register -- node_modules/jasmine/bin/jasmine --config=./spec/support/jasmine.json",
@@ -19,9 +19,9 @@
         "mongodb": "^6.15.0"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.40",
-        "@flink-app/jwt-auth-plugin": "^0.12.1-alpha.43",
-        "@flink-app/test-utils": "^0.12.1-alpha.40",
+        "@flink-app/flink": "^0.12.1-alpha.45",
+        "@flink-app/jwt-auth-plugin": "^0.12.1-alpha.45",
+        "@flink-app/test-utils": "^0.12.1-alpha.45",
         "@types/jasmine": "^3.7.1",
         "@types/jwt-simple": "^0.5.36",
         "@types/node": "22.13.10",
@@ -34,5 +34,5 @@
         "tsc-watch": "^4.2.9",
         "typescript": "5.4.5"
     },
-    "gitHead": "e5fc78243a97075ce0272f287f3f89fd44681715"
+    "gitHead": "af426a157217c110ac9c7beb48e2e746968bec33"
 }

package/spec/integration.spec.ts

@@ -8,10 +8,8 @@
  * Once Task Groups 1-6 are implemented, these tests should be completed with actual assertions.
  */
 
-import { createMockJwtAuthPlugin, decodeTestToken } from "./helpers/mockJwtAuthPlugin";
-import { createMockGitHubProfile, createMockGoogleProfile, createMockTokenResponse } from "./helpers/mockOAuthProviders";
-import { beforeEachTest, afterAllTests } from "./helpers/testDatabase";
-import { extractTokenFromUrl } from "./helpers/testHelpers";
+import { createMockJwtAuthPlugin } from "./helpers/mockJwtAuthPlugin";
+import { afterAllTests, beforeEachTest } from "./helpers/testDatabase";
 
 describe("OAuth Plugin Integration Tests", () => {
     let mockJwtAuth: any;

package/GITHUB_APP_PLUGIN_PRD.md

@@ -1,1383 +0,0 @@
-# Product Requirements Document: GitHub App Plugin
-
-**Version:** 1.0
-**Date:** 2025-10-26
-**Status:** Draft
-**Package Name:** `@flink-app/github-app-plugin`
-
----
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Background & Motivation](#background--motivation)
-3. [Goals & Non-Goals](#goals--non-goals)
-4. [Architecture](#architecture)
-5. [GitHub App Authentication Flow](#github-app-authentication-flow)
-6. [Plugin API Specification](#plugin-api-specification)
-7. [Configuration Options](#configuration-options)
-8. [Data Models](#data-models)
-9. [HTTP Handlers](#http-handlers)
-10. [Repositories](#repositories)
-11. [Security Considerations](#security-considerations)
-12. [Context API](#context-api)
-13. [Error Handling](#error-handling)
-14. [Integration with OAuth Plugin](#integration-with-oauth-plugin)
-15. [Examples & Use Cases](#examples--use-cases)
-16. [Development Tasks](#development-tasks)
-17. [Testing Requirements](#testing-requirements)
-18. [Documentation Requirements](#documentation-requirements)
-
----
-
-## Overview
-
-The GitHub App Plugin is a Flink plugin that enables GitHub App integration for fine-grained repository access. Unlike OAuth Apps which require all-or-nothing repo access, GitHub Apps allow users to selectively grant access to specific repositories.
-
-This plugin complements the existing OAuth Plugin by handling repository-level operations while OAuth Plugin continues to handle social login/authentication.
-
-### Key Features
-
-- GitHub App installation flow with repository selection
-- JWT-based authentication with private key signing
-- Installation access token management with automatic refresh
-- Fine-grained repository permissions
-- Webhook integration support
-- Higher API rate limits (15,000 requests/hour)
-- Support for organization and user installations
-- Encrypted private key storage
-- Repository permission verification
-
----
-
-## Background & Motivation
-
-### Problem Statement
-
-The OAuth Plugin uses GitHub OAuth Apps which have limitations:
-- Users must grant access to ALL repositories or none
-- Lower API rate limits (5,000 requests/hour)
-- No webhook integration
-- Cannot act as a bot/service account
-- Broad permission model
-
-### Solution
-
-Implement a separate GitHub App plugin that:
-- Allows users to select specific repositories during installation
-- Provides higher rate limits for API operations
-- Enables webhook integration for real-time events
-- Supports fine-grained permissions per repository
-- Can be installed at organization or user level
-
-### Why Separate Plugin?
-
-GitHub Apps use a **non-OAuth authentication flow** that is incompatible with the OAuth 2.0 standard:
-- JWT signing with RSA private keys (not client secrets)
-- Installation-based token model (not user-based)
-- Different endpoints and flows
-- Installation ID tracking required
-
----
-
-## Goals & Non-Goals
-
-### Goals
-
-✅ Enable fine-grained repository access for Flink applications
-✅ Follow Flink plugin architecture patterns (matching OAuth Plugin)
-✅ Support both user and organization installations
-✅ Provide webhook endpoint handling
-✅ Implement secure private key storage and JWT signing
-✅ Auto-refresh installation access tokens
-✅ Integrate seamlessly with JWT Auth Plugin for user linking
-✅ Provide comprehensive error handling
-✅ Support multiple GitHub App configurations (multi-tenant)
-
-### Non-Goals
-
-❌ Replace OAuth Plugin for social login (OAuth Plugin handles this)
-❌ Support other Git providers (GitHub-specific)
-❌ Implement GitHub Actions or CI/CD features
-❌ Provide repository cloning/Git operations (app-level concern)
-❌ Handle GitHub Packages or GitHub Container Registry
-
----
-
-## Architecture
-
-### Plugin Structure
-
-Following the OAuth Plugin pattern:
-
-```
-packages/github-app-plugin/
-├── src/
-│   ├── GitHubAppPlugin.ts              # Plugin factory function
-│   ├── GitHubAppPluginOptions.ts       # Configuration interface
-│   ├── GitHubAppPluginContext.ts       # Public context interface
-│   ├── GitHubAppInternalContext.ts     # Internal context interface
-│   │
-│   ├── handlers/
-│   │   ├── InitiateInstallation.ts     # GET /github-app/install
-│   │   ├── InstallationCallback.ts     # GET /github-app/callback
-│   │   ├── WebhookHandler.ts           # POST /github-app/webhook
-│   │   └── UninstallHandler.ts         # DELETE /github-app/installation/:id
-│   │
-│   ├── repos/
-│   │   ├── GitHubInstallationRepo.ts   # Installation storage
-│   │   └── GitHubWebhookEventRepo.ts   # Webhook event log (optional)
-│   │
-│   ├── schemas/
-│   │   ├── GitHubInstallation.ts       # Installation model
-│   │   ├── WebhookEvent.ts             # Webhook event model
-│   │   ├── InstallationCallbackRequest.ts
-│   │   └── WebhookPayload.ts
-│   │
-│   ├── services/
-│   │   ├── GitHubAuthService.ts        # JWT signing and token management
-│   │   ├── GitHubAPIClient.ts          # API client wrapper
-│   │   └── WebhookValidator.ts         # Webhook signature validation
-│   │
-│   ├── utils/
-│   │   ├── jwt-utils.ts                # JWT signing with private key
-│   │   ├── token-cache-utils.ts        # Installation token caching
-│   │   ├── encryption-utils.ts         # Private key encryption (reuse from oauth)
-│   │   ├── webhook-signature-utils.ts  # HMAC signature validation
-│   │   └── error-utils.ts              # Error handling
-│   │
-│   └── index.ts                        # Exports
-│
-├── spec/                               # Tests
-├── examples/                           # Usage examples
-├── README.md
-├── SECURITY.md
-├── package.json
-└── tsconfig.json
-```
-
-### Component Responsibilities
-
-| Component | Responsibility |
-|-----------|----------------|
-| **GitHubAppPlugin** | Plugin initialization, handler registration, context setup |
-| **GitHubAuthService** | JWT generation, token exchange, token caching |
-| **GitHubAPIClient** | Wrapper for GitHub API calls with automatic authentication |
-| **WebhookValidator** | Validate webhook signatures and parse payloads |
-| **Repositories** | MongoDB storage for installations and webhook events |
-| **Handlers** | HTTP endpoints for installation flow and webhooks |
-
----
-
-## GitHub App Authentication Flow
-
-### 1. Installation Flow
-
-```
-User clicks "Install GitHub App"
-  ↓
-GET /github-app/install?user_id={userId}
-  ↓
-Redirect to: https://github.com/apps/{app_slug}/installations/new
-  ↓
-User selects repositories to grant access
-  ↓
-GitHub redirects to: /github-app/callback?installation_id=123&setup_action=install&state={state}
-  ↓
-Validate state parameter (CSRF protection)
-  ↓
-Call onInstallationSuccess callback
-  ↓
-Store installation_id linked to user_id
-  ↓
-Redirect to app dashboard
-```
-
-### 2. API Access Flow
-
-```
-App needs to access user's repos
-  ↓
-Get installation_id from database
-  ↓
-Check token cache for valid installation token
-  ↓
-If expired or missing:
-  ├── Generate JWT signed with app private key (RS256)
-  ├── Exchange JWT for installation access token
-  └── Cache token (expires in 1 hour)
-  ↓
-Use installation token to call GitHub API
-  ↓
-Return data to application
-```
-
-### 3. Webhook Flow
-
-```
-GitHub sends webhook event
-  ↓
-POST /github-app/webhook
-  ↓
-Validate X-Hub-Signature-256 header
-  ↓
-Parse webhook payload
-  ↓
-Call onWebhookEvent callback with event data
-  ↓
-Application processes event
-  ↓
-Return 200 OK to GitHub
-```
-
----
-
-## Plugin API Specification
-
-### Factory Function
-
-```typescript
-import { githubAppPlugin } from '@flink-app/github-app-plugin';
-
-const plugin = githubAppPlugin({
-  appId: string;
-  privateKey: string;
-  webhookSecret: string;
-  clientId: string;
-  clientSecret: string;
-  appSlug?: string;
-
-  onInstallationSuccess: (params: InstallationSuccessParams, ctx: Context) => Promise<InstallationSuccessResponse>;
-  onInstallationError?: (params: InstallationErrorParams) => Promise<InstallationErrorResponse>;
-  onWebhookEvent?: (params: WebhookEventParams, ctx: Context) => Promise<void>;
-
-  installationsCollectionName?: string;
-  webhookEventsCollectionName?: string;
-  tokenCacheTTL?: number;
-  registerRoutes?: boolean;
-});
-```
-
-### Callback Interfaces
-
-```typescript
-interface InstallationSuccessParams {
-  installationId: number;
-  repositories: Array<{
-    id: number;
-    name: string;
-    full_name: string;
-    private: boolean;
-  }>;
-  account: {
-    id: number;
-    login: string;
-    type: 'User' | 'Organization';
-    avatar_url: string;
-  };
-  permissions: Record<string, string>;
-  events: string[];
-}
-
-interface InstallationSuccessResponse {
-  userId: string;
-  redirectUrl?: string;
-}
-
-interface WebhookEventParams {
-  event: string;
-  action?: string;
-  installationId: number;
-  payload: any;
-}
-```
-
----
-
-## Configuration Options
-
-### GitHubAppPluginOptions
-
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `appId` | `string` | Yes | - | GitHub App ID |
-| `privateKey` | `string` | Yes | - | RSA private key (PEM format) |
-| `webhookSecret` | `string` | Yes | - | Webhook secret for signature validation |
-| `clientId` | `string` | Yes | - | GitHub App client ID |
-| `clientSecret` | `string` | Yes | - | GitHub App client secret |
-| `appSlug` | `string` | No | - | GitHub App slug (auto-detected if not provided) |
-| `onInstallationSuccess` | `Function` | Yes | - | Callback after successful installation |
-| `onInstallationError` | `Function` | No | - | Callback on installation errors |
-| `onWebhookEvent` | `Function` | No | - | Callback for webhook events |
-| `installationsCollectionName` | `string` | No | `'github_installations'` | MongoDB collection for installations |
-| `webhookEventsCollectionName` | `string` | No | `'github_webhook_events'` | MongoDB collection for webhook logs |
-| `tokenCacheTTL` | `number` | No | `3300` | Token cache TTL in seconds (55 min) |
-| `registerRoutes` | `boolean` | No | `true` | Auto-register HTTP handlers |
-
-### Environment Variables
-
-```bash
-# GitHub App credentials
-GITHUB_APP_ID=123456
-GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
-GITHUB_APP_WEBHOOK_SECRET=your_webhook_secret
-GITHUB_APP_CLIENT_ID=Iv1.abc123
-GITHUB_APP_CLIENT_SECRET=your_client_secret
-
-# Optional
-GITHUB_APP_SLUG=my-app-slug
-```
-
----
-
-## Data Models
-
-### GitHubInstallation
-
-```typescript
-interface GitHubInstallation {
-  _id?: string;
-  userId: string;                    // Link to application user
-  installationId: number;            // GitHub installation ID
-  accountId: number;                 // GitHub account ID
-  accountLogin: string;              // GitHub username or org name
-  accountType: 'User' | 'Organization';
-  avatarUrl: string;
-
-  repositories: Array<{
-    id: number;
-    name: string;
-    fullName: string;
-    private: boolean;
-  }>;
-
-  permissions: Record<string, string>; // e.g., { contents: 'read', issues: 'write' }
-  events: string[];                    // Webhook events subscribed
-
-  suspendedAt?: Date;                  // If installation suspended
-  suspendedBy?: {
-    id: number;
-    login: string;
-  };
-
-  createdAt: Date;
-  updatedAt: Date;
-}
-```
-
-### WebhookEvent (Optional - for logging)
-
-```typescript
-interface WebhookEvent {
-  _id?: string;
-  installationId: number;
-  event: string;                     // e.g., 'push', 'pull_request'
-  action?: string;                   // e.g., 'opened', 'closed'
-  deliveryId: string;                // X-GitHub-Delivery header
-  payload: any;                      // Full webhook payload
-  processed: boolean;
-  processedAt?: Date;
-  error?: string;
-  createdAt: Date;
-}
-```
-
----
-
-## HTTP Handlers
-
-### 1. InitiateInstallation Handler
-
-**Route:** `GET /github-app/install`
-
-**Query Parameters:**
-- `user_id` (required) - Application user ID to link installation
-
-**Flow:**
-1. Generate secure state parameter for CSRF protection
-2. Store state in session/cache with user_id
-3. Build GitHub App installation URL
-4. Redirect user to GitHub
-
-**Implementation:**
-```typescript
-export const Route: RouteProps = {
-  path: '/github-app/install',
-  method: HttpMethod.get,
-};
-
-const InitiateInstallation: GetHandler = async ({ ctx, req }) => {
-  const { user_id } = req.query;
-
-  // Validate user exists
-  // Generate state
-  // Store session
-  // Redirect to GitHub
-
-  return {
-    status: 302,
-    headers: {
-      Location: `https://github.com/apps/${appSlug}/installations/new?state=${state}`
-    },
-    data: {}
-  };
-};
-```
-
-### 2. InstallationCallback Handler
-
-**Route:** `GET /github-app/callback`
-
-**Query Parameters:**
-- `installation_id` - GitHub installation ID
-- `setup_action` - 'install', 'update', or 'request'
-- `state` - CSRF protection token
-- `code` (optional) - Authorization code (if requesting user token)
-
-**Flow:**
-1. Validate state parameter
-2. Exchange code for user access token (if present)
-3. Fetch installation details from GitHub API
-4. Call `onInstallationSuccess` callback
-5. Store installation in database
-6. Redirect to app
-
-**Implementation:**
-```typescript
-export const Route: RouteProps = {
-  path: '/github-app/callback',
-  method: HttpMethod.get,
-};
-
-const InstallationCallback: GetHandler = async ({ ctx, req }) => {
-  const { installation_id, setup_action, state, code } = req.query;
-
-  // Validate state
-  // Fetch installation details
-  // Call onInstallationSuccess
-  // Store installation
-  // Redirect
-};
-```
-
-### 3. WebhookHandler
-
-**Route:** `POST /github-app/webhook`
-
-**Headers:**
-- `X-GitHub-Event` - Event type
-- `X-GitHub-Delivery` - Unique delivery ID
-- `X-Hub-Signature-256` - HMAC signature for validation
-
-**Flow:**
-1. Validate webhook signature
-2. Parse payload
-3. Optionally log webhook event
-4. Call `onWebhookEvent` callback
-5. Return 200 OK
-
-**Implementation:**
-```typescript
-export const Route: RouteProps = {
-  path: '/github-app/webhook',
-  method: HttpMethod.post,
-};
-
-const WebhookHandler: PostHandler = async ({ ctx, req }) => {
-  // Validate signature
-  // Parse payload
-  // Call onWebhookEvent
-  // Return 200
-};
-```
-
-### 4. UninstallHandler (Optional)
-
-**Route:** `DELETE /github-app/installation/:installationId`
-
-**Auth:** Requires JWT authentication
-
-**Flow:**
-1. Verify user owns installation
-2. Delete from database
-3. Optionally revoke on GitHub (requires API call)
-
----
-
-## Repositories
-
-### GitHubInstallationRepo
-
-```typescript
-class GitHubInstallationRepo extends FlinkRepo<any, GitHubInstallation> {
-  /**
-   * Find installation by user ID and installation ID
-   */
-  async findByUserAndInstallationId(
-    userId: string,
-    installationId: number
-  ): Promise<GitHubInstallation | null>;
-
-  /**
-   * Find all installations for a user
-   */
-  async findByUserId(userId: string): Promise<GitHubInstallation[]>;
-
-  /**
-   * Find installation by installation ID only
-   */
-  async findByInstallationId(installationId: number): Promise<GitHubInstallation | null>;
-
-  /**
-   * Update repositories for an installation
-   */
-  async updateRepositories(
-    installationId: number,
-    repositories: Array<{ id: number; name: string; fullName: string; private: boolean }>
-  ): Promise<void>;
-
-  /**
-   * Mark installation as suspended
-   */
-  async suspend(installationId: number, suspendedBy: { id: number; login: string }): Promise<void>;
-
-  /**
-   * Delete installation
-   */
-  async deleteByInstallationId(installationId: number): Promise<number>;
-}
-```
-
-### GitHubWebhookEventRepo (Optional)
-
-```typescript
-class GitHubWebhookEventRepo extends FlinkRepo<any, WebhookEvent> {
-  /**
-   * Find unprocessed webhook events
-   */
-  async findUnprocessed(): Promise<WebhookEvent[]>;
-
-  /**
-   * Mark event as processed
-   */
-  async markProcessed(eventId: string): Promise<void>;
-
-  /**
-   * Find events by installation ID
-   */
-  async findByInstallationId(installationId: number): Promise<WebhookEvent[]>;
-}
-```
-
----
-
-## Security Considerations
-
-### Private Key Management
-
-1. **Storage:**
-   - Store private key in environment variables
-   - Encrypt at rest if storing in database
-   - Use PEM format (PKCS#1 or PKCS#8)
-
-2. **Validation:**
-   - Validate PEM format on plugin initialization
-   - Verify key can sign JWTs successfully
-   - Check key permissions (should be 600 or stricter)
-
-3. **Best Practices:**
-   - Never commit private key to version control
-   - Rotate keys periodically
-   - Use secret management services in production
-
-### JWT Signing
-
-```typescript
-// RS256 algorithm with private key
-const jwt = sign({
-  iat: Math.floor(Date.now() / 1000),
-  exp: Math.floor(Date.now() / 1000) + 600, // 10 minutes
-  iss: appId
-}, privateKey, {
-  algorithm: 'RS256'
-});
-```
-
-### Webhook Signature Validation
-
-```typescript
-function validateWebhookSignature(
-  payload: string,
-  signature: string,
-  secret: string
-): boolean {
-  const hmac = crypto.createHmac('sha256', secret);
-  const digest = 'sha256=' + hmac.update(payload).digest('hex');
-  return crypto.timingSafeEqual(
-    Buffer.from(signature),
-    Buffer.from(digest)
-  );
-}
-```
-
-### CSRF Protection
-
-- Use state parameter in installation flow (similar to OAuth)
-- Store state in MongoDB session with TTL
-- Validate state on callback using constant-time comparison
-
-### Installation Token Security
-
-- Cache installation tokens in memory (not database)
-- Tokens expire after 1 hour
-- Never expose tokens to client
-- Use HTTPS for all API calls
-
----
-
-## Context API
-
-### Plugin Context
-
-The plugin exposes methods via `ctx.plugins.githubApp`:
-
-```typescript
-interface GitHubAppPluginContext {
-  githubApp: {
-    /**
-     * Get GitHub API client for an installation
-     */
-    getClient(installationId: number): Promise<GitHubAPIClient>;
-
-    /**
-     * Get installation for a user
-     */
-    getInstallation(userId: string): Promise<GitHubInstallation | null>;
-
-    /**
-     * Get all installations for a user
-     */
-    getInstallations(userId: string): Promise<GitHubInstallation[]>;
-
-    /**
-     * Delete installation
-     */
-    deleteInstallation(userId: string, installationId: number): Promise<void>;
-
-    /**
-     * Check if user has access to specific repository
-     */
-    hasRepositoryAccess(
-      userId: string,
-      owner: string,
-      repo: string
-    ): Promise<boolean>;
-
-    /**
-     * Get installation access token (for advanced usage)
-     */
-    getInstallationToken(installationId: number): Promise<string>;
-
-    /**
-     * Plugin options (read-only)
-     */
-    options: Readonly<GitHubAppPluginOptions>;
-  };
-}
-```
-
-### GitHubAPIClient
-
-Wrapper for GitHub API calls with automatic authentication:
-
-```typescript
-class GitHubAPIClient {
-  /**
-   * Get repositories accessible by this installation
-   */
-  async getRepositories(): Promise<Repository[]>;
-
-  /**
-   * Get repository details
-   */
-  async getRepository(owner: string, repo: string): Promise<Repository>;
-
-  /**
-   * List repository contents
-   */
-  async getContents(owner: string, repo: string, path: string): Promise<Content[]>;
-
-  /**
-   * Create an issue
-   */
-  async createIssue(
-    owner: string,
-    repo: string,
-    params: { title: string; body: string }
-  ): Promise<Issue>;
-
-  /**
-   * Generic API call
-   */
-  async request(
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
-    endpoint: string,
-    data?: any
-  ): Promise<any>;
-}
-```
-
----
-
-## Error Handling
-
-### Error Codes
-
-```typescript
-export const GitHubAppErrorCodes = {
-  INVALID_STATE: 'invalid_state',
-  INSTALLATION_NOT_FOUND: 'installation_not_found',
-  INVALID_PRIVATE_KEY: 'invalid_private_key',
-  JWT_SIGNING_FAILED: 'jwt_signing_failed',
-  TOKEN_EXCHANGE_FAILED: 'token_exchange_failed',
-  WEBHOOK_SIGNATURE_INVALID: 'webhook_signature_invalid',
-  REPOSITORY_NOT_ACCESSIBLE: 'repository_not_accessible',
-  INSTALLATION_SUSPENDED: 'installation_suspended',
-  API_RATE_LIMIT: 'api_rate_limit',
-  NETWORK_ERROR: 'network_error',
-} as const;
-```
-
-### Error Structure
-
-```typescript
-interface GitHubAppError {
-  code: string;
-  message: string;
-  details?: any;
-}
-```
-
-### Error Handling in Callbacks
-
-```typescript
-onInstallationError: async ({ error, installationId }) => {
-  console.error(`Installation error ${installationId}:`, error);
-
-  return {
-    redirectUrl: `/dashboard?error=${error.code}`
-  };
-}
-```
-
----
-
-## Integration with OAuth Plugin
-
-### Complementary Usage
-
-The GitHub App Plugin works **alongside** the OAuth Plugin:
-
-```typescript
-const app = new FlinkApp<Context>({
-  auth: jwtAuthPlugin({ /* ... */ }),
-
-  plugins: [
-    // OAuth Plugin for social login
-    oauthPlugin({
-      providers: {
-        github: {
-          scope: ['user:email'], // Just authentication
-        }
-      },
-      storeTokens: false,
-      onAuthSuccess: async ({ profile }, ctx) => {
-        // Create user account
-        // Generate JWT token
-      }
-    }),
-
-    // GitHub App Plugin for repo access
-    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 }, ctx) => {
-        // Get current authenticated user
-        const userId = ctx.auth.tokenData.userId;
-
-        return {
-          userId,
-          redirectUrl: '/dashboard/repos'
-        };
-      },
-
-      onWebhookEvent: async ({ event, payload }, ctx) => {
-        // Handle push events, PR events, etc.
-        if (event === 'push') {
-          // Process push webhook
-        }
-      }
-    })
-  ]
-});
-```
-
-### User Flow
-
-1. User signs up/logs in via **OAuth Plugin** (social login)
-2. User navigates to "Connect Repositories" in dashboard
-3. User clicks "Install GitHub App"
-4. **GitHub App Plugin** handles installation and repo selection
-5. Application can now access selected repos via GitHub API
-6. Webhooks keep application in sync with repo events
-
----
-
-## Examples & Use Cases
-
-### Example 1: Basic Installation
-
-```typescript
-import { githubAppPlugin } from '@flink-app/github-app-plugin';
-
-const plugin = 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) => {
-    console.log(`Installed to ${account.login} with ${repositories.length} repos`);
-
-    // Get current user from JWT auth
-    const userId = ctx.auth.tokenData.userId;
-
-    return {
-      userId,
-      redirectUrl: '/dashboard'
-    };
-  }
-});
-```
-
-### Example 2: Accessing Repositories
-
-```typescript
-// In a handler
-const GetUserRepos: GetHandler = async ({ ctx, auth }) => {
-  const userId = auth.tokenData.userId;
-
-  // Get GitHub App client
-  const installation = await ctx.plugins.githubApp.getInstallation(userId);
-
-  if (!installation) {
-    return badRequest('GitHub App not installed');
-  }
-
-  const client = await ctx.plugins.githubApp.getClient(installation.installationId);
-  const repos = await client.getRepositories();
-
-  return { status: 200, data: repos };
-};
-```
-
-### Example 3: Webhook Handling
-
-```typescript
-githubAppPlugin({
-  // ... config
-
-  onWebhookEvent: async ({ event, action, payload, installationId }, ctx) => {
-    switch (event) {
-      case 'push':
-        // Handle push events
-        await ctx.repos.commitRepo.create({
-          installationId,
-          repository: payload.repository.full_name,
-          commits: payload.commits,
-          pusher: payload.pusher
-        });
-        break;
-
-      case 'pull_request':
-        if (action === 'opened') {
-          // Handle new PR
-          await ctx.repos.prRepo.create({
-            installationId,
-            prNumber: payload.pull_request.number,
-            title: payload.pull_request.title
-          });
-        }
-        break;
-
-      case 'installation':
-        if (action === 'deleted') {
-          // Handle uninstallation
-          await ctx.plugins.githubApp.deleteInstallation(installationId);
-        }
-        break;
-    }
-  }
-});
-```
-
-### Example 4: Creating Issues
-
-```typescript
-const CreateIssue: PostHandler = async ({ ctx, auth, req }) => {
-  const { owner, repo, title, body } = req.body;
-  const userId = auth.tokenData.userId;
-
-  // Verify user has access to this repo
-  const hasAccess = await ctx.plugins.githubApp.hasRepositoryAccess(
-    userId,
-    owner,
-    repo
-  );
-
-  if (!hasAccess) {
-    return forbidden('No access to this repository');
-  }
-
-  // Get client and create issue
-  const installation = await ctx.plugins.githubApp.getInstallation(userId);
-  const client = await ctx.plugins.githubApp.getClient(installation!.installationId);
-
-  const issue = await client.createIssue(owner, repo, { title, body });
-
-  return { status: 201, data: issue };
-};
-```
-
----
-
-## Development Tasks
-
-### Phase 1: Core Infrastructure (Week 1-2)
-
-**Task 1.1: Project Setup**
-- [ ] Create package structure in `packages/github-app-plugin/`
-- [ ] Set up TypeScript configuration
-- [ ] Configure build scripts
-- [ ] Set up Jest/Jasmine for testing
-- [ ] Create README.md skeleton
-
-**Task 1.2: Data Models & Schemas**
-- [ ] Implement `GitHubInstallation` interface
-- [ ] Implement `WebhookEvent` interface
-- [ ] Implement `InstallationCallbackRequest` interface
-- [ ] Implement `WebhookPayload` interface
-- [ ] Add schema validation (optional)
-
-**Task 1.3: Utilities**
-- [ ] Implement `jwt-utils.ts` (JWT signing with RS256)
-- [ ] Implement `token-cache-utils.ts` (in-memory token cache)
-- [ ] Implement `webhook-signature-utils.ts` (HMAC validation)
-- [ ] Implement `error-utils.ts` (error codes and handlers)
-- [ ] Add encryption utilities (reuse from oauth-plugin)
-
-### Phase 2: Authentication & Token Management (Week 2-3)
-
-**Task 2.1: GitHub Auth Service**
-- [ ] Implement JWT generation with private key
-- [ ] Implement installation token exchange
-- [ ] Implement token caching with TTL
-- [ ] Implement token refresh logic
-- [ ] Add error handling for auth failures
-
-**Task 2.2: GitHub API Client**
-- [ ] Implement base API client class
-- [ ] Add automatic token injection
-- [ ] Implement common API methods (repos, issues, contents)
-- [ ] Add rate limit handling
-- [ ] Add retry logic with exponential backoff
-
-**Task 2.3: Private Key Validation**
-- [ ] Validate PEM format on initialization
-- [ ] Test JWT signing on startup
-- [ ] Add helpful error messages for invalid keys
-- [ ] Support both PKCS#1 and PKCS#8 formats
-
-### Phase 3: HTTP Handlers (Week 3-4)
-
-**Task 3.1: Installation Initiation Handler**
-- [ ] Implement `InitiateInstallation.ts`
-- [ ] Add state generation (CSRF protection)
-- [ ] Store session in MongoDB
-- [ ] Build GitHub installation URL
-- [ ] Add error handling
-
-**Task 3.2: Installation Callback Handler**
-- [ ] Implement `InstallationCallback.ts`
-- [ ] Validate state parameter
-- [ ] Fetch installation details from GitHub API
-- [ ] Call `onInstallationSuccess` callback
-- [ ] Store installation in database
-- [ ] Handle errors and edge cases
-
-**Task 3.3: Webhook Handler**
-- [ ] Implement `WebhookHandler.ts`
-- [ ] Validate webhook signature
-- [ ] Parse webhook payload
-- [ ] Call `onWebhookEvent` callback
-- [ ] Add webhook event logging (optional)
-- [ ] Return proper status codes
-
-**Task 3.4: Uninstall Handler (Optional)**
-- [ ] Implement `UninstallHandler.ts`
-- [ ] Verify user ownership
-- [ ] Delete from database
-- [ ] Optionally revoke on GitHub
-
-### Phase 4: Repositories (Week 4)
-
-**Task 4.1: GitHubInstallationRepo**
-- [ ] Implement base repository extending FlinkRepo
-- [ ] Add `findByUserAndInstallationId` method
-- [ ] Add `findByUserId` method
-- [ ] Add `findByInstallationId` method
-- [ ] Add `updateRepositories` method
-- [ ] Add `suspend` method
-- [ ] Add `deleteByInstallationId` method
-
-**Task 4.2: GitHubWebhookEventRepo (Optional)**
-- [ ] Implement base repository
-- [ ] Add `findUnprocessed` method
-- [ ] Add `markProcessed` method
-- [ ] Add `findByInstallationId` method
-- [ ] Add TTL index for auto-cleanup
-
-### Phase 5: Plugin Core (Week 5)
-
-**Task 5.1: Plugin Factory**
-- [ ] Implement `githubAppPlugin()` factory function
-- [ ] Add configuration validation
-- [ ] Initialize repositories
-- [ ] Register HTTP handlers
-- [ ] Set up webhook endpoint
-- [ ] Initialize services (auth, API client)
-
-**Task 5.2: Plugin Context**
-- [ ] Implement `GitHubAppPluginContext` interface
-- [ ] Add `getClient()` method
-- [ ] Add `getInstallation()` method
-- [ ] Add `getInstallations()` method
-- [ ] Add `deleteInstallation()` method
-- [ ] Add `hasRepositoryAccess()` method
-- [ ] Add `getInstallationToken()` method
-
-**Task 5.3: Plugin Options**
-- [ ] Implement `GitHubAppPluginOptions` interface
-- [ ] Add validation for required fields
-- [ ] Set default values
-- [ ] Add TypeScript type exports
-
-### Phase 6: Testing (Week 5-6)
-
-**Task 6.1: Unit Tests**
-- [ ] Test JWT signing utilities
-- [ ] Test webhook signature validation
-- [ ] Test token caching logic
-- [ ] Test error handling utilities
-
-**Task 6.2: Integration Tests**
-- [ ] Test installation flow end-to-end
-- [ ] Test webhook processing
-- [ ] Test API client methods
-- [ ] Test repository operations
-- [ ] Mock GitHub API responses
-
-**Task 6.3: Security Tests**
-- [ ] Test CSRF protection
-- [ ] Test webhook signature validation
-- [ ] Test private key validation
-- [ ] Test token expiration handling
-
-### Phase 7: Documentation (Week 6)
-
-**Task 7.1: README.md**
-- [ ] Add installation instructions
-- [ ] Document GitHub App setup process
-- [ ] Add configuration examples
-- [ ] Document all callback functions
-- [ ] Add usage examples
-- [ ] Create troubleshooting section
-
-**Task 7.2: SECURITY.md**
-- [ ] Document private key management
-- [ ] Document webhook security
-- [ ] Document CSRF protection
-- [ ] Add security checklist
-- [ ] Document rate limiting
-
-**Task 7.3: Examples**
-- [ ] Create basic installation example
-- [ ] Create webhook handling example
-- [ ] Create API client usage example
-- [ ] Create multi-tenant example
-
-**Task 7.4: API Documentation**
-- [ ] Document all public interfaces
-- [ ] Add JSDoc comments
-- [ ] Generate TypeDoc documentation (optional)
-
-### Phase 8: Polish & Release (Week 7)
-
-**Task 8.1: Code Review**
-- [ ] Review all code for consistency
-- [ ] Check error handling coverage
-- [ ] Verify security implementations
-- [ ] Check TypeScript types
-
-**Task 8.2: Package Preparation**
-- [ ] Update package.json
-- [ ] Add LICENSE file
-- [ ] Add CHANGELOG.md
-- [ ] Test npm package build
-
-**Task 8.3: Integration Testing**
-- [ ] Test with demo Flink app
-- [ ] Test with OAuth plugin integration
-- [ ] Test webhook delivery
-- [ ] Test rate limiting
-
-**Task 8.4: Release**
-- [ ] Version bump (0.1.0-alpha.1)
-- [ ] Publish to npm
-- [ ] Create GitHub release
-- [ ] Update main Flink documentation
-
----
-
-## Testing Requirements
-
-### Unit Tests
-
-Required test coverage:
-
-1. **JWT Utilities**
-   - Valid JWT generation
-   - Invalid private key handling
-   - Token expiration
-   - Algorithm validation
-
-2. **Webhook Validation**
-   - Valid signature verification
-   - Invalid signature rejection
-   - Constant-time comparison
-   - Missing signature handling
-
-3. **Token Cache**
-   - Cache hit/miss
-   - TTL expiration
-   - Cache invalidation
-
-4. **Error Utilities**
-   - Error code mapping
-   - User-friendly messages
-   - Details sanitization
-
-### Integration Tests
-
-1. **Installation Flow**
-   - Full installation process
-   - State validation
-   - Callback handling
-   - Database storage
-
-2. **Webhook Processing**
-   - Signature validation
-   - Event parsing
-   - Callback execution
-   - Event logging
-
-3. **API Client**
-   - Token injection
-   - API calls
-   - Error handling
-   - Rate limit handling
-
-### Security Tests
-
-1. **CSRF Protection**
-   - State parameter validation
-   - Replay attack prevention
-   - State expiration
-
-2. **Webhook Security**
-   - Signature verification
-   - Timing attack resistance
-   - Payload validation
-
-3. **Token Security**
-   - Expiration handling
-   - Cache security
-   - No token leakage
-
----
-
-## Documentation Requirements
-
-### README.md Sections
-
-1. **Overview** - What the plugin does
-2. **Installation** - npm install instructions
-3. **Prerequisites** - GitHub App setup guide
-4. **Quick Start** - Minimal working example
-5. **Configuration** - All options documented
-6. **GitHub App Setup** - Step-by-step guide
-7. **Installation Flow** - How users install the app
-8. **Webhook Setup** - How to configure webhooks
-9. **Context API** - All available methods
-10. **Examples** - Real-world usage examples
-11. **Security** - Security considerations
-12. **Troubleshooting** - Common issues and solutions
-13. **API Reference** - Full TypeScript API docs
-
-### SECURITY.md Sections
-
-1. **Private Key Management**
-2. **JWT Signing Security**
-3. **Webhook Signature Validation**
-4. **CSRF Protection**
-5. **Token Caching Security**
-6. **HTTPS Requirements**
-7. **Secrets Management**
-8. **Security Checklist**
-9. **Reporting Security Issues**
-
-### Code Examples Required
-
-1. Basic installation flow
-2. Webhook event handling
-3. Repository access
-4. Creating issues
-5. File content access
-6. Multi-tenant setup
-7. Error handling
-8. Integration with OAuth plugin
-
----
-
-## Success Criteria
-
-The GitHub App Plugin will be considered complete when:
-
-✅ Users can install GitHub Apps and select specific repositories
-✅ Application can access selected repositories via GitHub API
-✅ Webhooks are processed with signature validation
-✅ Private keys are securely stored and validated
-✅ Installation tokens are automatically refreshed
-✅ Integration with OAuth Plugin works seamlessly
-✅ Comprehensive error handling is implemented
-✅ All tests pass with >80% coverage
-✅ Documentation is complete and accurate
-✅ Security best practices are followed
-
----
-
-## Future Enhancements (Out of Scope for v1)
-
-- Support for GitHub Enterprise Server
-- Proactive token refresh before expiration
-- Installation token revocation
-- Repository permission auditing
-- Webhook event replay mechanism
-- GitHub Actions integration
-- GraphQL API support
-- Multi-region deployment support
-- Advanced rate limit handling with queuing
-- Webhook event transformation/filtering
-
----
-
-## Questions & Decisions
-
-### Open Questions
-
-1. Should we support GitHub Enterprise Server in v1?
-   - **Decision:** No, add in v2 if needed
-
-2. Should webhook events be logged by default?
-   - **Decision:** Optional, controlled by config flag
-
-3. Should we cache installation details or always fetch fresh?
-   - **Decision:** Cache with configurable TTL
-
-4. How to handle installation updates (repo add/remove)?
-   - **Decision:** Process via webhooks
-
-5. Should we support multiple GitHub Apps per Flink app?
-   - **Decision:** Yes, via multi-tenant pattern
-
-### Resolved Decisions
-
-- ✅ Use RS256 algorithm for JWT signing
-- ✅ Cache installation tokens in memory (not database)
-- ✅ Follow OAuth plugin architecture patterns
-- ✅ Use FlinkRepo for database operations
-- ✅ Integrate with JWT Auth Plugin for user linking
-- ✅ Support both user and organization installations
-- ✅ Provide webhook handler out of the box
-
----
-
-## Appendix
-
-### GitHub App Permissions
-
-Common permission configurations:
-
-**Read-Only Access:**
-```yaml
-contents: read
-metadata: read
-```
-
-**Issue Management:**
-```yaml
-contents: read
-issues: write
-metadata: read
-```
-
-**Full Repository Access:**
-```yaml
-contents: write
-issues: write
-pull_requests: write
-metadata: read
-```
-
-### GitHub App Events
-
-Common webhook events:
-
-- `push` - Code pushed to repository
-- `pull_request` - PR opened/closed/merged
-- `issues` - Issue opened/closed/commented
-- `installation` - App installed/uninstalled
-- `installation_repositories` - Repos added/removed
-- `member` - Collaborator added/removed
-- `release` - Release published
-
-### Useful GitHub API Endpoints
-
-```
-GET /app/installations - List installations
-GET /installation/repositories - List accessible repos
-GET /repos/{owner}/{repo} - Get repository details
-GET /repos/{owner}/{repo}/contents/{path} - Get file contents
-POST /repos/{owner}/{repo}/issues - Create issue
-GET /repos/{owner}/{repo}/issues - List issues
-POST /repos/{owner}/{repo}/pulls - Create pull request
-```
-
----
-
-**End of PRD**