feat: add optional authentication with a personal access token

When given, the token is sent as an `Authorization` header on every
request, raising the rate limit and granting access to private repo the
token can see.
The forge adapter interface has new optional fields: `tokenStorageKey`
and `authHeader`.
A dedicated options page renders one token field per auth-capable forge,
storing tokens in `storage.local` on the device only.

Ref #5

Author: Linkid

DOCUMENTATION.md

@@ -10,6 +10,7 @@ request question: instead of *"which files does this PR change?"*, it tells you
 - [How it works](#how-it-works)
 - [Project layout](#project-layout)
 - [Usage](#usage)
+- [Authentication](#authentication)
 - [Forges](#forges)
 - [Internationalization](#internationalization)
 - [Install](#install)
@@ -36,8 +37,9 @@ Runs on every tab update:
 
 1.   **Parse the URL**: extract `projectKey`, `repoSlug` and `filepath`
 2.   **Detect the forge** by hostname
-3.   **Promise chain**: list PRs, get files, keep PRs including the file
-4.   **Render**: set the toolbar badge text and stores `{ tabId, prs }` in
+3.   **Load the auth headers** for the forge from the stored token (if any)
+4.   **Promise chain**: list PRs, get files, keep PRs including the file
+5.   **Render**: set the toolbar badge text and stores `{ tabId, prs }` in
      `browser.storage.local`.
 
 ### Popup
@@ -60,7 +62,12 @@ On open, the popup:
 ├── forges.js              # per-forge API endpoint config
 ├── popup/
 │   ├── popup.html         # popup markup
+│   ├── options.css        # popup page styles
 │   └── popup.js           # popup logic (read storage, render)
+├── options/
+│   ├── options.html       # options page markup
+│   ├── options.css        # options page styles
+│   └── options.js         # options logic (per-forge token fields)
 ├── _locales/
 │   ├── template.json      # empty key template for new locales
 │   ├── en/messages.json   # English (default locale)
@@ -81,6 +88,28 @@ On open, the popup:
 A badge of `err` means a request failed (often the rate limit — see below);
 check the service-worker console for details.
 
+## Authentication
+
+Authentication is **optional**. Without a token, the extension calls the forge
+API anonymously. Configuring a token raises the API rate limit and lets the
+extension see private repositories the token can access.
+
+To set a token, open the extension's **options page** (the *Settings* /
+*Preferences* / *Options* entry of the extension in the browser) and paste a
+forge token into its field. Tokens are saved in `browser.storage.local`, so
+they stay **on the device only** and are never synced or sent anywhere except
+as an `Authorization` header to that forge's API.
+
+The options page is forge-agnostic: it renders one token field per forge that
+declares authentication support (see `authForges()` in `forges.js`), so a new
+authenticated forge needs no options-page change.
+
+For GitHub, create a [personal access token][gh-token] (classic or
+fine-grained) — no scope is required for public repositories; grant repository
+read access for private ones.
+
+[gh-token]: https://github.com/settings/tokens
+
 ## Forges
 
 Forge endpoints are configured in `forges.js`, which defines one **adapter**
@@ -101,6 +130,12 @@ Here is the interface for each forge:
 | `prNumber`   | identifier of a PR (used in URLs and displayed)                    |
 | `prWebUrl`   | web (non-API) URL of a PR, for the popup links                     |
 | `rateLimit`  | optional `{ url, header, remaining(data) }`; `null` if unsupported |
+| `tokenStorageKey` | optional `storage.local` key holding the user's token; omit for no auth |
+| `authHeader` | optional `(token) → headers` sent with API requests; omit for no auth |
+
+A forge that omits `tokenStorageKey`/`authHeader` simply stays unauthenticated;
+declaring both opts it into the [Authentication](#authentication) flow and the
+options-page token field.
 
 So, to add a new forge:
 - in `forges.js`, create a new object implementing this interface
@@ -119,7 +154,7 @@ language if it exists.
 
 Strings are resolved two ways:
 - `__MSG_<key>__` placeholders
-- `browser.i18n.getMessage("<key>")` (in `popup.js`).
+- `browser.i18n.getMessage("<key>")` (in `popup.js` and `options.js`).
 
 To add a locale:
 - copy `_locales/template.json` to `_locales/<lang>/messages.json`
@@ -156,4 +191,5 @@ See https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-worl
 | --------------------------- | ------------------------------------------------------------ |
 | Badge shows `err`           | A request failed — often the rate limit. Check the console.  |
 | Badge/popup never updates   | The page URL doesn't match the expected file path.           |
-| Rate limit reached quickly  | Unauthenticated API quota; the repo has many open PRs.       |
+| Rate limit reached quickly  | Low anonymous API quota — set a token (see [Authentication](#authentication)). |
+| Private repo shows no PRs   | Set a token whose access covers that repository.             |

README.md

@@ -16,6 +16,9 @@ When you browse a file on a supported forge, the extension:
 This helps you spot pending changes before editing a file and avoid conflicting
 with work already in review.
 
+Optionally, set a personal access token in the extension's options to raise the
+API rate limit and list pull requests from private repositories.
+
 ## Supported forges
 
 - GitHub

_locales/en/messages.json

@@ -18,5 +18,33 @@
   "popupErrorMessage": {
     "message": "Failed to get data",
     "description": "Error message in the popup"
+  },
+  "optionsTitle": {
+    "message": "Settings",
+    "description": "Title of the options page"
+  },
+  "optionsTokenLabel": {
+    "message": "Personal access token",
+    "description": "Label for a forge token input on the options page"
+  },
+  "optionsTokenHint": {
+    "message": "Optional. A token raises the API rate limit and lets the extension see private repositories. It is stored only on this device.",
+    "description": "Hint explaining a forge token input on the options page"
+  },
+  "optionsSave": {
+    "message": "Save",
+    "description": "Label of the save button on the options page"
+  },
+  "optionsClear": {
+    "message": "Clear",
+    "description": "Label of the clear button on the options page"
+  },
+  "optionsSaved": {
+    "message": "Token saved",
+    "description": "Status message shown after saving the token"
+  },
+  "optionsCleared": {
+    "message": "Token cleared",
+    "description": "Status message shown after clearing the token"
   }
 }

_locales/fr/messages.json

@@ -18,5 +18,33 @@
   "popupErrorMessage": {
     "message": "Échec lors de la récupération des données",
     "description": "Message d'erreur dans la popup"
+  },
+  "optionsTitle": {
+    "message": "Paramètres",
+    "description": "Titre de la page d'options"
+  },
+  "optionsTokenLabel": {
+    "message": "Jeton d'accès personnel",
+    "description": "Libellé d'un champ de jeton de forge sur la page d'options"
+  },
+  "optionsTokenHint": {
+    "message": "Facultatif. Un jeton augmente la limite de l'API et permet à l'extension de voir les dépôts privés. Il est stocké uniquement sur cet appareil.",
+    "description": "Aide expliquant un champ de jeton de forge sur la page d'options"
+  },
+  "optionsSave": {
+    "message": "Enregistrer",
+    "description": "Libellé du bouton d'enregistrement sur la page d'options"
+  },
+  "optionsClear": {
+    "message": "Effacer",
+    "description": "Libellé du bouton d'effacement sur la page d'options"
+  },
+  "optionsSaved": {
+    "message": "Jeton enregistré",
+    "description": "Message affiché après l'enregistrement du jeton"
+  },
+  "optionsCleared": {
+    "message": "Jeton effacé",
+    "description": "Message affiché après l'effacement du jeton"
   }
 }

_locales/template.json

@@ -18,5 +18,33 @@
   "popupErrorMessage": {
     "message": "",
     "description": ""
+  },
+  "optionsTitle": {
+    "message": "",
+    "description": ""
+  },
+  "optionsTokenLabel": {
+    "message": "",
+    "description": ""
+  },
+  "optionsTokenHint": {
+    "message": "",
+    "description": ""
+  },
+  "optionsSave": {
+    "message": "",
+    "description": ""
+  },
+  "optionsClear": {
+    "message": "",
+    "description": ""
+  },
+  "optionsSaved": {
+    "message": "",
+    "description": ""
+  },
+  "optionsCleared": {
+    "message": "",
+    "description": ""
   }
 }

background.js

@@ -6,6 +6,9 @@ import { forgeForHostname } from './forges.js'
 //
 let forge = new Object()
 let urlInfo = new Object()
+// headers sent with every forge API request; populated from the stored token
+// (empty when the forge supports no auth or the user configured no token)
+let requestHeaders = {}
 
 // register the extension against the browser (skipped when this module is
 // imported outside a WebExtension context, e.g. by the test runner, where the
@@ -22,12 +25,37 @@ if (browser) {
 //
 // Functions
 //
+// build the auth headers for a forge from an already-fetched storage object
+// returns the headers object — empty when there is no token or the forge
+// supports no authentication
+export function authHeadersFor(forge, stored) {
+    // forges without authentication need no token
+    if (!forge.authHeader || !forge.tokenStorageKey) {
+        return {}
+    }
+
+    const token = stored[forge.tokenStorageKey]
+    return token ? forge.authHeader(token) : {}
+}
+
+// load the auth headers for a forge from its stored token
+// returns a promise resolving to the headers object
+function loadAuthHeaders(forge) {
+    // forges without authentication need no token (and no storage read)
+    if (!forge.authHeader || !forge.tokenStorageKey) {
+        return Promise.resolve({})
+    }
+
+    return browser.storage.local.get(forge.tokenStorageKey)
+        .then(stored => authHeadersFor(forge, stored))
+}
+
 // fetch all pull requests
 // returns a promise with the list of pull requests
 function listAllPRs() {
     console.log("List all pull requests")
 
-    const request = new Request(forge.listPRsUrl(urlInfo))
+    const request = new Request(forge.listPRsUrl(urlInfo), { headers: requestHeaders })
 
     return fetch(request).then(response => {
         //if (!response.ok) {
@@ -41,7 +69,7 @@ function listAllPRs() {
 // returns a promise with the list of modified files for a pull request
 function getModifiedFiles(pr) {
     // fetch the API
-    const request = new Request(forge.filesUrl(urlInfo, pr))
+    const request = new Request(forge.filesUrl(urlInfo, pr), { headers: requestHeaders })
 
     return fetch(request).then(async response => {
         const data = await response.json()
@@ -93,7 +121,7 @@ function checkRateLimit() {
     console.log("Check the rate limit")
 
     // fetch the rate limit endpoint
-    return fetch(forge.rateLimit.url)
+    return fetch(forge.rateLimit.url, { headers: requestHeaders })
         .then(async response => {
             const data = await response.json()
 
@@ -167,8 +195,10 @@ function main(tab) {
     }
     urlInfo = info
 
-    // check the forge rate limit
-    checkRateLimit()
+    // load the stored API token, then check the forge rate limit
+    loadAuthHeaders(forge)
+        .then(headers => { requestHeaders = headers })
+        .then(checkRateLimit)
         // list pull requests
         .then(listAllPRs)
         .then(checkRateLimitFromPRs)

forges.js

@@ -4,7 +4,7 @@
 // unchanged.
 //
 // Adapter interface:
-//   label       human-readable forge name
+//   label       human-readable forge name, shown in the options page UI
 //   hostnames   array of substrings matched against the page hostname (static
 //               forges only; self-hosted forges are matched against the user's
 //               configured instance list instead)
@@ -16,6 +16,10 @@
 //   prWebUrl    (info, prNumber) -> web (non-API) URL of a PR, for popup links
 //   rateLimit   optional { url, header, remaining(data) }; null if the forge
 //               exposes no rate-limit endpoint
+//   tokenStorageKey  optional storage.local key holding the user's API token;
+//                    omit if the forge supports no authentication
+//   authHeader  optional (token) -> headers object sent with API requests when
+//               a token is configured; omit if the forge supports no auth
 
 // API docs: https://docs.github.com/en/rest/pulls
 export const github = {
@@ -55,6 +59,15 @@ export const github = {
         header: "x-ratelimit-remaining",
         remaining: (data) => data.resources.core.remaining,
     },
+
+    // GitHub accepts classic and fine-grained personal access tokens as a
+    // Bearer credential. Authenticating raises the rate limit and grants
+    // access to private repositories the token can see.
+    tokenStorageKey: "githubToken",
+
+    authHeader(token) {
+        return { Authorization: `Bearer ${token}` }
+    },
 }
 
 // registry of forges matched by a static hostname
@@ -64,3 +77,9 @@ const staticForges = [github]
 export function forgeForHostname(hostname) {
     return staticForges.find(f => f.hostnames.some(h => hostname.includes(h))) || null
 }
+
+// forges that support authentication (declare both a token storage key and a
+// header builder); the options page renders one token field per such forge.
+export function authForges() {
+    return staticForges.filter(f => f.tokenStorageKey && f.authHeader)
+}

manifest.json

@@ -18,7 +18,8 @@
       "id": "git-pr-reverse@webext.com",
       "strict_min_version": "140.0",
       "data_collection_permissions": {
-        "required": ["none"]
+        "required": ["none"],
+        "optional": ["authenticationInfo"]
       }
     },
     "gecko_android": {
@@ -41,6 +42,10 @@
     "default_title": "Git PR reverse",
     "default_popup": "popup/popup.html"
   },
+  "options_ui": {
+    "page": "options/options.html",
+    "open_in_tab": true
+  },
 
   "permissions": [
     "storage",

options/options.css

@@ -0,0 +1,24 @@
+:root {
+  --bg: #fff; --fg: #1b1b1b; --muted: #6b6b6b;
+  --link: #0060df; --border: #e0e0e0;
+}
+@media (prefers-color-scheme: dark) {
+  :root { --bg: #1c1b22; --fg: #fbfbfe; --muted: #b1b1bd;
+          --link: #80b3ff; --border: #38383d; }
+}
+
+body { background: var(--bg); color: var(--fg); }
+.options { max-width: 32rem; margin: 0 auto; padding: 1rem; }
+.options__form { display: flex; flex-direction: column; gap: 0.5rem; }
+.options__forge {
+  display: flex; flex-direction: column; gap: 0.5rem;
+  border: 1px solid var(--border); border-radius: 4px; padding: 0.75rem;
+}
+.options__forge legend { font-weight: 600; padding: 0 0.25rem; }
+.options__hint { color: var(--muted); margin: 0; font-size: 0.85rem; }
+.options__input {
+  padding: 0.4rem; border: 1px solid var(--border); border-radius: 4px;
+  background: var(--bg); color: var(--fg);
+}
+.options__actions { display: flex; gap: 0.5rem; margin-top: 0.5rem; }
+.options__status { color: var(--muted); min-height: 1.2em; }