domainkit 0.1.1 → 0.2.0

package/README.md

@@ -1,45 +1,39 @@
 # DomainKit
 
 DomainKit is a provider-independent TypeScript SDK for turning DNS requirements into reviewable,
-authorized provisioning plans. It is intended for products that need to connect customer domains
-without making registrar-specific APIs their product architecture.
+authorized provisioning plans. Products can connect customer domains without making one
+registrar's API or authorization model their architecture.
 
-## Direction
-
-DomainKit separates four concerns:
-
-1. a portable, versioned DNS plan and receipt format;
-2. explicit authorization for the exact operations being applied;
-3. provider adapters that reconcile and apply records;
-4. host-owned credentials, persistence, routes, and user interaction.
+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.
 
 ## Package shape
 
-- `domainkit` — Promise-based API for application code;
+- `domainkit` — Promise API for application code;
 - `domainkit/effect` — canonical Effect-native services and programs;
-- `domainkit/cloudflare` — Promise-based Cloudflare authoritative-DNS adapter;
-- `domainkit/effect/cloudflare` — canonical Effect-native Cloudflare adapter;
-- `domainkit/vercel` — Promise-based Vercel authoritative-DNS adapter;
-- `domainkit/effect/vercel` — canonical Effect-native Vercel adapter;
-- `domainkit/testing` — deterministic provider and store implementations for tests.
+- `domainkit/cloudflare` and `domainkit/vercel` — Promise provider integrations;
+- `domainkit/effect/cloudflare` and `domainkit/effect/vercel` — Effect provider integrations;
+- `domainkit/testing` — in-memory lifecycle capabilities and the provider conformance runner.
 
-The package is portable ESM built on Fetch and Web APIs. Effect is a peer dependency.
+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.
 
-Both entry points are organized by capability namespaces. The root API accepts ordinary async
-providers and stores:
+## Plan, approve, and apply
 
 ```ts
 import { Provisioning } from "domainkit";
 
-const plan = await Provisioning.create({
-  provider: {
-    id: "my-provider",
-    listRecords: async (zone) => listDnsRecords(zone),
-    createRecord: async (zone, record) => createDnsRecord(zone, record),
-  },
+const { plan } = await Provisioning.create({
+  provider,
   requirements,
-  zone: "example.com",
+  target: Provisioning.Target.ExactZone({ zone: "example.com" }),
 });
+
+// Present plan.operations to the user before authorizing the exact digest.
+const authorization = await Provisioning.authorize(plan);
+const receipt = await Provisioning.apply({ authorization, plan, provider });
 ```
 
 Effect applications provide the same capabilities as Layers and run the canonical program
@@ -49,82 +43,92 @@ directly:
 import { Effect, Layer } from "effect";
 import { Digest, DnsProvider, Provisioning } from "domainkit/effect";
 
