@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://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).

Licence

Apache License 2.0. See LICENSE.

Apache-2.0 rather than MIT deliberately: it carries an express patent grant, bounded to this package. OneAddress holds a pending patent application over the address-change notification architecture, and this SDK is the recipient half of it. Partners using it is the entire point, so an explicit, bounded grant is clearer for you than MIT's silence on patents.