@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/MetricsSampler.js

@@ -0,0 +1,211 @@
+// The metrics history of one instance (game-server-admin-console D22, DR §6.7): one MetricsSample every
+// metricsSampleIntervalMs into an in-memory ring of admin.metricsHistoryHours, and with Redis also into the store stream
+// metrics:<processId>, so the fleet's charts survive page reloads and an instance's restart.
+import { monitorEventLoopDelay } from "node:perf_hooks";
+import { getLogger } from "../GameServerLogger.js";
+import { EVENT_LOOP_MONITOR_RESOLUTION_MS, METRICS_SAMPLES_PER_HOUR } from "./AdminConstants.js";
+/** Counter values of a sample when metrics are off (D22: process and room figures only). */
+const EMPTY_COUNTERS = {
+    joinsAccepted: 0,
+    joinsRefused: 0,
+    refusalsByReason: {},
+    authFailures: 0,
+    framesIn: 0,
+    framesOut: 0,
+    bytesIn: 0,
+    bytesOut: 0,
+    framesByTransport: { websocket: 0, webtransport: 0 },
+    messagesIn: 0,
+    messagesOut: 0,
+    dedicatedTickOverruns: 0,
+    dedicatedFrameSecondsSum: 0,
+    dedicatedFrameCount: 0,
+    cpuSecondsTotal: 0,
+    residentMemoryBytes: 0,
+    heapUsedBytes: 0,
+    gcSecondsTotal: 0,
+    leaderboardScoresAccepted: 0,
+    leaderboardScoresRefused: 0
+};
+/** Least time between two "metrics sample failed" warnings, in milliseconds. */
+const SAMPLE_WARNING_INTERVAL_MS = 60000;
+/** Microseconds per second (process.cpuUsage reports microseconds). */
+const MICROSECONDS_PER_SECOND = 1e6;
+/** Nanoseconds per millisecond (the event-loop histogram reports nanoseconds). */
+const NANOSECONDS_PER_MILLISECOND = 1e6;
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/**
+ * The sampler reads counters at most this fraction of its interval old, so each sample sees fresh counters while the
+ * heartbeats reuse the sampler's snapshot (R22).
+ */
+const SNAPSHOT_AGE_FRACTION = 0.5;
+/**
+ * The store stream of an instance's samples.
+ * @param processId The instance.
+ * @returns The stream name.
+ */
+export function metricsStreamOf(processId) {
+    return `metrics:${processId}`;
+}
+/** Takes this instance's samples while the console runs. */
+export class MetricsSampler {
+    /** The shared core services. */
+    services;
+    /** The samples, oldest first. */
+    ring = [];
+    /** How many samples the ring and the store stream keep. */
+    capacity;
+    /** The sampler's own event-loop delay histogram, so Prometheus' windows are untouched (D22). */
+    eventLoopMonitor = null;
+    /** The sample timer, while started. */
+    sampleTimer = null;
+    /** True while a sample is being taken, so a slow store never stacks them. */
+    isSampling = false;
+    /** The counters of the previous sample, for the dedicated frame mean between samples. */
+    previousCounters = null;
+    /** Clock time of the last "metrics sample failed" warning. */
+    lastSampleWarningAt = Number.NEGATIVE_INFINITY;
+    /**
+     * Prepares an empty history; nothing is sampled until start().
+     * @param services The shared core services.
+     */
+    constructor(services) {
+        this.services = services;
+        this.capacity = Math.max(1, Math.round(services.config.admin.metricsHistoryHours * METRICS_SAMPLES_PER_HOUR));
+    }
+    /** Starts sampling every metricsSampleIntervalMs. */
+    start() {
+        this.eventLoopMonitor = monitorEventLoopDelay({ resolution: EVENT_LOOP_MONITOR_RESOLUTION_MS });
+        this.eventLoopMonitor.enable();
+        this.sampleTimer = this.services.clock.setInterval(() => void this.takeSample(), this.services.metricsSampleIntervalMs);
+    }
+    /** Stops sampling; the history taken so far stays readable. */
+    stop() {
+        if (this.sampleTimer != null)
+            this.services.clock.clearInterval(this.sampleTimer);
+        this.sampleTimer = null;
+        this.eventLoopMonitor?.disable();
+        this.eventLoopMonitor = null;
+    }
+    /**
+     * This instance's samples of a recent period, from the in-memory ring.
+     * @param rangeMilliseconds How far back, in milliseconds.
+     * @returns The samples, oldest first.
+     */
+    samples(rangeMilliseconds) {
+        const cutoff = this.services.clock.now() - rangeMilliseconds;
+        return this.ring.filter((sample) => Date.parse(sample.at) >= cutoff);
+    }
+    /** Takes one sample into the ring and, with Redis, into the store stream; a failure is logged. */
+    async takeSample() {
+        if (this.isSampling)
+            return;
+        this.isSampling = true;
+        try {
+            const sample = await this.buildSample();
+            this.ring.push(sample);
+            if (this.ring.length > this.capacity)
+                this.ring.splice(0, this.ring.length - this.capacity);
+            if (this.services.store.kind === "redis")
+                await this.storeSample(sample);
+        }
+        catch (error) {
+            this.warnSampleFailure(error);
+        }
+        finally {
+            this.isSampling = false;
+        }
+    }
+    /**
+     * Appends a sample to this instance's store stream and trims it to the ring's capacity.
+     * @param sample The sample.
+     */
+    async storeSample(sample) {
+        const stream = metricsStreamOf(this.services.processId());
+        await this.services.store.appendRecord(stream, sample);
+        await this.services.store.trimRecordsToCount(stream, this.capacity);
+    }
+    /**
+     * This instance's figures now (DR §6.7).
+     * @returns The sample.
+     */
+    async buildSample() {
+        const counters = await this.readCounters();
+        const rooms = Array.from(this.services.state.sessionRooms);
+        const memory = process.memoryUsage();
+        const cpu = process.cpuUsage();
+        const sample = {
+            at: new Date(this.services.clock.now()).toISOString(),
+            players: rooms.reduce((total, room) => total + room.playerCount, 0),
+            sessions: rooms.length,
+            dedicatedSessions: rooms.filter((room) => room.isDedicated).length,
+            joinsAccepted: counters.joinsAccepted,
+            joinsRefused: counters.joinsRefused,
+            refusalsByReason: Object.assign({}, counters.refusalsByReason),
+            authFailures: counters.authFailures,
+            framesIn: counters.framesIn,
+            framesOut: counters.framesOut,
+            bytesIn: counters.bytesIn,
+            bytesOut: counters.bytesOut,
+            framesByTransport: Object.assign({}, counters.framesByTransport),
+            messagesIn: counters.messagesIn,
+            cpuSecondsTotal: (cpu.user + cpu.system) / MICROSECONDS_PER_SECOND,
+            residentMemoryBytes: memory.rss,
+            heapUsedBytes: memory.heapUsed,
+            eventLoopLagMilliseconds: this.sampleEventLoopLag(),
+            gcSecondsTotal: counters.gcSecondsTotal,
+            dedicatedFrameMillisecondsAverage: this.dedicatedFrameAverage(counters),
+            dedicatedTickOverruns: counters.dedicatedTickOverruns,
+            leaderboardScoresAccepted: counters.leaderboardScoresAccepted,
+            leaderboardScoresRefused: counters.leaderboardScoresRefused
+        };
+        this.previousCounters = counters;
+        return sample;
+    }
+    /**
+     * The metrics counters, read fresh for this sample (R22), or zeros when metrics are off.
+     * @returns The counters.
+     */
+    async readCounters() {
+        const metrics = this.services.routeContext.metrics();
+        if (metrics == null)
+            return EMPTY_COUNTERS;
+        return metrics.snapshot(this.services.metricsSampleIntervalMs * SNAPSHOT_AGE_FRACTION);
+    }
+    /**
+     * The mean dedicated frame time since the previous sample.
+     * @param counters The counters now.
+     * @returns The mean, in milliseconds (0 when no dedicated frame ran).
+     */
+    dedicatedFrameAverage(counters) {
+        const previousSum = this.previousCounters?.dedicatedFrameSecondsSum ?? 0;
+        const previousCount = this.previousCounters?.dedicatedFrameCount ?? 0;
+        const frameCount = counters.dedicatedFrameCount - previousCount;
+        if (frameCount <= 0)
+            return 0;
+        return ((counters.dedicatedFrameSecondsSum - previousSum) / frameCount) * MILLISECONDS_PER_SECOND;
+    }
+    /**
+     * The mean event-loop delay since the previous sample; the histogram restarts afterwards.
+     * @returns The delay, in milliseconds (0 before any measurement).
+     */
+    sampleEventLoopLag() {
+        if (this.eventLoopMonitor == null)
+            return 0;
+        const meanNanoseconds = this.eventLoopMonitor.mean;
+        this.eventLoopMonitor.reset();
+        return Number.isFinite(meanNanoseconds) ? meanNanoseconds / NANOSECONDS_PER_MILLISECOND : 0;
+    }
+    /**
+     * Logs a failed sample at warn, at most once per SAMPLE_WARNING_INTERVAL_MS.
+     * @param error What failed.
+     */
+    warnSampleFailure(error) {
+        const now = this.services.clock.now();
+        if (now - this.lastSampleWarningAt < SAMPLE_WARNING_INTERVAL_MS)
+            return;
+        this.lastSampleWarningAt = now;
+        getLogger().warn("a metrics sample failed", { error: String(error) });
+    }
+}

