@tilua-types/bridge 1.0.0 → 2.1.0

package/README.md

@@ -40,6 +40,55 @@ Every handler of a name runs, on the server and the client alike, and what comes
 before the first one waits for it, up to 256 messages. A name still without a
 handler after ten seconds is warned about.
 
+What a side sends in one frame goes out together at the next `Heartbeat`, in the
+order it was sent: one sealed packet from a client — or as few as fit under
+`bridgeMaxPacket` — and one remote call to each player from the server, or a
+single `FireAllClients` when the frame held only `sendAll`. So `bridgeRateLimit`
+counts packets, not messages.
+
+### A handler's own limits
+
+A handler can take its own limits as a third argument, on top of the config's:
+
+```ts
+bridge.onServer("Chat", (player: Player, text: string) => { ... }, {
+    rateLimit: 5,    // messages of this name a player may have it run a second
+    maxPacket: 512,  // the largest message, in bytes of its arguments as JSON
+})
+```
+
+Past either, the message is dropped for that handler alone — before its
+arguments are decoded — and another handler of the name still gets it. The
+first message over `maxPacket` is warned about. Neither is a breach: the client
+does not know a handler's limits, so a fair one can cross them. `onClient` takes
+the same options, counted per handler.
+
+### Asking the server
+
+`bridge.invoke` asks the server and waits for its answer, through a RemoteFunction:
+
+```ts
+// server: one handler a name; what it returns goes back
+bridge.onInvoke("Price", (player: Player, item: string) => {
+    return prices[item]
+})
+
+// client
+const price = bridge.invoke("Price", "sword")
+```
+
+The request is sealed and numbered like a packet, on a count of its own, and
+counts toward `bridgeRateLimit`; the answer comes back plain, to that client
+alone, carrying what arguments carry. What the client sent before the invoke goes
+out first, so the handler sees it. `onInvoke` takes a handler's limits as
+`onServer` does. The handler runs on the invoke's own thread, so it may yield.
+
+`invoke` raises when there is no answer: no handler within ten seconds (the invoke
+waits for one, as a message would), over the handler's limits, or the handler
+failed. The client is told only that — the error itself is warned on the server.
+A handler that returns nothing answers `nil`. There is no invoke from the server
+to a client: a client that never answers would hold the server's thread for good.
+
 What cannot run does not build: `bridge` read as a value, a `.client` script
 calling a server's member or the other way round, and any output but `"files"`.
 
@@ -52,6 +101,10 @@ calling a server's member or the other way round, and any output but `"files"`.
   secret. A token the build did not make is a breach and gets nothing. A real one
   claims as often as it is offered: the game can clone any script, and it runs
   again wherever it lands, so a second claim cannot be told from a replay.
+  The claim's strings — the module's path, the place and the token — are
+  encrypted in the file, so neither reading the script's constants nor searching
+  its source turns up a token to replay (`bridgeObfuscate: false` leaves them as
+  written).
 - **Nothing hands it out.** The module's value is that one claim function. The
   handle is a local of the file: not in its exports, not in tilua's runtime
   (`G`, which anything can `require`). `bridge` read as a value — kept,
@@ -69,6 +122,12 @@ calling a server's member or the other way round, and any output but `"files"`.
   salt: the real remotes are named by it under the secret, in a folder named
   after it, shuffled among the decoys, so a name kept from another server finds
   nothing. The client renames the real ones once found, in the decoys' form.
+- **Honeypots.** One decoy RemoteEvent and one decoy RemoteFunction are named by
+  the salt too. The game's client fires the first beside every packet and
+  invokes the second beside every invoke, each with a number one past the last,
+  sealed with AES-GCM, so a spy watching the remotes sees them carry traffic like
+  the real ones. The server lets the next number be; anything else through them —
+  a blob it did not seal, or a replay of one it did — is a breach.
 
 On the client a breach is reported to the server through the bridge.
 
@@ -76,7 +135,7 @@ On the client a breach is reported to the server through the bridge.
 
 With no handler, a breach bans the player for good across the experience, their
 alt accounts too, through `Players:BanAsync`; a ban that fails is a kick. In Studio
-it only warns. A file that loads within five seconds of the breach can still take
+it is a kick that says why, and no ban. A file that loads within five seconds of the breach can still take
 it. To answer another way, register a handler on the server, which replaces the
 ban entirely:
 
@@ -109,41 +168,46 @@ those. Two more things to know:
 
 Each build writes the module beside tilua's runtime — `shared/_bridge.luau` in the
 output of a project laid out by `tilua init` — with that build's secret inside,
