domainkit 0.3.0 → 0.4.0

package/README.md

@@ -1,139 +1,72 @@
 # DomainKit
 
-DomainKit is a provider-independent TypeScript SDK for turning DNS requirements into reviewable,
-authorized provisioning plans. Products can connect customer domains without making one
-registrar's API or authorization model their architecture.
+Domain setup infrastructure for TypeScript SaaS applications.
 
-DomainKit is additive and fail-closed. It creates missing records, treats exact records as no-ops,
-reports incompatible state as a conflict, and never silently overwrites DNS. Every applied write is
-bound to an approved plan digest and recorded in a receipt that can authorize a separate cleanup.
+DomainKit turns DNS requirements into reviewable plans, requires explicit digest-bound
+authorization before writes, records applied changes in receipts, and uses those receipts to plan
+safe cleanup. It supports Cloudflare and Vercel without making either provider's API your product
+architecture.
 
-## Package shape
+## Install
 
-- `domainkit` — canonical Effect services, programs, schemas, and first-party providers;
-- `domainkit/promise` — secondary Promise facade for foreign runtime boundaries;
-- `domainkit/testing` — in-memory lifecycle capabilities and the provider conformance runner.
+```sh
+npm install domainkit effect@rc
+```
 
-The package is portable ESM built on Fetch, Web Crypto, and Web APIs. Effect is a peer dependency.
-Promise namespaces delegate to the Effect implementation rather than maintaining another planner,
-authorization engine, or verifier. There are no provider-specific subpaths: `Cloudflare` and
-`Vercel` are cohesive namespaces on each root.
+Node.js 24.10 or newer and Effect 4 are required.
 
 ## Plan, approve, and apply
 
 ```ts
+import { Digest, DnsRecord, DomainName, Provisioning } from "domainkit";
+import { InMemoryDnsProvider } from "domainkit/testing";
 import { Effect, Layer } from "effect";
-import { Digest, DnsProvider, Provisioning } from "domainkit";
-
-const program = Provisioning.create({
-  requirements,
-  target: Provisioning.Target.ExactZone({ zone: "example.com" }),
-}).pipe(
-  Effect.flatMap(({ plan }) =>
-    Provisioning.authorize(plan).pipe(
-      Effect.flatMap((authorization) => Provisioning.apply({ authorization, plan })),
-    ),
-  ),
-  Effect.provide(Layer.merge(Layer.succeed(DnsProvider.Service, provider), Digest.webCryptoLayer)),
-);
-```
-
-Promise consumers use the explicit secondary entry point at a JavaScript boundary:
 
-```ts
-import { Provisioning } from "domainkit/promise";
-
-const { plan } = await Provisioning.create({
-  provider,
-  requirements,
-  target: Provisioning.Target.ExactZone({ zone: "example.com" }),
+const requirement = DnsRecord.parse({
+  _tag: "CNAME",
+  metadata: {
+    ownership: "customer",
+    provenance: "product-onboarding",
+    purpose: "tracking",
+  },
+  name: "track.example.com",
+  policy: "exclusive",
+  target: "tracking.example.net",
+  ttl: 300,
 });
-```
-
-Use `DiscoverFromDomain` when the host has several authorized provider accounts. `ZoneDiscovery`
-checks the requested name and its parents, returns `Resolved`, `SelectionRequired`, or `NotFound`,
-and never guesses between ambiguous accounts.
-
-## Connect provider accounts
-
-`Connection.start` handles token and interactive provider methods. It returns either `Connected`
-or `Redirect`; `Connection.complete` consumes an interactive continuation exactly once. Cloudflare
-implements OAuth and token methods. Vercel implements its installation-code flow without
-mislabeling it as generic OAuth.
-
-After a host proves that an existing connected account owns another domain and obtains the owner's
-consent, `Connection.extend` adds that domain to the existing owner grant without repeating provider
-authentication. It preserves earlier domain grants and rejects cross-owner, expired, or revoking
-connections.
-
-Cloudflare can discover the selected account from a domain already visible to the credential, so a
-customer does not need to find or type an account ID. Vercel retains explicit personal or team
-context returned by the installation. Both contexts are versioned, non-secret values that can
-reconstruct the correct provider client later.
-
-Hosts provide one `AuthorizationLifecycle` repository for an authorization aggregate, its
-credential, and its owner bindings. SQL hosts can implement one transaction; split database and
-vault hosts can implement a recoverable saga behind the same interface. Interactive continuations
-remain separate, short-lived, one-time state. DomainKit does not choose a database, cache, vault,
-callback route, session model, consent UI, or audit system.
 
