rentgen/util.ts
am0 ffb37f9d61 feat/refactor: Chrome MV3 Support + Refaktoryzacja architektury dla kompatybilności obu przeglądarek
## 🎯 Cel
Dodanie pełnego wsparcia dla Chrome Manifest V3 przy zachowaniu kompatybilności z Firefox. Główne wyzwanie: Chrome MV3 używa service workerów zamiast persistent background pages, co wymaga nowej architektury zarządzania pamięcią.

---

## 🏗️ Architektura

### Nowa warstwa abstrakcji: lib/browser-api/

**lib/browser-api/index.ts**
- Główny punkt wejścia do zunifikowanego API
- Wybiera właściwą implementację na podstawie zmiennej TARGET (build-time)
- Eksportuje jeden interfejs dla całej aplikacji

**lib/browser-api/types.ts**
- Wspólne definicje typów dla obu przeglądarek
- Interfejs BrowserAPI definiujący wszystkie potrzebne metody
- Typy dla tabs, badge, webRequest, cookies, extension, windows

**lib/browser-api/firefox.ts**
- Adapter dla Firefox browser.* API
- Lazy access do globalnego obiektu browser (bezpieczne dla środowisk bez Firefox API)
- Wszystkie metody zwracają Promise lub są no-op jeśli API niedostępne

**lib/browser-api/chrome.ts**
- Adapter dla Chrome chrome.* API
- Mapowanie chrome.action → badge (różnica nazewnictwa)
- Ochrona przed błędami gdy karta zostaje zamknięta (try-catch w operacjach badge)

---

## 🔧 Build System

### esbuild.config.js
- **Dodano**: Rozpoznawanie zmiennej środowiskowej TARGET (firefox/chrome)
- **Dodano**: Różne katalogi wyjściowe (dist-firefox, dist-chrome)
- **Dodano**: Kopiowanie odpowiedniego manifestu na podstawie TARGET
- **Dodano**: Plugin do konwersji ikon SVG → PNG dla Chrome (wymaga PNG w MV3)
- **Zmieniono**: define zawiera teraz process.env.TARGET dostępny w runtime

### package.json
- **Dodano**: Skrypty build:firefox, build:chrome, watch:firefox, watch:chrome
- **Dodano**: Skrypty build-addon:firefox, build-addon:chrome do tworzenia paczek
- **Dodano**: Skrypt convert-icons do generowania PNG z SVG
- **Dodano**: Zależność sharp do konwersji obrazów

### scripts/convert-icons.js (NOWY PLIK)
- Konwertuje assets/icon-addon.svg → PNG w rozmiarach 16, 32, 48, 128px
- Wymagane dla Chrome (MV3 nie akceptuje SVG w manifestach)

### manifest-chrome.json (NOWY PLIK)
- Manifest V3 dla Chrome
- background.service_worker zamiast background.scripts
- action zamiast browser_action
- Ikony PNG zamiast SVG
- host_permissions zamiast embedowanych w permissions

---

## 🧠 Pamięć i Stan (NAJWIĘKSZA ZMIANA)

### memory.ts - Kompletna refaktoryzacja

**Problem Chrome MV3:**
- Service worker może być wyładowany w dowolnym momencie
- Brak dostępu do window.memory z popup/sidebar
- chrome.extension.getBackgroundPage() zwraca null w MV3

**Rozwiązanie:**
1. **Service Worker**: Trzyma pełne dane, synchronizuje do chrome.storage.session
2. **Popup/Sidebar**: Tworzy własną instancję Memory czytając z storage
3. **Throttled sync**: Maksymalnie co 500ms zapisy do storage (wydajność)

**Nowa klasa: CachedRequestCluster**
- Dziedziczy po RequestCluster ale NIE ma rzeczywistych requestów
- Przechowuje tylko metadane: hasCookies, exposesOrigin, hasMarks
- Implementuje wszystkie wymagane metody zwracając cached state
- Używana TYLKO w popup/report window w Chrome

