48 lines
2.6 KiB
Markdown
48 lines
2.6 KiB
Markdown
# GitHub Module Documentation
|
|
|
|
## Purpose
|
|
This module provides GitHub authentication, OAuth device flow, Octokit client factory, and repository URL parsing utilities for the web server runtime.
|
|
|
|
## Entrypoints and structure
|
|
- `packages/web/server/lib/github/index.js`: public entrypoint imported by `packages/web/server/index.js`.
|
|
- `packages/web/server/lib/github/auth.js`: auth storage, multi-account support, and client ID/scope configuration.
|
|
- `packages/web/server/lib/github/device-flow.js`: OAuth device code flow implementation for browserless auth.
|
|
- `packages/web/server/lib/github/octokit.js`: Octokit client factory backed by current auth.
|
|
- `packages/web/server/lib/github/repo/index.js`: GitHub remote URL parser and directory-to-repo resolver.
|
|
|
|
## Public exports (from index.js)
|
|
|
|
### Auth (`auth.js`)
|
|
- `getGitHubAuth()`: Returns current auth entry (accessToken, user, scope, accountId).
|
|
- `getGitHubAuthAccounts()`: Returns list of all configured accounts.
|
|
- `setGitHubAuth({ accessToken, scope, tokenType, user, accountId })`: Stores or updates auth entry.
|
|
- `activateGitHubAuth(accountId)`: Sets specified account as current.
|
|
- `clearGitHubAuth()`: Removes current account or deletes storage file if last account.
|
|
- `getGitHubClientId()`: Resolves client ID from env var, settings.json, or default.
|
|
- `getGitHubScopes()`: Resolves scopes from env var, settings.json, or default.
|
|
- `GITHUB_AUTH_FILE`: Storage file path constant.
|
|
|
|
### Device flow (`device-flow.js`)
|
|
- `startDeviceFlow({ clientId, scope })`: Requests device code from GitHub.
|
|
- `exchangeDeviceCode({ clientId, deviceCode })`: Polls for access token.
|
|
|
|
### Octokit (`octokit.js`)
|
|
- `getOctokitOrNull()`: Returns configured Octokit instance or null if no auth.
|
|
|
|
### Repo (`repo/index.js`)
|
|
- `parseGitHubRemoteUrl(raw)`: Parses SSH/HTTPS URLs into `{ owner, repo, url }`.
|
|
- `resolveGitHubRepoFromDirectory(directory, remoteName)`: Resolves GitHub repo from git remote.
|
|
|
|
## Storage and configuration
|
|
- Auth storage: `~/.config/openchamber/github-auth.json` (atomic writes, mode 0o600).
|
|
- Client ID: `OPENCHAMBER_GITHUB_CLIENT_ID` env var → `settings.json` → default.
|
|
- Scopes: `OPENCHAMBER_GITHUB_SCOPES` env var → `settings.json` → default.
|
|
|
|
## Account resolution
|
|
Account IDs are resolved in priority order: explicit `accountId` → user login → user ID → token prefix.
|
|
|
|
## Notes for contributors
|
|
- All auth operations use atomic file writes for safe multi-instance sharing.
|
|
- Device flow handles GitHub's `authorization_pending` responses at caller level.
|
|
- Repo parser supports `git@github.com:`, `ssh://git@github.com/`, and `https://github.com/` URL formats.
|