@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/OpenIdConnect.js

@@ -0,0 +1,335 @@
+// OpenID Connect single sign-on of the admin console (game-server-admin-console D26, DR §7.10): authorization code flow
+// with PKCE (S256), the ID token verified with jose against the provider's JWKS, the state and nonce checked, accounts
+// matched by verified email or subject, roles mapped from a claim, and the provider's multi-factor proof honoured.
+import { createHash } from "node:crypto";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { ADMIN_API_PREFIX, CHALLENGE_LIFETIME_MS, OIDC_DISCOVERY_CACHE_MS } from "./AdminConstants.js";
+import { randomToken, sha256Hex } from "./AdminCrypto.js";
+import { ADMIN_ROLES } from "./AdminPermissions.js";
+import { getLogger } from "../GameServerLogger.js";
+/** The provider's discovery document path below the issuer. */
+const DISCOVERY_PATH = "/.well-known/openid-configuration";
+/** The API path of the callback, below the console origin. */
+const CALLBACK_PATH = ADMIN_API_PREFIX + "auth/oidc/callback";
+/** The scopes the console asks for. */
+const SCOPES = "openid email profile";
+/** Random bytes of the state, the nonce and the PKCE verifier. */
+const RANDOM_VALUE_BYTES = 32;
+/** The id prefix of OIDC sign-ins in pendingSignIns. */
+const CHALLENGE_ID_PREFIX = "oidc:";
+/** amr values that count as a multi-factor proof (D26). */
+const MULTI_FACTOR_METHODS = new Set(["mfa", "otp", "hwk", "swk"]);
+/** Usernames: lower case letters, digits, dot, underscore and dash, 3 to 32 characters (AdminAccounts' rule). */
+const USERNAME_MAX_LENGTH = 32;
+const USERNAME_MIN_LENGTH = 3;
+/** Characters a derived username may not contain. */
+const USERNAME_INVALID_CHARACTERS = /[^a-z0-9._-]/g;
+/** The fallback base of a derived username. */
+const DEFAULT_USERNAME_BASE = "sso-user";
+/** Claims an ID token must carry besides those jwtVerify checks by value. */
+const REQUIRED_CLAIMS = ["exp", "iat"];
+/** The owner role, which the last enabled owner never loses (DR §5). */
+const OWNER_ROLE = "owner";
+/** Request timeout of provider calls, in milliseconds. */
+const PROVIDER_TIMEOUT_MS = 10000;
+/** The console's OpenID Connect client. */
+export class OpenIdConnectClient {
+    /** admin.oidc. */
+    config;
+    /** The admin store (pending sign-ins, accounts). */
+    store;
+    /** The clock of the discovery cache and challenge expiries. */
+    clock;
+    /** The admin accounts. */
+    accounts;
+    /** The cached discovery document and when it was fetched, or null. */
+    cachedDiscovery = null;
+    /** The provider's key set, per jwks_uri (jose caches the keys). */
+    keySet = null;
+    /**
+     * Creates the client.
+     * @param config admin.oidc.
+     * @param store The admin store.
+     * @param clock The clock.
+     * @param accounts The admin accounts.
+     */
+    constructor(config, store, clock, accounts) {
+        this.config = config;
+        this.store = store;
+        this.clock = clock;
+        this.accounts = accounts;
+    }
+    /** True when admin.oidc.enabled. */
+    get isEnabled() {
+        return this.config.enabled;
+    }
+    /** The sign-in button label. */
+    get label() {
+        return this.config.label;
+    }
+    /**
+     * The provider's discovery document, cached for OIDC_DISCOVERY_CACHE_MS.
+     * @returns The document.
+     * @throws Error when the provider does not answer with one.
+     */
+    async discovery() {
+        const now = this.clock.now();
+        if (this.cachedDiscovery != null && now - this.cachedDiscovery.fetchedAt < OIDC_DISCOVERY_CACHE_MS)
+            return this.cachedDiscovery.document;
+        const issuer = (this.config.issuer ?? "").replace(/\/+$/, "");
+        const answer = await fetch(issuer + DISCOVERY_PATH, { signal: AbortSignal.timeout(PROVIDER_TIMEOUT_MS) });
+        if (!answer.ok)
+            throw new Error("the OpenID provider's discovery document answered " + answer.status);
+        const document = await answer.json();
+        const isComplete = [document.issuer, document.authorization_endpoint, document.token_endpoint, document.jwks_uri].every((field) => typeof field === "string");
+        if (!isComplete)
+            throw new Error("the OpenID provider's discovery document lacks issuer, endpoints or jwks_uri");
+        this.cachedDiscovery = { document: document, fetchedAt: now };
+        return this.cachedDiscovery.document;
+    }
+    /**
+     * 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.
+     */
+    async startUrl(consoleOrigin) {
+        const provider = await this.discovery();
+        const state = randomToken(RANDOM_VALUE_BYTES);
+        const record = {
+            kind: "oidc",
+            nonce: randomToken(RANDOM_VALUE_BYTES),
+            codeVerifier: randomToken(RANDOM_VALUE_BYTES),
+            redirectUri: consoleOrigin + CALLBACK_PATH,
+            expiresAt: new Date(this.clock.now() + CHALLENGE_LIFETIME_MS).toISOString()
+        };
+        await this.store.putDocument("pendingSignIns", CHALLENGE_ID_PREFIX + sha256Hex(state), record, 0);
+        const location = new URL(provider.authorization_endpoint);
+        const parameters = {
+            response_type: "code",
+            client_id: this.config.clientId ?? "",
+            redirect_uri: record.redirectUri,
+            scope: SCOPES,
+            state: state,
+            nonce: record.nonce,
+            code_challenge: createHash("sha256").update(record.codeVerifier).digest("base64url"),
+            code_challenge_method: "S256"
+        };
+        for (const [name, value] of Object.entries(parameters))
+            location.searchParams.set(name, value);
+        return { location: location.toString() };
+    }
+    /**
+     * 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.
+     */
+    async complete(query) {
+        const challenge = await this.consumeChallenge(query.get("state"));
+        const code = query.get("code");
+        if (challenge == null || code == null || query.has("error"))
+            return { kind: "refused", reason: "sign-in-failed" };
+        let claims;
+        try {
+            claims = await this.verifiedClaims(await this.exchangeCode(code, challenge), challenge.nonce);
+        }
+        catch (error) {
+            getLogger().warn("an admin single sign-on was refused", { error: String(error) });
+            return { kind: "refused", reason: "sign-in-failed" };
+        }
+        return this.signInWithClaims(claims);
+    }
+    /**
+     * Matches or creates the account of verified claims and decides the second factor.
+     * @param claims The verified ID token claims.
+     * @returns The outcome.
+     */
+    async signInWithClaims(claims) {
+        const mappedRole = this.mappedRoleOf(claims);
+        const existing = await this.findAccount(claims);
+        if (existing == null && mappedRole == null)
+            return { kind: "refused", reason: "no-role" };
+        const matched = (existing != null)
+            ? await this.updateAccount(existing, claims, mappedRole)
+            : { user: await this.createAccount(claims, mappedRole), note: null };
+        const user = matched.user;
+        if (user.disabled || this.accounts.isLocked(user))
+            return { kind: "refused", reason: "account-disabled" };
+        const methods = claims.amr;
+        const hasMultiFactorProof = Array.isArray(methods) && methods.some((method) => typeof method === "string" && MULTI_FACTOR_METHODS.has(method));
+        if (hasMultiFactorProof)
+            return { kind: "signedIn", user: user, note: matched.note };
+        const step = await this.accounts.startSingleSignOnSecondFactor(user);
+        return { kind: "needsSecondFactor", pendingToken: step.pendingToken, stage: step.stage, user: user, note: matched.note };
+    }
+    /**
+     * 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.
+     */
+    async consumeChallenge(state) {
+        if (state == null || state === "")
+            return null;
+        const documentId = CHALLENGE_ID_PREFIX + sha256Hex(state);
+        const stored = await this.store.getDocument("pendingSignIns", documentId);
+        if (stored == null || !(await this.store.deleteDocument("pendingSignIns", documentId)))
+            return null;
+        const isLive = stored.value.kind === "oidc" && Date.parse(stored.value.expiresAt) > this.clock.now();
+        return isLive ? stored.value : null;
+    }
+    /**
+     * 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.
+     */
+    async exchangeCode(code, challenge) {
+        const provider = await this.discovery();
+        const form = new URLSearchParams({
+            grant_type: "authorization_code",
+            code: code,
+            redirect_uri: challenge.redirectUri,
+            client_id: this.config.clientId ?? "",
+            code_verifier: challenge.codeVerifier
+        });
+        if (this.config.clientSecret != null)
+            form.set("client_secret", this.config.clientSecret);
+        const answer = await fetch(provider.token_endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: form.toString(),
+            signal: AbortSignal.timeout(PROVIDER_TIMEOUT_MS)
+        });
+        const tokens = await answer.json();
+        if (!answer.ok || typeof tokens.id_token !== "string")
+            throw new Error("the token endpoint answered " + answer.status + " without an id_token");
+        return tokens.id_token;
+    }
+    /**
+     * 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.
+     */
+    async verifiedClaims(idToken, expectedNonce) {
+        const provider = await this.discovery();
+        const verified = await jwtVerify(idToken, this.keysOf(provider.jwks_uri), { issuer: provider.issuer, audience: this.config.clientId ?? "", requiredClaims: REQUIRED_CLAIMS });
+        if (verified.payload.nonce !== expectedNonce)
+            throw new Error("the ID token's nonce does not match");
+        if (typeof verified.payload.sub !== "string" || verified.payload.sub === "")
+            throw new Error("the ID token has no subject");
+        return verified.payload;
+    }
+    /**
+     * 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.
+     */
+    keysOf(jwksUri) {
+        if (this.keySet == null || this.keySet.jwksUri !== jwksUri)
+            this.keySet = { jwksUri: jwksUri, getKey: createRemoteJWKSet(new URL(jwksUri)) };
+        return this.keySet.getKey;
+    }
+    /**
+     * 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.
+     */
+    mappedRoleOf(claims) {
+        const claim = claims[this.config.roleClaim];
+        const values = (Array.isArray(claim) ? claim : [claim]).filter((value) => typeof value === "string");
+        const roles = [];
+        for (const entry of this.config.roleMapping) {
+            const separatorIndex = entry.lastIndexOf("=");
+            if (values.includes(entry.substring(0, separatorIndex)))
+                roles.push(entry.substring(separatorIndex + 1));
+        }
+        // ADMIN_ROLES lists the roles from most to least powerful.
+        return ADMIN_ROLES.find((role) => roles.includes(role)) ?? null;
+    }
+    /**
+     * 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.
+     */
+    async findAccount(claims) {
+        const users = await this.store.listDocuments("users");
+        const bySubject = users.find((stored) => stored.value.oidcSubject === claims.sub);
+        if (bySubject != null)
+            return bySubject;
+        const email = verifiedEmailOf(claims);
+        if (email == null)
+            return null;
+        return users.find((stored) => stored.value.email != null && stored.value.email.toLowerCase() === email) ?? null;
+    }
+    /**
+     * 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.
+     */
+    async updateAccount(stored, claims, mappedRole) {
+        const keepsLastOwner = stored.value.role === OWNER_ROLE && mappedRole != null && mappedRole !== OWNER_ROLE && !(await this.accounts.hasAnotherEnabledOwner(stored.id));
+        const note = keepsLastOwner ? "the last owner keeps the owner role; the role mapping asked for " + mappedRole : null;
+        if (keepsLastOwner)
+            getLogger().warn("a single sign-on role mapping would demote the last owner; the owner role is kept", { username: stored.value.username, mappedRole: mappedRole });
+        const role = keepsLastOwner ? OWNER_ROLE : (mappedRole ?? stored.value.role);
+        const subject = String(claims.sub);
+        if (stored.value.oidcSubject === subject && stored.value.role === role)
+            return { user: stored.value, note: note };
+        const updated = Object.assign({}, stored.value, { oidcSubject: subject, role: role });
+        await this.store.putDocument("users", stored.id, updated, stored.revision);
+        return { user: updated, note: note };
+    }
+    /**
+     * 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.
+     */
+    async createAccount(claims, role) {
+        const email = verifiedEmailOf(claims);
+        const username = await this.freeUsername(usernameBaseOf(claims, email));
+        const displayName = (typeof claims.name === "string") ? claims.name : username;
+        return this.accounts.createUser({ username: username, displayName: displayName, email: email, role: role, password: null, oidcSubject: String(claims.sub) });
+    }
+    /**
+     * A username not taken yet: the base, else the base with a number.
+     * @param base A valid username base.
+     * @returns The username.
+     */
+    async freeUsername(base) {
+        if ((await this.accounts.findByUsername(base)) == null)
+            return base;
+        for (let suffix = 2;; suffix++) {
+            const candidate = base.substring(0, USERNAME_MAX_LENGTH - String(suffix).length - 1) + "-" + suffix;
+            if ((await this.accounts.findByUsername(candidate)) == null)
+                return candidate;
+        }
+    }
+}
+/**
+ * The email of the claims when the provider verified it.
+ * @param claims The verified claims.
+ * @returns The lower-case email, or null.
+ */
+function verifiedEmailOf(claims) {
+    return (typeof claims.email === "string" && claims.email_verified === true) ? claims.email.toLowerCase() : null;
+}
+/**
+ * A username base from preferred_username, the email's local part or a default, cut to the username rule.
+ * @param claims The verified claims.
+ * @param email The verified email, or null.
+ * @returns The base.
+ */
+function usernameBaseOf(claims, email) {
+    const preferred = (typeof claims.preferred_username === "string") ? claims.preferred_username : null;
+    const raw = preferred ?? (email != null ? email.split("@")[0] : DEFAULT_USERNAME_BASE);
+    const cleaned = raw.toLowerCase().replace(USERNAME_INVALID_CHARACTERS, "-").substring(0, USERNAME_MAX_LENGTH);
+    return (cleaned.length >= USERNAME_MIN_LENGTH) ? cleaned : DEFAULT_USERNAME_BASE;
+}