**Zmiany w Memory klasie:**
- **Dodano**: isReady flag i readyPromise dla async inicjalizacji (Chrome)
- **Dodano**: waitUntilReady() - popup musi poczekać na załadowanie danych
- **Dodano**: tabUrls: Map<number, string> - tracking pełnych URL dla Chrome (service worker nie dostaje documentUrl)
- **Dodano**: scheduleSyncToStorage() - throttled sync do storage
- **Dodano**: syncToStorage() - serializacja clustrów do JSON
- **Dodano**: loadFromStorage() - deserializacja przy starcie popup
- **Zmieniono**: register() śledzi main_frame URL i synuje po każdej zmianie
- **Zmieniono**: Badge operacje w try-catch (karta może być zamknięta)

**Funkcja getMemory():**
- **Firefox**: browserAPI.extension.getBackgroundPage().memory (tradycyjnie)
- **Chrome Service Worker**: self.memory (jesteśmy W service workerze)
- **Chrome Popup**: Tworzy NOWĄ instancję czytając z storage (cachowana jako popupMemoryInstance)

---

## 🔒 Bezpieczeństwo i Obsługa Błędów

### util.ts - getshorthost()
- **Dodano**: Walidacja wejścia (null, undefined, pusty string)
- **Dodano**: Czyszczenie URL (protokół, ścieżka, port)
- **Dodano**: Obsługa edge cases (localhost, single word domains)
- **Dodano**: Bezpieczne fallbacki zamiast crashowania
- **Dodano**: Console.warn zamiast milczących błędów

