@lovrozagar/honey 0.6.8 → 0.7.0

package/src/init.ts

@@ -1,11 +1,10 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { basename, dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
+import type { InitFlags } from "./cli-args.ts"
 
-export type InitFlags = {
-	cf: boolean
-	force: boolean
-}
+export type { InitFlags } from "./cli-args.ts"
+export { parseInitFlags } from "./cli-args.ts"
 
 type PackageJson = {
 	dependencies?: Record<string, string>
@@ -50,13 +49,6 @@ export default {
 }
 `
 
-export function parseInitFlags(args: string[]): InitFlags {
-	return {
-		cf: args.includes("--cf"),
-		force: args.includes("--force"),
-	}
-}
-
 export function runInit(cwd: string, flags: InitFlags): void {
 	const files: Record<string, string> = {
 		"src/app.ts": APP_TS,
@@ -76,7 +68,7 @@ export function runInit(cwd: string, flags: InitFlags): void {
 	for (const [rel, contents] of Object.entries(files)) {
 		writeText(join(cwd, rel), contents)
 	}
-	writePackageJson(cwd)
+	writePackageJson(cwd, flags.force)
 	console.log("honey: initialized")
 }
 
@@ -91,25 +83,45 @@ function wranglerJsonc(name: string): string {
 `
 }
 
-function writePackageJson(cwd: string): void {
+const PACKAGE_NAME = "@lovrozagar/honey"
+
+const SCRIPTS: Record<string, string> = {
+	dev: "bun --watch src/server.ts",
+	generate: "honey generate",
+}
+
+/**
+ * Creates package.json, or adds what is missing to an existing one. Existing scripts, `type` and
+ * dependency ranges are kept unless `force` is set; each kept value is reported.
+ */
+function writePackageJson(cwd: string, force: boolean): void {
 	const path = join(cwd, "package.json")
-	const existing = existsSync(path) ? readPackageJson(path) : {}
-	const next: PackageJson = {
-		...existing,
-		name: existing.name ?? packageNameFromDir(cwd),
-		private: existing.private ?? true,
-		type: existing.type ?? "module",
-		scripts: {
-			...existing.scripts,
-			dev: "bun --watch src/server.ts",
-			generate: "honey generate",
-		},
-		dependencies: {
-			...existing.dependencies,
-			honey: existing.dependencies?.honey ?? `^${honeyVersion()}`,
-		},
+	const exists = existsSync(path)
+	const existing = exists ? readPackageJson(path) : {}
+	const notes: string[] = []
+
+	const scripts = { ...existing.scripts }
+	for (const [name, command] of Object.entries(SCRIPTS)) {
+		const current = scripts[name]
+		if (current === undefined || current === command || force) scripts[name] = command
+		else notes.push(`kept scripts.${name} ("${current}"); honey expects "${command}"`)
+	}
+
+	const dependencies = { ...existing.dependencies }
+	if (dependencies[PACKAGE_NAME] === undefined || force) dependencies[PACKAGE_NAME] = `^${honeyVersion()}`
+
+	const next: PackageJson = { ...existing, dependencies, scripts }
+	if (!exists) {
+		next.name = packageNameFromDir(cwd)
+		next.private = true
+	}
+	if (existing.type === undefined) {
+		if (!exists || force) next.type = "module"
+		else notes.push('package.json has no "type"; the scaffold is ESM, so set "type": "module" or rerun with --force')
 	}
+
 	writeText(path, `${JSON.stringify(next, null, "\t")}\n`)
+	for (const note of notes) console.log(`honey: ${note}`)
 }
 
 function readPackageJson(path: string): PackageJson {

package/src/invalidate-check.ts

@@ -62,8 +62,15 @@ function declaredNothing(meta: Record<string, unknown> | null): boolean {
 	return value === null || (Array.isArray(value) && value.length === 0)
 }
 
-function alreadyInvalidates(operation: Record<string, unknown>): boolean {
-	const emitted = operation["x-invalidate"]
+/**
+ * Did the author declare targets? Read from the meta, not the emitted operation: a profile
+ * that leaves `x-invalidate` out of its document must not make every declared mutation look
+ * undeclared.
+ */
+function alreadyInvalidates(entry: InvalidateCheckOperation): boolean {
+	const declared = entry.meta?.invalidate
+	if (Array.isArray(declared) && declared.length > 0) return true
+	const emitted = entry.operation["x-invalidate"]
 	return Array.isArray(emitted) && emitted.length > 0
 }
 
@@ -112,7 +119,7 @@ export function findMissingInvalidate(
 	const findings: InvalidateFinding[] = []
 	for (const entry of operations) {
 		if (!MUTATION_METHODS.has(entry.method)) continue
-		if (alreadyInvalidates(entry.operation)) continue
+		if (alreadyInvalidates(entry)) continue
 		if (declaredNothing(entry.meta)) continue
 
 		let affects: string[] = []
@@ -120,7 +127,9 @@ export function findMissingInvalidate(
 		if (entity !== undefined && entity !== null) {
 			/* sharper than path shape: the same entity is read somewhere else in the document */
 			affects = readsByEntity.get(JSON.stringify(entity)) ?? []
-		} else {
+		}
+		if (affects.length === 0) {
+			/* no reader is tagged with the entity — path shape is still a signal, not silence */
 			affects = pathFamily(entry.path)
 				.filter((candidate) => readPaths.has(candidate))
 				.map((candidate) => `GET ${candidate}`)
@@ -165,3 +174,32 @@ export function reportMissingInvalidate(
 	if (level === "error") throw new Error(report)
 	console.warn(report)
 }
+
+/**
+ * `invalidate` selectors that name no route. A selector is `"<METHOD> <pattern>"`, exactly as
+ * the generated `RouteSelector` union spells it; anything else invalidates nothing at runtime.
+ */
+export function findInvalidSelectors(
+	operations: readonly InvalidateCheckOperation[],
+	inventory: ReadonlySet<string>,
+): Array<{ method: string; path: string; selector: unknown }> {
+	const out: Array<{ method: string; path: string; selector: unknown }> = []
+	const seen = new Set<string>()
+	for (const entry of operations) {
+		const declared = entry.meta?.invalidate
+		if (!Array.isArray(declared)) continue
+		for (const selector of declared) {
+			if (typeof selector === "string" && inventory.has(selector)) continue
+			const key = `${entry.method} ${entry.path} ${String(selector)}`
+			if (seen.has(key)) continue
+			seen.add(key)
+			out.push({ method: entry.method.toUpperCase(), path: entry.path, selector })
+		}
+	}
+	return out
+}
+
+/** The level an `invalidate` config reports at. */
+export function invalidateLevel(config: InvalidateCheckConfig | undefined): InvalidateCheckLevel {
+	return resolveConfig(config).level
+}

package/src/invoke-user.ts

@@ -0,0 +1,95 @@
+/**
+ * Containment for user callbacks the framework calls outside a request's middleware chain
+ * (WebSocket and realtime events, adapter hooks). A sync throw or a rejection never escapes
+ * into the runtime, where it would be an uncaught exception or an unhandled rejection and,
+ * on Node, end the process.
+ */
+
+/** The error side of a structured logger (`error(obj, msg)`), e.g. honey/logger. */
+export type InvokeLogger = {
+	error?: (obj: Record<string, unknown>, msg?: string) => void
+}
+
+export type InvokeOptions = {
+	/** Where the callback's error goes. When it throws or rejects itself, that is logged and it is not called again for its own error. */
+	onError?: ((err: unknown) => unknown) | null
+	/** The app logger; `console.error` when absent. */
+	log?: InvokeLogger | null
+	/** A label for the log line (`"open"`, `"message"`, …). */
+	phase: string
+	/** Extra fields for the log line. */
+	fields?: Record<string, unknown>
+}
+
+function logFailure(err: unknown, opts: InvokeOptions, phase: string): void {
+	const fields = { ...opts.fields, err, phase }
+	try {
+		if (opts.log?.error) {
+			opts.log.error(fields, "callback failed")
+			return
+		}
+	} catch {
+		/* a broken logger must not take the callback's place as the thing that escapes */
+	}
+	console.error("honey: callback failed", fields)
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+	return value !== null && typeof value === "object" && typeof (value as { then?: unknown }).then === "function"
+}
+
+/** Report `err` through `onError`, or log it. Never throws, never rejects. */
+export function reportUserError(err: unknown, opts: InvokeOptions): void {
+	const onError = opts.onError
+	if (!onError) {
+		logFailure(err, opts, opts.phase)
+		return
+	}
+	try {
+		const r = onError(err)
+		if (isThenable(r)) r.then(undefined, (e: unknown) => logFailure(e, opts, "onError"))
+	} catch (e) {
+		logFailure(e, opts, "onError")
+	}
+}
+
+/**
+ * Call `fn` and resolve once it settles. Resolves `true` when it succeeded and `false` when it
+ * threw or rejected (the error went to `onError` or the logger). Never rejects.
+ */
+export function invokeUser(fn: () => unknown, opts: InvokeOptions): Promise<boolean> {
+	try {
+		const r = fn()
+		if (isThenable(r)) {
+			return Promise.resolve(r).then(
+				() => true,
+				(e: unknown) => {
+					reportUserError(e, opts)
+					return false
+				},
+			)
+		}
+		return Promise.resolve(true)
+	} catch (e) {
+		reportUserError(e, opts)
+		return Promise.resolve(false)
+	}
+}
+
+/**
+ * One ordered event queue: each task starts after the previous one settled, and a failing task
+ * never stops the ones after it.
+ */
+export function createEventQueue(): { push(task: () => Promise<unknown>): Promise<void> } {
+	let tail: Promise<void> = Promise.resolve()
+	return {
+		push(task) {
+			const next = tail.then(task).then(
+				() => undefined,
+				() => undefined,
+			)
+			tail = next
+			return next
+		},
+	}
+}

package/src/ip-restrict.ts

@@ -1,153 +1,29 @@
 import { namedMiddleware } from "./middleware.ts"
 import { HoneyError } from "./error.ts"
+import { ipInRange, parseIp, parseIpRange, type IpRange } from "./ip.ts"
 import type { MiddlewareFn } from "./middleware.ts"
 import { EK, SK } from "./types.ts"
 
 type IpRestrictOptions = {
+	/** Addresses and CIDR ranges allowed through. When set, everything else is rejected. */
 	allowList?: string[]
+	/** Addresses and CIDR ranges rejected. Checked before `allowList`. */
 	denyList?: string[]
+	/**
+	 * Returns the client address, replacing `ctx.ip`. Leave it out to use `ctx.ip`, which the
+	 * app's `trustProxy()` setting decides — the same address every other feature sees.
+	 */
 	getIp?: (req: Request) => string | null
-	trustProxy?: boolean
 }
 
-function stripBrackets(ip: string): string {
-	if (ip.startsWith("[") && ip.endsWith("]")) {
-		return ip.slice(1, -1)
-	}
-	return ip
-}
-
-function defaultGetIp(req: Request): string | null {
-	const cfIp = req.headers.get("cf-connecting-ip")
-	if (cfIp) return stripBrackets(cfIp.trim())
-
-	return null
-}
-
-function proxyAwareGetIp(req: Request): string | null {
-	const cfIp = req.headers.get("cf-connecting-ip")
-	if (cfIp) return stripBrackets(cfIp.trim())
-
-	const xff = req.headers.get("x-forwarded-for")
-	if (xff) return stripBrackets(xff.split(",")[0].trim())
-
-	const realIp = req.headers.get("x-real-ip")
-	if (realIp) return stripBrackets(realIp.trim())
-
-	return null
-}
-
-function parseIpv4(ip: string): number | null {
-	const parts = ip.split(".")
-	if (parts.length !== 4) return null
-	let result = 0
-	for (const part of parts) {
-		const n = Number.parseInt(part, 10)
-		if (Number.isNaN(n) || n < 0 || n > 255) return null
-		result = (result << 8) | n
-	}
-	return result >>> 0
-}
-
-type Ipv4CidrRule = {
-	base: number
-	mask: number
-	v6: false
-}
-
-type Ipv6CidrRule = {
-	base: bigint
-	mask: bigint
-	v6: true
-}
-
-type CidrRule = Ipv4CidrRule | Ipv6CidrRule
-
-type ParsedRule = {
-	cidr?: CidrRule
-	exact: string
-}
-
-function expandIpv6(ip: string): bigint | null {
-	let addr = ip
-
-	/* handle ::ffff:1.2.3.4 mapped IPv4 */
-	const v4Suffix = addr.match(/:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/)
-	if (v4Suffix) {
-		const v4 = parseIpv4(v4Suffix[1])
-		if (v4 === null) return null
-		addr = `${addr.slice(0, addr.lastIndexOf(":"))}:${((v4 >>> 16) & 0xffff).toString(16)}:${(v4 & 0xffff).toString(16)}`
-	}
-
-	/* expand :: */
-	const halves = addr.split("::")
-	if (halves.length > 2) return null
-
-	let groups: string[]
-	if (halves.length === 2) {
-		const left = halves[0] === "" ? [] : halves[0].split(":")
-		const right = halves[1] === "" ? [] : halves[1].split(":")
-		const fill = 8 - left.length - right.length
-		if (fill < 0) return null
-		groups = [...left, ...Array.from<string>({ length: fill }).fill("0"), ...right]
-	} else {
-		groups = addr.split(":")
-	}
-
-	if (groups.length !== 8) return null
-
-	let result = 0n
-	for (const g of groups) {
-		const n = Number.parseInt(g, 16)
-		if (Number.isNaN(n) || n < 0 || n > 0xffff) return null
-		result = (result << 16n) | BigInt(n)
-	}
-	return result
-}
-
-function isIpv6(ip: string): boolean {
-	return ip.includes(":")
-}
-
-function parseRule(rule: string): ParsedRule {
-	const slashIdx = rule.indexOf("/")
-	if (slashIdx === -1) {
-		return { exact: rule }
-	}
-
-	const ip = rule.slice(0, slashIdx)
-	const bits = Number.parseInt(rule.slice(slashIdx + 1), 10)
-
-	if (isIpv6(ip)) {
-		const base = expandIpv6(ip)
-		if (base === null || Number.isNaN(bits) || bits < 0 || bits > 128) {
-			return { exact: rule }
-		}
-		const mask = bits === 0 ? 0n : ((1n << BigInt(bits)) - 1n) << BigInt(128 - bits)
-		return { cidr: { base: base & mask, mask, v6: true }, exact: rule }
-	}
-
-	const base = parseIpv4(ip)
-	if (base === null || Number.isNaN(bits) || bits < 0 || bits > 32) {
-		return { exact: rule }
-	}
-
-	const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0
-	return { cidr: { base: (base & mask) >>> 0, mask, v6: false }, exact: rule }
-}
-
-function matchesRule(ip: string, rule: ParsedRule): boolean {
-	if (rule.cidr) {
-		if (rule.cidr.v6) {
-			const parsed = expandIpv6(ip)
-			if (parsed === null) return false
-			return (parsed & rule.cidr.mask) === rule.cidr.base
-		}
-		const parsed = parseIpv4(ip)
-		if (parsed === null) return false
-		return (parsed & rule.cidr.mask) >>> 0 === rule.cidr.base
-	}
-	return ip === rule.exact
+function parseRules(list: readonly string[] | undefined, name: string): IpRange[] {
+	if (list === undefined) return []
+	return list.map((rule) => {
+		const range = typeof rule === "string" ? parseIpRange(rule) : null
+		if (range === null)
+			throw new Error(`ipRestrict: ${name} entry ${JSON.stringify(rule)} is not an IP address or CIDR range`)
+		return range
+	})
 }
 
 function throwForbidden(): never {
@@ -157,35 +33,45 @@ function throwForbidden(): never {
 	})
 }
 
+/**
+ * Allows or rejects requests by client address. Rules and addresses are compared in canonical
+ * numeric form, so `::ffff:203.0.113.7`, `203.0.113.7` and `203.0.113.7:51234` are one address.
+ *
+ * Fails closed: a request whose address is unknown or unparseable is rejected with 403, under
+ * a deny list as much as under an allow list.
+ */
 export function ipRestrict(opts: IpRestrictOptions): MiddlewareFn<{ req: Request }, {}> {
-	const getIp = opts.getIp ?? (opts.trustProxy === true ? proxyAwareGetIp : defaultGetIp)
-	const denyRules = opts.denyList?.map(parseRule) ?? []
-	const allowRules = opts.allowList?.map(parseRule) ?? []
-	const hasAllowList = allowRules.length > 0
+	const legacy = opts as { trustCloudflare?: unknown; trustProxy?: unknown }
+	if (legacy.trustProxy !== undefined || legacy.trustCloudflare !== undefined) {
+		throw new Error(
+			"ipRestrict: `trustProxy` and `trustCloudflare` moved to the app. Call `app.trustProxy(1)` " +
+				"(one reverse proxy) or `app.trustProxy([...proxy ranges])`; on Cloudflare Workers `ctx.ip` " +
+				"already reads CF-Connecting-IP.",
+		)
+	}
+	if (opts.allowList !== undefined && opts.allowList.length === 0) {
+		throw new Error("ipRestrict: `allowList: []` would reject every request. Remove the middleware or list addresses.")
+	}
+	const denyRules = parseRules(opts.denyList, "denyList")
+	const allowRules = parseRules(opts.allowList, "allowList")
+	if (denyRules.length === 0 && allowRules.length === 0) {
+		throw new Error("ipRestrict: pass a non-empty `allowList` or `denyList`")
+	}
+	const getIp = opts.getIp
 
 	const mw: MiddlewareFn<{ req: Request }, {}> = (ctx, next) => {
-		const ip = getIp(ctx.req)
+		const raw = getIp ? getIp(ctx.req) : ((ctx as { ip?: string | null }).ip ?? null)
+		const addr = raw === null || raw === "" ? null : parseIp(raw)
 
-		/* deny list checked first */
-		if (ip !== null) {
-			for (const rule of denyRules) {
-				if (matchesRule(ip, rule)) throwForbidden()
-			}
-		}
+		/* fail closed: an unknown address can match neither list */
+		if (addr === null) throwForbidden()
 
-		/* allow list: if set, IP must match at least one rule */
-		if (hasAllowList) {
-			if (ip === null) throwForbidden()
-			let allowed = false
-			for (const rule of allowRules) {
-				if (matchesRule(ip, rule)) {
-					allowed = true
-					break
-				}
-			}
-			if (!allowed) throwForbidden()
+		for (const rule of denyRules) {
+			if (ipInRange(addr, rule)) throwForbidden()
 		}
 
+		if (allowRules.length > 0 && !allowRules.some((rule) => ipInRange(addr, rule))) throwForbidden()
+
 		return next()
 	}
 

package/src/ip.ts

@@ -0,0 +1,194 @@
+/**
+ * IP addresses in canonical numeric form. Every comparison the framework makes (`ipRestrict`
+ * rules, trusted proxy ranges) parses both sides here first, so `::ffff:203.0.113.7`,
+ * `203.0.113.7` and `203.0.113.7:51234` are one address and `2001:DB8::1` equals `2001:db8::1`.
+ */
+
+export type IpAddress = { readonly v: 4; readonly n: number } | { readonly v: 6; readonly n: bigint }
+
+export type IpRange =
+	| { readonly v: 4; readonly base: number; readonly mask: number }
+	| { readonly v: 6; readonly base: bigint; readonly mask: bigint }
+
+const V4_MAPPED_PREFIX = 0xffffn << 32n
+const V4_MAPPED_MASK = ~0xffffffffn & ((1n << 128n) - 1n)
+
+function parseIpv4(s: string): number | null {
+	const parts = s.split(".")
+	if (parts.length !== 4) return null
+	let n = 0
+	for (const part of parts) {
+		/* digits only, no leading zeros (`010` is octal to some parsers, decimal to others) */
+		if (part.length === 0 || part.length > 3 || !/^\d+$/.test(part)) return null
+		if (part.length > 1 && part.charCodeAt(0) === 48) return null
+		const octet = Number(part)
+		if (octet > 255) return null
+		n = n * 256 + octet
+	}
+	return n
+}
+
+/** The `:`-separated hex groups of one side of `::`; `null` when a group is not 1–4 hex digits. */
+function groupsOf(part: string): string[] | null {
+	if (part === "") return []
+	const groups = part.split(":")
+	for (const g of groups) {
+		if (!/^[0-9A-Fa-f]{1,4}$/.test(g)) return null
+	}
+	return groups
+}
+
+function parseIpv6(s: string): bigint | null {
+	let addr = s
+	let tail: number[] = []
+	const lastColon = addr.lastIndexOf(":")
+	if (lastColon !== -1 && addr.indexOf(".", lastColon) !== -1) {
+		const v4 = parseIpv4(addr.slice(lastColon + 1))
+		if (v4 === null) return null
+		tail = [Math.floor(v4 / 65536), v4 % 65536]
+		addr = addr.slice(0, lastColon + 1)
+		/* "::1.2.3.4" leaves "::", "a::1.2.3.4" leaves "a::"; "a:1.2.3.4" leaves "a:" */
+		if (addr.endsWith(":") && !addr.endsWith("::")) addr = addr.slice(0, -1)
+	}
+	const halves = addr.split("::")
+	if (halves.length > 2) return null
+	const left = groupsOf(halves[0])
+	if (left === null) return null
+	let groups: number[]
+	if (halves.length === 2) {
+		const right = groupsOf(halves[1])
+		if (right === null) return null
+		const fill = 8 - left.length - right.length - tail.length
+		if (fill < 1) return null
+		groups = [...left.map(hex), ...Array.from({ length: fill }, () => 0), ...right.map(hex), ...tail]
+	} else {
+		groups = [...left.map(hex), ...tail]
+	}
+	if (groups.length !== 8) return null
+	let n = 0n
+	for (const g of groups) n = (n << 16n) | BigInt(g)
+	return n
+}
+
+function hex(g: string): number {
+	return Number.parseInt(g, 16)
+}
+
+/** An IPv4-mapped IPv6 address (`::ffff:a.b.c.d`) is the IPv4 address it maps. */
+function fromV6(n: bigint): IpAddress {
+	if ((n & V4_MAPPED_MASK) === V4_MAPPED_PREFIX) return { n: Number(n & 0xffffffffn), v: 4 }
+	return { n, v: 6 }
+}
+
+/**
+ * Parses an address as a peer or a forwarding header writes it: brackets, an IPv6 zone
+ * (`%eth0`) and a port (`1.2.3.4:5678`, `[::1]:5678`) are accepted and dropped. Returns
+ * `null` for anything that is not exactly one address.
+ */
+export function parseIp(input: string): IpAddress | null {
+	let s = input.trim()
+	if (s.startsWith("[")) {
+		const close = s.indexOf("]")
+		if (close === -1) return null
+		const after = s.slice(close + 1)
+		if (after !== "" && !/^:\d{1,5}$/.test(after)) return null
+		s = s.slice(1, close)
+	} else if (s.indexOf(":") !== -1 && s.indexOf(":") === s.lastIndexOf(":") && s.includes(".")) {
+		/* "1.2.3.4:5678" — one colon and a dot can only be IPv4 with a port */
+		const [host, port] = s.split(":")
+		if (!/^\d{1,5}$/.test(port)) return null
+		s = host
+	}
+	const zone = s.indexOf("%")
+	if (zone !== -1) {
+		if (!s.includes(":")) return null
+		s = s.slice(0, zone)
+	}
+	if (s.includes(":")) {
+		const n = parseIpv6(s)
+		return n === null ? null : fromV6(n)
+	}
+	const n = parseIpv4(s)
+	return n === null ? null : { n, v: 4 }
+}
+
+/** Canonical text: dotted IPv4, or RFC 5952 IPv6 (lowercase, longest zero run compressed). */
+export function formatIp(addr: IpAddress): string {
+	if (addr.v === 4) {
+		const n = addr.n
+		return `${Math.floor(n / 16777216)}.${Math.floor(n / 65536) % 256}.${Math.floor(n / 256) % 256}.${n % 256}`
+	}
+	const groups: number[] = []
+	for (let i = 7; i >= 0; i--) groups.push(Number((addr.n >> BigInt(i * 16)) & 0xffffn))
+	let bestStart = -1
+	let bestLen = 1
+	for (let i = 0; i < 8;) {
+		if (groups[i] !== 0) {
+			i++
+			continue
+		}
+		let j = i
+		while (j < 8 && groups[j] === 0) j++
+		if (j - i > bestLen) {
+			bestStart = i
+			bestLen = j - i
+		}
+		i = j
+	}
+	const text = groups.map((g) => g.toString(16))
+	if (bestStart === -1) return text.join(":")
+	const head = text.slice(0, bestStart).join(":")
+	const tail = text.slice(bestStart + bestLen).join(":")
+	return `${head}::${tail}`
+}
+
+/** `canonicalIp("::ffff:127.0.0.1")` is `"127.0.0.1"`; `null` when the input is not an address. */
+export function canonicalIp(input: string): string | null {
+	const addr = parseIp(input)
+	return addr === null ? null : formatIp(addr)
+}
+
+/**
+ * Parses an address or CIDR rule (`10.0.0.0/8`, `2001:db8::/32`, `203.0.113.7`). Strict: no
+ * port, no zone, a prefix length that fits the family. An IPv4-mapped IPv6 range of `/96` or
+ * longer is the IPv4 range it maps. Returns `null` when the rule is invalid.
+ */
+export function parseIpRange(rule: string): IpRange | null {
+	const s = rule.trim()
+	const slash = s.indexOf("/")
+	const ipText = slash === -1 ? s : s.slice(0, slash)
+	if (ipText.startsWith("[") || ipText.includes("%")) return null
+	let bits: number | null = null
+	if (slash !== -1) {
+		const bitsText = s.slice(slash + 1)
+		if (!/^\d{1,3}$/.test(bitsText)) return null
+		bits = Number(bitsText)
+	}
+	if (ipText.includes(":")) {
+		const n = parseIpv6(ipText)
+		if (n === null) return null
+		const prefix = bits ?? 128
+		if (prefix > 128) return null
+		if ((n & V4_MAPPED_MASK) === V4_MAPPED_PREFIX && prefix >= 96) {
+			return v4Range(Number(n & 0xffffffffn), prefix - 96)
+		}
+		const mask = prefix === 0 ? 0n : (((1n << BigInt(prefix)) - 1n) << BigInt(128 - prefix)) & ((1n << 128n) - 1n)
+		return { base: n & mask, mask, v: 6 }
+	}
+	const n = parseIpv4(ipText)
+	if (n === null) return null
+	const prefix = bits ?? 32
+	if (prefix > 32) return null
+	return v4Range(n, prefix)
+}
+
+function v4Range(n: number, prefix: number): IpRange {
+	const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0
+	return { base: (n & mask) >>> 0, mask, v: 4 }
+}
+
+export function ipInRange(addr: IpAddress, range: IpRange): boolean {
+	if (addr.v === 4 && range.v === 4) return (addr.n & range.mask) >>> 0 === range.base
+	if (addr.v === 6 && range.v === 6) return (addr.n & range.mask) === range.base
+	return false
+}