@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/TlsCertificates.d.ts

@@ -0,0 +1,35 @@
+import type { TlsConfig } from "./GameServerConfig.js";
+/** A certificate and its private key, as PEM text. */
+export interface TlsMaterial {
+    /** The certificate chain (PEM). */
+    cert: string;
+    /** The private key (PEM). */
+    key: string;
+}
+/** Milliseconds between checks of the certificate files for a renewal (D9). */
+export declare const TLS_RELOAD_POLL_MS: number;
+/**
+ * The HTTPS certificate and key the server uses (D9): the PEM pair, else the files, else the development certificate
+ * made by mkcert. With UDP on, a missing mkcert is not an error: the HTTP/3 transport's own pinned development
+ * certificate then serves HTTPS too (null).
+ * @param tls The TLS settings.
+ * @param udpEnabled True when the HTTP/3 transport runs.
+ * @returns The material, or null when TLS is off or (UDP on, no mkcert) the HTTP/3 certificate serves HTTPS.
+ * @throws Error(MKCERT_MISSING_MESSAGE) when the development certificate needs mkcert and it is not installed.
+ */
+export declare function loadTlsMaterial(tls: TlsConfig, udpEnabled: boolean): Promise<TlsMaterial | null>;
+/**
+ * Polls the certificate files for a renewal every TLS_RELOAD_POLL_MS and hands changed material to a callback (D9).
+ * Only file-based TLS is watched; PEM text and the development certificate never change while running.
+ * @param tls The TLS settings.
+ * @param onChange Receives the renewed certificate and key.
+ */
+export declare function watchTlsFiles(tls: TlsConfig, onChange: (material: TlsMaterial) => void): void;
+/**
+ * Re-reads the watched certificate files now and hands them to the watcher's callback when they changed (tests and
+ * the file poll call it).
+ * @returns True when the material changed and the callback ran.
+ */
+export declare function reloadTlsNow(): Promise<boolean>;
+/** Stops polling the certificate files and forgets the callback (close). */
+export declare function stopWatchingTlsFiles(): void;

package/lib/TlsCertificates.js

