domainkit 0.0.1 → 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arya Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,115 @@
-# domainkit
+# 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.
+
+## 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.
+
+## Package shape
+
+- `domainkit` — Promise-based 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.
+
+The package is portable ESM built on Fetch and Web APIs. Effect is a peer dependency.
+
+Both entry points are organized by capability namespaces. The root API accepts ordinary async
+providers and stores:
+
+```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),
+  },
+  requirements,
+  zone: "example.com",
+});
+```
+
+Effect applications provide the same capabilities as Layers and run the canonical program
+directly:
+
+```ts
+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)),
+);
+```
+
+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.
+
+The Cloudflare adapter accepts a host-owned API or OAuth token and an explicitly selected account.
+The host also declares the capabilities required when that credential was issued; Cloudflare's
+non-mutating token-verification endpoint cannot infer DNS write permission. The adapter creates
+DNS-only records and leaves credential storage and user interaction to the host:
+
+```ts
+import { Cloudflare, Provisioning, Secret } from "domainkit";
+
+const provider = Cloudflare.make({
+  accountId: "cloudflare-account-id",
+  capabilities: ["dns:read", "dns:write"],
+  token: Secret.make(apiToken),
+});
+
+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.
+
+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:
+
+```ts
+import { Secret, Vercel } from "domainkit";
+
+const provider = Vercel.make({
+  capabilities: ["dns:read", "dns:write"],
+  context: { _tag: "team", teamId: "team-id" },
+  token: Secret.make(apiToken),
+});
+```
+
+`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.
+
+## License
+
+MIT

package/dist/auth-Df9BuC25.mjs

