roblox-bat

Handles x-bound-auth-token generation for extensions. It will be enforced on some endpoints by the end of June 2024 at the latest. (via DevForum)

What is x-bound-auth-token

A token generated by the client based on request body and epoch timestamp to give to the server in the headers to “verify itself” as the original session. The crypto key pair is stored in an Indexed DB and is used to sign further requests. The crypto key is generated on authentication (login, signup), it is per-session and is used as hardware-backed authentication.

There is an article on this feature: https://en.help.roblox.com/hc/en-us/articles/18765146769812-Account-Session-Protection, it also details on how to disable it. However, for extensions, asking the user to disable session protection is not feasible, especially when Open Cloud development is slow and extremely restricting.

How it Works

• On the first request, it will fetch metadata from https://www.roblox.com/reference/blank in the meta[name="hardware-backed-authentication-data"] element.
• Any requests to generate a token will check if the URL is supported, and then grab a private key from the Indexed DB hbaStore in the hbaObjectStore with the key hba_keys. The final x-bound-auth-token key should be formatted like:
  • Currently: v1|sha256ofrequestbody|timestamp|signature
    • Previously: sha256ofrequestbody|timestamp|signatureoffirst2
• If the URL is supported and it could find a key, generateBaseHeaders will return {"x-bound-auth-token": string}, otherwise {}

Usage

In the Browser, it must be in a context where it has access to www.roblox.com’s indexedDB. This is also a likely reason why web.roblox.com was merged into www.roblox.com.

const hbaClient = new HBAClient({
    onSite: true,
});

In server-side runtimes (Bun, NodeJS, Deno), you will have to supply the key yourself or generate one:

const hbaClient = new HBAClient({
    keys: await crypto.subtle.generateKey(
        {
            name: "ECDSA",
            namedCurve: "P-256",
        },
        false,
        ["sign"],
    ),
    // We need to supply the cookie to tell that the client is authenticated, otherwise we can set hbaClient.isAuthenticated externally.
    cookie: ".ROBLOSECURITY=...",
});

• GET Requests

import { HBAClient } from "roblox-bat";

const hbaClient = new HBAClient({
    onSite: true,
    // Or use "keys": CryptoKeyPair
});
// {"x-bound-auth-token": string}
const headers = await hbaClient.generateBaseHeaders(
    "https://users.roblox.com/v1/users/authenticated",
    "GET",
    true, // set to false or undefined if not authenticated
);

await fetch("https://users.roblox.com/v1/users/authenticated", {
    headers,
    credentials: "include",
});

• Requests with a body (POST, PUT, PATCH, DELETE)

import { HBAClient } from "roblox-bat";

const hbaClient = new HBAClient({
    onSite: true,
    // Or use "keys": CryptoKeyPair
});
const body = JSON.stringify({
    items: [
        {
            itemType: "Asset",
            id: 1028593,
        },
    ],
});
// {"x-bound-auth-token": string}
const headers = await hbaClient.generateBaseHeaders(
    "https://catalog.roblox.com/v1/catalog/items/details",
    "POST",
    true, // set to false or undefined if not authenticated
    body,
);

await fetch("https://catalog.roblox.com/v1/catalog/items/details", {
    method: "POST",
    headers: {
        ...headers,
        "content-type": "application/json",
    },
    body,
    credentials: "include",
});