domainkit 0.7.0 → 0.9.0

package/README.md

@@ -2,9 +2,10 @@
 
 Add custom domains to a TypeScript SaaS application.
 
-DomainKit turns DNS requirements into plans you can review, requires approval for the exact plan
-before a write, records applied changes in receipts, and uses those receipts to plan cleanup. It
-supports Cloudflare and Vercel without making either provider's API your product architecture.
+DomainKit turns DNS requirements into plans a customer can review, applies only the plan digest
+they approved, keeps a receipt of every write, and plans cleanup from that receipt. Cloudflare and
+Vercel are built in; a provider is one declarative value, so tokens-only providers are the same
+shape minus the OAuth case.
 
 ## Install
 
@@ -14,59 +15,233 @@ npm install domainkit effect@rc
 
 Node.js 24.10 or newer and Effect 4 are required.
 
-## Plan, approve, and apply
+## Plan, approve, apply
+
+```ts
+import { Effect, Match } from "effect";
+import { DnsRecord, DomainKit, Principal, Provision, Verify } from "domainkit";
+import { Testing } from "domainkit/testing";
+
+const requirements = [
+  DnsRecord.cname({ name: "app.example.com", target: "edge.acme.dev", purpose: "Serve your site" }),
+  DnsRecord.txt({
+    name: "_acme.app.example.com",
+    value: "acme-verify=7f3a",
+    purpose: "Prove ownership",
+  }),
+];
+
+const program = Effect.gen(function* () {
+  const plan = yield* Provision.plan({ domain: "app.example.com", requirements });
+  //    ^ operations: [Create CNAME, Noop TXT] with a digest the customer approves
+
+  const approval = yield* Provision.approve(plan);
+  const receipt = yield* Provision.apply(approval);
+  //    ^ status: "complete" | "partial", one outcome per operation, safe to retry
+
+  const readiness = yield* Verify.observe({ domain: "app.example.com" });
+  return { receipt, ready: readiness.overall === "ready", nextCheckAt: readiness.nextCheckAt };
+}).pipe(
+  Effect.catchTag("DomainKitError", (error) =>
+    Match.value(error.reason).pipe(
+      Match.tag("Conflict", ({ operations }) =>
+        Effect.fail(`Fix ${operations.length} conflicting record(s) first`),
+      ),
+      Match.tag("Stale", () => Effect.fail("Provider changed under us; plan again")),
+      Match.orElse(() => Effect.fail(error.message)),
+    ),
+  ),
+);
+
+export const main = program.pipe(
+  Effect.provideService(Principal.Service, { ownerId: "org_42", actorId: "user_7" }),
+  Effect.provide(
+    DomainKit.layerMemory({ providers: [Testing.provider({ zones: ["example.com"] })] }),
+  ),
+);
+```
+
+Plans are additive and fail closed: exact records are `Noop`, missing records are `Create`, and
+incompatible state is `Conflict`. DomainKit never updates or deletes a record it did not create,
+and cleanup is its own plan, approval, and receipt built from the apply receipt.
+
+Every step is a stored attempt, so a host can render the plan in one request, collect consent in
+another, and apply in a third; retrying any step replays its result. A customer who declines calls
+`Provision.reject`, which closes the attempt for good and leaves the domain free for a new plan. Every failure is one
+`DomainKit.Error` whose `reason` you match on; `category`, `isRetryable`, and `httpStatus` derive
+from it.
+
+## Wire it into your app
+
+```ts
+import { Config, Layer } from "effect";
+import { Cloudflare, Custody, DomainKit, Vercel } from "domainkit";
+
+export const DomainKitLive = DomainKit.layer({
+  providers: [
+    Cloudflare.provider({
+      oauth: {
+        clientId: Config.string("CF_CLIENT_ID"),
+        clientSecret: Config.redacted("CF_CLIENT_SECRET"),
+      },
+    }),
+    Vercel.provider(), // tokens only
+  ],
+}).pipe(
+  // `provideMerge`, not `provide`: `domainkit/server`'s handlers read attempts and receipts
+  // straight from Storage, so the layer they are given has to still carry it.
+  Layer.provideMerge(Layer.mergeAll(YourStorage, Custody.layerConfig())),
+);
+```
+
+The host provides two services beneath the layer and one per request:
+
+- `Storage` — every durable row (authorizations with sealed credentials, connections, attachments,
+  continuations, attempts, readiness). `Storage.layerMemory` is for tests; the Postgres
+  implementation lives in `@domainkit/capsuledb`; `Storage.layerFromAsync` wraps a Promise-shaped
+  implementation of your own. `Testing.conformance.storage` checks any implementation.
+- `Custody` — seals credentials before Storage sees them. `Custody.layerConfig()` reads a 32-byte
+  key from `DOMAINKIT_CUSTODY_KEY`; `Custody.layerFromAsync` wraps a KMS.
+- `Principal` — `{ ownerId, actorId }` per request. Every Storage read and write is scoped by it, so
+  cross-tenant access is a type error, not a runtime check.
+
+`Connect.start` connects a provider (a token in one call, OAuth or a marketplace integration via a
+redirect and `Connect.complete`), attaches domains, refreshes credentials before they expire, and
+revokes them on disconnect. `Verify.observe` reads the provider and public DNS, stores readiness
+per requirement, and tells you when to look again; pass `requirements` to observe records a
+customer applies by hand on a domain with no attachment.
+
+## Mount the routes
 
 ```ts
-import { Digest, DnsRecord, DomainName, Provisioning } from "domainkit";
-import { InMemoryDnsProvider } from "domainkit/testing";
 import { Effect, Layer } from "effect";
+import { HttpApi, HttpApiBuilder } from "effect/unstable/httpapi";
+import { DomainKit, Reason } from "domainkit";
+import { Server } from "domainkit/server";
+
+// Verify a credential you issued and look the tenant up yourself. A request never names its own
+// `ownerId`, and one you cannot attribute fails closed. Read it from a cookie: `/callback/:provider`
+// is a browser navigation, so only what the browser sends by itself arrives with it.
+const IdentityLive = Layer.succeed(Server.Identity)({
+  principal: (request) =>
+    Effect.flatMap(yourSessions.verify(request.cookies.session), (session) =>
+      session === null
+        ? Effect.fail(
+            new DomainKit.Error({ reason: new Reason.Unauthenticated({ message: "No session" }) }),
+          )
+        : Effect.succeed({ ownerId: session.orgId, actorId: session.userId }),
+    ),
+  // Optional: which routes this principal may reach. Members read, administrators write.
+  authorize: (principal, endpoint) =>
+    principal.actorId === "admin" || !writeRoutes.has(endpoint)
+      ? Effect.void
+      : Effect.fail(
+          new DomainKit.Error({
+            reason: new Reason.Forbidden({ message: `${endpoint} needs an administrator` }),
+          }),
+        ),
+});
+
+export const Api = HttpApi.make("app").add(Server.group);
+
+export const ApiLive = HttpApiBuilder.layer(Api).pipe(
+  Layer.provide(Server.layer(Api, { defaultReturnTo: "/settings/domains" })),
+  Layer.provide([DomainKitLive, IdentityLive]),
+);
+```
+
+`Server.group` is one `HttpApiGroup` with fifteen typed endpoints covering the whole lifecycle:
+inspect, discover, connect, callback, attach, detach, disconnect, plan, approve, reject, apply, read
+a plan or a receipt, observe, and build a cleanup plan. `Identity` is the only service you write, and
+every handler derives the `Principal` for the request it is serving. `Server.group.prefix("/internal/dns")` moves
+every route, and the OAuth callback URL follows the mount. `OpenApi.fromApi(Server.api)` documents
+the group.
+
+`/callback/:provider` is the one route the provider drives the browser to, so `Identity` has to
+recognise a credential the browser sends on a top-level navigation.
+
+`authorize` is optional and runs after `principal` on every request with the route's name, one of
+`Server.EndpointName`. Fail it with reason `Forbidden` for the 403 a UI expects. Omit it and every
+authenticated principal reaches every route, which is right when your own middleware already gates
+the mount.
+
+After an interactive connection completes, the callback redirects to the `returnTo` the flow was
+started with, or to `defaultReturnTo`. The destination is resolved against the callback's own base
+and must land on its origin, so neither the provider nor a crafted `returnTo` can steer the customer
+off the application. Behind a proxy that rewrites `Host`, set `callbackBaseUrl` to the public base:
+the request origin is one the browser never sees, and both the provider's callback URL and the
+redirect follow the configured one.
 
