Privacy & Security Model

The Privacy & Security Model of Refined GitHub Projects is built on a "local-first" philosophy where sensitive data and API interactions remain entirely within the user's browser environment. The system is designed to provide bulk-action superpowers for GitHub Projects V2 without introducing middle-man servers, telemetry, or external data collection.

Key security tenets include the local storage of Personal Access Tokens (PAT), direct browser-to-GitHub API communication, and strict rate-limit management to protect the user's account standing.

Sources: PRIVACY.md:1-5, README.md:231-235

Data Sovereignty & Storage

The extension follows a zero-collection policy. It does not utilize any backend servers, proxies, or third-party relays for processing project data.

Personal Access Token (PAT) Management

The most sensitive piece of information, the GitHub Personal Access Token, is handled with high isolation:

• Storage: Tokens are stored exclusively in chrome.storage.local on the user's device.
• Transmission: The token is only sent to api.github.com via the Authorization header.
• Scope: The extension requires specific scopes (repo, read:org, project) to function, but these are used only for direct mutations and queries requested by the user.

Sources: PRIVACY.md:7-11, src/entries/background/helpers.ts:161-163, README.md:201-209

Storage Architecture

The following diagram illustrates the isolated storage model used for sensitive credentials.

The PAT is never transmitted to any destination other than GitHub's official API.
Sources: README.md:214-230, PRIVACY.md:13-15

Network Security & API Flow

All network communication is strictly limited to GitHub's infrastructure. There are no analytics, crash reporting, or telemetry services integrated into the codebase.

Communication Flow

To maintain security and bypass Content Security Policy (CSP) limitations on the GitHub website, all API calls are proxied through the extension's background service worker.

Sources: README.md:214-230, CONTRIBUTING.md:12-13, PRIVACY.md:17-19

Sequential Mutation Queue

A critical security and stability feature is the sequential execution of mutations. Concurrent requests to GitHub's API with a PAT can result in 403 "Abuse" bans. The extension enforces a 1-second delay between every mutation to ensure account safety.

The architecture explicitly forbids the use of Promise.all() for mutations.
Sources: CONTRIBUTING.md:7-10, README.md:231-235, src/entries/background/helpers.ts:468-472

Implementation Details

GitHub Request Security

The githubRest helper function standardizes security headers for all REST requests, ensuring that the PAT is handled consistently.

// src/entries/background/helpers.ts:160-170
export async function githubRest<T>(path: string, init: RequestInit = {}): Promise<T> {
  const pat = await patStorage.getValue()
  const headers = new Headers(init.headers)
  headers.set('Accept', 'application/vnd.github+json')
  headers.set('Authorization', `Bearer ${pat ?? ''}`)
  headers.set('X-GitHub-Api-Version', '2022-11-28')
  // ... execution ...
}

Sources: src/entries/background/helpers.ts:160-170

Rate Limit & Error Handling

The security model includes proactive backoff logic when GitHub signals rate limiting (HTTP 403 or 429).

• Backoff: If a rate limit is hit, the queue pauses and broadcasts a paused state.
• Retry: The system waits for the duration specified in the Retry-After header before resuming.

Sources: src/entries/background/helpers.ts:518-535, README.md:131-133

Manifest Permissions

The extension follows the principle of least privilege in its manifest.json configuration, requesting only necessary permissions.

Sources: wxt.config.ts:80-87

Summary

The Refined GitHub Projects security model prioritizes user privacy by eliminating the need for a backend and keeping all sensitive data, including Personal Access Tokens, within the local browser storage. By enforcing sequential API calls and respecting GitHub's rate limits, the extension ensures that bulk operations are performed safely without risking the user's account integrity.