@tilua-types/bridge 2.0.0 → 2.1.0

package/README.md

@@ -101,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,
@@ -164,9 +168,12 @@ 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
@@ -188,25 +195,14 @@ many numbers as it takes — and one that does not make the type is `nil`. The r
 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 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, one packet a frame each way in order, invokes answered and refused, Instances, value types and `nil`s found again,
-each handler's limits, 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.
+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@2.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 | |

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/lowering.mjs

@@ -1,187 +1,228 @@
-// @ts-check
-/**
- * What tilua lowers for `bridge`, and the module it writes.
- *
- * `bridge.send("Buy", item)` is a call of a handle the file holds in a local:
- * `__tilua_bridge.send("Buy", item)`. That local is the first line of every
- * file that calls `bridge`, put there as the host's prelude:
- *
- *     local __tilua_bridge = require(<the bridge module>)("<place>", "<token>")
- *
- * where the token is the HMAC of the file's place under the build's secret. It
- * is a local of the file, so neither the module's exports nor the runtime's
- * table (`G`, which anything can `require`) ever hold it. The bridge module
- * hands a handle to whoever offers a place's token, as often as it is offered:
- * the game can clone any script, and it runs again where it lands.
- *
- * Each build has a new secret, so its tokens and its module go with it: what was
- * read from one update is no use on the next. A watching process keeps one, or
- * every file would change on every save.
- *
- * `bridge` read as a value — kept in a variable, exported, passed along — would
- * carry the handle out of the file, so it does not build. Nor does calling a
- * member a `.client` or `.server` file cannot run.
- *
- * The layout is `@tilua-types/roblox`'s, with the claim added to its prelude.
- */
-import { createHmac, randomBytes } from "node:crypto"
-import { dirname, join, relative, resolve, sep } from "node:path"
-import { luauString } from "@tilua/parser"
-import roblox from "@tilua-types/roblox/lowering.mjs"
-import { bridgeSource, obfuscateBridge } from "./generate.mjs"
-
-/** @typedef {import("@tilua/parser").LoweringPlugin} LoweringPlugin */
-
-const HANDLE = "__tilua_bridge"
-const CLIENT_MEMBERS = new Set(["send", "invoke", "onClient"])
-const SERVER_MEMBERS = new Set(["onServer", "onInvoke", "sendTo", "sendAll", "onBreach"])
-/** Members taking a handler, which runs on a thread of the module's. */
-const HANDLERS = new Set(["onClient", "onServer", "onInvoke", "onBreach"])
-export const MODULE_NAME = "_bridge.luau"
-
-/** A handler runs on a thread the module starts, away from the `xpcall` that
- *  reports errors in the project's files: the same guard roblox's `task.spawn`
- *  gives a callback. */
-const GUARD = `local __NAME__ = {}
-local fail = __FAIL__
-
-function __NAME__.guard(callback)
-	if fail == nil then
-		return callback
-	end
-	return function(...)
-		local results = table.pack(xpcall(callback, fail, ...))
-		if not results[1] then
-			error(results[2], 0)
-		end
-		return table.unpack(results, 2, results.n)
-	end
-end
-`
-
-/** The files that called `bridge` in this build, as the call sites name them. */
-const used = new Set()
-
-/** A secret and its module for each project this process builds, so a watching
- *  build writes the same files until something changes them. */
-const projects = new Map()
-
-/** @param {string} message */
-const raise = message => `error(${luauString(message)}, 0)`
-
-const REFUSED = "bridge: the module refused this file's claim: it is from another build — see the warnings above"
-
-/** @param {string | undefined} file */
-const sideOf = file => (file?.endsWith(".client.tilua") ? "client" : file?.endsWith(".server.tilua") ? "server" : undefined)
-
-/** @param {string} directory */
-function projectOf(directory) {
-    let project = projects.get(directory)
-    if (!project) {
-        project = { secret: randomBytes(32).toString("hex"), modules: new Map() }
-        projects.set(directory, project)
-    }
-    return project
-}
-
-/** @type {LoweringPlugin} */
-const plugin = {
-    runtime: { guard: GUARD },
-
-    globalCall({ name, at, perFile, report, use }) {
-        if (name === "bridge") {
-            report("bridge is not a function: call one of its members, as bridge.send(...)")
-            return { callee: "error" }
-        }
-        if (!name.startsWith("bridge.")) return undefined
-        const member = name.slice("bridge.".length)
-        // A member that is not one is the type checker's to say
-        if (!CLIENT_MEMBERS.has(member) && !SERVER_MEMBERS.has(member)) return { callee: `(function() ${raise(`bridge has no member '${member}'`)} end)` }
-        if (!perFile) report(`bridge.${member}: the bridge needs "output": "files", where each file claims its own handle`)
-        const side = sideOf(at.file)
-        if (side === "client" && SERVER_MEMBERS.has(member)) report(`bridge.${member} runs on the server, and this is a client script`)
-        if (side === "server" && CLIENT_MEMBERS.has(member)) report(`bridge.${member} runs on the client, and this is a server script`)
-        if (at.file !== undefined) used.add(at.file)
-        const handle = `(${HANDLE} or ${raise(REFUSED)})`
-        if (!HANDLERS.has(member)) return { callee: `${handle}.${member}` }
-        const guard = `${use("guard")}.guard`
-        return {
-            callee: member === "onBreach"
-                ? `(function(handler) ${handle}.${member}(${guard}(handler)) end)`
-                : `(function(name, handler, options) ${handle}.${member}(name, ${guard}(handler), options) end)`,
-        }
-    },
-
-    globalValue({ name, report }) {
-        if (name === "bridge" || name.startsWith("bridge.")) {
-            report("bridge can only be called — bridge.send(...) — never kept, passed or exported")
-            return "nil"
-        }
-        return undefined
-    },
-
-    files(layout) {
-        // A new build: what calls `bridge` is gathered again as it lowers
-        used.clear()
-        const base = roblox.files?.(layout) ?? {}
-        const problems = [...(base.problems ?? [])]
-        const project = projectOf(layout.directory)
-
-        // The module sits beside the runtime, where every script reaches it
-        const modulePath = join(dirname(base.runtime ?? layout.runtime), MODULE_NAME)
-        const place = base.place?.(modulePath)
-        if (!place) problems.push({ message: `Nothing in the Rojo project puts ${MODULE_NAME} in the game` })
-        const locate = place && [
-            `game:GetService(${luauString(place[0])})`,
-            ...place.slice(1).map(part => `:WaitForChild(${luauString(part)})`),
-        ].join("")
-
-        /** @param {string} file */
-        const callsBridge = file => {
-            const written = relative(layout.outDir, file).split(sep).join("/")
-            for (const source of used) {
-                const output = relative(layout.rootDir, resolve(layout.directory, source)).split(sep).join("/").replace(/\.tilua$/, ".luau")
-                if (output === written) return true
-            }
-            return false
-        }
-
-        return {
-            ...base,
-            problems,
-            prelude(file) {
-                const before = base.prelude?.(file)
-                if (!locate || !callsBridge(file)) return before
-                const inGame = base.place?.(file) ?? [relative(layout.outDir, file)]
-                // A module and a script of one name share a place in the game
-                const kind = /\.(server|client|local|legacy|plugin)\.luau?$/.exec(file)?.[1]
-                const where = `${inGame.join("/")}${kind ? `.${kind}` : ""}`
-                const token = createHmac("sha256", project.secret).update(where).digest("hex")
-                const claim = `local ${HANDLE} = require(${locate})(${luauString(where)}, ${luauString(token)})`
-                return before === undefined ? claim : `${before}\n${claim}`
-            },
-            async output() {
-                if (!place || !used.size) return { files: [] }
-                const { bridgeMaxPacket: maxPacket, bridgeRateLimit: rateLimit, bridgeObfuscate } = layout.options
-                const key = JSON.stringify([maxPacket, rateLimit, bridgeObfuscate])
-                if (!project.modules.has(key)) {
-                    const source = bridgeSource({
-                        secret: project.secret,
-                        maxPacket: typeof maxPacket === "number" ? maxPacket : undefined,
-                        rateLimit: typeof rateLimit === "number" ? rateLimit : undefined,
-                    })
-                    project.modules.set(key, bridgeObfuscate === false ? source : await obfuscateBridge(source))
-                }
-                const clientOnly = [...used].every(file => sideOf(file) === "client")
-                return {
-                    files: [{ file: modulePath, code: project.modules.get(key) }],
-                    problems: clientOnly
-                        ? [{ severity: /** @type {const} */ ("warning"), message: "Only client scripts call bridge: nothing starts it on the server, so the clients will wait for it" }]
-                        : [],
-                }
-            },
-        }
-    },
-}
-
-export default plugin
+// @ts-check
+/**
+ * What tilua lowers for `bridge`, and the module it writes.
+ *
+ * `bridge.send("Buy", item)` is a call of a handle the file holds in a local:
+ * `__tilua_bridge.send("Buy", item)`. That local is the first line of every
+ * file that calls `bridge`, put there as the host's prelude:
+ *
+ *     local __tilua_bridge = require(<the bridge module>)("<place>", "<token>")
+ *
+ * where the token is the HMAC of the file's place under the build's secret. It
+ * is a local of the file, so neither the module's exports nor the runtime's
+ * table (`G`, which anything can `require`) ever hold it. The bridge module
+ * hands a handle to whoever offers a place's token, as often as it is offered:
+ * the game can clone any script, and it runs again where it lands.
+ *
+ * Each build has a new secret, so its tokens and its module go with it: what was
+ * read from one update is no use on the next. A watching process keeps one, or
+ * every file would change on every save.
+ *
+ * `bridge` read as a value — kept in a variable, exported, passed along — would
+ * carry the handle out of the file, so it does not build. Nor does calling a
+ * member a `.client` or `.server` file cannot run.
+ *
+ * The layout is `@tilua-types/roblox`'s, with the claim added to its prelude.
+ */
+import { createHmac, randomBytes } from "node:crypto"
+import { dirname, join, relative, resolve, sep } from "node:path"
+import { luauString } from "@tilua/parser"
+import roblox from "@tilua-types/roblox/lowering.mjs"
+import { bridgeSource, obfuscateBridge, obfuscateClaim } from "./generate.mjs"
+
+/** @typedef {import("@tilua/parser").LoweringPlugin} LoweringPlugin */
+
+const HANDLE = "__tilua_bridge"
+const CLIENT_MEMBERS = new Set(["send", "invoke", "onClient"])
+const SERVER_MEMBERS = new Set(["onServer", "onInvoke", "sendTo", "sendAll", "onBreach"])
+/** Members taking a handler, which runs on a thread of the module's. */
+const HANDLERS = new Set(["onClient", "onServer", "onInvoke", "onBreach"])
+export const MODULE_NAME = "_bridge.luau"
+
+/** A handler runs on a thread the module starts, away from the `xpcall` that
+ *  reports errors in the project's files: the same guard roblox's `task.spawn`
+ *  gives a callback. */
+const GUARD = `local __NAME__ = {}
+local fail = __FAIL__
+
+function __NAME__.guard(callback)
+	if fail == nil then
+		return callback
+	end
+	return function(...)
+		local results = table.pack(xpcall(callback, fail, ...))
+		if not results[1] then
+			error(results[2], 0)
+		end
+		return table.unpack(results, 2, results.n)
+	end
+end
+`
+
+/** The files that called `bridge` in this build, as the call sites name them. */
+const used = new Set()
+
+/** A secret, its module and its files' claims for each project this process
+ *  builds, so a watching build writes the same files until something changes
+ *  them: obfuscating anew would change every one. */
+const projects = new Map()
+
+/** @param {string} message */
+const raise = message => `error(${luauString(message)}, 0)`
+
+const REFUSED = "bridge: the module refused this file's claim: it is from another build — see the warnings above"
+
+/** @param {string | undefined} file */
+const sideOf = file => (file?.endsWith(".client.tilua") ? "client" : file?.endsWith(".server.tilua") ? "server" : undefined)
+
+/** @param {string} directory */
+function projectOf(directory) {
+    let project = projects.get(directory)
+    if (!project) {
+        project = { secret: randomBytes(32).toString("hex"), modules: new Map(), claims: new Map() }
+        projects.set(directory, project)
+    }
+    return project
+}
+
+/** @type {LoweringPlugin} */
+const plugin = {
+    runtime: { guard: GUARD },
+
+    globalCall({ name, at, perFile, report, use }) {
+        if (name === "bridge") {
+            report("bridge is not a function: call one of its members, as bridge.send(...)")
+            return { callee: "error" }
+        }
+        if (!name.startsWith("bridge.")) return undefined
+        const member = name.slice("bridge.".length)
+        // A member that is not one is the type checker's to say
+        if (!CLIENT_MEMBERS.has(member) && !SERVER_MEMBERS.has(member)) return { callee: `(function() ${raise(`bridge has no member '${member}'`)} end)` }
+        if (!perFile) report(`bridge.${member}: the bridge needs "output": "files", where each file claims its own handle`)
+        const side = sideOf(at.file)
+        if (side === "client" && SERVER_MEMBERS.has(member)) report(`bridge.${member} runs on the server, and this is a client script`)
+        if (side === "server" && CLIENT_MEMBERS.has(member)) report(`bridge.${member} runs on the client, and this is a server script`)
+        if (at.file !== undefined) used.add(at.file)
+        const handle = `(${HANDLE} or ${raise(REFUSED)})`
+        if (!HANDLERS.has(member)) return { callee: `${handle}.${member}` }
+        const guard = `${use("guard")}.guard`
+        return {
+            callee: member === "onBreach"
+                ? `(function(handler) ${handle}.${member}(${guard}(handler)) end)`
+                : `(function(name, handler, options) ${handle}.${member}(name, ${guard}(handler), options) end)`,
+        }
+    },
+
+    globalValue({ name, report }) {
+        if (name === "bridge" || name.startsWith("bridge.")) {
+            report("bridge can only be called — bridge.send(...) — never kept, passed or exported")
+            return "nil"
+        }
+        return undefined
+    },
+
+    files(layout) {
+        // A new build: what calls `bridge` is gathered again as it lowers
+        used.clear()
+        const base = roblox.files?.(layout) ?? {}
+        const project = projectOf(layout.directory)
+
+        // The module sits beside the runtime, where every script reaches it
+        const modulePath = join(dirname(base.runtime ?? layout.runtime), MODULE_NAME)
+        // Where a file is in the game: the Rojo project's place for it, or —
+        // with no project to say — its path under outDir, as tilua places it
+        /** @param {string} file */
+        const placeOf = file => base.place?.(file) ?? placeInFolder(relative(layout.outDir, file))
+        const modulePlace = base.place?.(modulePath)
+        /** How `file` reaches the module: by its place from `game` when the
+         *  Rojo project puts it there, by the path between them otherwise.
+         *  @param {string} file */
+        const locate = file => modulePlace
+            ? [
+                `game:GetService(${luauString(modulePlace[0])})`,
+                ...modulePlace.slice(1).map(part => `:WaitForChild(${luauString(part)})`),
+            ].join("")
+            : luauString(pathBetween(placeOf(file), placeOf(modulePath), base.root))
+
+        /** @param {string} file */
+        const callsBridge = file => {
+            const written = relative(layout.outDir, file).split(sep).join("/")
+            for (const source of used) {
+                const output = relative(layout.rootDir, resolve(layout.directory, source)).split(sep).join("/").replace(/\.tilua$/, ".luau")
+                if (output === written) return true
+            }
+            return false
+        }
+
+        return {
+            ...base,
+            prelude(file) {
+                const before = base.prelude?.(file)
+                if (!callsBridge(file)) return before
+                // A module and a script of one name share a place in the game
+                const kind = /\.(server|client|local|legacy|plugin)\.luau?$/.exec(file)?.[1]
+                // A place by path still has the kind in its name: once is enough
+                const placed = placeOf(file).join("/")
+                const inGame = kind && placed.endsWith(`.${kind}`) ? placed.slice(0, -kind.length - 1) : placed
+                const where = `${inGame}${kind ? `.${kind}` : ""}`
+                const token = createHmac("sha256", project.secret).update(where).digest("hex")
+                const plain = `local ${HANDLE} = require(${locate(file)})(${luauString(where)}, ${luauString(token)})`
+                // The token is all a claim needs, so it is not left in the file
+                // as written, nor where the module is: hidden as the module is
+                let claim = plain
+                if (layout.options.bridgeObfuscate !== false) {
+                    claim = project.claims.get(plain)
+                    if (claim === undefined) {
+                        claim = obfuscateClaim(plain)
+                        project.claims.set(plain, claim)
+                    }
+                }
+                return before === undefined ? claim : `${before}\n${claim}`
+            },
+            async output() {
+                if (!used.size) return { files: [] }
+                const { bridgeMaxPacket: maxPacket, bridgeRateLimit: rateLimit, bridgeObfuscate } = layout.options
+                const key = JSON.stringify([maxPacket, rateLimit, bridgeObfuscate])
+                if (!project.modules.has(key)) {
+                    const source = bridgeSource({
+                        secret: project.secret,
+                        maxPacket: typeof maxPacket === "number" ? maxPacket : undefined,
+                        rateLimit: typeof rateLimit === "number" ? rateLimit : undefined,
+                    })
+                    project.modules.set(key, bridgeObfuscate === false ? source : await obfuscateBridge(source))
+                }
+                const clientOnly = [...used].every(file => sideOf(file) === "client")
+                return {
+                    files: [{ file: modulePath, code: project.modules.get(key) }],
+                    problems: clientOnly
+                        ? [{ severity: /** @type {const} */ ("warning"), message: "Only client scripts call bridge: nothing starts it on the server, so the clients will wait for it" }]
+                        : [],
+                }
+            },
+        }
+    },
+}
+
+/** A file's place from `outDir`, as tilua gives it when no host does: its path
+ *  without the extension, and `init.luau` the folder it is in.
+ *  @param {string} path */
+function placeInFolder(path) {
+    const parts = path.split(sep).join("/").replace(/\.luau?$/, "").split("/").filter(part => part !== "")
+    if (parts.at(-1) === "init") parts.pop()
+    return parts
+}
+
+/** What a file at `from` passes to `require` to reach the one at `to`, both as
+ *  places: tilua's own rule, so the module is reached as the runtime is.
+ *  @param {readonly string[]} from @param {readonly string[]} to @param {string | undefined} root */
+function pathBetween(from, to, root) {
+    if (root !== undefined && from[0] !== to[0]) return `${root}/${to.join("/")}`
+    if (to.length > from.length && from.every((part, i) => to[i] === part)) return `@self/${to.slice(from.length).join("/")}`
+    const base = from.slice(0, -1)
+    let shared = 0
+    while (shared < base.length && shared < to.length - 1 && base[shared] === to[shared]) shared++
+    const up = base.length - shared
+    return `${up === 0 ? "./" : "../".repeat(up)}${to.slice(shared).join("/")}`
+}
+
+export default plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tilua-types/bridge",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "bridge: Roblox client-server networking through a per-game, obfuscated module that hands each file its handle once, with AES-GCM packets and decoy remotes",
   "license": "ISC",
   "type": "module",
@@ -33,14 +33,14 @@
       "bridgeObfuscate": {
         "type": "boolean",
         "default": true,
-        "description": "Obfuscate the bridge module. Off only to read it while debugging; never ship that."
+        "description": "Obfuscate the bridge module, and the strings of the claim at the top of each file that calls it. Off only to read it while debugging; never ship that."
       }
     }
   },
   "dependencies": {
     "@tilua-types/crypto": "^1.0.0",
     "@tilua-types/roblox": "^10.1.2",
-    "lua-obfuscator": "^3.0.9"
+    "luau-obfuscator": "^1.1.0"
   },
   "peerDependencies": {
     "@tilua/parser": "^9.1.2"