Authentication & PAT Setup

Relevant source files

The following files were used as context for generating this wiki page:

• src/components/token-setup.tsx
• src/entries/popup/app.tsx
• src/entries/options/app.tsx
• src/lib/storage.ts (Referenced via patStorage and usernameStorage)
• README.md
• src/lib/graphql/queries.ts

Introduction

Authentication in Refined GitHub Projects is handled exclusively through a GitHub Personal Access Token (PAT). This mechanism ensures that the extension can interact with the GitHub GraphQL API to perform bulk operations, such as editing project fields, duplicating items, and managing sprints. The system is designed with a "Privacy by Design" approach, where the token is stored locally within the browser's extension storage and never transmitted to external servers other than GitHub's official API.

Sources: README.md:144-149, src/components/token-setup.tsx:109-111

Token Requirements & Scopes

To function correctly, the extension requires a "Classic" Personal Access Token with specific permissions. These scopes allow the background service worker to read and write data across repositories and project boards.

Scope	Requirement	Reason
repo	Mandatory	Read/write access to issues, labels, and assignees.
read:org	Mandatory	Read organization membership for searching assignees.
project	Mandatory	Read/write access to GitHub Projects V2 fields and items.

Sources: README.md:158-166, src/components/token-setup.tsx:101

Authentication Architecture

The authentication system is built on a React-based UI that interacts with the browser's storage and background scripts. The useTokenSetup hook serves as the primary logic controller for managing token states, validation, and persistence.

Data Flow for Token Validation

The following diagram illustrates the sequence of events when a user provides a new PAT for validation:

Components and Hooks

• useTokenSetup Hook: Manages the local state for the token, loading status, validating status, and error messages. It utilizes patStorage to retrieve or persist the token.
  • Sources: src/components/token-setup.tsx:14-78
• TokenSetupCard: A reusable UI component (used in the Options page) that provides a full interface for token entry, scope checklists, and validation feedback.
  • Sources: src/components/token-setup.tsx:94-239
• Popup App: A compact version of the authentication interface for quick status checks and token updates.
  • Sources: src/entries/popup/app.tsx:15-117

Implementation Details

Validation Logic

The validation process uses the VALIDATE_TOKEN GraphQL query to verify the token's validity and retrieve the authenticated user's login name. This ensures that the token not only exists but has the necessary connectivity.

// src/lib/graphql/queries.ts:1-7
export const VALIDATE_TOKEN = `
  query {
    viewer {
      login
    }
  }
`

Sources: src/lib/graphql/queries.ts:1-7

Persistence

The extension uses WXT's storage API (wrapped in patStorage and usernameStorage) to keep the session active across browser restarts.

• patStorage: Stores the actual sensitive token string.
• usernameStorage: Stores the GitHub login of the authenticated user to display the "Connected as @user" status.

Sources: src/components/token-setup.tsx:24-27, src/entries/popup/app.tsx:32-36

Onboarding and User Feedback

The extension provides clear feedback during the setup process to guide the user:

1. Loading State: When the popup or options page opens, it checks for an existing token using patStorage.getValue().
2. Success Feedback: Upon successful validation, a Flash component or StatusBanner displays the authenticated GitHub username.
3. Error Handling: If validation fails (e.g., due to missing scopes or an expired token), an error message is displayed, and the "Validate" button is re-enabled.

Sources: src/components/token-setup.tsx:129-159, src/entries/popup/app.tsx:55-72

Summary

Authentication in Refined GitHub Projects is a secure, local-only process centered around a GitHub Personal Access Token. By requiring specific scopes (repo, read:org, project), the extension ensures it has the necessary permissions to manage Project V2 boards. The architecture leverages React hooks for state management and browser storage for persistence, providing a seamless onboarding experience through both the extension popup and the dedicated options page.