GitHub OAuth Authentication Service

A Val Town service for handling GitHub OAuth authentication with redirect support for external applications.

• GitHub OAuth sign-in flow
• JWT token generation for authenticated users
• Redirect support for external applications
• Secure token validation
• User profile retrieval
• Graceful handling of missing configuration

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Click "New OAuth App"
3. Fill in the details:
   • Application name: Your app name
   • Homepage URL: Your main application URL
   • Authorization callback URL: https://[your-val-url]/auth/callback
4. Click "Register application"
5. Note down your Client ID and generate a Client Secret

In your Val Town environment, set these variables:

• GITHUB_CLIENT_ID: Your GitHub OAuth app client ID
• GITHUB_CLIENT_SECRET: Your GitHub OAuth app client secret
• JWT_SECRET: A secure random string for signing JWT tokens (generate with openssl rand -base64 32)

Visit your Val Town URL to see the auth page and verify configuration.

1. Redirect users to: https://[your-val-url]/auth/signin?redirect_uri=[your-app-url]
2. Users will be redirected to GitHub for authentication
3. After successful auth, users are redirected back to your app with a token: [your-app-url]?token=[jwt-token]

Make a GET request to: https://[your-val-url]/auth/validate?token=[jwt-token]

Returns user profile if token is valid:

{
  "valid": true,
  "user": {
    "id": 12345,
    "login": "username",
    "name": "User Name",
    "email": "user@example.com",
    "avatar_url": "https://avatars.githubusercontent.com/u/12345",
    "html_url": "https://github.com/username"
  },
  "expires_at": 1640995200
}

• GET / - Auth page UI with configuration status
• GET /auth/signin?redirect_uri=URL - Initiate GitHub OAuth flow
• GET /auth/callback - Handle GitHub OAuth callback (internal)
• GET /auth/validate?token=JWT - Validate JWT token and return user info
• GET /health - Health check with configuration status

See /examples/client-integration.md for detailed integration examples including:

• JavaScript/TypeScript frontend integration
• React component example
• Node.js backend middleware
• Security best practices

├── backend/
│   └── index.ts             # Main Hono server with OAuth routes
├── frontend/
│   └── index.html           # Auth page UI
├── shared/
│   └── types.ts             # Shared TypeScript types
├── examples/
│   └── client-integration.md # Integration examples
└── README.md                # This file

• JWT tokens with 7-day expiration
• State parameter validation to prevent CSRF
• Secure token signing with configurable secret
• Input validation and error handling
• HTTPS-only operation in production

The service provides clear error messages for:

• Missing configuration
• Invalid redirect URIs
• GitHub OAuth errors
• Token validation failures
• Network issues

The service gracefully handles missing environment variables during development, showing configuration warnings in the UI and API responses.