@eep-dev/compliance-cli

End-to-end conformance testing CLI for any EEP-compatible platform.

Overview

@eep-dev/compliance-cli is a zero-dependency test harness that verifies whether a platform correctly implements the Entity Engagement Protocol. It simulates an agent subscriber — creating subscriptions, receiving webhook deliveries, and validating every aspect of the EEP specification.

What It Tests

The CLI runs tests across three conformance levels:

| Level | Tests | What's Verified | |-------|-------|----------------| | 🥉 Core | Platform reachability, EEP discovery (Link headers), subscription creation, WebSub intent verification, webhook delivery, Standard Webhooks headers, HMAC-SHA256 signature, CloudEvents envelope | Signal stream basics | | 🥈 Standard | All Core tests + SSE stream endpoint, rate limit headers | SSE + rate limiting | | 🏆 Full | All Standard tests + manifest/policy probes + extended probes (Layer 1 content negotiation, 402 payment gate, WebSocket pulse, CloudEvents/EEP helper validation) | Advanced baseline checks (partial full-tier automation) |

--level full currently performs partial full-tier automation. WebSocket commerce state machine, PoI cryptographic verification, and some sector-specific checks still require manual/stack-specific validation.

Requirements

• Node.js ≥ 22 (uses node:util/parseArgs and --experimental-strip-types)
• Network access to the target platform
• An API key for authenticated endpoints
• A publicly reachable port for the webhook receiver (or use host.docker.internal for Docker environments)

Usage

Quick Start

# Run against any EEP-compatible platform
npx @eep-dev/compliance-cli --target https://api.example.com --api-key sk_... --entity u/acme-corp

# Test only core conformance
npx @eep-dev/compliance-cli --target https://api.example.com --api-key sk_... --entity u/test --level core

# Use a custom port for the local webhook receiver
npx @eep-dev/compliance-cli --target https://localhost:3000 --api-key sk_... --entity u/test --port 9999

# Emit structured audit reports
npx @eep-dev/compliance-cli \
  --target https://api.example.com \
  --api-key sk_... \
  --entity u/acme-corp \
  --level full \
  --report-json ./eep-audit-report.json \
  --report-md ./eep-audit-report.md \
  --report-html ./eep-audit-report.html

From the Monorepo

cd packages/@eep-dev/compliance-cli
node --experimental-strip-types src/index.ts \
  --target https://api.example.com \
  --api-key sk_... \
  --entity u/test

CLI Options

| Flag | Short | Type | Default | Description | |------|-------|------|---------|-------------| | --target | -t | string | — | Required. Platform base URL | | --api-key | -k | string | — | API key for authenticated requests | | --entity | -e | string | — | Entity DID or {prefix}/{username} to subscribe to | | --level | -l | string | standard | Conformance level: core, standard, full | | --port | -p | string | 9876 | Local port for the test webhook receiver | | --report-json | — | string | — | Write machine-readable audit report JSON | | --report-md | — | string | — | Write human-readable audit report markdown | | --report-html | — | string | — | Write self-contained HTML audit report | | --help | -h | boolean | — | Show help message |

How It Works

┌──────────────────┐       ┌───────────────────┐
│  compliance-cli  │       │  Target Platform  │
│                  │       │                   │
│  1. POST /subscribe ───► │  Creates sub      │
│                  │       │                   │
│  2. ◄── WebSub challenge │  Intent verify    │
│     (GET ?hub.challenge) │                   │
│                  │       │                   │
│  3. POST /test ────────► │  Triggers event   │
│                  │       │                   │
│  4. ◄── POST /hook       │  Delivers webhook │
│     (Verify HMAC)        │                   │
│                  │       │                   │
│  5. Check SSE ──────────►│  Stream endpoint  │
│                  │       │                   │
│  📊 Report Results       │                   │
└──────────────────┘       └───────────────────┘

Step-by-Step Flow

