domainkit 0.8.0 → 0.9.1

package/dist/types/DnsRecord.d.ts

@@ -0,0 +1,158 @@
+/**
+ * DNS record requirements a product asks a customer to satisfy, and the observed records a
+ * provider or resolver reports back.
+ *
+ * Constructors are lowercase functions (`DnsRecord.cname(...)`), Effect style. `policy` defaults
+ * to `exclusive` for CNAME and `append` for everything else; `ttl` defaults to `null` (provider
+ * default); `purpose` is an optional human label the UI shows.
+ */
+import { Schema } from "effect";
+export declare const Type: Schema.Literals<readonly ["A", "AAAA", "CNAME", "TXT", "MX", "CAA", "NS", "SRV"]>;
+export type Type = typeof Type.Type;
+export declare const Policy: Schema.Literals<readonly ["exclusive", "append"]>;
+export type Policy = typeof Policy.Type;
+declare const A_base: Schema.Class<A, Schema.TaggedStruct<"A", {
+    readonly name: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+    readonly ttl: Schema.NullOr<Schema.Int>;
+    readonly policy: Schema.Literals<readonly ["exclusive", "append"]>;
+    readonly purpose: Schema.optionalKey<Schema.String>;
+    readonly address: Schema.String;
+}>, {}>;
+export declare class A extends A_base {
+}
+declare const AAAA_base: Schema.Class<AAAA, Schema.TaggedStruct<"AAAA", {
+    readonly name: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+    readonly ttl: Schema.NullOr<Schema.Int>;
+    readonly policy: Schema.Literals<readonly ["exclusive", "append"]>;
+    readonly purpose: Schema.optionalKey<Schema.String>;
+    readonly address: Schema.String;
+}>, {}>;
+export declare class AAAA extends AAAA_base {
+}
+declare const CNAME_base: Schema.Class<CNAME, Schema.TaggedStruct<"CNAME", {
+    readonly name: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+    readonly ttl: Schema.NullOr<Schema.Int>;
+    readonly policy: Schema.Literals<readonly ["exclusive", "append"]>;
+    readonly purpose: Schema.optionalKey<Schema.String>;
+    readonly target: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+}>, {}>;
+export declare class CNAME extends CNAME_base {
+}
+declare const TXT_base: Schema.Class<TXT, Schema.TaggedStruct<"TXT", {
+    readonly name: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+    readonly ttl: Schema.NullOr<Schema.Int>;
+    readonly policy: Schema.Literals<readonly ["exclusive", "append"]>;
+    readonly purpose: Schema.optionalKey<Schema.String>;
+    readonly value: Schema.String;
+}>, {}>;
+export declare class TXT extends TXT_base {
+}
+declare const MX_base: Schema.Class<MX, Schema.TaggedStruct<"MX", {
+    readonly name: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+    readonly ttl: Schema.NullOr<Schema.Int>;
+    readonly policy: Schema.Literals<readonly ["exclusive", "append"]>;
+    readonly purpose: Schema.optionalKey<Schema.String>;
+    readonly exchange: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+    readonly priority: Schema.Int;
+}>, {}>;
+export declare class MX extends MX_base {
+}
+declare const CAA_base: Schema.Class<CAA, Schema.TaggedStruct<"CAA", {
+    readonly name: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+    readonly ttl: Schema.NullOr<Schema.Int>;
+    readonly policy: Schema.Literals<readonly ["exclusive", "append"]>;
+    readonly purpose: Schema.optionalKey<Schema.String>;
+    readonly flags: Schema.Int;
+    readonly tag: Schema.String;
+    readonly value: Schema.String;
+}>, {}>;
+export declare class CAA extends CAA_base {
+}
+declare const NS_base: Schema.Class<NS, Schema.TaggedStruct<"NS", {
+    readonly name: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+    readonly ttl: Schema.NullOr<Schema.Int>;
+    readonly policy: Schema.Literals<readonly ["exclusive", "append"]>;
+    readonly purpose: Schema.optionalKey<Schema.String>;
+    readonly nameserver: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+}>, {}>;
+export declare class NS extends NS_base {
+}
+declare const SRV_base: Schema.Class<SRV, Schema.TaggedStruct<"SRV", {
+    readonly name: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+    readonly ttl: Schema.NullOr<Schema.Int>;
+    readonly policy: Schema.Literals<readonly ["exclusive", "append"]>;
+    readonly purpose: Schema.optionalKey<Schema.String>;
+    readonly target: Schema.suspend<Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>>;
+    readonly port: Schema.Int;
+    readonly priority: Schema.Int;
+    readonly weight: Schema.Int;
+}>, {}>;
+export declare class SRV extends SRV_base {
+}
+export declare const Model: Schema.Union<readonly [typeof A, typeof AAAA, typeof CNAME, typeof TXT, typeof MX, typeof CAA, typeof NS, typeof SRV]>;
+export type Model = typeof Model.Type;
+export type Encoded = typeof Model.Encoded;
+declare const Opaque_base: Schema.Class<Opaque, Schema.TaggedStruct<"Opaque", {
+    readonly name: Schema.String;
+    readonly type: Schema.String;
+    readonly raw: Schema.Unknown;
+}>, {}>;
+/** A provider record DomainKit cannot model but must not overwrite. */
+export declare class Opaque extends Opaque_base {
+}
+export declare const Observed: Schema.Union<readonly [Schema.Union<readonly [typeof A, typeof AAAA, typeof CNAME, typeof TXT, typeof MX, typeof CAA, typeof NS, typeof SRV]>, typeof Opaque]>;
+export type Observed = typeof Observed.Type;
+type Options = {
+    readonly ttl?: number;
+    readonly policy?: Policy;
+    readonly purpose?: string;
+};
+export declare const a: (input: {
+    readonly name: string;
+    readonly address: string;
+} & Options) => A;
+export declare const aaaa: (input: {
+    readonly name: string;
+    readonly address: string;
+} & Options) => AAAA;
+export declare const cname: (input: {
+    readonly name: string;
+    readonly target: string;
+} & Omit<Options, "policy">) => CNAME;
+export declare const txt: (input: {
+    readonly name: string;
+    readonly value: string;
+} & Options) => TXT;
+export declare const mx: (input: {
+    readonly name: string;
+    readonly exchange: string;
+    readonly priority: number;
+} & Options) => MX;
+export declare const caa: (input: {
+    readonly name: string;
+    readonly flags: number;
+    readonly tag: string;
+    readonly value: string;
+} & Options) => CAA;
+export declare const ns: (input: {
+    readonly name: string;
+    readonly nameserver: string;
+} & Options) => NS;
+export declare const srv: (input: {
+    readonly name: string;
+    readonly target: string;
+    readonly port: number;
+    readonly priority: number;
+    readonly weight: number;
+} & Options) => SRV;
+export declare const isDnsRecord: (input: unknown) => input is Model;
+/** The record's data portion as a canonical string, for display and zone-file rendering. */
+export declare const data: (record: Model) => string;
+/**
+ * Structural equality over type, name, and data. `ttl`, `policy`, and `purpose` are requirement
+ * metadata, not record identity, so they are ignored; TTL drift is reported on plan operations.
+ */
+export declare const equals: (left: Observed, right: Observed) => boolean;
+/** `true` when both records occupy the same name and type, regardless of data. */
+export declare const sameSet: (left: Observed, right: Observed) => boolean;
+export {};

