Trackeep/Others/oauth-service/TRACKEEP_INTEGRATION.md

Trackeep Integration Guide

Architecture Overview

This OAuth service is designed only for authentication. Trackeep instances (user-hosted) handle all GitHub data tracking directly.

How It Works

1. User Authentication Flow

1. User clicks "Login with GitHub" in Trackeep
2. Trackeep redirects to: https://oauth.tdvorak.dev/auth/github?redirect_uri=https://user-trackeep-instance.com
3. OAuth service handles GitHub authentication
4. OAuth service redirects back: https://user-trackeep-instance.com/auth/callback?token=JWT&user=username

2. What Trackeep Receives

The JWT token contains:

{
  "user_id": 123,
  "github_id": 456789,
  "username": "johndoe",
  "email": "john@example.com",
  "access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_type": "bearer",
  "expires_at": 1738123456,
  "exp": 1738123456,
  "iat": 1737518656
}

3. Trackeep GitHub API Access

Trackeep instances can now make GitHub API calls using the user's access_token:

// Example: Get user repositories
const response = await fetch('https://api.github.com/user/repos', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Accept': 'application/vnd.github.v3+json'
  }
});

// Example: Get commits for a repo
const commits = await fetch(`https://api.github.com/repos/${owner}/${repo}/commits`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Accept': 'application/vnd.github.v3+json'
  }
});

Trackeep Implementation Guide

1. OAuth Login Button

<a href="https://oauth.tdvorak.dev/auth/github?redirect_uri=https://your-trackeep-instance.com">
  Login with GitHub
</a>

2. Handle OAuth Callback

// In your /auth/callback route
async function handleOAuthCallback(req, res) {
  const { token, user: username } = req.query;
  
  // Decode and verify JWT
  const jwtPayload = decodeJWT(token);
  
  // Store user session
  req.session.user = {
    id: jwtPayload.user_id,
    username: jwtPayload.username,
    email: jwtPayload.email,
    githubAccessToken: jwtPayload.access_token,
    tokenType: jwtPayload.token_type,
    expiresAt: jwtPayload.expires_at
  };
  
  // Redirect to dashboard
  res.redirect('/dashboard');
}

3. GitHub API Helper

class GitHubAPI {
  constructor(accessToken) {
    this.accessToken = accessToken;
  }
  
  async makeRequest(url) {
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Accept': 'application/vnd.github.v3+json'
      }
    });
    return response.json();
  }
  
  async getUserRepos() {
    return this.makeRequest('https://api.github.com/user/repos');
  }
  
  async getRepoCommits(owner, repo) {
    return this.makeRequest(`https://api.github.com/repos/${owner}/${repo}/commits`);
  }
  
  async getRepoPulls(owner, repo) {
    return this.makeRequest(`https://api.github.com/repos/${owner}/${repo}/pulls`);
  }
  
  async getBranches(owner, repo) {
    return this.makeRequest(`https://api.github.com/repos/${owner}/${repo}/branches`);
  }
}

4. Track Data Collection

// Example: Track repository activity
async function trackRepositoryActivity(user, repoFullName) {
  const [owner, repo] = repoFullName.split('/');
  const github = new GitHubAPI(user.githubAccessToken);
  
  // Get commits
  const commits = await github.getRepoCommits(owner, repo);
  
  // Get pull requests
  const pulls = await github.getRepoPulls(owner, repo);
  
  // Store in your local database
  await storeActivityData({
    userId: user.id,
    repo: repoFullName,
    commits: commits.length,
    pullRequests: pulls.length,
    lastActivity: new Date()
  });
}

Security Considerations

1. Token Storage

• Store GitHub access tokens securely (encrypted at rest)
• Never expose tokens in client-side JavaScript
• Use secure, HTTP-only cookies for session management

2. Token Expiration

• Monitor expires_at field in JWT
• Refresh tokens before expiration if needed
• Handle token expiry gracefully

3. Rate Limiting

• GitHub API has rate limits (5,000 requests/hour for authenticated users)
• Implement caching to reduce API calls
• Handle rate limit responses (HTTP 429)

Available GitHub Scopes

The OAuth service requests these scopes:

• user:email - Read user email addresses
• read:user - Read user profile data
• repo - Access to repositories (full control)

This allows Trackeep instances to:

• Read repository data
• Access commit history
• Monitor pull requests
• Track branch activity

API Endpoints

OAuth Service

• GET /auth/github - Initiate OAuth flow
• GET /auth/github/callback - Handle GitHub callback
• GET /api/v1/user/me - Get current user info

GitHub API (via access token)

• GET /user/repos - User repositories
• GET /repos/{owner}/{repo}/commits - Repository commits
• GET /repos/{owner}/{repo}/pulls - Pull requests
• GET /repos/{owner}/{repo}/branches - Branches
• And all other GitHub API endpoints

Benefits of This Architecture

1. Separation of Concerns - OAuth service only handles authentication
2. User Privacy - GitHub data stays in user's Trackeep instance
3. Scalability - Each user instance handles its own GitHub API calls
4. Security - No centralized GitHub data storage
5. Flexibility - Trackeep can implement custom tracking logic

Example Implementation

See the examples/ directory for complete implementation examples in different frameworks.