basalt / tenancy/src / CustomDomains
Class: CustomDomains
Defined in: tenancy/src/custom-domains.ts:279
Constructors
Constructor
> new CustomDomains(options?): CustomDomains
Defined in: tenancy/src/custom-domains.ts:288
Parameters
options?
CustomDomainsOptions = {}
Returns
CustomDomains
Methods
add()
> add(tenantId, domain): Promise<{ dns: DnsVerification; record: CustomDomain; }>
Defined in: tenancy/src/custom-domains.ts:324
Register a domain for a tenant (unverified). Returns it plus the DNS record to publish.
Refuses a value that is not a hostname (InvalidDomainError) and the platform's own domains (DomainReservedError). A domain another tenant holds is refused with DomainTakenError — unless that claim is unverified and either older than claimTtlMs, or the caller has already published its challenge TXT record (then the caller gets it, verified). A verified claim yields only to a published challenge record when the incumbent's own TXT record is gone (see reverify).
Parameters
tenantId
string
domain
string
Returns
Promise<{ dns: DnsVerification; record: CustomDomain; }>
challenge()
> challenge(tenantId, domain): DnsVerification
Defined in: tenancy/src/custom-domains.ts:353
The DNS record tenantId publishes to prove it owns domain while another tenant holds an unverified claim on it. Once it resolves, add() hands the domain over. Requires challengeSecret.
Parameters
tenantId
string
domain
string
Returns
instructions()
> instructions(tenantId, domain): Promise<DnsVerification>
Defined in: tenancy/src/custom-domains.ts:482
The DNS record for one of the tenant's OWN domains (to show them again).
Parameters
tenantId
string
domain
string
Returns
Promise<DnsVerification>
list()
> list(tenantId): Promise<CustomDomain[]>
Defined in: tenancy/src/custom-domains.ts:505
Parameters
tenantId
string
Returns
Promise<CustomDomain[]>
remove()
> remove(tenantId, domain): Promise<void>
Defined in: tenancy/src/custom-domains.ts:510
Remove one of the tenant's OWN domains (asserts ownership first).
Parameters
tenantId
string
domain
string
Returns
Promise<void>
reverify()
> reverify(domain): Promise<DomainReverification | null>
Defined in: tenancy/src/custom-domains.ts:432
SYSTEM-ONLY: re-check the TXT record of whichever tenant holds domain and un-verify the claim when the record is definitively gone. Unlike verify(tenantId, domain, { force: true }) it needs no tenant id, and a failed lookup (timeout, SERVFAIL) leaves the claim verified (dns-error). The un-verify is conditional (DomainStore.replace when available), so a claim that changed hands meanwhile is left alone (changed).
Run it — or reverifyAll — on a schedule: a verified domain whose owner let it lapse otherwise keeps resolving to them (dangling-domain takeover), and a new owner can then claim it through add(). Returns null for a domain nobody holds.
Parameters
domain
string
Returns
Promise<DomainReverification | null>
reverifyAll()
> reverifyAll(options?): Promise<DomainReverifySummary>
Defined in: tenancy/src/custom-domains.ts:462
SYSTEM-ONLY: reverify every verified domain — from DomainStore.listVerified(), or the domains you pass (required when the store does not implement it). Sequential, so a large portfolio does not burst the resolver. Meant for a scheduled job:
scheduler.every('1h', async () => {
const { revoked, errors } = await customDomains.reverifyAll()
if (revoked.length) log.warn({ revoked }, 'custom domains un-verified')
})Parameters
options?
domains?
Iterable<string, any, any>
Returns
Promise<DomainReverifySummary>
tenantOf()
> tenantOf(domain): Promise<string | null>
Defined in: tenancy/src/custom-domains.ts:516
The tenant id a verified domain maps to — wire this into TenantSource.findByDomain.
Parameters
domain
string
Returns
Promise<string | null>
verify()
> verify(tenantId, domain, options?): Promise<boolean>
Defined in: tenancy/src/custom-domains.ts:494
Check the TXT record for one of the tenant's OWN domains and (un)mark it verified. Already-verified domains short-circuit unless force is set — pass force on a schedule to catch a domain whose DNS was later removed/repointed (defence against dangling-domain takeover); on a failed re-check it is un-verified so it stops resolving.
Parameters
tenantId
string
domain
string
options?
force?
boolean
Returns
Promise<boolean>