Instance catch-alls: <label>.<parent> serves the app's instance <label>

Date: 2026-10-05 Status: branch instance-catchall on amadan, not landed. Revised after the review on #233 (§8).

1. Problem

Jelly (lazyatom/jam) runs one instance of dev-managed-jelly per team, at <team>.bad.carlos.exciting.io. Teams should also answer at <team>.letsjelly.dev. Today the manager makes that happen with one exact claim per team at signup (AttachDomain in manager/carlos.go), plus a wait for DNS. The existing catch-all (Wildcard+Catchall on a claim) cannot do it, because it sends every subdomain to ONE route (domains.ReconcileAliases, the *.<host> → primary row). It cannot fan out to per-team instances, and it belongs to whoever holds the apex claim. Here that is the static site dev-jelly-site.

2. Design

The claim. An instance catch-all is a domains.Claim at the key domains/*.<parent>.json, with Host: "*.<parent>", Account, App, Instances: true and nothing else: no Route, Wildcard, Catchall or Paths.

• The star in the key means there is one catch-all per parent, held by the same create-only bucket-key gate that every claim uses.
• No attach door accepts a * (NormalizeAliasHost), so a catch-all can never collide with an ordinary claim.

The door. carlos domains attach --app <a> '*.<parent>' (API: the existing attach body with host: "*.<parent>"). detach removes it the same way. Writing a catch-all requires all of these:

1. A person (apiPerson), like carlos instances enable. A catch-all is standing policy over every unclaimed name under the parent. A credential the app holds must not be able to set it for itself. Without this, an app token could also put its instances under a sibling app's parent.
2. No route, kind, channel, wildcard, catchall or platform field in the request. They are refused, not ignored.
3. The app has an instance manifest. Without one it has nothing to serve. An app without one is also the only kind of app a rename can still move, which would leave the claim naming a dead app.
4. The parent passes catchallParentRefused. It refuses a parent when: - the parent is in a deny tier (reserved or platform, so operators are refused too); - any console, reserved or platform hostname is equal to the parent, under it, or above it. The box cannot see the deny lists, so a derived name could otherwise land on the tunnel host or a console host; - the parent is equal to the apps domain, under it, or above it. That space holds the account-sqid and app-apex names. This is checked whatever CONSOLE_RESERVE_PLATFORM_DOMAINS says: on a self-hosted box the apps domain is not reserved, and edge.<apps-domain> would otherwise be derivable; - the parent is a public suffix (co.uk, github.io); - the parent is under the sidecar suffix.
5. The parent's own claim is held by the same account, by any of its apps (domains.AttachInstanceCatchall). With wildcard DNS at the edge, a catch-all covers every unclaimed name under the parent at once, so only whoever already holds the parent may make one. If the parent has no claim at all, the request is refused: claim the parent first (an alias to any route of the account will do). Holding a catch-all in the same account but under a different app from the apex is the point of the design (static site at the apex, teams below it).

On the box. ReconcileAliases gains deriveInstanceAliases. For each catch-all whose parent is still claimed by the same account, it walks the box's local routes and derives one ordinary route_aliases row, <rt.Slug>.<parent> → rt.Host, for each route that meets every one of these:

• Provisioned, not a sidecar, and not a replica;
• the claim's own app, and the claim's own account (RouteAccount);
• a Slug that is a single DNS label and is the first label of the host. The instance create door makes every record this shape.

A derived name loses to, in this order:

1. any claim on that exact name, whoever holds it. This covers the manager's existing per-team claims, www, auth, and another account's claim made before the catch-all existed;
2. a real route on this box;
3. a real route on any live box (deploymentRoutes).

The desired set is rebuilt on every pass:

• a deleted or moved instance drops its name on the next pass;
• a detached catch-all drops every name;
• a released exact claim hands its name back to the catch-all.

Rows are written only when they change, so a steady state causes no edge reload. At most 1000 derived names per box (maxInstanceAliases), in a deterministic order, with the overflow logged (§4.11).

What the derived rows are. They are the same rows an exact alias claim for each name produces today: Alias, Host, Account, App. That is the property the rest of this note relies on. Every reader of route_aliases already handles such rows correctly, and none of them looks for a claim behind a row. The only code that deletes alias rows is the pass's own desired-set sweep. The edge itself needed only one change, made after review: the cross-box precedence fix in §8, item 5.

The attach guard. While a catch-all is live, the attach doors refuse other accounts the one-label names under its parent that it reserves (domains.ForeignInstanceCatchall, then catchallInstanceName in the console). A refused attach gets the neutral 409 from the same place deploymentRouteTaken gives it, in all three attach paths (API alias, form alias, first-route). What it reserves (§8, review P1s):

• Proved parent: every label. The account proves it controls the parent in DNS with TXT _carlos-catchall.<parent> = carlos-catchall-account=<sqid>. The value names the account, the same shape as the mail ownership proof (#216). - The guard checks the record live, so it follows the domain's DNS rather than a stamp taken once. - A lookup failure counts as "not proved": the narrower reservation, never a refusal. - carlos domains list reports reserves: all or reserves: instances on the catch-all's row, and names the record when it is missing.
• Unproved parent: the labels of the app's existing instances, under any instance domain the app has used. These are counted from the app's instance record keys, so a manifest-domain change does not orphan them.

• Why it exists. Without it, any account could attach acme.letsjelly.dev. Its exact claim would beat the derived name and take a live team's address. Attach needs no DNS proof, so nothing else stops that.
• Why an unproved parent holds less (first review, finding 3). Attach needs no DNS proof, so a parent claim proves nothing. Holding every label for an unproved parent would let one squatted apex claim plus a catch-all block the real domain owner from every name under it.
• One label only, because a catch-all serves one label only. Deeper names stay as open as they are today.
• The caller's own existing claim is never refused (review finding 1). A claim made before the catch-all keeps re-attaching and converging. titogo's router re-attaches every name on every pass. deploymentRouteTaken makes the same allowance.
• "Live" is the box's rule: the catch-all's parent is still claimed by its account. A catch-all whose parent was released, or has moved to another account, holds nothing. The parent's new holder may replace it (AttachInstanceCatchall overwrites a dead one).
• Read failures. A bucket read failure in the guard is a retryable 502. It is never a 409 (which would read as "held") and never a skipped guard.

Precedence is decided from the listing (review finding 2). The box decides "a claim on this name exists" from the bucket listing's keys, not from the claim bodies that decoded this pass. A body whose GET fails is still a claim, so a spurious store error cannot hand another account's name to a derived alias for a pass.

Certificates. Each derived name gets per-host HTTP-01/ALPN certificates exactly as exact aliases do: the cert warm orders them once DNS points here, and the first handshake orders one otherwise. A delegated wildcard certificate is optional on top, by setting --wildcard on the parent's own claim. It then covers every derived name on every box (§4.10).

3. Mixed versions

• An old box or old console reading a catch-all decodes a claim with no Route, no Wildcard and no Paths. Every pass already skips that shape. It logs nothing and makes no DNS lookup or ACME order for the literal *.<parent>. Certwarm drops *. hosts anyway.
• An old console lists the row with an empty route and "checking" state. Its Detach button answers 404, because NormalizeAliasHost refuses the star. No old door can rewrite the claim, for the same reason, so the unknown instances field cannot be stripped.
• Keys: * is safe in S3 keys, in DirStore on Linux, and through the fleet store door. canonicalKey accepts it, and aclRead and aclListScope already grant domains/** to fleet boxes. DirStore on Windows would refuse it, but no deployment bucket runs there.
• A new console with old boxes: the catch-all is inert until the boxes upgrade. The attach guard is already live at that point, so other accounts are refused names the boxes do not serve yet. That is harmless, and it is what the owner asked for.

4. Deployment types

Each item says whether it is affected and what guards it.

1. Flagship (console as an app, carloku.com, #209). Not affected unless a catch-all is made, and none can be made on the deployment's own zones: refused for everyone, operators included. The console's names, steering, tunnel and the apps domain are refused at, under and above the parent. There is no --platform form; it can be added if the flagship ever wants one.
2. Tito / titogo. Its router re-attaches hostnames with an instance token, and it cannot create or remove a catch-all: those are person-only. Store-mode custom instance domains (go.tito.io) are unaffected, since nothing derives without a catch-all. The re-attach loop pays one extra GET per attach (*.<parent> of the host, usually a 404). A Hetzner spurious 403 there is a retryable 502. Re-attach is idempotent, so the next pass succeeds.
3. Pages-hub one-route catch-all, and woodstar.app (apex plus Wildcard+Catchall, same app). Unaffected unless an instance catch-all is added on the same parent. If one is, derived exact names beat the route catch-all name by name (lookupIn: exact key first, then *.). That is same-account by construction, and it is the useful combination: unknown labels fall to the site, known ones to their team. - On woodstar it would take a PDS handle whose label matches an instance label, so do not combine the two there. - The ceecb3a9 self-removal loop cannot recur. Derived rows are exact names published with Alias: true, and DeploymentRoutes counts only Role==home && !Alias.
4. Self-hosted single box, and this hand-staged box. Same as above: nothing changes without a catch-all. The apps domain is refused as a parent even though it is not reserved there. Hand-added routes (carlos route add) are not Provisioned and derive nothing. That also keeps a legacy account-name column, which reads as ops, out of reach.
5. Customer fleets / carlos apps place. Fleet boxes read domains/** through the store door, so they derive for their own instances. The store door does not grant control/edges/, so deploymentRoutes is nil (permissive) there. This gap already exists for plain aliases, and the exact-claim skip still applies.
6. Multi-box, multi-region edges, the edges file. Derived rows publish exactly like exact aliases: only once StampHealth has stamped them pointing, and backhauled by remote edges to the home box. A new or moved name can take up to about 12 minutes to reach other edges (one stamp period plus one edges-file period). Exact claims have the same delay today; a single box serves at once. Duplicate publication (everywhere-class instances) folds to the first-sorted box, as for exact aliases.
7. Edge replicas, steering. - Replica rows are excluded explicitly (rt.Replica). A door-created replica carries the label as its Slug, so the Slug shape alone would not exclude it. - Steering looks at platform names only, and never at aliases or claims.
8. Instance moves. During the cut the source row is moving, and the edge and edges file skip it. After the flip the target box derives the name. The name follows the instance, as an exact alias claim would.
9. Hibernation and activation. An alias entry is its primary's upstream copied whole, route and hibernating included. A request on a derived name therefore wakes the instance itself, and metering, the gate and analytics are keyed on rt.Host. - The response cache keys on the requested host, so the app purges a derived name's entries with Carlos-Purge-Host. That is pre-existing for exact aliases. - The backend sees Host: <label>.<parent>, so the app must accept it. Jelly does today, via the exact claims.
10. Isolated exec, path-prefix maps. - Isolated exec: units and sockets are keyed on rt.Host, so it is unaffected. - Path-prefix maps: a derived name inherits its instance's map, as any alias does. A Paths claim on a derived name itself is an exact claim and suppresses the derived row.
11. Platform apps-domain wildcard, platform-domain claims (#209), reserved/deny lists, readings sweep, cert sweep, LE limits, alias-table growth, maxWildcardDomains. - parentsFor takes only platform/provisioned non-alias hosts, so derived names cannot mint platform parents. - The deny tiers are covered in §2. - The readings sweep (StampHealth) does one serial LookupHost per alias (3s timeout) every 5–6 minutes. Each alias adds about 140 bytes to the box's status snapshot, and readers skip a snapshot above 1 MiB. A skipped box also drops out of DeploymentRoutes and the edge-IP fold. That is why there is a per-box cap of 1000 derived names, logged when it is hit. - The cert sweep is expiry-only, and ownsCertName checks deploymentHost, not claims. - Let's Encrypt: without a wildcard, N instances means N new CT-logged certs against the registered domain's limit (50 per 7 days as of writing). About 200 teams take about four weeks of issuance; past the limit, certwarm backs off 12h per host. That is identical to today's per-team exact claims. The remedy is --wildcard on the parent claim, which needs CARLOS_ACME_DELEGATION_ZONE and a DNS provider. The testbed has neither. - The instance catch-all is not a Wildcard claim, so it takes no slot in maxWildcardDomains or maxDelegatedParents.
12. Trash, purge, rename and move of apps; instance delete with parked data. - Trash drops the app's routes, so the derived names go with them. The catch-all claim stays, as every claim does, and comes back to life on restore. - Purge never deletes domains/ (pre-existing for all claims). An orphaned catch-all keeps holding names under its parent for its account, and passes to a later app of the same name in the same account. Detach it before purging. - Rename only applies to never-shipped apps, and the door requires an instance manifest. - Account move leaves claims on the old account, which derive nothing (pre-existing). - Instance delete removes the route but keeps the parked data. The name drops, and comes back if the instance is recreated.

5. Security cases

• (a) A label colliding with another account's exact claim: the exact claim wins, on every box. A derived name is skipped whenever any claim exists for it. New claims of that kind are refused by the attach guard while the catch-all is live. Claims made before the catch-all keep working, so it cannot take a name away from anyone.
• (b) A sibling app's apex label: cannot happen. - Only the claim's own app's routes derive. - Sibling apex hosts are not under the parent. - The instance create door refuses a label that names a live or trashed sibling app, and apex.go refuses the name arriving afterwards.
• (c) A team's name taken before the team exists. - Proved parent: impossible while the catch-all is live, for every label, including a deleted team's. - Unproved parent: the name is protected once the instance exists. A foreign claim made before that wins, which is the first-come rule every claim has. - A same-account exact claim wins on purpose.
• (d) Races between the claim pass and the instance reconcile: both sides are rebuilt from scratch each pass, and every precedence check is made against the same pass's claim list and route table. A catch-all write racing a foreign attach can let both land; the exact claim then wins, which is the same outcome as (c). A parent released between the door's check and its write is caught by the box's parent re-check.
• (e) The parent changes hands: the old catch-all goes inert on the box, stops holding names at the door, and the new holder can replace it.
• (f) A derived alias pointing at another account's route: prevented by three filters, all of which stay: rt.App == c.App, RouteAccount(rt) == c.Account and rt.Provisioned.
• Abuse of the guard as a squat. - Unproved parent: the guard holds only names of instances that exist, each a real, rate-limited instance. That is the same class of squat as claiming those names directly. - Proved parent: holding every label takes write access to the parent's DNS, which is what owning the domain means. - Public suffixes are refused as parents either way.

7. Review

Reviewed by an Opus agent before landing. Three medium findings were all fixed, each with a test that was watched to fail first where practical:

1. The guard refused an account's re-attach of its own older claim.
2. Precedence was decided from decoded bodies, which fails open on a read error.
3. The guard held every label, which amplified a squat.

Lows taken:

• the browser form now refuses a channel on a catch-all.

Lows left as they are:

• Member, not owner, on the API door. The API door admits any person in the account, the browser door only owners. That is the same split ordinary attach has.
• A reassigned name keeps its old dns_status until the next stamp. Pre-existing for exact claims changing hands.
• Once-per-process refusal logs do not repeat if a catch-all recovers and fails again.

8. Second review (#233, Paul's agent with Astra)

Two P1s and three P2s. Every one was checked against the code and found real, and all five are fixed with tests that were watched to fail first.

1. P1: a team's name could be taken before the team exists. Wildcard DNS points every label at the edge, and attach needs no proof. Fixed: a proved parent reserves every label (§2, the attach guard).
2. P1: the guard checked only the current manifest domain. Fixed: the guard counts the app's instance record keys by first label, across every instance domain (domains.InstanceLabelCounts), with one listing and no record bodies.
3. P2: a duplicate label routed differently per box. Two instances sharing a label, possible only after an instance-domain change, were each named by the box that held them. Fixed: a label shared by two records derives nothing, on every box alike, and the refusal is logged. - Seen from the same record listing, asked once per catch-all and only when the box has an instance to name. - If the listing fails, the catch-all's existing rows are kept for that pass, never dropped. - The earlier "first in host order wins" text is withdrawn.
4. P2: an old owner's detach could delete the new owner's catch-all. This happened after the parent changed hands and the catch-all was replaced in place. Fixed: DetachClaim deletes an instance catch-all only at the revision it read (release.DeleteIfMatch). - Ordinary claims are unchanged. They cannot be replaced while held, so the race does not exist for them. - Both production stores (S3, DirStore) support the conditional delete.
5. P2: a route catch-all on one box beat an instance name on another. The local *.<parent> matched before backhaul was considered. Fixed in the edge: a local match made only through a star key now yields to another box's exact host (homeMap.ExactHome, then backhaul). - That is the single-box precedence, exact then star, extended across the deployment. - An arrived hop and a door call keep the local answer. - A two-box test covers it.

The review's answers to this note's asks:

• --platform catch-alls: keep refusing them.
• CLI spelling: agreed.
• "Delete now" leftovers: filed as their own discussion.

6. Surfaces

• CLI. The catch-all is spelled carlos domains attach --app <a> '*.<parent>' and carlos domains detach --app <a> '*.<parent>'. - The star is the mode, and no other flag combines with it. - This keeps the meaning of attach <host> as "this hostname now serves this app", and needs no new flag grammar. - --catchall stays the bool capability it is; --catchall instances would have made it a value flag and broken bare --catchall. - carlos domains list shows the catch-all row with mode instances, then each derived name the fleet reports, marked via *.<parent>.
• API. Same endpoints. The attach answer and list rows gain instances: true, and the list gains via on derived rows. Both are additive.
• Web UI. The app's Domains & TLS table shows the catch-all and its derived names. The page does not edit wildcard or catchall today, and the catch-all is person-only, so the page lets an owner attach and detach it the same way as any hostname: typing *.<parent> into the attach form.