@tilua-types/bridge 1.0.0 → 2.1.0

package/runtime/bridge.luau

@@ -13,8 +13,15 @@
 -- Client to server, each packet is AES-GCM under a key the server hands each
 -- player once, with a sequence number inside, so a packet cannot be forged,
 -- changed or sent twice. Server to client is plain: nothing but the server can
--- fire at a client.
+-- fire at a client. `bridge.invoke` is sealed and numbered the same way, apart,
+-- through a RemoteFunction; the answer comes back plain, to that client alone.
+--
+-- What is sent in one frame goes in one packet, at the next Heartbeat: each
+-- message is `[name, arguments]`, its arguments a JSON array of their own, so a
+-- handler's limits are checked before they are decoded. Instances travel as
+-- their path from `game` and are looked up again where they arrive.
 
+local DataModel = game
 local RunService = game:GetService("RunService")
 local Players = game:GetService("Players")
 local HttpService = game:GetService("HttpService")
@@ -31,6 +38,11 @@ local UNHANDLED_AFTER = 10
 local NO_SERVER_AFTER = 15
 -- How long a breach waits for a file that registers `bridge.onBreach` to load.
 local BREACH_GRACE = 5
+-- How deep a table, how long an Instance's path and how many arguments a message
+-- may have: past them a sender is refused and a packet is out of shape.
+local MAX_DEPTH = 64
+local MAX_PATH = 100
+local MAX_ARGS = 255
 
 local ONE_VM = "bridge: this module ran a second time, which means an Actor: the bridge works in one Luau VM, so call it from outside Actors"
 
@@ -64,13 +76,20 @@ local breachHandlers = {}
 local banning = {}
 
 -- With no handler: for good, and the player's alt accounts too. A ban that fails
--- is a kick. Studio only warns, so a test cannot ban whoever runs it.
-local function ban(player, reason)
+-- is a kick. In Studio it is a kick that says why, so a test cannot ban whoever
+-- runs it.
+local function punish(player, reason)
 	warn(("[bridge] %s: %s"):format(player.Name, reason))
-	if banning[player] or RunService:IsStudio() then
+	if banning[player] then
 		return
 	end
 	banning[player] = true
