# HeadlessDomains Future EPP Gateway Contract

Version: 0.1
Updated: 2026-06-11
Status: `planned_gateway_not_live`
Current endpoint status: `not_epp_endpoint`

## Boundary

The current production surface is the HTTP registrar API. EPP will be a protocol gateway on top of the same internal registry service and audit model.

## Transport Plan

- protocol: `EPP over TCP/TLS`
- service process: `separate headlessdomains-epp-gateway service`
- state source: `headlessdomains-partners internal registry service`
- session auth source: `approved registrar channel plus scoped registrar API credential/profile`

## Command Mappings

| EPP command | HTTP command | Registry service command | Notes |
| --- | --- | --- | --- |
| login | `GET /status` | `status/capability preflight` | Authenticate registrar session and return server capabilities from approved channel, API key scopes, namespace listings, and rate limits. |
| check domain | `POST /domains/check` | `check_domain` | Map EPP domain check to availability preflight for the authorized namespace listing. |
| create domain | `POST /domains` | `create_domain` | Create registration through the internal registry service; idempotency key should be derived from EPP client transaction id. |
| info domain | `GET /domains/{domain}` | `info_domain` | Return domain lifecycle, expiry, registrant reference, nameserver, and backend state that is safe for the authenticated registrar. |
| renew domain | `POST /domains/{domain}/renew` | `renew_domain` | Renew through the same balance, expiry, audit, and idempotency path as HTTP registrar API. |
| update domain | `PATCH /domains/{domain}` | `update_domain` | Update supported registrant metadata or lifecycle status fields; protected legacy status changes remain policy-gated. |
| transfer domain | `POST /domains/{domain}/transfer` | `transfer_domain` | Record transfer intent and queue backend apply when the namespace backend requires manual/application work. |
| update nameservers | `PUT /domains/{domain}/nameservers` | `update_nameservers` | Store desired nameserver state and expose pending backend apply status. |
| delete domain | `DELETE /domains/{domain}` | `delete_domain` | Cancel lifecycle record; protected legacy records require explicit policy confirmation and are never hard-deleted. |
| poll | `GET /poll and GET /backend/pending` | `poll/backend_pending` | Expose registrar-channel-scoped audit events and pending backend work as EPP poll messages or mapped poll responses. |

## Idempotency Mapping

- source: `EPP clTRID`
- target: `registry service idempotency_key`
- conflict error: `duplicate_idempotency_key_conflict`

## Error Mapping

- Source: `registry_service_error_catalog`
- Fields: `code, http_status, epp_result_code, epp_result, retryable`
- Default EPP result code: `2400`

## Poll Mapping

- audit source: `registry_command_audits`
- channel scope: `registrar_channel_id`
- pending backend endpoint: `/backend/pending`
- candidate epp messages: `command result, backend apply pending, backend apply applied, backend apply failed`

## Not Ready Gates

- TCP/TLS EPP server process is not implemented.
- EPP XML parser/serializer is not implemented.
- Registrar session lifecycle and greeting/login/logout are not implemented.
- EPP OT&E test suite and evidence archive are separate future work.

## Conformance Snapshot

- Ready for TCP gateway: `False`
- Ready for EPP OT&E: `False`
- Summary: Mapped for a future EPP gateway, but not ready for EPP OT&E until transport, XML, session lifecycle, and EPP evidence are implemented.

### Implemented Checks

- `command_mappings_complete`: EPP command mappings point at the HTTP registrar API and internal registry service commands.
- `error_mapping_shared`: The registrar error catalog includes HTTP status, EPP result code, EPP result label, and retryability.
- `poll_mapping_defined`: Audit events and pending backend work are mapped to future EPP poll messages.
- `idempotency_mapping_defined`: EPP clTRID maps to the internal registry service idempotency_key.

### Missing Checks

- `tcp_tls_server`: TCP/TLS EPP server process is not implemented.
- `xml_parser_serializer`: EPP XML parser/serializer is not implemented.
- `session_lifecycle`: Registrar greeting, login, session state, and logout are not implemented.
- `epp_ote_suite`: EPP OT&E fixtures, credentials, sample XML, command logs, and evidence archive are not implemented.