rozod 6.8.0 → 6.9.0

package/lib/index.js

@@ -135,9 +135,119 @@ function prepareRequestBody(method, requestFormat, body, headers) {
     return body;
 }
 const onRobloxSite = 'document' in globalThis && globalThis.location.href.includes('.roblox.com');
-exports.hbaClient = new roblox_bat_1.HBAClient({
+/** How long a failed token metadata lookup is remembered before retrying. */
+const HBA_METADATA_FAILURE_TTL = 5 * 60 * 1000;
+/** Upper bound on the token metadata page fetch. */
+const HBA_METADATA_FETCH_TIMEOUT = 10_000;
+/**
+ * HBAClient hardened for server (Node/Bun) usage:
+ *
+ * - `generateBaseHeaders` short-circuits when no crypto key source exists
+ *   (no supplied key pair and no IndexedDB): a BAT can never be signed, so
+ *   the token metadata page must not be fetched at all.
+ * - `getTokenMetadata` remembers failed lookups for a TTL. The base class
+ *   only caches successes, so an unparseable metadata page (e.g. a bot
+ *   challenge served to a datacenter IP) would otherwise be refetched on
+ *   every request — unbounded network and memory churn on hot paths.
+ * - The metadata page fetch is bounded by a timeout and sent with the
+ *   configured server user agent instead of the runtime default, which is
+ *   far more likely to receive a challenge page.
+ */
+class ServerSafeHBAClient extends roblox_bat_1.HBAClient {
+    metadataFailureAt = 0;
+    metadataInFlight;
+    metadataSource;
+    constructor(props) {
+        super(props);
+        this.metadataSource = props?.metadataSource;
+    }
+    /**
+     * Forget a remembered metadata failure so the next lookup retries
+     * immediately. Called when HBA keys are (re)configured — a lookup that
+     * failed under the old configuration says nothing about the new one.
+     */
+    resetMetadataFailure() {
+        this.metadataFailureAt = 0;
+    }
+    async generateBaseHeaders(requestUrl, requestMethod, includeCredentials, body) {
+        if (!this.suppliedCryptoKeyPair && !('indexedDB' in globalThis)) {
+            return {};
+        }
+        return super.generateBaseHeaders(requestUrl, requestMethod, includeCredentials, body);
+    }
+    async getTokenMetadata(uncached) {
+        // Token metadata is account-agnostic; per-cookie clients delegate to
+        // one shared client so its caches (success, failure TTL, in-flight)
+        // apply pool-wide instead of once per account.
+        if (this.metadataSource) {
+            return this.metadataSource.getTokenMetadata(uncached);
+        }
+        if (!uncached) {
+            if (this.metadataFailureAt && Date.now() - this.metadataFailureAt < HBA_METADATA_FAILURE_TTL) {
+                return null;
+            }
+            // The base class only shares in-flight lookups that resolve
+            // successfully; sharing here makes concurrent callers ride one
+            // lookup even when it fails, instead of each retrying in turn.
+            if (this.metadataInFlight) {
+                return this.metadataInFlight;
+            }
+        }
+        let promise;
+        promise = (async () => {
+            try {
+                const metadata = await super.getTokenMetadata(uncached);
+                this.metadataFailureAt = metadata ? 0 : Date.now();
+                return metadata;
+            }
+            finally {
+                // Guarded so an overlapping lookup's reference is not clobbered
+                if (this.metadataInFlight === promise) {
+                    this.metadataInFlight = undefined;
+                }
+            }
+        })();
+        this.metadataInFlight = promise;
+        return promise;
+    }
+}
+exports.hbaClient = new ServerSafeHBAClient({
     onSite: onRobloxSite,
+    // Applies to every non-on-site context, including extension background
+    // and popup pages: the timeout is desirable everywhere, and browsers
+    // silently drop the user-agent header (it is fetch-forbidden), so this
+    // only takes effect in Node/Bun.
+    ...(onRobloxSite
+        ? {}
+        : {
+            fetch: (url, params) => {
+                const headers = new Headers(params?.headers);
+                if (!headers.has('user-agent')) {
+                    const userAgent = getServerUserAgent();
+                    if (userAgent) {
+                        headers.set('user-agent', userAgent);
+                    }
+                }
+                return globalThis.fetch(url, {
+                    ...params,
+                    headers,
+                    signal: AbortSignal.timeout(HBA_METADATA_FETCH_TIMEOUT),
+                });
+            },
+        }),
 });
+/**
+ * BAT signing clients aligned index-for-index with the configured cookie
+ * pool. `null` marks cookies whose sessions have no registered key. Unset
+ * when hbaKeys was not configured as an array.
+ */
+let perCookieHbaClients;
+function hbaClientForCookie(cookieIndex) {
+    if (cookieIndex === undefined || !perCookieHbaClients) {
+        return exports.hbaClient;
+    }
+    return perCookieHbaClients[cookieIndex] ?? exports.hbaClient;
+}
 // ============================================================================
 // Server/Node.js Configuration
 // ============================================================================
@@ -200,6 +310,38 @@ function configureServer(config) {
     serverConfig.userAgents = config.userAgents;
     serverConfig.userAgentRotation = config.userAgentRotation;
     serverConfig.onCookieRefresh = config.onCookieRefresh;
+    // Keys live on the HBA clients, not in serverConfig — they are the single
+    // source of truth that getServerConfig() reads back from. A single shared
+    // pair is kept when hbaKeys is omitted so changeHBAKeys() callers keep
+    // theirs, but per-cookie keys are positionally bound to the cookies array
+    // passed in the same call: reconfiguring without them must drop them, or
+    // a changed pool would sign with other sessions' keys.
+    if (config.hbaKeys === undefined) {
+        perCookieHbaClients = undefined;
+    }
+    else {
+        if (Array.isArray(config.hbaKeys)) {
+            const poolSize = Array.isArray(config.cookies) ? config.cookies.length : config.cookies ? 1 : 0;
+            if (config.hbaKeys.length !== poolSize) {
+                throw new Error(`hbaKeys array length (${config.hbaKeys.length}) must match the cookie pool length (${poolSize}); use null for cookies without registered keys`);
+            }
+            perCookieHbaClients = config.hbaKeys.map((keys) => keys
+                ? new ServerSafeHBAClient({
+                    onSite: onRobloxSite,
+                    keys,
+                    metadataSource: exports.hbaClient,
+                })
+                : null);
+            // The shared client must not sign: requests that bypass the cookie
+            // pool have no session to match a key to.
+            exports.hbaClient.suppliedCryptoKeyPair = undefined;
+        }
+        else {
+            exports.hbaClient.suppliedCryptoKeyPair = config.hbaKeys;
+            perCookieHbaClients = undefined;
+        }
+        exports.hbaClient.resetMetadataFailure();
+    }
     // Reset indices and session values when config changes
     serverConfig._cookieIndex = 0;
     serverConfig._userAgentIndex = 0;
@@ -216,6 +358,8 @@ function clearServerConfig() {
     serverConfig.userAgents = undefined;
     serverConfig.userAgentRotation = undefined;
     serverConfig.onCookieRefresh = undefined;
+    exports.hbaClient.suppliedCryptoKeyPair = undefined;
+    perCookieHbaClients = undefined;
     serverConfig._cookieIndex = 0;
     serverConfig._userAgentIndex = 0;
     serverConfig._sessionUserAgent = undefined;
@@ -232,6 +376,9 @@ function getServerConfig() {
         userAgents: serverConfig.userAgents,
         userAgentRotation: serverConfig.userAgentRotation,
         onCookieRefresh: serverConfig.onCookieRefresh,
+        hbaKeys: perCookieHbaClients
+            ? perCookieHbaClients.map((client) => client?.suppliedCryptoKeyPair ?? null)
+            : exports.hbaClient.suppliedCryptoKeyPair,
     };
 }
 function selectFromPool(pool, rotation, indexKey, sessionKey) {
@@ -639,10 +786,11 @@ async function fetch(url, info, challengeData, csrfRetries = 0, challengeRetries
         // Normal flow: apply all defaults including cookie selection
         cookieSelection = applyServerDefaults(headers, url);
     }
+    const activeHbaClient = hbaClientForCookie(cookieSelection?.index);
     if (!onRobloxSite) {
-        exports.hbaClient.isAuthenticated = headers.get('cookie')?.includes('.ROBLOSECURITY');
+        activeHbaClient.isAuthenticated = headers.get('cookie')?.includes('.ROBLOSECURITY');
     }
-    const setHeaders = await exports.hbaClient.generateBaseHeaders(url, info?.method, info?.credentials === 'include', info?.body);
+    const setHeaders = await activeHbaClient.generateBaseHeaders(url, info?.method, info?.credentials === 'include', info?.body);
     for (const key in setHeaders) {
         headers.set(key, setHeaders[key]);
     }
@@ -694,10 +842,18 @@ async function fetch(url, info, challengeData, csrfRetries = 0, challengeRetries
 /**
  * Allows you to change the Crypto Key pair used by the internal hardware-based authentication signatures. This should only be used in a NodeJS context.
  *
+ * The pair applies to every request: any per-cookie keys configured via
+ * `configureServer({ hbaKeys: [...] })` are discarded. To key individual
+ * cookies in a pool, use `configureServer` instead.
+ *
  * @param keys The crypto key pair.
  */
 function changeHBAKeys(keys) {
     exports.hbaClient.suppliedCryptoKeyPair = keys;
+    perCookieHbaClients = undefined;
+    if (keys) {
+        exports.hbaClient.resetMetadataFailure();
+    }
 }
 async function handleRetryFetch(url, requestOptions, retries, retryDelay, body, method) {
     let response = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rozod",
-  "version": "6.8.0",
+  "version": "6.9.0",
   "description": "A TypeScript wrapper for the Roblox API",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -50,7 +50,7 @@
   "scripts": {
     "test": "jest --config jestconfig.json",
     "test:exports": "npm run build && node scripts/smoke-test-exports.mjs",
-    "build": "tsc && tsc --project tsconfig.declarations.json",
+    "build": "tsc && tsc --project tsconfig.declarations.json && node scripts/copy-endpoint-declarations.mjs",
     "format": "prettier --write \"src/**/*.ts\"",
     "prepare": "npm run build",
     "prepublishOnly": "npm test && npm run test:exports",