-const program = Provisioning.create({ requirements, zone: "example.com" }).pipe(
-  Effect.provide(Layer.merge(DnsProvider.layerFromAsync(provider), Digest.webCryptoLayer)),
+const program = Provisioning.create({
+  requirements,
+  target: Provisioning.Target.ExactZone({ zone: "example.com" }),
+}).pipe(
+  Effect.provide(Layer.merge(Layer.succeed(DnsProvider.Service, provider), Digest.webCryptoLayer)),
 );
 ```
 
-The Promise namespaces delegate to the canonical Effect programs rather than maintaining a second
-planning, authorization, or verification implementation. Hosts supply providers and stores
-explicitly; DomainKit does not own a hidden runtime.
+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.
+
+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
 
-The Cloudflare authorization helpers can discover the account selected by an OAuth grant or API
-token from a domain the host already owns. They walk from the requested name to its registrable
-domain, require exactly one accessible authoritative zone, and return its Cloudflare account ID.
-Hosts therefore do not need to ask users to find or paste an account ID. The host still declares
-the capabilities required when the credential was issued because Cloudflare's non-mutating token
-verification endpoint cannot infer DNS write permission:
+`Verification.observe` is the only verification operation. Public DNS is the default:
 
 ```ts
-import { Cloudflare, DomainName } from "domainkit";
+import { Verification } from "domainkit";
 
-const resolveSubject = Cloudflare.Auth.subjectResolver({
-  capabilities: ["dns:read", "dns:write"],
-  domain: DomainName.parse("mail.customer.example.com"),
-});
+const result = await Verification.observe({ record });
 ```
 
-Once authorized, the DNS client remains explicitly account-scoped. The host supplies the discovered
-account ID with its stored credential. The adapter creates DNS-only records and leaves credential
-storage and user interaction to the host:
+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.
 
-```ts
-import { Cloudflare, Provisioning, Secret } from "domainkit";
+Authoritative-provider observation is opt-in:
 
-const provider = Cloudflare.make({
-  accountId: "cloudflare-account-id",
-  capabilities: ["dns:read", "dns:write"],
-  token: Secret.make(apiToken),
+```ts
+const result = await Verification.observe({
+  provider: Verification.Provider.Enabled({ provider, zone }),
+  publicDns: Verification.PublicDns.Disabled(),
+  record,
 });
-
-const plan = await Provisioning.create({ provider, requirements, zone: "example.com" });
 ```
 
-OAuth helpers own Cloudflare's endpoints and client-auth variants while accepting the scope IDs
-assigned during OAuth client registration. `Cloudflare.Auth.tokenMethod` describes the equivalent
-API-token capability. Explicit `accountId` authorization remains available for hosts that already
-have a trusted account selection.
+When both sources are requested, both must match for `Verified`. Every result is exhaustive and
+tagged as `NotObserved`, `Pending`, `Mismatch`, `Unavailable`, or `Verified`.
 
-The Vercel adapter accepts either explicit personal or team context. It supports personal access
-tokens and Vercel's integration-code exchange without treating that provider-specific installation
-flow as generic OAuth:
+## Implement a DNS provider
 
-```ts
-import { Secret, Vercel } from "domainkit";
+Implement the narrow `DnsProvider` contract exported from `domainkit` or `domainkit/effect`. Then
+run the deterministic offline contract exported from `domainkit/testing`:
 
-const provider = Vercel.make({
-  capabilities: ["dns:read", "dns:write"],
-  context: { _tag: "team", teamId: "team-id" },
-  token: Secret.make(apiToken),
-});
+```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"),
+  }),
+);
 ```
 
-`listAccounts()` returns the distinct accounts represented by zones visible to the credential.
-Accounts with no visible zones are not returned because Cloudflare does not document bearer-token
-authentication for its separate account-list endpoint.
-
-Schemas own external parsing. For example, `DomainName.parse` and `DnsRecord.parse` decode and
-canonicalize strings through codecs, while encoded protocol dates remain ISO strings and decoded
-domain values use `Date`.
-
-See [the architecture decisions](docs/adr/README.md) for the durable rationale and
-[the provider contract](docs/providers.md) for adapter differences. Runnable TypeScript examples
-cover [manual Promise provisioning](examples/promise/manual-provider.ts),
-[token connections](examples/promise/cloudflare-token.ts),
-[Cloudflare OAuth](examples/promise/cloudflare-oauth.ts),
-[Vercel integration exchange](examples/promise/vercel-integration.ts), and
-[Effect-native provisioning](examples/effect/provisioning.ts). See
-[CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow.
+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.
+
+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/).
 
 ## License
 

package/dist/{auth-B0owkrpk.mjs → auth-CZ1pZHMZ.mjs}

@@ -1,18 +1,108 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
-import { D as parse, O as Error, T as decode$2, c as Opaque, h as decode$3, y as Error$1 } from "./dns-record-C_KwGPLf.mjs";
-import { Clock, Effect, Schema } from "effect";
-import { getDomain } from "tldts";
-//#region src/discovery/zones.ts
-var zones_exports = /* @__PURE__ */ __exportAll({ candidates: () => candidates });
-function candidates(input) {
-	const domain = parse(input);
-	const registrable = getDomain(domain, { allowPrivateDomains: true });
-	if (registrable === null) throw new Error({ message: "Domain does not have a registrable DNS zone" });
-	const labels = domain.split(".");
-	const registrableLabels = registrable.split(".").length;
-	const values = [];
-	for (let index = 0; index <= labels.length - registrableLabels; index += 1) values.push(parse(labels.slice(index).join(".")));
-	return values;
+import { E as decode$2, c as Opaque, h as decode$3, y as Error } from "./dns-record-BLeqo56C.mjs";
+import { f as Value, g as Method, h as Error$1, p as make$1, r as Evidence, u as codec } from "./authorization-DOg2Re1D.mjs";
+import { t as candidates } from "./zones-DKHTpX9C.mjs";
+import { Clock, Crypto, Effect, Schema } from "effect";
+import * as oauth from "oauth4webapi";
+//#region src/auth/authorization-code.ts
+const start = Effect.fn("AuthorizationCode.start")(function* (input) {
+	const crypto = yield* Crypto.Crypto;
+	const codeVerifier = base64Url(yield* randomBytes(crypto, 32));
+	const challenge = base64Url(yield* digest(crypto, codeVerifier));
+	const authorizationUrl = new URL(input.method.authorizationServer.authorization_endpoint);
+	authorizationUrl.search = new URLSearchParams({
+		client_id: input.client.clientId,
+		code_challenge: challenge,
+		code_challenge_method: "S256",
+		redirect_uri: input.redirectUri,
+		response_type: "code",
+		scope: input.method.scopes.join(" "),
+		state: input.state
+	}).toString();
+	return {
+		authorizationUrl,
+		payload: make$1(JSON.stringify({
+			codeVerifier,
+			redirectUri: input.redirectUri,
+			state: input.state
+		}))
+	};
+});
+const complete = Effect.fn("AuthorizationCode.complete")(function* (input) {
+	const payload = yield* decodePayload(input.payload);
+	if (input.callbackUrl.searchParams.get("state") !== payload.state) return yield* failure$2("Authorization callback state does not match its continuation");
+	const server = input.method.authorizationServer;
+	const client = { client_id: input.client.clientId };
+	const authentication = yield* clientAuthentication(input.method, input.client);
+	return yield* Effect.tryPromise({
+		try: async (signal) => {
+			const callback = oauth.validateAuthResponse(server, client, input.callbackUrl, payload.state);
+			const response = await oauth.authorizationCodeGrantRequest(server, client, authentication, callback, payload.redirectUri, payload.codeVerifier, requestOptions(input.fetch, signal));
+			return oauth.processAuthorizationCodeResponse(server, client, response);
+		},
+		catch: (cause) => new Error$1({
+			category: "provider",
+			message: cause instanceof globalThis.Error ? cause.name : "OAuth provider request failed",
+			operation: "AuthorizationCode.complete",
+			retry: "unknown"
+		})
+	});
+});
+const PayloadSchema = Schema.Struct({
+	codeVerifier: Schema.String,
+	redirectUri: Schema.String,
+	state: Schema.String
+});
+function decodePayload(payload) {
+	return Schema.decodeUnknownEffect(Schema.fromJsonString(PayloadSchema))(payload.expose()).pipe(Effect.mapError(() => new Error$1({
+		category: "authorization",
+		message: "OAuth continuation payload is invalid",
+		operation: "AuthorizationCode",
+		retry: "after-user-action"
+	})));
+}
+function clientAuthentication(method, client) {
+	switch (method.clientAuth) {
+		case "none": return Effect.succeed(oauth.None());
+		case "client_secret_basic": return client.clientSecret === void 0 ? failure$2("OAuth client secret is required") : Effect.succeed(oauth.ClientSecretBasic(client.clientSecret.expose()));
+		case "client_secret_post": return client.clientSecret === void 0 ? failure$2("OAuth client secret is required") : Effect.succeed(oauth.ClientSecretPost(client.clientSecret.expose()));
+	}
+}
+function requestOptions(fetchImplementation, signal) {
+	return fetchImplementation === void 0 ? { signal } : {
+		signal,
+		[oauth.customFetch]: (url, options) => fetchImplementation(url, {
+			...options,
+			body: options.body
+		})
+	};
+}
+const failure$2 = (message) => Effect.fail(new Error$1({
+	category: "authorization",
+	message,
+	operation: "AuthorizationCode",
+	retry: "after-user-action"
+}));
+function randomBytes(crypto, size) {
+	return crypto.randomBytes(size).pipe(Effect.mapError((cause) => new Error$1({
+		category: "validation",
+		message: cause.message,
+		operation: "AuthorizationCode.start",
+		retry: "safe"
+	})));
+}
+function digest(crypto, value) {
+	return crypto.digest("SHA-256", new TextEncoder().encode(value)).pipe(Effect.mapError((cause) => new Error$1({
+		category: "validation",
+		message: cause.message,
+		operation: "AuthorizationCode.start",
+		retry: "safe"
+	})));
+}
+function base64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
 }
 //#endregion
 //#region src/providers/cloudflare/protocol.ts
@@ -95,7 +185,7 @@ const TokenEnvelope = Schema.Struct({
 });
 //#endregion
 //#region src/providers/cloudflare/records.ts
-const Data = Schema.Struct({
+const Data$1 = Schema.Struct({
 	flags: Schema.optionalKey(Schema.Number),
 	port: Schema.optionalKey(Schema.Number),
 	priority: Schema.optionalKey(Schema.Number),
@@ -216,9 +306,9 @@ function encode(record) {
 		};
 	}
 }
-const decodeData = Effect.fn("CloudflareRecords.decodeData")((record) => Schema.decodeUnknownEffect(Data)(record.data).pipe(Effect.mapError((cause) => failure$1("decodeRecord", cause.message))));
+const decodeData = Effect.fn("CloudflareRecords.decodeData")((record) => Schema.decodeUnknownEffect(Data$1)(record.data).pipe(Effect.mapError((cause) => failure$1("decodeRecord", cause.message))));
 function failure$1(operation, message, fields = {}) {
-	return new Error$1({
+	return new Error({
 		message,
 		operation,
 		providerId: "cloudflare",
@@ -229,9 +319,20 @@ function failure$1(operation, message, fields = {}) {
 //#region src/providers/cloudflare/client.ts
 var client_exports = /* @__PURE__ */ __exportAll({
 	discoverAuthorizationAccount: () => discoverAuthorizationAccount,
+	discovery: () => discovery,
 	make: () => make,
 	validateDomainToken: () => validateDomainToken
 });
+/** Exposes Cloudflare zone lookup as the optional provider discovery capability. */
+function discovery(client) {
+	return {
+		listZones: (name) => client.listZones({ name }).pipe(Effect.map((zones) => zones.map((zone) => ({
+			...zone,
+			status: zone.status === "active" || zone.status === "pending" ? zone.status : "unknown"
+		})))),
+		provider: client
+	};
+}
 const makeTransport = (options) => {
 	const fetch = options.fetch ?? globalThis.fetch;
 	const baseUrl = (options.baseUrl ?? "https://api.cloudflare.com/client/v4").replace(/\/$/, "");
@@ -451,7 +552,7 @@ function retryAfter(value) {
 	return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
 }
 function failure(operation, message, fields = {}) {
-	return new Error$1({
+	return new Error({
 		...fields,
 		message,
 		operation,
@@ -461,9 +562,13 @@ function failure(operation, message, fields = {}) {
 //#endregion
 //#region src/providers/cloudflare/auth.ts
 var auth_exports = /* @__PURE__ */ __exportAll({
+	contextCodec: () => contextCodec,
 	manifest: () => manifest,
+	oauthAuthentication: () => oauthAuthentication,
+	oauthFlow: () => oauthFlow,
 	oauthMethod: () => oauthMethod,
 	subjectResolver: () => subjectResolver,
+	tokenConnectionMethod: () => tokenConnectionMethod,
 	tokenMethod: () => tokenMethod,
 	tokenValidator: () => tokenValidator
 });
@@ -473,6 +578,8 @@ const authorizationServer = {
 	revocation_endpoint: "https://dash.cloudflare.com/oauth2/revoke",
 	token_endpoint: "https://dash.cloudflare.com/oauth2/token"
 };
+const Context$1 = Schema.Struct({ tokenKind: Schema.Literals(["account", "user"]) });
+const contextCodec = codec("cloudflare.v1", Context$1);
 /** Describes Cloudflare's caller-created API-token authorization method. */
 function tokenMethod(capabilities) {
 	return {
@@ -540,7 +647,92 @@ function tokenValidator(options) {
 		...options.tokenKind === void 0 ? {} : { tokenKind: options.tokenKind }
 	}).validateToken();
 }
+/** Creates a provider-independent token connection method backed by Cloudflare validation. */
+function tokenConnectionMethod(options) {
+	const requiredCapabilities = [...options.capabilities];
+	return Method.Token({
+		authenticate: Effect.fn("CloudflareAuth.authenticateToken")(function* (token) {
+			const validated = yield* tokenValidator(options)(token);
+			const observedAt = new Date(yield* Clock.currentTimeMillis);
+			return {
+				capabilityEvidence: validated.capabilities.map((capability) => ({
+					capability,
+					evidence: Evidence.Introspected({ observedAt })
+				})),
+				credential: {
+					accessToken: token,
+					refreshToken: null,
+					tokenType: "bearer"
+				},
+				expiresAt: validated.expiresAt,
+				providerAccountId: validated.accountId,
+				providerContext: yield* contextCodec.encode({ tokenKind: options.tokenKind ?? "user" }),
+				scopes: [...validated.scopes]
+			};
+		}),
+		providerId: "cloudflare",
+		requiredCapabilities,
+		token: options.token
+	});
+}
+/** Converts a completed Cloudflare OAuth grant into the canonical connection authentication. */
+const oauthAuthentication = Effect.fn("CloudflareAuth.oauthAuthentication")(function* (options) {
+	const resolved = yield* subjectResolver(options)(options.tokens, options.accessToken);
+	const observedAt = new Date(yield* Clock.currentTimeMillis);
+	return {
+		capabilityEvidence: options.capabilities.map((capability) => ({
+			capability,
+			evidence: Evidence.Introspected({ observedAt })
+		})),
+		credential: {
+			accessToken: options.accessToken,
+			refreshToken: options.tokens.refresh_token === void 0 ? null : Value.from(options.tokens.refresh_token),
+			tokenType: options.tokens.token_type
+		},
+		expiresAt: resolved.expiresAt,
+		providerAccountId: resolved.accountId,
+		providerContext: yield* contextCodec.encode({ tokenKind: "user" }),
+		scopes: (options.tokens.scope ?? "").split(" ").filter(Boolean)
+	};
+});
+/** Creates Cloudflare's OAuth implementation of the common interactive connection capability. */
+function oauthFlow(options) {
+	const method = oauthMethod({
+		capabilities: options.capabilities,
+		clientAuth: options.clientAuth,
+		scopes: options.scopes
+	});
+	return {
+		complete: Effect.fn("CloudflareAuth.oauthFlow.complete")(function* (payload, callbackUrl) {
+			const tokens = yield* complete({
+				callbackUrl,
+				client: options.client,
+				...options.fetch === void 0 ? {} : { fetch: options.fetch },
+				method,
+				payload,
+				providerId: "cloudflare"
+			});
+			return yield* oauthAuthentication({
+				...options.accountId === void 0 ? { domain: options.domain } : { accountId: options.accountId },
+				...options.baseUrl === void 0 ? {} : { baseUrl: options.baseUrl },
+				capabilities: options.capabilities,
+				...options.fetch === void 0 ? {} : { fetch: options.fetch },
+				accessToken: make$1(tokens.access_token),
+				tokens
+			});
+		}),
+		method: "oauth2",
+		providerId: "cloudflare",
+		requiredCapabilities: [...options.capabilities],
+		start: (continuationId) => start({
+			client: options.client,
+			method,
+			redirectUri: options.redirectUri,
+			state: continuationId
+		})
+	};
+}
 //#endregion
-export { tokenMethod as a, make as c, subjectResolver as i, candidates as l, manifest as n, tokenValidator as o, oauthMethod as r, client_exports as s, auth_exports as t, zones_exports as u };
+export { subjectResolver as a, tokenValidator as c, make as d, oauthMethod as i, client_exports as l, manifest as n, tokenConnectionMethod as o, oauthFlow as r, tokenMethod as s, auth_exports as t, discovery as u };
 
-//# sourceMappingURL=auth-B0owkrpk.mjs.map
+//# sourceMappingURL=auth-CZ1pZHMZ.mjs.map