package/dist/types/DomainKit.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The composed layer. Provides every lifecycle service given a list of providers; the host
+ * provides `Storage` and `Custody` beneath it, the same way `Persistence.layer` sits over a
+ * backing store in Effect.
+ *
+ * Defaults: `Resolver.layer` (Cloudflare + Google DoH) and the `Policy` references. Override a
+ * policy with `Effect.provideService`; pass `resolver` for a different pool.
+ */
+import { Layer } from "effect";
+import * as Cleanup from "./Cleanup.ts";
+import * as Connect from "./Connect.ts";
+import * as Custody from "./Custody.ts";
+import { DomainKitError } from "./internal/error.ts";
+import type * as Provider from "./Provider.ts";
+import * as Providers from "./Providers.ts";
+import * as Provision from "./Provision.ts";
+import * as Resolver from "./Resolver.ts";
+import * as Storage from "./Storage.ts";
+import * as Verify from "./Verify.ts";
+export { DomainKitError as Error };
+export type { Category as ErrorCategory } from "./internal/error.ts";
+export declare const isError: (input: unknown) => input is DomainKitError;
+export interface Options {
+    readonly providers: ReadonlyArray<Provider.Definition>;
+    /** Replace the public DNS pool (e.g. `Testing.resolver()`); default `Resolver.layer`. */
+    readonly resolver?: Layer.Layer<Resolver.Service>;
+}
+export type Services = Provision.Service | Cleanup.Service | Connect.Service | Verify.Service | Providers.Service | Resolver.Service;
+export declare const layer: (options: Options) => Layer.Layer<Services, never, Storage.Service | Custody.Service>;
+/** `layer` with `Storage.layerMemory` and a throwaway custody key. Tests and playgrounds only. */
+export declare const layerMemory: (options: Options) => Layer.Layer<Services | Storage.Service | Custody.Service, DomainKitError>;