-obfuscated with [lua-obfuscator](https://www.npmjs.com/package/lua-obfuscator). The
+obfuscated with [luau-obfuscator](https://www.npmjs.com/package/luau-obfuscator). The
 secret is kept nowhere else, so there is nothing to set up or check in. `--watch`
-keeps one secret while it runs. A project from before this has a
+keeps one secret while it runs. A Rojo project isn't needed: without one the module
+is written as `_bridge.luau` in `outDir`, and each file requires it by its relative
+path (`require("../_bridge")`). With one, files reach it from `game`, as before.
+A project from before this has a
 `src/shared/_bridge.luau` and a `.tilua` folder to delete.
 
 The module runs in one Luau VM: calling `bridge` from an Actor stops with an error
 saying so.
 
-Client to server, arguments travel as JSON: strings, numbers, booleans, and tables
-of them. Not Instances, and no `nil` between arguments. Server to client they are
-a remote's arguments, as they are.
-
-The obfuscation hides the secret and every string in the module, but not the
-names of members it reads (`.OnServerInvoke`, `crypto.aesGcm`): lua-obfuscator
-keeps `a.b`'s `b` as written.
-
-## Tested
-
-`npm test` in the repository compiles a project with it — claims only in the
-files that call `bridge`, nothing in the runtime or the exports — and runs the
-module as server and client over a fake network, plain and obfuscated: traffic
-both ways, then a late executor making up a token, firing the packet remote with
-its own bytes and with a captured packet, asking for the
-key, and firing and invoking every decoy. Each is refused and reported. The
-network is a fake: nothing here has run in Roblox.
+Both ways, arguments travel as JSON: strings, numbers, booleans, `nil` — between
+and after the others too, counted as `select("#", ...)` counts them — and tables
+of them. An Instance travels as its path of names from `game` and is looked up
+again on arrival, the first child of each name: one the other side does not have
+— not replicated, destroyed, or in no game — arrives as `nil`, inside a table as a
+missing key. Roblox's value types travel as their components and are made again
+on arrival: `Vector3`, `Vector2`, `Vector3int16`, `Vector2int16`, `CFrame`,
+`Color3`, `BrickColor`, `UDim`, `UDim2`, `Rect`, `NumberRange`,
+`NumberSequence`, `ColorSequence`, `Ray`, `Region3` (axis-aligned, as
+`Region3.new` makes it), `PhysicalProperties`, `DateTime`, and an `EnumItem` by
+its enum's name and its own. Each is checked part by part where it arrives — as
+many numbers as it takes — and one that does not make the type is `nil`. The rest
+(`Font`, `TweenInfo`, …) is what `JSONEncode` makes of it. A table key that starts
+with `\1` is the bridge's mark, so a key of the game's that does is escaped on the
+way and arrives as it was.
+
+The obfuscation hides the secret, every string in the module, and the names of
+the members it reads (`.OnServerInvoke`, `crypto.aesGcm`): luau-obfuscator runs the
+whole module in its VM, so none of them is left in the source as written.
 
 <!-- compatibility:start -->
 ## Compatibility
 
-`@tilua-types/bridge@1.0.0` works with these tilua packages. *Released with* is the
+`@tilua-types/bridge@2.1.0` works with these tilua packages. *Released with* is the
 version it was built and tested against.
 
 | Package | Range | Released with | |
 | --- | --- | --- | --- |
 | `@tilua-types/crypto` | `^1.0.0` | 1.0.0 | dependency |
 | `@tilua-types/roblox` | `^10.1.2` | 10.1.2 | dependency |
-| `@tilua/parser` | `^9.1.2` | 9.1.2 | peer |
+| `@tilua/parser` | `^9.1.2` | 9.1.4 | peer |
 <!-- compatibility:end -->

package/generate.mjs

@@ -1,70 +1,93 @@
-// @ts-check
-/**
- * The game's own bridge module: runtime/bridge.luau with the secret, the limits,
- * the decoy count and the crypto runtime filled in, then obfuscated. The build
- * writes it; the tests make it the same way.
- */
-import { existsSync, readFileSync } from "node:fs"
-import { createRequire } from "node:module"
-import { dirname, join } from "node:path"
-import { fileURLToPath } from "node:url"
-
-const here = dirname(fileURLToPath(import.meta.url))
-const require = createRequire(import.meta.url)
-
-/** @tilua-types/crypto's runtime: from its package, or the checkout beside this one. */
-function cryptoRuntime() {
-    let folder
-    try {
-        folder = dirname(require.resolve("@tilua-types/crypto/package.json"))
-    } catch {
-        folder = join(here, "..", "crypto")
-    }
-    const file = join(folder, "runtime", "crypto.luau")
-    if (!existsSync(file)) throw new Error("@tilua-types/crypto is not installed")
-    return readFileSync(file, "utf8")
-}
-
-/** The table the crypto runtime is built into, inside the bridge module. */
-const CRYPTO = "BridgeCrypto"
-
-/**
- * The module's Luau before obfuscation.
- * @param {{ secret: string, decoys?: number, maxPacket?: number, rateLimit?: number }} options
- */
-export function bridgeSource({ secret, decoys = 4, maxPacket = 65536, rateLimit = 120 }) {
-    if (!/^[0-9a-f]{32,}$/.test(secret)) throw new Error("A bridge secret is at least 32 hex characters")
-    // Function replacers throughout: the crypto runtime holds `$` characters a
-    // replacement string would read as patterns.
-    return readFileSync(join(here, "runtime", "bridge.luau"), "utf8")
-        .replace("__SECRET__", () => JSON.stringify(secret))
-        .replace("__DECOYS__", () => String(decoys))
-        .replace("__MAX_PACKET__", () => String(maxPacket))
-        .replace("__RATE_LIMIT__", () => String(rateLimit))
-        .replace("__CRYPTO_NAME__", () => CRYPTO)
-        .replace("__CRYPTO__", () => cryptoRuntime().replace(/__NAME__/g, CRYPTO))
-}
-
-/** What the module goes through: every pass lua-obfuscator has, the VM included. */
-export const OBFUSCATION_STEPS = [
-    { name: "InsertJunk" },
-    { name: "RenameVariables" },
-    { name: "Vmify" },
-    { name: "ConstantArray" },
-    { name: "GlobalMapping" },
-    { name: "StringsToExpressions" },
-    { name: "NumbersToExpressions" },
-    { name: "EncryptStrings" },
-    { name: "EncryptNumbers" },
-    { name: "WrapInFunction" },
-]
-
-/**
- * The module, obfuscated.
- * @param {string} source
- * @param {{ steps?: readonly object[] }} [options]
- */
-export async function obfuscateBridge(source, { steps = OBFUSCATION_STEPS } = {}) {
-    const { obfuscate } = await import("lua-obfuscator")
-    return obfuscate(source, "luaU", { steps: /** @type {any} */ (steps), minify: true })
-}
+// @ts-check
+/**
+ * The game's own bridge module: runtime/bridge.luau with the secret, the limits,
+ * the decoy count and the crypto runtime filled in, then obfuscated. The build
+ * writes it; the tests make it the same way.
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { obfuscate } from "luau-obfuscator"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+
+/** @tilua-types/crypto's runtime: from its package, or the checkout beside this one. */
+function cryptoRuntime() {
+    let folder
+    try {
+        folder = dirname(require.resolve("@tilua-types/crypto/package.json"))
+    } catch {
+        folder = join(here, "..", "crypto")
+    }
+    const file = join(folder, "runtime", "crypto.luau")
+    if (!existsSync(file)) throw new Error("@tilua-types/crypto is not installed")
+    return readFileSync(file, "utf8")
+}
+
+/** The table the crypto runtime is built into, inside the bridge module. */
+const CRYPTO = "BridgeCrypto"
+
+/**
+ * The module's Luau before obfuscation.
+ * @param {{ secret: string, decoys?: number, maxPacket?: number, rateLimit?: number }} options
+ */
+export function bridgeSource({ secret, decoys = 4, maxPacket = 65536, rateLimit = 120 }) {
+    if (!/^[0-9a-f]{32,}$/.test(secret)) throw new Error("A bridge secret is at least 32 hex characters")
+    // Function replacers throughout: the crypto runtime holds `$` characters a
+    // replacement string would read as patterns.
+    return readFileSync(join(here, "runtime", "bridge.luau"), "utf8")
+        .replace("__SECRET__", () => JSON.stringify(secret))
+        .replace("__DECOYS__", () => String(decoys))
+        .replace("__MAX_PACKET__", () => String(maxPacket))
+        .replace("__RATE_LIMIT__", () => String(rateLimit))
+        .replace("__CRYPTO_NAME__", () => CRYPTO)
+        .replace("__CRYPTO__", () => cryptoRuntime().replace(/__NAME__/g, CRYPTO))
+}
+
+/**
+ * What the module goes through: every pass luau-obfuscator has, the VM included,
+ * each with the package's own defaults.
+ * @type {import("luau-obfuscator").ObfuscatePartialConfig}
+ */
+export const OBFUSCATION_CONFIG = {
+    InsertJunk: { active: true },
+    RenameVariables: { active: true },
+    Vmify: { active: true },
+    ConstantArray: { active: true },
+    GlobalMapping: { active: true },
+    StringsToExpressions: { active: true },
+    NumbersToExpressions: { active: true },
+    EncryptStrings: { active: true },
+    EncryptNumbers: { active: true },
+    WrapInFunction: { active: true },
+    Minify: { active: true },
+}
+
+/**
+ * The module, obfuscated.
+ * @param {string} source
+ * @param {{ config?: import("luau-obfuscator").ObfuscatePartialConfig }} [options]
+ */
+export async function obfuscateBridge(source, { config = OBFUSCATION_CONFIG } = {}) {
+    return obfuscate(source, config)
+}
+
+/**
+ * What a claim goes through: its strings encrypted — the token, the place and
+ * the module's path — and nothing else, so the claim stays a local of the file
+ * by its own name, and the file stays small.
+ * @type {import("luau-obfuscator").ObfuscatePartialConfig}
+ */
+const CLAIM_CONFIG = Object.fromEntries(
+    Object.keys(OBFUSCATION_CONFIG).map(pass => [pass, { active: pass === "EncryptStrings" }]),
+)
+
+/**
+ * A file's claim line, its strings encrypted.
+ * @param {string} claim
+ */
+export function obfuscateClaim(claim) {
+    return obfuscate(claim, CLAIM_CONFIG)
+}

package/index.d.tilua

@@ -3,36 +3,60 @@
 --
 --     -- client
 --     bridge.send("Buy", "sword", 2)
+--     const price = bridge.invoke("Price", "sword")
 --     bridge.onClient("Toast", (text: string) => { ... })
 --
 --     -- server
---     bridge.onServer("Buy", (player: Player, item: string, count: number) => { ... })
+--     bridge.onServer("Buy", (player: Player, item: string, count: number) => { ... }, { rateLimit: 5 })
 --     bridge.sendTo(player, "Toast", "bought")
+--     bridge.onInvoke("Price", (player: Player, item: string) => { return 100 })
 --     bridge.onBreach((player: Player, reason: string) => { player:Kick() })
 --
 -- `bridge` is only ever called. Kept in a variable, exported or passed along, it
 -- does not build: the handle stays in the file that claimed it. Each file that
 -- calls it claims it as it loads.
 --
--- Arguments travel as JSON: strings, numbers, booleans, and tables of them.
--- Client to server, each packet is sealed with AES-GCM and numbered.
+-- Arguments travel as JSON: strings, numbers, booleans, `nil`, and tables of
+-- them, and Instances by their path from `game`, found again on arrival — `nil`
+-- where the other side has nothing there. Vector3, CFrame, Color3, UDim2, EnumItem
+-- and Roblox's other value types go by their components and are made again. What
+-- is sent in one frame goes as one
+-- packet at the next Heartbeat. Client to server, each packet is sealed with
+-- AES-GCM and numbered.
+
+-- A handler's own limits, on top of the bridge's. Past either, a message is
+-- dropped before its arguments are decoded. 0 or missing for no limit.
+type bridge.HandlerOptions = {
+    -- Messages of this name a sender may have this handler run a second
+    rateLimit?: number,
+    -- The largest message, in bytes of its arguments as JSON
+    maxPacket?: number,
+}
 
 declare bridge: {
     -- Client: to the server's handler of that name
     send: (name: string, ...args: any[]) => void,
+    -- Client: the server's onInvoke handler of that name, waited for: what it
+    -- returns. An error when there is no answer — no handler within ten
+    -- seconds, over its limits, or the handler failed.
+    invoke: (name: string, ...args: any[]) => any,
     -- Client: what the server sends by that name. Every handler of a name runs;
     -- what comes before the first waits for it.
-    onClient: (name: string, handler: (...args: any[]) => void) => void,
+    onClient: (name: string, handler: (...args: any[]) => void, options?: bridge.HandlerOptions) => void,
     -- Server: what a client sends by that name, with the player first. Every
     -- handler of a name runs; what comes before the first waits for it.
-    onServer: (name: string, handler: (player: Player, ...args: any[]) => void) => void,
+    onServer: (name: string, handler: (player: Player, ...args: any[]) => void, options?: bridge.HandlerOptions) => void,
+    -- Server: what answers a client's bridge.invoke of that name, with the player
+    -- first; what it returns goes back. One handler a name.
+    onInvoke: (name: string, handler: (player: Player, ...args: any[]) => any, options?: bridge.HandlerOptions) => void,
     -- Server: to one client
     sendTo: (player: Player, name: string, ...args: any[]) => void,
     -- Server: to every client
     sendAll: (name: string, ...args: any[]) => void,
     -- Server: a client used a token it did not earn, sent a packet the bridge
     -- did not seal, sent one twice or over bridgeMaxPacket, asked for its key
-    -- twice, or touched a decoy. A handler is the game's whole answer. With none,
-    -- the player and their alt accounts are banned for good.
+    -- twice, touched a decoy, or replayed a honeypot. A handler is the game's
+    -- whole answer. With none, the player and their alt accounts are banned for
+    -- good; in Studio the player is kicked instead.
     onBreach: (handler: (player: Player, reason: string) => void) => void,
 }