Common Thread

A practitioner's methodology and reference implementation for sockpuppet attribution from observable behavioral signals on social platforms.

Common Thread ships as a methodology paper (the spec) and a reference implementation (Cloudflare Workers + MySQL + R2). Given a seed set of accounts, it attributes coordinated inauthentic behavior to a common operator and emits calibrated probabilistic claims at three confidence bands: insufficient, consistent, strongly_consistent. It stops at cluster-level attribution by design and never identifies natural persons.

Who this is for

Pro se litigants, small-newsroom journalists, OSINT practitioners, and researchers who need documented methodology without platform-internal data or commercial OSINT tooling. Read the paper's audience exclusions (§1.2) before applying the methodology.

Hosted public UI (BYOK): https://common-thread.skyphusion.org
Current release: v0.3.0 (see CHANGELOG.md).

Repository layout

Path	Purpose
paper/	Methodology paper (CC-BY-4.0) -- the spec
implementation/	Backend reference implementation (AGPL-3.0)
web/	Browser UI Worker (proxies API, BYOK for attribution)
docs/	Setup, deployment, API, testing
containers/	Optional VPC ingest and PDF workers
tests/	Vitest suite (Workers pool + MySQL integration)
examples/	Worked case studies (synthetic §9 walkthrough in v1)

Quick start

git clone https://github.com/skyphusion-labs/common-thread
cd common-thread
npm install

# Backend config (fill in Hyperdrive + R2 IDs)
cp wrangler.toml.example wrangler.toml

# Web frontend config (service binding to backend)
cp web/wrangler.toml.example web/wrangler.toml

# See docs/SETUP.md for MySQL, R2, Hyperdrive, and local dev

Local development

# Terminal 1 -- backend API
npm run dev

# Terminal 2 -- web UI (optional)
npm run dev:web

Open the web UI, create an investigation (save the access token), upload Apify Twitter JSON, run extractors via ingest, then run attribution with your own credentials (BYOK): Anthropic API key or Cloudflare AI Gateway Run token, plus a gateway URL ending in /anthropic. See docs/SETUP.md, docs/PUBLIC-USAGE.md, and the Setup tab in the web UI.

Documentation

Doc	Contents
docs/PUBLIC-USAGE.md	Stranger happy path on the hosted UI
docs/PUBLIC-RELEASE.md	Public readiness / go-no-go record
docs/SETUP.md	First-time install, MySQL, secrets, local dev
docs/DEPLOYMENT.md	Deploy backend + web, bindings, VPC containers
docs/API.md	HTTP routes and typical workflow
docs/ENCRYPTION-AT-REST.md	§3.5 encryption + VPC key-on-dispatch
docs/TESTING_SETUP.md	Vitest, MySQL test DB, LLM mocking
docs/contact.md	Public and private contact channels

Web frontend

web/worker.js is a single-file Worker that provides the full workflow UI:

• Create investigations (one-time capability token) and reopen with token or share link
• Upload Apify data; seal investigations when complete (read-only)
• Poll ingest jobs and view features
• Run attribution with bring-your-own-key (BYOK) credentials
• Download evidence packets (JSON, Markdown, PDF when configured)

Investigations are private: no global listing. Tokens are capability secrets -- the UI explains what they do and do not protect.

The web Worker proxies /api/proxy/* to the backend via a service binding (BACKEND) in production. Users supply Anthropic / AI Gateway keys and investigation access tokens in the browser; API keys are not stored on the server. Investigation tokens may be saved in localStorage on the user's device.

Bring-your-own-key (BYOK)

The host does not need to pay for everyone's LLM usage. Attribution accepts credentials per request (web UI or API headers):

• Headers: X-AI-Gateway-Url plus either X-Anthropic-Api-Key or X-CF-AIG-Token (AI Gateway Run token for keyless Unified Billing)
• Body fields: aiGatewayUrl + anthropicApiKey or cfAigToken

Public hosted prod sets PUBLIC_BYOK_ONLY=1 (fail closed without visitor credentials). Self-host may set server AI_GATEWAY_URL + CF_AIG_TOKEN or ANTHROPIC_API_KEY instead. See docs/API.md and the web Setup tab.

Licensing

• Implementation: AGPL-3.0
• Methodology paper: CC-BY-4.0

Contributing

Bug reports and methodology questions: GitHub issues. Code contributions should reference the relevant paper section where applicable. See docs/contact.md for private inquiries.

Project posture and maintenance

v1 maintenance is bounded (security, reproducibility, platform breakage on the default path). The twelve-month transition window to community maintainers is documented in docs/MAINTENANCE.md. Maintainer volunteers are welcome via GitHub Discussions.

Status

v1 in active stabilization. Methodology paper complete. Backend Worker, web frontend, and optional VPC ingest/PDF containers are implemented.

Public UI: https://common-thread.skyphusion.org

Public API: https://common-thread-backend.skyphusion.org (see docs/API.md). Using the hosted API in your own project requires prior contact with the operator -- email common-thread@skyphusion.org or see docs/contact.md. To run your own instance without asking, self-host per docs/SETUP.md.

Skyphusion Labs: https://skyphusion.org · Org: https://github.com/skyphusion-labs

Repository: https://github.com/skyphusion-labs/common-thread