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

package/dist/kiosk/kiosk.plugin.js

@@ -0,0 +1,877 @@
+// The kiosk profile's part of the Access plugin: its routes, the hooks that bind a
+// session to the device it was opened on, and the operator's API.
+//
+// Routes (under Better Auth's base path):
+//
+//   POST /kiosk/enroll-device   a fresh full-credential session `canEnrollDevice`
+//                               allows enrolls the device it is on: the device gets
+//                               its credential (an HTTP-only cookie), and the
+//                               enrolling session ends, so the device starts locked
+//   POST /kiosk/revoke-device   the same revokes a device
+//   GET  /kiosk/list-devices    the same lists the enrolled devices
+//   POST /kiosk/set-pin         a fresh full-credential session sets its own PIN
+//   POST /kiosk/switch-user     an enrolled device opens a session for a user by PIN,
+//                               ending every session on it and every one the request
+//                               carried
+//   POST /kiosk/lock            an enrolled device ends the same sessions
+//
+// and one server-only endpoint (Better Auth's `createAuthEndpoint.serverOnly`, which
+// its router never serves): `access.api.kioskSetUserPin({ body: { userId, pin } })`,
+// the app's server setting anyone's PIN. The operator's API (`access.kiosk`) lists
+// and revokes devices from the app's server.
+//
+// Any session opened on an enrolled device (a PIN switch's, or a password sign-in's
+// there) carries the device's id (`session.kioskDeviceId`); a PIN's carries
+// `kioskPin: true` too. On every call of Better Auth's that carries a session (by its
+// cookie, or by an `Authorization: Bearer` header as `bearer()` would read it: its
+// router's routes, and its API called with headers or a `request`, so `access.state` and `GET /me`
+// too), the guard reads each such session; one bound to a device is ended, and the
+// call goes on without it, when the request does not bring its device's current
+// credential (a session copied elsewhere) or the session has been idle for the
+// profile's `idleTimeout` (only a request that may change something counts as use:
+// `session-use.marker.ts`); one bound to no device is ended the same way when the
+// request brings an enrolled device's credential (it was opened off the device, and
+// is no session on it). A PIN session reaches only the routes that read it or end
+// it (and those that sign in with full credentials): it mints no token, no other
+// session, no credential, and changes no account. No device-bound session is issued
+// a token, and `/get-session` answers one without its token. That holds for Better
+// Auth's OAuth provider too (`mcp`, `audience`): a device-bound session is refused at
+// the routes that turn a session into an authorization grant (`/oauth2/authorize`,
+// `/oauth2/consent`, `/oauth2/continue`) and at those that manage the caller's
+// clients and consents, a request from an enrolled device that carries an
+// authorization request to resume (the provider's signed `oauth_query`, which its
+// login page posts with the sign-in) is refused before it runs, and so is a session
+// on one for a sign-in whose state carries such a request (a social sign-in begun
+// elsewhere); the access-token verifier takes no token issued in a device-bound
+// session either. No answer on this profile carries `bearer()`'s `set-auth-token`.
+import { startsSession } from "../access/profile.policy.js";
+import { signInTarget } from "../audit/audit.log.js";
+import { needsRehash, rehashPolicyOf, } from "../passwords/argon2id.hasher.js";
+import { isRecord } from "../policies.compiler.js";
+import { DEVICE_COOKIE_MAX_AGE, kioskStore, } from "./kiosk.store.js";
+import { KIOSK_ENROLL_PATH, KIOSK_LIST_PATH, KIOSK_LOCK_PATH, KIOSK_REVOKE_PATH, KIOSK_SET_PIN_PATH, KIOSK_SWITCH_PATH, } from "./kiosk-verbs.schema.js";
+import { pinDefect, pinShaped } from "./pin.policy.js";
+import { mayChange, SESSION_USE } from "./session-use.marker.js";
+/** The device credential's cookie, as Better Auth names it (`better-auth.kiosk_device`). */
+const DEVICE_COOKIE = "kiosk_device";
+/** How often a bound session's last use is written, in seconds: its idle time is this precise. */
+const SEEN_EVERY = 15;
+/** The longest device name and user id a kiosk route reads. */
+const NAME_MAX = 64;
+const ID_MAX = 255;
+const time = (value) => value === null || value === undefined ? undefined : new Date(value).getTime();
+/**
+ * Whether a call is the till's use of its session, which keeps it from idling: a
+ * request that may change something. Through a request (the router, `access.client`'s
+ * `call`), by its method; `access.state`'s read of the session, when it marks it
+ * ({@link SESSION_USE}: the framework's request is a write); any other call of the
+ * server's own but reading the session.
+ */
+const usesSession = (context) => {
+    if (context[SESSION_USE] === true) {
+        return true;
+    }
+    const sent = typeof context.request === "object" && context.request !== null
+        ? context.request.method
+        : context.method;
+    if (typeof sent === "string") {
+        return mayChange(sent.toUpperCase());
+    }
+    return context.path !== "/get-session";
+};
+/** Whether a call came through a request (the router, or `access.client`'s `call`), not the server's own API call. */
+const fromOutside = (context) => typeof context.request === "object" && context.request !== null;
+const originOf = (context) => fromOutside(context) ? "client" : "application";
+/**
+ * The request headers a call carries, as Better Auth reads its cookies: its
+ * `headers` (a `Headers`, or a plain record), or its `request`'s when it passed none.
+ */
+const headersOf = (context) => {
+    if (context.headers instanceof Headers) {
+        return context.headers;
+    }
+    if (isRecord(context.headers)) {
+        try {
+            return new Headers(context.headers);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (context.headers === undefined && context.request instanceof Request) {
+        return context.request.headers;
+    }
+    return undefined;
+};
+/** Whether a call brings a cookie or an `Authorization` header: the calls the guard reads. */
+const carriesCredentials = (context) => {
+    const headers = context === undefined ? undefined : headersOf(context);
+    return (headers !== undefined &&
+        (headers.has("cookie") || headers.has("authorization")));
+};
+/** Whether a session is bound to an enrolled device. */
+const boundDevice = (session) => typeof session?.kioskDeviceId === "string" && session.kioskDeviceId !== ""
+    ? session.kioskDeviceId
+    : undefined;
+/**
+ * The routes a PIN session reaches: reading the session, ending it, switching or
+ * locking the device, Access's `me`, the key set, and the routes that sign in with
+ * full credentials (never Better Auth's multi-session switch or the admin's
+ * impersonation, which act as the current session).
+ */
+const KIOSK_SESSION_ROUTES = new Set([
+    "/get-session",
+    "/sign-out",
+    "/me",
+    "/jwks",
+    "/ok",
+    "/error",
+    KIOSK_SWITCH_PATH,
+    KIOSK_LOCK_PATH,
+]);
+/** Whether a PIN session may reach the endpoint at `path` (a server-only endpoint has none). */
+const kioskSessionReaches = (path) => typeof path === "string" &&
+    (KIOSK_SESSION_ROUTES.has(path) ||
+        (startsSession(path) &&
+            !path.startsWith("/multi-session/") &&
+            !path.startsWith("/admin/")));
+/**
+ * The OAuth provider's routes (`@better-auth/oauth-provider`) that turn the caller's
+ * session into an authorization grant: a device-bound session reaches none of them.
+ */
+const OAUTH_GRANT_ROUTES = new Set([
+    "/oauth2/authorize",
+    "/oauth2/consent",
+    "/oauth2/continue",
+]);
+/** A device-bound session's refusal on a route that would issue it a token. */
+const NO_TOKEN_MESSAGE = "A session bound to a kiosk device is not issued a token.";
+/**
+ * The OAuth provider's routes that manage the caller's clients and consents (and the
+ * admin's, under `/admin/oauth2/`): account-level OAuth settings, which a session
+ * bound to a shared device does not change or read.
+ */
+const OAUTH_MANAGEMENT_ROUTES = new Set([
+    "/oauth2/register",
+    "/oauth2/create-client",
+    "/oauth2/get-client",
+    "/oauth2/get-clients",
+    "/oauth2/update-client",
+    "/oauth2/delete-client",
+    "/oauth2/client/rotate-secret",
+    "/oauth2/client/rotate-keys",
+    "/oauth2/get-consent",
+    "/oauth2/get-consents",
+    "/oauth2/update-consent",
+    "/oauth2/delete-consent",
+]);
+/** Whether `path` is one of the OAuth provider's management routes. */
+const managesOAuth = (path) => typeof path === "string" &&
+    (OAUTH_MANAGEMENT_ROUTES.has(path) || path.startsWith("/admin/oauth2/"));
+/** Whether a call carries an authorization request to resume: the OAuth provider's signed `oauth_query`. */
+const resumesAuthorization = (context) => isRecord(context?.body) && context.body.oauth_query !== undefined;
+const BEARER = "bearer ";
+/** The response header Better Auth's `bearer()` hands a session's token to page code in. */
+const AUTH_TOKEN_HEADER = "set-auth-token";
+/** A bearer value as `bearer()` reads it: URL-decoded when it can be. */
+const decoded = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};
+/** The kiosk's members of the Access plugin: its routes, its hooks and its operator API. */
+export const kioskPlugin = (input) => {
+    const { settings, refusal, auditLog } = input;
+    const storeOf = (context) => kioskStore(context.adapter, context.internalAdapter);
+    /**
+     * The device credential's cookie: Better Auth's form (its prefix and attributes),
+     * always `SameSite=Lax`, whatever the app's defaults say (a Strict one is not sent
+     * on a link the till opens from another site, such as a magic link from webmail,
+     * and the session it opens would not be bound), and on https a `__Host-` cookie,
+     * `Secure`, at `/` and with no `Domain`, so no other host (a subdomain included)
+     * can set or read it.
+     */
+    const deviceCookie = (context) => {
+        const cookie = context.createAuthCookie(DEVICE_COOKIE, {
+            maxAge: DEVICE_COOKIE_MAX_AGE,
+        });
+        const secure = input.secureDevice || cookie.attributes.secure === true;
+        const dropped = secure ? /^(?:samesite|domain)$/i : /^samesite$/i;
+        const attributes = {
+            ...Object.fromEntries(Object.entries(cookie.attributes).filter(([attribute]) => !dropped.test(attribute))),
+            sameSite: "lax",
+        };
+        if (!secure) {
+            return { name: cookie.name, attributes };
+        }
+        return {
+            name: `__Host-${cookie.name.replace(/^__(?:secure|host)-/i, "")}`,
+            attributes: { ...attributes, secure: true, path: "/" },
+        };
+    };
+    const setDevice = (ctx, secret) => {
+        const cookie = deviceCookie(ctx.context);
+        ctx.setCookie(cookie.name, secret, {
+            ...cookie.attributes,
+            httpOnly: true,
+            maxAge: DEVICE_COOKIE_MAX_AGE,
+        });
+    };
+    const clearDevice = (ctx) => {
+        const cookie = deviceCookie(ctx.context);
+        ctx.setCookie(cookie.name, "", { ...cookie.attributes, maxAge: 0 });
+    };
+    const refuse = (status, code, message, headers) => new refusal(status, { code, message }, headers);
+    /** The request's body as an object of strings, refusing any other shape. */
+    const bodyOf = (ctx, keys) => {
+        const body = ctx.body ?? {};
+        if (!isRecord(body)) {
+            throw refuse("BAD_REQUEST", "INVALID_BODY", "The body is a JSON object.");
+        }
+        for (const key of Object.keys(body)) {
+            if (!keys.includes(key)) {
+                throw refuse("BAD_REQUEST", "INVALID_BODY", `The body has \`${key}\`, which this route does not take (it takes ${keys.join(", ") || "nothing"}).`);
+            }
+        }
+        for (const key of keys) {
+            if (typeof body[key] !== "string") {
+                throw refuse("BAD_REQUEST", "INVALID_BODY", `The body's \`${key}\` is a string.`);
+            }
+        }
+        return body;
+    };
+    /**
+     * The session tokens a request carries: its signed session cookie's, and an
+     * `Authorization: Bearer` value's, read as `bearer()` reads one (a signed cookie
+     * value, or a bare token). Read for what the request could be taken to carry, so
+     * an unchecked signature only ever restricts: the guard ends or refuses, a
+     * switch or a lock ends.
+     */
+    const carried = async (ctx) => {
+        const tokens = new Set();
+        const cookie = await ctx.getSignedCookie(ctx.context.authCookies.sessionToken.name, ctx.context.secret);
+        if (typeof cookie === "string" && cookie !== "") {
+            tokens.add(cookie);
+        }
+        const header = ctx.getHeader("authorization");
+        if (typeof header === "string" &&
+            header.slice(0, BEARER.length).toLowerCase() === BEARER) {
+            const [token = ""] = decoded(header.slice(BEARER.length).trim()).split(".");
+            if (token !== "") {
+                tokens.add(token);
+            }
+        }
+        return [...tokens];
+    };
+    /** A device whose retired credential came back: revoked, with every session on it, and logged. */
+    const reused = async (ctx, store, deviceId) => {
+        await store.revoke(deviceId);
+        await auditLog?.record({
+            at: new Date(),
+            kind: "kiosk-device",
+            userId: null,
+            deviceId,
+            reason: "token-reuse",
+            origin: originOf(ctx),
+        });
+    };
+    /** A request that brought the credential the device's last rotation retired, inside the grace: logged, and refused. */
+    const busy = async (ctx, deviceId) => {
+        await auditLog?.record({
+            at: new Date(),
+            kind: "kiosk-device",
+            userId: null,
+            deviceId,
+            reason: "stale-in-grace",
+            origin: originOf(ctx),
+        });
+        return refuse("CONFLICT", "KIOSK_DEVICE_BUSY", "Another request on this device changed its credential a moment ago: try again.");
+    };
+    /**
+     * The device the request's credential names, current. A credential the last
+     * rotation retired, inside the grace, is a request that left before the answer:
+     * refused, and nothing changes (the device keeps its cookie). Any other retired
+     * credential is a copy in use: the device is revoked, and its cookie cleared.
+     */
+    const deviceOf = async (ctx) => {
+        const store = storeOf(ctx.context);
+        const checked = await store.check(ctx.getCookie(deviceCookie(ctx.context).name));
+        if (checked?.kind === "current") {
+            return { store, device: checked.device };
+        }
+        if (checked?.kind === "stale") {
+            throw await busy(ctx, checked.device.id);
+        }
+        if (checked?.kind === "reused") {
+            await reused(ctx, store, checked.device.id);
+            clearDevice(ctx);
+        }
+        return { store, device: undefined };
+    };
+    const notEnrolled = () => refuse("UNAUTHORIZED", "KIOSK_DEVICE_NOT_ENROLLED", "This device is not enrolled: a manager enrolls it with `enrollDevice`.");
+    /**
+     * The request's session, when it was opened with full credentials (any sign-in
+     * but a PIN) within Better Auth's `session.freshAge`: what enrolling, listing and
+     * revoking devices, and setting one's PIN, take.
+     */
+    const fullSession = async (ctx) => {
+        const found = await input.getSessionFromCtx(ctx, {
+            disableCookieCache: true,
+        });
+        if (found === null || found.session === undefined) {
+            throw refuse("UNAUTHORIZED", "UNAUTHORIZED", "Sign in first.");
+        }
+        if (found.session.kioskPin === true) {
+            throw refuse("FORBIDDEN", "KIOSK_FULL_CREDENTIAL_REQUIRED", "A PIN session cannot do this: sign in with your password.");
+        }
+        const freshAge = ctx.context.sessionConfig.freshAge;
+        if (freshAge !== 0 &&
+            Date.now() - (time(found.session.createdAt) ?? 0) >= freshAge * 1000) {
+            throw refuse("FORBIDDEN", "SESSION_NOT_FRESH", "Your session is too old for this: sign in again.");
+        }
+        return found;
+    };
+    /** A fresh full session whose user `canEnrollDevice` allows (`true` exactly): a manager. */
+    const managerSession = async (ctx) => {
+        const found = await fullSession(ctx);
+        const claims = await input.claimsFor(found);
+        if ((await settings.canEnrollDevice({ sub: found.user.id, claims })) !== true) {
+            throw refuse("FORBIDDEN", "KIOSK_ENROLL_REFUSED", "You may not enroll, list or revoke kiosk devices.");
+        }
+        return found;
+    };
+    /** A refused PIN, logged with its device and its target (the HMAC of the user id). */
+    const pinRefused = async (ctx, reason, userId, deviceId) => {
+        if (auditLog === undefined) {
+            return;
+        }
+        const target = await signInTarget(userId === undefined ? undefined : `userId:${userId}`, ctx.context.secret);
+        await auditLog.record({
+            at: new Date(),
+            kind: "sign-in-failed",
+            userId: null,
+            route: KIOSK_SWITCH_PATH,
+            reason,
+            origin: originOf(ctx),
+            ...(target === undefined ? {} : { target }),
+            ...(deviceId === undefined ? {} : { deviceId }),
+        });
+    };
+    const pinDisabled = () => refuse("FORBIDDEN", "KIOSK_PIN_DISABLED", "Too many wrong PINs for this user: sign in with your password, or ask a manager for a new PIN.");
+    const tooMany = (retryAfter) => refuse("TOO_MANY_REQUESTS", "KIOSK_PIN_LOCKED", "Too many wrong PINs. Please try again later.", { "X-Retry-After": String(retryAfter) });
+    /** A try held back by a limit, logged, as its refusal. */
+    const heldBack = async (ctx, held, userId, deviceId) => {
+        if (held.kind === "disabled") {
+            await pinRefused(ctx, "pin-disabled", userId, deviceId);
+            return pinDisabled();
+        }
+        await pinRefused(ctx, "rate-limited", userId, deviceId);
+        return tooMany(held.retryAfter);
+    };
+    const switchUser = async (ctx) => {
+        const { userId, pin } = bodyOf(ctx, ["userId", "pin"]);
+        const { store, device } = await deviceOf(ctx);
+        if (device === undefined) {
+            await pinRefused(ctx, "KIOSK_DEVICE_NOT_ENROLLED", undefined, undefined);
+            throw notEnrolled();
+        }
+        if (userId === "" || userId.length > ID_MAX || !pinShaped(pin)) {
+            throw refuse("BAD_REQUEST", "INVALID_USER_OR_PIN", "A switch takes a user id and a PIN of 6 to 12 digits.");
+        }
+        const pinHash = (await store.pinOf(userId))?.pinHash;
+        // The user's own count on this device, kept for any user id (one with no PIN,
+        // or no such user, included), so the answers never tell who holds a PIN.
+        const pairHeld = await store.pairHeld(device.id, userId);
+        if (pairHeld !== undefined) {
+            throw await heldBack(ctx, pairHeld, userId, device.id);
+        }
+        const deviceHeld = await store.reserveDevice(device.id);
+        if (deviceHeld === undefined) {
+            const pairCounted = await store.reservePair(device.id, userId);
+            if (pairCounted !== undefined) {
+                await store.releaseDevice(device.id);
+                throw await heldBack(ctx, pairCounted, userId, device.id);
+            }
+        }
+        else if (
+        // The device's tries are spent. A user with no failure on it since their last
+        // right PIN still gets their one try, counted as their first failure here:
+        // whoever spends the device's tries does not lock everyone else out of it.
+        // Only an id that names a user: a made-up one leaves no row behind past the
+        // device's limit. That answer tells whether an id names a user, never whether
+        // they hold a PIN.
+        (await ctx.context.internalAdapter.findUserById(userId)) === null ||
+            !(await store.reserveFirstPair(device.id, userId))) {
+            throw await heldBack(ctx, { kind: "wait", retryAfter: deviceHeld.retryAfter }, userId, device.id);
+        }
+        // A user with no PIN costs the same check as one with a PIN: a decoy hash.
+        const matches = await input.pins.verify({
+            hash: pinHash ?? "",
+            password: pin,
+        });
+        if (!matches || pinHash === undefined) {
+            await pinRefused(ctx, "INVALID_USER_OR_PIN", userId, device.id);
+            throw refuse("UNAUTHORIZED", "INVALID_USER_OR_PIN", "Invalid user or PIN.");
+        }
+        // A PIN stored at another profile's parameters moves to the profile now, as a
+        // password does at sign-in. A failure leaves the stored hash; the switch stands.
+        const policy = rehashPolicyOf(input.pins.verify);
+        if (policy !== undefined && needsRehash(pinHash, policy)) {
+            try {
+                await store.rehashPin(userId, pinHash, await input.pins.hash(pin));
+            }
+            catch {
+                ctx.context.logger.error("Aventara Access: rehashing a kiosk PIN at the current profile failed; the stored hash stays until the next switch.");
+            }
+        }
+        if (deviceHeld === undefined) {
+            await store.releaseDevice(device.id);
+        }
+        await store.clearPair(device.id, userId);
+        const internal = ctx.context.internalAdapter;
+        const user = await internal.findUserById(userId);
+        if (user === null) {
+            throw refuse("UNAUTHORIZED", "INVALID_USER_OR_PIN", "Invalid user or PIN.");
+        }
+        if (ctx.context.options.emailAndPassword?.requireEmailVerification === true &&
+            user.emailVerified !== true) {
+            throw refuse("FORBIDDEN", "EMAIL_NOT_VERIFIED", "Verify your email before you sign in.");
+        }
+        // The sessions the request carried (its cookie's, a bearer's) and the ones on
+        // the device now: all ended once the new one stands.
+        const tokens = await carried(ctx);
+        const previous = tokens[0] === undefined ? null : await internal.findSession(tokens[0]);
+        // Who was on the device: the session this request brought, when it is the device's.
+        const previousUserId = boundDevice(previous?.session) === device.id
+            ? (previous?.session.userId ?? null)
+            : null;
+        const before = new Set([...tokens, ...(await store.sessionsOn(device.id))]);
+        // The new session first: one Better Auth (or the app's session hook, as the
+        // admin plugin's ban check) refuses leaves the device as it was.
+        const session = await internal.createSession(user.id, true, { kioskDeviceId: device.id, kioskSeenAt: new Date(), kioskPin: true }, true);
+        if (session === null) {
+            throw refuse("INTERNAL_SERVER_ERROR", "FAILED_TO_CREATE_SESSION", "Failed to create the session.");
+        }
+        // Then the device's credential is replaced: a copy of the old one is spent.
+        const secret = await store.rotate(device);
+        if (secret === undefined) {
+            await internal.deleteSession(session.token);
+            throw await busy(ctx, device.id);
+        }
+        setDevice(ctx, secret);
+        // The sessions before are ended, never changed into the new user's, so nothing
+        // of them (their user, their roles) carries over.
+        before.delete(session.token);
+        if (before.size > 0) {
+            await internal.deleteSessions([...before]);
+        }
+        await input.cookies.setSessionCookie(ctx, { session, user }, true);
+        if (auditLog !== undefined) {
+            const target = await signInTarget(`userId:${userId}`, ctx.context.secret);
+            if (target !== undefined) {
+                await auditLog.flushTarget(target);
+            }
+            await auditLog.record({
+                at: new Date(),
+                kind: "kiosk-switch",
+                userId: user.id,
+                previousUserId,
+                deviceId: device.id,
+                origin: originOf(ctx),
+            });
+        }
+        return ctx.json({ user: { id: user.id } });
+    };
+    const lock = async (ctx) => {
+        bodyOf(ctx, []);
+        const { store, device } = await deviceOf(ctx);
+        if (device === undefined) {
+            throw notEnrolled();
+        }
+        const internal = ctx.context.internalAdapter;
+        const tokens = await carried(ctx);
+        const current = tokens[0] === undefined ? null : await internal.findSession(tokens[0]);
+        const ending = new Set([...tokens, ...(await store.sessionsOn(device.id))]);
+        if (ending.size > 0) {
+            await internal.deleteSessions([...ending]);
+        }
+        input.cookies.deleteSessionCookie(ctx);
+        if (current !== null && boundDevice(current.session) === device.id) {
+            await auditLog?.record({
+                at: new Date(),
+                kind: "kiosk-lock",
+                userId: current.session.userId,
+                deviceId: device.id,
+                reason: "lock",
+                origin: originOf(ctx),
+            });
+        }
+        return ctx.json({ success: true });
+    };
+    /** A PIN, checked and hashed, set for `userId` (their failed PINs cleared). */
+    const storePin = async (ctx, userId, pin) => {
+        const defect = pinDefect(pin);
+        if (defect !== undefined) {
+            throw refuse("BAD_REQUEST", "PIN_TOO_WEAK", defect);
+        }
+        await storeOf(ctx.context).setPin(userId, await input.pins.hash(pin));
+        await auditLog?.record({
+            at: new Date(),
+            kind: "kiosk-pin",
+            userId,
+            origin: originOf(ctx),
+        });
+        return ctx.json({ success: true });
+    };
+    const setPin = async (ctx) => {
+        const { pin } = bodyOf(ctx, ["pin"]);
+        const found = await fullSession(ctx);
+        return await storePin(ctx, found.user.id, pin);
+    };
+    /** The app's server sets anyone's PIN: server-only, so no request reaches it. */
+    const setUserPin = async (ctx) => {
+        if (fromOutside(ctx)) {
+            throw refuse("NOT_FOUND", "NOT_FOUND", "Not found.");
+        }
+        const { userId, pin } = bodyOf(ctx, ["userId", "pin"]);
+        if (userId === "" ||
+            userId.length > ID_MAX ||
+            (await ctx.context.internalAdapter.findUserById(userId)) === null) {
+            throw refuse("NOT_FOUND", "USER_NOT_FOUND", "No such user.");
+        }
+        return await storePin(ctx, userId, pin);
+    };
+    const enrollDevice = async (ctx) => {
+        const body = bodyOf(ctx, ["name"]);
+        const name = body.name.trim();
+        if (name === "" || name.length > NAME_MAX) {
+            throw refuse("BAD_REQUEST", "INVALID_BODY", `A device's name is 1 to ${NAME_MAX} characters.`);
+        }
+        const found = await managerSession(ctx);
+        const store = storeOf(ctx.context);
+        // Enrolled already: that enrollment ends first, with any session on it.
+        const before = await store.check(ctx.getCookie(deviceCookie(ctx.context).name));
+        if (before !== undefined) {
+            await store.revoke(before.device.id);
+        }
+        const { device, secret } = await store.enroll({
+            name,
+            enrolledBy: found.user.id,
+        });
+        setDevice(ctx, secret);
+        // The enrolling session ends here: no full-credential session stays on a kiosk.
+        await ctx.context.internalAdapter.deleteSession(found.session.token);
+        input.cookies.deleteSessionCookie(ctx);
+        await auditLog?.record({
+            at: new Date(),
+            kind: "kiosk-device",
+            userId: found.user.id,
+            deviceId: device.id,
+            reason: "enrolled",
+            origin: originOf(ctx),
+        });
+        return ctx.json({ device: { id: device.id, name: device.name } });
+    };
+    /** Revokes a device for `by` (`null`: the app's server); `false` when there is none. */
+    const revoke = async (ctx, store, deviceId, by) => {
+        if (deviceId === "" || deviceId.length > ID_MAX) {
+            return false;
+        }
+        if (!(await store.revoke(deviceId))) {
+            return false;
+        }
+        await auditLog?.record({
+            at: new Date(),
+            kind: "kiosk-device",
+            userId: by,
+            deviceId,
+            reason: "revoked",
+            origin: originOf(ctx),
+        });
+        return true;
+    };
+    const revokeDevice = async (ctx) => {
+        const { deviceId } = bodyOf(ctx, ["deviceId"]);
+        const found = await managerSession(ctx);
+        if (!(await revoke(ctx, storeOf(ctx.context), deviceId, found.user.id))) {
+            throw refuse("NOT_FOUND", "KIOSK_DEVICE_NOT_FOUND", "No such device.");
+        }
+        return ctx.json({ success: true });
+    };
+    const listDevices = async (ctx) => {
+        await managerSession(ctx);
+        const devices = await storeOf(ctx.context).devices();
+        return ctx.json({
+            devices: devices.map((device) => ({
+                id: device.id,
+                name: device.name,
+                enrolledBy: device.enrolledBy,
+                enrolledAt: device.enrolledAt.toISOString(),
+                ...(device.lastSwitchAt === null
+                    ? {}
+                    : { lastSwitchAt: device.lastSwitchAt.toISOString() }),
+            })),
+        });
+    };
+    /**
+     * Before every call that carries a session (by cookie or bearer header): a
+     * device-bound session is ended unless the request brings its device's current
+     * credential and it is not idle; one that passes is marked used, and a PIN
+     * session reaches only {@link kioskSessionReaches}'s routes, whether the call came
+     * through `access.handler` or the server's own API.
+     */
+    const guard = async (ctx) => {
+        const context = ctx.context;
+        const tokens = await carried(ctx);
+        let checked;
+        const device = () => {
+            checked ??= (async () => {
+                const store = storeOf(context);
+                const found = await store.check(ctx.getCookie(deviceCookie(context).name));
+                if (found?.kind === "reused") {
+                    await reused(ctx, store, found.device.id);
+                }
+                return found;
+            })();
+            return checked;
+        };
+        for (const token of tokens) {
+            const found = await context.internalAdapter.findSession(token);
+            if (found === null) {
+                continue;
+            }
+            const deviceId = boundDevice(found.session);
+            if (deviceId === undefined) {
+                // A session bound to no device, brought with an enrolled device's
+                // credential (current, in its grace, or retired): it was opened off the
+                // device (a native app's ID-token sign-in that sent no cookie, a sign-in
+                // in the system browser handed to the app), so it never became bound, and
+                // it is no session there. Ended, as a session of another device is.
+                const check = await device();
+                if (check !== undefined) {
+                    await context.internalAdapter.deleteSession(found.session.token);
+                    await auditLog?.record({
+                        at: new Date(),
+                        kind: "kiosk-lock",
+                        userId: found.session.userId,
+                        deviceId: check.device.id,
+                        reason: "device-mismatch",
+                        origin: originOf(ctx),
+                    });
+                }
+                continue;
+            }
+            const check = await device();
+            if (check?.device.id === deviceId) {
+                if (check.kind === "stale") {
+                    throw await busy(ctx, deviceId);
+                }
+                if (check.kind === "reused") {
+                    // Revoked: every session on the device is ended already.
+                    continue;
+                }
+            }
+            const bound = check?.kind === "current" && check.device.id === deviceId;
+            const now = Date.now();
+            const seen = time(found.session.kioskSeenAt) ?? time(found.session.createdAt) ?? 0;
+            const idle = now - seen >= settings.idleTimeout * 1000;
+            if (!bound || idle) {
+                await context.internalAdapter.deleteSession(found.session.token);
+                await auditLog?.record({
+                    at: new Date(),
+                    kind: "kiosk-lock",
+                    userId: found.session.userId,
+                    deviceId,
+                    reason: bound ? "idle" : "device-mismatch",
+                    origin: originOf(ctx),
+                });
+                continue;
+            }
+            if (now - seen >= SEEN_EVERY * 1000 && usesSession(ctx)) {
+                await context.internalAdapter.updateSession(found.session.token, {
+                    kioskSeenAt: new Date(now),
+                });
+            }
+            if (found.session.kioskPin === true && !kioskSessionReaches(ctx.path)) {
+                throw refuse("FORBIDDEN", "KIOSK_SESSION_NOT_ALLOWED", "A PIN session cannot do this: sign in with your password.");
+            }
+            if (typeof ctx.path === "string" && OAUTH_GRANT_ROUTES.has(ctx.path)) {
+                throw refuse("FORBIDDEN", "KIOSK_SESSION_NOT_ALLOWED", NO_TOKEN_MESSAGE);
+            }
+            if (managesOAuth(ctx.path)) {
+                throw refuse("FORBIDDEN", "KIOSK_SESSION_NOT_ALLOWED", "A session bound to a kiosk device manages no OAuth client or consent: do it from your own browser.");
+            }
+        }
+    };
+    /**
+     * Before a call that carries an authorization request to resume (the OAuth
+     * provider's `oauth_query`): from an enrolled device (its credential, current or
+     * retired), refused, since the session it signs in or reads would be bound to the
+     * device and the provider would issue it a grant. A retired credential brought
+     * back revokes the device, as everywhere.
+     */
+    const noGrantOnDevice = async (ctx) => {
+        const store = storeOf(ctx.context);
+        const checked = await store.check(ctx.getCookie(deviceCookie(ctx.context).name));
+        if (checked === undefined) {
+            return;
+        }
+        if (checked.kind === "reused") {
+            await reused(ctx, store, checked.device.id);
+            clearDevice(ctx);
+        }
+        throw refuse("FORBIDDEN", "KIOSK_SESSION_NOT_ALLOWED", NO_TOKEN_MESSAGE);
+    };
+    /**
+     * No answer hands page code a session's token in `set-auth-token`, the header
+     * Better Auth's `bearer()` sets (refused on this profile by its id, and here under
+     * any other). The Access plugin is Better Auth's last, so this runs after every
+     * plugin's after hook.
+     */
+    const noAuthToken = async (ctx) => {
+        const headers = ctx.context.responseHeaders;
+        if (headers === undefined || !headers.has(AUTH_TOKEN_HEADER)) {
+            return;
+        }
+        headers.delete(AUTH_TOKEN_HEADER);
+        const exposed = (headers.get("access-control-expose-headers") ?? "")
+            .split(",")
+            .map((name) => name.trim())
+            .filter((name) => name !== "" && name.toLowerCase() !== AUTH_TOKEN_HEADER);
+        if (exposed.length === 0) {
+            headers.delete("access-control-expose-headers");
+        }
+        else {
+            headers.set("access-control-expose-headers", exposed.join(", "));
+        }
+    };
+    /**
+     * Whether the sign-in being handled carries an authorization request for the
+     * OAuth provider to resume once its session stands: a social sign-in begun with
+     * the login page's `oauth_query` (anywhere: the state travels with the redirect),
+     * whose callback the provider resumes from the state's `serverContext`.
+     */
+    const resumesGrant = async () => {
+        let state;
+        try {
+            state = await input.oauthState();
+        }
+        catch {
+            // No request state: no sign-in flow to resume.
+            return false;
+        }
+        return state?.serverContext?.query !== undefined;
+    };
+    /** `/get-session`'s answer for a device-bound session, without its token: page code never holds one. */
+    const withoutToken = async (ctx) => {
+        const returned = ctx.context.returned;
+        if (!isRecord(returned) ||
+            !isRecord(returned.session) ||
+            boundDevice(returned.session) === undefined) {
+            return undefined;
+        }
+        return ctx.json({
+            ...returned,
+            session: Object.fromEntries(Object.entries(returned.session).filter(([field]) => field !== "token")),
+        });
+    };
+    const route = (method, path, handler) => input.endpoint(path, { method }, handler);
+    return {
+        endpoints: {
+            kioskSwitchUser: route("POST", KIOSK_SWITCH_PATH, switchUser),
+            kioskLock: route("POST", KIOSK_LOCK_PATH, lock),
+            kioskSetPin: route("POST", KIOSK_SET_PIN_PATH, setPin),
+            kioskSetUserPin: input.serverOnly({ method: "POST" }, setUserPin),
+            kioskEnrollDevice: route("POST", KIOSK_ENROLL_PATH, enrollDevice),
+            kioskRevokeDevice: route("POST", KIOSK_REVOKE_PATH, revokeDevice),
+            kioskListDevices: route("GET", KIOSK_LIST_PATH, listDevices),
+        },
+        hooks: {
+            before: [
+                {
+                    matcher: (context) => carriesCredentials(context),
+                    handler: input.middleware(guard),
+                },
+                {
+                    matcher: resumesAuthorization,
+                    handler: input.middleware(noGrantOnDevice),
+                },
+            ],
+            after: [
+                {
+                    matcher: (context) => context?.path === "/get-session",
+                    handler: input.middleware(withoutToken),
+                },
+                {
+                    matcher: () => true,
+                    handler: input.middleware(noAuthToken),
+                },
+            ],
+        },
+        /**
+         * Before a session is created: one opened on an enrolled device (the request
+         * brings its current credential) is bound to it, whatever signed in, unless the
+         * sign-in carries an authorization request the OAuth provider would resume for
+         * it (refused: a bound session gets no grant). The credential its last rotation
+         * retired, inside the grace, is refused as every kiosk route refuses it (`409
+         * KIOSK_DEVICE_BUSY`); any other retired credential brought back revokes the
+         * device. Either way no session is created.
+         */
+        sessionCreating: async (session, context) => {
+            const ctx = context;
+            const auth = ctx?.context;
+            if (typeof session?.kioskDeviceId === "string" ||
+                typeof ctx?.getCookie !== "function" ||
+                auth?.adapter === undefined) {
+                return undefined;
+            }
+            const store = storeOf(auth);
+            const checked = await store.check(ctx.getCookie(deviceCookie(auth).name));
+            if (checked === undefined) {
+                return undefined;
+            }
+            if (checked.kind === "reused") {
+                await reused(ctx, store, checked.device.id);
+                return false;
+            }
+            if (checked.kind === "stale") {
+                throw await busy(ctx, checked.device.id);
+            }
+            if (await resumesGrant()) {
+                throw refuse("FORBIDDEN", "KIOSK_SESSION_NOT_ALLOWED", NO_TOKEN_MESSAGE);
+            }
+            return {
+                data: { kioskDeviceId: checked.device.id, kioskSeenAt: new Date() },
+            };
+        },
+        /**
+         * A session opened with full credentials (any sign-in but a PIN, and never an
+         * admin's impersonation, which proves nothing of the user) clears its user's
+         * failed PINs on every device.
+         */
+        sessionCreated: async (session, context) => {
+            const userId = session?.userId;
+            const auth = context?.context;
+            if (typeof userId !== "string" ||
+                context?.path === KIOSK_SWITCH_PATH ||
+                (typeof session?.impersonatedBy === "string" &&
+                    session.impersonatedBy !== "") ||
+                auth?.adapter === undefined) {
+                return;
+            }
+            await storeOf(auth).clearUser(userId);
+        },
+        /** `access.kiosk`, over Better Auth's context once it is built. */
+        operator: (context) => {
+            const application = {};
+            return {
+                listDevices: async () => await storeOf(await context()).devices(),
+                revokeDevice: async (deviceId) => typeof deviceId === "string" &&
+                    (await revoke(application, storeOf(await context()), deviceId, null)),
+            };
+        },
+    };
+};