package/dist/types/DomainName.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A normalized, IDN-aware hostname. Lifecycle inputs accept plain strings and validate them, so
+ * most hosts never construct this directly; it exists for hosts that want the brand in their own
+ * types.
+ */
+import { Effect, Option, Schema } from "effect";
+import * as Errors from "./internal/error.ts";
+declare const Branded: Schema.brand<Schema.String, "@domainkit/DomainName">;
+/** Decodes any hostname spelling into its normalized, branded form; encodes back to a string. */
+export declare const Model: Schema.decodeTo<Schema.brand<Schema.String, "@domainkit/DomainName">, Schema.String, never, never>;
+export type Model = typeof Branded.Type;
+/** Validates and normalizes; `None` when the input is not a hostname. */
+export declare const fromString: (input: string) => Option.Option<Model>;
+/** Validates and normalizes; throws `DomainKit.Error` (reason `InvalidInput`) when invalid. */
+export declare const fromStringUnsafe: (input: string) => Model;
+/** Validates and normalizes inside Effect; fails with reason `InvalidInput`. */
+export declare const decode: (input: string, field?: string) => Effect.Effect<Model, Errors.DomainKitError>;
+export declare const isDomainName: (input: unknown) => input is Model;
+/**
+ * Zone candidates from the name itself down to the registrable domain, most specific first:
+ * `a.b.example.com` -> `a.b.example.com`, `b.example.com`, `example.com`. Empty when the name has
+ * no registrable suffix.
+ */
+export declare const candidates: (domain: Model) => ReadonlyArray<Model>;
+/** `true` when `name` is `zone` or a subdomain of it. */
+export declare const isWithin: (name: string, zone: string) => boolean;
+export {};

package/dist/types/Plan.d.ts