+	if RunService:IsStudio() then
+		if player.Parent then
+			player:Kick("[bridge] " .. reason)
+		end
+		return
+	end
 	task.spawn(function()
 		local ok, failure = pcall(Players.BanAsync, Players, {
 			UserIds = { player.UserId },
@@ -95,7 +114,8 @@ local function runBreachHandlers(player, reason)
 	end
 end
 
--- On the server: whoever the game registered with `bridge.onBreach`, or a ban.
+-- On the server: whoever the game registered with `bridge.onBreach`, or the
+-- punishment.
 local function serverBreach(player, reason)
 	if #breachHandlers > 0 then
 		runBreachHandlers(player, reason)
@@ -105,60 +125,481 @@ local function serverBreach(player, reason)
 		if #breachHandlers > 0 then
 			runBreachHandlers(player, reason)
 		elseif player then
-			ban(player, reason)
+			punish(player, reason)
 		end
 	end)
 end
 
+--------------------------------------------------------------------------------
+-- Arguments
+--------------------------------------------------------------------------------
+
+-- JSON carries strings, numbers, booleans and tables of them. The rest is said by
+-- a table with one key that starts with \1: an Instance by its path of names from
+-- `game`, a Vector3 or CFrame or the like by its components, a `nil` argument by
+-- a mark, so the array has no holes. A key of the
+-- game's own that starts with \1 gets another in front, and loses it on arrival.
+local TAG = "\1"
+local INSTANCE = TAG .. "i"
+local NIL = TAG .. "n"
+
+local function pathOf(instance)
+	local names = {}
+	local at = instance
+	while at ~= DataModel do
+		if at == nil or #names >= MAX_PATH then
+			return nil
+		end
+		table.insert(names, 1, at.Name)
+		at = at.Parent
+	end
+	return names
+end
+
+-- The first child of each name, from `game`: nil where there is none, as there is
+-- for what the other side has and this one was never given
+local function instanceAt(path)
+	if type(path) ~= "table" or #path > MAX_PATH then
+		return nil
+	end
+	local at = DataModel
+	for _, name in ipairs(path) do
+		if type(name) ~= "string" then
+			return nil
+		end
+		at = at:FindFirstChild(name)
+		if not at then
+			return nil
+		end
+	end
+	return at
+end
+
+-- Roblox's value types, as `{"\1d": [typeof, [components]]}`: each says what its
+-- components are and makes it again from them. What arrives is checked part by
+-- part — a number where a number goes, as many as there should be — and a value
+-- that does not make one is nil.
+local DATATYPE = TAG .. "d"
+local MAX_KEYPOINTS = 20
+
+local function numbers(parts, count)
+	if #parts ~= count then
+		error("wrong count", 0)
+	end
+	for i = 1, count do
+		if type(parts[i]) ~= "number" then
+			error("not a number", 0)
+		end
+	end
+	return table.unpack(parts, 1, count)
+end
+
+-- A sequence's keypoints, each `stride` numbers
+local function keypoints(parts, stride, make)
+	if #parts == 0 or #parts % stride ~= 0 or #parts > stride * MAX_KEYPOINTS then
+		error("wrong count", 0)
+	end
+	local points = {}
+	for i = 1, #parts, stride do
+		table.insert(points, make(numbers(table.move(parts, i, i + stride - 1, 1, {}), stride)))
+	end
+	return points
+end
+
+local DATATYPES = {
+	Vector3 = {
+		pack = function(v)
+			return { v.X, v.Y, v.Z }
+		end,
+		unpack = function(p)
+			return Vector3.new(numbers(p, 3))
+		end,
+	},
+	Vector2 = {
+		pack = function(v)
+			return { v.X, v.Y }
+		end,
+		unpack = function(p)
+			return Vector2.new(numbers(p, 2))
+		end,
+	},
+	Vector3int16 = {
+		pack = function(v)
+			return { v.X, v.Y, v.Z }
+		end,
+		unpack = function(p)
+			return Vector3int16.new(numbers(p, 3))
+		end,
+	},
+	Vector2int16 = {
+		pack = function(v)
+			return { v.X, v.Y }
+		end,
+		unpack = function(p)
+			return Vector2int16.new(numbers(p, 2))
+		end,
+	},
+	CFrame = {
+		pack = function(v)
+			return { v:GetComponents() }
+		end,
+		unpack = function(p)
+			return CFrame.new(numbers(p, 12))
+		end,
+	},
+	Color3 = {
+		pack = function(v)
+			return { v.R, v.G, v.B }
+		end,
+		unpack = function(p)
+			return Color3.new(numbers(p, 3))
+		end,
+	},
+	BrickColor = {
+		pack = function(v)
+			return { v.Number }
+		end,
+		unpack = function(p)
+			return BrickColor.new(numbers(p, 1))
+		end,
+	},
+	UDim = {
+		pack = function(v)
+			return { v.Scale, v.Offset }
+		end,
+		unpack = function(p)
+			return UDim.new(numbers(p, 2))
+		end,
+	},
+	UDim2 = {
+		pack = function(v)
+			return { v.X.Scale, v.X.Offset, v.Y.Scale, v.Y.Offset }
+		end,
+		unpack = function(p)
+			return UDim2.new(numbers(p, 4))
+		end,
+	},
+	Rect = {
+		pack = function(v)
+			return { v.Min.X, v.Min.Y, v.Max.X, v.Max.Y }
+		end,
+		unpack = function(p)
+			return Rect.new(numbers(p, 4))
+		end,
+	},
+	NumberRange = {
+		pack = function(v)
+			return { v.Min, v.Max }
+		end,
+		unpack = function(p)
+			return NumberRange.new(numbers(p, 2))
+		end,
+	},
+	NumberSequence = {
+		pack = function(v)
+			local parts = {}
+			for _, point in v.Keypoints do
+				table.insert(parts, point.Time)
+				table.insert(parts, point.Value)
+				table.insert(parts, point.Envelope)
+			end
+			return parts
+		end,
+		unpack = function(p)
+			return NumberSequence.new(keypoints(p, 3, NumberSequenceKeypoint.new))
+		end,
+	},
+	ColorSequence = {
+		pack = function(v)
+			local parts = {}
+			for _, point in v.Keypoints do
+				table.insert(parts, point.Time)
+				table.insert(parts, point.Value.R)
+				table.insert(parts, point.Value.G)
+				table.insert(parts, point.Value.B)
+			end
+			return parts
+		end,
+		unpack = function(p)
+			return ColorSequence.new(keypoints(p, 4, function(time, r, g, b)
+				return ColorSequenceKeypoint.new(time, Color3.new(r, g, b))
+			end))
+		end,
+	},
+	Ray = {
+		pack = function(v)
+			return { v.Origin.X, v.Origin.Y, v.Origin.Z, v.Direction.X, v.Direction.Y, v.Direction.Z }
+		end,
+		unpack = function(p)
+			local ox, oy, oz, dx, dy, dz = numbers(p, 6)
+			return Ray.new(Vector3.new(ox, oy, oz), Vector3.new(dx, dy, dz))
+		end,
+	},
+	Region3 = {
+		pack = function(v)
+			local min, max = v.CFrame.Position - v.Size / 2, v.CFrame.Position + v.Size / 2
+			return { min.X, min.Y, min.Z, max.X, max.Y, max.Z }
+		end,
+		unpack = function(p)
+			local x0, y0, z0, x1, y1, z1 = numbers(p, 6)
+			return Region3.new(Vector3.new(x0, y0, z0), Vector3.new(x1, y1, z1))
+		end,
+	},
+	PhysicalProperties = {
+		pack = function(v)
+			return { v.Density, v.Friction, v.Elasticity, v.FrictionWeight, v.ElasticityWeight }
+		end,
+		unpack = function(p)
+			return PhysicalProperties.new(numbers(p, 5))
+		end,
+	},
+	DateTime = {
+		pack = function(v)
+			return { v.UnixTimestampMillis }
+		end,
+		unpack = function(p)
+			return DateTime.fromUnixTimestampMillis(numbers(p, 1))
+		end,
+	},
+	-- By its enum's name and its own: Enum.Material.Plastic is ["Material", "Plastic"]
+	EnumItem = {
+		pack = function(v)
+			return { tostring(v.EnumType), v.Name }
+		end,
+		unpack = function(p)
+			if #p ~= 2 or type(p[1]) ~= "string" or type(p[2]) ~= "string" then
+				error("not an enum item", 0)
+			end
+			return Enum[p[1]][p[2]]
+		end,
+	},
+}
+
+local function datatypeOf(value)
+	local tagged = value[DATATYPE]
+	if type(tagged) ~= "table" or type(tagged[1]) ~= "string" or type(tagged[2]) ~= "table" then
+		return nil
+	end
+	local datatype = DATATYPES[tagged[1]]
+	if not datatype then
+		return nil
+	end
+	local ok, made = pcall(datatype.unpack, tagged[2])
+	return if ok and typeof(made) == tagged[1] then made else nil
+end
+
+local function packValue(value, depth)
+	local kind = typeof(value)
+	if kind == "Instance" then
+		local path = pathOf(value)
+		return if path then { [INSTANCE] = path } else { [NIL] = true }
+	end
+	local datatype = DATATYPES[kind]
+	if datatype then
+		return { [DATATYPE] = { kind, datatype.pack(value) } }
+	end
+	if type(value) ~= "table" then
+		return value
+	end
+	if depth >= MAX_DEPTH then
+		error(("bridge: a table nested deeper than %d, or inside itself"):format(MAX_DEPTH), 0)
+	end
+	local out = {}
+	for key, item in value do
+		if type(key) == "string" and string.sub(key, 1, 1) == TAG then
+			key = TAG .. key
+		end
+		out[key] = packValue(item, depth + 1)
+	end
+	return out
+end
+
+local function unpackValue(value, depth)
+	if type(value) ~= "table" then
+		return value
+	end
+	if depth >= MAX_DEPTH then
+		error("too deep", 0)
+	end
+	local only = next(value)
+	if only ~= nil and next(value, only) == nil then
+		if only == INSTANCE then
+			return instanceAt(value[INSTANCE])
+		elseif only == DATATYPE then
+			return datatypeOf(value)
+		elseif only == NIL then
+			return nil
+		end
+	end
+	local out = {}
+	for key, item in value do
+		if type(key) == "string" and string.sub(key, 1, 2) == TAG .. TAG then
+			key = string.sub(key, 2)
+		end
+		out[key] = unpackValue(item, depth + 1)
+	end
+	return out
+end
+
+-- Arguments, as a JSON array with no holes: `args` as table.pack makes it
+local function encodeArgs(args)
+	local packed = table.create(args.n)
+	for i = 1, args.n do
+		local value = packValue(args[i], 0)
+		packed[i] = if value == nil then { [NIL] = true } else value
+	end
+	return HttpService:JSONEncode(packed)
+end
+
+-- One message, as it travels: `[name, "[...arguments]"]`
+local function encodeMessage(what, name, ...)
+	if type(name) ~= "string" then
+		error(("bridge.%s: the name is a string, not %s"):format(what, typeof(name)), 3)
+	end
+	local args = table.pack(...)
+	if args.n > MAX_ARGS then
+		error(("bridge.%s: '%s' has %d arguments, over %d"):format(what, name, args.n, MAX_ARGS), 3)
+	end
+	return HttpService:JSONEncode({ name, encodeArgs(args) })
+end
+
+-- What a handler is called with, from a message's argument text; an error if it
+-- is not one the bridge made
+local function decodeArgs(text)
+	local raw = HttpService:JSONDecode(text)
+	if type(raw) ~= "table" or #raw > MAX_ARGS then
+		error("not an argument list", 0)
+	end
+	local args = { n = #raw }
+	for i = 1, args.n do
+		args[i] = unpackValue(raw[i], 0)
+	end
+	return args
+end
+
 --------------------------------------------------------------------------------
 -- Handlers
 --------------------------------------------------------------------------------
 
 -- Every handler of a name runs. What comes before there is one is held for it, as
 -- a remote holds events until something connects: the module connects as it
--- loads, likely before the file with the handler has.
-local function newInbox()
-	return { handlers = {}, waiting = {}, held = 0, noted = {}, full = false }
+-- loads, likely before the file with the handler has. `malformed` is what a
+-- message's arguments the bridge did not make are, on that side.
+local function newInbox(malformed)
+	return { handlers = {}, waiting = {}, held = 0, noted = {}, full = false, malformed = malformed }
 end
 
-local function deliver(inbox, name, ...)
+-- A handler's own limits, from the third argument of onServer/onClient
+local function newEntry(what, name, handler, options)
+	if type(name) ~= "string" then
+		error(("bridge.%s: the name is a string, not %s"):format(what, typeof(name)), 0)
+	end
+	if options ~= nil and type(options) ~= "table" then
+		error(("bridge.%s('%s'): the options are a table, not %s"):format(what, name, typeof(options)), 0)
+	end
+	local entry = { handler = handler, rateLimit = 0, maxPacket = 0, buckets = setmetatable({}, { __mode = "k" }), warned = false }
+	for _, key in { "rateLimit", "maxPacket" } do
+		local value = options and options[key]
+		if value ~= nil then
+			if type(value) ~= "number" or value < 0 or value ~= value then
+				error(("bridge.%s('%s'): %s is a number from 0, not %s"):format(what, name, key, tostring(value)), 0)
+			end
+			entry[key] = value
+		end
+	end
+	return entry
+end
+
+-- Within the handler's limits: no larger than its maxPacket, and no more of them
+-- from this sender this second than its rateLimit. The rest is dropped.
+local function admits(entry, name, message)
+	if entry.maxPacket > 0 and #message.text > entry.maxPacket then
+		if not entry.warned then
+			entry.warned = true
+			warn(("[bridge] a '%s' of %d bytes is over its handler's maxPacket of %d, so it and those after it are dropped"):format(name, #message.text, entry.maxPacket))
+		end
+		return false
+	end
+	if entry.rateLimit > 0 then
+		local key = message.from or false
+		local now = os.clock()
+		local bucket = entry.buckets[key]
+		if not bucket or now - bucket.window >= 1 then
+			bucket = { window = now, count = 0 }
+			entry.buckets[key] = bucket
+		end
+		bucket.count += 1
+		if bucket.count > entry.rateLimit then
+			return false
+		end
+	end
+	return true
+end
+
+-- Decoded once, for the first handler that admits it
+local function run(inbox, entry, message)
+	if not admits(entry, message.name, message) then
+		return
+	end
+	if message.args == nil then
+		local ok, args = pcall(decodeArgs, message.text)
+		message.args = ok and args
+		if not ok then
+			inbox.malformed(message.from, message.name)
+		end
+	end
+	local args = message.args
+	if not args then
+		return
+	end
+	if message.from ~= nil then
+		task.spawn(entry.handler, message.from, table.unpack(args, 1, args.n))
+	else
+		task.spawn(entry.handler, table.unpack(args, 1, args.n))
+	end
+end
+
+-- `from` is the player on the server, nil on the client
+local function deliver(inbox, from, name, text)
+	local message = { from = from, name = name, text = text }
 	local handlers = inbox.handlers[name]
 	if handlers then
-		for _, handler in handlers do
-			task.spawn(handler, ...)
+		for _, entry in handlers do
+			run(inbox, entry, message)
 		end
 		return
 	end
 	if inbox.held >= HOLD_LIMIT then
 		if not inbox.full then
 			inbox.full = true
-			warn(("[bridge] %d messages wait for handlers, so '%s' and those after it are dropped"):format(HOLD_LIMIT, tostring(name)))
+			warn(("[bridge] %d messages wait for handlers, so '%s' and those after it are dropped"):format(HOLD_LIMIT, name))
 		end
 		return
 	end
 	inbox.held += 1
-	table.insert(inbox.waiting, { name = name, args = table.pack(...) })
+	table.insert(inbox.waiting, message)
 	if not inbox.noted[name] then
 		inbox.noted[name] = true
 		task.delay(UNHANDLED_AFTER, function()
 			if not inbox.handlers[name] then
-				warn(("[bridge] nothing handles '%s'"):format(tostring(name)))
+				warn(("[bridge] nothing handles '%s'"):format(name))
 			end
 		end)
 	end
 end
 
-local function listen(inbox, name, handler)
+local function listen(inbox, what, name, handler, options)
+	local entry = newEntry(what, name, handler, options)
 	local handlers = inbox.handlers[name]
 	if handlers then
-		table.insert(handlers, handler)
+		table.insert(handlers, entry)
 		return
 	end
-	inbox.handlers[name] = { handler }
+	inbox.handlers[name] = { entry }
 	local still = {}
 	for _, message in inbox.waiting do
 		if message.name == name then
-			task.spawn(handler, table.unpack(message.args, 1, message.args.n))
+			run(inbox, entry, message)
 		else
 			table.insert(still, message)
 		end
@@ -172,21 +613,229 @@ end
 -- The server's side
 --------------------------------------------------------------------------------
 
-local serverInbox = newInbox()
-local clientInbox = newInbox()
-local packetRemote, keyRemote
+local serverInbox = newInbox(function(player)
+	serverBreach(player, "a packet out of shape")
+end)
+local clientInbox = newInbox(function(_, name)
+	warn(("[bridge] the server sent a '%s' the bridge could not read"):format(name))
+end)
+local packetRemote, keyRemote, invokeRemote
+
+-- What answers `bridge.invoke`: one handler a name. An invoke that comes before
+-- it waits for it, as long as a message would wait to be warned about.
+local invokeHandlers = {}
+local invokesWaiting = 0
+
+-- What the server sends this frame, in order: `to` a player, or false for all
+local serverOutbox = {}
+
+local function flushServer()
+	if #serverOutbox == 0 then
+		return
+	end
+	local queued = serverOutbox
+	serverOutbox = {}
+	local everyone = true
+	for _, item in queued do
+		if item.to then
+			everyone = false
+			break
+		end
+	end
+	if everyone then
+		local texts = table.create(#queued)
+		for i, item in queued do
+			texts[i] = item.text
+		end
+		packetRemote:FireAllClients("[" .. table.concat(texts, ",") .. "]")
+		return
+	end
+	-- One packet a player, still in the order they were sent
+	for _, player in Players:GetPlayers() do
+		local texts = {}
+		for _, item in queued do
+			if not item.to or item.to == player then
+				table.insert(texts, item.text)
+			end
+		end
+		if #texts > 0 then
+			packetRemote:FireClient(player, "[" .. table.concat(texts, ",") .. "]")
+		end
+	end
+end
 
 local sessions = {}
 
 local function sessionOf(player)
 	local session = sessions[player]
 	if not session then
-		session = { key = crypto.randomBytes(32), given = false, last = 0, window = 0, count = 0 }
+		-- Packets and invokes are numbered apart: an invoke waits for its answer
+		-- while the frame's packets go out, so neither can say which came first
+		session = {
+			key = crypto.randomBytes(32),
+			given = false,
+			last = 0,
+			lastInvoke = 0,
+			honeyEvent = 0,
+			honeyFunction = 0,
+			window = 0,
+			count = 0,
+		}
 		sessions[player] = session
 	end
 	return session
 end
 
+-- The text a blob sealed under this session's key holds, or nil
+local function unseal(session, blob)
+	local ok, raw = pcall(crypto.base64.decode, blob)
+	local sealed = ok and #raw >= 28 and {
+		iv = string.sub(raw, 1, 12),
+		ciphertext = string.sub(raw, 13, -17),
+		tag = string.sub(raw, -16),
+	}
+	return sealed and crypto.aesGcm.decrypt(session.key, sealed) or nil
+end
+
+-- Two of the decoys are honeypots: the game's own client fires one beside every
+-- packet and invokes the other beside every invoke, sealed and numbered on a
+-- count of each, so a spy sees them carry traffic like the real ones. What comes
+-- in with the next number is that and is let be; anything else — a blob it did
+-- not seal, a number out of turn, a replay — is someone firing what they saw.
+local HONEYPOT_MAX = 512
+
+local function honeypot(player, blob, field, touched)
+	local session = sessions[player]
+	if not session or not session.given or type(blob) ~= "string" or #blob > HONEYPOT_MAX then
+		serverBreach(player, touched)
+		return
+	end
+	local text = unseal(session, blob)
+	if not text then
+		serverBreach(player, touched)
+		return
+	end
+	local decoded, packet = pcall(HttpService.JSONDecode, HttpService, text)
+	if not decoded or type(packet) ~= "table" or packet.h ~= session[field] + 1 then
+		serverBreach(player, "replayed a honeypot")
+		return
+	end
+	session[field] = packet.h
+end
+
+-- A client's sealed packet, opened: the JSON in it, or nil when it is a breach or
+-- over the rate. `last` is the session's field its number has to be past.
+-- `shaped` says whether what is in it is what the remote takes.
+local function openPacket(player, blob, last, shaped)
+	local session = sessions[player]
+	if not session or not session.given or type(blob) ~= "string" then
+		serverBreach(player, "a packet without a session")
+		return nil
+	end
+	-- Both before any of the crypto, which is what a flood would cost. Past the
+	-- rate a packet is dropped, not a breach: a game can burst.
+	if RATE_LIMIT > 0 then
+		local now = os.clock()
+		if now - session.window >= 1 then
+			session.window = now
+			session.count = 0
+		end
+		session.count += 1
+		if session.count > RATE_LIMIT then
+			return nil
+		end
+	end
+	if MAX_PACKET > 0 and #blob > MAX_PACKET then
+		serverBreach(player, "a packet over bridgeMaxPacket")
+		return nil
+	end
+	local text = unseal(session, blob)
+	if not text then
+		serverBreach(player, "a packet the bridge did not seal")
+		return nil
+	end
+	local decoded, packet = pcall(HttpService.JSONDecode, HttpService, text)
+	if not decoded or type(packet) ~= "table" or type(packet.s) ~= "number" or not shaped(packet) then
+		serverBreach(player, "a packet out of shape")
+		return nil
+	end
+	if packet.s <= session[last] then
+		serverBreach(player, "a packet sent twice")
+		return nil
+	end
+	session[last] = packet.s
+	return packet
+end
+
+local function isMessage(message)
+	return type(message) == "table" and type(message[1]) == "string" and type(message[2]) == "string"
+end
+
+local function isEventPacket(packet)
+	if type(packet.b) == "string" then
+		return true
+	end
+	if type(packet.m) ~= "table" then
+		return false
+	end
+	for _, message in packet.m do
+		if not isMessage(message) then
+			return false
+		end
+	end
+	return true
+end
+
+local function isInvokePacket(packet)
+	return isMessage(packet.i)
+end
+
+-- An invoke's answer: true and the result as an argument list, or false and why
+-- not. Why is the bridge's own words: a handler's error stays on the server.
+local function answerInvoke(player, blob)
+	local packet = openPacket(player, blob, "lastInvoke", isInvokePacket)
+	if not packet then
+		return nil
+	end
+	local name, text = packet.i[1], packet.i[2]
+	local entry = invokeHandlers[name]
+	if not entry then
+		if invokesWaiting >= HOLD_LIMIT then
+			return false, "found no handler, with too many invokes waiting"
+		end
+		invokesWaiting += 1
+		local waited = 0
+		while not invokeHandlers[name] and waited < UNHANDLED_AFTER do
+			waited += task.wait(0.1)
+		end
+		invokesWaiting -= 1
+		entry = invokeHandlers[name]
+		if not entry then
+			warn(("[bridge] nothing answers the invoke '%s'"):format(name))
+			return false, "has no handler on the server"
+		end
+	end
+	if not admits(entry, name, { from = player, name = name, text = text }) then
+		return false, "is over its handler's limits"
+	end
+	local decoded, args = pcall(decodeArgs, text)
+	if not decoded then
+		serverBreach(player, "a packet out of shape")
+		return nil
+	end
+	local ran, result = pcall(entry.handler, player, table.unpack(args, 1, args.n))
+	if not ran then
+		warn(("[bridge] the handler of the invoke '%s' failed: %s"):format(name, tostring(result)))
+		return false, "failed on the server"
+	end
+	local encoded, answer = pcall(encodeArgs, table.pack(result))
+	if not encoded then
+		warn(("[bridge] the answer to the invoke '%s' could not be sent: %s"):format(name, tostring(answer)))
+		return false, "had an answer the bridge could not send"
+	end
+	return true, answer
+end
+
 local function startServer()
 	if script:FindFirstChildOfClass("Folder") then
 		error(ONE_VM, 0)
@@ -199,7 +848,10 @@ local function startServer()
 	packetRemote.Name = remoteName(salt, "packet")
 	keyRemote = Instance.new("RemoteFunction")
 	keyRemote.Name = remoteName(salt, "key")
-	local remotes = { packetRemote, keyRemote }
+	invokeRemote = Instance.new("RemoteFunction")
+	invokeRemote.Name = remoteName(salt, "invoke")
+	invokeRemote.OnServerInvoke = answerInvoke
+	local remotes = { packetRemote, keyRemote, invokeRemote }
 
 	-- The key, once per player: the game's own script asks for it as it loads,
 	-- before an executor can, so a second ask is one
@@ -214,78 +866,48 @@ local function startServer()
 	end
 
 	packetRemote.OnServerEvent:Connect(function(player, blob)
-		local session = sessions[player]
-		if not session or not session.given or type(blob) ~= "string" then
-			serverBreach(player, "a packet without a session")
-			return
-		end
-		-- Both before any of the crypto, which is what a flood would cost. Past
-		-- the rate a packet is dropped, not a breach: a game can burst.
-		if RATE_LIMIT > 0 then
-			local now = os.clock()
-			if now - session.window >= 1 then
-				session.window = now
-				session.count = 0
-			end
-			session.count += 1
-			if session.count > RATE_LIMIT then
-				return
-			end
-		end
-		if MAX_PACKET > 0 and #blob > MAX_PACKET then
-			serverBreach(player, "a packet over bridgeMaxPacket")
+		local packet = openPacket(player, blob, "last", isEventPacket)
+		if not packet then
 			return
 		end
-		local ok, raw = pcall(crypto.base64.decode, blob)
-		local sealed = ok and #raw >= 28 and {
-			iv = string.sub(raw, 1, 12),
-			ciphertext = string.sub(raw, 13, -17),
-			tag = string.sub(raw, -16),
-		}
-		local text = sealed and crypto.aesGcm.decrypt(session.key, sealed)
-		if not text then
-			serverBreach(player, "a packet the bridge did not seal")
-			return
-		end
-		local decoded, packet = pcall(HttpService.JSONDecode, HttpService, text)
-		if
-			not decoded
-			or type(packet) ~= "table"
-			or type(packet.s) ~= "number"
-			or (type(packet.n) ~= "string" and type(packet.b) ~= "string")
-		then
-			serverBreach(player, "a packet out of shape")
-			return
-		end
-		if packet.s <= session.last then
-			serverBreach(player, "a packet sent twice")
-			return
-		end
-		session.last = packet.s
 		if type(packet.b) == "string" then
 			serverBreach(player, "client: " .. packet.b)
 			return
 		end
-		local args = type(packet.a) == "table" and packet.a or {}
-		local count = type(packet.c) == "number" and math.clamp(packet.c, 0, 255) or #args
-		deliver(serverInbox, packet.n, player, table.unpack(args, 1, count))
+		for _, message in packet.m do
+			deliver(serverInbox, player, message[1], message[2])
+		end
 	end)
 
 	-- Decoys: nothing the game sends goes through them, so anything that does is
-	-- an executor firing every remote it can find
-	for _ = 1, DECOYS do
+	-- an executor firing every remote it can find. The first of each kind is a
+	-- honeypot, named by the salt so the client finds it; to anything else it is
+	-- one more decoy.
+	for n = 1, DECOYS do
 		local decoy = Instance.new("RemoteEvent")
-		decoy.Name = randomName()
-		decoy.OnServerEvent:Connect(function(player)
-			serverBreach(player, "fired a decoy")
-		end)
-		table.insert(remotes, decoy)
 		local decoyFunction = Instance.new("RemoteFunction")
-		decoyFunction.Name = randomName()
-		decoyFunction.OnServerInvoke = function(player)
-			serverBreach(player, "invoked a decoy")
-			return nil
+		if n == 1 then
+			decoy.Name = remoteName(salt, "honeypotEvent")
+			decoy.OnServerEvent:Connect(function(player, blob)
+				honeypot(player, blob, "honeyEvent", "fired a decoy")
+			end)
+			decoyFunction.Name = remoteName(salt, "honeypotFunction")
+			decoyFunction.OnServerInvoke = function(player, blob)
+				honeypot(player, blob, "honeyFunction", "invoked a decoy")
+				return nil
+			end
+		else
+			decoy.Name = randomName()
+			decoy.OnServerEvent:Connect(function(player)
+				serverBreach(player, "fired a decoy")
+			end)
+			decoyFunction.Name = randomName()
+			decoyFunction.OnServerInvoke = function(player)
+				serverBreach(player, "invoked a decoy")
+				return nil
+			end
 		end
+		table.insert(remotes, decoy)
 		table.insert(remotes, decoyFunction)
 	end
 
@@ -302,6 +924,7 @@ local function startServer()
 	Players.PlayerRemoving:Connect(function(player)
 		sessions[player] = nil
 	end)
+	RunService.Heartbeat:Connect(flushServer)
 end
 
 --------------------------------------------------------------------------------
@@ -310,19 +933,68 @@ end
 
 local clientKey
 local sequence = 0
+local invokeSequence = 0
+local honeypotEvent, honeypotFunction
+local honeyEventId, honeyFunctionId = 0, 0
 
-local function seal(packet)
-	sequence += 1
-	packet.s = sequence
-	local text = HttpService:JSONEncode(packet)
+-- What the client sends this frame, each message already JSON
+local clientOutbox = {}
+
+local function seal(text)
 	local sealed = crypto.aesGcm.encrypt(clientKey, text)
 	return crypto.base64.encode(sealed.iv .. sealed.ciphertext .. sealed.tag)
 end
 
+-- How large a packet of messages this long is sealed, at most: the sequence
+-- number and the JSON around them, the IV and the tag, in base64
+local function sealedSize(length)
+	return 4 * math.ceil((length + 64) / 3)
+end
+
+local function sealMessages(texts)
+	sequence += 1
+	return seal('{"s":' .. sequence .. ',"m":[' .. table.concat(texts, ",") .. "]}")
+end
+
+-- A honeypot's next number, sealed, with as much padding as a packet might have
+local function honey(id)
+	local padding = string.sub(crypto.randomHash().hex, 1, 8 + string.byte(crypto.randomBytes(1)) % 56)
+	return seal(HttpService:JSONEncode({ h = id, p = padding }))
+end
+
+-- The packet remote fired, and the event honeypot beside it
+local function fire(blob)
+	packetRemote:FireServer(blob)
+	if honeypotEvent then
+		honeyEventId += 1
+		honeypotEvent:FireServer(honey(honeyEventId))
+	end
+end
+
+-- One packet for the frame, or as few as fit under bridgeMaxPacket
+local function flushClient()
+	if #clientOutbox == 0 or not clientKey then
+		return
+	end
+	local queued = clientOutbox
+	clientOutbox = {}
+	local batch, length = {}, 0
+	for _, text in queued do
+		if MAX_PACKET > 0 and #batch > 0 and sealedSize(length + #text) > MAX_PACKET then
+			fire(sealMessages(batch))
+			batch, length = {}, 0
+		end
+		table.insert(batch, text)
+		length += #text + 1
+	end
+	fire(sealMessages(batch))
+end
+
 local function clientBreach(reason)
 	if clientKey and packetRemote then
 		pcall(function()
-			packetRemote:FireServer(seal({ b = reason }))
+			sequence += 1
+			fire(seal(HttpService:JSONEncode({ s = sequence, b = reason })))
 		end)
 	end
 end
@@ -342,17 +1014,64 @@ local function startClient()
 	local holder = script:FindFirstChildOfClass("Folder")
 	packetRemote = holder:WaitForChild(remoteName(holder.Name, "packet"))
 	keyRemote = holder:WaitForChild(remoteName(holder.Name, "key"))
+	invokeRemote = holder:WaitForChild(remoteName(holder.Name, "invoke"))
+	-- None with no decoys
+	honeypotEvent = holder:FindFirstChild(remoteName(holder.Name, "honeypotEvent"))
+	honeypotFunction = holder:FindFirstChild(remoteName(holder.Name, "honeypotFunction"))
 	script:SetAttribute("BridgeFound", true)
 	clientKey = keyRemote:InvokeServer()
 
-	packetRemote.OnClientEvent:Connect(function(name, ...)
-		deliver(clientInbox, name, ...)
+	packetRemote.OnClientEvent:Connect(function(blob)
+		local ok, messages = pcall(HttpService.JSONDecode, HttpService, blob)
+		if not ok or type(messages) ~= "table" then
+			warn("[bridge] the server sent a packet the bridge could not read")
+			return
+		end
+		for _, message in messages do
+			if type(message) == "table" and type(message[1]) == "string" and type(message[2]) == "string" then
+				deliver(clientInbox, nil, message[1], message[2])
+			end
+		end
 	end)
+	RunService.Heartbeat:Connect(flushClient)
 
 	-- Once found, the real remotes take names nothing else can look up, in the
 	-- decoys' form
 	packetRemote.Name = randomName()
 	keyRemote.Name = randomName()
+	invokeRemote.Name = randomName()
+	for _, remote in { honeypotEvent, honeypotFunction } do
+		remote.Name = randomName()
+	end
+end
+
+-- The server's handler of that name, called and waited for: its answer, or an
+-- error saying why there is none
+local function invoke(name, ...)
+	if not clientKey then
+		error("bridge: the server gave this client no key", 2)
+	end
+	local text = encodeMessage("invoke", name, ...)
+	if MAX_PACKET > 0 and sealedSize(#text) > MAX_PACKET then
+		error(("bridge.invoke: '%s' is %d bytes sealed, over bridgeMaxPacket"):format(name, sealedSize(#text)), 2)
+	end
+	-- What was sent before it goes first
+	flushClient()
+	invokeSequence += 1
+	-- Its honeypot on a thread of its own, so the invoke waits for one answer
+	if honeypotFunction then
+		honeyFunctionId += 1
+		task.spawn(honeypotFunction.InvokeServer, honeypotFunction, honey(honeyFunctionId))
+	end
+	local ok, answer = invokeRemote:InvokeServer(seal('{"s":' .. invokeSequence .. ',"i":' .. text .. "}"))
+	if ok ~= true then
+		error(("bridge.invoke: '%s' %s"):format(name, if type(answer) == "string" then answer else "was refused by the server"), 2)
+	end
+	local decoded, result = pcall(decodeArgs, answer)
+	if not decoded then
+		error(("bridge.invoke: '%s' had an answer the bridge could not read"):format(name), 2)
+	end
+	return result[1]
 end
 
 if IS_SERVER then
@@ -376,19 +1095,27 @@ end
 local function makeHandle()
 	if IS_SERVER then
 		return table.freeze({
-			onServer = function(name, handler)
-				listen(serverInbox, name, handler)
+			onServer = function(name, handler, options)
+				listen(serverInbox, "onServer", name, handler, options)
 			end,
 			sendTo = function(player, name, ...)
-				packetRemote:FireClient(player, name, ...)
+				table.insert(serverOutbox, { to = player, text = encodeMessage("sendTo", name, ...) })
 			end,
 			sendAll = function(name, ...)
-				packetRemote:FireAllClients(name, ...)
+				table.insert(serverOutbox, { to = false, text = encodeMessage("sendAll", name, ...) })
+			end,
+			onInvoke = function(name, handler, options)
+				local entry = newEntry("onInvoke", name, handler, options)
+				if invokeHandlers[name] then
+					error(("bridge.onInvoke: '%s' already has a handler, and an invoke has one answer"):format(name), 0)
+				end
+				invokeHandlers[name] = entry
 			end,
 			onBreach = function(handler)
 				table.insert(breachHandlers, handler)
 			end,
 			send = wrongSide("send"),
+			invoke = wrongSide("invoke"),
 			onClient = wrongSide("onClient"),
 		})
 	end
@@ -397,18 +1124,18 @@ local function makeHandle()
 			if not clientKey then
 				error("bridge: the server gave this client no key", 2)
 			end
-			-- The arguments as an array and their count apart: a JSON array cannot
-			-- say how many trailing nils there were
-			local blob = seal({ n = name, a = { ... }, c = select("#", ... ) })
-			if MAX_PACKET > 0 and #blob > MAX_PACKET then
-				error(("bridge.send: '%s' is %d bytes sealed, over bridgeMaxPacket"):format(tostring(name), #blob), 2)
+			local text = encodeMessage("send", name, ...)
+			if MAX_PACKET > 0 and sealedSize(#text) > MAX_PACKET then
+				error(("bridge.send: '%s' is %d bytes sealed, over bridgeMaxPacket"):format(name, sealedSize(#text)), 2)
 			end
-			packetRemote:FireServer(blob)
+			table.insert(clientOutbox, text)
 		end,
-		onClient = function(name, handler)
-			listen(clientInbox, name, handler)
+		invoke = invoke,
+		onClient = function(name, handler, options)
+			listen(clientInbox, "onClient", name, handler, options)
 		end,
 		onServer = wrongSide("onServer"),
+		onInvoke = wrongSide("onInvoke"),
 		sendTo = wrongSide("sendTo"),
 		sendAll = wrongSide("sendAll"),
 		onBreach = wrongSide("onBreach"),