@oneaddress/conformance

CLI tool partners use to verify their webhook integration conforms to the OneAddress protocol. Ships as oneaddress-conformance once built.

What it checks

Runs a suite of end-to-end checks against a partner's webhook endpoint, covering:

1. HTTP basics — endpoint reachable, responds to POST, returns a parseable body.
2. HMAC signature verification — rejects tampered bodies, rejects wrong secrets, rejects missing headers.
3. Timestamp replay window — rejects timestamps older than ±5 minutes (before signature verify).
4. Canonical signing format — signature covers ${timestamp}.${rawBody}, not the body alone.
5. Payload decryption — partner can decrypt the ECDH/HKDF/AES-GCM address payload with their private key.
6. Idempotency guidance — confirms the partner is reading dispatchId from the event (soft check; can't tell if they actually dedup, only that they receive the field).
7. Grace-window key rotation — when both currentSecret and previousSecret are provided, verifies the partner accepts signatures from either while the grace window is open.
8. Error responses — returns 4xx for known bad inputs rather than 5xx.
9. Pull API (optional, requires --customer-url) — partner can fetch pending updates from /api/dispatch/pull.
10. Pull API confirm (optional) — partner correctly acknowledges a pulled update via the confirm callback.

Checks 9 and 10 are skipped unless --customer-url is provided.

Installation

npx @oneaddress/conformance test <webhook-url>

No install required — npx fetches the latest published version on demand.

Usage

# Against your local dev server using built-in test credentials
oneaddress-conformance test http://localhost:3001/webhook

# Against a staging deployment with real credentials
oneaddress-conformance test https://api.mycompany.com/oneaddress \
  --secret whsec_real_xxx \
  --partner-id 123e4567-e89b-12d3-a456-426614174000 \
  --public-key <base64-SPKI-of-your-ECDH-public-key>

# Include the pull-API checks (9 and 10)
oneaddress-conformance test https://api.mycompany.com/oneaddress \
  --secret whsec_xxx \
  --partner-id aaa... \
  --customer-url https://app.oneaddress.io

Flags

| Flag | Default | Purpose | |------|---------|---------| | --secret | Built-in synthetic test secret (used when partner is testing the wizard scaffold) | Your HMAC webhook secret | | --partner-id | Built-in test UUID | Your partner UUID | | --public-key | Built-in test ECDH SPKI | Your ECDH P-256 public key, base64 SPKI | | --customer-url | — | Customer-app base URL; when set, adds pull-API checks |

Exit codes

• 0 — all checks passed
• 1 — one or more checks failed (individual check output indicates which)
• 2 — CLI usage error (bad args, missing required flag)

Why it exists

• Gives partners a self-service way to validate their integration before go-live.
• Protects OneAddress against a partner that silently starts replying "200 OK" without actually verifying signatures — these checks deliberately send tampered bodies and expect a 4xx response.
• Locks the canonical signing format. If anyone ever changes it, this tool breaks, and that's the intended early-warning.

Related

• @oneaddress/partner-sdk — the TypeScript SDK that implements the partner side of these checks.
• packages/protocol — shared test vectors this CLI uses as ground truth.
• Partner SDK README — step-by-step integration guide (packages/partner-sdk/README.md).