-Provider scope claims are not treated as proof. Each required capability carries `Declared`,
-`Introspected`, or `Exercised` evidence. Final-binding revocation is fail-closed: durable state
-remains retryable until the provider confirms revocation.
-
-## Observe DNS
-
-`Verification.observe` is the only verification operation. Public DNS is the default:
-
-```ts
-import { Effect } from "effect";
-import { DnsProvider, Verification } from "domainkit";
-
-const result = await Effect.runPromise(Verification.observe({ record }));
-```
-
-The default resolver pool queries Cloudflare and Google concurrently using RFC wire-format DNS over
-HTTPS and applies `AnyMatch`. Results preserve every named answer, negative response, timeout, and
-failure. Hosts can supply another resolver pool or choose tagged `AllMatch` and `Quorum` policies.
-
-Authoritative-provider observation is opt-in:
-
-```ts
-const result = await Verification.observe({
-  provider: Verification.Provider.Enabled({ zone }),
-  publicDns: Verification.PublicDns.Disabled(),
-  record,
-}).pipe(Effect.provideService(DnsProvider.Service, provider), Effect.runPromise);
+const program = Effect.gen(function* () {
+  const { plan } = yield* Provisioning.create({
+    requirements: [requirement],
+    target: Provisioning.Target.ExactZone({
+      zone: DomainName.parse("example.com"),
+    }),
+  });
+  const authorization = yield* Provisioning.authorize(plan);
+  return yield* Provisioning.apply({ authorization, plan });
+}).pipe(Effect.provide(Layer.merge(InMemoryDnsProvider.layer(), Digest.webCryptoLayer)));
 ```
 
-When both sources are requested, both must match for `Verified`. Every result is exhaustive and
-tagged as `NotObserved`, `Pending`, `Mismatch`, `Unavailable`, or `Verified`.
+Planning is additive and fail-closed: exact records become no-ops, missing records become creates,
+and incompatible state becomes a conflict. DomainKit never silently overwrites DNS.
 
-## Implement a DNS provider
+## Public entry points
 
-Implement the narrow `DnsProvider` contract exported from `domainkit`. Then
-run the deterministic offline contract exported from `domainkit/testing`:
+- `domainkit` — canonical Effect services, schemas, plans, providers, and verification;
+- `domainkit/promise` — Promise adapters for foreign-runtime boundaries;
+- `domainkit/testing` — in-memory services and provider conformance helpers.
 
-```ts
-import { Effect } from "effect";
-import { DomainName } from "domainkit";
-import { ProviderConformance } from "domainkit/testing";
-
-const report = await Effect.runPromise(
-  ProviderConformance.run({
-    makeProvider: ProviderConformance.fromAsync(() => makeFreshPromiseProvider()),
-    zone: DomainName.parse("example.com"),
-  }),
-);
-```
+Provider credentials, OAuth state, durable connections, plans, receipts, authorization, and audit
+history remain owned by your application. DomainKit supplies the domain model and operations, not a
+hosted control plane.
 
-The contract covers complete readback across provider pages, exact no-op, conflict, create, stale
-plans, partial receipts, and receipt-bound cleanup. First-party providers run the same contract and
-credential-gated live profiles against disposable records.
+## Learn more
 