@@ -0,0 +1,130 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, unwatchFile, watchFile } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { getLogger } from "./GameServerLogger.js";
+/** Milliseconds between checks of the certificate files for a renewal (D9). */
+export const TLS_RELOAD_POLL_MS = 30000;
+/** Folder under the OS temp folder the development certificate is cached in (D9). */
+const DEVELOPMENT_CERTIFICATE_FOLDER = "babylon-game-server-dev-cert";
+/** The development certificate's file name. */
+const DEVELOPMENT_CERT_FILE = "cert.pem";
+/** The development certificate's key file name. */
+const DEVELOPMENT_KEY_FILE = "key.pem";
+/** Names the development certificate is valid for. */
+const DEVELOPMENT_CERTIFICATE_NAMES = ["localhost", "127.0.0.1", "::1"];
+/** The mkcert executable. */
+const MKCERT_COMMAND = "mkcert";
+/** Error code of a command that is not installed. */
+const COMMAND_NOT_FOUND_CODE = "ENOENT";
+/** The startup error when the development certificate needs mkcert and it is missing (D9). */
+const MKCERT_MISSING_MESSAGE = "install mkcert (brew install mkcert && mkcert -install) or set tls.certFile/keyFile";
+/** Runs a command and resolves its output. */
+const runCommand = promisify(execFile);
+/** The TLS settings whose files are being watched, or null. */
+let watchedTls = null;
+/** What watchTlsFiles registered to receive renewed material, or null. */
+let reloadCallback = null;
+/** The material last loaded from the watched files. */
+let lastMaterial = null;
+/**
+ * The HTTPS certificate and key the server uses (D9): the PEM pair, else the files, else the development certificate
+ * made by mkcert. With UDP on, a missing mkcert is not an error: the HTTP/3 transport's own pinned development
+ * certificate then serves HTTPS too (null).
+ * @param tls The TLS settings.
+ * @param udpEnabled True when the HTTP/3 transport runs.
+ * @returns The material, or null when TLS is off or (UDP on, no mkcert) the HTTP/3 certificate serves HTTPS.
+ * @throws Error(MKCERT_MISSING_MESSAGE) when the development certificate needs mkcert and it is not installed.
+ */
+export async function loadTlsMaterial(tls, udpEnabled) {
+    if (!tls.enabled)
+        return null;
+    if (tls.certPem != null && tls.keyPem != null)
+        return { cert: tls.certPem, key: tls.keyPem };
+    if (tls.certFile != null && tls.keyFile != null)
+        return { cert: await readFile(tls.certFile, "utf8"), key: await readFile(tls.keyFile, "utf8") };
+    if (!tls.developmentCertificate)
+        return null;
+    try {
+        return await loadDevelopmentCertificate();
+    }
+    catch (error) {
+        const mkcertMissing = error.code === COMMAND_NOT_FOUND_CODE;
+        if (mkcertMissing && udpEnabled)
+            return null;
+        if (mkcertMissing)
+            throw new Error(MKCERT_MISSING_MESSAGE);
+        throw error;
+    }
+}
+/**
+ * Polls the certificate files for a renewal every TLS_RELOAD_POLL_MS and hands changed material to a callback (D9).
+ * Only file-based TLS is watched; PEM text and the development certificate never change while running.
+ * @param tls The TLS settings.
+ * @param onChange Receives the renewed certificate and key.
+ */
+export function watchTlsFiles(tls, onChange) {
+    stopWatchingTlsFiles();
+    if (!tls.enabled || tls.certFile == null || tls.keyFile == null)
+        return;
+    watchedTls = tls;
+    reloadCallback = onChange;
+    lastMaterial = { cert: readFileSync(tls.certFile, "utf8"), key: readFileSync(tls.keyFile, "utf8") };
+    for (const filePath of [tls.certFile, tls.keyFile])
+        watchFile(filePath, { interval: TLS_RELOAD_POLL_MS }, reloadAfterFileChange);
+}
+/**
+ * Re-reads the watched certificate files now and hands them to the watcher's callback when they changed (tests and
+ * the file poll call it).
+ * @returns True when the material changed and the callback ran.
+ */
+export async function reloadTlsNow() {
+    if (watchedTls == null || reloadCallback == null)
+        return false;
+    const material = await loadTlsMaterial(watchedTls, false);
+    if (material == null || isSameMaterial(material, lastMaterial))
+        return false;
+    lastMaterial = material;
+    reloadCallback(material);
+    return true;
+}
+/** Stops polling the certificate files and forgets the callback (close). */
+export function stopWatchingTlsFiles() {
+    if (watchedTls != null && watchedTls.certFile != null && watchedTls.keyFile != null) {
+        unwatchFile(watchedTls.certFile, reloadAfterFileChange);
+        unwatchFile(watchedTls.keyFile, reloadAfterFileChange);
+    }
+    watchedTls = null;
+    reloadCallback = null;
+    lastMaterial = null;
+}
+/** The file poll's listener: reloads, logging a failure (a half-written renewal is retried at the next poll). */
+function reloadAfterFileChange() {
+    reloadTlsNow().catch((error) => getLogger().warn("certificate reload failed", { error: String(error) }));
+}
+/**
+ * Whether two certificate/key pairs are the same text.
+ * @param material The new pair.
+ * @param previous The previous pair, or null.
+ * @returns True when both the certificate and the key are unchanged.
+ */
+function isSameMaterial(material, previous) {
+    return previous != null && material.cert === previous.cert && material.key === previous.key;
+}
+/**
+ * The mkcert development certificate for localhost, made once into the OS temp folder and reused while both files exist.
+ * @returns The material.
+ * @throws The mkcert error (code ENOENT when mkcert is not installed).
+ */
+async function loadDevelopmentCertificate() {
+    const folder = join(tmpdir(), DEVELOPMENT_CERTIFICATE_FOLDER);
+    const certPath = join(folder, DEVELOPMENT_CERT_FILE);
+    const keyPath = join(folder, DEVELOPMENT_KEY_FILE);
+    if (!existsSync(certPath) || !existsSync(keyPath)) {
+        mkdirSync(folder, { recursive: true });
+        await runCommand(MKCERT_COMMAND, ["-cert-file", certPath, "-key-file", keyPath].concat(DEVELOPMENT_CERTIFICATE_NAMES));
+    }
+    return { cert: await readFile(certPath, "utf8"), key: await readFile(keyPath, "utf8") };
+}