@@ -0,0 +1,460 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { T as decode$2, c as Opaque, h as decode$3, y as Error } from "./dns-record-Dzo4flM5.mjs";
+import { Clock, Effect, Schema } from "effect";
+//#region src/providers/cloudflare/protocol.ts
+const ErrorDetail = Schema.Struct({
+	code: Schema.Number,
+	message: Schema.String
+});
+const ResultInfo = Schema.Struct({
+	count: Schema.optionalKey(Schema.Number),
+	page: Schema.optionalKey(Schema.Number),
+	per_page: Schema.optionalKey(Schema.Number),
+	total_count: Schema.optionalKey(Schema.Number),
+	total_pages: Schema.optionalKey(Schema.Number)
+});
+const Message = Schema.Struct({
+	code: Schema.optionalKey(Schema.Number),
+	message: Schema.String
+});
+const BaseEnvelope = Schema.Struct({
+	errors: Schema.Array(ErrorDetail),
+	messages: Schema.Array(Message),
+	success: Schema.Boolean
+});
+const Account = Schema.Struct({
+	id: Schema.String,
+	name: Schema.String
+});
+const Zone = Schema.Struct({
+	account: Account,
+	id: Schema.String,
+	name: Schema.String,
+	name_servers: Schema.Array(Schema.String),
+	status: Schema.optionalKey(Schema.String)
+});
+const Record = Schema.Struct({
+	content: Schema.optionalKey(Schema.String),
+	data: Schema.optionalKey(Schema.Unknown),
+	id: Schema.String,
+	name: Schema.String,
+	priority: Schema.optionalKey(Schema.Number),
+	proxied: Schema.optionalKey(Schema.Boolean),
+	ttl: Schema.Number,
+	type: Schema.String
+});
+const Token = Schema.Struct({
+	expires_on: Schema.optionalKey(Schema.String),
+	id: Schema.String,
+	not_before: Schema.optionalKey(Schema.String),
+	status: Schema.Literals([
+		"active",
+		"disabled",
+		"expired"
+	])
+});
+const ZoneListEnvelope = Schema.Struct({
+	errors: Schema.Array(ErrorDetail),
+	messages: Schema.Array(Message),
+	result: Schema.Array(Zone),
+	result_info: Schema.optionalKey(ResultInfo),
+	success: Schema.Boolean
+});
+const RecordListEnvelope = Schema.Struct({
+	errors: Schema.Array(ErrorDetail),
+	messages: Schema.Array(Message),
+	result: Schema.Array(Record),
+	result_info: Schema.optionalKey(ResultInfo),
+	success: Schema.Boolean
+});
+const RecordEnvelope = Schema.Struct({
+	errors: Schema.Array(ErrorDetail),
+	messages: Schema.Array(Message),
+	result: Record,
+	success: Schema.Boolean
+});
+const TokenEnvelope = Schema.Struct({
+	errors: Schema.Array(ErrorDetail),
+	messages: Schema.Array(Message),
+	result: Token,
+	success: Schema.Boolean
+});
+//#endregion
+//#region src/providers/cloudflare/records.ts
+const Data = Schema.Struct({
+	flags: Schema.optionalKey(Schema.Number),
+	port: Schema.optionalKey(Schema.Number),
+	priority: Schema.optionalKey(Schema.Number),
+	tag: Schema.optionalKey(Schema.String),
+	target: Schema.optionalKey(Schema.String),
+	value: Schema.optionalKey(Schema.String),
+	weight: Schema.optionalKey(Schema.Number)
+});
+const decode$1 = Effect.fn("CloudflareRecords.decode")((record) => Effect.gen(function* () {
+	const name = yield* decode$2(record.name).pipe(Effect.match({
+		onFailure: () => null,
+		onSuccess: (value) => value
+	}));
+	if (name === null) return yield* decodeOpaque(record);
+	const common = {
+		metadata: {
+			ownership: "provider",
+			provenance: record.proxied === true ? "cloudflare:proxied" : "cloudflare",
+			purpose: "existing DNS record"
+		},
+		name,
+		policy: record.type === "CNAME" ? "exclusive" : "append",
+		ttl: record.ttl === 1 ? null : record.ttl
+	};
+	const content = () => record.content === void 0 ? Effect.fail(failure$1("decodeRecord", `Cloudflare ${record.type} record has no content`)) : Effect.succeed(record.content);
+	switch (record.type) {
+		case "A":
+		case "AAAA": return yield* decode$3({
+			...common,
+			_tag: record.type,
+			address: yield* content()
+		}).pipe(Effect.mapError((cause) => failure$1("decodeRecord", cause.message)));
+		case "CNAME":
+		case "NS": return yield* decode$3({
+			...common,
+			_tag: record.type,
+			target: yield* content()
+		}).pipe(Effect.mapError((cause) => failure$1("decodeRecord", cause.message)));
+		case "TXT": return yield* decode$3({
+			...common,
+			_tag: "TXT",
+			value: yield* content()
+		}).pipe(Effect.mapError((cause) => failure$1("decodeRecord", cause.message)));
+		case "MX": return yield* decode$3({
+			...common,
+			_tag: "MX",
+			exchange: yield* content(),
+			priority: record.priority
+		}).pipe(Effect.mapError((cause) => failure$1("decodeRecord", cause.message)));
+		case "CAA": {
+			const data = yield* decodeData(record);
+			return yield* decode$3({
+				...common,
+				_tag: "CAA",
+				...data
+			}).pipe(Effect.mapError((cause) => failure$1("decodeRecord", cause.message)));
+		}
+		case "SRV": {
+			const data = yield* decodeData(record);
+			return yield* decode$3({
+				...common,
+				_tag: "SRV",
+				...data
+			}).pipe(Effect.mapError((cause) => failure$1("decodeRecord", cause.message)));
+		}
+		default: return yield* decodeOpaque(record);
+	}
+}));
+const decodeOpaque = Effect.fn("CloudflareRecords.decodeOpaque")((record) => Schema.decodeUnknownEffect(Opaque)({
+	_tag: "Opaque",
+	name: record.name,
+	providerRecordId: record.id,
+	providerType: record.type
+}).pipe(Effect.mapError((cause) => failure$1("decodeRecord", cause.message))));
+function encode(record) {
+	const common = {
+		name: record.name,
+		proxied: false,
+		ttl: record.ttl ?? 1,
+		type: record._tag
+	};
+	switch (record._tag) {
+		case "A":
+		case "AAAA": return {
+			...common,
+			content: record.address
+		};
+		case "CNAME":
+		case "NS": return {
+			...common,
+			content: record.target
+		};
+		case "TXT": return {
+			...common,
+			content: record.value
+		};
+		case "MX": return {
+			...common,
+			content: record.exchange,
+			priority: record.priority
+		};
+		case "CAA": return {
+			...common,
+			data: {
+				flags: record.flags,
+				tag: record.tag,
+				value: record.value
+			}
+		};
+		case "SRV": return {
+			...common,
+			data: {
+				port: record.port,
+				priority: record.priority,
+				target: record.target,
+				weight: record.weight
+			}
+		};
+	}
+}
+const decodeData = Effect.fn("CloudflareRecords.decodeData")((record) => Schema.decodeUnknownEffect(Data)(record.data).pipe(Effect.mapError((cause) => failure$1("decodeRecord", cause.message))));
+function failure$1(operation, message, fields = {}) {
+	return new Error({
+		message,
+		operation,
+		providerId: "cloudflare",
+		reason: fields.reason ?? "response"
+	});
+}
+//#endregion
+//#region src/providers/cloudflare/client.ts
+var client_exports = /* @__PURE__ */ __exportAll({ make: () => make });
+/** Creates an Effect-native Cloudflare client without owning the credential lifecycle. */
+function make(options) {
+	const fetch = options.fetch ?? globalThis.fetch;
+	const baseUrl = (options.baseUrl ?? "https://api.cloudflare.com/client/v4").replace(/\/$/, "");
+	const request = Effect.fn("CloudflareClient.request")((path, operation, init) => Effect.gen(function* () {
+		const response = yield* Effect.tryPromise({
+			try: () => fetch(`${baseUrl}${path}`, {
+				...init,
+				headers: {
+					Accept: "application/json",
+					Authorization: `Bearer ${options.token.expose()}`,
+					...init?.body === void 0 ? {} : { "Content-Type": "application/json" },
+					...init?.headers
+				}
+			}),
+			catch: () => failure(operation, "Cloudflare request failed", { reason: "transport" })
+		});
+		return {
+			body: yield* Effect.tryPromise({
+				try: () => response.json(),
+				catch: () => {
+					const retryAfterMs = retryAfter(response.headers.get("retry-after"));
+					return failure(operation, response.ok ? "Cloudflare returned a non-JSON response" : `Cloudflare request failed with HTTP ${response.status}`, {
+						reason: response.ok ? "response" : reason(response.status),
+						...retryAfterMs === void 0 ? {} : { retryAfterMs },
+						status: response.status
+					});
+				}
+			}),
+			response
+		};
+	}));
+	const listZonesPage = Effect.fn("CloudflareClient.listZonesPage")((accountId, name, page) => Effect.gen(function* () {
+		const query = new URLSearchParams({
+			page: String(page),
+			per_page: "50"
+		});
+		query.set("type", "full,partial,secondary,internal");
+		if (accountId !== void 0) query.set("account.id", accountId);
+		if (name !== void 0) query.set("name", name);
+		const { body, response } = yield* request(`/zones?${query}`, "listZones");
+		yield* ensureSuccess(body, "listZones", response);
+		return yield* decode(ZoneListEnvelope, body, "listZones", response);
+	}));
+	const allZones = Effect.fn("CloudflareClient.allZones")((accountId, name) => Effect.gen(function* () {
+		const zones = [];
+		let page = 1;
+		while (true) {
+			const envelope = yield* listZonesPage(accountId, name, page);
+			zones.push(...envelope.result);
+			const totalPages = envelope.result_info?.total_pages;
+			if (totalPages !== void 0 && page >= totalPages || totalPages === void 0 && envelope.result.length < 50) return zones;
+			page += 1;
+		}
+	}));
+	const resolveZone = Effect.fn("CloudflareClient.resolveZone")((name) => Effect.gen(function* () {
+		const matches = yield* allZones(options.accountId, name);
+		const match = matches[0];
+		if (matches.length === 1 && match !== void 0) return match;
+		return yield* Effect.fail(failure("resolveZone", matches.length === 0 ? `Cloudflare zone ${name} was not found in account ${options.accountId}` : `Cloudflare returned multiple zones named ${name} in account ${options.accountId}`, { reason: matches.length === 0 ? "not_found" : "response" }));
+	}));
+	const listRecords = Effect.fn("CloudflareClient.listRecords")((zoneName) => Effect.gen(function* () {
+		const zone = yield* resolveZone(zoneName);
+		const records = [];
+		let page = 1;
+		while (true) {
+			const query = new URLSearchParams({
+				page: String(page),
+				per_page: "100"
+			});
+			const { body, response } = yield* request(`/zones/${encodeURIComponent(zone.id)}/dns_records?${query}`, "listRecords");
+			yield* ensureSuccess(body, "listRecords", response);
+			const envelope = yield* decode(RecordListEnvelope, body, "listRecords", response);
+			records.push(...yield* Effect.forEach(envelope.result, decode$1));
+			const totalPages = envelope.result_info?.total_pages;
+			if (totalPages !== void 0 && page >= totalPages || totalPages === void 0 && envelope.result.length < 100) return records;
+			page += 1;
+		}
+	}));
+	return {
+		id: "cloudflare",
+		createRecord: Effect.fn("CloudflareClient.createRecord")((zoneName, record) => Effect.gen(function* () {
+			const zone = yield* resolveZone(zoneName);
+			const { body, response } = yield* request(`/zones/${encodeURIComponent(zone.id)}/dns_records`, "createRecord", {
+				body: JSON.stringify(encode(record)),
+				method: "POST"
+			});
+			yield* ensureSuccess(body, "createRecord", response);
+			return { providerRecordId: (yield* decode(RecordEnvelope, body, "createRecord", response)).result.id };
+		})),
+		listAccounts: Effect.fn("CloudflareClient.listAccounts")(() => allZones().pipe(Effect.map((zones) => {
+			const accounts = /* @__PURE__ */ new Map();
+			for (const zone of zones) accounts.set(zone.account.id, zone.account);
+			return [...accounts.values()].sort((left, right) => left.name.localeCompare(right.name));
+		}))),
+		listRecords,
+		listZones: Effect.fn("CloudflareClient.listZones")((input = {}) => allZones(input.accountId ?? options.accountId, input.name).pipe(Effect.flatMap((zones) => Effect.forEach(zones, projectZone)))),
+		validateToken: Effect.fn("CloudflareClient.validateToken")(() => Effect.gen(function* () {
+			const path = options.tokenKind === "account" ? `/accounts/${encodeURIComponent(options.accountId)}/tokens/verify` : "/user/tokens/verify";
+			const { body, response } = yield* request(path, "validateToken");
+			yield* ensureSuccess(body, "validateToken", response);
+			const envelope = yield* decode(TokenEnvelope, body, "validateToken", response);
+			if (envelope.result.status !== "active") return yield* Effect.fail(failure("validateToken", `Cloudflare token is ${envelope.result.status}`, {
+				reason: "authentication",
+				status: response.status
+			}));
+			yield* allZones(options.accountId);
+			const expiresAt = envelope.result.expires_on === void 0 ? null : new Date(envelope.result.expires_on);
+			if (expiresAt !== null && Number.isNaN(expiresAt.valueOf())) return yield* Effect.fail(failure("validateToken", "Cloudflare token expiry is not a valid timestamp", {
+				reason: "response",
+				status: response.status
+			}));
+			return {
+				accountId: options.accountId,
+				capabilities: options.capabilities,
+				expiresAt,
+				scopes: []
+			};
+		}))
+	};
+}
+const projectZone = Effect.fn("CloudflareClient.projectZone")((zone) => Effect.gen(function* () {
+	const name = yield* decode$2(zone.name).pipe(Effect.mapError((cause) => failure("listZones", cause.message, { reason: "response" })));
+	const nameservers = yield* Effect.forEach(zone.name_servers, (nameserver) => decode$2(nameserver).pipe(Effect.mapError((cause) => failure("listZones", cause.message, { reason: "response" }))));
+	return {
+		accountId: zone.account.id,
+		id: zone.id,
+		name,
+		nameservers,
+		status: zone.status ?? null
+	};
+}));
+function decode(schema, input, operation, response) {
+	return Schema.decodeUnknownEffect(schema)(input).pipe(Effect.mapError((cause) => failure(operation, `Cloudflare response did not match its API contract: ${cause.message}`, {
+		reason: "response",
+		status: response.status
+	})));
+}
+function ensureSuccess(input, operation, response) {
+	return Schema.decodeUnknownEffect(BaseEnvelope)(input).pipe(Effect.mapError(() => failure(operation, "Cloudflare response did not contain a valid API envelope", {
+		reason: "response",
+		status: response.status
+	})), Effect.flatMap((envelope) => {
+		if (response.ok && envelope.success) return Effect.void;
+		const detail = envelope.errors[0];
+		const retryAfterMs = retryAfter(response.headers.get("retry-after"));
+		return Effect.fail(failure(operation, detail?.message ?? `Cloudflare request failed with HTTP ${response.status}`, {
+			...detail === void 0 ? {} : { code: detail.code },
+			reason: reason(response.status, detail?.code),
+			...retryAfterMs === void 0 ? {} : { retryAfterMs },
+			status: response.status
+		}));
+	}));
+}
+function reason(status, code) {
+	if (status === 401) return "authentication";
+	if (status === 403) return "authorization";
+	if (status === 404) return "not_found";
+	if (status === 409 || code === 81056 || code === 81057 || code === 81058) return "conflict";
+	if (status === 429) return "rate_limit";
+	if (status >= 500) return "response";
+	return "request";
+}
+function retryAfter(value) {
+	if (value === null) return void 0;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+	const date = Date.parse(value);
+	return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+}
+function failure(operation, message, fields = {}) {
+	return new Error({
+		...fields,
+		message,
+		operation,
+		providerId: "cloudflare"
+	});
+}
+//#endregion
+//#region src/providers/cloudflare/auth.ts
+var auth_exports = /* @__PURE__ */ __exportAll({
+	manifest: () => manifest,
+	oauthMethod: () => oauthMethod,
+	subjectResolver: () => subjectResolver,
+	tokenMethod: () => tokenMethod,
+	tokenValidator: () => tokenValidator
+});
+const authorizationServer = {
+	authorization_endpoint: "https://dash.cloudflare.com/oauth2/auth",
+	issuer: "https://dash.cloudflare.com",
+	revocation_endpoint: "https://dash.cloudflare.com/oauth2/revoke",
+	token_endpoint: "https://dash.cloudflare.com/oauth2/token"
+};
+/** Describes Cloudflare's caller-created API-token authorization method. */
+function tokenMethod(capabilities) {
+	return {
+		_tag: "token",
+		capabilities: [...capabilities],
+		instructionsUrl: "https://developers.cloudflare.com/fundamentals/api/get-started/create-token/"
+	};
+}
+/** Describes a registered Cloudflare OAuth client and its assigned scope IDs. */
+function oauthMethod(options) {
+	return {
+		_tag: "oauth2",
+		authorizationServer,
+		capabilities: [...options.capabilities],
+		clientAuth: options.clientAuth,
+		scopes: [...options.scopes]
+	};
+}
+/** Creates the Cloudflare token and OAuth authorization manifest. */
+function manifest(options) {
+	return {
+		methods: [tokenMethod(options.capabilities), oauthMethod(options)],
+		providerId: "cloudflare"
+	};
+}
+/** Resolves the Cloudflare account selected by a completed OAuth grant. */
+function subjectResolver(options) {
+	return (tokens, accessToken) => Effect.gen(function* () {
+		yield* make({
+			...options,
+			token: accessToken,
+			tokenKind: "user"
+		}).listZones();
+		const now = yield* Clock.currentTimeMillis;
+		return {
+			accountId: options.accountId,
+			expiresAt: typeof tokens.expires_in === "number" ? new Date(now + tokens.expires_in * 1e3) : null
+		};
+	});
+}
+/** Creates a host callback that validates a Cloudflare API token. */
+function tokenValidator(options) {
+	return (token) => make({
+		...options,
+		token
+	}).validateToken();
+}
+//#endregion
+export { tokenMethod as a, subjectResolver as i, manifest as n, client_exports as o, oauthMethod as r, make as s, auth_exports as t };
+
+//# sourceMappingURL=auth-Df9BuC25.mjs.map