package/lib/admin/OneTimeCodes.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Encodes bytes as base32 without padding.
+ * @param bytes The bytes.
+ * @returns The base32 text (upper case).
+ */
+export declare function encodeBase32(bytes: Uint8Array): string;
+/**
+ * Decodes base32 (any case, padding and spaces ignored).
+ * @param text The base32 text.
+ * @returns The bytes.
+ * @throws Error on a character outside the alphabet.
+ */
+export declare function decodeBase32(text: string): Buffer;
+/**
+ * A new random TOTP secret (TOTP_SECRET_BYTES bytes).
+ * @returns The secret in base32.
+ */
+export declare function generateTotpSecret(): string;
+/**
+ * Computes the 6-digit TOTP code of a counter (a 30-second step since the Unix epoch).
+ * @param secretBase32 The shared secret in RFC 4648 base32.
+ * @param counter The time step number.
+ * @returns The zero-padded 6-digit code.
+ */
+export declare function totpCodeAt(secretBase32: string, counter: number): string;
+/**
+ * Checks a TOTP code: steps from TOTP_ALLOWED_DRIFT_STEPS before to after now are accepted, but never a step at or
+ * below the last one used (each code works once, D8).
+ * @param secretBase32 The shared secret.
+ * @param code The code given.
+ * @param lastUsedStep The last step this secret signed in with (0 for none).
+ * @param nowMilliseconds The current time.
+ * @returns ok and the matched step (to store as the new lastUsedStep), or ok false and step 0.
+ */
+export declare function verifyTotp(secretBase32: string, code: string, lastUsedStep: number, nowMilliseconds: number): {
+    ok: boolean;
+    step: number;
+};
+/**
+ * The otpauth:// URI an authenticator app reads from the QR code (DR §8).
+ * @param username The account's username.
+ * @param secretBase32 The secret.
+ * @returns The URI.
+ */
+export declare function buildOtpauthUri(username: string, secretBase32: string): string;
+/**
+ * New recovery codes (`xxxx-xxxx`, base32 lower case) and their stored hashes.
+ * @returns The codes to show once, and their SHA-256 hashes to store.
+ */
+export declare function generateRecoveryCodes(): {
+    codes: string[];
+    hashes: string[];
+};
+/**
+ * Uses up a recovery code.
+ * @param code The code given (case and spaces ignored).
+ * @param hashes The account's unused code hashes.
+ * @returns The hashes left after removing the match, or null when no code matches.
+ */
+export declare function consumeRecoveryCode(code: string, hashes: string[]): string[] | null;

