scripts/popup-main.js"] - options["options.html
options.js"] - menus["Context menus
Ctrl+Shift+S"] - bg["background.js
service worker — message router"] - content["content.js
read-only DOM extraction"] - config["core/configuration-manager.js
chrome.storage.sync"] - tasks["core/tasks.js
prompt construction"] - client["providers/ai-client.js
one fetch client, shaped per provider"] - store["services/storage-service.js
chrome.storage.local history"] - api["Provider HTTPS API"] - - popup -->|chrome.runtime.sendMessage| bg - options -->|writes settings| config - options -->|connection test| bg - menus --> bg - bg -->|chrome.tabs.sendMessage| content - content -->|page text| bg - bg --> config - bg --> tasks - config -->|builds a client for
the selected provider| client - tasks -->|system + user prompt| client - client -->|fetch, with retry| api - bg --> store -``` - -### Request lifecycle: one summary +The repository root is a loadable MV3 extension with no build step or runtime +dependencies. All provider calls originate in the worker; the content script +only reads the page. ```mermaid -sequenceDiagram - participant U as User - participant P as Popup - participant B as background.js - participant C as content.js - participant A as Provider API - - U->>P: Click "Generate Summary" - P->>B: EXTRACT_PAGE_CONTENT { tabId } - B->>C: chrome.tabs.sendMessage - C-->>B: title, mainText, headings - B-->>P: page content - P->>B: GENERATE_CONTENT_SUMMARY { content, style, length } - B->>B: chunkContent() — split if over 24,000 chars - - alt page fits one request - B->>A: one completion - A-->>B: summary - else long page (map-reduce, 3 sections in flight) - loop each section, capped at 8 - B->>A: summarize section - A-->>B: section notes - end - B->>A: merge the notes - A-->>B: whole-page summary - end - - B->>B: save to local history - B-->>P: text, provider, model, sections, droppedChars - P->>U: rendered summary + coverage statement +flowchart LR + UI["Popup / workspace / options"] -->|runtime messages| Worker["background.js"] + Menu["Menus / shortcut"] --> Worker + Worker -->|tab message| Content["content.js"] + Worker --> Config["ConfigurationManager"] + Worker --> Tasks["core/tasks.js"] + Tasks --> Client["providers/ai-client.js"] + Config --> Client + Client -->|HTTPS| API["Selected provider"] + Worker --> History["StorageService"] ``` -A failure at any provider step is returned with its own message and an error -code (`MISSING_API_KEY`, `AUTH_ERROR`, `TIMEOUT`, …). Nothing degrades into a -plausible-looking fake result, and a section that fails after retries fails the -whole summary rather than producing a partial one presented as complete. +A summary extracts page text, checks the saved-result key, then either makes one +request or summarizes up to eight 24,000-character sections (three concurrently) +and merges the notes. Any failed section fails the task; partial results are not +presented as complete. Errors retain their code and message. ## Source map -| File | Responsibility | -| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `background.js` | `BackgroundService`: registers listeners synchronously, routes messages, runs AI tasks, and handles menus, commands, and cleanup | -| `providers/ai-client.js` | `AIClient` and `PROVIDERS`: provider-specific HTTPS requests, response parsing, retries, and timeouts | -| `core/tasks.js` | Prompt construction, content fencing, chunking, and response parsing | -| `core/document.js` | Shared 2,000,000-character limit and URL/content SHA-256 identity | -| `core/retrieval.js` | Local BM25 passage indexing, ranking, and source excerpts | -| `core/configuration-manager.js` | Settings defaults and persistence; constructs a client for the selected provider | -| `content.js` | Reads page text, metadata, links, images, and selection without modifying the page | -| `scripts/popup-main.js` | Popup/workspace controls, text import, scoped restoration, and escaped result rendering | -| `options.js` | Provider selection, keys, model overrides, appearance, and feature settings | -| `services/storage-service.js` | Local summary and conversation history | -| `services/notification-manager.js` | Desktop notifications for background actions | - -The selected provider is explicit. `ConfigurationManager.createAIClient()` either -constructs that provider's `AIClient` or reports a missing key. Default models and -wire formats live in `PROVIDERS`; there is no provider scoring or automatic -fallback. See [the provider client](../providers/ai-client.js) before adding an API. +| Path | Responsibility | +| ------------------------------- | ------------------------------------------------------------------------------------ | +| `background.js` | Synchronously registered listeners, message routing, tasks, menus, commands, cleanup | +| `content.js` | Read-only DOM text, metadata, links, images, selection | +| `core/configuration-manager.js` | Settings/defaults and construction of the selected client | +| `core/tasks.js` | Prompts, content fencing, chunking, response parsing | +| `core/document.js` | Shared document limit and URL/text SHA-256 identity | +| `core/retrieval.js` | Local BM25 indexing, ranking, source excerpts | +| `providers/ai-client.js` | Provider wire formats, HTTPS, retries, timeouts | +| `scripts/popup-main.js` | Popup/workspace, imports, restoration, escaped rendering | +| `options.js` | Settings UI | +| `services/` | History persistence and desktop notifications | + +Default models and wire formats live in `PROVIDERS`. Selection is explicit: +a missing key is an error, with no scoring or automatic provider fallback. ## Message contract Extension pages send `{ actionType, requestId, payload }` through -`chrome.runtime.sendMessage`. `requestId` is optional and echoed in the response. -`validateMessage()` requires a non-empty action string and this extension's sender -ID. The router rejects unsupported actions. - -| Action | Input / result | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `GENERATE_CONTENT_SUMMARY` | `content`, `summaryType`, `targetLength`; returns summary and coverage information | -| `ANSWER_CONTEXTUAL_QUESTION` | `question`, `context`, optional `conversationHistory`, `url`, `title`; returns answer, sources, and retrieval coverage | -| `TRANSLATE_CONTENT` | `text`, `targetLanguage`, optional `sourceLanguage` | -| `ANALYZE_SENTIMENT` | `text`; returns sentiment and reason | -| `EXTRACT_KEY_INSIGHTS`, `GENERATE_SMART_TAGS`, `EXTRACT_ENTITIES` | `text`; returns the requested analysis | -| `EXTRACT_PAGE_CONTENT` | `tabId`, falling back to the sender tab; returns content-script extraction | -| `GET_USER_PREFERENCES`, `UPDATE_USER_PREFERENCES` | Read settings or merge a settings payload | -| `GET_PROVIDER_STATUS` | Configured status for the selected provider and each provider key | -| `TEST_PROVIDER_CONNECTION` | Entered `provider`, `apiKey`, optional `model`; one 16-token request, 10-second timeout, zero retries; returns model, never saves key | -| `GET_DOCUMENT_HISTORY` | `url`, `content`; returns one summary, up to 30 exchanges for that identity, and `memoryEnabled` | -| `CLEAR_DOCUMENT_CHAT` | `url`, `content`; removes only matching exchanges; returns count | -| `GET_HISTORY` | Saved summaries and conversations | -| `EXPORT_USER_DATA` | Schema-v2 object containing settings without API keys and saved history | - -Success responses contain `{ success: true, data, requestId, processingTime }`. -Failures contain `{ success: false, error, errorCode, requestId, processingTime }`. -The popup passes an explicit tab ID because popup messages have no `sender.tab`. -The content script uses its separate `{ action: 'extractContent' }` protocol. +`chrome.runtime.sendMessage`. The optional request ID is echoed. +[Validation](../utils/validation-service.js) requires an object, a nonempty action, +and this extension's sender ID; the [router](../background.js) rejects unknown actions. + +| Action | Input / result | +| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `GENERATE_CONTENT_SUMMARY` | `content`, `summaryType`, `targetLength`; summary and coverage | +| `ANSWER_CONTEXTUAL_QUESTION` | `question`, `context`, optional `conversationHistory`, `url`, `title`; answer, sources, coverage | +| `TRANSLATE_CONTENT` | `text`, `targetLanguage`, optional `sourceLanguage` | +| `ANALYZE_SENTIMENT` | `text`; sentiment and reason | +| `EXTRACT_KEY_INSIGHTS`, `GENERATE_SMART_TAGS`, `EXTRACT_ENTITIES` | `text`; requested analysis | +| `EXTRACT_PAGE_CONTENT` | `tabId`, falling back to sender tab; extraction | +| `GET_USER_PREFERENCES`, `UPDATE_USER_PREFERENCES` | Read settings or merge a settings payload | +| `GET_PROVIDER_STATUS` | Selected provider and configured-key status | +| `TEST_PROVIDER_CONNECTION` | Entered `provider`, `apiKey`, optional `model`; 16-token request, 10s timeout, no retries; never saves key | +| `GET_DOCUMENT_HISTORY` | `url`, `content`; summary, up to 30 exchanges, `memoryEnabled` | +| `CLEAR_DOCUMENT_CHAT` | `url`, `content`; removes matching exchanges, returns count | +| `GET_HISTORY` | Saved summaries and conversations | +| `EXPORT_USER_DATA` | Schema-v2 settings/history object, excluding API keys | + +Success: `{ success: true, data, requestId, processingTime }`. +Failure: `{ success: false, error, errorCode, requestId, processingTime }`. +Popup messages have no `sender.tab`, so send an explicit tab ID. +The content script separately accepts `{ action: 'extractContent' }`. ## Storage and security -Settings live in `chrome.storage.sync.user_preferences`, including `apiKeys`, -`models`, `preferredProvider`, summary preferences, source/target languages, theme, -and feature flags. -API keys are plaintext at the storage API level and sync with the browser profile. -They are sent only to the selected provider in HTTPS headers and excluded from -exports. See [SECURITY.md](SECURITY.md) for the trust boundaries. - -History lives in `chrome.storage.local` under `genai_summary_history` (up to 1,000 -entries) and `genai_conversation_history` (up to 500). A daily alarm removes entries -older than 90 days; entries without timestamps are retained. Settings have one -reader/writer, `ConfigurationManager`; history belongs to `StorageService`. +`ConfigurationManager` owns `chrome.storage.sync.user_preferences`: +keys, models, provider, summary/language/theme preferences, and feature flags. +Keys are plaintext at the API level, sync with the browser profile, and are +excluded from exports. Unreadable preferences cannot authorize optional effects +or replacement updates. See [security and data handling](SECURITY.md). -Model output is escaped before the popup's small Markdown subset is applied. -Page text is fenced as untrusted data. Questions are limited to 1,000 characters; -single-request tasks use at most 24,000 context characters. Summaries can process -up to eight sections with three section requests in flight, then merge their notes. -There is no telemetry backend or production bundle. +`StorageService` owns local `genai_summary_history` (1,000 entries) and +`genai_conversation_history` (500). A daily alarm prunes entries older than +90 days; entries without timestamps remain. Mutations serialize per key in the +worker, including clear-chat and cleanup. A failed mutation read propagates +instead of overwriting history with an empty list; read-only access retains its +logged fallback. ### Document retrieval, cache, and memory -The worker hashes URL plus trimmed text to identify a document. A changed page or -different URL starts a new thread. Older unscoped history remains exportable but -is not restored into a page. Full text imports and indexes are not persisted. +Identity hashes URL plus trimmed text. Changed text/URLs start another thread; +old unscoped records remain exportable without being restored. Full imports and +indexes are not persisted. -```mermaid -flowchart LR - doc["Page or text import ≤2M characters"] --> id["URL/content identity"] - id --> index["BM25 index, up to 3 cached documents"] - question["Question + previous user wording"] --> index - index --> passages["Up to 6 passages, source labels"] - passages --> prompt["Fenced question prompt"] - prompt --> api["Selected provider"] - api --> saved["Answer + focused source excerpts in local history"] -``` +Retrieval selects up to six 2,800-character passages with 200-character overlap. +It uses question and prior user wording; no-match queries sample across the +document. This is lexical retrieval, with no guarantee of semantic or exhaustive +recall. The three-document cache evicts the oldest insertion and disappears on +worker suspension. Restoration returns at most 30 exchanges; prompts use bounded +recent conversation. See [retrieval research](product/RESEARCH.md). + +Summary keys include `summary-v1`, document identity, provider, model, style, +and length. Bump the version when summary prompt meaning changes. Save history +off disables saves, cache reuse, and restoration; it does not delete records. +The worker checks the preference again before saving an in-flight result. -Passages are at most 2,800 characters with 200-character overlap. Retrieval is -lexical; no-match queries sample across the document. It does not guarantee -semantic recall or whole-book coverage. The index cache evicts the oldest inserted -document at three entries and is lost on worker suspension. The next question -rebuilds it. Restored exchanges use at most 30 turns; prompts use the bounded -recent conversation in `core/tasks.js`. - -Summary cache keys include `summary-v1`, identity, provider, model, style, and -length. Bump the cache version if summary prompt meaning changes. The request -lifecycle above is skipped on a matching saved result. Save-history off disables -new saves, summary cache reuse, and restoration; it does not erase past records. -The preference is read again before persisting an in-flight result. - -Storage read-modify-write operations are serialized per history key in the single -worker. Clear-chat and daily cleanup use the same queues. A failed mutation read -propagates rather than overwriting history with an empty list. Read-only history -access retains its logged fallback behavior. -Generated summaries are stored once as `summary`; `text` is reconstructed for the -response contract. If a history write fails (including storage quota), summary -and chat results still reach the UI with a visible warning to copy the result. -No second AI request is made just to retry persistence. - -`popup.html?workspace=1&tabId=123` uses an explicit source tab; ordinary popup -startup queries the active tab. Workspace text/Markdown import validates an 8 MB -file limit and the shared character limit. Import and extraction trigger no AI -request. Imported material uses a `local-document:` filename identity plus its -content hash. File content is read only after the user chooses it. +Summaries are stored once as `summary`; response `text` is reconstructed. +History/quota failures leave generated summary/chat output visible with a save +warning, without another provider request. + +`popup.html?workspace=1&tabId=123` binds a workspace to its source tab; ordinary +popup startup queries the active tab. User-selected UTF-8 text/Markdown imports +validate 8 MB and 2,000,000-character limits. Their identity uses +`local-document:`, filename, and content hash. Extraction/import sends no AI request. ## Local validation -Use Node >=20.19 and npm >=10, as declared in [package.json](../package.json). +Use Node >=20.19 and npm >=10. ```bash npm ci @@ -204,49 +126,47 @@ npm audit --audit-level=high npm run benchmark:retrieval ``` -Vitest imports the shipped controllers and mocks `chrome.*` and provider fetches. -Coverage includes all shipped JavaScript; the global branch threshold is 78%, -with a separate 75% floor for `background.js`. Other thresholds are in -[vitest.config.js](../vitest.config.js). +`verify` runs lint, typecheck, and Vitest. Tests import shipped controllers and +mock Chrome APIs/provider fetches. [Coverage floors](../vitest.config.js) cover +all shipped JavaScript: statements/functions 85%, lines 88%, branches 78%, and +worker branches 75%. -Playwright loads the actual extension in persistent Chromium contexts. Fixture -pages and provider responses are intercepted. A real toolbar-icon click granting -`activeTab` remains a manual release check; intercepted tests do not demonstrate -live provider credentials, model availability, or output quality. +Playwright uses the actual unpacked extension in persistent Chromium contexts, +with intercepted fixture pages/provider responses. A real toolbar click granting +`activeTab` remains a manual release check. These tests do not verify live keys, +model access/quality, native OS notices, or minimum-browser compatibility. ## Pull requests and packaging -CI runs lint, typechecking, and coverage on Node 20/22/24; Node 22 also runs the -dependency audit. Browser tests run before the package job. - -The workflow selects `ubuntu-26.04` explicitly and pins action release commits. -Action runtimes are separate from the Node versions tested by the project. -Checkout credentials are not retained after checkout; the ancestry guard uses -the full fetched history. npm caching uses `package-lock.json` explicitly, and +[CI](../.github/workflows/ci.yml) runs lint, types, and coverage on Node 20/22/24; +Node 22 also audits dependencies. Browser tests precede packaging. +Ubuntu 26.04 and action release SHAs are explicit. Action execution runtimes are +separate from the application's Node matrix. Checkouts do not persist credentials; +the ancestry guard fetches full history. Install jobs cache npm using the lockfile; the dependency-free guard disables automatic package-manager caching. -See [migration decisions and validation](ci-modernization-evidence.md) before -updating these pins. Codecov remains optional; a green job alone does not prove -that coverage reached the service. - -The PR-base job rejects a non-default base branch already contained in the default -branch. Retarget the PR at the default branch when this fails. The check runs on -opening, reopening, head updates, and edits (including retargeting). It checks Git -ancestry at workflow time; squash/rebase equivalence and future base merges are -not continuously monitored. Tests in `tests/ci/pr-base.test.js` exercise the guard -against temporary Git histories. - -The repository root is the loadable extension. Load it unpacked at -`chrome://extensions`, then reload after source edits. Legacy `dist/` and `build/` -output are ignored by Git and ESLint and can be left in an older checkout. - -The CI ZIP explicitly includes `manifest.json`, the runtime root JavaScript and -HTML/CSS files, `assets/`, `core/`, `providers/`, `scripts/`, `services/`, `styles/`, -`utils/`, `README.md`, and `LICENSE`. Keep that list in -[ci.yml](../.github/workflows/ci.yml) current when adding runtime files. CI uploads -the ZIP as an Actions artifact; Chrome Web Store publishing is a separate release -step. Install and configure the unpacked extension using [README.md](../README.md). - -For consolidation decisions and verification evidence, see -[INTEGRATION-REVIEW.md](INTEGRATION-REVIEW.md). -For product scope, research, and retrieval measurements, see -[product/PRODUCT.md](product/PRODUCT.md) and [product/RESEARCH.md](product/RESEARCH.md). +Codecov is optional: green status alone does not establish upload success. +See [CI migration evidence](ci-modernization-evidence.md) before changing pins. + +The PR-base guard rejects a non-default base already contained in the default +branch. Retarget after its base lands. It runs on opening, reopening, head updates, +and edits; it checks workflow-time ancestry, not squash/rebase equivalence or +future merges. [Tests](../tests/ci/pr-base.test.js) use temporary Git histories. +The guard is independent of the verify job; required-check policy is a separate +repository setting. + +Load the repository root at `chrome://extensions` and reload after edits. +Legacy ignored output is not a runtime input. +The CI ZIP allowlist contains the manifest, root runtime JS/HTML/CSS, assets, +runtime module directories, README, and LICENSE. +The npm `files` list in [package.json](../package.json) covers the same runtime; +npm also includes package metadata. Check both lists when adding runtime files: + +```bash +npm pack --dry-run --json --ignore-scripts +``` + +Verify manifest targets, relative imports, and HTML assets in the resulting +package. CI uploads an Actions artifact; publication/store release is separate. +See [contribution release steps](../CONTRIBUTING.md#release-process), +[historical integration evidence](INTEGRATION-REVIEW.md), and the +[product brief](product/PRODUCT.md). diff --git a/docs/INTEGRATION-REVIEW.md b/docs/INTEGRATION-REVIEW.md index e1ae361..528131e 100644 --- a/docs/INTEGRATION-REVIEW.md +++ b/docs/INTEGRATION-REVIEW.md @@ -1,124 +1,61 @@ # Integration review -Reviewed 17 October 2026 against `main` at +Historical review: 17 October 2026, base [`b915866`](https://github.com/aaron-seq/GenAI-Browser-Tool/commit/b91586665941d3456f7411557edabc51842892d9). +The [full original record](https://github.com/aaron-seq/GenAI-Browser-Tool/blob/6e8288550ef4935684a6a44c87cbbed77b818d14/docs/INTEGRATION-REVIEW.md) +preserves the detailed inventory and run notes; results below are historical, +not tests rerun by each reader. ## Decision and scope -No PRs were open when this review began. [PR #24](https://github.com/aaron-seq/GenAI-Browser-Tool/pull/24) -had already recovered PRs #14 and #15 into `main`. Start the integration branch -from current `main`, preserve that implementation, and fix validation findings in -one PR targeting `main`. +[PR #24](https://github.com/aaron-seq/GenAI-Browser-Tool/pull/24) had recovered +PRs #14/#15; no PR was open when the review began. Integrate from current main, +preserve the source-loaded MV3 runtime, and fix demonstrated validation problems. -Older refs were inspected and preserved. The old `feat/close-open-issues` branch -contains an alternative test suite superseded by the controllers and coverage -work in 5.2.0. The January `fix/critical-stub-implementations-and-provider-interface` -branch adds an unused abstract provider class for the removed provider system. -Neither represents an open PR or a reason to restore that architecture. - -## Engineering review before implementation - -| Area | Finding / decision | -| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Known facts | Latest `main` contains the recovered functionality; the local checkout was behind. Baseline typecheck and 219 tests passed. | -| Unknown facts | Live credential validity, provider model availability, and real toolbar permission behavior were not demonstrated. | -| Assumptions | `main`, confirmed as the repository default, is the requested integration destination. Preserve existing extension behavior. | -| Clarification questions | None required for this integration; merge authorization was explicit. | -| Success criteria | Lint, types, coverage, browser tests, audit, package inspection, and PR CI pass before merging. | -| Root cause | Earlier stacked work targeted a base already merged; CI validated code without checking whether its destination still needed integration. | -| Architecture | Keep the source-loaded MV3 extension and one selected-provider client. No build system or runtime dependencies added. | -| Security | Patch vulnerable development dependencies; use read-only CI permissions; keep branch names out of shell interpolation; package explicit runtime paths. | -| Performance / scalability | Keep request concurrency, chunk limits, history caps, and retry behavior. No runtime performance changes or new services. | -| Maintainability | Ignore old generated files, document the real interfaces, and test worker lifecycle behavior through registered listeners. | -| Testing strategy | Real temporary Git histories for the base guard, existing mocked worker integration tests, coverage floors, and persistent Chromium E2E. | -| Dependencies | Compatible transitive updates only; no major upgrades, new dependencies, or changes to the shipped extension. | -| Alternatives | Re-merging superseded branches adds dead code; a validation-only report leaves demonstrated audit and packaging problems unresolved. | -| Recommendation | Apply the focused fixes and merge one tested integration PR. | -| Risk | CI ancestry checks observe workflow-time Git history, not patch equivalence or future events; the explicit ZIP input list needs updating for new runtime paths. | -| Rollback | Revert the integration merge on `main` and rerun CI. Existing settings/history and old branches are preserved. | - -Five whys: changes missed `main` because later PRs landed on an old feature branch; -that branch remained a target after its parent PR merged; stacking was valid when -work began; checks verified code but not the target's ancestry; there was no -automated destination check. [Issue #22](https://github.com/aaron-seq/GenAI-Browser-Tool/issues/22) -records the history and acceptance criteria. - -The guard uses [Git's documented `--is-ancestor` status codes](https://git-scm.com/docs/git-merge-base), -[full-history checkout](https://github.com/actions/checkout#fetch-all-history-for-all-tags-and-branches), -and [GitHub's read-only workflow permissions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions). -It runs on PR opening, reopening, head updates, and edits. It does not continuously -monitor future base merges or detect squash/rebase equivalence. Branch protection -was absent at inspection; this PR adds a check without changing repository policy. +Preserve older refs without restoring their superseded test suite or unused +abstract provider implementation. The delivery problem was a stacked base already +merged into main, not missing runtime functionality. +[Issue #22](https://github.com/aaron-seq/GenAI-Browser-Tool/issues/22) records the +ancestry guard; [#23](https://github.com/aaron-seq/GenAI-Browser-Tool/issues/23) +records worker regression coverage. Current behavior and guard limits belong in +[DEVELOPMENT.md](DEVELOPMENT.md#pull-requests-and-packaging). ## Validation personally run -Windows, Node 22.18.0, npm 11.6.2. Provider HTTP calls were mocked/intercepted. - -| Check | Baseline | Integration result | -| ------------------------- | ---------------------------------------------- | -------------------------------------------------- | -| Dependency installation | `npm ci` succeeded | Compatible lockfile updates installed successfully | -| Lint | Failed on pre-existing generated `dist/` files | Passed with old output preserved and ignored | -| Typecheck | Passed | Passed | -| Unit + integration tests | 219 passed, 11 files | 241 passed, 12 files | -| Statement / line coverage | 91.28% / 93.88% | 92.80% / 95.59% | -| Global branch coverage | 77.00%, floor 72% | 80.47%, floor 78% | -| Worker branch coverage | 57.14% | 83.92%, separate floor 75% | -| Worker function coverage | 91.66% | 100% | -| Chromium E2E | Earlier published results are in PR #24 | 13 passed on this branch | -| `npm audit` | 3 high-severity vulnerable packages | 0 vulnerabilities | - -The local extension ZIP contained 22 runtime/documentation files. All manifest -targets and 16 relative JavaScript/HTML references were present; tooling and -legacy output were excluded. GitHub's ZIP will also be inspected before merge. +The original session ran on Windows / Node 22.18.0 / npm 11.6.2, with +mocked/intercepted provider requests. -The 22 additional cases cover merged/equal/open/missing Git bases and a renamed -default branch; context-menu page extraction, absent input and notification size; -commands with/without an active tab; install/update, startup failure, cleanup and -unrelated alarms; and unsuccessful extraction and sender-tab fallback. Sources: -[guard tests](../tests/ci/pr-base.test.js), -[worker tests](../tests/integration/extension-workflow.test.js), and -[coverage configuration](../vitest.config.js). These address -[issue #23](https://github.com/aaron-seq/GenAI-Browser-Tool/issues/23). +| Check | Before | Integration result | +| ------------------------ | ------------------------------------------- | ----------------------------------------------- | +| Lint / types | Lint failed on legacy `dist/`; types passed | Both passed; legacy output retained and ignored | +| Unit/integration | 219 tests / 11 files | 241 / 12 | +| Statements / lines | 91.28% / 93.88% | 92.80% / 95.59% | +| Global / worker branches | 77.00% / 57.14% | 80.47% / 83.92%; floors 78% / 75% | +| Chromium E2E | Earlier evidence on PR #24 | 13 passed, no retries | +| npm audit | Three high-severity vulnerable packages | Zero vulnerabilities reported | -The first Chromium launch was cold; all 13 cases passed without retries. The -runner emitted an environment warning because both `NO_COLOR` and `FORCE_COLOR` -were set. This affects terminal coloring, not browser behavior. +The local ZIP had 22 files and all manifest targets/16 relative runtime references; +tooling and legacy output were excluded. This is the historical package, not the +current release count. Added tests used real temporary Git histories and worker +listeners for menu/command/lifecycle/alarm/extraction branches. +Run current checks from [local validation](DEVELOPMENT.md#local-validation). ## Dependency decisions -All changes remain within existing dependency ranges, add no runtime cost or -bundle content, retain upstream licenses, and require no application migration. -Rollback restores the prior lockfile, including its known vulnerabilities. - -| Dependency | Before → after | Evidence | -| ----------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `brace-expansion` | 5.0.9 → 5.0.12 | [Expansion DoS advisory](https://github.com/advisories/GHSA-q2hr-2g5m-vwhr), [recursion advisory](https://github.com/advisories/GHSA-qhr7-859c-m2p7) | -| `source-map-js` | 1.2.1 → 1.2.2 | [Indexed source-map DoS advisory](https://github.com/advisories/GHSA-68fv-2mgg-jv7q) | -| `undici` | 7.29.0 → 7.30.1 | [TLS validation advisory](https://github.com/advisories/GHSA-w293-vg96-wgc3); the fresh npm audit also reported retry/WebSocket/cache advisories | - -## Changed files and operational notes - -| Files | Reason | -| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| `.github/workflows/ci.yml`, `.github/scripts/check-pr-base.mjs` | Base ancestry guard, read-only permissions, dependency audit, explicit ZIP inputs | -| `.gitignore`, `eslint.config.js` | Preserve and ignore legacy output; recognize the Node-based CI script | -| `package-lock.json` | Three security updates and root-version alignment with existing package/manifest version 5.2.0 | -| `tests/ci/pr-base.test.js`, `tests/integration/extension-workflow.test.js`, `vitest.config.js` | Regression cases and higher enforced branch floors | -| `CONTRIBUTING.md`, `docs/DEVELOPMENT.md`, `CHANGELOG.md`, this review | Accurate prerequisites, actual runtime contracts, integration and validation evidence | - -Run the commands in [the development guide](DEVELOPMENT.md#local-validation). -The ZIP packages runtime inputs explicitly; it must contain every manifest, -relative import, and HTML asset target. CI produces an Actions artifact, not a -published store release. No data migration is required. - -No performance benchmark, load/stress test, accessibility audit, Edge test, live -provider evaluation, or real toolbar-click smoke test was performed. Passing the -available automated checks does not establish those outcomes. - -Remaining feature work stays in existing issues: -[#16](https://github.com/aaron-seq/GenAI-Browser-Tool/issues/16) provider key verification, -[#17](https://github.com/aaron-seq/GenAI-Browser-Tool/issues/17) long-page task coverage, -[#18](https://github.com/aaron-seq/GenAI-Browser-Tool/issues/18) translation preferences, -[#19](https://github.com/aaron-seq/GenAI-Browser-Tool/issues/19) import, -[#20](https://github.com/aaron-seq/GenAI-Browser-Tool/issues/20) repository formatting, -and [#21](https://github.com/aaron-seq/GenAI-Browser-Tool/issues/21) persistent chat UI. +Compatible transitive updates retained licenses, added no runtime dependency, +and needed no application migration: + +- `brace-expansion` 5.0.9 → 5.0.12: + [expansion DoS](https://github.com/advisories/GHSA-q2hr-2g5m-vwhr) and + [recursion advisory](https://github.com/advisories/GHSA-qhr7-859c-m2p7). +- `source-map-js` 1.2.1 → 1.2.2: + [indexed source-map DoS](https://github.com/advisories/GHSA-68fv-2mgg-jv7q). +- `undici` 7.29.0 → 7.30.1: + [TLS validation advisory](https://github.com/advisories/GHSA-w293-vg96-wgc3); + npm also reported retry/WebSocket/cache advisories. + +Reverting restores the prior workflow/lockfile, including known vulnerabilities. +No benchmark, load test, accessibility audit, Edge/live-provider test, or real +toolbar-click check was performed. CI artifacts are not store publication. +Remaining product work is maintained in the [product brief](product/PRODUCT.md) +and [current checkpoint](product/PROJECT-STATUS.md). diff --git a/docs/SECURITY.md b/docs/SECURITY.md index e477101..dbf9fa3 100644 --- a/docs/SECURITY.md +++ b/docs/SECURITY.md @@ -2,299 +2,142 @@ ## Supported Versions -We actively support the following versions with security updates: +| Version | Supported with security updates | +| ------- | ------------------------------- | +| 5.3.x | Yes | +| 5.2.x | Yes | +| 5.1.x | Yes | +| <5.1 | No | -| Version | Supported | -| ------- | ------------------ | -| 5.3.x | :white_check_mark: | -| 5.2.x | :white_check_mark: | -| 5.1.x | :white_check_mark: | -| < 5.1 | :x: | - -Versions before 5.0 shipped stub AI providers and are not a supported -configuration. +Versions before 5.0 shipped stub AI providers and are not supported. ## Reporting a Vulnerability ### How to Report -If you discover a security vulnerability in GenAI Browser Tool, please report it responsibly: - -1. **DO NOT** create a public GitHub issue -2. **DO NOT** disclose the vulnerability publicly until it has been addressed -3. **DO** email security concerns directly to: aaronsequeira12@gmail.com -4. **DO** provide detailed information about the vulnerability +Email **aaronsequeira12@gmail.com**, subject +`[SECURITY] GenAI Browser Tool - [Brief Description]`. +Do not file a public issue or disclose the vulnerability before it is addressed. ### What to Include -When reporting a security vulnerability, please include: - -- **Description**: Clear description of the vulnerability -- **Impact**: Potential impact and severity assessment -- **Reproduction**: Step-by-step instructions to reproduce -- **Evidence**: Screenshots, logs, or proof of concept (if applicable) -- **Environment**: Browser version, extension version, operating system -- **Contact**: Your preferred method of communication for follow-up +Send the impact, reproduction steps, redacted evidence, browser/extension/OS +versions, and a way to follow up. Do not send keys or unrelated private page data. ### Response Timeline -- **Acknowledgment**: Within 48 hours of report -- **Initial Assessment**: Within 5 business days -- **Status Updates**: Weekly until resolution -- **Resolution**: Target 30 days for critical issues, 90 days for others +- Acknowledgment: within 48 hours. +- Initial assessment: within five business days. +- Status updates: weekly until resolution. +- Resolution targets: 30 days for critical issues, 90 days for others. ## Security Measures ### Content Security Policy -```json -{ - "content_security_policy": { - "extension_pages": "script-src 'self'; object-src 'self'" - } -} -``` - -Extension pages load no remote scripts and no remote stylesheets. Network access -is limited to the three provider hosts declared in `host_permissions`. +The [manifest](../manifest.json) sets +`script-src 'self'; object-src 'self'`. Extension pages load no remote scripts +or stylesheets. Provider hosts are explicitly declared in `host_permissions`. ### Input validation -- **Message validation** (`utils/validation-service.js`): every - `chrome.runtime` message must be an object carrying a non-empty string - `actionType` and a sender whose id is this extension's own, or it is rejected - before any work is done. An `actionType` that is well formed but unrecognised - is rejected by the router's `default` case, still before any work — the list - of valid actions lives in exactly one place rather than being mirrored here. -- **Input limits**: page/text documents are limited to 2,000,000 characters. - Chat selects at most six passages of 2,800 characters. Translation and other - single-request analyses clip context to 24,000 characters. Summaries can send - up to eight sections of 24,000 characters, followed by a merge request. -- **Question length cap**: 1,000 characters. This bounds token spend; it is not - a security boundary. - - There is deliberately **no content filter on questions**. An earlier version - rejected questions matching patterns like `/