forked from icd/rentgen
chore: dodaj wsparcie Docker i dokumentację Claude Code
- Dodano Dockerfile z multi-stage build (artifacts + dev environment) - Dodano .dockerignore dla optymalizacji budowania - Dodano CLAUDE.md z dokumentacją architektury i workflow dla Claude Code 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
root
parent
cf94d45ee1
commit
6c1df64b40
16
.dockerignore
Normal file
16
.dockerignore
Normal file
@ -0,0 +1,16 @@
|
||||
.log
|
||||
node_modules
|
||||
sidebar.js
|
||||
web-ext-artifacts/
|
||||
lib/*
|
||||
yarn-error.log
|
||||
rentgen.zip
|
||||
|
||||
# Generated PNG icons (build artifacts)
|
||||
assets/icons/*.png
|
||||
assets/icon-addon-*.png
|
||||
|
||||
# Exception: do not ignore the `browser-api` directory inside `lib`
|
||||
!/lib/browser-api/
|
||||
|
||||
Dockerfile
|
||||
250
CLAUDE.md
Normal file
250
CLAUDE.md
Normal file
@ -0,0 +1,250 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Rentgen** is a privacy-focused browser extension for Firefox and Chrome that intercepts web traffic, identifies third-party tracking, and visualizes stolen data (cookies, browsing history, etc.). It generates GDPR-compliant reports and email templates for Polish website administrators and the Personal Data Protection Office.
|
||||
|
||||
**Language Note**: The codebase is in English, but the extension UI and generated reports are in Polish. Comments and documentation may be bilingual.
|
||||
|
||||
## Build & Development Commands
|
||||
|
||||
### Standard Build Workflow
|
||||
```bash
|
||||
npm install # Install dependencies
|
||||
npm run build # Build for Firefox (default)
|
||||
npm run build:firefox # Build for Firefox explicitly
|
||||
npm run build:chrome # Build for Chrome
|
||||
npm run create-package # Package into web-ext-artifacts/ directory
|
||||
npm run build-addon # Complete build: install + build + package
|
||||
```
|
||||
|
||||
### Development Workflow
|
||||
```bash
|
||||
npm run watch # Watch mode - auto-rebuild on file changes
|
||||
npm run watch:firefox # Watch for Firefox
|
||||
npm run watch:chrome # Watch for Chrome
|
||||
npm run ext-test # Run extension in temporary Firefox profile (web-ext run)
|
||||
```
|
||||
|
||||
### Quality Checks
|
||||
```bash
|
||||
npm run typecheck # Run TypeScript type checking (tsc --noEmit)
|
||||
npm run lint # Lint extension with web-ext lint
|
||||
```
|
||||
|
||||
### Testing in Browser
|
||||
After building, load the temporary add-on:
|
||||
1. Firefox: Navigate to `about:debugging` → This Firefox → Load Temporary Add-on
|
||||
2. Chrome: Navigate to `chrome://extensions/` → Enable Developer Mode → Load unpacked
|
||||
|
||||
**Note**: There are no automated test suites in this codebase. Testing is manual via browser extension loading.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Core Pattern: Event-Driven Singleton with Observer Pattern
|
||||
|
||||
Rentgen uses a centralized **Memory** singleton (background script) that:
|
||||
- Intercepts all HTTP requests via `webRequest` API
|
||||
- Maintains hierarchical data structure: `origin → shorthost → RequestCluster → StolenDataEntry`
|
||||
- Emits `'change'` events when data updates
|
||||
- Drives UI re-renders in React components via custom `useEmitter` hook
|
||||
|
||||
### Key Components
|
||||
|
||||
#### Background Service (`background.ts` + `memory.ts`)
|
||||
- **Memory class** (extends SaferEmitter): Central orchestrator managing all extension state
|
||||
- Listens to `webRequest.onBeforeRequest` and `webRequest.onBeforeSendHeaders`
|
||||
- Maintains `clusters` map: `origin → Map<shorthost, RequestCluster>`
|
||||
- Emits `'change'` events to notify UI components
|
||||
- Updates browser badge with domain count and color indicators
|
||||
- Accessible globally via `getMemory()` singleton
|
||||
|
||||
#### Network Interception Layer
|
||||
- **ExtendedRequest class** (`extended-request.ts`): Wraps individual HTTP requests
|
||||
- Static registry: `ExtendedRequest.by_id[requestId]` for fast lookup
|
||||
- Two-phase initialization: constructor (body) + `init()` method (headers)
|
||||
- Detects third-party requests by comparing origins
|
||||
- Extracts "stolen data" from: cookies, query params, pathname, headers, request body
|
||||
- Generates HAR (HTTP Archive) format for reports
|
||||
- Calculates priority scores based on data sensitivity
|
||||
|
||||
- **RequestCluster class** (`request-cluster.ts`): Groups requests by `origin + shorthost`
|
||||
- Aggregates StolenDataEntry items with deduplication
|
||||
- Tracks expanded/collapsed state for UI
|
||||
- Auto-marks suspicious entries (history exposure, tracking IDs)
|
||||
- Emits `'change'` events on modifications
|
||||
|
||||
#### Data Classification
|
||||
- **StolenDataEntry class** (`stolen-data-entry.ts`): Individual data points
|
||||
- Sources: `cookie`, `pathname`, `queryparams`, `header`, `request_body`
|
||||
- Classifications: `id` (tracking ID), `history` (browsing history), `location` (geolocation)
|
||||
- Smart value parsing: recursively decodes Base64, JSON, URLs, nested structures
|
||||
- Priority calculation: combines value length, origin exposure, data type
|
||||
- Mark/unmark system for user selection in reports
|
||||
|
||||
#### Browser API Abstraction (`lib/browser-api/`)
|
||||
- **Cross-browser compatibility layer** selected at build time via `TARGET` env var
|
||||
- `types.ts`: Unified interface for tabs, badge, webRequest, cookies APIs
|
||||
- `index.ts`: Exports Chrome or Firefox implementation based on `process.env.TARGET`
|
||||
- Standardizes differences (e.g., `browserAction` vs `action`)
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
HTTP Request Initiated
|
||||
↓
|
||||
Memory.onBeforeRequest → Create ExtendedRequest (capture body)
|
||||
↓
|
||||
Memory.onBeforeSendHeaders → ExtendedRequest.init() (capture headers)
|
||||
↓
|
||||
Extract stolen data (cookies, params, headers, body)
|
||||
↓
|
||||
Memory.register() → Check if third-party → Add to RequestCluster
|
||||
↓
|
||||
Memory.emit('change', shorthost) → Broadcast event
|
||||
↓
|
||||
React components (via useEmitter hook) → UI re-renders
|
||||
```
|
||||
|
||||
### UI Components
|
||||
|
||||
#### Sidebar (`components/sidebar/`)
|
||||
- **sidebar.tsx**: Main extension UI listing third-party domains
|
||||
- **stolen-data.tsx**: Renders RequestClusters with filtering options
|
||||
- **stolen-data-cluster.tsx**: Expandable cluster showing individual StolenDataEntry items
|
||||
- Filters: `minValueLength`, `cookiesOnly`, `cookiesOrOriginOnly`
|
||||
- Real-time updates via `useEmitter(Memory)` hook
|
||||
|
||||
#### Report Window (`components/report-window/`)
|
||||
- Multi-stage report generation workflow:
|
||||
1. **Survey**: User questionnaire (role, tone, gender pronouns) via `survey-react`
|
||||
2. **Screenshot**: External service generates domain screenshots
|
||||
3. **Preview**: Final email/report content with GDPR violation analysis
|
||||
- **deduce-problems.tsx**: Analyzes survey answers to identify GDPR violations
|
||||
- **har-converter.tsx**: Generates filtered HAR archives
|
||||
- **email-content.tsx**: Renders Polish email template (polite or harsh tone)
|
||||
|
||||
#### Toolbar (`components/toolbar/`)
|
||||
- Browser action popup (top-right icon)
|
||||
|
||||
### Build System
|
||||
|
||||
- **esbuild** (`esbuild.config.js`): TypeScript → JavaScript bundler
|
||||
- Entry points: toolbar.tsx, sidebar.tsx, report-window.tsx, background.ts, diag.tsx, styles
|
||||
- External React libs loaded via globals (`globalThis.React`, `globalThis.ReactDOM`)
|
||||
- SCSS plugin for styling
|
||||
- Define flags: `PLUGIN_NAME`, `PLUGIN_URL`
|
||||
- Watch mode available for development
|
||||
|
||||
- **Target Selection**: Set `TARGET=firefox` or `TARGET=chrome` before build to select browser API implementation
|
||||
|
||||
- **Manifest**: Currently uses Manifest V2 (Firefox). Chrome support is partial and being expanded.
|
||||
|
||||
## Important Implementation Details
|
||||
|
||||
### Third-Party Detection Heuristics
|
||||
When determining if a request is third-party (in `extended-request.ts`):
|
||||
1. Compare request origin with tab origin
|
||||
2. Check `documentUrl` and `originUrl` from webRequest details
|
||||
3. Use `urlClassification.thirdParty` if available
|
||||
4. Analyze `frameAncestors` for nested iframe scenarios
|
||||
5. Fall back to comparing hostnames
|
||||
|
||||
### Stolen Data Extraction Strategy
|
||||
Data is extracted from multiple sources (priority order):
|
||||
1. **Cookies**: Via `browser.cookies.getAll()`
|
||||
2. **Query Parameters**: Parsed from URL search string
|
||||
3. **Pathname**: URL path segments
|
||||
4. **Headers**: Request headers (Cookie, Referer, etc.)
|
||||
5. **Request Body**: POST/PUT data (form data, JSON)
|
||||
|
||||
### Value Parsing Chain
|
||||
`StolenDataEntry` recursively decodes values:
|
||||
1. Detect Base64 encoding → decode
|
||||
2. Detect URL encoding → decode
|
||||
3. Detect JSON → parse
|
||||
4. Detect nested URLs → extract
|
||||
5. Stop at maximum recursion depth
|
||||
|
||||
### Auto-Marking Rules
|
||||
RequestClusters automatically mark entries as suspicious if:
|
||||
- Value exposes browsing history (referrer, path info)
|
||||
- Cookie length > 100 characters
|
||||
- Known trackers: Google Analytics, Facebook, DoubleClick, etc.
|
||||
- Classified as `id` or `history` type
|
||||
|
||||
### Event System
|
||||
- **SaferEmitter** (`safer-emitter.ts`): EventEmitter wrapper with async emission
|
||||
- Uses `setTimeout(..., 0)` to decouple events from synchronous request handling
|
||||
- Prevents errors in listeners from breaking request flow
|
||||
- **useEmitter Hook** (`components/sidebar/sidebar.tsx`): React integration
|
||||
- Increments counter state on each event to trigger re-renders
|
||||
- Automatically subscribes/unsubscribes via `useEffect`
|
||||
|
||||
## Common Development Tasks
|
||||
|
||||
### Adding a New Data Source
|
||||
1. Add extraction logic to `ExtendedRequest.getAllData()` in `extended-request.ts`
|
||||
2. Define new source type in `StolenDataEntry.sources` in `stolen-data-entry.ts`
|
||||
3. Update classification logic in `StolenDataEntry.getClassification()`
|
||||
4. Update UI components to display the new source (if needed)
|
||||
|
||||
### Supporting a New Browser
|
||||
1. Create implementation in `lib/browser-api/` (e.g., `safari.ts`)
|
||||
2. Update `lib/browser-api/index.ts` to export based on `TARGET` env var
|
||||
3. Add corresponding npm scripts in `package.json` (`build:safari`, etc.)
|
||||
4. Test browser-specific APIs for compatibility
|
||||
|
||||
### Modifying Report Templates
|
||||
- **Email templates**: `email-template-polite.js`, `email-template-harsh.js`
|
||||
- **Problem deduction**: `components/report-window/deduce-problems.tsx`
|
||||
- **Survey questions**: `components/report-window/questions.tsx`
|
||||
- Templates are in Polish and follow GDPR complaint structure
|
||||
|
||||
### Debugging Request Interception
|
||||
- Check `ExtendedRequest.by_id` registry for request lookup issues
|
||||
- Verify `Memory.clusters` structure for data organization
|
||||
- Use browser DevTools → Extensions → Background Page for logging
|
||||
- Enable `console.log` in `memory.ts` event listeners
|
||||
|
||||
## Project Constraints
|
||||
|
||||
- **No automated tests**: Manual testing only via browser extension loading
|
||||
- **Polish language**: UI and reports are Polish-focused (English i18n is future work)
|
||||
- **Manifest V2**: Primary target is Firefox; Chrome V3 migration is in progress
|
||||
- **External screenshot service**: Report generation depends on external API
|
||||
- **No minification**: Currently disabled in esbuild config (commented out)
|
||||
- **Node.js 16.x requirement**: Specified in README
|
||||
|
||||
## Repository Information
|
||||
|
||||
- **Primary Repository**: https://git.internet-czas-dzialac.pl/icd/rentgen (Gitea)
|
||||
- **Mirror**: GitHub (issues not accepted there)
|
||||
- **Issue Tracking**: Email kontakt@internet-czas-dzialac.pl
|
||||
- **License**: GPL-3.0-or-later
|
||||
- **Authors**: Kuba Orlik, Arkadiusz Wieczorek (Internet. Time to act! Foundation)
|
||||
|
||||
## File Organization
|
||||
|
||||
```
|
||||
rentgen/
|
||||
├── background.ts # Extension entry point
|
||||
├── memory.ts # Central state manager (Memory singleton)
|
||||
├── extended-request.ts # HTTP request wrapper and data extraction
|
||||
├── request-cluster.ts # Request aggregation by domain
|
||||
├── stolen-data-entry.ts # Individual data point representation
|
||||
├── safer-emitter.ts # EventEmitter wrapper
|
||||
├── util.ts # Utility functions
|
||||
├── components/
|
||||
│ ├── sidebar/ # Main extension UI
|
||||
│ ├── toolbar/ # Browser action popup
|
||||
│ └── report-window/ # Report generation workflow
|
||||
├── lib/
|
||||
│ └── browser-api/ # Cross-browser API abstraction
|
||||
├── email-template-*.js # Polish email templates
|
||||
├── esbuild.config.js # Build configuration
|
||||
├── manifest.json # Extension manifest (V2)
|
||||
└── assets/ # Icons and screenshots
|
||||
```
|
||||
45
Dockerfile
Normal file
45
Dockerfile
Normal file
@ -0,0 +1,45 @@
|
||||
# Rentgen Browser Extension - Docker Build
|
||||
#
|
||||
# Usage:
|
||||
# Build and extract artifacts directly:
|
||||
# docker buildx build . --output artifacts
|
||||
#
|
||||
# Or traditional build (creates full development environment):
|
||||
# docker build -t rentgen .
|
||||
# docker run --rm rentgen ls -lh /app/web-ext-artifacts/
|
||||
#
|
||||
# Run commands in the container:
|
||||
# docker run --rm rentgen npm run build:chrome
|
||||
# docker run --rm rentgen npm run typecheck
|
||||
|
||||
# Build stage
|
||||
FROM node:lts AS builder
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Copy package files for dependency installation (better layer caching)
|
||||
COPY package.json package-lock.json ./
|
||||
|
||||
# Install dependencies
|
||||
RUN npm install
|
||||
|
||||
# Copy source code (respecting .dockerignore)
|
||||
COPY . .
|
||||
|
||||
# Build the extension for Firefox (default)
|
||||
RUN npm run build
|
||||
|
||||
# Create the package
|
||||
RUN npm run create-package
|
||||
|
||||
# Artifacts stage - only contains the built artifacts (for --output)
|
||||
FROM scratch AS artifacts
|
||||
|
||||
# Copy only the built extension zip file to root
|
||||
COPY --from=builder /app/web-ext-artifacts/*.zip /
|
||||
|
||||
# Default stage - full development environment
|
||||
FROM builder
|
||||
|
||||
# Default command shows the built artifact
|
||||
CMD ["ls", "-lh", "/app/web-ext-artifacts/"]
|
||||
Loading…
x
Reference in New Issue
Block a user