package/lib/admin/OneTimeCodes.js

@@ -0,0 +1,162 @@
+// Authenticator codes and recovery codes (game-server-admin-console D8, DR §8): RFC 6238 TOTP with SHA-1, 6 digits and
+// 30-second steps; RFC 4648 base32 secrets; ten single-use recovery codes stored as SHA-256 hashes.
+import { createHmac, randomBytes } from "node:crypto";
+import { sha256Hex, textsMatch } from "./AdminCrypto.js";
+import { RECOVERY_CODE_COUNT, TOTP_ALLOWED_DRIFT_STEPS, TOTP_DIGITS, TOTP_SECRET_BYTES, TOTP_STEP_SECONDS } from "./AdminConstants.js";
+/** The RFC 4648 base32 alphabet. */
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+/** Bits one base32 character carries. */
+const BITS_PER_BASE32_CHARACTER = 5;
+/** Bits in a byte. */
+const BITS_PER_BYTE = 8;
+/** Mask of the low five bits. */
+const FIVE_BIT_MASK = 0x1f;
+/** Keeps the bit buffer small: only its newest 16 bits are ever read. */
+const BIT_BUFFER_MASK = 0xffff;
+/** Mask of a byte. */
+const BYTE_MASK = 0xff;
+/** Mask of the dynamic truncation offset (RFC 4226). */
+const TRUNCATION_OFFSET_MASK = 0x0f;
+/** Mask that clears the sign bit of the truncated code (RFC 4226). */
+const SIGN_BIT_MASK = 0x7fffffff;
+/** Bytes of a TOTP counter. */
+const COUNTER_BYTES = 8;
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/** Issuer shown by authenticator apps. */
+const OTPAUTH_ISSUER = "Babylon Game Server";
+/** Random bytes of one recovery code: 5 bytes = 8 base32 characters. */
+const RECOVERY_CODE_BYTES = 5;
+/** Characters of each half of a recovery code (`xxxx-xxxx`). */
+const RECOVERY_CODE_HALF_LENGTH = 4;
+/**
+ * Encodes bytes as base32 without padding.
+ * @param bytes The bytes.
+ * @returns The base32 text (upper case).
+ */
+export function encodeBase32(bytes) {
+    let bitCount = 0;
+    let bitBuffer = 0;
+    let text = "";
+    for (const byte of bytes) {
+        bitBuffer = ((bitBuffer << BITS_PER_BYTE) | byte) & BIT_BUFFER_MASK;
+        bitCount += BITS_PER_BYTE;
+        while (bitCount >= BITS_PER_BASE32_CHARACTER) {
+            text += BASE32_ALPHABET[(bitBuffer >>> (bitCount - BITS_PER_BASE32_CHARACTER)) & FIVE_BIT_MASK];
+            bitCount -= BITS_PER_BASE32_CHARACTER;
+        }
+    }
+    if (bitCount > 0)
+        text += BASE32_ALPHABET[(bitBuffer << (BITS_PER_BASE32_CHARACTER - bitCount)) & FIVE_BIT_MASK];
+    return text;
+}
+/**
+ * Decodes base32 (any case, padding and spaces ignored).
+ * @param text The base32 text.
+ * @returns The bytes.
+ * @throws Error on a character outside the alphabet.
+ */
+export function decodeBase32(text) {
+    const clean = text.replace(/[\s=]/g, "").toUpperCase();
+    let bitCount = 0;
+    let bitBuffer = 0;
+    const bytes = [];
+    for (const character of clean) {
+        const value = BASE32_ALPHABET.indexOf(character);
+        if (value < 0)
+            throw new Error("not base32: " + character);
+        bitBuffer = ((bitBuffer << BITS_PER_BASE32_CHARACTER) | value) & BIT_BUFFER_MASK;
+        bitCount += BITS_PER_BASE32_CHARACTER;
+        if (bitCount >= BITS_PER_BYTE) {
+            bytes.push((bitBuffer >>> (bitCount - BITS_PER_BYTE)) & BYTE_MASK);
+            bitCount -= BITS_PER_BYTE;
+        }
+    }
+    return Buffer.from(bytes);
+}
+/**
+ * A new random TOTP secret (TOTP_SECRET_BYTES bytes).
+ * @returns The secret in base32.
+ */
+export function generateTotpSecret() {
+    return encodeBase32(randomBytes(TOTP_SECRET_BYTES));
+}
+/**
+ * Computes the 6-digit TOTP code of a counter (a 30-second step since the Unix epoch).
+ * @param secretBase32 The shared secret in RFC 4648 base32.
+ * @param counter The time step number.
+ * @returns The zero-padded 6-digit code.
+ */
+export function totpCodeAt(secretBase32, counter) {
+    const counterBytes = Buffer.alloc(COUNTER_BYTES);
+    counterBytes.writeBigUInt64BE(BigInt(counter));
+    const digest = createHmac("sha1", decodeBase32(secretBase32)).update(counterBytes).digest();
+    const offset = digest[digest.length - 1] & TRUNCATION_OFFSET_MASK;
+    const binaryCode = digest.readUInt32BE(offset) & SIGN_BIT_MASK;
+    return String(binaryCode % 10 ** TOTP_DIGITS).padStart(TOTP_DIGITS, "0");
+}
+/**
+ * Checks a TOTP code: steps from TOTP_ALLOWED_DRIFT_STEPS before to after now are accepted, but never a step at or
+ * below the last one used (each code works once, D8).
+ * @param secretBase32 The shared secret.
+ * @param code The code given.
+ * @param lastUsedStep The last step this secret signed in with (0 for none).
+ * @param nowMilliseconds The current time.
+ * @returns ok and the matched step (to store as the new lastUsedStep), or ok false and step 0.
+ */
+export function verifyTotp(secretBase32, code, lastUsedStep, nowMilliseconds) {
+    const cleanCode = code.replace(/\s/g, "");
+    if (cleanCode.length !== TOTP_DIGITS)
+        return { ok: false, step: 0 };
+    const currentStep = Math.floor(nowMilliseconds / MILLISECONDS_PER_SECOND / TOTP_STEP_SECONDS);
+    for (let step = currentStep - TOTP_ALLOWED_DRIFT_STEPS; step <= currentStep + TOTP_ALLOWED_DRIFT_STEPS; step++) {
+        if (step <= lastUsedStep)
+            continue;
+        if (textsMatch(totpCodeAt(secretBase32, step), cleanCode))
+            return { ok: true, step: step };
+    }
+    return { ok: false, step: 0 };
+}
+/**
+ * The otpauth:// URI an authenticator app reads from the QR code (DR §8).
+ * @param username The account's username.
+ * @param secretBase32 The secret.
+ * @returns The URI.
+ */
+export function buildOtpauthUri(username, secretBase32) {
+    const label = encodeURIComponent(OTPAUTH_ISSUER + ":" + username);
+    return "otpauth://totp/" + label + "?secret=" + secretBase32 + "&issuer=" + encodeURIComponent(OTPAUTH_ISSUER) + "&algorithm=SHA1&digits=" + TOTP_DIGITS + "&period=" + TOTP_STEP_SECONDS;
+}
+/**
+ * New recovery codes (`xxxx-xxxx`, base32 lower case) and their stored hashes.
+ * @returns The codes to show once, and their SHA-256 hashes to store.
+ */
+export function generateRecoveryCodes() {
+    const codes = [];
+    for (let i = 0; i < RECOVERY_CODE_COUNT; i++) {
+        const characters = encodeBase32(randomBytes(RECOVERY_CODE_BYTES)).toLowerCase();
+        codes.push(characters.substring(0, RECOVERY_CODE_HALF_LENGTH) + "-" + characters.substring(RECOVERY_CODE_HALF_LENGTH));
+    }
+    return { codes: codes, hashes: codes.map(hashRecoveryCode) };
+}
+/**
+ * Uses up a recovery code.
+ * @param code The code given (case and spaces ignored).
+ * @param hashes The account's unused code hashes.
+ * @returns The hashes left after removing the match, or null when no code matches.
+ */
+export function consumeRecoveryCode(code, hashes) {
+    const codeHash = hashRecoveryCode(code);
+    const index = hashes.findIndex((storedHash) => textsMatch(storedHash, codeHash));
+    if (index < 0)
+        return null;
+    return [...hashes.slice(0, index), ...hashes.slice(index + 1)];
+}
+/**
+ * The stored hash of a recovery code.
+ * @param code The code (normalized to lower case without spaces).
+ * @returns SHA-256 hex.
+ */
+function hashRecoveryCode(code) {
+    return sha256Hex(code.replace(/\s/g, "").toLowerCase());
+}