-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,
+Failures cross the wire as the `DomainKit.Error` value with the status its `reason` derives, so a
+`Conflict` is a 409 carrying the conflicting operations and a `Reconnect` is a 403 naming the
+connection.
+
+Hosts that are not on Effect's HTTP stack use the Promise edge:
+
+```ts
+const { handler, dispose } = Server.toWebHandler(Layer.mergeAll(DomainKitLive, IdentityLive), {
+  prefix: "/api/domainkit",
 });
+```
 
-const program = Effect.gen(function* () {
-  const { plan } = yield* Provisioning.create({
-    requirements: [requirement],
-    target: Provisioning.Target.ExactZone({
-      zone: DomainName.parse("example.com"),
-    }),
+## Talk to them from the browser
+
+```ts
+import { Transport } from "domainkit/client";
+
+const transport = Transport.fromFetch("/api/domainkit");
+
+// Effect at the call site, or `Transport.toAsync(transport)` for Promises.
+const started =
+  yield *
+  transport.connection!.start({
+    domain: "app.example.com",
+    provider: "cloudflare",
+    method: Transport.Method.oauth({ returnTo: "/settings/domains" }),
   });
-  const authorization = yield* Provisioning.authorize(plan);
-  return yield* Provisioning.apply({ authorization, plan });
-}).pipe(Effect.provide(Layer.merge(InMemoryDnsProvider.layer(), Digest.webCryptoLayer)));
 ```
 
-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.
+`connection.discover(domain)` answers which of the customer's existing connections already reaches
+the domain, so a second domain on a connected provider skips the connect step entirely.
+`Snapshot.providers[].methods[]` carries each method's label, docs URL, and token fields, so a
+connect form renders from the response instead of hard-coding provider names.
+
+Capability groups are optional. A host that mounts only the connection routes declares
+`Transport.fromFetch(url, { capabilities: ["connection"] })`, `Transport.capabilities(transport)`
+reports what is there, and the parts of `@domainkit/react` that plan or clean up do not render.
+`Transport.fromAsync` adapts a Promise-shaped transport of your own.
+
+Failures arrive as the same `DomainKit.Error` the lifecycle raised, reason intact, so a `Conflict`
+still carries its conflicting operations. A response the transport cannot read as a `DomainKit.Error`
+becomes a retryable `ProviderUnavailable` naming the base URL.
+
+## Test against the seam
+
+`domainkit/testing` ships `Testing.provider` (a token and OAuth provider over in-memory zones),
+`Testing.resolver`, `Testing.storage`, `Testing.transport` (the whole lifecycle over an in-memory
+server, recording every call), and the conformance runners, so host tests never stub global
+`fetch`. Provider authors run `Testing.conformance.provider(definition, credential, zone)` against
+a real account before shipping.
 
 ## Public entry points
 
-- `domainkit` — Effect services, schemas, plans, providers, and verification;
-- `domainkit/promise` — Promise API for apps that use async/await;
-- `domainkit/server` — provider connection routes and an async Web handler factory;
-- `domainkit/testing` — in-memory services and provider tests.
+- `domainkit` — the Effect-native root: lifecycle services, host seams, providers, and values;
+- `domainkit/server` — the mountable route group, its layers, and the wire schemas;
+- `domainkit/client` — the capability-gated fetch transport and its Promise adapters;
+- `domainkit/testing` — fakes and conformance runners;
+- `domainkit/<Module>` — every root namespace as its own subpath (`domainkit/Principal`,
+  `domainkit/DnsRecord`, ...), the same module instances the root re-exports, for declaration
+  emit and bundlers that want the declaring module.
 
-Your app owns provider credentials, OAuth state, saved connections, plans, receipts, authorization,
-and audit history. DomainKit supplies the domain model and operations, not a hosted control plane.
-Cloudflare's provider namespace includes credential refresh; the host owns refresh locking,
-encrypted rotation, retry policy, and reconnect UX.
+Your app owns identity, tenancy, persistence, keys, routes, and consent. DomainKit supplies the
+lifecycle, not a hosted control plane.
 
 ## Learn more
 
 - [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://domain-kit.dev/docs/reference/providers)
-- [Examples](https://github.com/AryaLabsHQ/domainkit/tree/main/packages/domainkit/examples)
+- [Mounting the routes](https://github.com/AryaLabsHQ/domainkit/blob/main/packages/domainkit/examples/effect/server.ts)
+- [Writing a provider](https://github.com/AryaLabsHQ/domainkit/blob/main/packages/domainkit/examples/effect/provider.ts)
+- [Architecture decisions](https://github.com/AryaLabsHQ/domainkit/tree/main/packages/domainkit/docs/adr)
 - [Issues](https://github.com/AryaLabsHQ/domainkit/issues)
 
 ## License

package/dist/Approval.mjs

@@ -0,0 +1,34 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import { Digest, Kind, OperationId, PlanId } from "./Plan.mjs";
+import { decode as decode$1 } from "./internal/error.mjs";
+import { Schema } from "effect";
+//#region src/Approval.ts
+/**
+* A principal's consent to apply a specific plan digest. `Provision.apply` and `Cleanup.apply`
+* accept only an Approval. The word "authorization" is reserved for provider OAuth.
+*/
+var Approval_exports = /* @__PURE__ */ __exportAll({
+	ApprovalId: () => ApprovalId,
+	Model: () => Model,
+	decode: () => decode,
+	encode: () => encode
+});
+const ApprovalId = Schema.String.pipe(Schema.brand("@domainkit/ApprovalId"));
+var Model = class extends Schema.Class("@domainkit/Approval")({
+	id: ApprovalId,
+	version: Schema.Literal("domainkit.approval.v2"),
+	kind: Kind,
+	planId: PlanId,
+	digest: Digest,
+	/** Subset of the plan's write operations; the full set unless partial approval was requested. */
+	operationIds: Schema.Array(OperationId),
+	approvedBy: Schema.String,
+	approvedAt: Schema.DateTimeUtcFromString,
+	expiresAt: Schema.DateTimeUtcFromString
+}) {};
+const decode = (input) => decode$1(Model, input);
+const encode = Schema.encodeSync(Model);
+//#endregion
+export { ApprovalId, Approval_exports, Model, decode, encode };
+
+//# sourceMappingURL=Approval.mjs.map

package/dist/Approval.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Approval.mjs","names":["Plan.Kind","Plan.PlanId","Plan.Digest","Plan.OperationId","Errors.decode"],"sources":["../src/Approval.ts"],"sourcesContent":["/**\n * A principal's consent to apply a specific plan digest. `Provision.apply` and `Cleanup.apply`\n * accept only an Approval. The word \"authorization\" is reserved for provider OAuth.\n */\nimport { Effect, Schema } from \"effect\";\n\nimport * as Errors from \"./internal/error.ts\";\nimport * as Plan from \"./Plan.ts\";\n\nexport const ApprovalId = Schema.String.pipe(Schema.brand(\"@domainkit/ApprovalId\"));\nexport type ApprovalId = typeof ApprovalId.Type;\n\nexport class Model extends Schema.Class<Model>(\"@domainkit/Approval\")({\n  id: ApprovalId,\n  version: Schema.Literal(\"domainkit.approval.v2\"),\n  kind: Plan.Kind,\n  planId: Plan.PlanId,\n  digest: Plan.Digest,\n  /** Subset of the plan's write operations; the full set unless partial approval was requested. */\n  operationIds: Schema.Array(Plan.OperationId),\n  approvedBy: Schema.String,\n  approvedAt: Schema.DateTimeUtcFromString,\n  expiresAt: Schema.DateTimeUtcFromString,\n}) {}\nexport type Encoded = typeof Model.Encoded;\n\nexport const decode = (input: unknown): Effect.Effect<Model, Errors.DomainKitError> =>\n  Errors.decode(Model, input);\nexport const encode: (approval: Model) => Encoded = Schema.encodeSync(Model);\n"],"mappings":";;;;;;;;;;;;;;;AASA,MAAa,aAAa,OAAO,OAAO,KAAK,OAAO,MAAM,uBAAuB,CAAC;AAGlF,IAAa,QAAb,cAA2B,OAAO,MAAa,qBAAqB,CAAC,CAAC;CACpE,IAAI;CACJ,SAAS,OAAO,QAAQ,uBAAuB;CAC/C,MAAMA;CACN,QAAQC;CACR,QAAQC;;CAER,cAAc,OAAO,MAAMC,WAAgB;CAC3C,YAAY,OAAO;CACnB,YAAY,OAAO;CACnB,WAAW,OAAO;AACpB,CAAC,CAAC,CAAC,CAAC;AAGJ,MAAa,UAAU,UACrBC,SAAc,OAAO,KAAK;AAC5B,MAAa,SAAuC,OAAO,WAAW,KAAK"}

package/dist/Cleanup.mjs

@@ -0,0 +1,97 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import { decode } from "./DomainName.mjs";
+import { InvalidInput, NotFound } from "./Reason.mjs";
+import { fail } from "./internal/error.mjs";
+import { applied } from "./Receipt.mjs";
+import { Service as Service$1 } from "./Storage.mjs";
+import { Service as Service$2 } from "./Connect.mjs";
+import { assertWithin, cleanupOperation, make as make$1 } from "./internal/attempts.mjs";
+import { Policy } from "./Provision.mjs";
+import { Context, Effect, Layer, Option } from "effect";
+//#region src/Cleanup.ts
+/**
+* Remove only what a receipt proves DomainKit created, with its own plan, approval, and receipt.
+* Same three verbs as Provision; the plan is built from a receipt instead of requirements.
+*/
+var Cleanup_exports = /* @__PURE__ */ __exportAll({
+	Service: () => Service,
+	apply: () => apply,
+	approve: () => approve,
+	layer: () => layer,
+	make: () => make,
+	plan: () => plan,
+	reject: () => reject
+});
+var Service = class extends Context.Service()("@domainkit/Cleanup") {};
+const make = Effect.gen(function* () {
+	const storage = yield* Service$1;
+	const connect = yield* Service$2;
+	const attempts = make$1(storage, connect, "cleanup");
+	const sourceAttempt = (input) => Effect.gen(function* () {
+		if ("receiptId" in input) {
+			const attempt = yield* storage.attempts.byReceipt(input.receiptId);
+			if (attempt.kind !== "provisioning" || attempt.receipt === null) return yield* fail(new NotFound({
+				entity: "receipt",
+				id: input.receiptId
+			}));
+			return attempt;
+		}
+		const domain = yield* decode(input.domain);
+		const attachment = yield* storage.attachments.byDomain(domain);
+		const latest = Option.isSome(attachment) ? yield* storage.attempts.latest(attachment.value.id, "provisioning") : Option.none();
+		if (Option.isNone(latest) || latest.value.receipt === null) return yield* fail(new NotFound({
+			entity: "receipt",
+			id: domain
+		}));
+		return latest.value;
+	});
+	return {
+		plan: (input) => Effect.gen(function* () {
+			const policy = yield* Policy;
+			const source = yield* sourceAttempt(input);
+			const receipt = source.receipt;
+			if (receipt === null) return yield* fail(new NotFound({
+				entity: "receipt",
+				id: source.id
+			}));
+			const attachment = yield* storage.attachments.get(source.attachmentId);
+			yield* assertWithin(attachment, source.plan.operations.map((operation) => operation.record));
+			const { session, target } = yield* connect.session(attachment.id);
+			const dns = session.dns(target);
+			const operations = yield* Effect.forEach(applied(receipt), (applied) => Effect.gen(function* () {
+				const created = source.plan.operations.find((operation) => operation._tag === "Create" && operation.id === applied.operationId);
+				if (created === void 0) return yield* fail(new InvalidInput({
+					message: `Receipt ${receipt.id} proves no created record for ${applied.operationId}`,
+					field: "receiptId"
+				}));
+				return yield* cleanupOperation(dns, target.zone, created.id, created.record, applied.providerRecordId);
+			}));
+			return yield* attempts.record({
+				attachment,
+				target,
+				operations,
+				ttlMs: policy.planTtlMs,
+				sourceReceiptId: receipt.id
+			});
+		}),
+		approve: (plan, options) => attempts.approve(plan, options),
+		reject: (plan, options) => Effect.map(attempts.reject(plan, options), (attempt) => ({
+			plan: attempt.plan,
+			status: attempt.status,
+			approval: attempt.approval,
+			receipt: attempt.receipt,
+			rejection: attempt.rejection
+		})),
+		apply: (approval) => Effect.flatMap(Policy, (policy) => attempts.apply(approval, policy))
+	};
+});
+const layer = Layer.effect(Service)(make);
+const accessor = (pick) => (...args) => Effect.flatMap(Service, (service) => pick(service)(...args));
+const plan = accessor((service) => service.plan);
+const approve = accessor((service) => service.approve);
+const reject = accessor((service) => service.reject);
+const apply = accessor((service) => service.apply);
+//#endregion
+export { Cleanup_exports, Service, apply, approve, layer, make, plan, reject };
+
+//# sourceMappingURL=Cleanup.mjs.map

package/dist/Cleanup.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cleanup.mjs","names":["Storage.Service","Connect.Service","Attempts.make","Errors.fail","Reason.NotFound","DomainName.decode","Provision.Policy","Attempts.assertWithin","Receipt.applied","Reason.InvalidInput","Attempts.cleanupOperation"],"sources":["../src/Cleanup.ts"],"sourcesContent":["/**\n * Remove only what a receipt proves DomainKit created, with its own plan, approval, and receipt.\n * Same three verbs as Provision; the plan is built from a receipt instead of requirements.\n */\nimport { Context, Effect, Layer, Option } from \"effect\";\n\nimport type * as Approval from \"./Approval.ts\";\nimport * as Connect from \"./Connect.ts\";\nimport * as Errors from \"./internal/error.ts\";\nimport * as Reason from \"./Reason.ts\";\nimport * as DomainName from \"./DomainName.ts\";\nimport * as Attempts from \"./internal/attempts.ts\";\nimport type * as Plan from \"./Plan.ts\";\nimport type * as Principal from \"./Principal.ts\";\nimport * as Provision from \"./Provision.ts\";\nimport * as Receipt from \"./Receipt.ts\";\nimport * as Storage from \"./Storage.ts\";\n\ntype Fx<A> = Effect.Effect<A, Errors.DomainKitError, Principal.Service>;\n\nexport interface Interface {\n  /** Read back every receipt record; records that no longer match exactly become `Conflict`. */\n  readonly plan: (\n    input: { readonly receiptId: Receipt.ReceiptId } | { readonly domain: string },\n  ) => Fx<Plan.Model>;\n  readonly approve: (\n    plan: Plan.Model | Plan.PlanId,\n    options?: Attempts.ApproveOptions,\n  ) => Fx<Approval.Model>;\n  /** Decline the cleanup plan; terminal, same rules as `Provision.reject`. */\n  readonly reject: (\n    plan: Plan.Model | Plan.PlanId,\n    options?: Provision.RejectOptions,\n  ) => Fx<Provision.Attempt>;\n  readonly apply: (approval: Approval.Model | Approval.ApprovalId) => Fx<Receipt.Model>;\n}\n\nexport class Service extends Context.Service<Service, Interface>()(\"@domainkit/Cleanup\") {}\n\nexport const make: Effect.Effect<Interface, never, Storage.Service | Connect.Service> = Effect.gen(\n  function* () {\n    const storage = yield* Storage.Service;\n    const connect = yield* Connect.Service;\n    const attempts = Attempts.make(storage, connect, \"cleanup\");\n\n    const sourceAttempt = (\n      input: { readonly receiptId: Receipt.ReceiptId } | { readonly domain: string },\n    ) =>\n      Effect.gen(function* () {\n        if (\"receiptId\" in input) {\n          const attempt = yield* storage.attempts.byReceipt(input.receiptId);\n          if (attempt.kind !== \"provisioning\" || attempt.receipt === null) {\n            return yield* Errors.fail(\n              new Reason.NotFound({ entity: \"receipt\", id: input.receiptId }),\n            );\n          }\n          return attempt;\n        }\n        const domain = yield* DomainName.decode(input.domain);\n        const attachment = yield* storage.attachments.byDomain(domain);\n        const latest = Option.isSome(attachment)\n          ? yield* storage.attempts.latest(attachment.value.id, \"provisioning\")\n          : Option.none<Storage.Attempt>();\n        if (Option.isNone(latest) || latest.value.receipt === null) {\n          return yield* Errors.fail(new Reason.NotFound({ entity: \"receipt\", id: domain }));\n        }\n        return latest.value;\n      });\n\n    return {\n      plan: (input) =>\n        Effect.gen(function* () {\n          const policy = yield* Provision.Policy;\n          const source = yield* sourceAttempt(input);\n          const receipt = source.receipt;\n          if (receipt === null) {\n            return yield* Errors.fail(new Reason.NotFound({ entity: \"receipt\", id: source.id }));\n          }\n          const attachment = yield* storage.attachments.get(source.attachmentId);\n          yield* Attempts.assertWithin(\n            attachment,\n            source.plan.operations.map((operation) => operation.record),\n          );\n          const { session, target } = yield* connect.session(attachment.id);\n          const dns = session.dns(target);\n          const operations = yield* Effect.forEach(Receipt.applied(receipt), (applied) =>\n            Effect.gen(function* () {\n              const created = source.plan.operations.find(\n                (operation) => operation._tag === \"Create\" && operation.id === applied.operationId,\n              );\n              if (created === undefined) {\n                return yield* Errors.fail(\n                  new Reason.InvalidInput({\n                    message: `Receipt ${receipt.id} proves no created record for ${applied.operationId}`,\n                    field: \"receiptId\",\n                  }),\n                );\n              }\n              return yield* Attempts.cleanupOperation(\n                dns,\n                target.zone,\n                created.id,\n                created.record,\n                applied.providerRecordId,\n              );\n            }),\n          );\n          return yield* attempts.record({\n            attachment,\n            target,\n            operations,\n            ttlMs: policy.planTtlMs,\n            sourceReceiptId: receipt.id,\n          });\n        }),\n      approve: (plan, options) => attempts.approve(plan, options),\n      reject: (plan, options) =>\n        Effect.map(attempts.reject(plan, options), (attempt) => ({\n          plan: attempt.plan,\n          status: attempt.status,\n          approval: attempt.approval,\n          receipt: attempt.receipt,\n          rejection: attempt.rejection,\n        })),\n      apply: (approval) =>\n        Effect.flatMap(Provision.Policy, (policy) => attempts.apply(approval, policy)),\n    };\n  },\n);\n\nexport const layer: Layer.Layer<Service, never, Storage.Service | Connect.Service> =\n  Layer.effect(Service)(make);\n\nconst accessor =\n  <Args extends ReadonlyArray<unknown>, A>(\n    pick: (service: Interface) => (...args: Args) => Fx<A>,\n  ): ((...args: Args) => Effect.Effect<A, Errors.DomainKitError, Principal.Service | Service>) =>\n  (...args) =>\n    Effect.flatMap(Service, (service) => pick(service)(...args));\n\nexport const plan = accessor((service) => service.plan);\nexport const approve = accessor((service) => service.approve);\nexport const reject = accessor((service) => service.reject);\nexport const apply = accessor((service) => service.apply);\n"],"mappings":"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"}

package/dist/Cloudflare.mjs

@@ -0,0 +1,225 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import { decode } from "./DomainName.mjs";
+import { Unauthenticated, Unsupported } from "./Reason.mjs";
+import { fail } from "./internal/error.mjs";
+import { authorizationUrl, exchangeCode, refresh, revoke } from "./internal/oauth.mjs";
+import { make, resolveAmong, tokenAuth } from "./Provider.mjs";
+import { dns, listZones, provider as provider$1, tokenExpiry, verifyToken } from "./internal/cloudflare/client.mjs";
+import { resolve } from "./internal/config.mjs";
+import { Effect, Redacted, Schema } from "effect";
+//#region src/Cloudflare.ts
+/** Cloudflare: personal API tokens and OAuth. */
+var Cloudflare_exports = /* @__PURE__ */ __exportAll({
+	AccountContext: () => AccountContext,
+	TokenFields: () => TokenFields,
+	provider: () => provider,
+	server: () => server
+});
+/**
+* Authorization context: `accountId` is `null` when the credential spans several accounts or
+* none yet. Target context: the zone's account and zone id.
+*/
+const AccountContext = Schema.Struct({
+	accountId: Schema.NullOr(Schema.String),
+	/** How the token was verified: user tokens span accounts, account tokens are pinned. */
+	tokenKind: Schema.optionalKey(Schema.Literals(["user", "account"])),
+	zoneId: Schema.optionalKey(Schema.String)
+});
+/** Token-method input: the API token, and the account id for account-owned tokens. */
+const TokenFields = Schema.Struct({
+	token: Schema.RedactedFromValue(Schema.String),
+	accountId: Schema.optionalKey(Schema.String)
+});
+const server = {
+	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"
+};
+const defaultScopes = [
+	"zone:read",
+	"dns_records:edit",
+	"offline_access"
+];
+const capabilities = ["dns:read", "dns:write"];
+/** OAuth credentials pack both tokens into `secret`; token credentials are the token itself. */
+const Secret = Schema.fromJsonString(Schema.Struct({
+	accessToken: Schema.String,
+	refreshToken: Schema.NullOr(Schema.String)
+}));
+const parseSecret = (secret) => {
+	const raw = Redacted.value(secret);
+	const parsed = raw.startsWith("{") ? Schema.decodeUnknownOption(Secret)(raw) : void 0;
+	return parsed !== void 0 && parsed._tag === "Some" ? parsed.value : {
+		accessToken: raw,
+		refreshToken: null
+	};
+};
+const packSecret = (tokens) => Redacted.make(Schema.encodeSync(Secret)({
+	accessToken: tokens.accessToken,
+	refreshToken: tokens.refreshToken
+}));
+const provider = (options = {}) => {
+	const fetch = options.fetch ?? globalThis.fetch;
+	const baseUrl = (options.baseUrl ?? "https://api.cloudflare.com/client/v4").replace(/\/$/, "");
+	const client = (token) => ({
+		token,
+		fetch,
+		baseUrl
+	});
+	const discoverAccount = (token) => listZones(client(token)).pipe(Effect.map((zones) => {
+		const accounts = new Set(zones.map((zone) => zone.account.id));
+		const [only] = accounts;
+		return accounts.size === 1 && only !== void 0 ? only : null;
+	}));
+	const targetOf = (zone) => ({
+		zone: zone.name,
+		context: {
+			accountId: zone.account.id,
+			zoneId: zone.id
+		},
+		label: `${zone.name} (${zone.account.name})`,
+		nameservers: zone.name_servers ?? []
+	});
+	const oauthClient = (oauth) => Effect.gen(function* () {
+		return {
+			clientId: yield* resolve(oauth.clientId, "oauth.clientId"),
+			clientSecret: yield* resolve(oauth.clientSecret, "oauth.clientSecret"),
+			clientAuth: oauth.clientAuth ?? "client_secret_basic"
+		};
+	});
+	const issued = (tokens) => discoverAccount(tokens.accessToken).pipe(Effect.map((accountId) => ({
+		secret: packSecret(tokens),
+		context: { accountId },
+		expiresAt: tokens.expiresAt
+	})));
+	const oauth = options.oauth === void 0 ? void 0 : oauthAuth(options.oauth);
+	function oauthAuth(settings) {
+		const scopes = settings.scopes ?? defaultScopes;
+		return {
+			label: "Sign in with Cloudflare",
+			scopes,
+			start: (input) => oauthClient(settings).pipe(Effect.map(({ clientId }) => ({ authorizationUrl: authorizationUrl({
+				server,
+				clientId,
+				scopes,
+				state: input.state,
+				callbackUrl: input.callbackUrl,
+				codeChallenge: input.codeChallenge
+			}) }))),
+			complete: (input) => oauthClient(settings).pipe(Effect.flatMap((oauthClientValue) => exchangeCode({
+				provider: provider$1,
+				server,
+				client: oauthClientValue,
+				code: input.code,
+				state: input.params.state ?? "",
+				callbackUrl: input.callbackUrl,
+				codeVerifier: input.codeVerifier,
+				fetch
+			})), Effect.flatMap(issued)),
+			refresh: (credential) => Effect.gen(function* () {
+				const { refreshToken } = parseSecret(credential.secret);
+				if (refreshToken === null) return yield* fail(new Unauthenticated({ message: "Cloudflare credential has no refresh token" }));
+				const tokens = yield* refresh({
+					provider: provider$1,
+					server,
+					client: yield* oauthClient(settings),
+					refreshToken,
+					fetch
+				});
+				return {
+					secret: packSecret(tokens),
+					context: credential.context,
+					expiresAt: tokens.expiresAt
+				};
+			}),
+			revoke: (credential) => Effect.gen(function* () {
+				const { accessToken } = parseSecret(credential.secret);
+				yield* revoke({
+					provider: provider$1,
+					server,
+					client: yield* oauthClient(settings),
+					token: accessToken,
+					fetch
+				});
+			})
+		};
+	}
+	return make({
+		id: "cloudflare",
+		name: "Cloudflare",
+		context: AccountContext,
+		contextVersion: "cloudflare.v1",
+		auth: {
+			token: tokenAuth({
+				label: "API token",
+				docsUrl: "https://developers.cloudflare.com/fundamentals/api/get-started/create-token/",
+				requiredCapabilities: capabilities,
+				fields: TokenFields,
+				authenticate: ({ token, accountId }) => Effect.gen(function* () {
+					const raw = Redacted.value(token);
+					if (accountId !== void 0) {
+						const expiresAt = yield* verifyToken(client(raw), `/accounts/${encodeURIComponent(accountId)}/tokens/verify`);
+						return {
+							secret: token,
+							context: {
+								accountId,
+								tokenKind: "account"
+							},
+							expiresAt
+						};
+					}
+					const discovered = yield* discoverAccount(raw);
+					const verified = yield* tokenExpiry(client(raw), discovered);
+					return {
+						secret: token,
+						context: {
+							accountId: discovered,
+							tokenKind: verified.kind
+						},
+						expiresAt: verified.expiresAt
+					};
+				})
+			}),
+			...oauth === void 0 ? {} : { oauth }
+		},
+		session: (credential) => {
+			const { accessToken } = parseSecret(credential.secret);
+			const clientOptions = client(accessToken);
+			const context = Schema.decodeUnknownOption(AccountContext)(credential.context);
+			const accountId = context._tag === "Some" ? context.value.accountId ?? void 0 : void 0;
+			const listTargets = () => listZones(clientOptions, accountId).pipe(Effect.map((zones) => zones.map(targetOf)));
+			return {
+				capabilities: () => Effect.succeed(capabilities),
+				listTargets,
+				resolveTarget: (domain) => Effect.gen(function* () {
+					const name = yield* decode(domain);
+					const targets = yield* listTargets();
+					return resolveAmong(name, targets);
+				}),
+				dns: (target) => {
+					const zone = Schema.decodeUnknownOption(AccountContext)(target.context);
+					const zoneId = zone._tag === "Some" ? zone.value.zoneId : void 0;
+					if (zoneId === void 0) {
+						const failure = fail(new Unsupported({
+							provider: "cloudflare",
+							operation: "dns",
+							message: "Cloudflare target has no zone id; only zone targets host records"
+						}));
+						return {
+							list: () => failure,
+							create: () => failure,
+							get: () => failure,
+							delete: () => failure
+						};
+					}
+					return dns(clientOptions, zoneId);
+				}
+			};
+		}
+	});
+};
+//#endregion
+export { AccountContext, Cloudflare_exports, TokenFields, provider, server };
+
+//# sourceMappingURL=Cloudflare.mjs.map