Motir

The service that walks a customer domain through its life — add it, prove the customer owns it, ask the platform for its certificate, make it the project's canonical, take it away — and the four thin routes the settings pane calls. Built over the store, behind the certificates port, and guarded by the entitlement; the state machine is the ADR's Q4–Q6.

The service — lib/services/customDomainService.ts

Authorisation: every write asserts the project's manage permission (project:manage_access, the key projectMembersService uses for the access level — read it, do not guess); reads need browse. Cloud gate: isCloud() false ⇒ typed refusal ⇒ 404 { code }.

The two external dependencies, and the SEAM for each — owed here, because this card names the test home

The verify path crosses two systems an automated lane cannot reach: DNS and Fly. The service therefore takes both through injectable ports — CertificateProvider (already the adapter's port) and a DnsResolver port (resolveTxt(name): Promise<string[]>) with the node:dns/promises implementation as the production binding — and a single factory (lib/publicAddresses/providers.ts) selects the production bindings unless the lane's server env sets MOTIR_E2E_FAKE_PUBLIC_ADDRESS_PROVIDERS=1, in which case it binds an in-memory CertificateProvider that reports issued on the first check and a resolver that answers the stored token. The flag is read at call time, is refused in production builds (NODE_ENV === 'production' ⇒ ignored, with a test proving it), and is documented in the E2E lane's server env. Without this seam the E2E card cannot reach issued and would pass vacuously or stub the API in the browser — the failure type-test.md's tell (d) names.

The DTO and routes

• lib/dto/publicAddresses.ts — PublicAddressDto { id, kind, hostname, status, isPrimary, verification: { name, value } | null, dns: { type, name, value }[], lastCheckedAt, issuedAt, failureReason }; status is the store's enum crossing the wire as a string-literal union, TOTAL.
• app/api/projects/[key]/public-addresses/route.ts (GET list · POST add), …/[addressId]/verify/route.ts (POST), …/[addressId]/primary/route.ts (POST set · DELETE clear), …/[addressId]/route.ts (DELETE) — parse → gate → one service call → error mapping, in the shape of app/api/projects/[key]/access/route.ts; EntitlementExceededError maps to the status and body the billing routes already use for a cap, so the pane's upgrade prompt fires from the same shape.

Tests

Every operation's happy path and every typed error; the DNS verification with a stubbed resolver (token present, absent, wrong); the platform port stubbed for request success / refusal / unavailable; remove with a failing platform call still answers 2xx and logs; makePrimary refuses a non-issued row; add at the cap surfaces the entitlement error through the route; the manage gate (member → 403, non-member → 404); the factory binds production by default, the fakes under the flag, and never the fakes in a production build.

Boundary

No polling (the status job carries later state changes home), no UI, no public-surface change, no subdomain logic (that service).

Acceptance criteria

• POST /api/projects/{key}/public-addresses with a valid hostname answers 201 with a DTO carrying the TXT and the pointing record; the base domain, a reserved label, motir.co and a taken hostname each answer 4xx with distinct codes; at the cap it answers the billing surface's entitlement-exceeded shape with entitlement: 'custom_domains'.
• POST …/verify moves unverified → pending_certificate when the stubbed resolver returns the token and the stubbed port accepts; leaves unverified with a failureReason on a DNS miss; moves to failed with the platform's reason on a refusal — and in every case the platform call and the DNS lookup happen outside the write transaction (asserted by the transaction spy pattern the repo's side-effect tests use).
• POST …/primary succeeds only for issued; DELETE …/{id} on the primary leaves Project.primaryAddressId null and the platform remove is attempted after commit; a failing remove still answers 204.
• The provider factory binds the fakes only under MOTIR_E2E_FAKE_PUBLIC_ADDRESS_PROVIDERS=1 and never when NODE_ENV is production, both asserted; the E2E lane's server env is documented as the flag's home.
• Every route file is parse → gate → one call → mapping; the manage gate and the cloud gate are tested on each.
• No file outside motir-core is touched.

Context refs

• the decision — Q3, Q4, Q5, Q6, Q8; the store; the port; the entitlement
• motir-core/lib/services/projectMembersService.ts — the manage permission the access level asserts; lib/services/entitlementsService.ts — the cap-inside-the-create-transaction contract
• motir-core/app/api/projects/[key]/access/route.ts — the route shape; the billing routes' entitlement-exceeded mapping
• motir-core/CLAUDE.md — side effects after commit, typed errors, the 4-layer split; playwright.config.ts and the cloud lane's server env — where the seam flag lives
• Fly — https://fly.io/docs/networking/custom-domain/ (validation methods, what happens when a hostname stops validating)