-Schemas own external and persisted parsing; Effect `Data` values own in-process configuration and
-control flow. See [the architecture decisions](docs/adr/README.md),
-[provider behavior](docs/providers.md), and [runnable examples](examples/).
+- [Executable quickstart](https://github.com/AryaLabsHQ/domainkit/blob/main/packages/domainkit/examples/effect/quickstart.ts)
+- [Architecture decisions](https://github.com/AryaLabsHQ/domainkit/tree/main/docs/adr)
+- [Provider behavior](https://github.com/AryaLabsHQ/domainkit/blob/main/docs/providers.md)
+- [Examples](https://github.com/AryaLabsHQ/domainkit/tree/main/packages/domainkit/examples)
+- [Issues](https://github.com/AryaLabsHQ/domainkit/issues)
 
 ## License
 

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
-import { $ as RemoveDomainResult$1, A as make$1, B as discovery, G as secret_exports, O as client_exports$1, Q as Method$1, Tt as version, U as connection_authorization_exports, V as make, W as selection_exports, X as diagnostic_exports, Y as manifest_exports, Z as Error, at as AuthorizationError, b as dns_data_exports, ct as assertGrant, dt as decode, et as StartResult, ft as encode, g as cloudflare_doh_exports, ht as validate, it as start, j as auth_exports, k as discovery$1, lt as authorizationError, m as google_doh_exports, mt as removeDomain$1, nt as extend, ot as Grant, p as resolver_pool_exports, pt as includeDomains, rt as removeDomain, s as verify_exports, st as Schema$1, tt as complete, ut as coversDomain, v as doh_exports, wt as provider_context_exports, x as auth_exports$1, xt as authorization_exports, z as client_exports } from "./verify-B00c81-n.mjs";
+import { $ as RemoveDomainResult$1, A as make$1, B as discovery, G as secret_exports, O as client_exports$1, Q as Method$1, Tt as version, U as connection_authorization_exports, V as make, W as selection_exports, X as diagnostic_exports, Y as manifest_exports, Z as Error, at as AuthorizationError, b as dns_data_exports, ct as assertGrant, dt as decode, et as StartResult, ft as encode, g as cloudflare_doh_exports, ht as validate, it as start, j as auth_exports, k as discovery$1, lt as authorizationError, m as google_doh_exports, mt as removeDomain$1, nt as extend, ot as Grant, p as resolver_pool_exports, pt as includeDomains, rt as removeDomain, s as verify_exports, st as Schema$1, tt as complete, ut as coversDomain, v as doh_exports, wt as provider_context_exports, x as auth_exports$1, xt as authorization_exports, z as client_exports } from "./verify-BUB4N5zs.mjs";
 import { B as provider_exports, C as plan_exports, N as types_exports, P as canonical_json_exports, _t as domain_name_exports, bt as invalid_input_exports, dt as zones_exports, lt as zone_discovery_exports, m as deletion_exports, mt as lifecycle_repository_exports, r as resolver_exports, rt as dns_record_exports } from "./resolver-CvK7JoJM.mjs";
 import { Context, Data, Effect, Layer, Schema } from "effect";
 //#region src/auth/connection-api.ts

package/dist/promise.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
-import { $ as RemoveDomainResult, A as make$7, C as integrationFlow$1, Ct as encode$1, D as tokenMethod$3, E as tokenConnectionMethod$3, F as subjectResolver$1, G as secret_exports, H as authorize$2, I as tokenConnectionMethod$2, J as decode$5, K as Method$2, L as tokenMethod$2, M as manifest$2, N as oauthFlow$1, P as oauthMethod$1, Q as Method$1, R as tokenValidator$1, S as exchangeCode$1, St as decode$6, T as manifest$3, Tt as version, V as make$6, W as selection_exports, X as diagnostic_exports, Z as Error, _ as toAsync$2, _t as CapabilityEvidence, a as Result, at as AuthorizationError, bt as Schema$3, c as Observation, ct as assertGrant, d as defaultMake$1, dt as decode$4, et as StartResult, f as make$8, ft as encode, gt as Capability, h as toAsync$4, i as PublicDnsObservation, it as start$1, l as Policy, mt as removeDomain$1, n as ProviderObservation, nt as extend$1, o as observe$1, ot as Grant, pt as includeDomains, q as Schema$2, r as PublicDns$1, rt as removeDomain$2, st as Schema$1, t as Provider$1, tt as complete$1, u as Service, ut as coversDomain, vt as Evidence, w as integrationMethod$1, wt as provider_context_exports, y as toAsync$3, yt as EvidenceSchema } from "./verify-B00c81-n.mjs";
+import { $ as RemoveDomainResult, A as make$7, C as integrationFlow$1, Ct as encode$1, D as tokenMethod$3, E as tokenConnectionMethod$3, F as subjectResolver$1, G as secret_exports, H as authorize$2, I as tokenConnectionMethod$2, J as decode$5, K as Method$2, L as tokenMethod$2, M as manifest$2, N as oauthFlow$1, P as oauthMethod$1, Q as Method$1, R as tokenValidator$1, S as exchangeCode$1, St as decode$6, T as manifest$3, Tt as version, V as make$6, W as selection_exports, X as diagnostic_exports, Z as Error, _ as toAsync$2, _t as CapabilityEvidence, a as Result, at as AuthorizationError, bt as Schema$3, c as Observation, ct as assertGrant, d as defaultMake$1, dt as decode$4, et as StartResult, f as make$8, ft as encode, gt as Capability, h as toAsync$4, i as PublicDnsObservation, it as start$1, l as Policy, mt as removeDomain$1, n as ProviderObservation, nt as extend$1, o as observe$1, ot as Grant, pt as includeDomains, q as Schema$2, r as PublicDns$1, rt as removeDomain$2, st as Schema$1, t as Provider$1, tt as complete$1, u as Service, ut as coversDomain, vt as Evidence, w as integrationMethod$1, wt as provider_context_exports, y as toAsync$3, yt as EvidenceSchema } from "./verify-BUB4N5zs.mjs";
 import { $ as Txt, A as decodeReceipt$1, D as Receipt, E as Operation, F as webCryptoLayer, G as Cname, H as A, I as Error$2, J as Observed, K as Mx, L as Service$2, M as encodeReceipt, O as Schema$6, Q as Srv, S as create$3, T as Authorization, U as Aaaa, W as Caa, X as RequirementMetadata, Y as Opaque, Z as Schema$4, a as Authorization$1, at as parse, b as apply$3, bt as invalid_input_exports, c as PartialError, ct as make$9, d as apply$2, dt as zones_exports, et as Type, f as authorize$3, ft as Error$1, g as CreateResult, ht as Schema$5, it as equals, j as encode$2, k as decode$7, l as Plan, o as Error$3, ot as Candidate, p as create$2, pt as Service$1, q as Ns, s as Operation$1, st as Service$3, t as Error$4, tt as data, u as Receipt$1, vt as parse$1, w as renderManualInstructions$1, x as authorize$4, y as Target, z as layerFromAsync } from "./resolver-CvK7JoJM.mjs";
 import { Data, Effect, Layer } from "effect";
 //#region src/promise/authorization-lifecycle.ts

package/dist/{verify-B00c81-n.mjs → verify-BUB4N5zs.mjs}

@@ -4,7 +4,7 @@ import { Clock, Context, Crypto, Data, Effect, Layer, Option, Schema, SchemaIssu
 import * as oauth from "oauth4webapi";
 import * as DnsPacket from "@leichtgewicht/dns-packet";
 //#region package.json
-var version = "0.3.0";
+var version = "0.4.0";
 //#endregion
 //#region src/auth/provider-context.ts
 var provider_context_exports = /* @__PURE__ */ __exportAll({
@@ -2417,4 +2417,4 @@ function recordValue(requirement) {
 //#endregion
 export { RemoveDomainResult as $, make$4 as A, discovery$1 as B, integrationFlow as C, encode$3 as Ct, tokenMethod as D, tokenConnectionMethod as E, subjectResolver as F, secret_exports as G, authorize as H, tokenConnectionMethod$1 as I, decode$4 as J, Method as K, tokenMethod$1 as L, manifest$1 as M, oauthFlow as N, client_exports as O, oauthMethod as P, Method$1 as Q, tokenValidator as R, exchangeCode as S, decode$6 as St, manifest as T, version as Tt, connection_authorization_exports as U, make$5 as V, selection_exports as W, diagnostic_exports as X, manifest_exports as Y, Error$1 as Z, toAsync$1 as _, CapabilityEvidence as _t, Result as a, AuthorizationError as at, dns_data_exports as b, Schema$3 as bt, Observation as c, assertGrant as ct, defaultMake as d, decode$5 as dt, StartResult as et, make as f, encode$2 as ft, cloudflare_doh_exports as g, Capability as gt, toAsync as h, validate as ht, PublicDnsObservation as i, start$1 as it, auth_exports$1 as j, discovery as k, Policy as l, authorizationError as lt, google_doh_exports as m, removeDomain$1 as mt, ProviderObservation as n, extend as nt, observe as o, Grant as ot, resolver_pool_exports as p, includeDomains as pt, Schema$1 as q, PublicDns as r, removeDomain as rt, verify_exports as s, Schema$2 as st, Provider as t, complete$1 as tt, Service as u, coversDomain as ut, doh_exports as v, Evidence$1 as vt, integrationMethod as w, provider_context_exports as wt, auth_exports as x, authorization_exports as xt, toAsync$2 as y, EvidenceSchema as yt, client_exports$1 as z };
 
-//# sourceMappingURL=verify-B00c81-n.mjs.map
+//# sourceMappingURL=verify-BUB4N5zs.mjs.map