Helyx Verification Contracts

Versioned runtime contracts for the Helyx-operated Verification service and the hosted Helyx bot that consumes it.

The package exposes strict Zod schemas and their inferred TypeScript types for:

• protocol compatibility, capability offers and installation claims;
• challenge creation with bounded Discord and policy snapshots;
• browser completion with an allow-listed, bounded signal set;
• signed assessment envelopes and permitted Discord-action boundaries;
• idempotent, provenance-labelled action receipts;
• dashboard-safe attempt lists and details;
• stable customer-safe reason codes and bounded service errors; and
• the four evidence source classifications required by the Verification trust model.

Security and privacy boundary

These contracts intentionally do not expose raw IP addresses, IP/device/signal digests, challenge-token digests, full provider payloads, other-server details, installation credentials, signing secrets or internal scoring intelligence. Every object is strict and its strings, arrays, records and numeric inputs are bounded.

helyx_hosted identifies the only supported Discord identity and action source. self_hosted_reported remains reserved in the wire schema so an unsupported source can be parsed and rejected explicitly; it is never accepted for storage or action. Browser and network observations remain labelled helyx_observed_web and provider_observed respectively.

Cryptographic signature generation and verification belong to the service and bot integrations. Consumers must verify the Ed25519 signature over the agreed canonical payload encoding, key ID, expiry, result nonce and every binding before performing an action. This package validates the envelope shape; it does not treat shape validation as signature verification.

Usage

import {
  challengeCreateRequestSchema,
  signedAssessmentEnvelopeSchema,
} from "@helyx/verification-contracts";

const request = challengeCreateRequestSchema.parse(untrustedRequest);
const envelope = signedAssessmentEnvelopeSchema.parse(untrustedEnvelope);

Use .parse() or .safeParse() at every process and trust boundary. Do not use TypeScript casts as a replacement for runtime validation.

Compatibility

The current protocol is 1.0. Compatibility is negotiated by major/minor protocol version and required capabilities. Unknown majors and offers missing a mandatory capability are rejected. Protocol changes that alter signed meaning, bindings or security behaviour require a new reviewed protocol version.