Provider authorization and domain grants

Understand how provider credentials, account context, host owners, domain grants, reusable connections, continuations, and revocation fit together.

Connecting a DNS provider crosses two authority systems: the provider’s account and scopes, and the host application’s users, tenants, and domains. DomainKit keeps those systems explicit instead of equating one provider token with one product domain.

The authorization aggregate

A durable provider authorization contains:

the provider and account identity;
non-secret provider context needed to reconstruct the correct client;
a reference to the host-stored credential;
required capabilities and their evidence;
expiry and revocation state;
one or more host-owner bindings and grants.

The credential is part of one logical aggregate, but DomainKit does not choose how the host encrypts or persists it.

Owner bindings and grants

A provider authorization can be bound to a host owner with:

an account-wide grant, optionally excluding domains; or
an explicit set of domain grants.

The grant is enforced in addition to provider scopes. A broad Cloudflare or Vercel credential does not automatically authorize every host tenant or every visible zone.

This separation allows one valid provider authorization to serve another domain for the same owner without repeating provider consent.

Starting and completing a connection

Connection.start accepts a token method or an interactive provider flow:

token
  -> validate provider authority
  -> commit authorization aggregate

interactive
  -> create one-time continuation
  -> redirect to provider
  -> consume callback continuation
  -> exchange code
  -> commit authorization aggregate

Cloudflare implements standards-based OAuth and scoped API tokens. Vercel implements its provider-specific Integration installation flow and tokens. DomainKit does not label every redirect/code exchange as generic OAuth.

Reusing provider authority

Connection.extend adds a new domain grant only after the host:

loads an authorization owned by the same host owner;
proves the provider authorization can serve the requested domain;
obtains the owner’s consent for the new grant.

Reuse preserves earlier grants. It rejects cross-owner, expired, insufficient, or revoking authorizations.

Removing a domain

Removing one domain binding preserves the other bindings and normally preserves DNS. If the removed binding was the last one, the authorization lifecycle attempts provider revocation before deleting the durable authorization and credential state.

Revocation is fail-closed. Durable retry state remains until the provider confirms the outcome.

Host-owned boundaries

The host supplies:

authenticated start, callback, token, reuse, and disconnect routes;
user and tenant authorization policy;
one durable AuthorizationLifecycle.Repository;
credential encryption or vault storage;
a short-lived, one-time continuation store;
consent records and audit history.

A SQL application can implement the aggregate commit as one transaction. A split database/vault application must implement a recoverable saga behind the same repository boundary.

Capability evidence

Provider scope strings are not treated as complete proof. Required capabilities record one of three evidence levels:

Declared — the host or provider flow claims the capability;
Introspected — a provider response reported it;
Exercised — a successful provider operation demonstrated it.

The host can promote evidence after successful use without changing the underlying grant model.