@alchemy-unifi/network 0.0.1 → 0.1.0

package/src/FirewallPolicyOrdering.ts

@@ -0,0 +1,286 @@
+import * as Sdk from "@alchemy-unifi/network-sdk";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { UserFacingError } from "alchemy/UserFacingError";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import { withConnection } from "./Connection.ts";
+import { type FirewallPolicyReference, isUserDefined, listFirewallPolicies } from "./FirewallPolicy.ts";
+import { type FirewallZoneReference, resolveFirewallZone } from "./FirewallZone.ts";
+import { captureServices } from "./internal/Services.ts";
+import type { Providers } from "./Providers.ts";
+import { checkSameSite, resolveSite, type Site } from "./Site.ts";
+import { STATE_POLICY_PREFIX } from "./State.ts";
+
+export interface FirewallPolicyOrderingProps {
+	/** Site of the zones. @default the profile's site, else the console's only site */
+	site?: string;
+	source: FirewallZoneReference;
+	destination: FirewallZoneReference;
+	/** Policies evaluated before the system-defined ones, first match wins. */
+	beforeSystemDefined?: ReadonlyArray<FirewallPolicyReference>;
+	/** Policies evaluated after the system-defined ones. */
+	afterSystemDefined?: ReadonlyArray<FirewallPolicyReference>;
+	/**
+	 * Fail instead of keeping policies in the zone pair that aren't listed
+	 * (e.g. made in the UI). @default false
+	 */
+	exclusive?: boolean;
+}
+
+export interface FirewallPolicyOrderingAttributes {
+	siteId: string;
+	sourceFirewallZoneId: string;
+	destinationFirewallZoneId: string;
+	beforeSystemDefined: ReadonlyArray<string>;
+	afterSystemDefined: ReadonlyArray<string>;
+	/** The policies the props list, as opposed to unlisted ones kept in the order. */
+	listedFirewallPolicyIds: ReadonlyArray<string>;
+}
+
+export interface FirewallPolicyOrdering extends Resource<
+	"UnifiNetwork.FirewallPolicyOrdering",
+	FirewallPolicyOrderingProps,
+	FirewallPolicyOrderingAttributes,
+	never,
+	Providers
+> {}
+
+/** An ordering that can't be applied as given. */
+export class InvalidFirewallPolicyOrdering extends Data.TaggedError("InvalidFirewallPolicyOrdering")<{
+	readonly reason: string;
+}> {
+	readonly [UserFacingError]: true = true;
+	override get message() {
+		return `Can't apply the firewall policy ordering: ${this.reason}`;
+	}
+}
+
+type Order = Sdk.OrderedFirewallPolicyIDs;
+
+const sameOrder = (a: Order, b: Order) =>
+	a.beforeSystemDefined.join() === b.beforeSystemDefined.join() &&
+	a.afterSystemDefined.join() === b.afterSystemDefined.join();
+
+const resolvePair = Effect.fn(function* (props: FirewallPolicyOrderingProps) {
+	const site = yield* resolveSite(props.site);
+	return {
+		site,
+		siteId: site.id,
+		sourceFirewallZoneId: yield* resolveFirewallZone(props.source, site),
+		destinationFirewallZoneId: yield* resolveFirewallZone(props.destination, site),
+	};
+});
+
+const getOrder = ({ siteId, sourceFirewallZoneId, destinationFirewallZoneId }: Pair) =>
+	withConnection(Sdk.getFirewallPolicyOrdering({ siteId, sourceFirewallZoneId, destinationFirewallZoneId })).pipe(
+		Effect.map((ordering) => ordering.orderedFirewallPolicyIds),
+	);
+
+interface Pair {
+	readonly siteId: string;
+	readonly sourceFirewallZoneId: string;
+	readonly destinationFirewallZoneId: string;
+}
+
+const toAttributes = (
+	pair: Pair,
+	order: Order,
+	listedFirewallPolicyIds: ReadonlyArray<string>,
+): FirewallPolicyOrderingAttributes => ({
+	siteId: pair.siteId,
+	sourceFirewallZoneId: pair.sourceFirewallZoneId,
+	destinationFirewallZoneId: pair.destinationFirewallZoneId,
+	beforeSystemDefined: order.beforeSystemDefined,
+	afterSystemDefined: order.afterSystemDefined,
+	listedFirewallPolicyIds,
+});
+
+const resolvePolicies = (references: ReadonlyArray<FirewallPolicyReference> | undefined, site: Site) =>
+	Effect.forEach(references ?? [], (reference) =>
+		checkSameSite("firewall policy", reference.siteId, site).pipe(Effect.as(reference.firewallPolicyId)),
+	);
+
+/** Why a listed policy isn't in the zone pair's ordering. */
+const explainMissing = Effect.fn(function* (site: Site, firewallPolicyId: string, pair: Pair) {
+	const policy = (yield* listFirewallPolicies(site.id)).find((p) => p.id === firewallPolicyId);
+	if (policy === undefined) return `policy ${firewallPolicyId} doesn't exist`;
+	if (!isUserDefined(policy)) return `"${policy.name}" isn't user-defined, so it can't be ordered`;
+	if (
+		policy.source.zoneId !== pair.sourceFirewallZoneId ||
+		policy.destination.zoneId !== pair.destinationFirewallZoneId
+	) {
+		return `"${policy.name}" belongs to another zone pair`;
+	}
+	return `"${policy.name}" isn't in the zone pair's ordering`;
+});
+
+/**
+ * The state store's policies (`UnifiNetwork.state()`) among `ids`. The store
+ * may have created one since the run's policy list was read, so policies
+ * missing from it are fetched.
+ */
+const statePolicies = Effect.fn(function* (site: Site, ids: ReadonlyArray<string>) {
+	const policies = yield* listFirewallPolicies(site.id);
+	const names = yield* Effect.forEach(ids, (id) => {
+		const listed = policies.find((p) => p.id === id);
+		return listed !== undefined
+			? Effect.succeed(listed.name)
+			: withConnection(Sdk.getFirewallPolicy({ siteId: site.id, firewallPolicyId: id })).pipe(
+					Effect.map((policy): string | undefined => policy.name),
+					Effect.catchTag("NotFound", () => Effect.undefined),
+				);
+	});
+	return ids.filter((_, i) => names[i]?.startsWith(STATE_POLICY_PREFIX) === true);
+});
+
+const describePolicies = Effect.fn(function* (site: Site, ids: ReadonlyArray<string>) {
+	const policies = yield* listFirewallPolicies(site.id);
+	return ids.map((id) => `"${policies.find((p) => p.id === id)?.name ?? id}"`).join(", ");
+});
+
+/**
+ * The evaluation order of user-defined policies from one zone to another.
+ * Listing policies makes the ordering depend on them, so it's applied after
+ * they're created or moved, and re-applied when the list changes.
+ *
+ * UniFi rejects an ordering that leaves out any of the pair's policies, so
+ * unlisted ones (e.g. made in the UI) are kept after the listed ones in each
+ * bucket, in their current relative order, with a warning; `exclusive: true`
+ * fails instead. A policy the ordering listed before but no longer does is
+ * kept quietly, even when exclusive: it's usually being deleted in the same
+ * deploy, which runs after the ordering is applied. The state store's
+ * policies (`UnifiNetwork.state()`, Gateway → Gateway) are kept quietly too.
+ * System-defined policies sit between the two buckets and
+ * can't be reordered; policies UniFi derives from UI Objects aren't ordered
+ * at all.
+ *
+ * The zone pair is the identity: an existing ordering is adopted without
+ * `--adopt`, and deleting the resource leaves the order as it is.
+ *
+ * @example
+ * ```ts
+ * import * as UnifiNetwork from "@alchemy-unifi/network";
+ * import * as Alchemy from "alchemy";
+ * import * as Effect from "effect/Effect";
+ *
+ * export default Alchemy.Stack(
+ * 	"HomeNetwork",
+ * 	{ providers: UnifiNetwork.providers(), state: UnifiNetwork.state() },
+ * 	Effect.gen(function* () {
+ * 		const { INTERNAL } = UnifiNetwork.FirewallZone;
+ * 		const iot = yield* UnifiNetwork.FirewallZone("iot-zone", { name: "IoT" });
+ * 		const policy = { enabled: true, source: { zone: INTERNAL }, destination: { zone: iot }, loggingEnabled: false } as const;
+ * 		const allowHomeAssistant = yield* UnifiNetwork.FirewallPolicy("allow-ha", {
+ * 			...policy,
+ * 			name: "Allow Home Assistant",
+ * 			action: { type: "ALLOW", allowReturnTraffic: true },
+ * 			ipProtocolScope: { ipVersion: "IPV4_AND_IPV6" },
+ * 		});
+ * 		const blockTheRest = yield* UnifiNetwork.FirewallPolicy("block-rest", {
+ * 			...policy,
+ * 			name: "Block the rest",
+ * 			action: { type: "BLOCK" },
+ * 			ipProtocolScope: { ipVersion: "IPV4_AND_IPV6" },
+ * 		});
+ * 		yield* UnifiNetwork.FirewallPolicyOrdering("internal-to-iot", {
+ * 			source: INTERNAL,
+ * 			destination: iot,
+ * 			beforeSystemDefined: [allowHomeAssistant, blockTheRest],
+ * 		});
+ * 	}),
+ * );
+ * ```
+ */
+export const FirewallPolicyOrdering = Resource<FirewallPolicyOrdering>("UnifiNetwork.FirewallPolicyOrdering");
+
+export const FirewallPolicyOrderingProvider = () =>
+	Provider.effect(
+		FirewallPolicyOrdering,
+		Effect.gen(function* () {
+			const run = yield* captureServices;
+
+			return FirewallPolicyOrdering.Provider.of({
+				// Orderings aren't objects of their own: there's nothing to list or nuke.
+				list: () => Effect.succeed([]),
+
+				read: ({ olds, output }) =>
+					run(
+						Effect.gen(function* () {
+							if (output !== undefined) {
+								return toAttributes(output, yield* getOrder(output), output.listedFirewallPolicyIds);
+							}
+							// One ordering per zone pair, so the existing one is this resource's.
+							const pair = yield* resolvePair(olds);
+							return toAttributes(pair, yield* getOrder(pair), []);
+						}),
+					),
+
+				reconcile: ({ news, output }) =>
+					run(
+						Effect.gen(function* () {
+							const pair = yield* resolvePair(news);
+							const { site } = pair;
+							const before = yield* resolvePolicies(news.beforeSystemDefined, site);
+							const after = yield* resolvePolicies(news.afterSystemDefined, site);
+							const listed = [...before, ...after];
+							const duplicate = listed.find((id, i) => listed.indexOf(id) !== i);
+							if (duplicate !== undefined) {
+								const names = yield* describePolicies(site, [duplicate]);
+								return yield* new InvalidFirewallPolicyOrdering({
+									reason: `${names} is listed twice.`,
+								});
+							}
+
+							const current = yield* getOrder(pair);
+							const inPair = new Set([...current.beforeSystemDefined, ...current.afterSystemDefined]);
+							const missing = listed.find((id) => !inPair.has(id));
+							if (missing !== undefined) {
+								return yield* new InvalidFirewallPolicyOrdering({
+									reason: `${yield* explainMissing(site, missing, pair)}.`,
+								});
+							}
+
+							const unlisted = (ids: ReadonlyArray<string>) => ids.filter((id) => !listed.includes(id));
+							const formerlyListed = output?.listedFirewallPolicyIds ?? [];
+							const unlistedNow = [
+								...unlisted(current.beforeSystemDefined),
+								...unlisted(current.afterSystemDefined),
+							].filter((id) => !formerlyListed.includes(id));
+							// The state store's policies are disabled and kept where they are, without a word.
+							const stateIds = yield* statePolicies(site, unlistedNow);
+							const unmanaged = unlistedNow.filter((id) => !stateIds.includes(id));
+							if (unmanaged.length > 0) {
+								const names = yield* describePolicies(site, unmanaged);
+								if (news.exclusive === true) {
+									return yield* new InvalidFirewallPolicyOrdering({
+										reason: `the zone pair has policies the ordering doesn't list: ${names}. List them, delete them, or drop \`exclusive\`.`,
+									});
+								}
+								yield* Effect.logWarning(
+									`Firewall policy ordering: keeping unlisted policies after the listed ones: ${names}.`,
+								);
+							}
+
+							const desired: Order = {
+								beforeSystemDefined: [...before, ...unlisted(current.beforeSystemDefined)],
+								afterSystemDefined: [...after, ...unlisted(current.afterSystemDefined)],
+							};
+							if (sameOrder(desired, current)) return toAttributes(pair, current, listed);
+							const updated = yield* withConnection(
+								Sdk.updateFirewallPolicyOrdering({
+									siteId: pair.siteId,
+									sourceFirewallZoneId: pair.sourceFirewallZoneId,
+									destinationFirewallZoneId: pair.destinationFirewallZoneId,
+									orderedFirewallPolicyIds: desired,
+								}),
+							);
+							return toAttributes(pair, updated.orderedFirewallPolicyIds, listed);
+						}),
+					),
+
+				// The order stays as it is; the policies themselves are deleted by their own resources.
+				delete: () => Effect.void,
+			});
+		}),
+	);

