Ownership model¶
6. Ownership model¶
6.1 Unit of ownership: the RRset¶
Providers offer no free-form field on records (a EuroDNS record only has id,
type, host, ttl, rdata, updated, locked, isDynDns, proxy), so
ownership cannot be stored on the record. It lives in the gate's store, keyed by
RRset = (zone, host, type), with host normalized (dns.NormalizeHost:
lowercase, no trailing dot, zone suffix stripped, apex = @).
An ownership entry (store.Ownership):
| Field | Meaning |
|---|---|
Zone, Host, Type |
RRset key |
Owner |
team (not the individual identity, which may rotate) |
CreatedBy, CreatedAt, RequestID |
provenance |
ContentHash |
dns.ContentHash (TTL + sorted values, or the alias target) after the last gate write |
PendingHash |
expected hash while a write is in flight |
State |
pending, active, tainted |
Adopted |
true when the RRset pre-existed and was adopted |
ExpiresAt |
ephemeral RRsets (ACME challenges), garbage-collected after this time |
Version |
optimistic concurrency on the entry |
6.1.1 URL forwards¶
A URL forward (HTTP redirect) is owned like an RRset: it is modelled as the RRset of
the pseudo type URLFWD (never a DNS type) of its host, with TTL 0, no values and
a dns.Forward (type 301, 302 or frame, url, and title, keywords,
description for frames). Ownership entries, tombstones, transfers, adoption,
reconcile (drift taints it), plans, audit (old_forward/new_forward), the UI and
MCP all reuse the RRset machinery with that key. Its content hash is
dns.ContentHash of TTL 0 and the single value
forward <type> <n>:<url> <n>:<title> <n>:<keywords> <n>:<description> (each field
prefixed by its length in bytes, so no field can bleed into another); hashes of
other RRsets are unchanged. Writing requires dns.forward.write, scoped by
records.hosts (policy.WriteAction); providers without forwards (Route53) report
Capabilities.Forwards false and the engine refuses forward changes. A forward
shadows the A, AAAA, CNAME and APEX records of its host
(policy.ForwardShadowTypes): the engine creates one only where those records are
absent or owned by the caller's teams, and the reverse; a protected entry listing
one of those types protects the forward. Through the full-zone PUT,
dns.zone.admin only changes or deletes unowned forwards (audited as
zone_admin_forwards), never creates one. Frame fields are plain text with length
limits and URLs must be canonical http(s) URLs: EuroDNS serves frame forwards as a
page on the customer host.
HTTPS: a EuroDNS forward entry has no HTTPS setting; the forward host answers HTTPS
only with an HTTPS redirect subscription on the domain (a paid product: a
certificate for the forward hosts, state ACTIVE, PENDING or NO_FORWARD). The
adapter reads it (GET /subscriptions?subscription-types=HTTPS_REDIRECT&domain-name=
then GET /https-redirect-subscriptions/{id}, cached 10 minutes per zone, a failure
30 seconds; one lookup per zone at a time, with its own timeout, before the zone
lock) and the API reports it, an expired subscription as inactive;
require_https on a forward write is refused (https_unavailable) unless it is
active or no_forward. The gate never
orders, renews nor deletes subscriptions (orders are paid, and the passthrough
keeps denying the subscription operations).
6.2 Rules¶
| Situation | Result | Reason code / HTTP |
|---|---|---|
| Create an RRset that does not exist upstream | allowed if RBAC allows; claim written for the caller's team (Authorizer.OwnerTeam, the default team or the one selected with X-DNS-Gate-Team) |
— |
Create an RRset deleted less than ownership.tombstone_ttl ago by a team the caller is not a member of |
refused, the RRset is reserved for that team (tombstone); a transfer moves it | not_owner / 403 |
| Create/modify an RRset that exists upstream but has no ownership entry | refused, never mixed with foreign records | foreign_rrset / 409 |
| Modify/delete an RRset owned by another team | refused | not_owner / 403 |
Modify/delete an owned RRset whose upstream content no longer matches ContentHash |
refused, entry marked tainted |
tainted / 409 |
| Any change on a protected RRset | refused, even for admins | forbidden / 403 |
| Any change or adoption of a read-only RRset (SOA, EuroDNS locked or relative target, Route53 routing policy) | refused | forbidden / 403 |
MustNotExist on an existing RRset (RRset API) |
refused | foreign_rrset / 409 if not owned, precondition / 412 if owned |
ExpectedHash differs from the upstream content (RRset API) |
refused | precondition / 412 |
Alias RRset on a provider without alias support, value or TTL refused by Normalize |
refused | invalid_zone / 400 |
More changes than Authorizer.MaxChangesPerRequest |
refused | too_many_changes / 403 |
If-Match does not match the zone version |
refused | precondition / 412 |
The provider check (EuroDNS check) reports a blocking problem |
refused | invalid_zone / 400 |
Zone lock not acquired within LockWait |
refused, client retries | zone_locked / 423 |
The CNAME exclusivity rule falls out naturally: creating a CNAME where foreign records exist at the same host is a foreign collision.
6.3 Adoption¶
Records that existed before the gate are foreign and read-only through the gate.
POST /.well-known/dns-gate/zones/{domain}/adopt (action dns.record.adopt,
admin role) creates ownership entries for listed RRsets, with their current content
hash and Adopted = true. Adopting an RRset already owned by the caller's team is
a no-op. The owner is one of the caller's teams; another team requires
dns.ownership.approve on each adopted RRset. An RRset reserved for another team by
a tombstone is never adopted for another team: it moves through a transfer. In gate mode, terraform import of an eurodns_record_set calls adopt.
Bulk adoption with preview, Terraform export and onboarding of whole zones are
described in section 16.
6.3.1 Teams, tombstones and transfers¶
Teams are declared in the teams block (base file or managed layer) with their
members; a binding naming a team without groups or subjects grants its role to the
members. Once the block exists, references to undeclared teams are refused; before,
they are declared automatically with a warning (migration). Derived teams never take
the name of a declared team: with the block, families (team_from, from_subject)
need a prefix that no declared or fixed team carries, Snapshot.Resolve drops a
binding whose derived team is declared, and a team_claim value is kept only for a
family member that is not declared. A subject records the roles of each of its teams
(Subject.TeamRoles): rights held through one team never count for another.
Deleting an owned RRset (gate write, or a pending delete settled by the reconciler)
writes a tombstone (ZONE#<zone>/TOMB#<host>#<type> in DynamoDB, table
ownership_tombstone in SQL) with the team, the deleter and an expiry, in the same
store transaction as the removal of the ownership entry
(Store.DeleteWithTombstone): when it fails the entry stays pending and the
reconciler retries. Until it expires, only that team may create or adopt the RRset
again; ephemeral RRsets leave no tombstone.
A transfer request lists RRsets of one team (owned or tombstoned) and a target team,
with their content hash. The approver may, for every RRset, write it through the
bindings of the owner team or holds dns.ownership.approve on it, and is a human
unless ownership.machine_approvers. With ownership.require_second_approver it is
another person: requester and approver share no person key (the subject for
ownership.person_issuers, and the values of ownership.person_claims, email
only when trusted and verified), and either without person keys fails closed;
without it, the requester may approve its own request (audited approval: self).
The transfer is then applying: the engine takes the zone lock, reads the zone,
checks that every entry still has the team, the state and the content hash of the
request (store and upstream) or already carries the transfer id, then changes them
all in one store transaction (Store.Reassign: SQL transaction, DynamoDB
TransactWriteItems with a version or team condition per item, at most 100 items)
and audits the move as soon as it commits. After an ambiguous store error it reads
the entries back to tell whether the transaction committed. A transfer left
applying (zone locked, store unavailable, crash) is retried in the background no
earlier than 2 minutes after the approval, by one replica at a time (a lease in the
transfer, taken with a version check), with the approver bound again (Rebinder,
the current policy) and its rights checked again; after 24 hours it fails. A team
rename is approved by a policy.approve holder and always applied in the
background: zone by zone, in the managed zones and every zone the store still holds
(Store.ListOwnedZones, a scan on DynamoDB, #68), each entry checked for
dns.ownership.approve of the approver under the zone lock.
6.4 Rebase on full-zone PUT¶
PUT /dns-zones/{d} carries a whole zone, often stale (the client read it earlier).
The EuroDNS facade computes zonediff.Diff(current, desired) against the current
zone, read under the zone lock by the engine.
- Default: any difference outside the caller's scope (RBAC or ownership) is refused.
- Roles with
rebase_on_save(ACME clients such as lego): out-of-scope differences are ignored and logged; only in-scope changes are applied on top of the current zone (zonediff.Apply). This avoids both silent overwrites and spurious failures when another writer changed the zone after the client's read.
Residual race: two rebasing clients changing the same in-scope RRset
concurrently without If-Match. Acceptable for ACME (distinct challenge values,
a failed challenge is retried).
6.5 Ephemeral RRsets¶
Roles may set an ephemeral TTL (Authorizer.EphemeralTTL). RRsets they create get
ExpiresAt; the reconciler deletes expired ones. This cleans up ACME challenge
records left behind by clients that do not clean up; the ACME endpoints refuse
callers whose role has no ephemeral TTL (ACME.md).
6.6 Reconcile¶
zonewrite.RunReconciler calls Engine.Reconcile(zone) for every managed zone at a
configurable interval (one GET per zone, within the rate budget):
- owned RRset whose upstream content differs from
ContentHash→tainted, alert; - owned RRset missing upstream →
tainted(deleted outside the gate); pendingentry → resolved:activeif upstream matchesPendingHash, otherwise rolled back to the previous state (the write did not happen);- expired ephemeral RRset → deleted upstream and from the store;
- side product: inventory of foreign RRsets per zone.
A tainted RRset stays blocked until an admin re-adopts it.