domainkit 0.8.0 → 0.9.0

package/dist/types/Connect.d.ts

@@ -0,0 +1,506 @@
+/**
+ * Connect a provider, attach domains to it, and keep the credential alive. Interactive methods
+ * (OAuth, integration) return a redirect and complete on callback; token methods connect in one
+ * call. Reuse of an existing connection for a new domain is `attach`.
+ */
+import { Context, Data, Effect, Layer, Redacted } from "effect";
+import * as Custody from "./Custody.ts";
+import * as Errors from "./internal/error.ts";
+import * as Principal from "./Principal.ts";
+import * as Provider from "./Provider.ts";
+import * as Providers from "./Providers.ts";
+import * as Resolver from "./Resolver.ts";
+import * as Storage from "./Storage.ts";
+type Fx<A> = Effect.Effect<A, Errors.DomainKitError, Principal.Service>;
+export type Method = Data.TaggedEnum<{
+    /** Values keyed by the provider's declared `auth.token.fields`. */
+    Token: {
+        readonly values: Provider.TokenValues;
+    };
+    OAuth: {
+        readonly returnTo?: string;
+    };
+    Integration: {
+        readonly returnTo?: string;
+    };
+}>;
+/** `token` accepts a lone string (`{ token }`) or a record; every value is wrapped in `Redacted`. */
+export declare const Method: {
+    readonly $is: <Tag extends "Integration" | "OAuth" | "Token">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Integration";
+        readonly returnTo?: string;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "OAuth";
+        readonly returnTo?: string;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Token";
+        readonly values: Provider.TokenValues;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <Cases extends { readonly [Tag in "Integration" | "OAuth" | "Token"]: (args: Extract<{
+            readonly _tag: "Integration";
+            readonly returnTo?: string;
+        } | {
+            readonly _tag: "OAuth";
+            readonly returnTo?: string;
+        } | {
+            readonly _tag: "Token";
+            readonly values: Provider.TokenValues;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(cases: Cases): (value: {
+            readonly _tag: "Integration";
+            readonly returnTo?: string;
+        } | {
+            readonly _tag: "OAuth";
+            readonly returnTo?: string;
+        } | {
+            readonly _tag: "Token";
+            readonly values: Provider.TokenValues;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["Integration" | "OAuth" | "Token"]>>;
+        <Cases extends { readonly [Tag in "Integration" | "OAuth" | "Token"]: (args: Extract<{
+            readonly _tag: "Integration";
+            readonly returnTo?: string;
+        } | {
+            readonly _tag: "OAuth";
+            readonly returnTo?: string;
+        } | {
+            readonly _tag: "Token";
+            readonly values: Provider.TokenValues;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(value: {
+            readonly _tag: "Integration";
+            readonly returnTo?: string;
+        } | {
+            readonly _tag: "OAuth";
+            readonly returnTo?: string;
+        } | {
+            readonly _tag: "Token";
+            readonly values: Provider.TokenValues;
+        }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Integration" | "OAuth" | "Token"]>>;
+    };
+    readonly token: (values: string | Readonly<Record<string, Redacted.Redacted<string> | string | undefined>>) => Method;
+    readonly oauth: (options?: {
+        readonly returnTo?: string;
+    }) => Method;
+    readonly integration: (options?: {
+        readonly returnTo?: string;
+    }) => Method;
+    readonly Integration: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Integration";
+        readonly returnTo?: string;
+    }, "_tag">;
+    readonly OAuth: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "OAuth";
+        readonly returnTo?: string;
+    }, "_tag">;
+    readonly Token: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Token";
+        readonly values: Provider.TokenValues;
+    }, "_tag">;
+};
+/** Everything the UI needs about a domain's provider state. */
+export interface Snapshot {
+    readonly domain: string;
+    readonly attachment: Storage.Attachment | null;
+    readonly connection: Storage.Connection | null;
+    readonly authorization: Pick<Storage.Authorization, "id" | "provider" | "method" | "capabilities" | "revocation"> | null;
+    readonly lastReceiptId: string | null;
+    /** Other connections of this owner that could serve this domain. */
+    readonly reusable: ReadonlyArray<{
+        readonly connection: Storage.Connection;
+        readonly provider: string;
+        readonly method: Storage.AuthMethod;
+    }>;
+    readonly providers: ReadonlyArray<{
+        readonly id: string;
+        readonly name: string;
+        readonly methods: ReadonlyArray<Provider.MethodDescriptor>;
+    }>;
+}
+export type Started = Data.TaggedEnum<{
+    Connected: {
+        readonly connection: Storage.Connection;
+        readonly attachment: Storage.Attachment | null;
+    };
+    Redirect: {
+        readonly authorizationUrl: string;
+        readonly continuationId: string;
+    };
+    SelectionRequired: {
+        readonly connection: Storage.Connection;
+        readonly candidates: ReadonlyArray<Provider.Target>;
+    };
+}>;
+export declare const Started: {
+    readonly $is: <Tag extends "Connected" | "Redirect" | "SelectionRequired">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "Connected";
+        readonly connection: Storage.Connection;
+        readonly attachment: Storage.Attachment | null;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Redirect";
+        readonly authorizationUrl: string;
+        readonly continuationId: string;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "SelectionRequired";
+        readonly connection: Storage.Connection;
+        readonly candidates: ReadonlyArray<Provider.Target>;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <Cases extends { readonly [Tag in "Connected" | "Redirect" | "SelectionRequired"]: (args: Extract<{
+            readonly _tag: "Connected";
+            readonly connection: Storage.Connection;
+            readonly attachment: Storage.Attachment | null;
+        } | {
+            readonly _tag: "Redirect";
+            readonly authorizationUrl: string;
+            readonly continuationId: string;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly connection: Storage.Connection;
+            readonly candidates: ReadonlyArray<Provider.Target>;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(cases: Cases): (value: {
+            readonly _tag: "Connected";
+            readonly connection: Storage.Connection;
+            readonly attachment: Storage.Attachment | null;
+        } | {
+            readonly _tag: "Redirect";
+            readonly authorizationUrl: string;
+            readonly continuationId: string;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly connection: Storage.Connection;
+            readonly candidates: ReadonlyArray<Provider.Target>;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["Connected" | "Redirect" | "SelectionRequired"]>>;
+        <Cases extends { readonly [Tag in "Connected" | "Redirect" | "SelectionRequired"]: (args: Extract<{
+            readonly _tag: "Connected";
+            readonly connection: Storage.Connection;
+            readonly attachment: Storage.Attachment | null;
+        } | {
+            readonly _tag: "Redirect";
+            readonly authorizationUrl: string;
+            readonly continuationId: string;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly connection: Storage.Connection;
+            readonly candidates: ReadonlyArray<Provider.Target>;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(value: {
+            readonly _tag: "Connected";
+            readonly connection: Storage.Connection;
+            readonly attachment: Storage.Attachment | null;
+        } | {
+            readonly _tag: "Redirect";
+            readonly authorizationUrl: string;
+            readonly continuationId: string;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly connection: Storage.Connection;
+            readonly candidates: ReadonlyArray<Provider.Target>;
+        }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["Connected" | "Redirect" | "SelectionRequired"]>>;
+    };
+    readonly Connected: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Connected";
+        readonly connection: Storage.Connection;
+        readonly attachment: Storage.Attachment | null;
+    }, "_tag">;
+    readonly Redirect: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Redirect";
+        readonly authorizationUrl: string;
+        readonly continuationId: string;
+    }, "_tag">;
+    readonly SelectionRequired: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "SelectionRequired";
+        readonly connection: Storage.Connection;
+        readonly candidates: ReadonlyArray<Provider.Target>;
+    }, "_tag">;
+};
+/** `attach` either attached the domain or needs the caller to pick a zone. */
+export type Selection = Data.TaggedEnum<{
+    SelectionRequired: {
+        readonly candidates: ReadonlyArray<Provider.Target>;
+    };
+}>;
+export declare const Selection: {
+    readonly $is: <Tag extends "SelectionRequired">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "SelectionRequired";
+        readonly candidates: ReadonlyArray<Provider.Target>;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <Cases extends { readonly [Tag in "SelectionRequired"]: (args: Extract<{
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<Provider.Target>;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(cases: Cases): (value: {
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<Provider.Target>;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["SelectionRequired"]>>;
+        <Cases extends { readonly [Tag in "SelectionRequired"]: (args: Extract<{
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<Provider.Target>;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(value: {
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<Provider.Target>;
+        }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["SelectionRequired"]>>;
+    };
+    readonly SelectionRequired: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "SelectionRequired";
+        readonly candidates: ReadonlyArray<Provider.Target>;
+    }, "_tag">;
+};
+export type Attached = Storage.Attachment | Selection;
+export type Refreshed = "current" | "refreshed" | "reconnect";
+/** Which of the principal's connections serves a domain, from nameserver evidence and zone lists. */
+export type Discovery = Data.TaggedEnum<{
+    Resolved: {
+        readonly connectionId: string;
+        readonly target: Provider.Target;
+    };
+    SelectionRequired: {
+        readonly candidates: ReadonlyArray<{
+            readonly connectionId: string;
+            readonly target: Provider.Target;
+        }>;
+    };
+    NotFound: {
+        readonly nameservers: ReadonlyArray<string>;
+    };
+}>;
+export declare const Discovery: {
+    readonly $is: <Tag extends "NotFound" | "Resolved" | "SelectionRequired">(tag: Tag) => (u: unknown) => u is Extract<{
+        readonly _tag: "NotFound";
+        readonly nameservers: ReadonlyArray<string>;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "Resolved";
+        readonly connectionId: string;
+        readonly target: Provider.Target;
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
+        readonly _tag: "SelectionRequired";
+        readonly candidates: ReadonlyArray<{
+            readonly connectionId: string;
+            readonly target: Provider.Target;
+        }>;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <Cases extends { readonly [Tag in "NotFound" | "Resolved" | "SelectionRequired"]: (args: Extract<{
+            readonly _tag: "NotFound";
+            readonly nameservers: ReadonlyArray<string>;
+        } | {
+            readonly _tag: "Resolved";
+            readonly connectionId: string;
+            readonly target: Provider.Target;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<{
+                readonly connectionId: string;
+                readonly target: Provider.Target;
+            }>;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(cases: Cases): (value: {
+            readonly _tag: "NotFound";
+            readonly nameservers: ReadonlyArray<string>;
+        } | {
+            readonly _tag: "Resolved";
+            readonly connectionId: string;
+            readonly target: Provider.Target;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<{
+                readonly connectionId: string;
+                readonly target: Provider.Target;
+            }>;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["NotFound" | "Resolved" | "SelectionRequired"]>>;
+        <Cases extends { readonly [Tag in "NotFound" | "Resolved" | "SelectionRequired"]: (args: Extract<{
+            readonly _tag: "NotFound";
+            readonly nameservers: ReadonlyArray<string>;
+        } | {
+            readonly _tag: "Resolved";
+            readonly connectionId: string;
+            readonly target: Provider.Target;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<{
+                readonly connectionId: string;
+                readonly target: Provider.Target;
+            }>;
+        }, {
+            readonly _tag: Tag;
+        }>) => any; }>(value: {
+            readonly _tag: "NotFound";
+            readonly nameservers: ReadonlyArray<string>;
+        } | {
+            readonly _tag: "Resolved";
+            readonly connectionId: string;
+            readonly target: Provider.Target;
+        } | {
+            readonly _tag: "SelectionRequired";
+            readonly candidates: ReadonlyArray<{
+                readonly connectionId: string;
+                readonly target: Provider.Target;
+            }>;
+        }, cases: Cases): import("effect/Unify").Unify<ReturnType<Cases["NotFound" | "Resolved" | "SelectionRequired"]>>;
+    };
+    readonly NotFound: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "NotFound";
+        readonly nameservers: ReadonlyArray<string>;
+    }, "_tag">;
+    readonly Resolved: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "Resolved";
+        readonly connectionId: string;
+        readonly target: Provider.Target;
+    }, "_tag">;
+    readonly SelectionRequired: Data.TaggedEnum.ConstructorFrom<{
+        readonly _tag: "SelectionRequired";
+        readonly candidates: ReadonlyArray<{
+            readonly connectionId: string;
+            readonly target: Provider.Target;
+        }>;
+    }, "_tag">;
+};
+export interface Interface {
+    readonly inspect: (domain: string) => Fx<Snapshot>;
+    /**
+     * Resolve the domain's authoritative nameservers, then match them against the zones each of
+     * the principal's connections can reach: the closest zone wins, a decisive nameserver match
+     * breaks ties, and anything else needs a selection.
+     */
+    readonly discover: (domain: string) => Fx<Discovery>;
+    /** Connect a provider and, when `domain` is given, attach it. Token methods finish here. */
+    readonly start: (input: {
+        readonly provider: string;
+        readonly method: Method;
+        readonly domain?: string;
+        readonly callbackUrl?: string;
+    }) => Fx<Started>;
+    /** Finish an interactive connection from the provider callback (the full callback URL). */
+    readonly complete: (input: {
+        readonly continuationId: string;
+        readonly callbackUrl: string;
+    }) => Fx<Started>;
+    readonly attach: (input: {
+        readonly connectionId: string;
+        readonly domain: string;
+        readonly target?: Provider.Target;
+    }) => Fx<Attached>;
+    /** Records stay in DNS; DomainKit forgets the domain. Use `Cleanup` first to remove records. */
+    readonly detach: (attachmentId: string) => Fx<void>;
+    /** Detach every domain and revoke the credential at the provider when the method supports it. */
+    readonly disconnect: (connectionId: string) => Fx<void>;
+    /** Refresh a near-expiry credential, single-flighted. Called automatically before provider use. */
+    readonly refresh: (connectionId: string) => Fx<Refreshed>;
+    /** Live provider session for an attachment; used by Provision, Cleanup, Verify. */
+    readonly session: (attachmentId: string) => Fx<{
+        readonly session: Provider.Session;
+        readonly target: Provider.Target;
+    }>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@domainkit/Connect", Interface>;
+export declare class Service extends Service_base {
+}
+/** Which owner-scoped reuse is allowed. Default: any connection of the same owner may serve any of its domains. */
+export interface PolicyShape {
+    readonly allowReuse: (input: {
+        readonly connection: Storage.Connection;
+        readonly domain: string;
+    }) => Effect.Effect<boolean, never, Principal.Service>;
+    /** Refresh this long before expiry. Default 10 minutes. */
+    readonly refreshBeforeMs: number;
+    /** Continuation lifetime. Default 15 minutes. */
+    readonly continuationTtlMs: 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 | Custody.Service | Providers.Service | Resolver.Service>;
+export declare const layer: Layer.Layer<Service, never, Storage.Service | Custody.Service | Providers.Service | Resolver.Service>;
+export declare const inspect: (domain: string) => Effect.Effect<Snapshot, Errors.DomainKitError, Principal.Service | Service>;
+export declare const discover: (domain: string) => Effect.Effect<{
+    readonly _tag: "NotFound";
+    readonly nameservers: ReadonlyArray<string>;
+} | {
+    readonly _tag: "Resolved";
+    readonly connectionId: string;
+    readonly target: Provider.Target;
+} | {
+    readonly _tag: "SelectionRequired";
+    readonly candidates: ReadonlyArray<{
+        readonly connectionId: string;
+        readonly target: Provider.Target;
+    }>;
+}, Errors.DomainKitError, Principal.Service | Service>;
+export declare const start: (input: {
+    readonly provider: string;
+    readonly method: Method;
+    readonly domain?: string;
+    readonly callbackUrl?: string;
+}) => Effect.Effect<{
+    readonly _tag: "Connected";
+    readonly connection: Storage.Connection;
+    readonly attachment: Storage.Attachment | null;
+} | {
+    readonly _tag: "Redirect";
+    readonly authorizationUrl: string;
+    readonly continuationId: string;
+} | {
+    readonly _tag: "SelectionRequired";
+    readonly connection: Storage.Connection;
+    readonly candidates: ReadonlyArray<Provider.Target>;
+}, Errors.DomainKitError, Principal.Service | Service>;
+export declare const complete: (input: {
+    readonly continuationId: string;
+    readonly callbackUrl: string;
+}) => Effect.Effect<{
+    readonly _tag: "Connected";
+    readonly connection: Storage.Connection;
+    readonly attachment: Storage.Attachment | null;
+} | {
+    readonly _tag: "Redirect";
+    readonly authorizationUrl: string;
+    readonly continuationId: string;
+} | {
+    readonly _tag: "SelectionRequired";
+    readonly connection: Storage.Connection;
+    readonly candidates: ReadonlyArray<Provider.Target>;
+}, Errors.DomainKitError, Principal.Service | Service>;
+export declare const attach: (input: {
+    readonly connectionId: string;
+    readonly domain: string;
+    readonly target?: Provider.Target;
+}) => Effect.Effect<Attached, Errors.DomainKitError, Principal.Service | Service>;
+export declare const detach: (attachmentId: string) => Effect.Effect<void, Errors.DomainKitError, Principal.Service | Service>;
+export declare const disconnect: (connectionId: string) => Effect.Effect<void, Errors.DomainKitError, Principal.Service | Service>;
+export declare const refresh: (connectionId: string) => Effect.Effect<Refreshed, Errors.DomainKitError, Principal.Service | Service>;
+export declare const session: (attachmentId: string) => Effect.Effect<{
+    readonly session: Provider.Session;
+    readonly target: Provider.Target;
+}, Errors.DomainKitError, Principal.Service | Service>;
+export {};

package/dist/types/Custody.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Seals provider credentials before Storage writes them. The default is AES-256-GCM through
+ * WebCrypto from one configured key; hosts with a KMS provide their own. There is no plaintext
+ * mode.
+ *
+ * Envelope format: `v1.<iv>.<ciphertext>` with base64url segments and a 12-byte IV. Rotating
+ * the key requires re-sealing stored credentials; `open` fails with `CryptoFailed` on a mismatch.
+ */
+import { Config, Context, Effect, Layer, Redacted } from "effect";
+import * as Errors from "./internal/error.ts";
+import * as Aes from "./internal/aes.ts";
+export interface Interface {
+    readonly seal: (plaintext: Redacted.Redacted<string>) => Effect.Effect<string, Errors.DomainKitError>;
+    readonly open: (ciphertext: string) => Effect.Effect<Redacted.Redacted<string>, Errors.DomainKitError>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@domainkit/Custody", Interface>;
+export declare class Service extends Service_base {
+}
+export interface Options {
+    /** 32 bytes, base64 or hex. Rotating it requires re-sealing stored credentials. */
+    readonly key: Redacted.Redacted<string>;
+}
+export declare const make: (options: Options) => Effect.Effect<Interface, Errors.DomainKitError>;
+export declare const layer: (options: Options) => Layer.Layer<Service, Errors.DomainKitError>;
+/** Same options, each field a `Config`. Defaults to `DOMAINKIT_CUSTODY_KEY`. */
+export declare const layerConfig: (options?: {
+    readonly key?: Config.Config<Redacted.Redacted<string>>;
+}) => Layer.Layer<Service, Errors.DomainKitError>;
+/** A fresh random key in the accepted encoding; for tests, playgrounds, and first-time setup. */
+export declare const generateKey: typeof Aes.generateKey;
+export interface AsyncInterface {
+    readonly seal: (plaintext: string) => Promise<string>;
+    readonly open: (ciphertext: string) => Promise<string>;
+}
+/** Wrap a Promise-shaped KMS client; rejections become `CryptoFailed`. */
+export declare const fromAsync: (service: AsyncInterface) => Interface;
+export declare const layerFromAsync: (service: AsyncInterface) => Layer.Layer<Service>;
+export {};