### extended-request.ts
- **MASYWNE POPRAWKI** parsowania URL w konstruktorze
- **Dodano**: isValidHttpUrl() helper - sprawdza czy URL zaczyna się od http(s)
- **Dodano**: safeParseUrl() helper - try-catch wokół new URL()
- **Dodano**: Próba parsowania wielu URL w kolejności priorytetów
- **Dodano**: Obsługa Chrome MV3 initiator property
- **Dodano**: Bezpieczne defaulty gdy parsowanie się nie uda (unknown://unknown)
- **Zmieniono**: isThirdParty() pomija requesty z unparseable URLs
- **Dodano**: uint8ArrayToString() - chunked konwersja dużych arrayów (zapobiega stack overflow)
- **Zmieniono**: Request body processing używa chunked konwersji

---

## 🎨 UI Components

### toolbar.tsx (popup)
- **Dodano**: getCurrentTab() z retry mechanism (Chrome czasem nie zwraca karty od razu)
- **Dodano**: Sprawdzanie memoryReady przed renderowaniem danych
- **Dodano**: Wywołanie waitUntilReady() w useEffect
- **Dodano**: Opóźnienie 200ms dla Chrome przy inicjalizacji (service worker + storage delay)
- **Dodano**: Graceful handling gdy popup otwarty bez active tab

### sidebar.tsx
- **Dodano**: Stan memoryReady i loading screen dla Chrome
- **Dodano**: Wywołanie waitUntilReady() przed dostępem do danych
- **Dodano**: Conditional rendering - pokazuje Ładowanie... gdy pamięć nie gotowa

### report-window.tsx
- **Dodano**: Stan memoryReady i loading message
- **Dodano**: Wywołanie waitUntilReady() przed generowaniem raportu
- **Dodano**: Fallback konstruowania URL z origin gdy brak visited_url
- **Zmieniono**: Filtr clustrów używa hasMarks() zamiast getMarkedRequests().length

### stolen-data-cluster.tsx
- **Bez znaczących zmian** - działa z abstrakcją RequestCluster

---

## 🐛 Poprawki Bugów

### background.ts
- **Dodano**: Diagnostic logging do debugowania inicjalizacji
- **Dodano**: Try-catch wokół init() z error logging
- **Dodano**: Różne logi dla Firefox vs Chrome

### memory.ts - badge operations
- **Dodano**: Try-catch wokół wszystkich operacji badge
- Zapobiega crashowaniu gdy użytkownik zamknie kartę podczas operacji

### chrome.ts - badge adapter
- **Dodano**: Try-catch w setBadgeText, setTitle, setBadgeBackgroundColor
- Chrome rzuca błędy gdy operujemy na zamkniętych kartach

---

## 📝 Workflow Użytkownika (Chrome)

1. **Użytkownik odwiedza stronę** → Service worker rejestruje requesty → Auto-mark podejrzanych → Sync do storage
2. **Użytkownik otwiera popup** → Tworzy Memory → Czyta ze storage → Pokazuje dane z flagami
3. **Użytkownik (od)zaznacza domeny** → Zmienia flagi → Sync do storage
4. **Użytkownik generuje raport** → Otwiera report-window → Czyta ze storage → Filtruje według hasMarks()

---

##  Rezultat

-  **Firefox**: Działa jak wcześniej (background page + window.memory)
-  **Chrome**: Pełne wsparcie MV3 (service worker + storage.session)
-  **Wspólny kod**: 95% kodu jest shared, tylko warstwa dostępu do API różni się
-  **Bezpieczeństwo**: Obsługa wszystkich edge cases w parsowaniu URL
-  **Wydajność**: Throttled sync do storage (max co 500ms)
-  **UX**: Loading states w popup/sidebar dla Chrome
-  **Build**: npm run build-addon:firefox lub npm build-addon dla firefox / npm run build:chrome dla chrome
2025-10-18 13:08:14 +02:00

350 lines
11 KiB
TypeScript

import { EventEmitter } from 'events';
import React from 'react';
import { DataLocation, Sources } from './stolen-data-entry';
import browserAPI from './lib/browser-api';
export type Unpromisify<T> = T extends Promise<infer R> ? R : T;
export type Unarray<T> = T extends Array<infer R> ? R : T;
export type Tab = Unarray<Unpromisify<ReturnType<typeof browserAPI.tabs.query>>>;
export type Request = {
cookieStoreId?: string;
documentUrl?: string; // RL of the document in which the resource will be loaded. For example, if the web page at "https://example.com" contains an image or an iframe, then the documentUrl for the image or iframe will be "https://example.com". For a top-level document, documentUrl is undefined.
frameId: number;
incognito?: boolean;
method: string;
originUrl: string;
parentFrameId: number;
proxyInfo?: {
host: string;
port: number;
type: string;
username: string;
proxyDNS: boolean;
failoverTimeout: number;
};
requestHeaders?: { name: string; value?: string; binaryValue?: number[] }[];
requestId: string;
tabId: number;
thirdParty?: boolean;
timeStamp: number;
type: string;
url: string; // the target of the request;
urlClassification?: { firstParty: string[]; thirdParty: string[] };
};
export function getshorthost(host: string) {
// Obsługa przypadków brzegowych
if (!host || typeof host !== 'string') {
console.warn('getshorthost: nieprawidłowy host:', host);
return 'unknown';
}
// Czyszczenie stringa hosta
const cleanHost = host
.replace(/^.*:\/\//, '') // Usunięcie protokołu
.replace(/\/.*$/, '') // Usunięcie ścieżki
.replace(/:\d+$/, ''); // Usunięcie portu
const parts = cleanHost.split('.');
// Obsługa przypadków specjalnych
if (parts.length === 0 || !cleanHost) {
console.warn('getshorthost: pusty host po czyszczeniu');
return 'unknown';
}
if (parts.length === 1) {
// Pojedyncze słowo jak "localhost" lub "unknown"
return parts[0];
}
const second_last = parts.at(-2);
// Bezpieczny fallback jeśli wciąż nieprawidłowy
if (!second_last) {
console.warn('getshorthost: nie można określić domeny dla:', host);
return cleanHost; // Zwracamy jak jest zamiast crashować
}
let lookback = !['co', 'com'].includes(second_last) ? -2 : -3;
if (parts.at(-2) == 'doubleclick' || parts.at(-2) == 'google') {
lookback = -4; // aby rozróżnić google ads i stats
} else if (parts.at(-2) == 'google') {
lookback = -3; // aby rozróżnić różne usługi google
}
// Upewnienie się, że nie wycinamy poza granice tablicy
const sliceStart = Math.max(0, parts.length + lookback);
return parts.slice(sliceStart).join('.');
}
export function useEmitter(
e: EventEmitter
): [
Record<string, number | undefined>,
React.Dispatch<React.SetStateAction<Record<string, number | undefined>>>
] {
const [eventCounts, setEventCounts] = React.useState<Record<string, number | undefined>>({
'*': 0,
});
React.useEffect(() => {
const callback = (eventSubtype: string) => {
setEventCounts((eventCounts) => ({
...eventCounts,
...{ [eventSubtype]: (eventCounts[eventSubtype] || 0) + 1 },
...{ '*': (eventCounts['*'] === undefined ? 0 : eventCounts['*']) + 1 },
}));
};
e.on('change', callback);
return () => {
e.removeListener('change', callback);
};
}, []);
return [eventCounts, setEventCounts];
}
export function parseCookie(cookie: string): Record<string, string> {
return cookie
.split(';')
.map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)])
.reduce(
(acc, [key, value]) => ({
...acc,
[key]: value,
}),
{}
);
}
export async function getTabByID(id: number) {
const tabs = await browserAPI.tabs.query({ currentWindow: true });
return tabs.find((tab) => tab.id == id);
}
export function parseToObject(str: unknown): Record<string | symbol, unknown> {
let result: Record<string | symbol, unknown> = {};
let original_string: string;
if (typeof str === 'string') {
original_string = str;
result = JSON.parse(str);
} else if (typeof str == 'object') {
result = str as Record<string | symbol, unknown>;
original_string = (result[Symbol.for('originalString')] as string) || JSON.stringify(str);
} else {
return result;
}
result[Symbol.for('originalString')] = original_string;
return result;
}
export function isJSONObject(str: unknown): str is Record<string, unknown> | string | number {
try {
const firstChar = JSON.stringify(parseToObject(str))[0];
return ['{', '['].includes(firstChar);
} catch (e) {
return false;
}
}
export function isURL(str: unknown): str is string {
try {
return !!(typeof str === 'string' && new URL(str));
} catch (e) {
return false;
}
}
export function hyphenate(str: string): string {
return str.replace(/[_\[A-Z]/g, `${String.fromCharCode(173)}$&`);
}
export function unique<T>(array: T[]): Array<T> {
return Array.from(new Set<T>(array));
}
export function allSubhosts(host: string) {
const parts = host.split('.');
const result = [];
for (let i = 0; i < parts.length - 2; i++) {
result.push(parts.slice(i).join('.'));
}
return result;
}
export function reduceConcat<T>(a: T[], b: T[]): T[] {
return a.concat(b);
}
export function getDate() {
const d = new Date();
return `${d.getFullYear()}-${(d.getMonth() + 1).toString().padStart(2, '0')}-${d
.getDate()
.toString()
.padStart(2, '0')}`;
}
export function toBase64(file: File): Promise<string> {
return new Promise((resolve, reject) => {
const FR = new FileReader();
FR.addEventListener('load', (e) => {
const target = e.target;
if (!target) {
return reject('File missing?');
}
resolve(e.target.result as string);
});
FR.readAsDataURL(file);
});
}
export function makeThrottle(interval: number) {
let last_emit = 0;
function emit(callback: () => void) {
if (Date.now() - last_emit > interval) {
callback();
last_emit = Date.now();
return true;
} else {
return false;
}
}
return function (callback: () => void) {
if (!emit(callback)) {
setTimeout(() => emit(callback), interval);
}
};
}
export function isSameURL(url1: string, url2: string): boolean {
if (url1 === url2) {
return true;
}
url1 = url1.replace(/^https?:\/\//, '').replace(/\/$/, '');
url2 = url2.replace(/^https?:\/\//, '').replace(/\/$/, '');
return url1 === url2;
}
export function isBase64(s: string): boolean {
try {
atob(s);
return true;
} catch (e) {}
return false;
}
export function isBase64JSON(s: unknown): s is string {
return typeof s === 'string' && isBase64(s) && isJSONObject(atob(s));
}
export function flattenObject(
obj: unknown,
parser: (to_parse: { toString: () => string }) => string | Record<string, unknown> = (id) =>
id.toString(),
key = '',
ret = [] as [string, string][],
parsed = false
): [string, string][] {
const prefix = key === '' ? '' : `${key}.`;
if (Array.isArray(obj)) {
if (obj.length == 1) {
flattenObject(obj[0], parser, key, ret);
} else {
for (let i in obj) {
flattenObject(obj[i], parser, prefix + i, ret);
}
}
} else if (obj === null) {
ret.push([key, '']);
} else if (typeof obj === 'object') {
for (const [subkey, value] of Object.entries(obj)) {
flattenObject(value, parser, prefix + subkey, ret);
}
} else if (!parsed) {
try {
flattenObject(parser(obj as { toString: () => string }), parser, key, ret, true);
} catch (e) {
//emergency case, mostly for just type safety
ret.push([key, JSON.stringify(obj)]);
}
} else if (typeof obj === 'string') {
ret.push([key, obj]);
} else {
throw new Error('Something went wrong when parsing ' + obj);
}
return ret;
}
export function flattenObjectEntries(
entries: [string, unknown][],
parser: (to_parse: { toString: () => string }) => string | Record<string, unknown> = (id) =>
id.toString()
): [string, string][] {
return flattenObject(Object.fromEntries(entries), parser);
}
export function maskString(
str: string,
max_fraction_remaining: number,
max_chars_total: number
): string {
const amount_of_chars_to_cut =
str.length - Math.min(str.length * max_fraction_remaining, max_chars_total);
if (amount_of_chars_to_cut == 0) {
return str;
}
return (
str.slice(0, str.length / 2 - amount_of_chars_to_cut / 2) +
'(...)' +
str.slice(str.length / 2 + amount_of_chars_to_cut / 2)
);
}
export function safeDecodeURIComponent(s: string) {
try {
return decodeURIComponent(s);
} catch (e) {
return s;
}
}
export function normalizeForClassname(string: string) {
return string.replace(/[^a-z0-9]/gi, '-');
}
export function wordlist(words: string[]) {
return Array.from(new Set(words)).reduce(
(acc, word, i) =>
`${acc}${
i > 0 ? (i < words.length - 1 ? ', ' : Math.random() > 0.5 ? ' i ' : ' oraz ') : ''
}${word}`,
''
);
}
const source_to_word: Record<Sources, string> = {
cookie: 'plik cookie o nazwie',
pathname: 'fragment ścieżki w URL',
queryparams: 'query params w URL o nazwie',
header: 'nagłówek HTTP',
request_body: 'body zapytania HTTP, pod kluczem',
};
export function dataLocationToText(l: DataLocation) {
return `${source_to_word[l.source]} ${l.key}`;
}
export function downloadText(filename: string, text: string) {
// https://stackoverflow.com/questions/45831191/generate-and-download-file-from-js
var element = document.createElement('a');
element.setAttribute('href', 'data:text/plain;charset=utf-8,' + encodeURIComponent(text));
element.setAttribute('download', filename);
element.style.display = 'none';
document.body.appendChild(element);
element.click();
document.body.removeChild(element);
}