OAuth Library - Design Document

English | 中文

⚠️ WARNING: This library may violate GitHub Copilot's Terms of Service. Using this library to access GitHub Copilot without proper authorization may result in account suspension or termination. This project is for educational and research purposes only. Use at your own risk and ensure you have appropriate authorization before using this library.

1. Project Overview

This is a multi-language OAuth authentication library specifically designed to provide Device Flow authentication for GitHub Copilot and Hyper services. The project implements the standard OAuth2.0 Device Authorization Grant (RFC 8628) and provides specialized integration modules for two different services.

Supported Languages:

Go - Original implementation, located in go/ directory
Python - Located in python/ directory
TypeScript - Located in ts/ directory

1.1 Core Values

Unified Token Management: Provides unified token data structure and lifecycle management
Multi-Service Support: Supports both GitHub Copilot and Hyper authentication scenarios
Automatic Refresh: Built-in token expiration detection and automatic refresh logic
Device Flow Authentication: Enables user authorization without a browser (suitable for CLI tools)
Multi-Language Support: Complete implementations in Go, Python, and TypeScript

1.2 Project Structure

oauth/
├── docs/
│   ├── design_EN.md       # English design document
│   └── design_CN.md       # Chinese design document
├── go/                     # Go implementation
│   ├── go.mod
│   ├── README_EN.md
│   ├── README_CN.md
│   ├── token.go
│   ├── copilot/
│   │   ├── oauth.go       # Device flow
│   │   ├── client.go      # Custom HTTP client
│   │   ├── disk.go        # Disk cache
│   │   ├── http.go        # HTTP headers
│   │   └── urls.go        # URL constants
│   └── hyper/
│       └── device.go      # Hyper device flow
├── python/                 # Python implementation
│   ├── setup.py
│   ├── requirements.txt
│   ├── README_EN.md
│   ├── README_CN.md
│   └── oauth/
│       ├── token.py
│       ├── copilot/
│       └── hyper/
└── ts/                     # TypeScript implementation
    ├── package.json
    ├── tsconfig.json
    ├── README_EN.md
    ├── README_CN.md
    └── src/
        ├── token.ts
        ├── copilot/
        └── hyper/

2. Architecture Design

2.1 Layered Architecture

┌──────────────────────────────────────────┐
│      Application Layer (CLI/Service)     │
├──────────────────────────────────────────┤
│   copilot/        │      hyper/          │  ← Service Adapter Layer
├───────────────────┼──────────────────────┤
│          Token Management (Core)         │  ← Core Layer
├──────────────────────────────────────────┤
│      HTTP Client / Transport Layer       │
└──────────────────────────────────────────┘

2.2 Module Design

Core Module (Token Management)

Language-agnostic token data structure
Lifecycle management (creation, expiration check, refresh)
Serialization/deserialization support

Service Adapter Layer

copilot/: GitHub Copilot-specific implementation
hyper/: Hyper service-specific implementation

Transport Layer

Standard HTTP client with timeout
Custom interceptors (e.g., X-Initiator header injection)
Response size limiting (1MB max)

3. Core Design Principles

3.1 Token Abstraction

Design Philosophy: Separate token management from service-specific logic to enable reusability across different OAuth providers.

Key Features:

Dual Time Representation
- expires_in: Relative time in seconds (for API responses)
- expires_at: Absolute Unix timestamp (for expiration checks)
- Automatic conversion between the two
Smart Expiration Detection
- 10% buffer before actual expiration
- Prevents using tokens near their expiration time
- Provides time for token refresh
Serialization Support
- Go: JSON tags for encoding/json
- Python: to_dict() and from_dict() methods
- TypeScript: toJSON() and fromJSON() methods

3.2 GitHub Copilot Integration

Three-Stage Authentication Flow:

1. Device Code Request
   ↓
   GitHub returns device_code and user_code
   ↓
2. User Authorization
   User visits GitHub and enters user_code
   ↓
3. Token Polling
   App polls GitHub for access token
   ↓
4. Copilot Token Exchange
   Exchange GitHub token for Copilot token

Key Design Decisions:

Disk Cache Reading
- Reads tokens from official GitHub Copilot client cache
- Platform-specific paths:
  - Windows: %LOCALAPPDATA%/github-copilot/apps.json
  - macOS/Linux: ~/.config/github-copilot/apps.json
- Graceful fallback if cache unavailable
X-Initiator Header Injection
- Custom HTTP client/adapter that inspects request body
- Sets X-Initiator: user for user-initiated requests
- Sets X-Initiator: agent for agent/assistant messages
- Uses regex pattern matching to detect assistant messages
Error Handling
- Specific error for "Copilot not available" (HTTP 403)
- Retry logic for authorization_pending
- Backoff for slow_down errors (increments interval by 5s)

3.3 Hyper Service Integration

Device Flow with Callbacks:

1. Initiate Device Auth
   ↓
   Hyper returns device_code, user_code, verification_url
   ↓
2. User Authorization
   User visits verification_url and enters user_code
   ↓
3. Token Polling
   Poll until authorization complete
   ↓
4. Success Callback (optional)
   Trigger callback with user ID
   ↓
5. Token Exchange
   Exchange refresh token for access token

Key Features:

Environment Configuration
- Base URL configurable via HYPER_BASE_URL environment variable
- Default: https://api.hyper.example.com
Token Introspection
- Implements RFC 7662 (OAuth 2.0 Token Introspection)
- Validates token status and retrieves metadata
- Returns user ID, organization ID, expiration time
Success Callbacks
- Optional callback function/lambda on successful authentication
- Receives user ID as parameter
- Useful for analytics and logging

