domain0 0.1.0

package/README.md

@@ -0,0 +1,629 @@
+# Domain0 TypeScript SDK
+
+This package contains Domain0's type-safe HTTP client,
+Zod contracts, and dependency-free embeddable connection UI.
+Node.js consumers require a currently supported Node.js 22 or newer release;
+browser consumers need standards-compliant `fetch`, Web Crypto, and `<dialog>`.
+
+The hosted platform uses two explicit trust boundaries. Keep the long-lived
+API key on the integrating server, then give the browser only short-lived,
+exact-origin access to one connection:
+
+```ts
+import { createDomain0PlatformClient } from 'domain0'
+
+const platform = createDomain0PlatformClient({
+  baseUrl: 'https://domain0.dev/api/domain0/',
+  apiKey: process.env.DOMAIN0_API_KEY!,
+})
+
+const { connection } = await platform.createConnection({
+  intent: {
+    domain: 'customer.example',
+    records: [{ host: 'app', type: 'CNAME', value: 'edge.example.com' }],
+  },
+})
+const access = await platform.issueConnectionToken(connection.id, {
+  origin: 'https://app.example.com',
+})
+```
+
+Use `forwardDomain0ConnectionRequest()` from `domain0/server` in a same-origin
+catch-all route. It forwards only browser-safe connection routes, strips
+cookies and API keys, caps request bodies, and preserves the exact origin.
+The browser constructs `createDomain0Client()` against that local route and
+opens `domain0.connectDomain()` with the returned connection ID.
+
+Webhook receivers can import the strict schema-v1 contract separately. The
+verifier authenticates untouched request bytes before parsing them:
+
+```ts
+import { verifyDomain0Webhook } from 'domain0/contracts'
+
+const event = await verifyDomain0Webhook({
+  body: new Uint8Array(await request.arrayBuffer()),
+  headers: request.headers,
+  secretKeyring: { 'webhook-v1': decoded32ByteSecret },
+})
+
+await processOnceInTransaction(event.eventId, () => applyEvent(event))
+```
+
+Keep the idempotency record and business change in one database transaction.
+Return 2xx when an event ID was already processed.
+
+```ts
+import { createDomain0Client } from 'domain0'
+
+const client = createDomain0Client({
+  baseUrl: 'https://domain0.example.com',
+  token: async () => obtainShortLivedConnectionToken(),
+})
+
+const connection = await client.getConnection(connectionId)
+
+const providerHealth = await client.getProviderHealth()
+for (const provider of providerHealth.providers) {
+  if (!provider.enabled) {
+    console.info(provider.providerName, provider.reason)
+  }
+}
+
+const currentDns = await client.checkRecords({
+  domain: 'example.com',
+  records: [{ host: 'www', type: 'CNAME', value: 'edge.example.net', ttl: 300 }],
+})
+
+const support = await client.checkDomain({
+  domain: 'example.com',
+  records: [{ host: 'www', type: 'CNAME', value: 'edge.example.net' }],
+  checkConflicts: true,
+})
+
+await client.authorizeWithCredential(connectionId, {
+  providerId: 'cloudflare',
+  credentials: {
+    kind: 'api_token',
+    token: obtainProviderToken(),
+  },
+  commandId: crypto.randomUUID(),
+})
+
+await client.cancelConnection(connectionId, {
+  commandId: crypto.randomUUID(),
+})
+
+if (connection.connection.state === 'failed_retryable') {
+  await client.retryConnection(connectionId, {
+    commandId: crypto.randomUUID(),
+  })
+}
+```
+
+An application-authenticated server can provision several exact-domain
+connections with one replay-safe command. A target uses either direct records
+or the conditional record shape—never both:
+
+```ts
+const created = await applicationClient.createConnectionFlow({
+  applicationId: 'application-1',
+  tenantId: 'tenant-1',
+  commandId: crypto.randomUUID(),
+  targets: [
+    {
+      domain: 'example.com',
+      records: [{ host: '@', type: 'A', value: '192.0.2.10', ttl: 300 }],
+    },
+    {
+      domain: 'docs.example.net',
+      conditionalRecords: {
+        domain: [{ host: '@', type: 'CNAME', value: 'fallback.example.net' }],
+        subDomain: [{ host: '@', type: 'CNAME', value: 'edge.example.net' }],
+        rootNS: [{ host: '@', type: 'NS', value: 'ns1.example.net' }],
+      },
+    },
+  ],
+})
+
+await domain0.connectDomains({
+  client: browserConnectionClient,
+  flowId: created.flow.id,
+})
+```
+
+`connectDomains()` reuses the same single-domain controller for one child at a
+time and announces fixed “Domain N of total” progress. Closing does not delete
+server state; reopening the flow ID reloads its durable child references.
+Domain0 derives the registrable-root boundary and resolves `rootNS` only after
+the selected provider's catalogued capability is `supported`. Unverified or
+unsupported providers fall back to `subDomain`, then `domain`; callers cannot
+override either decision.
+
+An application-authenticated server can create a time-bounded handoff for an
+existing connection. The URL fragment is not sent in HTTP requests or ordinary
+access logs:
+
+```ts
+import { createSharedFlowUrl, loadSharedFlow } from 'domain0'
+
+const shared = await applicationClient.createSharedFlow({
+  connectionId,
+  expiresAt: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+})
+const link = createSharedFlowUrl('https://app.example.com/connect', shared.token)
+
+const loaded = await loadSharedFlow({
+  baseUrl: 'https://domain0.example.com',
+  url: link,
+  origin: window.location.origin,
+})
+await loaded.client.getConnection(loaded.connectionId)
+```
+
+`mountDomain0SharedFlow()` combines resolution with the same dependency-free
+connection UI. Shared-flow storage contains only ownership identifiers, a
+SHA-256 token digest, and timestamps—never the bearer token, DNS configuration,
+or provider credentials. Invalid and expired tokens are indistinguishable.
+
+Every request is validated before transmission and every successful or error
+response is parsed at runtime. The SDK rejects non-HTTPS base URLs except
+loopback development addresses. Base URLs cannot contain user information,
+query parameters, or fragments, and bearer tokens must match RFC 6750's ASCII
+token grammar before `fetch` is called. Keep application API tokens on the server;
+browsers should receive only short-lived, exact-origin, connection-scoped
+tokens. Credential shapes are a provider-discriminated Zod union, so an
+unsupported provider or credential kind fails before a request is sent.
+`getProviderHealth()` returns every reviewed provider and matches Entri's
+`enabled` compatibility field while adding strict `status`, `reason`,
+`observedAt`, and `refreshAfter` semantics. Enabled means that this Domain0
+deployment exposes a verified non-manual setup path. It is not an upstream
+uptime probe and does not promote an unverified provider.
+`checkRecords()` is an application-token-only, read-only authoritative DNS
+check. It does not create a connection, write provider state, or treat a
+recursive resolver answer as propagation proof; each result reports how many
+authoritative nameservers returned the requested value.
+`checkDomain()` has the same application-token-only boundary. It reports
+`delegated`, `undelegated`, or `unknown` DNS state; provider candidates;
+deployment-backed setup availability; and optional conflict analysis. A
+`partial` analysis means at least one authoritative nameserver could not
+complete every required query, so callers must not treat the result as proof
+that no conflict exists. Domain0 deliberately does not expose `registered` or
+`expired` booleans from DNS evidence because delegation cannot prove either.
+The same union covers API tokens, access-key pairs, username/password,
+account/token, username/token, OVH AK/AS/CK, TransIP PEM keys, temporary AWS
+sessions with explicit expiry, and provider-scoped cPanel credentials.
+Cancellation is an idempotent, typed operation for non-terminal connections;
+it does not reverse DNS records that a provider may already have applied.
+Retry does not blindly repeat a provider mutation. It restores the exact
+pre-failure checkpoint, after which the integrating application or UI starts a
+fresh snapshot or reconciliation attempt explicitly.
+
+SPF conflict handling is explicit and typed when preparing a plan. `merge` is
+the safe default and combines unique mechanisms, choosing `~all` when existing
+and requested terminal policies disagree. `replace` uses the requested SPF
+record as-is, marks the change destructive, emits a plan warning, and still
+requires the separate destructive confirmation step:
+
+```ts
+await client.preparePlan(connectionId, {
+  conflictPolicy: 'preserve',
+  spfPolicy: 'replace',
+  commandId: crypto.randomUUID(),
+})
+```
+
+Advanced DMARC options are attached only to a valid `_dmarc` TXT record. They
+are strict application configuration, not arbitrary UI input:
+
+```ts
+await applicationClient.createConnection({
+  applicationId: 'application-1',
+  tenantId: 'tenant-1',
+  commandId: crypto.randomUUID(),
+  intent: {
+    domain: 'mail.example.com',
+    records: [{
+      host: '_dmarc',
+      type: 'TXT',
+      value: 'v=DMARC1; p=none',
+      ttl: 300,
+      advancedDmarcOptions: {
+        inheritRootDmarc: true,
+        overrideTags: { p: 'quarantine' },
+        removeTags: ['pct'],
+        addTagsIfNotExist: { aspf: 's' },
+      },
+    }],
+  },
+})
+```
+
+Planning preserves this requested intent and returns `effectiveIntent` after
+reading existing provider records and, when requested, the registrable root's
+public DMARC TXT record. Guided manual setup resolves the same policy from
+authoritative public DNS. The UI always displays the effective records that
+propagation verification will check. If an existing or inherited DMARC policy
+is invalid or ambiguous, Domain0 uses the supplied valid `value` unchanged
+instead of partially rewriting it.
+
+Existing-record checks are a separate strict policy on the requested intent:
+
+```ts
+await applicationClient.createConnection({
+  applicationId: 'application-1',
+  tenantId: 'tenant-1',
+  commandId: crypto.randomUUID(),
+  intent: {
+    domain: 'example.com',
+    existingRecordPolicy: {
+      validateDmarc: true,
+      validateCAA: true,
+    },
+    records: [
+      { host: '_dmarc', type: 'TXT', value: 'v=DMARC1; p=reject' },
+      { host: '@', type: 'CAA', value: '0 issue letsencrypt.org' },
+    ],
+  },
+})
+```
+
+`validateDmarc` preserves an exactly-one valid DMARC policy at the requested
+host. `validateCAA` includes a requested CAA record only when that host already
+has CAA. Both default to `false`. If every requested record is suppressed, the
+response contains `effectiveIntent.records: []`; the UI explains that no DNS
+changes are required and verification completes without querying DNS. The same
+policy may be supplied at the top level of `createConnectionFlow()` and is
+persisted on every child connection.
+
+Every provider descriptor includes a validated HTTPS `referenceUrl`. The
+embeddable UI opens it in a new tab with an explicit accessible label and
+`noopener noreferrer`. This link helps users find provider-specific material;
+it is not a claim that the provider has passed automatic conformance.
+
+`provider.capabilities.rootNSModification` is always one of `supported`,
+`unsupported`, or `unverified`. Domain0 exposes the assessment but never uses
+it to resolve records in the browser. Conditional intent is resolved by the
+backend when the provider is selected, preventing a caller from claiming a
+capability the provider has not proved.
+
+The framework-neutral UI exposes fully typed `onStepChange`, `onSuccess`, and
+`onClose` lifecycle callbacks. Step events are deduplicated, success is emitted
+once per open modal session, and close events distinguish the close button,
+Escape, programmatic close, and destruction. The lower-level
+`onConnectionChange` observer is revision-aware and does not repeat an
+unchanged connection.
+
+For an Entri-style high-level lifecycle, use the singleton `domain0` export or
+create an isolated instance with `createDomain0()`. `connectDomain()` mounts
+and opens the flow immediately, `close()` closes the active modal,
+`destroy()` also removes its DOM root, and a later connection replaces the
+previous one without leaving duplicate roots. `load()` is an asynchronous
+preflight for API parity; the npm package is already bundled when imported.
+
+```ts
+import { createDomain0Client, domain0 } from 'domain0'
+
+await domain0.load()
+
+const client = createDomain0Client({
+  baseUrl: 'https://domain0.example.com',
+  token: async () => obtainShortLivedConnectionToken(),
+})
+
+await domain0.connectDomain({ client, connectionId })
+
+// Later, if the host application needs to dismiss the active flow:
+domain0.close()
+```
+
+### DKIM email-provider guidance
+
+The lower-level client exposes a connection-scoped, read-only query. The
+backend loads the tenant-owned connection and derives its domain; callers can
+only add bounded selectors to inspect:
+
+```ts
+import { DkimSelectorSchema } from 'domain0'
+
+const guidance = await client.getDkimGuidance(connectionId, {
+  selectors: [DkimSelectorSchema.parse('mail-2026')],
+})
+
+if (guidance.detectionStatus === 'detected') {
+  console.info(guidance.provider.name, guidance.dkimDns.status)
+}
+```
+
+Set `enableDkim` to render the same guidance only after the connection becomes
+active. Known account-specific selectors can be supplied explicitly:
+
+```ts
+await domain0.connectDomain({
+  client,
+  connectionId,
+  enableDkim: true,
+  dkimSelectors: [DkimSelectorSchema.parse('mail-2026')],
+  onDkimSetupDocumentationClick: ({ provider }) => {
+    analytics.track('dkim_guide_opened', { provider: provider.id })
+  },
+})
+```
+
+MX evidence is bounded to Google Workspace, Microsoft 365, and Zoho Mail.
+Documentation URLs are a fixed discriminated union of their official guides,
+not network-provided links. `record_observed` means only that a TXT or CNAME
+was observed for a checked selector. `no_record_observed` is equally narrow:
+it does not prove DKIM is disabled because selectors can differ. The UI states
+that provider-admin status must be checked and never reports signing as enabled
+or disabled.
+
+### Locale and fallback contract
+
+Every connection entry point accepts a strict `locale`. The Zod-derived
+`Domain0Locale` contract mirrors Entri Connect's current identifiers:
+`en`, `es`, `pt`, `pt-br`, `pt-pt`, `fr`, `it`, `de`, `nl`, `pl`, `tr`,
+`ja`, `da`, and `sv`. The default is `en`; `pt` uses Brazilian Portuguese
+formatting (`pt-BR`). Unknown or region-expanded values such as `en-US` are
+rejected instead of being guessed.
+
+```ts
+await domain0.connectDomain({
+  client,
+  connectionId,
+  locale: 'de',
+})
+```
+
+Domain0 currently ships complete English, Spanish, Brazilian Portuguese,
+European Portuguese, French, and German message catalogs. The
+other accepted Entri identifiers use the English built-in catalog until their
+native catalog is complete. This fallback is exposed by
+`createDomain0Localizer(locale).translatedLocale`, so hosts and tests can
+observe it instead of assuming a translation exists. Each mounted controller
+owns its immutable localizer, writes the requested BCP 47 language tag and
+direction to its root, uses `Intl` for numbers and visible dates, and preserves
+machine-readable ISO values in native `<time datetime>` elements. Provider
+detection explanations, plan warnings, API failures, transport failures, and
+protocol failures are rendered from exhaustive typed mappings; raw server or
+adapter messages remain diagnostic data and never become visible copy. The current
+Entri locale set is left-to-right; the renderer nevertheless uses logical CSS
+alignment so a future RTL locale does not require a layout rewrite.
+
+### Typed browser events
+
+Every lifecycle event is available through the strict Zod-discriminated
+`onEvent` stream. The existing focused callbacks remain available:
+
+```ts
+await domain0.connectDomain({
+  client,
+  connectionId,
+  onEvent: (event) => {
+    switch (event.type) {
+      case 'success':
+      case 'close':
+      case 'step_change':
+      case 'manual_setup_documentation_click':
+      case 'dkim_setup_documentation_click':
+      case 'request_close':
+      case 'shared_flow_sent':
+        analytics.track(event.type, event)
+        break
+    }
+  },
+  onRequestClose: async () => {
+    if (await confirmExit()) {
+      domain0.close()
+    }
+  },
+})
+```
+
+Providing `onRequestClose` intercepts only the in-widget Close button. The
+modal remains open until the host closes it, and `onClose` fires only after the
+real close. Manual-guide events fire only from the manual instructions screen.
+
+To display the manual screen's **Copy secure setup link** action, provide a
+`sharedFlowGateway.create` adapter that calls an application-authenticated host
+endpoint. It returns `{ sharedFlowId, url, expiresAt }`; Domain0 validates the
+capability-fragment URL and expiry, copies it, then emits `shared_flow_sent`.
+Application tokens must never be placed in this browser gateway.
+
+`manualSetupDocumentation` replaces the manual screen's generic provider guide
+with a bounded, credential-free HTTPS application guide. It renders as a native
+anchor with descriptive visible text, explicit new-tab wording, and
+`noopener noreferrer`; activation still emits
+`manual_setup_documentation_click`:
+
+```ts
+await domain0.connectDomain({
+  client,
+  connectionId,
+  manualSetupDocumentation: 'https://docs.example.com/dns/setup',
+})
+```
+
+Set `whiteLabel.copy.manuallyScreen.disableManualSetupDocumentationLink` to
+replace navigation with a native **Get step-by-step DNS help** action. The
+action is rendered only when `onEvent` or
+`onManualSetupDocumentationClick` can handle it, so the UI never presents an
+inert link-shaped control.
+
+### White-label theme and copy
+
+`connectDomain()` and `loadSharedFlow()` accept the same `whiteLabel` input.
+The exported `Domain0WhiteLabelSchema` is the runtime source of truth and
+`Domain0WhiteLabelInput` is inferred from it. Theme values are semantic tokens,
+not raw CSS:
+
+```ts
+await domain0.connectDomain({
+  client,
+  connectionId,
+  applicationName: 'Example Hosting',
+  whiteLabel: {
+    logo: 'https://assets.example.com/logo.svg',
+    logoBackgroundColor: '#FFFFFF',
+    removeLogoBorder: false,
+    hideCompanyLogo: false,
+    hideCompanyName: false,
+    theme: {
+      colorMode: 'system',
+      light: {
+        primary: '#003366',
+        onPrimary: '#FFFFFF',
+        link: '#003366',
+      },
+      dark: {
+        primary: '#DBEAFE',
+      },
+      widthPx: 720,
+      dialogRadiusPx: 16,
+      buttonRadiusPx: 6,
+      inputRadiusPx: 6,
+      fontFamily: 'Inter, system-ui, sans-serif',
+      fontWeight: 400,
+      boldFontWeight: 650,
+    },
+    copy: {
+      initialSubtitle: {
+        en: 'Connect DNS without leaving this application.',
+        de: 'Verbinden Sie DNS, ohne diese Anwendung zu verlassen.',
+      },
+      providerLoginMessage: {
+        en: 'Continue securely with {PROVIDER}.',
+        de: 'Sicher mit {PROVIDER} fortfahren.',
+      },
+      successTitle: {
+        en: '{DOMAIN} is ready',
+        de: '{DOMAIN} ist bereit',
+      },
+      successDescription: {
+        en: 'Required DNS records for {DOMAIN} are live.',
+        de: 'Die erforderlichen DNS-Einträge für {DOMAIN} sind aktiv.',
+      },
+      successButton: { en: 'Done', de: 'Fertig' },
+      manuallyScreen: {
+        disableManualSetupDocumentationLink: false,
+        stepByStepGuide: {
+          en: 'Open our DNS setup guide',
+          de: 'Unsere DNS-Einrichtungsanleitung öffnen',
+        },
+      },
+    },
+    removeShareLogin: false,
+    skipCongratulationsScreen: false,
+    customProperties: {
+      manualConfiguration: { disableScreen: false },
+      providerLogin: {
+        forwardLink: { disable: false },
+        gotoManualLink: { disable: false },
+      },
+    },
+  },
+})
+```
+
+Each effective light and dark palette must keep body, secondary, link, error,
+and button text at least 4.5:1 against its paired surface. Control boundaries
+and focus indicators must reach 3:1. Colors are opaque `#RRGGBB` values;
+the backdrop is `#RRGGBBAA`. Dimensions are bounded numbers and the font is a
+validated local system-font stack, so the UI never evaluates caller-provided
+CSS or fetches a font. Localized copy requires an `en` value, falls back to it
+when the active locale is missing, is inserted only with `textContent`, rejects
+HTML and control characters, and supports only `{PROVIDER}` or `{DOMAIN}` in
+the fields that document those placeholders. A plain string remains a
+backward-compatible shorthand for `{ en: value }`.
+
+The behavior names above match Entri's current public configuration where
+Domain0 has an equivalent safe action:
+
+- `removeShareLogin` and `providerLogin.forwardLink.disable` suppress the
+  manual screen's shared-link handoff;
+- `providerLogin.gotoManualLink.disable` removes entry into guided manual
+  setup and renders an explicit explanation;
+- `manualConfiguration.disableScreen` blocks an already persisted
+  `manual_required` screen without rendering DNS records, provider guides, or
+  sharing; it does not rewrite or advance connection state; and
+- `skipCongratulationsScreen` emits `step_change(active)` and `success`, closes
+  with reason `success`, and restores the host invoker without rendering the
+  success screen.
+
+The combined `Domain0ConnectConfigurationSchema` rejects forced-manual mode
+when manual entry or its screen is disabled, and rejects `enableDkim` with a
+skipped success screen because that screen owns the DKIM guidance. Unknown
+controls are rejected. In particular, Domain0 does not support Entri's
+`existingRecords.disableScreen`: change-plan confirmation and the separate
+destructive acknowledgement are never auto-confirmed.
+
+`copy.manuallyScreen.stepByStepGuide` customizes the visible guide-link or
+host-action label with the same strict locale-keyed English fallback as other
+copy. Domain0 accepts plain text only and deliberately rejects Entri's embedded
+`<link>` markup; native anchor/button semantics remain renderer-owned.
+
+`logo` accepts only a bounded HTTPS URL without embedded credentials.
+`hideCompanyLogo: true` prevents creation of the image element, so no logo
+request occurs. A visible logo uses `referrerPolicy="no-referrer"`; this hides
+the application URL but cannot hide the user's IP address or user agent from
+the logo host. Self-host the asset on the application origin when that
+disclosure is unacceptable. `applicationName` supplies visible company text
+and the logo's accessible alternative when the name itself is hidden.
+`logoBackgroundColor`, `removeLogoBorder`, `hideCompanyLogo`, and
+`hideCompanyName` match Entri's current new-UI fields.
+
+External font loading and native catalogs beyond English, Spanish, Brazilian
+Portuguese, European Portuguese, French, and German remain
+outside this contract pending their separate privacy and translation gates.
+
+### Forced manual setup
+
+Use the typed setup policy when the host product must always show manual DNS
+instructions, even for a provider with an automatic adapter:
+
+```ts
+await domain0.connectDomain({
+  client,
+  connectionId,
+  setupPolicy: { mode: 'manual' },
+})
+```
+
+Domain0 already receives the exact domain and DNS intent from the server-created
+connection, so it does not collect a duplicate `prefilledDomain` in the browser.
+After provider confirmation, the UI calls the existing
+`startManualConfiguration()` use case and renders the exact record table. It
+does not call OAuth, accept provider credentials, prepare a plan, or apply DNS.
+The user still explicitly reports completion and Domain0 still queries every
+authoritative nameserver before activation.
+
+Forced manual mode affects only a connection that has not entered an automatic
+workflow. If an existing connection is already authorizing, planning, applying,
+or recovering from an automatic provider timeout, the UI blocks that workflow
+and asks the user to cancel and create a new manual connection. It never rewinds
+or reinterprets persisted connection state.
+
+The application token remains on the integrating server. The browser lifecycle
+receives only a connection-scoped client, or resolves an opaque shared-flow
+fragment directly:
+
+```ts
+await domain0.loadSharedFlow({
+  apiBaseUrl: 'https://domain0.example.com',
+  url: window.location.href,
+})
+```
+
+For a provider whose evidence state is `domain_connect`, pass the integrating
+application's onboarded template as `domainConnectTemplate`. The backend
+checks support for that exact template and returns a reviewed provider handoff;
+the UI never treats the handoff or user return as propagation success.
+
+The package name is `domain0` and its license is Apache-2.0. Releases are
+versioned through reviewed Changesets pull requests and published from the
+verified GitHub Actions artifact with npm Trusted Publishing.
+`bun run test:browser` builds the package and exercises native modal keyboard
+behavior, dark mode, and 320 CSS-pixel reflow in pinned Chromium, Firefox, and
+WebKit, including the high-level lifecycle; Forced Colors is emulated in
+Chromium. Run the Domain0 repository's
+remaining real-platform and assistive-technology checklist before treating a
+packed SDK as accessibility-verified.