package/lib/admin/AccountRoutes.d.ts

@@ -0,0 +1,8 @@
+import { type AdminApiRouter } from "./AdminApiRouter.js";
+import type { AdminServices } from "./AdminServices.js";
+/**
+ * Registers every auth/*, setup/* and account/* route, passkeys (D31) and single sign-on (D26) included.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export declare function registerAccountRoutes(router: AdminApiRouter, services: AdminServices): void;

package/lib/admin/AccountRoutes.js

@@ -0,0 +1,502 @@
+// The sign-in, setup and account routes of the admin API (game-server-admin-console DR §6.11 auth/*, setup/*,
+// account/* rows; D8, D10, D30). None of them may be called with an API key (R8).
+import { CONSOLE_BASE_PATH } from "./AdminConstants.js";
+import { getLogger } from "../GameServerLogger.js";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { ROLE_PERMISSIONS } from "./AdminPermissions.js";
+import { bodyObject, optionalStringField, stringField } from "./AdminRequestBodies.js";
+import { buildClearingCookie, buildSessionCookie } from "./AdminResponses.js";
+import { colyseusCloudFeatureOf } from "./ColyseusCloudSettings.js";
+/** HTTP status of a successful answer. */
+const HTTP_OK = 200;
+/** HTTP status of a refused request body. */
+const HTTP_BAD_REQUEST = 400;
+/** HTTP status of a caller without a session. */
+const HTTP_UNAUTHORIZED = 401;
+/** HTTP status of a refused sign-in method. */
+const HTTP_FORBIDDEN = 403;
+/** HTTP status of a missing account or session. */
+const HTTP_NOT_FOUND = 404;
+/** The console page a finished single sign-on lands on. */
+const SIGNED_IN_PAGE = CONSOLE_BASE_PATH + "#/";
+/** The console sign-in page a single sign-on hands a second factor or a refusal to. */
+const SIGN_IN_PAGE = CONSOLE_BASE_PATH + "#/sign-in";
+/** The answer of an action with nothing else to say. */
+const OK_BODY = { ok: true };
+/** Allowed console themes. */
+const THEMES = new Set(["system", "light", "dark"]);
+/** Allowed console time zones. */
+const TIME_ZONES = new Set(["local", "utc"]);
+/**
+ * Registers every auth/*, setup/* and account/* route, passkeys (D31) and single sign-on (D26) included.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerAccountRoutes(router, services) {
+    const routes = [
+        publicRoute("GET", "auth/methods", null, async () => ok(await signInMethods(services))),
+        publicRoute("POST", "setup/owner", "setup.owner", async (request) => createOwner(services, request)),
+        publicRoute("POST", "auth/sign-in", "auth.signIn", async (request) => ok(await beginSignIn(services, request))),
+        publicRoute("POST", "auth/enrol", null, async (request) => ok(await beginEnrolment(services, request))),
+        publicRoute("POST", "auth/enrol/confirm", "auth.enrol", async (request) => confirmEnrolment(services, request)),
+        publicRoute("POST", "auth/second-factor", "auth.secondFactor", async (request) => completeSecondFactor(services, request)),
+        signedInRoute("GET", "auth/session", false, null, async (request) => ok(await sessionView(services, requireSession(request)))),
+        signedInRoute("POST", "auth/step-up", false, "auth.stepUp", async (request) => stepUp(services, request)),
+        signedInRoute("POST", "auth/sign-out", false, "auth.signOut", async (request) => signOut(services, request, false)),
+        signedInRoute("POST", "auth/sign-out-everywhere", false, "auth.signOutEverywhere", async (request) => signOut(services, request, true)),
+        signedInRoute("GET", "account/sessions", false, null, async (request) => ok(await accountSessions(services, request))),
+        signedInRoute("DELETE", "account/sessions/:sessionId", false, "account.endSession", async (request) => endAccountSession(services, request)),
+        signedInRoute("PUT", "account/password", true, "account.password", async (request) => changePassword(services, request)),
+        signedInRoute("POST", "account/recovery-codes", true, "account.recoveryCodes", async (request) => ok({ recoveryCodes: await services.accounts.regenerateRecoveryCodes(requireSession(request).user.userId) })),
+        signedInRoute("PUT", "account/preferences", false, null, async (request) => updatePreferences(services, request)),
+        publicRoute("POST", "auth/passkey/options", null, async (request) => ok(await passkeyRequestOptions(services, request))),
+        publicRoute("POST", "auth/passkey/verify", "auth.passkey", async (request) => verifyPasskey(services, request)),
+        signedInRoute("POST", "account/passkeys/options", true, null, async (request) => ok(await services.passkeys.creationOptions(requirePasskeys(services, request).user, request.consoleOrigin))),
+        signedInRoute("POST", "account/passkeys", true, "account.passkeyAdd", async (request) => addPasskey(services, request)),
+        signedInRoute("GET", "account/passkeys", false, null, async (request) => ok(await services.passkeys.list(requireSession(request).user.userId))),
+        signedInRoute("DELETE", "account/passkeys/:passkeyId", true, "account.passkeyRemove", async (request) => removePasskey(services, request)),
+        publicRoute("GET", "auth/oidc/start", null, async (request) => startSingleSignOn(services, request)),
+        publicRoute("GET", "auth/oidc/callback", "auth.oidc", async (request) => finishSingleSignOn(services, request))
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * A route anyone may call (sign-in steps, setup).
+ * @param method The HTTP method.
+ * @param pattern The pattern.
+ * @param auditAction The audit action, or null.
+ * @param handler The handler.
+ * @returns The route.
+ */
+function publicRoute(method, pattern, auditAction, handler) {
+    return { method: method, pattern: pattern, permission: "public", requiresStepUp: false, auditAction: auditAction, allowsApiKeys: false, handler: handler };
+}
+/**
+ * A route of the signed-in admin's own account.
+ * @param method The HTTP method.
+ * @param pattern The pattern.
+ * @param requiresStepUp True for dangerous changes.
+ * @param auditAction The audit action, or null.
+ * @param handler The handler.
+ * @returns The route.
+ */
+function signedInRoute(method, pattern, requiresStepUp, auditAction, handler) {
+    return { method: method, pattern: pattern, permission: "signedIn", requiresStepUp: requiresStepUp, auditAction: auditAction, allowsApiKeys: false, handler: handler };
+}
+/**
+ * A 200 answer.
+ * @param body The JSON body.
+ * @returns The result.
+ */
+function ok(body) {
+    return { status: HTTP_OK, body: body };
+}
+/**
+ * What the sign-in page offers. A process's own setup link stays pending after another process created the first owner,
+ * so the store decides whether setup is still needed.
+ * @param services The shared services.
+ * @returns The methods.
+ */
+async function signInMethods(services) {
+    const oidc = services.openId.isEnabled ? { label: services.openId.label } : null;
+    const needsSetup = services.accounts.hasPendingSetup() && !await services.accounts.hasUsers();
+    return { local: isLocalSignInAllowed(services), oidc: oidc, passkeys: services.passkeys.isEnabled, needsSetup: needsSetup };
+}
+/**
+ * Whether username and password sign-in is offered: always, unless single sign-on is on with allowLocalSignIn false
+ * (the CLI stays the recovery path).
+ * @param services The shared services.
+ * @returns True when local sign-in is allowed.
+ */
+function isLocalSignInAllowed(services) {
+    return !(services.openId.isEnabled && !services.config.admin.oidc.allowLocalSignIn);
+}
+/**
+ * POST setup/owner: audited as the new owner, the account the request created.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The owner's enrolment step.
+ */
+async function createOwner(services, request) {
+    const body = bodyObject(request.body);
+    const username = stringField(body, "username");
+    const step = await services.accounts.createOwnerFromSetup({
+        setupToken: stringField(body, "setupToken"),
+        username: username,
+        displayName: optionalStringField(body, "displayName") ?? "",
+        password: stringField(body, "password")
+    });
+    const owner = await services.accounts.findByUsername(username);
+    const audit = (owner != null) ? { target: owner.value.username, parameters: {}, actor: userActorOf(owner.value) } : undefined;
+    return { status: HTTP_OK, body: step, audit: audit };
+}
+/**
+ * POST auth/sign-in.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The next step.
+ */
+function beginSignIn(services, request) {
+    if (!isLocalSignInAllowed(services))
+        throw new AdminRequestError(HTTP_FORBIDDEN, "sign in with single sign-on");
+    const body = bodyObject(request.body);
+    return services.accounts.beginSignIn({ username: stringField(body, "username"), password: stringField(body, "password") }, signInContextOf(request));
+}
+/**
+ * POST auth/enrol.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The secret to enrol.
+ */
+function beginEnrolment(services, request) {
+    return services.accounts.beginEnrolment(stringField(bodyObject(request.body), "pendingToken"));
+}
+/**
+ * POST auth/enrol/confirm.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The signed-in answer with the session cookie.
+ */
+async function confirmEnrolment(services, request) {
+    const body = bodyObject(request.body);
+    const result = await services.accounts.completeEnrolment(stringField(body, "pendingToken"), stringField(body, "code"), signInContextOf(request));
+    return signedInResult(services, request, result);
+}
+/**
+ * POST auth/second-factor.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The signed-in answer with the session cookie.
+ */
+async function completeSecondFactor(services, request) {
+    const body = bodyObject(request.body);
+    const pendingToken = stringField(body, "pendingToken");
+    const result = await services.accounts.completeSecondFactor(pendingToken, secondFactorProofOf(body), signInContextOf(request));
+    return signedInResult(services, request, result);
+}
+/**
+ * POST auth/step-up.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The session with its fresh secondFactorAt.
+ */
+async function stepUp(services, request) {
+    const caller = requireCaller(request);
+    const session = await services.accounts.stepUp(caller, secondFactorProofOf(bodyObject(request.body)));
+    const user = requireSession(request).user;
+    return ok(await sessionView(services, { session: session, user: user }));
+}
+/**
+ * POST auth/sign-out and auth/sign-out-everywhere.
+ * @param services The shared services.
+ * @param request The request.
+ * @param everywhere True to end every session of the account.
+ * @returns ok with a clearing cookie.
+ */
+async function signOut(services, request, everywhere) {
+    const signedIn = requireSession(request);
+    if (everywhere)
+        await services.sessions.endAllFor(signedIn.user.userId);
+    else
+        await services.sessions.end(signedIn.session.sessionId);
+    return { status: HTTP_OK, body: OK_BODY, setCookies: [buildClearingCookie(request.isSecure)], audit: { target: signedIn.user.username, parameters: {} } };
+}
+/**
+ * GET account/sessions.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The caller's sessions.
+ */
+async function accountSessions(services, request) {
+    const signedIn = requireSession(request);
+    const sessions = await services.sessions.listFor(signedIn.user.userId);
+    return sessions.map((record) => ({
+        sessionId: record.sessionId,
+        createdAt: record.createdAt,
+        lastSeenAt: record.lastSeenAt,
+        clientAddress: record.clientAddress,
+        userAgent: record.userAgent,
+        current: record.sessionId === signedIn.session.sessionId
+    }));
+}
+/**
+ * DELETE account/sessions/:sessionId.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ * @throws AdminRequestError 404 when the session is not the caller's.
+ */
+async function endAccountSession(services, request) {
+    const signedIn = requireSession(request);
+    const sessionId = request.params.sessionId;
+    const owned = await services.sessions.listFor(signedIn.user.userId);
+    if (!owned.some((record) => record.sessionId === sessionId))
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no such session");
+    await services.sessions.end(sessionId);
+    return { status: HTTP_OK, body: OK_BODY, audit: { target: sessionId, parameters: {} } };
+}
+/**
+ * PUT account/password.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ */
+async function changePassword(services, request) {
+    const body = bodyObject(request.body);
+    const user = requireSession(request).user;
+    await services.accounts.changePassword(user.userId, stringField(body, "currentPassword"), stringField(body, "newPassword"));
+    return { status: HTTP_OK, body: OK_BODY, audit: { target: user.username, parameters: {} } };
+}
+/**
+ * PUT account/preferences.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The updated account view.
+ * @throws AdminRequestError 400 for an unknown theme or time zone.
+ */
+async function updatePreferences(services, request) {
+    const body = bodyObject(request.body);
+    const theme = stringField(body, "theme");
+    const timeZone = stringField(body, "timeZone");
+    if (!THEMES.has(theme) || !TIME_ZONES.has(timeZone))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "theme must be system, light or dark and timeZone local or utc");
+    const preferences = { theme: theme, timeZone: timeZone };
+    const stored = await services.accounts.updatePreferences(requireSession(request).user.userId, preferences);
+    return ok(services.accounts.toUserView(stored));
+}
+/**
+ * The answer of a finished sign-in: the SignedInView, the session cookie and the audit target.
+ * @param services The shared services.
+ * @param request The request.
+ * @param result The sign-in.
+ * @returns The result.
+ */
+async function signedInResult(services, request, result) {
+    const view = { session: await sessionView(services, { session: result.session, user: result.user }), recoveryCodes: result.recoveryCodes };
+    const cookie = buildSessionCookie(result.cookieValue, request.isSecure, services.sessions.cookieMaxAgeSeconds);
+    return { status: HTTP_OK, body: view, setCookies: [cookie], audit: { target: result.user.username, parameters: {}, actor: userActorOf(result.user) } };
+}
+/**
+ * The audit actor of an account that just signed in or was just created on a public route.
+ * @param user The account.
+ * @returns The actor.
+ */
+function userActorOf(user) {
+    return { kind: "user", id: user.userId, name: user.displayName };
+}
+/**
+ * The ConsoleSessionView of a session.
+ * @param services The shared services.
+ * @param signedIn The session and its account.
+ * @returns The view.
+ */
+async function sessionView(services, signedIn) {
+    const stored = await services.accounts.getUser(signedIn.user.userId);
+    if (stored == null)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no such admin user");
+    return {
+        user: services.accounts.toUserView(stored),
+        permissions: Array.from(ROLE_PERMISSIONS[stored.value.role]),
+        csrfToken: signedIn.session.csrfToken,
+        secondFactorAt: signedIn.session.secondFactorAt,
+        expiresAt: services.sessions.expiresAt(signedIn.session),
+        features: { colyseusCloud: colyseusCloudFeatureOf(services.config, process.env) }
+    };
+}
+/**
+ * The second factor of a body: a code or a recovery code.
+ * @param body The body object.
+ * @returns The proof.
+ * @throws AdminRequestError 400 when neither is given.
+ */
+function secondFactorProofOf(body) {
+    const code = optionalStringField(body, "code");
+    if (code != null)
+        return { code: code };
+    const recoveryCode = optionalStringField(body, "recoveryCode");
+    if (recoveryCode != null)
+        return { recoveryCode: recoveryCode };
+    throw new AdminRequestError(HTTP_BAD_REQUEST, "send a code or a recovery code");
+}
+/**
+ * Where a sign-in comes from.
+ * @param request The request.
+ * @returns The address and user agent.
+ */
+function signInContextOf(request) {
+    return { clientAddress: request.clientAddress, userAgent: request.headers.get("user-agent") ?? "" };
+}
+/**
+ * The caller of a signedIn route.
+ * @param request The request.
+ * @returns The caller.
+ * @throws AdminRequestError 401 without one (the router already refuses that).
+ */
+function requireCaller(request) {
+    if (request.caller == null)
+        throw new AdminRequestError(HTTP_UNAUTHORIZED, "sign in first");
+    return request.caller;
+}
+/**
+ * The console session and account of a signedIn route's caller.
+ * @param request The request.
+ * @returns The session and the account.
+ * @throws AdminRequestError 401 for a caller without a session.
+ */
+function requireSession(request) {
+    const caller = requireCaller(request);
+    if (caller.session == null || caller.user == null)
+        throw new AdminRequestError(HTTP_UNAUTHORIZED, "sign in first");
+    return { session: caller.session, user: caller.user };
+}
+/**
+ * The signed-in account of a passkey route, when passkeys are on.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The session and the account.
+ * @throws AdminRequestError 404 while passkeys are off.
+ */
+function requirePasskeys(services, request) {
+    if (!services.passkeys.isEnabled)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "passkeys are off");
+    return requireSession(request);
+}
+/**
+ * POST auth/passkey/options.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The options of navigator.credentials.get.
+ * @throws AdminRequestError 404 while passkeys are off.
+ */
+async function passkeyRequestOptions(services, request) {
+    if (!services.passkeys.isEnabled)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "passkeys are off");
+    return services.passkeys.requestOptions(optionalStringField(bodyObject(request.body), "username"), request.consoleOrigin);
+}
+/**
+ * POST auth/passkey/verify: a passkey as the second factor of a password sign-in (with its pendingToken), or a
+ * password-less sign-in when the authenticator verified the user (D31).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The signed-in answer with the session cookie.
+ * @throws AdminRequestError 404 while passkeys are off, 401 for a refused passkey or a password-less sign-in without
+ *     user verification.
+ */
+async function verifyPasskey(services, request) {
+    if (!services.passkeys.isEnabled)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "passkeys are off");
+    const body = bodyObject(request.body);
+    const pendingToken = optionalStringField(body, "pendingToken");
+    const verified = await services.passkeys.verifyAssertion(assertionOf(body.credential), request.consoleOrigin);
+    if (pendingToken != null)
+        return signedInResult(services, request, await services.accounts.completeSecondFactorWithPasskey(pendingToken, verified.user.userId, signInContextOf(request)));
+    if (!verified.userVerified)
+        throw new AdminRequestError(HTTP_UNAUTHORIZED, "this passkey did not verify you; sign in with your password first");
+    return signedInResult(services, request, await services.accounts.signInVerified(verified.user.userId, signInContextOf(request)));
+}
+/**
+ * POST account/passkeys: registers a passkey for the signed-in admin.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The passkey.
+ */
+async function addPasskey(services, request) {
+    const signedIn = requirePasskeys(services, request);
+    const body = bodyObject(request.body);
+    const name = optionalStringField(body, "name") ?? "";
+    const record = await services.passkeys.register(signedIn.user, name, attestationOf(body.credential), request.consoleOrigin);
+    const view = { passkeyId: record.passkeyId, name: record.name, createdAt: record.createdAt, lastUsedAt: record.lastUsedAt };
+    return { status: HTTP_OK, body: view, audit: { target: signedIn.user.username, parameters: { passkeyId: record.passkeyId, name: record.name } } };
+}
+/**
+ * DELETE account/passkeys/:passkeyId.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ */
+async function removePasskey(services, request) {
+    const signedIn = requireSession(request);
+    const passkeyId = request.params.passkeyId;
+    await services.passkeys.remove(signedIn.user.userId, passkeyId);
+    return { status: HTTP_OK, body: OK_BODY, audit: { target: signedIn.user.username, parameters: { passkeyId: passkeyId } } };
+}
+/**
+ * GET auth/oidc/start: a redirect to the provider (or back to the sign-in page when it cannot be reached).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The redirect.
+ * @throws AdminRequestError 404 while single sign-on is off.
+ */
+async function startSingleSignOn(services, request) {
+    if (!services.openId.isEnabled)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "single sign-on is off");
+    try {
+        const start = await services.openId.startUrl(request.consoleOrigin);
+        return { status: HTTP_OK, body: null, redirectTo: start.location };
+    }
+    catch (error) {
+        getLogger().warn("the OpenID provider could not be reached", { error: String(error) });
+        return { status: HTTP_OK, body: null, redirectTo: SIGN_IN_PAGE + "?error=sign-in-failed" };
+    }
+}
+/**
+ * GET auth/oidc/callback (DR §7.10): signs in (cookie, then the console), hands a second factor to the sign-in page,
+ * or sends a refusal reason there. A refusal is audited as a failure.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The redirect.
+ * @throws AdminRequestError 404 while single sign-on is off.
+ */
+async function finishSingleSignOn(services, request) {
+    if (!services.openId.isEnabled)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "single sign-on is off");
+    const outcome = await services.openId.complete(request.query);
+    if (outcome.kind === "refused") {
+        return { status: HTTP_FORBIDDEN, body: { error: "single sign-on refused", detail: outcome.reason }, redirectTo: SIGN_IN_PAGE + "?error=" + outcome.reason };
+    }
+    if (outcome.kind === "needsSecondFactor") {
+        const location = SIGN_IN_PAGE + "?second-factor=" + encodeURIComponent(outcome.pendingToken) + "&stage=" + outcome.stage;
+        return { status: HTTP_OK, body: null, redirectTo: location, audit: { target: outcome.user.username, parameters: { secondFactor: "asked", note: outcome.note } } };
+    }
+    const result = await services.accounts.signInVerified(outcome.user.userId, signInContextOf(request));
+    const cookie = buildSessionCookie(result.cookieValue, request.isSecure, services.sessions.cookieMaxAgeSeconds);
+    return { status: HTTP_OK, body: null, redirectTo: SIGNED_IN_PAGE, setCookies: [cookie], audit: { target: result.user.username, parameters: { secondFactor: "provider", note: outcome.note }, actor: userActorOf(result.user) } };
+}
+/**
+ * A navigator.credentials.get result from a request body.
+ * @param value body.credential.
+ * @returns The assertion.
+ * @throws AdminRequestError 400 when a field is missing.
+ */
+function assertionOf(value) {
+    const credential = bodyObject(value);
+    const response = bodyObject(credential.response);
+    return {
+        id: stringField(credential, "id"),
+        rawId: stringField(credential, "rawId"),
+        type: "public-key",
+        response: {
+            clientDataJSON: stringField(response, "clientDataJSON"),
+            authenticatorData: stringField(response, "authenticatorData"),
+            signature: stringField(response, "signature"),
+            userHandle: optionalStringField(response, "userHandle")
+        }
+    };
+}
+/**
+ * A navigator.credentials.create result from a request body.
+ * @param value body.credential.
+ * @returns The attestation.
+ * @throws AdminRequestError 400 when a field is missing.
+ */
+function attestationOf(value) {
+    const credential = bodyObject(value);
+    const response = bodyObject(credential.response);
+    return {
+        id: stringField(credential, "id"),
+        rawId: stringField(credential, "rawId"),
+        type: "public-key",
+        response: { clientDataJSON: stringField(response, "clientDataJSON"), attestationObject: stringField(response, "attestationObject") }
+    };
+}