3.4 Security Measures

All implementations include:

Request Timeouts
- 30-second timeout for all HTTP requests
- Prevents hanging connections
Response Size Limits
- Maximum 1MB response body
- Prevents memory exhaustion attacks
- Implemented using streaming readers
Token Refresh Strategy
- Tokens refreshed at 90% of their lifetime
- 10% buffer prevents edge-case failures
- Automatic refresh on isExpired() check
Error Handling
- Specific exception types for different error scenarios
- Proper HTTP status code handling
- Graceful degradation when optional features unavailable

4. Implementation Differences

4.1 Go Implementation

Characteristics:

Uses standard library net/http
Context-based cancellation and timeouts
Interface-based design for extensibility
No external dependencies for core functionality

Code Style:

// Context throughout
func RequestDeviceCode(ctx context.Context) (*DeviceCode, error)

// Explicit error handling
if err != nil {
    return nil, fmt.Errorf("request failed: %w", err)
}

// Defer for cleanup
defer resp.Body.Close()

4.2 Python Implementation

Characteristics:

Uses requests library for HTTP
Dataclasses for structured data
Type hints for better IDE support
Pythonic error handling

Code Style:

# Dataclasses
@dataclass
class Token:
    access_token: str
    refresh_token: str

# Type hints
def request_device_code(timeout: int = 30) -> DeviceCode:

# Context managers
with requests.Session() as session:
    response = session.post(url)

4.3 TypeScript Implementation

Characteristics:

Uses axios for HTTP requests
Full TypeScript type safety
Async/await for all I/O operations
ES6+ features (classes, arrow functions)

Code Style:

// Class-based
class Token {
  constructor(
    public accessToken: string,
    public refreshToken: string,
    public expiresIn: number,
    public expiresAt: number
  ) {}
}

// Async/await
async function requestDeviceCode(timeout: number = 30000): Promise<DeviceCode>

// Promise-based
return axios.post(url, data).then(response => response.data)

5. Testing Considerations

5.1 Unit Testing

Token Management:

Test expiration calculation
Test 10% buffer logic
Test serialization/deserialization

HTTP Mocking:

Mock device code requests
Mock token polling responses
Test retry and backoff logic

5.2 Integration Testing

End-to-End Flows:

Complete device flow authentication
Token refresh scenarios
Error handling paths

Environment Testing:

Test disk cache reading on different platforms
Test environment variable configuration
Test timeout and size limit enforcement

6. Future Enhancements

6.1 Potential Features

Token Storage
- Secure token storage (keychain/keyring integration)
- Encrypted cache files
- Memory-only mode for sensitive environments
Additional OAuth Providers
- Generic OAuth2 device flow client
- Support for other services using device flow
Improved Observability
- Structured logging
- Metrics/telemetry hooks
- Debug mode with request/response logging
Rate Limiting
- Client-side rate limiting
- Respect Retry-After headers
- Exponential backoff improvements

6.2 Performance Optimizations

Connection Pooling
- Reuse HTTP connections
- Connection keep-alive
Caching
- Cache device codes
- Cache user codes for retry scenarios

7. Best Practices for Users

7.1 Error Handling

Always handle specific errors:

try:
    token = poll_for_token(device_code)
except NotAvailableError:
    print("GitHub Copilot not available for this account")
except TimeoutError:
    print("Authentication timed out")
except Exception as e:
    print(f"Unexpected error: {e}")

7.2 Token Management

Check expiration before use:

if (token.isExpired()) {
  token = await refreshToken(token.refreshToken);
}
// Use token
await makeAuthenticatedRequest(token.accessToken);

7.3 Configuration

Use environment variables for configuration:

export HYPER_BASE_URL=https://api.hyper.example.com

Author

Name: Shibo Li
Email: shadow.li981@gmail.com

References

This project is inspired by and references:

License

MIT License

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OAuth Library - Design Document

1. Project Overview

1.1 Core Values

1.2 Project Structure

2. Architecture Design

2.1 Layered Architecture

2.2 Module Design

3. Core Design Principles

3.1 Token Abstraction

3.2 GitHub Copilot Integration

3.3 Hyper Service Integration

3.4 Security Measures

4. Implementation Differences

4.1 Go Implementation

4.2 Python Implementation

4.3 TypeScript Implementation

5. Testing Considerations

5.1 Unit Testing

5.2 Integration Testing

6. Future Enhancements

6.1 Potential Features

6.2 Performance Optimizations

7. Best Practices for Users

7.1 Error Handling

7.2 Token Management

7.3 Configuration

Author

References

License

FilesExpand file tree

design_EN.md

Latest commit

History

design_EN.md

File metadata and controls

OAuth Library - Design Document

1. Project Overview

1.1 Core Values

1.2 Project Structure

2. Architecture Design

2.1 Layered Architecture

2.2 Module Design

3. Core Design Principles

3.1 Token Abstraction

3.2 GitHub Copilot Integration

3.3 Hyper Service Integration

3.4 Security Measures

4. Implementation Differences

4.1 Go Implementation

4.2 Python Implementation

4.3 TypeScript Implementation

5. Testing Considerations

5.1 Unit Testing

5.2 Integration Testing

6. Future Enhancements

6.1 Potential Features

6.2 Performance Optimizations

7. Best Practices for Users

7.1 Error Handling

7.2 Token Management

7.3 Configuration

Author

References

License