@flink-app/github-app-plugin 2.0.0-alpha.59 → 2.0.0-alpha.60

package/README.md

@@ -1,610 +1,251 @@
-# GitHub App Plugin
+# @flink-app/github-app-plugin
 
-A standalone Flink plugin for GitHub App integration with installation management, JWT-based authentication, webhook handling with signature validation, and GitHub API client wrapper.
+GitHub App integration plugin for Flink. Handles installation management, JWT-based authentication, webhook signature validation, and provides an authenticated GitHub API client. Webhook events can be processed via auto-discovered handler files in `src/github-events/` or a single `onWebhookEvent` callback.
 
-## Features
+## Setup
 
--   GitHub App installation flow with CSRF protection
--   Automatic JWT signing with RSA private key (RS256 algorithm)
--   Installation access token management with automatic caching and refresh
--   Webhook integration with HMAC-SHA256 signature validation
--   GitHub API client wrapper with automatic token injection
--   Repository access verification
--   Standalone plugin (works with any authentication system)
--   TypeScript support with full type safety
--   Auto-detection of PKCS#1 and PKCS#8 private key formats
--   Configurable MongoDB collections and TTL settings
-
-## Installation
+### 1. Install
 
 ```bash
-npm install @flink-app/github-app-plugin
+pnpm add @flink-app/github-app-plugin
 ```
 
