openchamber/packages/web/server/lib/github/DOCUMENTATION.md

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.