Registry

The Registry is ENI6MA’s public HTTP API. It provides circuit discovery, proof flow (challenge and validate), CLI proxy for remote command execution, binary distribution, and health and documentation endpoints. Integrators use the Registry as the single entry point for proof-based authentication and for distributing or executing circuit binaries.

Operational capacity

The Registry operates as a catalog and execution gateway. It does not store user secrets or mappings; it holds circuit metadata (handles, SHA256 hashes, manifests, build identifiers) and coordinates with the Ledger for nonce reservation and consumption. All proof verification is performed either by the Registry’s executor (running the circuit in a sandbox) or by the relying party, using the same challenge–response semantics. This design keeps the Registry stateless with respect to credentials while still enabling central discovery, rate limiting, and audit.

Deployments typically expose the Registry at a public URL (e.g. registry.eni6ma.net). No API keys are required for standard proof flow; security is proof-based. Optional header x-eni6ma-ledger-url allows directing nonce operations to a dedicated Ledger instance for enterprises that operate their own ledger.

Endpoints overview

The API is organized into discovery, proof, CLI proxy, binaries, and health/docs groups. OpenAPI is available at GET /api/swagger and Swagger UI at /docs (or your deployment’s equivalent). Below we summarize each group and then walk through the three-call proof pattern.

Discovery

• GET /api/circuits — List available circuits (handles and metadata).
• GET /api/circuits/{handle} — Circuit metadata for a given handle.
• GET /api/circuits/{handle}/manifest — Build manifest (versions, hashes).
• GET /api/circuits/{handle}/verify — Verification and compatibility info.
• Build-scoped variants (e.g. by build id) allow pinning to a specific binary version.

Proof flow

• POST /api/circuits/{handle}/challenge — Request a challenge. The Registry reserves a nonce from the Ledger (or the ledger indicated by x-eni6ma-ledger-url) and returns a nonce UUID, tau timestamp, and challenge data (e.g. geometry for the six-zone grid).
• POST /api/circuits/{handle}/validate — Submit proof payload (kind, nonce_uuid, payload with tau, bearings, proof_hash, etc.). The Registry burns the nonce first (burn-before-validate), then runs verification. Returns { validated: true } or an error.

CLI proxy

POST /api/circuits/{handle}/cli/{command} accepts an ExecRequest body (command, args, flags, optional input). The Registry runs the circuit binary in a sandbox with the given command and returns stdout/stderr. This allows servers to invoke proof commands (e.g. challenge, validate-response), ledger commands, or signing commands without distributing the binary to the client. Implications: same rate limits and audit as direct API; commands are executed in an isolated container with no persistent storage.

Binaries

GET /api/binaries/handle/{handle} (and build-specific variants) streams the circuit binary for download. Response headers include X-ENI6MA-SHA256, X-ENI6MA-Version, and X-ENI6MA-Manifest-URL for integrity and versioning. Clients can verify the downloaded file against the SHA256 and pin to a specific build.

Health and documentation

• GET /api/health — Service health; GET /api/health/db for database connectivity.
• GET /api/swagger — OpenAPI 3.0 spec (optionally ?handle={handle} for handle-scoped docs).
• /docs — Swagger UI for interactive exploration and testing.

Three-call pattern: reserve → ceremony → validate

The minimal integration is three steps. (1) Reserve (via challenge): call POST .../challenge; the Registry reserves a nonce from the Ledger and returns nonce_uuid, tau, and challenge data. (2) Ceremony: present the challenge to the user (six-zone grid); collect bearing selections; the user never sends a reusable credential, only one-time responses bound to this challenge. (3) Validate: call POST .../validate with the nonce_uuid and payload (tau, bearings, proof_hash, etc.). The Registry first burns the nonce (POST /response to the Ledger), then verifies the proof. If the proof is valid, you get { validated: true }; if the nonce was already spent you get 409; if the nonce expired you get 410; if tau or payload is invalid you get 400.

Burn-before-validate means each challenge accepts exactly one validation attempt. Replay is rejected at the Ledger; rate limiting and TTL (e.g. 300 s) prevent challenge stockpiling and brute force. Developers should treat the nonce as single-use and time-bound and never retry the same nonce on failure (request a new challenge instead).

Engagement flow and optional ledger URL