1. Health check — Verifies the platform is reachable
2. EEP discovery — Checks for Link: <...>; rel="subscribe" header on entity pages
3. Subscription creation — Creates a webhook subscription via POST /eep/subscribe
4. WebSub Intent Verification — Waits for the platform to send a GET challenge to the local webhook receiver
5. Webhook delivery — Triggers a test event and waits for the webhook to be delivered
6. Signature verification — Validates HMAC-SHA256 using the delivery_secret
7. CloudEvents validation — Checks specversion, id, source, and eep_version fields
8. SSE stream (Standard+) — Opens an SSE connection and verifies Content-Type: text/event-stream
9. Rate limit headers (Standard+) — Checks for X-RateLimit-* headers

Example Output

🔬 EEP Compliance Test — Level: STANDARD
   Target: https://api.example.com
   Entity: u/acme-corp
────────────────────────────────────────────────────────

📋 CORE CONFORMANCE

  ✅ Platform is reachable (HTTP 200)
  ✅ EEP discovery via Link header (rel="subscribe" found)
  ✅ Subscription creation (ID: sub_abc123)
  ✅ WebSub Intent Verification (challenge/response completed within 10s)
  ✅ Webhook delivery received (event type: com.example.entity.test)
  ✅ Standard Webhooks headers present (webhook-id, webhook-timestamp, webhook-signature)
  ✅ HMAC-SHA256 signature is valid (Standard Webhooks v1)
  ✅ CloudEvents specversion is 1.0
  ✅ Event id field present
  ✅ Event source field present
  ✅ EEP extension attributes present (eep_version: 0.1)

📋 STANDARD CONFORMANCE

  ✅ SSE stream endpoint (Content-Type: text/event-stream)
  ✅ Rate limit headers present (X-RateLimit-* headers found)

────────────────────────────────────────────────────────

📊 Results: 13 passed | 0 failed | 0 skipped

   Audit score: 100/100

   🥈 Standard EEP Compliant

Verification & Scoring Workflow

The CLI can act as an automated verifier for projects claiming EEP compliance:

1. Run conformance checks against the target.
2. Compute a normalized score (score_100) over evaluated checks.
3. Emit per-check failures with actionable recommendations.
4. Share the generated JSON/markdown report with the target project.

This enables repeatable, automatable audit loops for migration and transition programs.

Architecture

The CLI is a single TypeScript file (~360 lines) with zero runtime dependencies. It uses:

• node:util/parseArgs — CLI argument parsing
• node:http/createServer — Local webhook receiver (receives both WebSub challenges and webhook deliveries)
• node:crypto — HMAC-SHA256 signature verification with timingSafeEqual
• fetch — HTTP requests (built into Node.js 22+)

The local webhook receiver runs on localhost:9876 (configurable) and handles:

• GET requests — WebSub intent verification (echoes hub.challenge parameter)
• POST requests — Webhook delivery capture and header recording

Network Configuration

The CLI starts a local HTTP server to receive webhooks. The target platform must be able to reach this server.

| Scenario | delivery_url | |----------|---------------| | Same machine | http://localhost:9876/hook | | Docker → host | http://host.docker.internal:9876/hook | | Cloud dev | Use a tunnel (e.g., ngrok http 9876) |

The CLI defaults to http://host.docker.internal:${port}/hook for Docker environments.

Exit Codes

| Code | Meaning | |------|---------| | 0 | All tests passed — platform is compliant at the requested level | | 1 | One or more tests failed, or --help was invoked without --target |

Unit Tests

The CLI's helper functions are thoroughly tested with 34 unit tests covering:

| Area | Tests | What's Covered | |------|-------|----------------| | Test Runner | 11 | pass/fail/skip tracking, summary computation, conformance labels (all 3 levels + failures) | | Argument Validation | 7 | Missing target, invalid level, port validation (range + NaN) | | Target Normalization | 4 | Trailing slash removal, multi-slash, path URLs | | CloudEvents Validation | 5 | Required fields, specversion check, multiple missing fields | | EEP Extensions | 2 | eep_version presence | | Webhook Headers | 4 | Standard Webhooks header detection, undefined handling |

cd packages/@eep-dev/compliance-cli && npx vitest run

Specification Reference

• EEP SPECIFICATION.md — The formal specification
• EEP security.md — Security model
• EEP delivery_guarantees.md — Retry and backoff requirements
• CloudEvents v1.0.2 — Event envelope format
• Standard Webhooks — Signature specification

License

Apache 2.0 — See LICENSE