GitHub App and OAuth Integration Server

This Express server provides APIs for integrating with GitHub Apps and OAuth Apps, including functionality to calculate git diffs between branches.

Setup

1. Copy .env.example to .env and fill in your configuration:

   cp .env.example .env

2. Install dependencies:

   npm install

3. Place your GitHub App private key in the root directory as private.pem

4. Start the server:

   npm start

GitHub App Authentication

Unlike traditional webhook-based installations, this server provides manual authentication endpoints:

1. Initiate GitHub App Authentication

GET /app/auth

This returns an installation URL that users can visit to install your GitHub App:

{
  "message": "Visit the installation URL to authenticate and install the GitHub App",
  "installation_url": "https://github.com/apps/your-app-name/installations/new?state=abc123",
  "state": "abc123",
  "instructions": "After installation, you will be redirected to the callback URL"
}

2. Handle Installation Callback

GET /app/callback?installation_id=123&setup_action=install&state=abc123

This endpoint is called automatically after the user installs your app. It:

• Fetches installation details
• Retrieves accessible repositories
• Stores the data in your JSON database

3. Refresh Installation Data

POST /app/refresh

Manually refresh all installations and repositories for your GitHub App.

OAuth Authentication

1. Initiate OAuth Flow

GET /auth/github

Redirects users to GitHub for OAuth authorization.

2. Handle OAuth Callback

GET /auth/github/callback?code=abc123&state=xyz789

Exchanges the authorization code for an access token and stores user data.

3. Get User Information

GET /auth/user/:userId

Retrieve stored user information (without the access token).

Diff Calculation

Using GitHub App

POST /diff/app
Content-Type: application/json

{
  "repo_owner": "username",
  "repo_name": "repository",
  "base_branch": "main",
  "head_branch": "feature-branch",
  "installation_id": "123456"
}

Using OAuth

POST /diff/oauth
Content-Type: application/json

{
  "repo_owner": "username",
  "repo_name": "repository", 
  "base_branch": "main",
  "head_branch": "feature-branch",
  "user_id": "12345"
}

Both endpoints return detailed diff information including:

• File changes
• Commit details
• Statistics (additions, deletions, modifications)
• Patch data

Data Storage

The server uses a JSON file (db.json) to store:

• GitHub App installations and repositories
• OAuth user tokens and information
• All data is persisted between server restarts

Configuration

Required environment variables:

• GITHUB_APP_ID: Your GitHub App ID
• GITHUB_APP_SLUG: Your GitHub App name/slug (for installation URLs)
• GITHUB_PRIVATE_KEY_PATH: Path to your private key file
• GITHUB_CLIENT_ID: OAuth App client ID
• GITHUB_CLIENT_SECRET: OAuth App client secret
• CALLBACK_URL: OAuth callback URL
• APP_CALLBACK_URL: GitHub App installation callback URL
• GITHUB_OAUTH_SCOPES: (optional) OAuth scopes to request. Defaults to repo,user:email.
  • To request read-only repository content, consider repo:status repo:invite read:repo or repo depending on needs.
  • Example for read-only content: read:repo or repo (repo includes write access; use with caution).

Optional:

• GITHUB_WEBHOOK_SECRET: For webhook verification (if using webhooks)
• PORT: Server port (default: 3000)

API Endpoints

Method	Endpoint	Description
GET	/	API documentation
GET	/health	Health check
GET	/app/auth	GitHub App authentication
GET	/app/callback	GitHub App installation callback
POST	/app/refresh	Refresh GitHub App data
GET	/app/installations	List installations
GET	/app/repositories	List repositories
GET	/auth/github	OAuth authorization
GET	/auth/github/callback	OAuth callback
GET	/auth/user/:userId	Get user info
POST	/diff/app	Calculate diff (GitHub App)
POST	/diff/oauth	Calculate diff (OAuth)
POST	/webhook	Webhook endpoint (optional)

Authentication Flow Examples

GitHub App Flow

1. Call GET /app/auth to get installation URL
2. User visits the installation URL and installs the app
3. GitHub redirects to /app/callback with installation details
4. Server stores installation and repository data
5. Use installation_id for API calls that require GitHub App authentication

OAuth Flow

1. Call GET /auth/github (user is redirected to GitHub)
2. User authorizes the application
3. GitHub redirects to /auth/github/callback
4. Server exchanges code for access token and stores user data
5. Use user_id for API calls that require OAuth authentication

Error Handling

The server includes comprehensive error handling for:

• Missing configuration
• Invalid authentication
• API rate limits
• Network errors
• Invalid parameters

All errors return JSON responses with appropriate HTTP status codes.