package/lib/admin/Passkeys.d.ts

@@ -0,0 +1,130 @@
+import type { AdminAccounts } from "./AdminAccounts.js";
+import type { PasskeyAlgorithm, PasskeyAssertionView, PasskeyAttestationView, PasskeyCreationOptionsView, PasskeyRequestOptionsView, PasskeyView } from "./AdminApiTypes.js";
+import type { AdminClock } from "./AdminClock.js";
+import type { AdminUserRecord, PasskeyRecord } from "./AdminRecords.js";
+import type { AdminStore } from "./AdminStore.js";
+import type { AdminPasskeyConfig } from "../GameServerConfig.js";
+/** Registers passkeys and verifies passkey sign-ins. */
+export declare class Passkeys {
+    /** The admin store. */
+    private readonly store;
+    /** The clock of challenge expiries and use times. */
+    private readonly clock;
+    /** The passkey settings. */
+    private readonly config;
+    /** The admin accounts. */
+    private readonly accounts;
+    /**
+     * Creates the passkey service.
+     * @param store The admin store.
+     * @param clock The clock.
+     * @param config admin.passkeys.
+     * @param accounts The admin accounts.
+     */
+    constructor(store: AdminStore, clock: AdminClock, config: AdminPasskeyConfig, accounts: AdminAccounts);
+    /** True when admin.passkeys.enabled. */
+    get isEnabled(): boolean;
+    /**
+     * Options of navigator.credentials.create for a signed-in admin.
+     * @param user The account.
+     * @param consoleOrigin The console origin (its host is the default relying party id).
+     * @returns The options.
+     */
+    creationOptions(user: AdminUserRecord, consoleOrigin: string): Promise<PasskeyCreationOptionsView>;
+    /**
+     * Registers a passkey from navigator.credentials.create's result (attestation "none" only).
+     * @param user The signed-in account.
+     * @param name The passkey's name.
+     * @param attestation The credential.
+     * @param consoleOrigin The console origin.
+     * @returns The stored passkey.
+     * @throws AdminRequestError 400 for a refused credential, 409 for a passkey already registered.
+     */
+    register(user: AdminUserRecord, name: string, attestation: PasskeyAttestationView, consoleOrigin: string): Promise<PasskeyRecord>;
+    /**
+     * Options of navigator.credentials.get. With a username, its passkeys are listed; an unknown username gets an empty
+     * list like a discoverable sign-in, so the answer never reveals which usernames exist.
+     * @param username The username, or null for any account's discoverable passkey.
+     * @param consoleOrigin The console origin (its host is the default relying party id).
+     * @returns The options.
+     */
+    requestOptions(username: string | null, consoleOrigin: string): Promise<PasskeyRequestOptionsView>;
+    /**
+     * Verifies navigator.credentials.get's result (DR §7.11): client data, relying party, presence, signature and sign
+     * count, then records the use.
+     * @param assertion The assertion.
+     * @param consoleOrigin The console origin.
+     * @returns The account and whether the authenticator verified the user.
+     * @throws AdminRequestError 401 for a refused assertion.
+     */
+    verifyAssertion(assertion: PasskeyAssertionView, consoleOrigin: string): Promise<{
+        user: AdminUserRecord;
+        userVerified: boolean;
+    }>;
+    /**
+     * An account's passkeys, oldest first.
+     * @param userId The account.
+     * @returns The passkeys.
+     */
+    list(userId: string): Promise<PasskeyView[]>;
+    /**
+     * Removes one of an account's passkeys.
+     * @param userId The account.
+     * @param passkeyId The passkey.
+     * @throws AdminRequestError 404 when the account has no such passkey.
+     */
+    remove(userId: string, passkeyId: string): Promise<void>;
+    /**
+     * The relying party id: admin.passkeys.rpId, or the console's host name.
+     * @param consoleOrigin The console origin.
+     * @returns The id.
+     */
+    private rpIdOf;
+    /**
+     * Checks authenticator data against the relying party and the user-present flag. User verification is checked by
+     * the caller, since only a password-less sign-in needs it.
+     * @param authenticatorData The parsed data.
+     * @param consoleOrigin The console origin.
+     * @param status The status of a refusal.
+     * @throws AdminRequestError with the status on a mismatch.
+     */
+    private checkAuthenticatorData;
+    /**
+     * Creates and stores a challenge for CHALLENGE_LIFETIME_MS.
+     * @param kind Registration or sign-in.
+     * @param userId The account it is for, or null.
+     * @returns The challenge, base64url.
+     */
+    private createChallenge;
+    /**
+     * Takes a live challenge of a kind out of the store (single use).
+     * @param challenge The challenge from clientDataJSON.
+     * @param kind The kind the call needs.
+     * @param status The status of a refusal.
+     * @returns The challenge record.
+     * @throws AdminRequestError with the status when it is unknown, expired, used or of another kind.
+     */
+    private consumeChallenge;
+    /**
+     * An account's stored passkeys.
+     * @param userId The account.
+     * @returns The records.
+     */
+    private passkeysOf;
+    /**
+     * The passkey with a credential id.
+     * @param credentialId The base64url credential id.
+     * @returns The stored passkey, or null.
+     */
+    private findByCredentialId;
+}
+/**
+ * Turns a COSE public key into a JWK: EC2 P-256 (x -2, y -3), RSA (n -1, e -2) or OKP Ed25519 (x -2).
+ * @param coseKey The decoded COSE key.
+ * @returns The JWK and its algorithm.
+ * @throws AdminRequestError 400 for another key type, curve or algorithm.
+ */
+export declare function coseKeyToJwk(coseKey: Map<unknown, unknown>): {
+    jwk: JsonWebKey;
+    algorithm: PasskeyAlgorithm;
+};