Chrome extension + TypeScript/Fastify API + PostgreSQL cache. An MVP for collecting and explaining source-verification signals.
Chrome extension (Manifest V3)
| HTTP / shared RiskCard contract
v
Fastify API ----> RDAP, DNS, TLS and page metadata checks
|
v
PostgreSQL risk-card cache
The stack demonstrates API integration, a shared TypeScript contract, browser-extension development, caching, and Docker-based setup. Redis is included in Compose but is not yet used for queues.
Assessment uses explainable rules, not an AI credibility model. A risk card supports manual verification; it does not prove that a source is truthful or malicious.
After starting the local stack:
curl http://localhost:8080/v1/domains/example.com/risk-cardIllustrative response excerpt with placeholder values, based on the shared RiskCard contract. This is not a live assessment of example.com and omits other contract fields:
{
"domain": "example.com",
"status": "partial",
"riskLevel": "unknown",
"confidence": "low",
"summary": "Illustrative placeholder; inspect the actual response and evidence.",
"signals": []
}The full response groups domain, DNS, TLS, site, redirect, and list-match information with a check timestamp and cache TTL. Signals can include evidence and verification recommendations. Known limitations are listed below.
Chrome extension plus backend API for transparent source credibility signals. The project does not claim that a site is fake or malicious. It collects technical and contextual signals, explains them, and recommends manual verification when risk is elevated.
- Chrome extension shell with:
- toolbar badge
- popup risk card
- dismissible content overlay
- local card cache via
chrome.storage.local
- Backend API with:
- RDAP lookup
- DNS lookup
- TLS certificate inspection
- homepage metadata and common about/contact/privacy checks
- simple explainable risk scoring
- Postgres-backed risk card cache
- Docker Compose stack:
apipostgresredis
- Shared TypeScript
RiskCardcontract. - Initial scoring tests.
- Node.js 22+
- npm 10+
- Docker and Docker Compose
By default, Docker stores container data (including Postgres databases) in its default data directory on the system disk (/var/lib/docker on Linux, or inside the Docker Desktop VM on macOS/Windows). This can fill up your system disk over time.
To store Docker data on an external volume instead, configure DOCKER_DATA_PATH in your .env file:
# .env
DOCKER_DATA_PATH=/Volumes/Transcend/DockerData/sco-chrome-extensionThis path is used as a bind mount for the Postgres data directory in docker-compose.yml:
volumes:
- ${DOCKER_DATA_PATH}/postgres:/var/lib/postgresql/dataThe directory will be created automatically when you run docker compose up. Make sure the path exists and is writable by your user (and Docker has access to it on macOS/Windows via Docker Desktop's file sharing settings).
Install dependencies:
npm installRun tests:
npm testBuild all workspaces:
npm run buildStart backend, Postgres, and Redis:
docker compose up --buildAPI endpoints:
GET http://localhost:8080/health
GET http://localhost:8080/v1/domains/example.com/risk-card
POST http://localhost:8080/v1/domains/example.com/refresh
Build the extension:
npm run build -w @sco/extensionLoad apps/extension/dist as an unpacked extension in Chrome:
chrome://extensions
Developer mode
Load unpacked
The extension calls http://localhost:8080 by default. Override it at build time with:
VITE_API_BASE_URL=https://your-api.example.com npm run build -w @sco/extensionRun the API locally without Docker:
npm run dev:apiWhen running locally outside Docker, set DATABASE_URL if you want persistent cache:
DATABASE_URL=postgres://sco:sco_password@localhost:5432/sco npm run dev:apiIf DATABASE_URL is omitted, the API still runs but does not persist risk card cache.
The MVP uses explainable rules, not machine learning:
- recently registered domain
- unavailable or incomplete RDAP
- missing HTTPS
- recently issued TLS certificate
- missing about/contact/privacy pages
- sparse homepage metadata
- cross-domain redirects
The popup and overlay use cautious language:
Signals indicate elevated risk. Manual verification recommended.
apps/
api/ Fastify backend
extension/ Chrome Manifest V3 extension
packages/
shared/ Shared TypeScript contracts
docker/
postgres/ DB initialization
docs/ Product and risk model notes
- External list matching is stubbed for now.
- Redis is included in Docker but not yet used for queues.
- Page checks are intentionally shallow to avoid aggressive crawling.
- Social profile extraction is best-effort from homepage links only.
- The content overlay's "View details" action is a placeholder; the toolbar popup is the canonical detail view.