-## Prerequisites
-
-### 1. GitHub App Setup
-
-You need to create a GitHub App to use this plugin:
-
-1. Go to [GitHub Settings > Developer settings > GitHub Apps](https://github.com/settings/apps)
-2. Click "New GitHub App"
-3. Fill in the required fields:
-    - **App Name:** Your app name (e.g., "My Flink App")
-    - **Homepage URL:** Your application URL
-    - **Webhook URL:** `https://yourdomain.com/github-app/webhook`
-    - **Webhook Secret:** Generate a secure random string (save this!)
-4. Set **Repository permissions** based on your needs:
-    - Contents: Read or Write
-    - Issues: Read or Write
-    - Pull requests: Read or Write
-    - etc.
-5. Subscribe to **Webhook events**:
-    - Push
-    - Pull request
-    - Issues
-    - Installation
-    - etc.
-6. Click "Create GitHub App"
-7. After creation:
-    - Note the **App ID**
-    - Note the **Client ID**
-    - Generate and download the **private key** (PEM file)
-    - Generate and save the **Client Secret**
-    - Note the **App Slug** (optional, used in installation URL)
-
-### 2. Configure Private Key
-
-The plugin requires your GitHub App's private key in **Base64 encoded** format to avoid issues with line breaks in environment variables.
-
-**Encode your private key to base64:**
-
-```bash
-# On macOS/Linux:
-base64 -i github-app-private-key.pem | tr -d '\n'
-
-# On Windows (PowerShell):
-[Convert]::ToBase64String([IO.File]::ReadAllBytes("github-app-private-key.pem"))
-```
+### 2. Register the compiler plugin (for auto-discovered handlers)
 
-**Store the base64 encoded key in an environment variable:**
+```js
+// flink.config.js
+const { compilerPlugin } = require("@flink-app/github-app-plugin/compiler");
 
-```bash
-# .env
-GITHUB_APP_PRIVATE_KEY_BASE64="LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcEFJQkFBS0NBUUVB..."
+module.exports = {
+    compilerPlugins: [compilerPlugin()],
+};
 ```
 
-**Important:** Never commit your private key to version control!
+This tells the Flink compiler to scan `src/github-events/` and auto-register every file that contains `GitHubEventHandler`.
 
-### 3. MongoDB Connection
+### 3. Extend your app context type
 
-The plugin requires MongoDB to store installation data and sessions.
+```typescript
+// src/Ctx.ts
+import { FlinkContext } from "@flink-app/flink";
+import { GitHubAppPluginContext } from "@flink-app/github-app-plugin";
 
-## Quick Start
+export interface Ctx extends FlinkContext<GitHubAppPluginContext> {
+    repos: {
+        // your repos
+    };
+}
+```
 
-### 1. Configure the Plugin
+### 4. Register the runtime plugin
 
 ```typescript
-import { FlinkApp } from "@flink-app/flink";
 import { githubAppPlugin } from "@flink-app/github-app-plugin";
-import { Context } from "./Context";
-
-const app = new FlinkApp<Context>({
-    name: "My App",
-
-    db: {
-        uri: process.env.MONGODB_URI!,
-    },
 
+const app = new FlinkApp<Ctx>({
+    db: { uri: process.env.MONGODB_URI! },
     plugins: [
         githubAppPlugin({
-            // GitHub App credentials (required)
             appId: process.env.GITHUB_APP_ID!,
-            privateKey: process.env.GITHUB_APP_PRIVATE_KEY_BASE64!, // Base64 encoded
+            privateKey: process.env.GITHUB_APP_PRIVATE_KEY_BASE64!,
             webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
             clientId: process.env.GITHUB_APP_CLIENT_ID!,
             clientSecret: process.env.GITHUB_APP_CLIENT_SECRET!,
-            appSlug: "my-flink-app",
-
-            // Optional: Handle webhook events
-            onWebhookEvent: async ({ event, action, payload, installationId }, ctx) => {
-                if (event === "push") {
-                    console.log(`Push to ${payload.repository.full_name}`);
-                }
-            },
+            appSlug: "my-app",
         }),
     ],
 });
-
-await app.start();
 ```
 
-### 2. Implement Installation Callback Handler
-
-The plugin does NOT include an opinionated installation callback handler. You must implement your own handler with your own authentication and authorization logic.
-
-```typescript
-// src/handlers/github/GetGitHubInstallCallback.ts
-import { GetHandler, unauthorized, badRequest, redirect } from "@flink-app/flink";
-import { Context } from "../../Context";
-
-export const Route = {
-    path: "/github/callback",
-};
+## GitHub App Prerequisites
 
-const GetGitHubInstallCallback: GetHandler<{}, {}, {}, { installation_id: string; state: string }> = async ({
-    ctx,
-    req,
-}) => {
-    // 1. Check authentication (your way)
-    if (!ctx.auth?.tokenData?.userId) {
-        return unauthorized("Please log in to connect GitHub");
-    }
-
-    // 2. Parse query params
-    const { installation_id, state } = req.query;
-    if (!installation_id || !state) {
-        return badRequest("Missing required parameters");
-    }
-
-    // 3. Complete installation using plugin
-    const result = await ctx.plugins.githubApp.completeInstallation({
-        installationId: parseInt(installation_id, 10),
-        state,
-        userId: ctx.auth.tokenData.userId,
-    });
-
-    // 4. Handle response (your way)
-    if (!result.success) {
-        console.error("Installation failed:", result.error);
-        return redirect(`/settings/github?error=${result.error.code}`);
-    }
-
-    console.log("GitHub App installed:", result.installation);
-    return redirect("/settings/github?success=true");
-};
+1. Create a GitHub App at [GitHub Settings > Developer settings > GitHub Apps](https://github.com/settings/apps)
+2. Configure:
+   - **Webhook URL:** `https://yourdomain.com/github-app/webhook`
+   - **Webhook Secret:** A secure random string
+   - **Permissions & events:** Select what your app needs
+3. After creation, note: **App ID**, **Client ID**, **Client Secret**, **App Slug**
+4. Generate and download the **private key** (PEM file), then base64 encode it:
 
-export default GetGitHubInstallCallback;
+```bash
+base64 -i private-key.pem | tr -d '\n'
 ```
 
-## Configuration
-
-### GitHubAppPluginOptions
+Store the base64 string as `GITHUB_APP_PRIVATE_KEY_BASE64` in your environment.
 
-| Option                        | Type       | Required | Default                  | Description                                       |
-| ----------------------------- | ---------- | -------- | ------------------------ | ------------------------------------------------- |
-| `appId`                       | `string`   | Yes      | -                        | GitHub App ID                                     |
-| `privateKey`                  | `string`   | Yes      | -                        | Base64 encoded RSA private key (PKCS#1 or PKCS#8) |
-| `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       | Auto-detected            | GitHub App slug (used in installation URL)        |
-| `baseUrl`                     | `string`   | No       | `https://api.github.com` | GitHub API base URL (for GitHub Enterprise)       |
-| `onWebhookEvent`              | `Function` | No       | -                        | Callback for webhook events                       |
-| `sessionsCollectionName`      | `string`   | No       | `github_app_sessions`    | MongoDB collection for sessions                   |
-| `installationsCollectionName` | `string`   | No       | `github_installations`   | MongoDB collection for installations              |
-| `webhookEventsCollectionName` | `string`   | No       | `github_webhook_events`  | MongoDB collection for webhook events             |
-| `tokenCacheTTL`               | `number`   | No       | `3300` (55 minutes)      | Installation token cache TTL in seconds           |
-| `sessionTTL`                  | `number`   | No       | `600` (10 minutes)       | Session TTL in seconds                            |
-| `registerRoutes`              | `boolean`  | No       | `true`                   | Register HTTP handlers automatically              |
-| `logWebhookEvents`            | `boolean`  | No       | `false`                  | Log webhook events to MongoDB                     |
+## Event Handlers
 
-### Callback Functions
-
-#### onWebhookEvent (Optional)
-
-Called when a webhook event is received.
+Create one file per handler in `src/github-events/`. Export a `Route` for matching and a default handler function:
 
 ```typescript
-onWebhookEvent: async (
-    params: {
-        event: string;
-        action?: string;
-        payload: Record<string, any>;
-        installationId: number;
-        deliveryId: string;
-    },
-    ctx: Context
-) => Promise<void>;
-```
+// src/github-events/OnPush.ts
+import { GitHubEventHandler, GitHubEventRouteProps } from "@flink-app/github-app-plugin";
+import { Ctx } from "../Ctx";
 
-**Example:**
+export const Route: GitHubEventRouteProps = { event: "push" };
 
-```typescript
-onWebhookEvent: async ({ event, action, payload, installationId }, ctx) => {
-    switch (event) {
-        case "push":
-            console.log(`Push to ${payload.repository.full_name}`);
-            break;
-
-        case "pull_request":
-            if (action === "opened") {
-                const client = await ctx.plugins.githubApp.getClient(installationId);
-                await client.createIssue(payload.repository.owner.login, payload.repository.name, {
-                    title: "Thanks for the PR!",
-                    body: "We appreciate your contribution.",
-                });
-            }
-            break;
-
-        case "installation":
-            if (action === "deleted") {
-                console.log(`Installation ${installationId} was deleted`);
-            }
-            break;
-    }
+const handler: GitHubEventHandler<Ctx> = async ({ ctx, event, payload, github }) => {
+    const repo = payload.repository.full_name;
+    const commits = payload.commits || [];
+    console.log(`Push to ${repo}: ${commits.length} commits`);
 };
-```
-
-## Installation Flow
-
-### How Users Install Your GitHub App
-
-1. User navigates to: `GET /github-app/install?user_id=USER_ID`
-    - The `user_id` query parameter is optional and determined by your app
-2. User is redirected to GitHub's installation page
-3. User selects repositories to grant access
-4. User clicks "Install" or "Install & Authorize"
-5. GitHub redirects back to: `GET /github-app/callback?installation_id=...&state=...`
-6. Plugin validates the state parameter (CSRF protection)
-7. Plugin fetches installation details from GitHub
-8. Plugin calls your `onInstallationSuccess` callback
-9. Plugin stores installation in MongoDB
-10. User is redirected to your app
-
-### Initiating Installation from Your App
 
-**HTML Button:**
-
-```html
-<a href="/github-app/install?user_id=123">Install GitHub App</a>
+export default handler;
 ```
 
-**React Component:**
+Handlers are evaluated in discovery order. All matching handlers run (not just the first). Each handler receives a pre-authenticated `github` API client scoped to the installation that triggered the event.
 
-```typescript
-function InstallGitHubApp() {
-    const handleInstall = () => {
-        const userId = getCurrentUserId(); // Your function
-        window.location.href = `/github-app/install?user_id=${userId}`;
-    };
+### Routing
 
-    return <button onClick={handleInstall}>Connect GitHub</button>;
-}
-```
-
-## Webhook Setup
-
-### 1. Configure Webhook in GitHub App Settings
+`GitHubEventRouteProps` — all fields are optional. Omit any to match everything (catch-all). All specified criteria must match (AND logic).
 
--   **Webhook URL:** `https://yourdomain.com/github-app/webhook`
--   **Webhook Secret:** Same secret used in plugin configuration
--   **Events:** Select events you want to receive (push, PR, issues, etc.)
-
-### 2. Handle Webhook Events
+| Field            | Type                                              | Matches when                        |
+| ---------------- | ------------------------------------------------- | ----------------------------------- |
+| `event`          | `string \| string[]`                              | GitHub event type (e.g. `"push"`)   |
+| `action`         | `string \| string[]`                              | Event action (e.g. `"opened"`)      |
+| `repository`     | `string \| RegExp \| (payload) => boolean`        | `payload.repository.full_name`      |
+| `installationId` | `number \| number[]`                              | GitHub installation ID              |
 
 ```typescript
-onWebhookEvent: async ({ event, action, payload, installationId, deliveryId }, ctx) => {
-    console.log(`Event: ${event}, Action: ${action}, Delivery: ${deliveryId}`);
-
-    // Access installation
-    const installation = await ctx.repos.githubInstallationRepo.findByInstallationId(installationId);
+// Single event
+export const Route: GitHubEventRouteProps = { event: "push" };
 
-    // Get API client
-    const client = await ctx.plugins.githubApp.getClient(installationId);
+// Multiple events
+export const Route: GitHubEventRouteProps = { event: ["push", "pull_request"] };
 
-    // Process event
-    if (event === "push") {
-        const commits = payload.commits;
-        console.log(`Received ${commits.length} commits`);
-    }
-};
-```
-
-### 3. Webhook Signature Validation
+// Event + action
+export const Route: GitHubEventRouteProps = { event: "pull_request", action: ["opened", "synchronize"] };
 
-The plugin automatically validates webhook signatures using HMAC-SHA256 with constant-time comparison. Invalid signatures are rejected with a 401 status code.
+// Specific repository
+export const Route: GitHubEventRouteProps = { event: "push", repository: "myorg/myrepo" };
 
-## Context API
+// Regex on repository
+export const Route: GitHubEventRouteProps = { repository: /^myorg\// };
 
-The plugin exposes methods via `ctx.plugins.githubApp`:
-
-### getClient(installationId)
-
-Get GitHub API client for an installation.
+// Custom function
+export const Route: GitHubEventRouteProps = {
+    repository: (payload) => payload.repository?.private === true,
+};
 
-```typescript
-const client = await ctx.plugins.githubApp.getClient(12345);
-const repos = await client.getRepositories();
+// Catch-all (no Route export or empty object)
+export const Route: GitHubEventRouteProps = {};
 ```
 
-### getInstallation(userId)
-
-Get installation for a user (returns first installation if multiple exist).
+### Handler arguments
 
 ```typescript
-const installation = await ctx.plugins.githubApp.getInstallation("user-123");
-if (installation) {
-    console.log(`Installed on: ${installation.accountLogin}`);
-}
+const handler: GitHubEventHandler<Ctx> = async ({
+    ctx,            // Flink app context
+    event,          // Event type string (e.g. "push")
+    action,         // Event action string (e.g. "opened"), may be undefined
+    payload,        // Full webhook payload from GitHub
+    installationId, // GitHub installation ID
+    deliveryId,     // Unique delivery ID (X-GitHub-Delivery header)
+    github,         // Pre-authenticated GitHubAPIClient
+}) => {
+    // ...
+};
 ```
 
-### getInstallations(userId)
+## onWebhookEvent callback (alternative)
 
-Get all installations for a user.
+For simpler setups, use the `onWebhookEvent` callback instead of handler files:
 
 ```typescript
-const installations = await ctx.plugins.githubApp.getInstallations("user-123");
-installations.forEach((inst) => {
-    console.log(`${inst.accountLogin} (${inst.accountType})`);
+githubAppPlugin({
+    // ...credentials
+    onWebhookEvent: async ({ event, action, payload, installationId, deliveryId }, ctx) => {
+        if (event === "push") {
+            const client = await ctx.plugins.githubApp.getClient(installationId);
+            // ...
+        }
+    },
 });
 ```
 
-### deleteInstallation(userId, installationId)
+Both approaches can be used simultaneously — the callback runs first, then auto-registered handlers.
 
-Delete an installation from the database.
+## Context API (ctx.plugins.githubApp)
 
-```typescript
-await ctx.plugins.githubApp.deleteInstallation("user-123", 12345);
-```
-
-### hasRepositoryAccess(userId, owner, repo)
+### getClient(installationId)
 
-Check if user has access to a specific repository.
+Get an authenticated GitHub API client for an installation:
 
 ```typescript
-const hasAccess = await ctx.plugins.githubApp.hasRepositoryAccess("user-123", "facebook", "react");
-
-if (!hasAccess) {
-    return forbidden("You do not have access to this repository");
-}
+const client = await ctx.plugins.githubApp.getClient(12345);
+const repos = await client.getRepositories();
+const repo = await client.getRepository("owner", "repo");
+const contents = await client.getContents("owner", "repo", "README.md");
+const issue = await client.createIssue("owner", "repo", { title: "Bug", body: "..." });
+const data = await client.request("GET", "/rate_limit"); // generic API call
 ```
 
-### completeInstallation(params)
-
-Complete GitHub App installation after callback from GitHub.
+### Installation management
 
 ```typescript
+// Initiate installation flow (generates CSRF-protected URL)
+const { redirectUrl } = await ctx.plugins.githubApp.initiateInstallation({
+    userId: "user-123",
+    metadata: { source: "settings" },
+});
+
+// Complete installation after GitHub callback
 const result = await ctx.plugins.githubApp.completeInstallation({
     installationId: 12345,
-    state: "csrf-state-token",
+    state: "csrf-state",
     userId: "user-123",
 });
 
-if (result.success) {
-    console.log("Installation completed:", result.installation);
-} else {
-    console.error("Installation failed:", result.error);
-}
-```
-
-### getInstallationToken(installationId)
+// Query installations
+const installation = await ctx.plugins.githubApp.getInstallation("user-123");
+const installations = await ctx.plugins.githubApp.getInstallations("user-123");
 
-Get raw installation access token (for advanced usage).
+// Uninstall
+await ctx.plugins.githubApp.uninstall({ userId: "user-123", installationId: 12345 });
+await ctx.plugins.githubApp.deleteInstallation("user-123", 12345);
 
-```typescript
-const token = await ctx.plugins.githubApp.getInstallationToken(12345);
-// Make custom API call with token
+// Check repository access
+const hasAccess = await ctx.plugins.githubApp.hasRepositoryAccess("user-123", "owner", "repo");
 ```
 
-### clearTokenCache()
-
-Clear all cached installation tokens.
+### Token management
 
 ```typescript
+const token = await ctx.plugins.githubApp.getInstallationToken(12345);
 ctx.plugins.githubApp.clearTokenCache();
 ```
 
-## GitHub API Client
-
-The plugin provides a GitHub API client with automatic token injection:
-
-```typescript
-const client = await ctx.plugins.githubApp.getClient(installationId);
-
-// Get repositories accessible by this installation
-const repos = await client.getRepositories();
-
-// Get specific repository
-const repo = await client.getRepository("facebook", "react");
-
-// Get file contents
-const contents = await client.getContents("facebook", "react", "README.md");
-
-// Create an issue
-const issue = await client.createIssue("facebook", "react", {
-    title: "Bug Report",
-    body: "Found a bug...",
-});
-
-// Generic API call
-const response = await client.request("GET", "/rate_limit");
-```
-
-## Authentication Integration
-
-This plugin is **auth-agnostic** and works with any authentication system. You implement your own installation callback handler with your own auth logic.
-
-### Example with Session-Based Auth
-
-```typescript
-// In your handler
-const GetGitHubCallback: GetHandler = async ({ ctx, req }) => {
-    // Check session-based auth
-    const userId = ctx.req.session?.userId;
-    if (!userId) {
-        return unauthorized("Please log in");
-    }
-
-    const { installation_id, state } = req.query;
-    const result = await ctx.plugins.githubApp.completeInstallation({
-        installationId: parseInt(installation_id),
-        state,
-        userId,
-    });
-
-    return result.success
-        ? redirect("/dashboard")
-        : redirect(`/error?code=${result.error.code}`);
-};
-```
-
-### Example with JWT Auth Plugin
-
-```typescript
-// In your handler with @flink-app/jwt-auth-plugin
-const GetGitHubCallback: GetHandler = async ({ ctx, req }) => {
-    // Check JWT auth
-    const userId = ctx.auth?.tokenData?.userId;
-    if (!userId) {
-        return unauthorized("Please log in");
-    }
-
-    const { installation_id, state } = req.query;
-    const result = await ctx.plugins.githubApp.completeInstallation({
-        installationId: parseInt(installation_id),
-        state,
-        userId,
-    });
-
-    return result.success
-        ? redirect("/dashboard/github")
-        : redirect(`/error?code=${result.error.code}`);
-};
-```
-
-## Security Considerations
-
-### Private Key Management
-
--   Store base64 encoded private key in environment variables
--   Never commit private key to version control
--   Encode keys using base64 before storing in environment variables
--   Original key must be in PEM format (PKCS#1 or PKCS#8)
--   Rotate keys periodically
-
-### JWT Signing Security
-
--   Uses RS256 algorithm with RSA private key
--   Tokens expire after 10 minutes
--   Automatic key format detection (PKCS#1 and PKCS#8)
-
-### Webhook Signature Validation
-
--   HMAC-SHA256 signature validation
--   Constant-time comparison to prevent timing attacks
--   Rejects webhooks with invalid signatures
-
-### CSRF Protection
-
--   State parameter with cryptographically secure random generation
--   Session stored with TTL (default: 10 minutes)
--   One-time use: session deleted after successful callback
--   Constant-time comparison for state validation
-
-### Token Caching Security
-
--   Tokens cached in memory only (never in database)
--   Automatic expiration after 55 minutes (tokens expire at 60 minutes)
--   Clear cache on demand via `clearTokenCache()`
-
-### HTTPS Requirements
-
-All GitHub API calls and webhook URLs must use HTTPS in production.
-
-## Troubleshooting
-
-### Invalid Private Key Format
-
-**Issue:** `invalid-private-key` error on plugin initialization
-
-**Solution:**
-
--   Ensure private key is base64 encoded before storing in environment variable
--   Verify original PEM key starts with `-----BEGIN RSA PRIVATE KEY-----` (PKCS#1) or `-----BEGIN PRIVATE KEY-----` (PKCS#8)
--   Use the encoding commands: `base64 -i private-key.pem | tr -d '\n'` (macOS/Linux)
--   Ensure entire base64 string is included in environment variable with no line breaks
-
-### Webhook Signature Validation Failed
-
-**Issue:** Webhooks rejected with 401 status
-
-**Solution:**
-
--   Verify webhook secret matches exactly
--   Check webhook secret is set in GitHub App settings
--   Ensure raw request body is used (not parsed JSON)
-
-### Installation State Mismatch
-
-**Issue:** `invalid-state` error during callback
-
-**Solution:**
-
--   Ensure MongoDB is running and accessible
--   Check session TTL hasn't expired (default: 10 minutes)
--   Verify cookies are enabled
--   Check clock synchronization between servers
-
-### Token Cache Not Working
-
-**Issue:** Too many GitHub API calls
-
-**Solution:**
-
--   Verify `tokenCacheTTL` is set appropriately (default: 55 minutes)
--   Check memory usage (tokens cached in-memory)
--   Call `clearTokenCache()` only when necessary
-
-### Installation Not Found
-
-**Issue:** `installation-not-found` error
-
-**Solution:**
-
--   Verify user has installed the GitHub App
--   Check MongoDB for installation record
--   Ensure `userId` matches the one stored during installation
-
-## API Reference
-
-See TypeScript interfaces for complete type definitions:
-
--   `GitHubAppPluginOptions` - Plugin configuration
--   `GitHubAppPluginContext` - Context API methods
--   `GitHubInstallation` - Installation model
--   `WebhookEvent` - Webhook event model
--   `GitHubAPIClient` - API client methods
-
-## Examples
-
-See the `examples/` directory for complete working examples:
-
--   `basic-installation.ts` - Basic GitHub App installation
--   `webhook-handling.ts` - Process webhook events
--   `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
-
-## Production Checklist
-
--   [ ] GitHub App created with proper permissions
--   [ ] Webhook URL configured with HTTPS
--   [ ] Private key stored securely in environment variables
--   [ ] Webhook secret configured and stored securely
--   [ ] MongoDB connection configured and tested
--   [ ] `onInstallationSuccess` callback implemented
--   [ ] Webhook event handling implemented
--   [ ] Error handling configured
--   [ ] HTTPS enabled for all endpoints
--   [ ] Rate limiting configured (app-level)
--   [ ] Monitoring and logging set up
--   [ ] Test installation flow end-to-end
--   [ ] Test webhook delivery and signature validation
-
-## License
-
-MIT
+## Plugin Options
+
+| Option                        | Type       | Default                  | Description                                       |
+| ----------------------------- | ---------- | ------------------------ | ------------------------------------------------- |
+| `appId`                       | `string`   | **required**             | GitHub App ID                                     |
+| `privateKey`                  | `string`   | **required**             | Base64 encoded RSA private key                    |
+| `webhookSecret`               | `string`   | **required**             | Webhook secret for signature validation           |
+| `clientId`                    | `string`   | **required**             | GitHub App client ID                              |
+| `clientSecret`                | `string`   | **required**             | GitHub App client secret                          |
+| `appSlug`                     | `string`   | Auto-detected            | GitHub App slug (used in installation URL)        |
+| `baseUrl`                     | `string`   | `https://api.github.com` | GitHub API base URL (for GitHub Enterprise)       |
+| `onWebhookEvent`              | `Function` | —                        | Callback for webhook events                       |
+| `registerRoutes`              | `boolean`  | `true`                   | Register webhook HTTP handler                     |
+| `logWebhookEvents`            | `boolean`  | `false`                  | Log webhook events to MongoDB                     |
+| `sessionsCollectionName`      | `string`   | `github_app_sessions`    | MongoDB collection for sessions                   |
+| `installationsCollectionName` | `string`   | `github_installations`   | MongoDB collection for installations              |
+| `webhookEventsCollectionName` | `string`   | `github_webhook_events`  | MongoDB collection for webhook events             |
+| `tokenCacheTTL`               | `number`   | `3300` (55 min)          | Installation token cache TTL in seconds           |
+| `sessionTTL`                  | `number`   | `600` (10 min)           | Session TTL in seconds                            |
+
+## Custom scan directory
+
+```js
+// flink.config.js
+compilerPlugins: [compilerPlugin({ scanDir: "src/my-github-events" })];
+```
+
+## Security
+
+- **Private key**: Base64 encoded, stored in env vars, never committed. Supports PKCS#1 and PKCS#8.
+- **JWT signing**: RS256 algorithm, tokens expire after 10 minutes.
+- **Webhook validation**: HMAC-SHA256 with constant-time comparison.
+- **CSRF protection**: Cryptographic state parameter with TTL-based sessions.
+- **Token caching**: In-memory only, auto-expires after 55 minutes.