\n \n

\n GitHub Authentication\n

\n Secure authentication service for your applications\n

\n\n

\n \n Redirect URI (where to send users after auth)\n \n \n

\n\n \n

\n\n

\n \n

\n\n

This service provides secure GitHub OAuth authentication.

After authentication, you'll be redirected back to your application with a secure token.

\n\n \n

API Usage

Initiate Sign In:

\n \n GET /auth/signin?redirect_uri=YOUR_APP_URL\n \n

Validate Token:

\n \n GET /auth/validate?token=JWT_TOKEN\n \n

Required Environment Variables:

GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET
JWT_SECRET

\n\n \n\n",[18,64],"pulls","branches","forks","envVars",{"_163":165,"_166":26},"connections",{"_163":26,"_164":26},"count","unfilledCount",3,"emptyCount",{"_33":229,"_13":228,"_62":220,"_43":-5,"_35":36,"_147":230,"_152":24,"_37":231,"_39":26,"_65":71,"_145":-5,"_66":30,"_148":-5,"_181":232,"_17":233},{"_33":218,"_13":219,"_62":83,"_43":220,"_35":36,"_147":221,"_152":24,"_37":222,"_39":223,"_65":224,"_145":225,"_66":30,"_148":-5,"_181":226,"_17":227},{"_33":214,"_13":213,"_62":207,"_43":-5,"_35":36,"_147":208,"_152":24,"_37":215,"_39":26,"_65":71,"_145":-5,"_66":30,"_148":-5,"_181":216,"_17":217},{"_33":204,"_13":205,"_62":206,"_43":207,"_35":36,"_147":208,"_152":24,"_37":209,"_39":26,"_65":21,"_145":210,"_66":30,"_148":-5,"_181":211,"_17":212},{"_33":144,"_13":18,"_62":70,"_43":-5,"_35":36,"_147":40,"_152":24,"_37":201,"_39":26,"_65":71,"_145":-5,"_66":30,"_148":-5,"_181":202,"_17":203},{"_33":151,"_13":64,"_62":63,"_43":70,"_35":36,"_147":40,"_152":24,"_37":198,"_39":26,"_65":21,"_145":154,"_66":30,"_148":-5,"_181":199,"_17":200},{"_33":194,"_13":193,"_62":187,"_43":-5,"_35":36,"_147":165,"_152":24,"_37":195,"_39":26,"_65":71,"_145":-5,"_66":30,"_148":-5,"_181":196,"_17":197},{"_33":184,"_13":185,"_62":186,"_43":187,"_35":36,"_147":165,"_152":24,"_37":188,"_39":26,"_65":189,"_145":190,"_66":30,"_148":-5,"_181":191,"_17":192},{"_33":176,"_13":177,"_62":178,"_43":-5,"_35":36,"_147":108,"_152":24,"_37":179,"_39":88,"_65":21,"_145":180,"_66":30,"_148":-5,"_181":182,"_17":183},"bbc17d02-3b3a-11f0-93e0-9e149126039e","README.md","47d0ef0e-3b3a-11f0-9a11-9e149126039e",["D",1748378389257],"# GitHub OAuth Authentication Service\n\nA Val Town service for handling GitHub OAuth authentication with redirect support for external applications.\n\n## Features\n\n- GitHub OAuth sign-in flow\n- JWT token generation for authenticated users\n- Redirect support for external applications\n- Secure token validation\n- User profile retrieval\n- Graceful handling of missing configuration\n\n## Setup\n\n### 1. Create a GitHub OAuth App\n\n1. Go to GitHub Settings > Developer settings > OAuth Apps\n2. Click \"New OAuth App\"\n3. Fill in the details:\n - **Application name**: Your app name\n - **Homepage URL**: Your main application URL\n - **Authorization callback URL**: `https://[your-val-url]/auth/callback`\n4. Click \"Register application\"\n5. Note down your **Client ID** and generate a **Client Secret**\n\n### 2. Configure Environment Variables\n\nIn your Val Town environment, set these variables:\n\n- `GITHUB_CLIENT_ID`: Your GitHub OAuth app client ID\n- `GITHUB_CLIENT_SECRET`: Your GitHub OAuth app client secret \n- `JWT_SECRET`: A secure random string for signing JWT tokens (generate with `openssl rand -base64 32`)\n\n### 3. Test the Service\n\nVisit your Val Town URL to see the auth page and verify configuration.\n\n## Usage\n\n### Sign In Flow\n\n1. Redirect users to: `https://[your-val-url]/auth/signin?redirect_uri=[your-app-url]`\n2. Users will be redirected to GitHub for authentication\n3. After successful auth, users are redirected back to your app with a token: `[your-app-url]?token=[jwt-token]`\n\n### Token Validation\n\nMake a GET request to: `https://[your-val-url]/auth/validate?token=[jwt-token]`\n\nReturns user profile if token is valid:\n\n```json\n{\n \"valid\": true,\n \"user\": {\n \"id\": 12345,\n \"login\": \"username\",\n \"name\": \"User Name\",\n \"email\": \"user@example.com\",\n \"avatar_url\": \"https://avatars.githubusercontent.com/u/12345\",\n \"html_url\": \"https://github.com/username\"\n },\n \"expires_at\": 1640995200\n}\n```\n\n## API Endpoints\n\n- `GET /` - Auth page UI with configuration status\n- `GET /auth/signin?redirect_uri=URL` - Initiate GitHub OAuth flow\n- `GET /auth/callback` - Handle GitHub OAuth callback (internal)\n- `GET /auth/validate?token=JWT` - Validate JWT token and return user info\n- `GET /health` - Health check with configuration status\n\n## Integration Examples\n\nSee `/examples/client-integration.md` for detailed integration examples including:\n\n- JavaScript/TypeScript frontend integration\n- React component example\n- Node.js backend middleware\n- Security best practices\n\n## File Structure\n\n```\n├── backend/\n│ └── index.ts # Main Hono server with OAuth routes\n├── frontend/\n│ └── index.html # Auth page UI\n├── shared/\n│ └── types.ts # Shared TypeScript types\n├── examples/\n│ └── client-integration.md # Integration examples\n└── README.md # This file\n```\n\n## Security Features\n\n- JWT tokens with 7-day expiration\n- State parameter validation to prevent CSRF\n- Secure token signing with configurable secret\n- Input validation and error handling\n- HTTPS-only operation in production\n\n## Error Handling\n\nThe service provides clear error messages for:\n\n- Missing configuration\n- Invalid redirect URIs\n- GitHub OAuth errors\n- Token validation failures\n- Network issues\n\n## Development\n\nThe service gracefully handles missing environment variables during development, showing configuration warnings in the UI and API responses.","children",[],[177],"4df5f6f4-3b3a-11f0-b246-9e149126039e","types.ts","4df5f7b2-3b3a-11f0-b246-9e149126039e","39885a88-d8a3-4095-87bd-5bd287e5cbc3",["D",1748378205053],"script","// Shared types for GitHub OAuth authentication\n\nexport interface GitHubUser {\n id: number;\n login: string;\n name: string | null;\n email: string | null;\n avatar_url: string;\n html_url: string;\n}\n\nexport interface AuthToken {\n user: GitHubUser;\n iat: number;\n exp: number;\n}\n\nexport interface GitHubTokenResponse {\n access_token: string;\n token_type: string;\n scope: string;\n}\n\nexport interface AuthError {\n error: string;\n error_description?: string;\n}",[],[193,185],"shared","4df6514e-3b3a-11f0-b246-9e149126039e",["D",1748378205053],[174],[193],["D",1748378263766],[],[18,64],["D",1748378263766],[172],[18],"ad82cd36-3b3a-11f0-984c-9e149126039e","client-integration.md","ad82cde0-3b3a-11f0-984c-9e149126039e","21acd166-3c82-4271-9bbc-4d64e70bcf83",14,["D",1748378365359],"# Client Integration Examples\n\n## JavaScript/TypeScript Integration\n\n### 1. Redirect to Auth Service\n\n```javascript\n// Redirect user to GitHub auth service\nfunction signInWithGitHub() {\n const authServiceUrl = 'https://your-auth-service.web.val.run';\n const redirectUri = encodeURIComponent(window.location.origin + '/auth-callback');\n \n window.location.href = `${authServiceUrl}/auth/signin?redirect_uri=${redirectUri}`;\n}\n```\n\n### 2. Handle Auth Callback\n\n```javascript\n// Handle the callback with token\nfunction handleAuthCallback() {\n const urlParams = new URLSearchParams(window.location.search);\n const token = urlParams.get('token');\n \n if (token) {\n // Store token securely\n localStorage.setItem('auth_token', token);\n \n // Validate token and get user info\n validateToken(token);\n \n // Clean up URL\n window.history.replaceState({}, document.title, window.location.pathname);\n }\n}\n\n// Call this on page load\nwindow.addEventListener('load', handleAuthCallback);\n```\n\n### 3. Validate Token and Get User Info\n\n```javascript\nasync function validateToken(token) {\n const authServiceUrl = 'https://your-auth-service.web.val.run';\n \n try {\n const response = await fetch(`${authServiceUrl}/auth/validate?token=${token}`);\n const data = await response.json();\n \n if (data.valid) {\n console.log('User:', data.user);\n // Update UI with user info\n updateUserInterface(data.user);\n } else {\n console.error('Invalid token:', data.error);\n // Redirect to sign in\n signInWithGitHub();\n }\n } catch (error) {\n console.error('Token validation failed:', error);\n }\n}\n```\n\n### 4. Complete React Example\n\n```jsx\nimport React, { useState, useEffect } from 'react';\n\nconst AUTH_SERVICE_URL = 'https://your-auth-service.web.val.run';\n\nfunction App() {\n const [user, setUser] = useState(null);\n const [loading, setLoading] = useState(true);\n\n useEffect(() => {\n // Check for auth callback\n const urlParams = new URLSearchParams(window.location.search);\n const token = urlParams.get('token');\n \n if (token) {\n localStorage.setItem('auth_token', token);\n window.history.replaceState({}, document.title, window.location.pathname);\n validateToken(token);\n } else {\n // Check for existing token\n const existingToken = localStorage.getItem('auth_token');\n if (existingToken) {\n validateToken(existingToken);\n } else {\n setLoading(false);\n }\n }\n }, []);\n\n const validateToken = async (token) => {\n try {\n const response = await fetch(`${AUTH_SERVICE_URL}/auth/validate?token=${token}`);\n const data = await response.json();\n \n if (data.valid) {\n setUser(data.user);\n } else {\n localStorage.removeItem('auth_token');\n }\n } catch (error) {\n console.error('Token validation failed:', error);\n localStorage.removeItem('auth_token');\n } finally {\n setLoading(false);\n }\n };\n\n const signIn = () => {\n const redirectUri = encodeURIComponent(window.location.origin);\n window.location.href = `${AUTH_SERVICE_URL}/auth/signin?redirect_uri=${redirectUri}`;\n };\n\n const signOut = () => {\n localStorage.removeItem('auth_token');\n setUser(null);\n };\n\n if (loading) {\n return

