smart-org/docs/plan/reports/agent-3-phase-4.md

Agent 3 — Phase 4 report: domains owned by the platform owner

Date: 2026-10-14 · Branch: dev

What was done

4.1 admin_domains.py — the owner's routing console

Four routes under /api/admin/domains, all require_platform_owner:

Method	Path	Purpose
GET	/admin/domains	every route, with its owning org/app and target port
POST	/admin/domains	attach an extra host to an app
DELETE	/admin/domains/{id}	detach, with the host typed back as confirmation
POST	/admin/domains/sync	converge the router on the database
GET	/admin/domains/suggested	system routes the owner may enable (the MCP gateway)

Attaching a host points it at whatever port the app already serves on (demo, then web), so the owner never has to look a port up. Detaching requires the host typed back — removing a route is what makes a live URL stop working, so it gets the same typed confirmation as a production deploy — and is audited (domain.detach).

Users cannot attach domains. The member-facing POST/DELETE .../projects/{id}/preview/domains routes in projects.py are now owner-only. They are kept rather than deleted because the demo host is still created through them at app-creation time; the owner is simply the only actor who can reach them.

The host rule (domain/platform/rules.py)

validate_extra_host(host, root_domain, allow_custom) accepts exactly two shapes:

• a single label under the managed root (shop.msa.artacloud.ir) — the default; and
• a full custom FQDN (shop.customer.example), only when ALLOW_CUSTOM_DOMAINS is on. A custom host needs its own DNS record and certificate, and accepting one that will never resolve produces a domain that looks configured and is not.

A wildcard is refused in both shapes — *.example.com in a Caddy site block matches every subdomain, including another tenant's. So is a 30-name list of protected platform labels (git, mcp, panel, api, www, …): a tenant host that resolves to the forge or the console is both a phishing surface and a routing conflict with a real service. Hosts are normalised (lower-cased, trailing dot stripped, length-capped).

The rule is enforced twice — in the router and again inside the adapter — because a rule checked in one place is a rule that will eventually be bypassed.

4.2 Re-sync is idempotent

Both adapters gained routes_fingerprint(), list_all_routes() and sync_routes(desired):

• sync_routes renders the desired state, compares it against what is on disk, and writes and reloads only when it differs. Pressing the console's re-sync button must not drop every in-flight connection on the host, including tenants' live demos.
• The mock adapter applies the same validation, so a test that passes against the mock describes behaviour the real adapter also guarantees.

sync_routes/routes_fingerprint are adapter-level extras, not additions to DomainRouterPort — that contract is frozen by the plan. The router declares a local SyncableRouter protocol and reports "this router cannot re-sync" rather than crashing against a router that does not implement them.

4.3 The MCP gateway as a suggested route

GET /admin/domains/suggested offers mcp.<root> → MCP_GATEWAY_PORT. It is suggested rather than created automatically: it needs a DNS record and a certificate before it can work, and creating it eagerly would produce a host that looks live and is not. enabled reflects whether the route already exists.

Files changed

File	Change
app/domain/platform/rules.py	validate_extra_host, PROTECTED_HOST_LABELS
app/infrastructure/adapters/caddy.py	routes_fingerprint, list_all_routes, sync_routes
app/infrastructure/adapters/mock.py	the same three, with matching validation
app/infrastructure/repositories/projects.py	PreviewDomainRepository.list_all(), derived url
app/interfaces/http/routers/admin_domains.py	5 owner-only routes
app/interfaces/http/routers/projects.py	preview-domain create/delete are owner-only
tests/test_admin_domains.py	new — 58 tests

Test output

apps/api:  473 passed, 1 skipped (was 415; +58)
           ruff check .  -> All checks passed!
           mypy app      -> Success: no issues found in 132 source files
apps/web:  67 passed (unchanged)

Deviations from the TODO

1. sync_routes lives on the adapters, not the port. The TODO says "the Caddy adapter keeps validate → revert → reload. Add a routes_fingerprint check"; adding either to DomainRouterPort would change a frozen contract, so a local protocol covers it.
2. Detach requires the host typed back (the TODO says "confirm + audit"). A boolean confirm would be one more thing to click through; typing the host is the same pattern the production deploy uses, so operators meet it once and recognise it.
3. GET /admin/domains/suggested is new. The TODO asks for the MCP host to be "recorded as a protected system route that the owner can enable from this page"; without a route to read the suggestion the page has nothing to render.

Open questions / CHANGE REQUESTS

• None. DomainRouterPort and platform/rules.py's existing exports are unchanged; everything new is additive.

Known limitations

• A custom FQDN needs its DNS record and certificate to be arranged outside the platform (Caddy will attempt ACME on reload, which fails for a host that does not resolve). The console says so; it cannot do it for the operator.
• sync_routes is all-or-nothing: one invalid row in the ledger refuses the whole re-sync rather than applying the valid subset. That is deliberate — a partial sync is harder to reason about than a refusal — but it does mean one bad row blocks the button until it is fixed.