@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/Passkeys.js

@@ -0,0 +1,432 @@
+// Passkeys of the admin console (game-server-admin-console D31, DR §7.11), verified by hand with node:crypto: WebAuthn
+// registration with attestation "none" only, and assertions signed with ES256, RS256 or EdDSA. A passkey is a second
+// factor after a password, and a full sign-in when the authenticator verified the user (password-less).
+import { createHash, createPublicKey, randomBytes, verify } from "node:crypto";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { CHALLENGE_LIFETIME_MS } from "./AdminConstants.js";
+import { randomToken, sha256Hex } from "./AdminCrypto.js";
+import { decodeCbor, decodeCborPrefix } from "./CborDecoder.js";
+/** HTTP statuses of the refusals. */
+const HTTP_BAD_REQUEST = 400;
+const HTTP_UNAUTHORIZED = 401;
+const HTTP_NOT_FOUND = 404;
+const HTTP_CONFLICT = 409;
+/** Random bytes of a challenge and of a passkey id. */
+const CHALLENGE_BYTES = 32;
+const PASSKEY_ID_BYTES = 12;
+/** The relying party name authenticators show. */
+const RELYING_PARTY_NAME = "Babylon Game Server";
+/** The algorithms the console accepts, in order of preference (D31). */
+const ACCEPTED_ALGORITHMS = [-7, -8, -257];
+/** COSE algorithm ids. */
+const COSE_ES256 = -7;
+const COSE_EDDSA = -8;
+const COSE_RS256 = -257;
+/** COSE key labels and values (RFC 9053). */
+const COSE_KEY_TYPE = 1;
+const COSE_ALGORITHM = 3;
+const COSE_EC2_CURVE = -1;
+const COSE_EC2_X = -2;
+const COSE_EC2_Y = -3;
+const COSE_RSA_MODULUS = -1;
+const COSE_RSA_EXPONENT = -2;
+const COSE_OKP_CURVE = -1;
+const COSE_OKP_X = -2;
+const COSE_KEY_TYPE_OKP = 1;
+const COSE_KEY_TYPE_EC2 = 2;
+const COSE_KEY_TYPE_RSA = 3;
+const COSE_CURVE_P256 = 1;
+const COSE_CURVE_ED25519 = 6;
+/** Authenticator data layout (WebAuthn §6.1). */
+const RP_ID_HASH_LENGTH = 32;
+const FLAGS_OFFSET = 32;
+const SIGN_COUNT_OFFSET = 33;
+const ATTESTED_DATA_OFFSET = 37;
+const AAGUID_LENGTH = 16;
+const CREDENTIAL_ID_LENGTH_BYTES = 2;
+/** Authenticator data flags. */
+const FLAG_USER_PRESENT = 0x01;
+const FLAG_USER_VERIFIED = 0x04;
+const FLAG_ATTESTED_DATA = 0x40;
+/** clientDataJSON types. */
+const CREATE_TYPE = "webauthn.create";
+const GET_TYPE = "webauthn.get";
+/** The id prefix of passkey challenges in pendingSignIns. */
+const CHALLENGE_ID_PREFIX = "passkey:";
+/** The answer of every refused assertion or registration. */
+const REFUSED_MESSAGE = "the passkey was not accepted";
+/** Registers passkeys and verifies passkey sign-ins. */
+export class Passkeys {
+    /** The admin store. */
+    store;
+    /** The clock of challenge expiries and use times. */
+    clock;
+    /** The passkey settings. */
+    config;
+    /** The admin accounts. */
+    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, clock, config, accounts) {
+        this.store = store;
+        this.clock = clock;
+        this.config = config;
+        this.accounts = accounts;
+    }
+    /** True when admin.passkeys.enabled. */
+    get isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * 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.
+     */
+    async creationOptions(user, consoleOrigin) {
+        const challenge = await this.createChallenge("passkeyRegistration", user.userId);
+        const existing = await this.passkeysOf(user.userId);
+        return {
+            challenge: challenge,
+            rp: { id: this.rpIdOf(consoleOrigin), name: RELYING_PARTY_NAME },
+            user: { id: user.userId, name: user.username, displayName: user.displayName },
+            pubKeyCredParams: ACCEPTED_ALGORITHMS.map((algorithm) => ({ type: "public-key", alg: algorithm })),
+            timeout: CHALLENGE_LIFETIME_MS,
+            attestation: "none",
+            authenticatorSelection: { residentKey: "preferred", userVerification: "preferred" },
+            excludeCredentials: existing.map((passkey) => ({ type: "public-key", id: passkey.credentialId }))
+        };
+    }
+    /**
+     * 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.
+     */
+    async register(user, name, attestation, consoleOrigin) {
+        const clientData = parseClientData(attestation.response.clientDataJSON);
+        if (clientData.type !== CREATE_TYPE || clientData.origin !== consoleOrigin)
+            throw refused(HTTP_BAD_REQUEST);
+        const challenge = await this.consumeChallenge(clientData.challenge, "passkeyRegistration", HTTP_BAD_REQUEST);
+        if (challenge.userId !== user.userId)
+            throw refused(HTTP_BAD_REQUEST);
+        const authenticatorData = parseAttestationObject(attestation.response.attestationObject);
+        this.checkAuthenticatorData(authenticatorData, consoleOrigin, HTTP_BAD_REQUEST);
+        if (authenticatorData.credential == null)
+            throw refused(HTTP_BAD_REQUEST);
+        const credentialId = authenticatorData.credential.credentialId.toString("base64url");
+        if (credentialId !== attestation.rawId)
+            throw refused(HTTP_BAD_REQUEST);
+        if ((await this.findByCredentialId(credentialId)) != null)
+            throw new AdminRequestError(HTTP_CONFLICT, "this passkey is already registered");
+        const publicKey = coseKeyToJwk(authenticatorData.credential.coseKey);
+        const record = {
+            passkeyId: randomToken(PASSKEY_ID_BYTES),
+            userId: user.userId,
+            name: (name.trim() !== "") ? name.trim() : "Passkey",
+            credentialId: credentialId,
+            publicKeyJwk: publicKey.jwk,
+            algorithm: publicKey.algorithm,
+            signCount: authenticatorData.signCount,
+            createdAt: new Date(this.clock.now()).toISOString(),
+            lastUsedAt: null
+        };
+        await this.store.putDocument("passkeys", record.passkeyId, record, 0);
+        return record;
+    }
+    /**
+     * 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.
+     */
+    async requestOptions(username, consoleOrigin) {
+        const stored = (username != null && username !== "") ? await this.accounts.findByUsername(username) : null;
+        const passkeys = (stored != null) ? await this.passkeysOf(stored.value.userId) : [];
+        const challenge = await this.createChallenge("passkeyAssertion", stored?.value.userId ?? null);
+        return {
+            challenge: challenge,
+            rpId: this.rpIdOf(consoleOrigin),
+            timeout: CHALLENGE_LIFETIME_MS,
+            userVerification: "preferred",
+            allowCredentials: passkeys.map((passkey) => ({ type: "public-key", id: passkey.credentialId }))
+        };
+    }
+    /**
+     * 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.
+     */
+    async verifyAssertion(assertion, consoleOrigin) {
+        const clientData = parseClientData(assertion.response.clientDataJSON);
+        if (clientData.type !== GET_TYPE || clientData.origin !== consoleOrigin)
+            throw refused(HTTP_UNAUTHORIZED);
+        const challenge = await this.consumeChallenge(clientData.challenge, "passkeyAssertion", HTTP_UNAUTHORIZED);
+        const stored = await this.findByCredentialId(assertion.rawId);
+        if (stored == null || (challenge.userId != null && challenge.userId !== stored.value.userId))
+            throw refused(HTTP_UNAUTHORIZED);
+        const authenticatorDataBytes = Buffer.from(assertion.response.authenticatorData, "base64url");
+        const authenticatorData = parseAuthenticatorData(authenticatorDataBytes, false);
+        this.checkAuthenticatorData(authenticatorData, consoleOrigin, HTTP_UNAUTHORIZED);
+        const signedBytes = Buffer.concat([authenticatorDataBytes, createHash("sha256").update(Buffer.from(assertion.response.clientDataJSON, "base64url")).digest()]);
+        if (!verifySignature(stored.value, signedBytes, Buffer.from(assertion.response.signature, "base64url")))
+            throw refused(HTTP_UNAUTHORIZED);
+        if (!isSignCountValid(stored.value.signCount, authenticatorData.signCount))
+            throw refused(HTTP_UNAUTHORIZED);
+        const used = Object.assign({}, stored.value, { signCount: authenticatorData.signCount, lastUsedAt: new Date(this.clock.now()).toISOString() });
+        await this.store.putDocument("passkeys", stored.id, used, stored.revision);
+        const user = await this.accounts.getUser(used.userId);
+        if (user == null)
+            throw refused(HTTP_UNAUTHORIZED);
+        return { user: user.value, userVerified: (authenticatorData.flags & FLAG_USER_VERIFIED) !== 0 };
+    }
+    /**
+     * An account's passkeys, oldest first.
+     * @param userId The account.
+     * @returns The passkeys.
+     */
+    async list(userId) {
+        const passkeys = await this.passkeysOf(userId);
+        return passkeys.sort((left, right) => left.createdAt.localeCompare(right.createdAt))
+            .map((passkey) => ({ passkeyId: passkey.passkeyId, name: passkey.name, createdAt: passkey.createdAt, lastUsedAt: passkey.lastUsedAt }));
+    }
+    /**
+     * 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.
+     */
+    async remove(userId, passkeyId) {
+        const stored = await this.store.getDocument("passkeys", passkeyId);
+        if (stored == null || stored.value.userId !== userId)
+            throw new AdminRequestError(HTTP_NOT_FOUND, "no such passkey");
+        await this.store.deleteDocument("passkeys", passkeyId);
+    }
+    /**
+     * The relying party id: admin.passkeys.rpId, or the console's host name.
+     * @param consoleOrigin The console origin.
+     * @returns The id.
+     */
+    rpIdOf(consoleOrigin) {
+        return this.config.rpId ?? new URL(consoleOrigin).hostname;
+    }
+    /**
+     * 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.
+     */
+    checkAuthenticatorData(authenticatorData, consoleOrigin, status) {
+        const expectedHash = createHash("sha256").update(this.rpIdOf(consoleOrigin)).digest();
+        if (!authenticatorData.rpIdHash.equals(expectedHash))
+            throw refused(status);
+        if ((authenticatorData.flags & FLAG_USER_PRESENT) === 0)
+            throw refused(status);
+    }
+    /**
+     * 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.
+     */
+    async createChallenge(kind, userId) {
+        const challenge = randomBytes(CHALLENGE_BYTES).toString("base64url");
+        const record = { kind: kind, userId: userId, expiresAt: new Date(this.clock.now() + CHALLENGE_LIFETIME_MS).toISOString() };
+        await this.store.putDocument("pendingSignIns", CHALLENGE_ID_PREFIX + sha256Hex(challenge), record, 0);
+        return challenge;
+    }
+    /**
+     * 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.
+     */
+    async consumeChallenge(challenge, kind, status) {
+        const documentId = CHALLENGE_ID_PREFIX + sha256Hex(challenge);
+        const stored = await this.store.getDocument("pendingSignIns", documentId);
+        if (stored == null || !(await this.store.deleteDocument("pendingSignIns", documentId)))
+            throw refused(status);
+        if (stored.value.kind !== kind || Date.parse(stored.value.expiresAt) <= this.clock.now())
+            throw refused(status);
+        return stored.value;
+    }
+    /**
+     * An account's stored passkeys.
+     * @param userId The account.
+     * @returns The records.
+     */
+    async passkeysOf(userId) {
+        const documents = await this.store.listDocuments("passkeys");
+        return documents.map((document) => document.value).filter((passkey) => passkey.userId === userId);
+    }
+    /**
+     * The passkey with a credential id.
+     * @param credentialId The base64url credential id.
+     * @returns The stored passkey, or null.
+     */
+    async findByCredentialId(credentialId) {
+        const documents = await this.store.listDocuments("passkeys");
+        return documents.find((document) => document.value.credentialId === credentialId) ?? null;
+    }
+}
+/**
+ * The refusal of a passkey check (the same text for every reason, so a probe learns nothing).
+ * @param status 400 for registration, 401 for sign-in.
+ * @returns The error.
+ */
+function refused(status) {
+    return new AdminRequestError(status, REFUSED_MESSAGE);
+}
+/**
+ * Parses base64url clientDataJSON.
+ * @param clientDataJson The base64url text.
+ * @returns Its type, challenge and origin.
+ * @throws AdminRequestError 400 when it is not the JSON WebAuthn defines.
+ */
+function parseClientData(clientDataJson) {
+    try {
+        const parsed = JSON.parse(Buffer.from(clientDataJson, "base64url").toString("utf8"));
+        if (typeof parsed.type === "string" && typeof parsed.challenge === "string" && typeof parsed.origin === "string") {
+            return { type: parsed.type, challenge: parsed.challenge, origin: parsed.origin };
+        }
+    }
+    catch {
+        // Falls through to the refusal below.
+    }
+    throw refused(HTTP_BAD_REQUEST);
+}
+/**
+ * Decodes an attestation object and checks its format is "none" (D31).
+ * @param attestationObject The base64url CBOR attestation object.
+ * @returns Its parsed authenticator data with the attested credential.
+ * @throws AdminRequestError 400 for another format or malformed data.
+ */
+function parseAttestationObject(attestationObject) {
+    let decoded;
+    try {
+        decoded = decodeCbor(Buffer.from(attestationObject, "base64url"));
+    }
+    catch {
+        throw refused(HTTP_BAD_REQUEST);
+    }
+    if (!(decoded instanceof Map) || decoded.get("fmt") !== "none")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "only passkeys without attestation (\"none\") are accepted");
+    const authenticatorData = decoded.get("authData");
+    if (!(authenticatorData instanceof Uint8Array))
+        throw refused(HTTP_BAD_REQUEST);
+    return parseAuthenticatorData(Buffer.from(authenticatorData), true);
+}
+/**
+ * Parses authenticator data (WebAuthn §6.1).
+ * @param bytes The data.
+ * @param expectsCredential True for registration: the attested credential data must follow.
+ * @returns The parsed data.
+ * @throws AdminRequestError 400 when it is too short or the credential is malformed.
+ */
+function parseAuthenticatorData(bytes, expectsCredential) {
+    if (bytes.length < ATTESTED_DATA_OFFSET)
+        throw refused(HTTP_BAD_REQUEST);
+    const flags = bytes[FLAGS_OFFSET];
+    const parsed = { rpIdHash: bytes.subarray(0, RP_ID_HASH_LENGTH), flags: flags, signCount: bytes.readUInt32BE(SIGN_COUNT_OFFSET), credential: null };
+    if (!expectsCredential)
+        return parsed;
+    if ((flags & FLAG_ATTESTED_DATA) === 0)
+        throw refused(HTTP_BAD_REQUEST);
+    const lengthOffset = ATTESTED_DATA_OFFSET + AAGUID_LENGTH;
+    if (bytes.length < lengthOffset + CREDENTIAL_ID_LENGTH_BYTES)
+        throw refused(HTTP_BAD_REQUEST);
+    const credentialIdLength = bytes.readUInt16BE(lengthOffset);
+    const credentialIdStart = lengthOffset + CREDENTIAL_ID_LENGTH_BYTES;
+    const keyStart = credentialIdStart + credentialIdLength;
+    if (bytes.length <= keyStart)
+        throw refused(HTTP_BAD_REQUEST);
+    let coseKey;
+    try {
+        coseKey = decodeCborPrefix(bytes.subarray(keyStart)).value;
+    }
+    catch {
+        throw refused(HTTP_BAD_REQUEST);
+    }
+    if (!(coseKey instanceof Map))
+        throw refused(HTTP_BAD_REQUEST);
+    parsed.credential = { credentialId: bytes.subarray(credentialIdStart, keyStart), coseKey: coseKey };
+    return parsed;
+}
+/**
+ * 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 function coseKeyToJwk(coseKey) {
+    const keyType = coseKey.get(COSE_KEY_TYPE);
+    const algorithm = coseKey.get(COSE_ALGORITHM);
+    if (keyType === COSE_KEY_TYPE_EC2 && algorithm === COSE_ES256 && coseKey.get(COSE_EC2_CURVE) === COSE_CURVE_P256) {
+        return { jwk: { kty: "EC", crv: "P-256", x: base64UrlOf(coseKey.get(COSE_EC2_X)), y: base64UrlOf(coseKey.get(COSE_EC2_Y)) }, algorithm: COSE_ES256 };
+    }
+    if (keyType === COSE_KEY_TYPE_RSA && algorithm === COSE_RS256) {
+        return { jwk: { kty: "RSA", n: base64UrlOf(coseKey.get(COSE_RSA_MODULUS)), e: base64UrlOf(coseKey.get(COSE_RSA_EXPONENT)) }, algorithm: COSE_RS256 };
+    }
+    if (keyType === COSE_KEY_TYPE_OKP && algorithm === COSE_EDDSA && coseKey.get(COSE_OKP_CURVE) === COSE_CURVE_ED25519) {
+        return { jwk: { kty: "OKP", crv: "Ed25519", x: base64UrlOf(coseKey.get(COSE_OKP_X)) }, algorithm: COSE_EDDSA };
+    }
+    throw new AdminRequestError(HTTP_BAD_REQUEST, "the passkey uses an algorithm the console does not accept (ES256, RS256 or EdDSA)");
+}
+/**
+ * A COSE byte string as base64url.
+ * @param value The decoded value.
+ * @returns The base64url text.
+ * @throws AdminRequestError 400 when it is not a byte string.
+ */
+function base64UrlOf(value) {
+    if (!(value instanceof Uint8Array))
+        throw refused(HTTP_BAD_REQUEST);
+    return Buffer.from(value).toString("base64url");
+}
+/**
+ * Verifies an assertion signature with the stored key (ES256 signatures are DER-encoded).
+ * @param passkey The stored passkey.
+ * @param signedBytes authenticatorData || sha256(clientDataJSON).
+ * @param signature The signature.
+ * @returns True when it verifies.
+ */
+function verifySignature(passkey, signedBytes, signature) {
+    try {
+        const key = createPublicKey({ key: passkey.publicKeyJwk, format: "jwk" });
+        if (passkey.algorithm === COSE_EDDSA)
+            return verify(null, signedBytes, key, signature);
+        if (passkey.algorithm === COSE_ES256)
+            return verify("sha256", signedBytes, { key: key, dsaEncoding: "der" }, signature);
+        return verify("sha256", signedBytes, key, signature);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The sign count rule (D31): it must grow, unless both counts are 0 (an authenticator without a counter).
+ * @param storedCount The last count seen.
+ * @param newCount The assertion's count.
+ * @returns True when it is acceptable.
+ */
+function isSignCountValid(storedCount, newCount) {
+    if (storedCount === 0 && newCount === 0)
+        return true;
+    return newCount > storedCount;
+}

package/lib/admin/PlayerRoutes.d.ts

@@ -0,0 +1,20 @@
+import { type AdminApiRouter } from "./AdminApiRouter.js";
+import type { BanRecord } from "./AdminRecords.js";
+import type { AdminServices } from "./AdminServices.js";
+/**
+ * Registers the players/*, lobby/kick and bans/* routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export declare function registerPlayerRoutes(router: AdminApiRouter, services: AdminServices): void;
+/**
+ * Registers this instance's searchPlayers, disconnectBanned and kickFromLobby fleet commands (R15).
+ * @param services The shared services.
+ */
+export declare function registerPlayerCommands(services: AdminServices): void;
+/**
+ * Reads every stored ban into this instance's BanList (at start and on every "bans" change announcement, D15).
+ * @param services The shared services.
+ * @returns Every stored ban.
+ */
+export declare function reloadBanList(services: AdminServices): Promise<BanRecord[]>;