;\n }\n\n return (\n

\n {user ? (\n

Welcome, {user.name || user.login}!

\n $\"Avatar\"$ \n \n

\n ) : (\n

Please sign in

\n \n

\n )}\n

\n );\n}\n\nexport default App;\n```\n\n## Backend Integration (Node.js/Express)\n\n```javascript\nconst express = require('express');\nconst fetch = require('node-fetch');\n\nconst app = express();\nconst AUTH_SERVICE_URL = 'https://your-auth-service.web.val.run';\n\n// Middleware to validate auth token\nasync function validateAuth(req, res, next) {\n const token = req.headers.authorization?.replace('Bearer ', '');\n \n if (!token) {\n return res.status(401).json({ error: 'No token provided' });\n }\n\n try {\n const response = await fetch(`${AUTH_SERVICE_URL}/auth/validate?token=${token}`);\n const data = await response.json();\n \n if (data.valid) {\n req.user = data.user;\n next();\n } else {\n res.status(401).json({ error: 'Invalid token' });\n }\n } catch (error) {\n res.status(500).json({ error: 'Token validation failed' });\n }\n}\n\n// Protected route\napp.get('/api/profile', validateAuth, (req, res) => {\n res.json({ user: req.user });\n});\n\napp.listen(3000);\n```\n\n## Security Best Practices\n\n1. **Token Storage**: Store tokens securely (httpOnly cookies for web apps)\n2. **Token Validation**: Always validate tokens on the server side for protected routes\n3. **HTTPS Only**: Only use this service over HTTPS in production\n4. **Token Expiry**: Tokens expire after 7 days - implement refresh logic\n5. **Environment Variables**: Never expose your GitHub client secret\n\n## Error Handling\n\n```javascript\n// Handle common errors\nasync function handleAuthError(error) {\n if (error.message.includes('Invalid token')) {\n // Token expired or invalid - redirect to sign in\n localStorage.removeItem('auth_token');\n signInWithGitHub();\n } else if (error.message.includes('Network')) {\n // Network error - show retry option\n showRetryDialog();\n } else {\n // Other errors\n console.error('Auth error:', error);\n }\n}\n```",[],[213,205],"examples","ad831688-3b3a-11f0-984c-9e149126039e",["D",1748378365359],[170],[213],"9a11f5d8-3b3a-11f0-84c6-9e149126039e","index.ts","bf332b80-887e-4688-9890-891be88c7019",13,["D",1748378332692],7,"http","import { Hono } from \"https://esm.sh/hono@3.11.7\";\nimport { readFile } from \"https://esm.town/v/std/utils@85-main/index.ts\";\nimport { sign, verify } from \"https://esm.sh/jsonwebtoken@9.0.2\";\nimport type { GitHubUser, GitHubTokenResponse, AuthToken, AuthError } from \"../shared/types.ts\";\n\nconst app = new Hono();\n\n// Unwrap Hono errors to see original error details\napp.onError((err, c) => {\n throw err;\n});\n\n// Environment variables\nconst GITHUB_CLIENT_ID = Deno.env.get('GITHUB_CLIENT_ID');\nconst GITHUB_CLIENT_SECRET = Deno.env.get('GITHUB_CLIENT_SECRET');\nconst JWT_SECRET = Deno.env.get('JWT_SECRET');\n\n// Check if environment variables are configured\nconst isConfigured = GITHUB_CLIENT_ID && GITHUB_CLIENT_SECRET && JWT_SECRET;\n\n// Serve the auth page\napp.get(\"/\", async (c) => {\n const html = await readFile(\"/frontend/index.html\", import.meta.url);\n \n if (!isConfigured) {\n // Inject configuration warning\n const warningScript = ``;\n \n return c.html(html.replace(\"\", `${warningScript}`));\n }\n \n return c.html(html);\n});\n\n// Initiate GitHub OAuth flow\napp.get(\"/auth/signin\", (c) => {\n if (!isConfigured) {\n return c.json({ error: 'Service not configured. Please set environment variables.' }, 500);\n }\n\n const redirectUri = c.req.query('redirect_uri');\n \n if (!redirectUri) {\n return c.json({ error: 'redirect_uri parameter is required' }, 400);\n }\n\n // Store redirect URI in state parameter (base64 encoded for URL safety)\n const state = btoa(redirectUri);\n \n const githubAuthUrl = new URL('https://github.com/login/oauth/authorize');\n githubAuthUrl.searchParams.set('client_id', GITHUB_CLIENT_ID!);\n githubAuthUrl.searchParams.set('redirect_uri', `${c.req.url.split('/auth/signin')[0]}/auth/callback`);\n githubAuthUrl.searchParams.set('scope', 'user:email');\n githubAuthUrl.searchParams.set('state', state);\n\n return new Response(null, {\n status: 302,\n headers: { Location: githubAuthUrl.toString() }\n });\n});\n\n// Handle GitHub OAuth callback\napp.get(\"/auth/callback\", async (c) => {\n if (!isConfigured) {\n return c.json({ error: 'Service not configured. Please set environment variables.' }, 500);\n }\n\n const code = c.req.query('code');\n const state = c.req.query('state');\n const error = c.req.query('error');\n\n if (error) {\n const errorDescription = c.req.query('error_description') || 'GitHub OAuth error';\n return c.json({ error, error_description: errorDescription }, 400);\n }\n\n if (!code || !state) {\n return c.json({ error: 'Missing code or state parameter' }, 400);\n }\n\n try {\n // Decode redirect URI from state\n const redirectUri = atob(state);\n\n // Exchange code for access token\n const tokenResponse = await fetch('https://github.com/login/oauth/access_token', {\n method: 'POST',\n headers: {\n 'Accept': 'application/json',\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n client_id: GITHUB_CLIENT_ID!,\n client_secret: GITHUB_CLIENT_SECRET!,\n code,\n }),\n });\n\n const tokenData: GitHubTokenResponse = await tokenResponse.json();\n\n if (!tokenData.access_token) {\n return c.json({ error: 'Failed to obtain access token' }, 400);\n }\n\n // Get user information from GitHub\n const userResponse = await fetch('https://api.github.com/user', {\n headers: {\n 'Authorization': `Bearer ${tokenData.access_token}`,\n 'Accept': 'application/vnd.github.v3+json',\n },\n });\n\n const userData: GitHubUser = await userResponse.json();\n\n // Create JWT token\n const jwtPayload: Omit = {\n user: userData,\n };\n\n const token = sign(jwtPayload, JWT_SECRET!, { expiresIn: '7d' });\n\n // Redirect back to the original app with the token\n const finalRedirectUrl = new URL(redirectUri);\n finalRedirectUrl.searchParams.set('token', token);\n\n return new Response(null, {\n status: 302,\n headers: { Location: finalRedirectUrl.toString() }\n });\n\n } catch (error) {\n console.error('OAuth callback error:', error);\n return c.json({ error: 'Authentication failed' }, 500);\n }\n});\n\n// Validate JWT token and return user info\napp.get(\"/auth/validate\", (c) => {\n if (!isConfigured) {\n return c.json({ error: 'Service not configured. Please set environment variables.' }, 500);\n }\n\n const token = c.req.query('token');\n\n if (!token) {\n return c.json({ error: 'Token parameter is required' }, 400);\n }\n\n try {\n const decoded = verify(token, JWT_SECRET!) as AuthToken;\n return c.json({\n valid: true,\n user: decoded.user,\n expires_at: decoded.exp,\n });\n } catch (error) {\n return c.json({ \n valid: false, \n error: 'Invalid or expired token' \n }, 401);\n }\n});\n\n// Health check endpoint\napp.get(\"/health\", (c) => {\n return c.json({ \n status: 'ok', \n timestamp: new Date().toISOString(),\n configured: isConfigured,\n missing_vars: isConfigured ? [] : [\n !GITHUB_CLIENT_ID && 'GITHUB_CLIENT_ID',\n !GITHUB_CLIENT_SECRET && 'GITHUB_CLIENT_SECRET', \n !JWT_SECRET && 'JWT_SECRET'\n ].filter(Boolean)\n });\n});\n\n// Export the Hono app\nexport default app.fetch;",[],[228,219],"backend","5a6ed45a-3b3a-11f0-bec7-9e149126039e",4,["D",1748378225973],[168],[228],["D",1748377929808],{"_11":12,"_121":69},{"_11":12,"_117":-5,"_68":69,"_31":67,"_118":119,"_120":30},{"_39":108,"_13":16,"_33":36,"_109":73,"_110":-5,"_111":-5,"_112":-5,"_113":-5,"_114":-5,"_115":14,"_116":12},"ctx",{"_52":-5,"_140":271,"_272":273,"_274":275,"_276":30,"_277":30,"_278":30,"_279":24,"_280":-5,"_281":-7,"_282":-7,"_283":26,"_284":30,"_285":30,"_286":-5,"_287":30,"_288":30,"_289":30,"_290":-5},"ENV",{"_242":243,"_244":245,"_246":16,"_247":248,"_249":250,"_251":252,"_253":254,"_255":256,"_257":258,"_259":260,"_261":262,"_263":264,"_265":266,"_267":268,"_269":270},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

History · frontend