@aventara/access 0.0.0-stage → 0.1.0-rc.0

package/dist/kiosk/kiosk.store.js

@@ -0,0 +1,478 @@
+// The kiosk profile's records, through Better Auth's database adapter: enrolled
+// devices and their credentials, users' PINs, and the counts of failed PINs that
+// limit guessing.
+//
+// A device's credential is 32 random bytes, written `avk_device_…` as the registry's
+// keys are, held by the device in an HTTP-only cookie. The table keeps its SHA-256
+// only. It rotates at every PIN switch: the new secret goes to the device, and the
+// old one joins the device's token family, the hash of every secret it retired in
+// the last 400 days (the device cookie's life: an older one no browser still sends).
+// A request that brings a retired secret is a copy in use (a thief's, or the
+// device's own while the thief holds the newer one), and revokes the device with
+// every session on it, however many rotations ago it was retired. One exception: the
+// secret retired by the last rotation, within {@link ROTATION_GRACE} of it, is a
+// request that left before the device's answer arrived (a double tap, two calls at
+// once); it is refused, and nothing changes.
+//
+// Two limits on guessing PINs, both counted before the PIN is checked (so parallel
+// guesses cannot all pass one read) and both kept in the database (so they hold
+// across restarts and instances):
+//
+// - per user id on one device ({@link KIOSK_PIN_FAILURES}): 5 failures free, then
+//   one try per backoff that doubles from 1 minute to 1 hour, and after
+//   {@link KIOSK_PIN_DISABLE_AFTER} in a row the PIN stops working on that device. A
+//   success clears it. It is kept for any user id, one that holds no PIN (or names
+//   no user) included, so the answers never tell who holds a PIN. It is kept per
+//   device so that whoever stands at one device can slow, or disable, a colleague's
+//   PIN on that device only: on every other device it still works, and a full
+//   sign-in, or a new PIN, clears it everywhere. No count locks an account.
+// - per device ({@link KIOSK_DEVICE_FAILURES}): 10 failed PINs at once, for any
+//   users, and then one more every 90 seconds (a token bucket, so no window's edge
+//   lets a second burst through). A success gives its own try back but never the
+//   others', so a cashier who knows one PIN cannot reset the count between guesses
+//   at others. While the device is held, a user with no failure on it since their
+//   last right PIN still gets one try, counted as their first failure there: whoever
+//   spends the device's tries does not lock everyone else out of it.
+import { randomSecret } from "../random-secret.generator.js";
+import { sha256Hex } from "../sha256.digest.js";
+import { KIOSK_DEVICE_MODEL, KIOSK_LOCKOUT_MODEL, KIOSK_PIN_MODEL, KIOSK_RETIRED_MODEL, } from "./kiosk.schema.js";
+/**
+ * The device limit, for any users: `max` failed PINs at once, then one more every
+ * `window / max` seconds, so `max` in `window` over time.
+ */
+const KIOSK_DEVICE_FAILURES = { window: 900, max: 10 };
+/** Seconds a device's failed PIN keeps one of its tries spent. */
+const TRY_SPACING = KIOSK_DEVICE_FAILURES.window / KIOSK_DEVICE_FAILURES.max;
+/** How far ahead a device's tries may be spent before it is held: all but the last of `max`. */
+const TRY_TOLERANCE = (KIOSK_DEVICE_FAILURES.max - 1) * TRY_SPACING;
+/**
+ * The per-user limit on one device: `free` failed PINs, then one try per backoff,
+ * `first` seconds doubling with each failure up to `max` seconds.
+ */
+const KIOSK_PIN_FAILURES = { free: 5, first: 60, max: 3600 };
+/**
+ * Wrong PINs for one user on one device since their last right one there, after which
+ * the PIN stops working on that device until they sign in with full credentials or
+ * are given a new PIN: NIST SP 800-63B's ceiling of 100 consecutive failures (section
+ * 5.2.2). Reaching it takes days under the backoff, every try logged.
+ */
+const KIOSK_PIN_DISABLE_AFTER = 100;
+/** Seconds after a rotation in which the secret it retired is refused without revoking the device. */
+const ROTATION_GRACE = 30;
+/**
+ * How long a device keeps its credential cookie, in seconds: 400 days, the most a
+ * browser keeps one. A retired credential older than this is forgotten at the
+ * device's next rotation: no browser still sends it.
+ */
+export const DEVICE_COOKIE_MAX_AGE = 400 * 24 * 60 * 60;
+/** The rows a listing reads per call to the adapter. */
+const PAGE = 100;
+/** How many times a counter update is tried against concurrent ones before the call is refused. */
+const CAS_TRIES = 8;
+const SECRET = /^avk_device_[A-Za-z0-9_-]{43}$/;
+/** A new device secret: 256 random bits from the runtime's CSPRNG. */
+const newSecret = () => randomSecret("avk_device_");
+const hashOf = (secret) => `sha256:${sha256Hex(secret)}`;
+const time = (value) => value === null || value === undefined ? undefined : new Date(value).getTime();
+/** The kiosk's store over Better Auth's adapter and sessions. */
+export const kioskStore = (adapter, sessions, now = Date.now) => {
+    const device = async (id) => (await adapter.findOne({
+        model: KIOSK_DEVICE_MODEL,
+        where: [{ field: "id", value: id }],
+    }));
+    /** Every row of `model` that `where` matches, a page at a time: Better Auth's adapter answers 100 at most by default. */
+    const all = async (model, where) => {
+        const rows = [];
+        for (;;) {
+            const page = await adapter.findMany({
+                model,
+                where,
+                limit: PAGE,
+                offset: rows.length,
+                sortBy: { field: "id", direction: "asc" },
+            });
+            rows.push(...page);
+            if (page.length < PAGE) {
+                return rows;
+            }
+        }
+    };
+    /** The tokens of the sessions bound to a device. */
+    const sessionsOn = async (deviceId) => {
+        const rows = (await all("session", [
+            { field: "kioskDeviceId", value: deviceId },
+        ]));
+        const tokens = [];
+        for (const row of rows) {
+            if (typeof row.token === "string") {
+                tokens.push(row.token);
+            }
+        }
+        return tokens;
+    };
+    const endSessionsOn = async (deviceId) => {
+        const tokens = await sessionsOn(deviceId);
+        if (tokens.length > 0) {
+            await sessions.deleteSessions(tokens);
+        }
+        return tokens.length;
+    };
+    const lockoutKey = (deviceId, userId) => `${deviceId}:${userId}`;
+    const lockout = async (deviceId, userId) => (await adapter.findOne({
+        model: KIOSK_LOCKOUT_MODEL,
+        where: [{ field: "key", value: lockoutKey(deviceId, userId) }],
+    }));
+    /** Whether a user's try on a device waits: past the free failures, or past the ceiling; `undefined` when one may go now. */
+    const pairHeld = (row) => {
+        if (row === null || row.failures < KIOSK_PIN_FAILURES.free) {
+            return undefined;
+        }
+        if (row.failures >= KIOSK_PIN_DISABLE_AFTER) {
+            return { kind: "disabled" };
+        }
+        const backoff = Math.min(KIOSK_PIN_FAILURES.first *
+            2 ** Math.min(row.failures - KIOSK_PIN_FAILURES.free, 16), KIOSK_PIN_FAILURES.max);
+        const until = (time(row.lastFailureAt) ?? 0) + backoff * 1000;
+        const wait = Math.ceil((until - now()) / 1000);
+        return wait > 0 ? { kind: "wait", retryAfter: wait } : undefined;
+    };
+    /** Whole seconds since a device's enrollment: the clock its `triesBackAt` is read on. */
+    const clockOf = (row) => Math.max(0, Math.floor((now() - (time(row.createdAt) ?? 0)) / 1000));
+    return {
+        /** The device a credential names, read from its hash; `undefined` for none. */
+        check: async (secret) => {
+            if (typeof secret !== "string" || !SECRET.test(secret)) {
+                return undefined;
+            }
+            const hash = hashOf(secret);
+            const current = (await adapter.findOne({
+                model: KIOSK_DEVICE_MODEL,
+                where: [{ field: "secretHash", value: hash }],
+            }));
+            if (current !== null) {
+                return { kind: "current", device: current };
+            }
+            const previous = (await adapter.findOne({
+                model: KIOSK_DEVICE_MODEL,
+                where: [{ field: "previousSecretHash", value: hash }],
+            }));
+            if (previous !== null) {
+                const rotatedAt = time(previous.rotatedAt) ?? 0;
+                return {
+                    kind: now() - rotatedAt < ROTATION_GRACE * 1000 ? "stale" : "reused",
+                    device: previous,
+                };
+            }
+            const retired = (await adapter.findOne({
+                model: KIOSK_RETIRED_MODEL,
+                where: [{ field: "secretHash", value: hash }],
+            }));
+            const family = retired === null ? null : await device(retired.deviceId);
+            return family === null ? undefined : { kind: "reused", device: family };
+        },
+        /** Enrolls a device: its row, and the secret it is handed (once). */
+        enroll: async (input) => {
+            const secret = newSecret();
+            const device = (await adapter.create({
+                model: KIOSK_DEVICE_MODEL,
+                data: {
+                    name: input.name,
+                    secretHash: hashOf(secret),
+                    enrolledBy: input.enrolledBy,
+                    createdAt: new Date(now()),
+                    triesBackAt: 0,
+                    rotations: 0,
+                },
+            }));
+            return { device, secret };
+        },
+        /**
+         * Gives the device a new secret, in place of the one it brought; `undefined` when
+         * another request rotated it first (that one's secret is the device's now).
+         */
+        rotate: async (from) => {
+            const secret = newSecret();
+            // Into the family first: whichever request's rotation wins, this secret is
+            // the one it retires, so it is never live and unrecorded.
+            try {
+                await adapter.create({
+                    model: KIOSK_RETIRED_MODEL,
+                    data: {
+                        deviceId: from.id,
+                        secretHash: from.secretHash,
+                        retiredAt: new Date(now()),
+                    },
+                });
+            }
+            catch {
+                // Another request retired it first.
+            }
+            const rotated = await adapter.incrementOne({
+                model: KIOSK_DEVICE_MODEL,
+                where: [
+                    { field: "id", value: from.id },
+                    { field: "secretHash", value: from.secretHash },
+                ],
+                increment: { rotations: 1 },
+                set: {
+                    secretHash: hashOf(secret),
+                    previousSecretHash: from.secretHash,
+                    rotatedAt: new Date(now()),
+                },
+            });
+            if (rotated === null) {
+                return undefined;
+            }
+            // The family keeps no credential a browser no longer sends.
+            await adapter.deleteMany({
+                model: KIOSK_RETIRED_MODEL,
+                where: [
+                    { field: "deviceId", value: from.id },
+                    {
+                        field: "retiredAt",
+                        operator: "lt",
+                        value: new Date(now() - DEVICE_COOKIE_MAX_AGE * 1000),
+                    },
+                ],
+            });
+            return secret;
+        },
+        /** Revokes a device: every session on it ended, its counts and its row deleted. */
+        revoke: async (deviceId) => {
+            const found = await device(deviceId);
+            await endSessionsOn(deviceId);
+            await adapter.deleteMany({
+                model: KIOSK_LOCKOUT_MODEL,
+                where: [{ field: "deviceId", value: deviceId }],
+            });
+            await adapter.deleteMany({
+                model: KIOSK_RETIRED_MODEL,
+                where: [{ field: "deviceId", value: deviceId }],
+            });
+            if (found === null) {
+                return false;
+            }
+            await adapter.delete({
+                model: KIOSK_DEVICE_MODEL,
+                where: [{ field: "id", value: deviceId }],
+            });
+            return true;
+        },
+        sessionsOn,
+        endSessionsOn,
+        /** Every enrolled device, oldest first, as a manager sees it. */
+        devices: async () => {
+            const rows = (await all(KIOSK_DEVICE_MODEL, []));
+            return rows
+                .map((row) => ({
+                id: row.id,
+                name: row.name,
+                enrolledBy: row.enrolledBy,
+                enrolledAt: new Date(row.createdAt),
+                lastSwitchAt: row.rotatedAt === null || row.rotatedAt === undefined
+                    ? null
+                    : new Date(row.rotatedAt),
+            }))
+                .sort((left, right) => left.enrolledAt.getTime() - right.enrolledAt.getTime() ||
+                (left.id < right.id ? -1 : 1));
+        },
+        /** A user's PIN, as its hash; `undefined` when they have none. */
+        pinOf: async (userId) => (await adapter.findOne({
+            model: KIOSK_PIN_MODEL,
+            where: [{ field: "userId", value: userId }],
+        })) ?? undefined,
+        /** Sets a user's PIN hash, and clears their failed PINs on every device. */
+        setPin: async (userId, pinHash) => {
+            const at = new Date(now());
+            const updated = await adapter.update({
+                model: KIOSK_PIN_MODEL,
+                where: [{ field: "userId", value: userId }],
+                update: { pinHash, updatedAt: at },
+            });
+            if (updated === null) {
+                try {
+                    await adapter.create({
+                        model: KIOSK_PIN_MODEL,
+                        data: { userId, pinHash, updatedAt: at },
+                    });
+                }
+                catch (error) {
+                    // Another request created it first: this one's hash is the newer.
+                    const again = await adapter.update({
+                        model: KIOSK_PIN_MODEL,
+                        where: [{ field: "userId", value: userId }],
+                        update: { pinHash, updatedAt: at },
+                    });
+                    if (again === null) {
+                        throw error;
+                    }
+                }
+            }
+            await adapter.deleteMany({
+                model: KIOSK_LOCKOUT_MODEL,
+                where: [{ field: "userId", value: userId }],
+            });
+        },
+        /**
+         * Replaces a user's PIN hash with the same PIN hashed anew, only while the row
+         * still holds `from` (a compare-and-set): a PIN set meanwhile stays. Their failed
+         * PINs are left as they are.
+         */
+        rehashPin: async (userId, from, pinHash) => {
+            await adapter.updateMany({
+                model: KIOSK_PIN_MODEL,
+                where: [
+                    { field: "userId", value: userId },
+                    { field: "pinHash", value: from },
+                ],
+                update: { pinHash, updatedAt: new Date(now()) },
+            });
+        },
+        /** Clears a user's failed PINs on every device (a full sign-in proves who they are). */
+        clearUser: async (userId) => {
+            await adapter.deleteMany({
+                model: KIOSK_LOCKOUT_MODEL,
+                where: [{ field: "userId", value: userId }],
+            });
+        },
+        /** Whether a user's next try on a device waits, and why; `undefined` when it may go. */
+        pairHeld: async (deviceId, userId) => pairHeld(await lockout(deviceId, userId)),
+        /**
+         * Counts a try at a user's PIN on a device, before it is checked; held when
+         * the user's backoff on that device has not passed, or their PIN is disabled
+         * there (counted by another request meanwhile).
+         */
+        reservePair: async (deviceId, userId) => {
+            for (let attempt = 0; attempt < CAS_TRIES; attempt += 1) {
+                const row = await lockout(deviceId, userId);
+                const held = pairHeld(row);
+                if (held !== undefined) {
+                    return held;
+                }
+                const at = new Date(now());
+                if (row === null) {
+                    try {
+                        await adapter.create({
+                            model: KIOSK_LOCKOUT_MODEL,
+                            data: {
+                                key: lockoutKey(deviceId, userId),
+                                deviceId,
+                                userId,
+                                failures: 1,
+                                lastFailureAt: at,
+                            },
+                        });
+                        return undefined;
+                    }
+                    catch {
+                        // Another request counted the first try: read it again.
+                        continue;
+                    }
+                }
+                const counted = await adapter.incrementOne({
+                    model: KIOSK_LOCKOUT_MODEL,
+                    where: [
+                        { field: "key", value: row.key },
+                        { field: "failures", value: row.failures },
+                    ],
+                    increment: { failures: 1 },
+                    set: { lastFailureAt: at },
+                });
+                if (counted !== null) {
+                    return undefined;
+                }
+            }
+            return { kind: "wait", retryAfter: KIOSK_PIN_FAILURES.first };
+        },
+        /**
+         * Counts a user's first try on a device since their last right PIN there, and
+         * only that one: `false` when they have a failure there already (counted by
+         * another request meanwhile included). What a held device lets through.
+         */
+        reserveFirstPair: async (deviceId, userId) => {
+            try {
+                await adapter.create({
+                    model: KIOSK_LOCKOUT_MODEL,
+                    data: {
+                        key: lockoutKey(deviceId, userId),
+                        deviceId,
+                        userId,
+                        failures: 1,
+                        lastFailureAt: new Date(now()),
+                    },
+                });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        /** Clears a user's failed PINs on a device: their PIN matched there. */
+        clearPair: async (deviceId, userId) => {
+            await adapter.deleteMany({
+                model: KIOSK_LOCKOUT_MODEL,
+                where: [{ field: "key", value: lockoutKey(deviceId, userId) }],
+            });
+        },
+        /**
+         * Counts a try on a device, before the PIN is checked; held when the device's
+         * tries are spent ({@link KIOSK_DEVICE_FAILURES}): `max` at once, one back every
+         * `window / max` seconds.
+         */
+        reserveDevice: async (deviceId) => {
+            for (let attempt = 0; attempt < CAS_TRIES; attempt += 1) {
+                const row = await device(deviceId);
+                if (row === null) {
+                    return { retryAfter: KIOSK_DEVICE_FAILURES.window };
+                }
+                const clock = clockOf(row);
+                const back = row.triesBackAt;
+                const from = Math.max(back, clock);
+                if (from - clock > TRY_TOLERANCE) {
+                    return { retryAfter: from - clock - TRY_TOLERANCE };
+                }
+                // The whole state is `triesBackAt`, so a write that finds it unchanged
+                // since the read is right, whatever came between.
+                const counted = await adapter.incrementOne({
+                    model: KIOSK_DEVICE_MODEL,
+                    where: [
+                        { field: "id", value: deviceId },
+                        { field: "triesBackAt", value: back },
+                    ],
+                    increment: { triesBackAt: from + TRY_SPACING - back },
+                });
+                if (counted !== null) {
+                    return undefined;
+                }
+            }
+            return { retryAfter: TRY_SPACING };
+        },
+        /** Gives back a try counted on a device: its PIN matched. */
+        releaseDevice: async (deviceId) => {
+            for (let attempt = 0; attempt < CAS_TRIES; attempt += 1) {
+                const row = await device(deviceId);
+                if (row === null) {
+                    return;
+                }
+                const clock = clockOf(row);
+                const back = row.triesBackAt;
+                if (back <= clock) {
+                    return;
+                }
+                const given = await adapter.incrementOne({
+                    model: KIOSK_DEVICE_MODEL,
+                    where: [
+                        { field: "id", value: deviceId },
+                        { field: "triesBackAt", value: back },
+                    ],
+                    increment: {
+                        triesBackAt: Math.max(back - TRY_SPACING, clock) - back,
+                    },
+                });
+                if (given !== null) {
+                    return;
+                }
+            }
+        },
+    };
+};

package/dist/kiosk/lan-range.policy.d.ts

@@ -0,0 +1,31 @@
+/** A range of `insecureLan`, read. */
+export type LanRange = {
+    /** As the app wrote it, which is its canonical form. */
+    readonly cidr: string;
+    /** The network address, as an unsigned 32-bit number. */
+    readonly network: number;
+    readonly prefix: number;
+};
+/**
+ * The checked `profile.insecureLan`: each range read, or a refusal saying what to
+ * change.
+ */
+export declare const checkInsecureLan: (value: unknown) => readonly LanRange[];
+/**
+ * The range of `ranges` that holds `hostname` (a URL's `hostname`, which the URL
+ * parser writes in dotted decimal for any IPv4 spelling), or `undefined`: a hostname
+ * or an IPv6 address is in none.
+ */
+export declare const lanRangeOf: (hostname: string, ranges: readonly LanRange[]) => LanRange | undefined;
+/** Whether `hostname` is an IPv4 address in dotted decimal, as the URL parser writes one. */
+export declare const isIpv4Literal: (hostname: string) => boolean;
+/**
+ * Whether `hostname` (dotted decimal) is the network or the broadcast address of
+ * `range`, which no server has; a /31 or a /32 has neither.
+ */
+export declare const isRangeEdge: (hostname: string, range: LanRange) => boolean;
+/**
+ * The host a URL is written with, before the URL parser reads it (`192.168.01.10`
+ * stays so); `undefined` when the string has no `scheme://host` to read.
+ */
+export declare const writtenHost: (url: string) => string | undefined;

package/dist/kiosk/lan-range.policy.js

@@ -0,0 +1,113 @@
+// The kiosk profile's `insecureLan`: the private IPv4 ranges of an on-prem till
+// network (a router of its own) on whose addresses the kiosk takes a plain http:
+// base URL. The kiosk otherwise refuses http: off a loopback host, since the device's
+// credential, its PIN sessions and the PINs themselves would cross the network in the
+// clear; this is the operator saying, range by range, that the network is the tills'
+// alone.
+//
+// A range is written in full: four decimal numbers without leading zeros (so no
+// octal or hex reading differs from the one a person sees) and a prefix length,
+// with its host bits clear. It must lie wholly inside RFC 1918's private blocks and be
+// a /16 or narrower: shared address space (100.64.0.0/10), link-local, loopback,
+// public ranges, IPv6 and hostnames are refused, and so is a whole /8 or /12, which
+// is an enterprise's network rather than a till network.
+import { AccessError } from "../access/access.error.js";
+/** The widest range `insecureLan` takes: a /16. */
+const LAN_WIDEST_PREFIX = 16;
+/** RFC 1918's private blocks: a range must lie wholly inside one. */
+const PRIVATE_BLOCKS = [
+    { cidr: "10.0.0.0/8", network: 0x0a000000, prefix: 8 },
+    { cidr: "172.16.0.0/12", network: 0xac100000, prefix: 12 },
+    { cidr: "192.168.0.0/16", network: 0xc0a80000, prefix: 16 },
+];
+/** One octet in decimal, without a leading zero. */
+const OCTET = "(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)";
+const ADDRESS = `${OCTET}\\.${OCTET}\\.${OCTET}\\.${OCTET}`;
+const CIDR = new RegExp(`^${ADDRESS}/(3[0-2]|[12]?\\d)$`);
+const DOTTED = new RegExp(`^${ADDRESS}$`);
+const refuse = (message) => {
+    throw new AccessError("ACCESS_OPTIONS_INVALID", message);
+};
+const maskOf = (prefix) => prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+const numberOf = (octets) => octets.reduce((value, octet) => value * 256 + Number(octet), 0);
+const dotted = (address) => [24, 16, 8, 0].map((shift) => (address >>> shift) & 0xff).join(".");
+/** Whether `address` (unsigned 32-bit) lies in `range`. */
+const inside = (address, range) => (address & maskOf(range.prefix)) >>> 0 === range.network;
+/**
+ * The checked `profile.insecureLan`: each range read, or a refusal saying what to
+ * change.
+ */
+export const checkInsecureLan = (value) => {
+    if (!Array.isArray(value)) {
+        return refuse(`\`profile.insecureLan\` is a list of private IPv4 ranges in CIDR notation, such as \`["192.168.1.0/24"]\`; it was ${JSON.stringify(value)}.`);
+    }
+    if (value.length === 0) {
+        return refuse("`profile.insecureLan` lists at least one range: leave the key out to keep the kiosk on https:.");
+    }
+    const ranges = [];
+    for (const entry of value) {
+        const match = typeof entry === "string" ? CIDR.exec(entry) : null;
+        if (typeof entry !== "string" || match === null) {
+            return refuse(`\`profile.insecureLan\` takes IPv4 CIDRs written in full, such as \`"192.168.1.0/24"\`: four decimal numbers without leading zeros, then \`/\` and a prefix length from 0 to 32. A hostname, an IPv6 range or any other spelling is refused; it was ${JSON.stringify(entry)}.`);
+        }
+        const prefix = Number(match[5]);
+        const address = numberOf(match.slice(1, 5));
+        const network = (address & maskOf(prefix)) >>> 0;
+        if (network !== address) {
+            return refuse(`\`profile.insecureLan\`'s \`${entry}\` has bits set past its prefix length: write its network, \`${dotted(network)}/${prefix}\`, or the one address \`${dotted(address)}/32\`.`);
+        }
+        if (prefix < LAN_WIDEST_PREFIX) {
+            return refuse(`\`profile.insecureLan\`'s \`${entry}\` is wider than a till network: list the tills' own subnet, a /${LAN_WIDEST_PREFIX} or narrower (such as \`"192.168.1.0/24"\`).`);
+        }
+        const range = { cidr: entry, network, prefix };
+        if (!PRIVATE_BLOCKS.some((block) => prefix >= block.prefix && inside(network, block))) {
+            return refuse(`\`profile.insecureLan\`'s \`${entry}\` is not a private range: a till network is inside ${PRIVATE_BLOCKS.map((block) => block.cidr).join(", ")} (RFC 1918); shared, link-local, loopback and public addresses are refused (loopback needs no listing).`);
+        }
+        if (ranges.some((listed) => listed.cidr === entry)) {
+            return refuse(`\`profile.insecureLan\` lists \`${entry}\` twice.`);
+        }
+        // Two ranges either nest or are apart: a nested one says nothing the wider does not.
+        const nested = ranges.find((listed) => inside(listed.network, range) || inside(range.network, listed));
+        if (nested !== undefined) {
+            const [narrow, wide] = nested.prefix >= prefix ? [nested, range] : [range, nested];
+            return refuse(`\`profile.insecureLan\`'s \`${narrow.cidr}\` lies inside \`${wide.cidr}\`: list the till network once, as one range.`);
+        }
+        ranges.push(range);
+    }
+    return ranges;
+};
+/**
+ * The range of `ranges` that holds `hostname` (a URL's `hostname`, which the URL
+ * parser writes in dotted decimal for any IPv4 spelling), or `undefined`: a hostname
+ * or an IPv6 address is in none.
+ */
+export const lanRangeOf = (hostname, ranges) => {
+    const match = DOTTED.exec(hostname);
+    if (match === null) {
+        return undefined;
+    }
+    const address = numberOf(match.slice(1, 5));
+    return ranges.find((range) => inside(address, range));
+};
+/** Whether `hostname` is an IPv4 address in dotted decimal, as the URL parser writes one. */
+export const isIpv4Literal = (hostname) => DOTTED.test(hostname);
+/**
+ * Whether `hostname` (dotted decimal) is the network or the broadcast address of
+ * `range`, which no server has; a /31 or a /32 has neither.
+ */
+export const isRangeEdge = (hostname, range) => {
+    const match = DOTTED.exec(hostname);
+    if (match === null || range.prefix > 30) {
+        return false;
+    }
+    const address = numberOf(match.slice(1, 5));
+    const broadcast = (range.network | ~maskOf(range.prefix)) >>> 0;
+    return address === range.network || address === broadcast;
+};
+/**
+ * The host a URL is written with, before the URL parser reads it (`192.168.01.10`
+ * stays so); `undefined` when the string has no `scheme://host` to read.
+ */
+export const writtenHost = (url) => /^[a-z][a-z\d+.-]*:\/\/(?:[^/?#@]*@)?(\[[^\]]*\]|[^/?#:]*)/i
+    .exec(url.trim())?.[1]
+    ?.toLowerCase();

package/dist/kiosk/pin.policy.d.ts

@@ -0,0 +1,9 @@
+/** The shortest and longest PIN, in digits. */
+export declare const PIN_LENGTH: {
+    readonly min: 6;
+    readonly max: 12;
+};
+/** Why a PIN is refused at `setPin`, or `undefined` when it is accepted. */
+export declare const pinDefect: (pin: unknown) => string | undefined;
+/** Whether a PIN could be one `setPin` accepted: its shape only, for a switch. */
+export declare const pinShaped: (pin: unknown) => pin is string;