package/src/FirewallZone.ts

@@ -0,0 +1,247 @@
+import * as Sdk from "@alchemy-unifi/network-sdk";
+import { Unowned } from "alchemy/AdoptPolicy";
+import type { Diff } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { withConnection } from "./Connection.ts";
+import { loadNetworks } from "./internal/Networks.ts";
+import { plannedString, UNKNOWN } from "./internal/Plan.ts";
+import { captureServices } from "./internal/Services.ts";
+import { describeQuery, LookupNotFound } from "./Lookup.ts";
+import type { Providers } from "./Providers.ts";
+import * as ReadCache from "./ReadCache.ts";
+import { checkSameSite, resolveSite, type Site } from "./Site.ts";
+
+/** The zones every zone-based firewall has, by their API names. */
+export type BuiltinFirewallZoneName = "Internal" | "External" | "Gateway" | "Vpn" | "Hotspot" | "Dmz";
+
+/** A built-in zone, resolved by name in whichever site the referencing resource is in. */
+export interface BuiltinFirewallZone {
+	readonly builtinFirewallZone: BuiltinFirewallZoneName;
+}
+
+/**
+ * A zone: a `FirewallZone` resource, a {@link FirewallZone.lookup} result,
+ * `{ firewallZoneId }`, or a built-in constant such as `FirewallZone.INTERNAL`.
+ */
+export type FirewallZoneReference =
+	| { readonly firewallZoneId: string; readonly siteId?: string | undefined }
+	| BuiltinFirewallZone;
+
+export interface FirewallZoneProps {
+	/** Site to create the zone in. @default the profile's site, else the console's only site */
+	site?: string;
+	name: string;
+}
+
+export interface FirewallZoneAttributes {
+	siteId: string;
+	firewallZoneId: string;
+	name: string;
+}
+
+export interface FirewallZone extends Resource<
+	"UnifiNetwork.FirewallZone",
+	FirewallZoneProps,
+	FirewallZoneAttributes,
+	never,
+	Providers
+> {}
+
+const loadZones = (siteId: string) => withConnection(Stream.runCollect(Sdk.getFirewallZones.items({ siteId })));
+const zonesKey = ReadCache.key<ReadonlyArray<Sdk.FirewallZone>, Effect.Error<ReturnType<typeof loadZones>>>(
+	"firewallZones",
+);
+
+/** A site's zones, built-in ones included, listed once per run. */
+export const listFirewallZones = (siteId: string) => ReadCache.cached(zonesKey, siteId, loadZones(siteId));
+
+const toAttributes = (siteId: string, zone: Sdk.FirewallZone): FirewallZoneAttributes => ({
+	siteId,
+	firewallZoneId: zone.id,
+	name: zone.name,
+});
+
+const isBuiltin = (zone: Sdk.FirewallZone) => zone.metadata.origin === "SYSTEM_DEFINED";
+
+/** The zone ID a reference means in `site`. */
+export const resolveFirewallZone = Effect.fn("UnifiNetwork.resolveFirewallZone")(function* (
+	reference: FirewallZoneReference,
+	site: Site,
+) {
+	if ("firewallZoneId" in reference) {
+		yield* checkSameSite("firewall zone", reference.siteId, site);
+		return reference.firewallZoneId;
+	}
+	const zones = yield* listFirewallZones(site.id);
+	const zone = zones.find((z) => isBuiltin(z) && z.name === reference.builtinFirewallZone);
+	if (zone === undefined) {
+		return yield* new LookupNotFound({
+			resource: "built-in firewall zone",
+			query: `name "${reference.builtinFirewallZone}" (has the site been migrated to zone-based firewall?)`,
+			site,
+		});
+	}
+	return zone.id;
+});
+
+const builtin = (name: BuiltinFirewallZoneName): BuiltinFirewallZone => ({ builtinFirewallZone: name });
+
+/**
+ * A custom zone in the zone-based firewall. Networks join zones through
+ * `Network`'s `zone` prop; the zone doesn't list its networks, so the two
+ * resources never fight over membership.
+ *
+ * @example
+ * ```ts
+ * import * as UnifiNetwork from "@alchemy-unifi/network";
+ * import * as Alchemy from "alchemy";
+ * import * as Effect from "effect/Effect";
+ *
+ * export default Alchemy.Stack(
+ * 	"HomeNetwork",
+ * 	{ providers: UnifiNetwork.providers(), state: UnifiNetwork.state() },
+ * 	Effect.gen(function* () {
+ * 		const cameras = yield* UnifiNetwork.FirewallZone("cameras", { name: "Cameras" });
+ * 		// Networks join zones from the network's side.
+ * 		yield* UnifiNetwork.Network("cctv", {
+ * 			management: "GATEWAY",
+ * 			name: "CCTV",
+ * 			vlanId: 30,
+ * 			enabled: true,
+ * 			cellularBackupEnabled: false,
+ * 			internetAccessEnabled: false,
+ * 			isolationEnabled: true,
+ * 			zone: cameras, // or a built-in zone, e.g. UnifiNetwork.FirewallZone.INTERNAL
+ * 			ipv4Configuration: { autoScaleEnabled: false, hostIpAddress: "192.168.30.1", prefixLength: 24 },
+ * 		});
+ * 	}),
+ * );
+ * ```
+ */
+export const FirewallZone = Resource<FirewallZone>("UnifiNetwork.FirewallZone")({
+	INTERNAL: builtin("Internal"),
+	EXTERNAL: builtin("External"),
+	GATEWAY: builtin("Gateway"),
+	VPN: builtin("Vpn"),
+	HOTSPOT: builtin("Hotspot"),
+	DMZ: builtin("Dmz"),
+	/**
+	 * Any zone in the site, built-in or custom, by name. Dies with a
+	 * user-facing `LookupNotFound` if there's none: stack bodies can't fail
+	 * with typed errors.
+	 */
+	lookup: Effect.fn("UnifiNetwork.FirewallZone.lookup")(function* (query: {
+		readonly name: string;
+		readonly site?: string;
+	}) {
+		const site = yield* resolveSite(query.site);
+		const zone = (yield* listFirewallZones(site.id)).find((z) => z.name === query.name);
+		if (zone === undefined) {
+			return yield* new LookupNotFound({ resource: "firewall zone", query: describeQuery(query), site });
+		}
+		return toAttributes(site.id, zone);
+	}, Effect.orDie),
+});
+
+const getZone = (siteId: string, firewallZoneId: string) =>
+	withConnection(Sdk.getFirewallZone({ siteId, firewallZoneId })).pipe(
+		Effect.catchTag("NotFound", () => Effect.undefined),
+	);
+
+/**
+ * The networks in a zone, from the networks' own `zoneId`s. Updates replace
+ * a zone's member list, and the zone's `networkIds` lags a network joining
+ * it by a fraction of a second, so sending those back could detach a
+ * network that just joined.
+ */
+const currentMembers = (siteId: string, firewallZoneId: string) =>
+	loadNetworks(siteId).pipe(
+		Effect.map((networks) => networks.filter((n) => "zoneId" in n && n.zoneId === firewallZoneId).map((n) => n.id)),
+	);
+
+export const FirewallZoneProvider = () =>
+	Provider.effect(
+		FirewallZone,
+		Effect.gen(function* () {
+			const run = yield* captureServices;
+
+			return FirewallZone.Provider.of({
+				list: () =>
+					run(
+						Effect.gen(function* () {
+							const site = yield* resolveSite();
+							const zones = yield* listFirewallZones(site.id);
+							return zones.filter((zone) => !isBuiltin(zone)).map((zone) => toAttributes(site.id, zone));
+						}),
+					),
+
+				read: ({ olds, output }) =>
+					run(
+						Effect.gen(function* () {
+							if (output !== undefined) {
+								const zone = yield* getZone(output.siteId, output.firewallZoneId);
+								return zone === undefined ? undefined : toAttributes(output.siteId, zone);
+							}
+							const site = yield* resolveSite(olds.site);
+							const zone = (yield* listFirewallZones(site.id)).find(
+								(z) => !isBuiltin(z) && z.name === olds.name,
+							);
+							return zone === undefined ? undefined : Unowned(toAttributes(site.id, zone));
+						}),
+					),
+
+				diff: ({ news, output }) =>
+					run(
+						Effect.gen(function* () {
+							const siteProp = plannedString(news, "site");
+							if (output === undefined || siteProp === UNKNOWN) return undefined;
+							const site = yield* resolveSite(siteProp);
+							if (site.id !== output.siteId) return { action: "replace" } satisfies Diff;
+							return undefined;
+						}),
+					),
+
+				reconcile: ({ news, output }) =>
+					run(
+						Effect.gen(function* () {
+							const site = yield* resolveSite(news.site);
+							const observed =
+								output !== undefined && output.siteId === site.id
+									? yield* getZone(site.id, output.firewallZoneId)
+									: undefined;
+							const write = ReadCache.invalidating(zonesKey, site.id);
+							if (observed === undefined) {
+								const created = yield* withConnection(
+									Sdk.createFirewallZone({ siteId: site.id, name: news.name, networkIds: [] }),
+								).pipe(write);
+								return toAttributes(site.id, created);
+							}
+							if (observed.name === news.name) return toAttributes(site.id, observed);
+							const updated = yield* withConnection(
+								Sdk.updateFirewallZone({
+									siteId: site.id,
+									firewallZoneId: observed.id,
+									name: news.name,
+									networkIds: yield* currentMembers(site.id, observed.id),
+								}),
+							).pipe(write);
+							return toAttributes(site.id, updated);
+						}),
+					),
+
+				delete: ({ output }) =>
+					run(
+						withConnection(
+							Sdk.deleteFirewallZone({ siteId: output.siteId, firewallZoneId: output.firewallZoneId }),
+						).pipe(
+							Effect.asVoid,
+							Effect.catchTag("NotFound", () => Effect.void),
+							ReadCache.invalidating(zonesKey, output.siteId),
+						),
+					),
+			});
+		}),
+	);