package/lib/admin/OpenIdConnect.d.ts

@@ -0,0 +1,146 @@
+import type { AdminAccounts } from "./AdminAccounts.js";
+import type { AdminClock } from "./AdminClock.js";
+import type { AdminUserRecord } from "./AdminRecords.js";
+import type { AdminStore } from "./AdminStore.js";
+import type { AdminOpenIdConfig } from "../GameServerConfig.js";
+/** The provider fields the console uses (the provider's own names, R32). */
+export interface OpenIdDiscovery {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri: string;
+}
+/** How a callback ended: signed in, a second factor asked, or refused with a reason code for the sign-in page. */
+export type OpenIdOutcome = {
+    kind: "signedIn";
+    user: AdminUserRecord;
+    note: string | null;
+} | {
+    kind: "needsSecondFactor";
+    pendingToken: string;
+    stage: "secondFactor" | "enrolSecondFactor";
+    user: AdminUserRecord;
+    note: string | null;
+} | {
+    kind: "refused";
+    reason: OpenIdRefusalReason;
+};
+/** Why a single sign-on was refused (the sign-in page shows #/sign-in?error=<reason>). */
+export type OpenIdRefusalReason = "no-role" | "account-disabled" | "sign-in-failed";
+/** The console's OpenID Connect client. */
+export declare class OpenIdConnectClient {
+    /** admin.oidc. */
+    private readonly config;
+    /** The admin store (pending sign-ins, accounts). */
+    private readonly store;
+    /** The clock of the discovery cache and challenge expiries. */
+    private readonly clock;
+    /** The admin accounts. */
+    private readonly accounts;
+    /** The cached discovery document and when it was fetched, or null. */
+    private cachedDiscovery;
+    /** The provider's key set, per jwks_uri (jose caches the keys). */
+    private keySet;
+    /**
+     * Creates the client.
+     * @param config admin.oidc.
+     * @param store The admin store.
+     * @param clock The clock.
+     * @param accounts The admin accounts.
+     */
+    constructor(config: AdminOpenIdConfig, store: AdminStore, clock: AdminClock, accounts: AdminAccounts);
+    /** True when admin.oidc.enabled. */
+    get isEnabled(): boolean;
+    /** The sign-in button label. */
+    get label(): string;
+    /**
+     * The provider's discovery document, cached for OIDC_DISCOVERY_CACHE_MS.
+     * @returns The document.
+     * @throws Error when the provider does not answer with one.
+     */
+    discovery(): Promise<OpenIdDiscovery>;
+    /**
+     * Starts a sign-in (GET auth/oidc/start): stores the state, nonce and PKCE verifier for CHALLENGE_LIFETIME_MS and
+     * builds the provider's authorization URL.
+     * @param consoleOrigin The console origin (the redirect URI is below it).
+     * @returns Where to send the browser.
+     */
+    startUrl(consoleOrigin: string): Promise<{
+        location: string;
+    }>;
+    /**
+     * Finishes a sign-in (GET auth/oidc/callback): checks the state, exchanges the code, verifies the ID token (issuer,
+     * audience, signature, nonce), then matches or creates the account and applies the two-factor rule (D26).
+     * @param query The callback's query.
+     * @returns The outcome.
+     */
+    complete(query: URLSearchParams): Promise<OpenIdOutcome>;
+    /**
+     * Matches or creates the account of verified claims and decides the second factor.
+     * @param claims The verified ID token claims.
+     * @returns The outcome.
+     */
+    private signInWithClaims;
+    /**
+     * Takes a started sign-in out of the store (single use).
+     * @param state The callback's state, or null.
+     * @returns The live record, or null for a missing, unknown, used or expired state.
+     */
+    private consumeChallenge;
+    /**
+     * Exchanges the authorization code at the token endpoint (client_secret_post, PKCE verifier).
+     * @param code The authorization code.
+     * @param challenge The started sign-in.
+     * @returns The ID token.
+     * @throws Error when the provider refuses or answers without an ID token.
+     */
+    private exchangeCode;
+    /**
+     * Verifies an ID token: signature against the provider's JWKS, issuer, audience (the client id) and nonce.
+     * @param idToken The ID token.
+     * @param expectedNonce The nonce of the started sign-in.
+     * @returns The claims.
+     * @throws Error when any check fails.
+     */
+    private verifiedClaims;
+    /**
+     * The provider's key set (one per jwks_uri; jose fetches and caches the keys).
+     * @param jwksUri The provider's jwks_uri.
+     * @returns The key resolver.
+     */
+    private keysOf;
+    /**
+     * The most powerful console role the claim maps to (admin.oidc.roleMapping "value=role").
+     * @param claims The verified claims.
+     * @returns The role, or null when no value maps.
+     */
+    private mappedRoleOf;
+    /**
+     * The account of the claims: the one with this subject, else the one with this verified email.
+     * @param claims The verified claims.
+     * @returns The stored account, or null.
+     */
+    private findAccount;
+    /**
+     * Links an existing account to the subject and applies a mapped role, except that the last enabled owner keeps the
+     * owner role (DR §5); that refusal is logged and returned as a note for the audit record.
+     * @param stored The account.
+     * @param claims The verified claims.
+     * @param mappedRole The mapped role, or null to keep the account's role.
+     * @returns The account as stored now, and the note.
+     */
+    private updateAccount;
+    /**
+     * Creates the account of a first single sign-on (no password: SSO only).
+     * @param claims The verified claims.
+     * @param role The mapped role.
+     * @returns The new account.
+     */
+    private createAccount;
+    /**
+     * A username not taken yet: the base, else the base with a number.
+     * @param base A valid username base.
+     * @returns The username.
+     */
+    private freeUsername;
+}