Finalize ConspiracyAlert extension artifact

.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  extension:
+    name: Extension client
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: client/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: client
+
+      - name: Audit dependencies
+        run: npm audit --audit-level=moderate
+        working-directory: client
+
+      - name: Run unit tests
+        run: npm test
+        working-directory: client
+
+      - name: Run TypeScript checks
+        run: npm run check
+        working-directory: client
+
+      - name: Build extension
+        run: npm run build
+        working-directory: client
+
+      - name: Package extension
+        run: npm run package
+        working-directory: client
+
+      - name: Upload extension package
+        uses: actions/upload-artifact@v7
+        with:
+          name: conspiracy-alert-plugin
+          path: client/release/*.zip
+
+      - name: Install Playwright browser
+        run: npx playwright install --with-deps chromium
+        working-directory: client
+
+      - name: Run extension E2E tests
+        run: xvfb-run -a npm run test:e2e
+        working-directory: client

ARTIFACT.md

@@ -0,0 +1,153 @@
+# Paper Artifact Guide
+
+This guide is the shortest path for an external reviewer to run the browser extension client for
+the paper artifact.
+
+## Scope
+
+This repository contains the Chrome/Chromium extension client. It does not embed the public
+datasets and does not reimplement the backend. The extension calls the FastAPI service from
+`channel-checker-bot` and displays:
+
+- a toolbar popup for the active tab;
+- a manual `Check now` action;
+- an optional in-page banner when the current page URL matches a dataset or monetization signal;
+- a per-tab badge for matched pages or backend errors.
+
+## Paper Alignment
+
+The paper describes ConspiracyAlert as a Chrome TypeScript browser plug-in that observes web
+navigation, sends the loaded page URL to a remote server, checks it against the Conspiracy Resource
+Dataset and URL dataset, and displays an informative warning when a match exists.
+
+This artifact implements that workflow as a Manifest V3 extension:
+
+- the content script evaluates the loaded page URL through the background worker;
+- the background worker calls the shared Channel Checker backend;
+- matched pages show an in-page warning banner and toolbar badge;
+- the popup lets users inspect the current tab status and run a manual `Check now`;
+- automatic in-page checks can be disabled from the options page;
+- extension storage is limited to configuration and the latest tab evaluation state.
+
+The extension intentionally does not ship the datasets or a separate Flask server. Matching stays
+in the backend so the browser artifact remains small and privacy boundaries are easier to audit.
+
+Related repositories:
+
+- `channel-checker-bot`: backend API and optional Telegram bot;
+- `conspiracy-dataset-telegram`: public CSV datasets consumed by the backend.
+
+## Prerequisites
+
+- Chrome or Chromium with extension developer mode available;
+- Node.js 24 with npm;
+- the backend running at `http://127.0.0.1:8000`;
+- the expected sibling checkout layout:
+
+```text
+SystemsLab-Sapienza/
+  channel-checker-bot/
+  conspiracy-dataset-telegram/
+  conspiracy-alert-plugin/
+```
+
+## Start The Backend
+
+From `channel-checker-bot`:
+
+```bash
+docker build -t channel-checker-bot:local .
+docker run --rm \
+  -p 8000:8000 \
+  -e CHANNEL_CHECKER_DATASET_DIR=/data \
+  -v "$(pwd)/../conspiracy-dataset-telegram:/data:ro" \
+  channel-checker-bot:local
+```
+
+Verify it:
+
+```bash
+curl -s http://127.0.0.1:8000/health
+curl -s -X POST http://127.0.0.1:8000/v1/evaluate-url \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://8kun.top/qresearch/catalog.html"}'
+```
+
+The first command should return `{"status":"ok","version":"0.1.0"}`. The second should return a
+matched result.
+
+## Build And Load The Extension
+
+From `conspiracy-alert-plugin/client`:
+
+```bash
+npm ci
+npm run build
+```
+
+Then:
+
+1. Open `chrome://extensions/`.
+2. Enable Developer mode.
+3. Click `Load unpacked`.
+4. Select `conspiracy-alert-plugin/client/dist`.
+5. Open the extension options page and confirm the backend URL is `http://127.0.0.1:8000`.
+
+## Manual Smoke Test
+
+With the backend running and the extension loaded:
+
+1. Open `https://www.amazon.com/?tag=example-20`.
+2. Wait for the page to finish loading.
+3. The extension should show a non-blocking in-page banner for monetization signals.
+4. The toolbar popup should show the current tab status.
+5. Disable automatic page checks in the extension options page.
+6. Reload the page and confirm the banner does not appear automatically.
+7. Use `Check now` in the popup to run a manual check.
+
+This smoke test uses a monetization signal because it does not depend on any third-party page from
+the public dataset being reachable during review.
+
+## Package Artifact
+
+```bash
+npm run package
+```
+
+The ZIP is written to `client/release/conspiracy-alert-plugin-1.0.0.zip` and contains the built
+extension files from `client/dist`.
+
+## Verification Commands
+
+```bash
+npm run check
+npm test
+npm run build
+npm run package
+npm run check:api-types
+npm run test:e2e
+```
+
+CI installs dependencies with `npm ci`, audits dependencies at moderate severity, runs TypeScript
+checks, unit tests, production build, package creation, and Playwright extension E2E tests.
+
+`npm run check:api-types` regenerates the backend OpenAPI schema from the sibling
+`channel-checker-bot` checkout and verifies that generated frontend types are current.
+
+## Privacy And Storage
+
+The extension stores only configuration and the latest evaluation state needed for the active tab.
+It does not store browsing history, raw page content, Telegram data, or dataset contents. The
+backend performs all matching.
+
+## Troubleshooting
+
+- `?` badge: backend unavailable or returned an error. Check `http://127.0.0.1:8000/health`.
+- No in-page banner: automatic checks may be disabled, the page URL may have no signal, or the
+  backend may not be running.
+- Custom backend URL: set it from the options page. The extension may request additional host
+  permission for non-default origins.
+
+## License
+
+This software artifact is released under the MIT License. See [LICENSE](LICENSE).

CITATION.cff

@@ -0,0 +1,34 @@
+cff-version: 1.2.0
+message: "If you use this artifact, please cite the associated paper."
+title: "Conspiracy Alert Plugin"
+type: software
+authors:
+  - family-names: "Imperati"
+    given-names: "Vincenzo"
+  - family-names: "La Morgia"
+    given-names: "Massimo"
+  - family-names: "Mei"
+    given-names: "Alessandro"
+  - family-names: "Mongardini"
+    given-names: "Alberto Maria"
+  - family-names: "Sassi"
+    given-names: "Francesco"
+version: "1.0.0"
+repository-code: "https://github.com/SystemsLab-Sapienza/conspiracy-alert-plugin"
+preferred-citation:
+  type: conference-paper
+  title: "The Conspiracy Money Machine: Uncovering Telegram's Conspiracy Channels and their Profit Model"
+  authors:
+    - family-names: "Imperati"
+      given-names: "Vincenzo"
+    - family-names: "La Morgia"
+      given-names: "Massimo"
+    - family-names: "Mei"
+      given-names: "Alessandro"
+    - family-names: "Mongardini"
+      given-names: "Alberto Maria"
+    - family-names: "Sassi"
+      given-names: "Francesco"
+  conference: "34th USENIX Security Symposium (USENIX Security 25)"
+  year: 2025
+  url: "https://arxiv.org/abs/2310.15977"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SystemsLab Sapienza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.