@@ -0,0 +1,76 @@
+/**
+ * A reviewable, digest-bound set of DNS operations. Plans are additive and fail closed: matching
+ * records are `Noop`, missing records are `Create`, incompatible state is `Conflict`. A
+ * provisioning plan never updates or deletes; a cleanup plan carries `Delete` operations for
+ * records a receipt proves DomainKit created.
+ */
+import { Effect, Schema } from "effect";
+import * as DnsRecord from "./DnsRecord.ts";
+import * as Errors from "./internal/error.ts";
+export declare const PlanId: Schema.brand<Schema.String, "@domainkit/PlanId">;
+export type PlanId = typeof PlanId.Type;
+export declare const Digest: Schema.brand<Schema.String, "@domainkit/Digest">;
+export type Digest = typeof Digest.Type;
+export declare const OperationId: Schema.brand<Schema.String, "@domainkit/OperationId">;
+export type OperationId = typeof OperationId.Type;
+export declare const Kind: Schema.Literals<readonly ["provisioning", "cleanup"]>;
+export type Kind = typeof Kind.Type;
+declare const Create_base: Schema.Class<Create, Schema.TaggedStruct<"Create", {
+    readonly id: Schema.brand<Schema.String, "@domainkit/OperationId">;
+    readonly record: Schema.suspend<Schema.Union<readonly [typeof DnsRecord.A, typeof DnsRecord.AAAA, typeof DnsRecord.CNAME, typeof DnsRecord.TXT, typeof DnsRecord.MX, typeof DnsRecord.CAA, typeof DnsRecord.NS, typeof DnsRecord.SRV]>>;
+}>, {}>;
+export declare class Create extends Create_base {
+}
+declare const Noop_base: Schema.Class<Noop, Schema.TaggedStruct<"Noop", {
+    readonly id: Schema.brand<Schema.String, "@domainkit/OperationId">;
+    readonly record: Schema.suspend<Schema.Union<readonly [typeof DnsRecord.A, typeof DnsRecord.AAAA, typeof DnsRecord.CNAME, typeof DnsRecord.TXT, typeof DnsRecord.MX, typeof DnsRecord.CAA, typeof DnsRecord.NS, typeof DnsRecord.SRV]>>;
+    readonly existing: Schema.suspend<Schema.Union<readonly [Schema.Union<readonly [typeof DnsRecord.A, typeof DnsRecord.AAAA, typeof DnsRecord.CNAME, typeof DnsRecord.TXT, typeof DnsRecord.MX, typeof DnsRecord.CAA, typeof DnsRecord.NS, typeof DnsRecord.SRV]>, typeof DnsRecord.Opaque]>>;
+    readonly ttlDrift: Schema.Boolean;
+}>, {}>;
+export declare class Noop extends Noop_base {
+}
+declare const Conflict_base: Schema.Class<Conflict, Schema.TaggedStruct<"Conflict", {
+    readonly id: Schema.brand<Schema.String, "@domainkit/OperationId">;
+    readonly record: Schema.suspend<Schema.Union<readonly [typeof DnsRecord.A, typeof DnsRecord.AAAA, typeof DnsRecord.CNAME, typeof DnsRecord.TXT, typeof DnsRecord.MX, typeof DnsRecord.CAA, typeof DnsRecord.NS, typeof DnsRecord.SRV]>>;
+    readonly existing: Schema.$Array<Schema.suspend<Schema.Union<readonly [Schema.Union<readonly [typeof DnsRecord.A, typeof DnsRecord.AAAA, typeof DnsRecord.CNAME, typeof DnsRecord.TXT, typeof DnsRecord.MX, typeof DnsRecord.CAA, typeof DnsRecord.NS, typeof DnsRecord.SRV]>, typeof DnsRecord.Opaque]>>>;
+    readonly reason: Schema.Literals<readonly ["exclusive-name", "cname-collision", "value-mismatch", "opaque", "missing"]>;
+}>, {}>;
+export declare class Conflict extends Conflict_base {
+}
+declare const Delete_base: Schema.Class<Delete, Schema.TaggedStruct<"Delete", {
+    readonly id: Schema.brand<Schema.String, "@domainkit/OperationId">;
+    readonly record: Schema.suspend<Schema.Union<readonly [typeof DnsRecord.A, typeof DnsRecord.AAAA, typeof DnsRecord.CNAME, typeof DnsRecord.TXT, typeof DnsRecord.MX, typeof DnsRecord.CAA, typeof DnsRecord.NS, typeof DnsRecord.SRV]>>;
+    readonly providerRecordId: Schema.String;
+}>, {}>;
+/** Cleanup only: remove the provider record a receipt proves DomainKit created. */
+export declare class Delete extends Delete_base {
+}
+export declare const Operation: Schema.Union<readonly [typeof Create, typeof Noop, typeof Conflict, typeof Delete]>;
+export type Operation = typeof Operation.Type;
+export declare const Version: Schema.Literal<"domainkit.plan.v2">;
+declare const Model_base: Schema.Class<Model, Schema.Struct<{
+    readonly id: Schema.brand<Schema.String, "@domainkit/PlanId">;
+    readonly version: Schema.Literal<"domainkit.plan.v2">;
+    readonly kind: Schema.Literals<readonly ["provisioning", "cleanup"]>;
+    readonly digest: Schema.brand<Schema.String, "@domainkit/Digest">;
+    readonly domain: Schema.String;
+    readonly zone: Schema.String;
+    readonly provider: Schema.String;
+    readonly attachmentId: Schema.String;
+    readonly operations: Schema.$Array<Schema.Union<readonly [typeof Create, typeof Noop, typeof Conflict, typeof Delete]>>;
+    readonly createdAt: Schema.DateTimeUtcFromString;
+    readonly expiresAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+export declare class Model extends Model_base {
+}
+export type Encoded = typeof Model.Encoded;
+export declare const decode: (input: unknown) => Effect.Effect<Model, Errors.DomainKitError>;
+export declare const encode: (plan: Model) => Encoded;
+/** `true` when the plan has no conflicts and at least one write (`Create` or `Delete`). */
+export declare const isApplicable: (plan: Model) => boolean;
+export declare const conflicts: (plan: Model) => ReadonlyArray<Conflict>;
+/** The operations that would touch the provider: creates for provisioning, deletes for cleanup. */
+export declare const writes: (plan: Model) => ReadonlyArray<Create | Delete>;
+/** Manual instructions for hosts whose customers apply records by hand. */
+export declare const renderInstructions: (plan: Model) => string;
+export {};

package/dist/types/Principal.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Who is acting. Required by every lifecycle operation and every Storage query; there is no
+ * default, so cross-tenant access is a type error rather than a runtime check. `domainkit/server`
+ * provides it per request from the host's `Identity`.
+ */
+import { Context, Layer } from "effect";
+export interface Interface {
+    /** Tenant boundary: organization, workspace, account. Storage scopes every row by it. */
+    readonly ownerId: string;
+    /** The user or automation acting on the tenant's behalf; recorded on approvals and receipts. */
+    readonly actorId: string;
+}
+declare const Service_base: Context.ServiceClass<Service, "@domainkit/Principal", Interface>;
+export declare class Service extends Service_base {
+}
+export declare const make: (input: Interface) => Interface;
+export declare const layer: (input: Interface) => Layer.Layer<Service>;
+export {};

package/dist/types/Provider.d.ts

@@ -0,0 +1,248 @@
+/**
+ * One declarative definition per DNS provider. Auth methods are optional cases, so a provider that
+ * only issues personal tokens declares `token` and nothing else. The definition drives connection
+ * routes, refresh, the UI method catalog, and rebuilding a session from stored context.
+ */
+import { Data, type DateTime, Effect, Redacted, Schema } from "effect";
+import type * as DnsRecord from "./DnsRecord.ts";
+import * as Errors from "./internal/error.ts";
+import * as DomainName from "./DomainName.ts";
+import type { Capability } from "./Storage.ts";
+export type Fx<A> = Effect.Effect<A, Errors.DomainKitError>;
+/** A record as the provider reports it, with the id needed to read or delete it later. */
+export interface ObservedRecord {
+    readonly record: DnsRecord.Observed;
+    readonly providerRecordId: string | null;
+}
+/** What a session can do inside one zone. The only thing planning and applying touch. */
+export interface Dns {
+    readonly list: (zone: string) => Fx<ReadonlyArray<ObservedRecord>>;
+    /** Must return the provider's id for the new record; cleanup deletes by that id. */
+    readonly create: (zone: string, record: DnsRecord.Model) => Fx<{
+        readonly providerRecordId: string;
+    }>;
+    readonly get: (zone: string, providerRecordId: string) => Fx<DnsRecord.Observed | null>;
+    readonly delete: (zone: string, providerRecordId: string) => Fx<void>;
+}
+/** A zone the credential can reach, with the provider identity needed to address it later. */
+export interface Target {
+    readonly zone: string;
+    readonly context: unknown;
+    readonly label: string;
+    /** The zone's nameservers as the provider reports them; `Connect.discover` matches on them. */
+    readonly nameservers?: ReadonlyArray<string>;
+}
+export type Resolution = Data.TaggedEnum<{
+    Resolved: {
+        readonly target: Target;
+    };
+    SelectionRequired: {
+        readonly candidates: ReadonlyArray<Target>;
+    };
+    NotFound: {};
+}>;
+export declare const Resolution: {
+    readonly $is: <Tag extends "NotFound" | "Resolved" | "SelectionRequired">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "NotFound";
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Resolved";
+        readonly target: Target;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "SelectionRequired";
+        readonly candidates: ReadonlyArray<Target>;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <Cases extends { readonly [Tag in "NotFound" | "Resolved" | "SelectionRequired"]: (args: Extract<{
+            readonly _tag: "NotFound";
+        } | {
+            readonly _tag: "Resolved";
+            readonly target: Target;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<Target>;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(cases: Cases): (value: {
+            readonly _tag: "NotFound";
+        } | {
+            readonly _tag: "Resolved";
+            readonly target: Target;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<Target>;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["NotFound" | "Resolved" | "SelectionRequired"]>>;
+        <Cases extends { readonly [Tag in "NotFound" | "Resolved" | "SelectionRequired"]: (args: Extract<{
+            readonly _tag: "NotFound";
+        } | {
+            readonly _tag: "Resolved";
+            readonly target: Target;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<Target>;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(value: {
+            readonly _tag: "NotFound";
+        } | {
+            readonly _tag: "Resolved";
+            readonly target: Target;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<Target>;
+        }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["NotFound" | "Resolved" | "SelectionRequired"]>>;
+    };
+    readonly NotFound: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "NotFound";
+    }, "_tag">;
+    readonly Resolved: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Resolved";
+        readonly target: Target;
+    }, "_tag">;
+    readonly SelectionRequired: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "SelectionRequired";
+        readonly candidates: ReadonlyArray<Target>;
+    }, "_tag">;
+};
+/** A credential bound to provider account context. */
+export interface Session {
+    readonly listTargets: () => Fx<ReadonlyArray<Target>>;
+    readonly resolveTarget: (domain: string) => Fx<Resolution>;
+    readonly dns: (target: Target) => Dns;
+    /** Capabilities actually held; promoted onto the authorization after first use. */
+    readonly capabilities: () => Fx<ReadonlyArray<Capability>>;
+}
+/**
+ * Secret material plus the account context needed to rebuild a session. `secret` is opaque to
+ * DomainKit: a provider may pack an access token and a refresh token into it.
+ */
+export interface Credential {
+    readonly secret: Redacted.Redacted<string>;
+    readonly context: unknown;
+}
+/** A credential the provider just issued or refreshed; `null` expiry means it does not expire. */
+export interface IssuedCredential extends Credential {
+    readonly expiresAt: DateTime.Utc | null;
+}
+/** Raw token-method input keyed by the provider's declared field names. */
+export type TokenValues = Readonly<Record<string, Redacted.Redacted<string> | undefined>>;
+export interface TokenAuth {
+    readonly label: string;
+    /** Where the customer creates the token; shown in the UI. */
+    readonly docsUrl?: string;
+    readonly requiredCapabilities: ReadonlyArray<Capability>;
+    /**
+     * The values this method needs, declared once so forms render from it: secrets as
+     * `Schema.RedactedFromValue(Schema.String)`, optional ones through `Schema.optionalKey`.
+     */
+    readonly fields: Schema.Struct<Schema.Struct.Fields>;
+    /** Validate the values (already decoded with `fields`) and return account context. */
+    readonly authenticate: (values: TokenValues) => Fx<IssuedCredential>;
+}
+/** Build a `TokenAuth` whose `authenticate` receives the record decoded by `fields`. */
+/** Field schemas whose decoding needs no services, so `authenticate` stays a plain `Fx`. */
+export type TokenFieldSchemas = {
+    readonly [name: string]: Schema.ConstraintDecoder<unknown>;
+};
+export declare const tokenAuth: <const Fields extends TokenFieldSchemas>(input: {
+    readonly label: string;
+    readonly docsUrl?: string;
+    readonly requiredCapabilities: ReadonlyArray<Capability>;
+    readonly fields: Schema.Struct<Fields>;
+    readonly authenticate: (values: Schema.Struct<Fields>["Type"]) => Fx<IssuedCredential>;
+}) => TokenAuth;
+export interface FieldDescriptor {
+    readonly name: string;
+    readonly required: boolean;
+    readonly secret: boolean;
+}
+/** What a UI needs to render one auth method; `fields` is `null` for interactive methods. */
+export interface MethodDescriptor {
+    readonly kind: AuthMethod;
+    readonly label: string;
+    readonly docsUrl: string | null;
+    readonly fields: ReadonlyArray<FieldDescriptor> | null;
+}
+/** Field descriptors derived from `TokenAuth.fields`: optional keys are not required, `Redacted` values are secret. */
+export declare const tokenFields: (auth: TokenAuth) => ReadonlyArray<FieldDescriptor>;
+export declare const describeMethods: (definition: Definition) => ReadonlyArray<MethodDescriptor>;
+export interface CallbackInput {
+    readonly code: string;
+    /** The redirect URI registered at start; token exchanges echo it. */
+    readonly callbackUrl: string;
+    /** Every query parameter the provider appended to the callback. */
+    readonly params: Readonly<Record<string, string>>;
+}
+export interface OAuthAuth {
+    readonly label: string;
+    readonly scopes: ReadonlyArray<string>;
+    readonly start: (input: {
+        readonly state: string;
+        readonly callbackUrl: string;
+        readonly codeChallenge: string;
+    }) => Fx<{
+        readonly authorizationUrl: string;
+    }>;
+    readonly complete: (input: CallbackInput & {
+        readonly codeVerifier: string;
+    }) => Fx<IssuedCredential>;
+    readonly refresh: (credential: Credential) => Fx<IssuedCredential>;
+    readonly revoke?: (credential: Credential) => Fx<void>;
+}
+/** Marketplace-style installs (Vercel integrations) that redirect but are not OAuth. */
+export interface IntegrationAuth {
+    readonly label: string;
+    readonly start: (input: {
+        readonly state: string;
+        readonly callbackUrl: string;
+    }) => Fx<{
+        readonly authorizationUrl: string;
+    }>;
+    readonly complete: (input: CallbackInput) => Fx<IssuedCredential>;
+    readonly refresh?: (credential: Credential) => Fx<IssuedCredential>;
+    readonly revoke?: (credential: Credential) => Fx<void>;
+}
+export interface Definition<Context = unknown> {
+    readonly id: string;
+    readonly name: string;
+    readonly auth: {
+        readonly token?: TokenAuth;
+        readonly oauth?: OAuthAuth;
+        readonly integration?: IntegrationAuth;
+    };
+    /** Schema for the account/zone context stored on authorizations and attachments. */
+    readonly context: Schema.Codec<Context, unknown, never, never>;
+    /** Tag written into every stored context envelope, e.g. `cloudflare.v1`; bump it with the schema. */
+    readonly contextVersion: string;
+    /** Upgrade an envelope written under an older `contextVersion`; absent means `Unsupported`. */
+    readonly migrateContext?: (envelope: Envelope) => Fx<Context>;
+    readonly session: (credential: Credential) => Session;
+}
+/** How provider context is persisted: the definition's version tag beside the encoded value. */
+export declare const Envelope: Schema.Struct<{
+    readonly version: Schema.String;
+    readonly value: Schema.Unknown;
+}>;
+export type Envelope = typeof Envelope.Type;
+/** Wrap a context value for storage; a value the schema rejects fails `InvalidInput`. */
+export declare const encodeContext: <Context>(definition: Definition<Context>, value: Context) => Effect.Effect<Envelope, Errors.DomainKitError>;
+export type AuthMethod = "token" | "oauth" | "integration";
+/** Validates a definition: an id and at least one auth method. Throws `DomainKit.Error` otherwise. */
+export declare const make: <Context>(definition: Definition<Context>) => Definition<Context>;
+export declare const methods: (definition: Definition) => ReadonlyArray<AuthMethod>;
+/**
+ * Pick the most specific zone among `targets` for `domain`: exactly one match resolves, several
+ * matches at the same depth need a selection, none is `NotFound`.
+ */
+export declare const resolveAmong: (domain: DomainName.Model, targets: ReadonlyArray<Target>) => Resolution;
+/**
+ * Decode a stored envelope: the current version decodes with `context`, an older one goes
+ * through `migrateContext`, anything else fails `Unsupported`.
+ */
+export declare const decodeContext: <Context>(definition: Definition<Context>, stored: unknown) => Effect.Effect<Context, Errors.DomainKitError>;
+export { type AsyncCredential, type AsyncDefinition, type AsyncDns, type AsyncIntegrationAuth, type AsyncIssuedCredential, type AsyncOAuthAuth, type AsyncSession, type AsyncTokenAuth, fromAsync, } from "./internal/provider-async.ts";

package/dist/types/Providers.d.ts

@@ -0,0 +1,16 @@
+/** The registry of provider definitions a host enabled. Built by `DomainKit.layer`. */
+import { Context, Effect, Layer } from "effect";
+import * as Errors from "./internal/error.ts";
+import * as Provider from "./Provider.ts";
+export interface Interface {
+    readonly get: (id: string) => Effect.Effect<Provider.Definition, Errors.DomainKitError>;
+    readonly list: () => ReadonlyArray<Provider.Definition>;
+    /** For UI catalogs: which methods each provider offers. */
+    readonly methods: (id: string) => Effect.Effect<ReadonlyArray<Provider.AuthMethod>, Errors.DomainKitError>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@domainkit/Providers", Interface>;
+export declare class Service extends Service_base {
+}
+export declare const make: (definitions: ReadonlyArray<Provider.Definition>) => Interface;
+export declare const layer: (definitions: ReadonlyArray<Provider.Definition>) => Layer.Layer<Service>;
+export {};

package/dist/types/Provision.d.ts

@@ -0,0 +1,75 @@
+/**
+ * plan -> approve -> apply, durable. 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, and a retry of any step
+ * is idempotent.
+ */
+import { Context, Effect, Layer } from "effect";
+import type * as Approval from "./Approval.ts";
+import * as Connect from "./Connect.ts";
+import type * as DnsRecord from "./DnsRecord.ts";
+import * as Errors from "./internal/error.ts";
+import * as Attempts from "./internal/attempts.ts";
+import type * as Plan from "./Plan.ts";
+import type * as Principal from "./Principal.ts";
+import type * as Receipt from "./Receipt.ts";
+import * as Storage from "./Storage.ts";
+type Fx<A> = Effect.Effect<A, Errors.DomainKitError, Principal.Service>;
+export interface Attempt {
+    readonly plan: Plan.Model;
+    readonly status: Storage.AttemptStatus;
+    readonly approval: Approval.Model | null;
+    readonly receipt: Receipt.Model | null;
+    readonly rejection: Storage.Rejection | null;
+}
+export interface RejectOptions {
+    readonly reason?: string;
+}
+export interface Interface {
+    /** Read provider state and build an additive plan. Fails `NotFound` when the domain is not attached. */
+    readonly plan: (input: {
+        readonly domain: string;
+        readonly requirements: ReadonlyArray<DnsRecord.Model>;
+    }) => Fx<Plan.Model>;
+    /**
+     * Record the principal's consent. Fails `Conflict` unless `allowPartial` and the selected
+     * operations are conflict-free. Approving an already-approved plan returns the same approval.
+     */
+    readonly approve: (plan: Plan.Model | Plan.PlanId, options?: Attempts.ApproveOptions) => Fx<Approval.Model>;
+    /**
+     * Decline the plan for the acting principal; terminal. Rejecting again returns the same
+     * attempt; a plan that was approved or applied fails `Stale`.
+     */
+    readonly reject: (plan: Plan.Model | Plan.PlanId, options?: RejectOptions) => Fx<Attempt>;
+    /**
+     * Re-plan the zone, fail `Stale` if the digest moved, then create records. Partial success is a
+     * `partial` receipt. Applying an attempt that already completed returns its receipt.
+     */
+    readonly apply: (approval: Approval.Model | Approval.ApprovalId) => Fx<Receipt.Model>;
+    readonly get: (planId: Plan.PlanId) => Fx<Attempt>;
+    readonly latest: (domain: string) => Fx<Attempt | null>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@domainkit/Provision", Interface>;
+export declare class Service extends Service_base {
+}
+export interface PolicyShape {
+    /** Plan lifetime before it must be rebuilt. Default 1 hour. */
+    readonly planTtlMs: number;
+    /** Apply lease; a crashed apply can be retried after this. Default 2 minutes. */
+    readonly applyLeaseMs: number;
+}
+export declare const defaults: PolicyShape;
+declare const Policy_base: Context.Reference<PolicyShape>;
+export declare class Policy extends Policy_base {
+}
+export declare const make: Effect.Effect<Interface, never, Storage.Service | Connect.Service>;
+export declare const layer: Layer.Layer<Service, never, Storage.Service | Connect.Service>;
+export declare const plan: (input: {
+    readonly domain: string;
+    readonly requirements: ReadonlyArray<DnsRecord.Model>;
+}) => Effect.Effect<Plan.Model, Errors.DomainKitError, Principal.Service | Service>;
+export declare const approve: (plan: Plan.Model | (string & import("effect/Brand").Brand<"@domainkit/PlanId">), options?: Attempts.ApproveOptions | undefined) => Effect.Effect<Approval.Model, Errors.DomainKitError, Principal.Service | Service>;
+export declare const reject: (plan: Plan.Model | (string & import("effect/Brand").Brand<"@domainkit/PlanId">), options?: RejectOptions | undefined) => Effect.Effect<Attempt, Errors.DomainKitError, Principal.Service | Service>;
+export declare const apply: (approval: Approval.Model | (string & import("effect/Brand").Brand<"@domainkit/ApprovalId">)) => Effect.Effect<Receipt.Model, Errors.DomainKitError, Principal.Service | Service>;
+export declare const get: (planId: string & import("effect/Brand").Brand<"@domainkit/PlanId">) => Effect.Effect<Attempt, Errors.DomainKitError, Principal.Service | Service>;
+export declare const latest: (domain: string) => Effect.Effect<Attempt | null, Errors.DomainKitError, Principal.Service | Service>;
+export {};