Domain Routing and DNS Bindings

Status: draft / design direction / roadmap. Names a future routing model for ICN. Items marked planned are not in the repo today. Companion to `COOPERATIVE_DOMAIN_INFRASTRUCTURE.md`.

Summary

Three concepts, often conflated, must stay distinct:

Plus a fourth, optional surface:

Why this distinction matters

Cooperative institutions need an authority boundary that does not depend on a vendor's DNS. Treating "ICN domain" and "DNS domain" as the same thing rebuilds the platform-landlord pattern: institutions become tenants of whoever owns the DNS namespace.

The institutional domain is the ICN object (InstitutionalDomain, planned). The DNS layer is just how packets find an HTTP surface. They bind to each other through an explicit, receipted process; they do not collapse into one thing.

Routing analogy (not a precedent)

Microsoft gives tenants an example.onmicrosoft.com domain and lets them verify example.org. ICN can use icn.zone similarly as a default utility namespace — but ICN must not become a landlord platform. The institution's real authority is the ICN InstitutionalDomain, and the institution may use its own custom public DNS.

The analogy stops at "utility namespace." ICN is not a tenancy.

Surfaces

Per accepted ADR-0032 — Website Truth Boundary, public ICN surfaces split into three roles. None of these is institutional authority — institutional authority lives in the InstitutionalDomain object, not in DNS.

Institutional sub-routes under icn.zone (nycn.icn.zone, icn.zone/n/nycn, etc.) are utility routes for finding/entering institutions. They are not the institution's authority and they are not the canonical public ICN surface. Authority lives in InstitutionalDomain; canonical ICN truth lives at intercooperative.network.

Future objects

DnsBinding

A binding between an InstitutionalDomain and a routable DNS name.

Future fields (illustrative shape — not yet committed):

• binding_id
• institutional_domain (the ICN scope, e.g. nycn)
• host (e.g. nycn.icn.zone or a custom public domain)
• purpose (default_icn_zone / short_route / custom_public_domain / event_route / etc.)
• verification (TXT challenge value, verification method, verification time)
• status (pending / verified / revoked)
• binding_receipt_hash (link into the receipt envelope)
• valid_from / valid_until (optional)

A binding is approved by domain governance and emits a receipt. Reversal is a counter-record, not a mutation (consistent with ADR-0026).

Verification flow (planned)

request custom domain                ──► proposal / charter act
   ↓
add TXT challenge                    ──► institution adds DNS record
   ↓
verify control                       ──► ICN node confirms TXT match
   ↓
approve binding                      ──► governance / domain admin act
   ↓
provision route / cert               ──► routing layer + ACME or equivalent
   ↓
emit binding receipt                 ──► receipt envelope (ADR-0026 Layer 2)

Each step is auditable. The binding's existence is provable from the receipt envelope alone, without trusting the routing layer.

PublicationReceipt (planned)

When content is published to a routed surface (custom domain or icn.zone route), the publish action emits a PublicationReceipt carrying:

• domain
• binding the publication used
• content artifact hash
• approving governance reference (proposal id or charter id, as applicable)
• timestamp
• runner DID

Public surfaces become provably approved — the published content can be verified back to a governance act.

NYCN example (illustrative)

NYCN-correct facts (preserve these — they replace prior placeholder text):

institutional_domain:
  id: nycn
  canonical_name: "New York Cooperative Network"

dns_bindings:
  default_icn_zone:
    host: nycn.icn.zone
    purpose: "ICN utility route / bootstrap namespace"

  short_route:
    host: icn.zone/n/nycn
    purpose: "Human-friendly ICN short link"

  custom_public_domain:
    # NYCN's own public domain (held by NYCN, not ICN). Documented in the
    # NYCN repo, not duplicated into ICN core.
    purpose: "NYCN public website / public identity"

  possible_summit_route:
    # Public route for the 2026 Summit (Schenectady, NY, 2026-10-17),
    # if NYCN chooses to expose one under their custom domain.
    purpose: "Public route for 2026 Summit (planned/example)"

NYCN-specific binding files (the institution/domain-bindings.example.yaml referenced in the parent doc) live in the NYCN repo. ICN core does not carry NYCN's specific public domain — that stays where it belongs, in the package.

Important: the prior placeholder newyorkcooperative.network is stale and incorrect. NYCN's actual public domain is documented in the NYCN repo (README.md, institution/package.yaml). Do not introduce NYCN-specific public-domain text into the ICN public website.

Routing semantics

A request to nycn.icn.zone/... should resolve to the routing layer for the nycn institutional domain. The routing layer:

1. Checks the requested path against the domain's installed tools (each tool exposes UI surfaces declared in its ToolManifest).
2. Checks the request's authentication against the domain's DomainPolicy (a DomainSession is established for member traffic; service-identity traffic uses scoped capabilities).
3. Forwards to the appropriate tool service, or returns the public-facing surface for unauthenticated requests.

For a custom public domain, the same flow applies — the difference is only the host header that arrived. The institution's authority is the same in either case.

Boundary discipline

• The routing layer never owns institutional truth. It is a router, not a database.
• A DnsBinding does not grant authority over the institutional domain. Authority is governed by charter / role / standing; the binding only routes.
• icn.zone is an ICN-owned utility-routing namespace. Institutional sub-routes under it (e.g. nycn.icn.zone, icn.zone/n/nycn) are utility routes, not institutional authority. The institution's authority lives in its InstitutionalDomain; DNS never equals institutional authority. ICN as a project must not become a landlord of institutional names.
• Canonical public truth about ICN lives at intercooperative.network, per ADR-0032. Custom institution domains and ICN utility routes can describe or link to ICN, but they do not define ICN.

Existing repo support

What exists today that this design will sit on:

• ADR-0032 — Website Truth Boundary — accepted; intercooperative.network is the canonical public truth surface.
• RFC-0015 — Public Surface and Learning Repo Architecture — draft; explores how intercooperative.network, icn.zone, learn.icn.zone, and adjacent surfaces split roles. Cited here as exploratory framing only; the accepted policy is ADR-0032.
• Receipt envelope for binding receipts and publication receipts (ADR-0026)
• Charter/role/authority_scope plumbing for governance acts that approve bindings (existing)
• Public ICN website source under website/src — does not carry NYCN/Summit nouns

Missing buildout

• DnsBinding object + verification record
• PublicationReceipt class
• Routing layer for *.icn.zone and custom institutional domains
• Per-tool UI-surface declarations in ToolManifest
• Provisioning automation (ACME or equivalent) gated on a verified binding
• Per-domain admin UI for managing bindings (future tool: icn-domain-admin)

Non-goals

• No runtime implementation in this PR.
• No public website changes.
• No new NYCN-specific text in website/src.
• No learn.icn.zone link on the public ICN website. ADR-0032 governs the canonical public surface; RFC-0015 explores the future split. This doc does not change either.
• No treatment of an institutional sub-route (e.g. nycn.icn.zone) as the institution's authority — authority lives in the InstitutionalDomain, not in DNS.
• No vendor lock-in to a specific DNS provider, certificate authority, or routing stack — the design is provider-agnostic.
• No treatment of icn.zone as the canonical public truth surface. ADR-0032 makes intercooperative.network the truth boundary; icn.zone is utility routing.

References

• `COOPERATIVE_DOMAIN_INFRASTRUCTURE.md` — parent design (institutional domains, agreements, receipts)
• `COOPERATIVE_TOOL_COMMONS.md` — companion: tools that publish to routed surfaces
• `MODEL_WORKLOADS_AND_DELIBERATION.md` — companion: advisory compute
• RFC-0015
• ADR-0026, ADR-0027