Glossary

The words DomainKit uses for requirements, plans, approvals, receipts, connections, attachments, and observation.

Look up the words DomainKit uses for the custom domain lifecycle. Every page, type name, and error message uses them the same way.

The lifecycle

Requirement — DNS state your product needs: a record, its policy (exclusive or append), an optional purpose label for the customer, and, on a TXT record made with DnsRecord.spf, an SPF constraint. A DnsRecord.Model.

Plan — a snapshot of one zone as exact operations, with a deterministic digest over them. Its operations are Create, Noop, Conflict, and, for cleanup, Delete. A Plan.Model.

Approval — a principal’s consent to apply one plan digest and one explicit set of operations. Apply accepts nothing else. An Approval.Model.

Rejection — the record that a principal declined a plan: who, optionally why, and when. It is terminal for that plan, and the domain stays free for a new one.

Receipt — durable evidence of what an apply actually wrote, with one outcome per operation and a status of complete or partial. Cleanup is planned only from a receipt. A Receipt.Model.

Digest — the SHA-256 hash of a plan’s version, kind, domain, zone, provider, attachment ID, and operations. An approval names a digest, and apply refuses when the zone no longer produces it. Requirement labels are not part of it.

Attempt — one durable plan, approval, and receipt with a status, so a host can plan in one request, collect consent in another, and apply in a third.

Batch — several domains planned together, with one digest and one consent, that each keep their own attempt. Create one with Provision.batch.create.

The connection

Provider authorization — an account-scoped credential plus the non-secret provider context needed to rebuild a session. Stored sealed; DomainKit never writes plaintext.

Connection — the principal-facing handle over one authorization. One authorization can back several connections, and one connection can serve several domains.

Domain attachment — one domain bound to one connection and one exact provider target: the zone and the provider identity that addresses it.

Continuation — the state held between starting an interactive connection and the provider’s callback. It is spent exactly once.

Target — a zone the credential can reach, with the provider context that addresses it and, when the provider reports them, its nameservers.

Discovery — which of a principal’s existing connections already reaches a domain, decided from the domain’s authoritative nameservers and each connection’s zones. When none does, it names the registered provider whose declared nameserver suffixes cover the delegation as the domain’s host.

Observation

Observation — a single reading of DNS from one source, tagged with where it came from: Provider (the provider’s own records), PublicDns (one recursive resolver), or Host (something only your app can see, such as a certificate or an email identity).

Readiness — the stored per-requirement status for a domain, the evidence behind each status, and nextCheckAt, the time to look again.

Requirement status — satisfied (an exact match), missing (nothing matched), mismatch (an exclusive requirement met another record at the same name and type, or an SPF requirement met a different or duplicate SPF record), or unknown (no source answered).

The seams your app fills

Principal — { ownerId, actorId } for the request being served. ownerId is the tenant boundary every stored row is scoped by; actorId is recorded on approvals and rejections.

Storage — every durable row, behind one service. @domainkit/capsuledb implements it on PostgreSQL; Storage.layerMemory is the in-memory one; Storage.layerFromAsync wraps your own.

Custody — sealing a credential before Storage sees it. AES-256-GCM from one configured key by default, or your KMS.

Identity — the one server-side service you write: a request to a Principal, by verifying a credential your app issued.

Transport — the browser-side view of the mounted routes, split into optional capability groups (connection, provisioning, verification, cleanup).

What DomainKit is not

DomainKit is not a DNS host, a registrar, a universal provider abstraction, or an automatic DNS reconciler. Provider writes are not atomic, transactional, or rollback-safe: a plan is applied operation by operation, and a partial receipt says exactly how far it got.