edgecheck

Browser-safe network integrity probe monorepo (Apache-2.0).

What it is

• Client-side probing toolkit for possible DNS, captive portal, proxy, and connectivity anomalies.
• Heuristic and non-invasive checks using browser-safe APIs only.

What it is not

• Not packet capture, not privileged host inspection, and not telemetry ingestion.
• Not a guarantee of compromise detection.

Packages

• @edgecheck/types
• @edgecheck/doh
• @edgecheck/dns-anomaly
• @edgecheck/captive-portal
• @edgecheck/proxy-heuristics
• @edgecheck/scoring
• @edgecheck/core

Install

pnpm install

Usage

import { runEdgeCheck } from '@edgecheck/core';

const report = await runEdgeCheck({
  canaryDomain: 'canary.example.com',
  diagEndpoint: 'https://diag.example.com/v1/ping',
  connectivityUrls: ['https://diag.example.com/v1/ping'],
  policy: {
    mode: 'safe',
    allowWebrtc: false,
    allowThirdPartyConnectivityUrls: false,
    disableOnCorporate: true
  }
});

How scoring works

EdgeCheck returns three additive score objects in report.scores:

• integrity (integrity concern)
• managed (managed/mediated likelihood)
• privacyRelay (privacy relay likely indicator)

These are derived from a weighted 4-layer model (DNS integrity, transport integrity, classification context, and deep-mode egress support). See docs/detection-model.md for formulas and thresholds.

Probe modes and privacy

• SAFE mode (default): minimal non-invasive probes.
• DEEP mode (opt-in): adds optional WebRTC egress indicator and expanded connectivity checks.
• Corporate/managed network context can gate invasive probes when disableOnCorporate=true.
• Report claims are conservative ("likely", "indicator", "heuristic").
• OSS does not upload telemetry.

Optional network context from diag endpoint

EdgeCheck can parse optional extended diag fields when present:

{
  "edgecheck": {
    "network": { "asn": 12345, "org": "Example", "type": "hosting", "confidence": 0.9 },
    "privacyRelay": { "level": "medium", "confidence": 0.7, "reasonCodes": ["example"] }
  }
}

The OSS reference diag endpoint is intentionally constrained and does not need to provide ASN/VPN enrichment. If you self-host a richer private diag service, EdgeCheck will surface these optional fields.

Demo

node scripts/setup-demo.mjs
cd examples/nextjs && pnpm dev

Contributing

Contributions are very welcome. A few good starting points:

• Improvements to detection heuristics (DNS, captive portal, managed networks, privacy relay/VPN indicators).
• Better explanations and UX in the example Next.js UI.
• Documentation and examples for integrating @edgecheck/core in different stacks.

See CONTRIBUTING.md for setup instructions, coding guidelines, and how to propose changes.

Environment variables:

• NEXT_PUBLIC_EDGECHK_CANARY_DOMAIN
• NEXT_PUBLIC_EDGECHK_DIAG_ENDPOINT
• NEXT_PUBLIC_EDGECHK_CONNECTIVITY_URLS (comma-separated)
• NEXT_PUBLIC_EDGECHK_EXPECTED_CANARIES (optional; canary CNAME expectations, format: a.canary.example.com=target1.example.com;b.canary.example.com=target2.example.com)
• NEXT_PUBLIC_EDGECHK_MODE (safe or deep)
• NEXT_PUBLIC_EDGECHK_ALLOW_WEBRTC (true or false)
• NEXT_PUBLIC_EDGECHK_ALLOW_THIRD_PARTY (true or false)
• NEXT_PUBLIC_EDGECHK_DUALPATH_ENABLED (true or false)
• NEXT_PUBLIC_EDGECHK_DUALPATH_VARIANTS (comma-separated A,B or A,B,C)

If diagEndpoint is omitted, portal/proxy/connectivity/stability probes are explicitly marked as skipped.