In the default deployment, the Registry is configured with a single Ledger URL and uses it for all nonce operations. For enterprises that run a dedicated Ledger (e.g. for isolation or compliance), the client or an intermediary can send the header x-eni6ma-ledger-url on the challenge request. The Registry will use that Ledger for the reserve (and the corresponding burn on validate). The rest of the flow is unchanged; only the nonce lifecycle is delegated to the specified Ledger instance.

The engagement flow for end users is: your app requests a challenge, you render the six-zone grid (or delegate to a hosted ceremony UI), the user applies their cognitive key (color–direction or personalized mapping) and submits bearings, and your backend calls validate. No passwords or long-lived tokens are issued; each authentication is a single proof ceremony. For machine-to-machine or agent flows, the same three calls apply; the “user” may be another service holding a circuit binary and submitting proofs on behalf of an identity.

Integration patterns and error handling

Integrators should treat the proof flow as a strict sequence: one challenge, one ceremony, one validation attempt. The Registry and Ledger return well-defined HTTP status codes so clients can distinguish replay, expiry, and bad requests from transient failures.

409 Conflict means the nonce was already consumed (replay). The client must not retry the same nonce; request a new challenge and present a fresh ceremony to the user. 410 Gone means the nonce expired (TTL elapsed without a burn). Again, request a new challenge. 400 Bad Request typically indicates a tau mismatch (payload generated for a different challenge) or malformed request body; check that the payload matches the challenge that was presented. On success, the validate endpoint returns 200 with a body such as { validated: true }.

For discovery and binaries, 404 indicates an unknown handle or build. Health endpoints return 200 when the service and optional dependencies (e.g. database) are up. CLI proxy errors surface the circuit binary’s exit code and stderr; the Registry does not interpret proof failure beyond forwarding the executor’s result. Best practice: implement idempotent challenge requests (each call reserves a new nonce), never reuse a nonce_uuid for a second validate call, and surface clear messaging to the user on 409/410 so they understand they must complete a new ceremony.

Rate limiting and quotas

The Registry may enforce rate limits on challenge and validate endpoints to prevent abuse and brute-force attempts. Limits are typically expressed per handle, per client IP, or per API key when keys are used. Exceeding the limit results in HTTP 429 Too Many Requests; the response may include headers such as Retry-After.

Rate limiting is a critical complement to the Ledger’s one-attempt-per-nonce rule. Even though each nonce accepts only one validation, an attacker could in theory reserve many nonces and attempt one guess per nonce. Rate limiting caps the number of challenges (and thus validations) per time window, making brute force infeasible. For example, at 10 validations per minute, an attacker facing a 12-round proof (with roughly 2.2 billion possible bearing sequences) would need centuries to exhaust the space. Combined with TTL expiry (unused challenges become invalid), the system prevents both online brute force and offline challenge stockpiling.

CLI proxy and binary download may have separate limits to protect server capacity. Check your deployment’s documentation or the OpenAPI spec for advertised limits and recommended backoff behavior.

Deployment and security model

The Registry is designed as a credential-less gateway: it never stores or processes user secrets or private mappings. Circuit metadata (handles, hashes, manifests) is public or policy-controlled; the only sensitive lifecycle data is the nonce state (reserved vs spent), which is held by the Ledger and does not reveal the user’s identity or proof content. This separation ensures that a compromise of the Registry does not yield reusable credentials or the ability to impersonate users.

In a typical deployment, the Registry runs in a trusted zone with access to the Ledger and to an executor that can run circuit binaries in a sandbox. The executor receives challenge-related inputs (e.g. tau) and proof payloads for verification but does not persist them. Network isolation between the public-facing Registry and internal services (Ledger, compiler, executor) reduces the attack surface. TLS is required for all client-facing endpoints; the Ledger URL passed via x-eni6ma-ledger-url should use HTTPS when the Ledger is remote.

Revocation is handled at the policy layer: remove a circuit’s SHA256 hash from the accepted set (or from the circuit catalog), and the next challenge or validate request for that circuit fails. There are no certificate revocation lists or long-lived tokens to revoke; the artifact identity is the hash, and policy is enforced at request time.

Registry API reference

For full request/response schemas, error codes, and examples, use the OpenAPI spec at GET /api/swagger or the Swagger UI at /docs on your Registry deployment (e.g. registry.eni6ma.net/docs). The spec includes ExecRequest for the CLI proxy and all proof and discovery endpoints.