package/src/HttpClient.ts

@@ -0,0 +1,138 @@
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import { buildConnector } from "@effect/platform-node/Undici";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import type * as HttpClient from "effect/http/HttpClient";
+import type * as Scope from "effect/Scope";
+import * as net from "node:net";
+import * as tls from "node:tls";
+
+/** How the client verifies a console's TLS certificate. */
+export interface TlsOptions {
+	/** Accept the server only if a certificate in its chain has this SHA-256 fingerprint. */
+	readonly certFingerprint?: string | undefined;
+	/** Skip verification entirely. */
+	readonly insecure?: boolean | undefined;
+}
+
+/** Normalises a SHA-256 fingerprint to Node's `AB:CD:…` form, or returns `undefined` if it isn't one. */
+export const normaliseFingerprint = (value: string): string | undefined => {
+	const hex = value.replace(/[\s:]/g, "").toUpperCase();
+	return /^[0-9A-F]{64}$/.test(hex) ? (hex.match(/../g) ?? []).join(":") : undefined;
+};
+
+/** SHA-256 fingerprints of a peer's certificate chain, leaf first. */
+const chainFingerprints = (socket: tls.TLSSocket): ReadonlyArray<string> => {
+	const fingerprints: string[] = [];
+	let cert: tls.DetailedPeerCertificate | undefined = socket.getPeerCertificate(true);
+	while (cert?.fingerprint256 !== undefined && !fingerprints.includes(cert.fingerprint256)) {
+		fingerprints.push(cert.fingerprint256);
+		cert = cert.issuerCertificate;
+	}
+	return fingerprints;
+};
+
+const PINNING_ERROR_CODE = "ERR_UNIFI_CERT_PINNING";
+
+/**
+ * Whether an error (or one of its causes) is a certificate verification or
+ * pinning failure. These are deterministic, so they aren't worth retrying.
+ */
+export const isCertificateError = (error: unknown): boolean => {
+	for (let e: unknown = error, depth = 0; typeof e === "object" && e !== null && depth < 5; depth++) {
+		const code = "code" in e ? String(e.code) : "";
+		if (code === PINNING_ERROR_CODE || /CERT|SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER/.test(code))
+			return true;
+		e = "cause" in e ? e.cause : "reason" in e ? e.reason : undefined;
+	}
+	return false;
+};
+
+/**
+ * Pinning can't use `checkServerIdentity`: Node skips it when the chain
+ * doesn't verify, which is always the case for a console's self-signed
+ * certificate. So verification is off, and the connector checks the
+ * presented chain itself once the handshake completes. Session resumption
+ * is off too, because a resumed session presents no certificate to check.
+ */
+const pinnedConnector = (fingerprint: string): buildConnector.connector => {
+	const connect = buildConnector({ rejectUnauthorized: false, maxCachedSessions: 0 });
+	return (options, callback) =>
+		connect(options, (error, socket) => {
+			if (error !== null) return callback(error, null);
+			if (socket instanceof tls.TLSSocket && !chainFingerprints(socket).includes(fingerprint)) {
+				socket.destroy();
+				return callback(
+					Object.assign(
+						new Error(
+							`The certificate presented by ${options.hostname} doesn't match the pinned fingerprint ${fingerprint}.`,
+						),
+						{ code: PINNING_ERROR_CODE },
+					),
+					null,
+				);
+			}
+			callback(null, socket);
+		});
+};
+
+/** An undici-backed `HttpClient` applying {@link TlsOptions}. The dispatcher closes with the scope. */
+export const make = (options: TlsOptions = {}): Effect.Effect<HttpClient.HttpClient, never, Scope.Scope> =>
+	NodeHttpClient.makeDispatcherOptions(
+		options.certFingerprint !== undefined
+			? { connect: pinnedConnector(options.certFingerprint) }
+			: options.insecure
+				? { connect: { rejectUnauthorized: false } }
+				: undefined,
+	).pipe(
+		Effect.flatMap((dispatcher) =>
+			NodeHttpClient.makeUndici.pipe(Effect.provideService(NodeHttpClient.Dispatcher, dispatcher)),
+		),
+	);
+
+export class CertificateInspectionError extends Data.TaggedError("CertificateInspectionError")<{
+	readonly message: string;
+	readonly cause?: unknown;
+}> {}
+
+export interface PeerCertificate {
+	/** Whether Node's default CAs trust the chain for this host. */
+	readonly trusted: boolean;
+	/** SHA-256 fingerprint of the leaf certificate (`AB:CD:…`). */
+	readonly fingerprint: string;
+	readonly subject: string;
+	readonly validTo: string;
+}
+
+/**
+ * Connects to an `https:` URL without verifying it and reports the
+ * certificate it presents, so `configure` can offer to pin it.
+ */
+export const inspectCertificate = (url: string): Effect.Effect<PeerCertificate, CertificateInspectionError> =>
+	Effect.callback<PeerCertificate, CertificateInspectionError>((resume) => {
+		const { hostname, port } = new URL(url);
+		const host = hostname.replace(/^\[|\]$/g, "");
+		const socket = tls.connect({
+			host,
+			port: Number(port || 443),
+			rejectUnauthorized: false,
+			...(net.isIP(host) === 0 ? { servername: host } : {}),
+		});
+		socket.setTimeout(10_000, () => socket.destroy(new Error(`Timed out connecting to ${url}.`)));
+		socket.once("secureConnect", () => {
+			const cert = socket.getPeerCertificate();
+			resume(
+				Effect.succeed({
+					trusted: socket.authorized,
+					fingerprint: cert.fingerprint256,
+					subject: String(cert.subject?.CN ?? cert.subjectaltname ?? "unknown"),
+					validTo: cert.valid_to,
+				}),
+			);
+			socket.end();
+		});
+		socket.once("error", (cause) =>
+			resume(Effect.fail(new CertificateInspectionError({ message: cause.message, cause }))),
+		);
+		return Effect.sync(() => socket.destroy());
+	});