Merge branch 'grandmas-kitchen' into dev

src/mods/AssetTransform.lua

@@ -16,6 +16,7 @@
 
 local Logger = require("src.core.Logger")
 local Runtime = require("src.mods.Runtime")
+local SafePath = require("src.mods.SafePath")
 
 local unpack = table.unpack or unpack
 local loadstring = loadstring or load
@@ -31,25 +32,8 @@ AssetTransform.SOURCE_ROOT = SOURCE_ROOT
 AssetTransform.DERIVED_ROOT = DERIVED_ROOT
 
 -- ------- path sandbox
-
--- a relative path that cannot climb out of the root it is joined to
-local function safeRelative(rel)
-  if type(rel) ~= "string" or rel == "" then return nil end
-  if rel:sub(1, 1) == "/" then return nil end
-  if rel:find("\\", 1, true) then return nil end
-  for segment in rel:gmatch("[^/]+") do
-    if segment == ".." or segment == "." then return nil end
-  end
-  return rel
-end
-
-local function requireRelative(rel, what)
-  local safe = safeRelative(rel)
-  if not safe then
-    error(("%s must stay inside its root, got %q"):format(what, tostring(rel)), 0)
-  end
-  return safe
-end
+-- shared with mod:read and the manifest's own paths (src/mods/SafePath.lua)
+local requireRelative = SafePath.require
 
 -- ------- the restricted context
 

src/mods/Loader.lua

@@ -12,12 +12,15 @@ local Manifest = require("src.mods.Manifest")
 local Merge = require("src.mods.Merge")
 local ModTargets = require("src.mods.ModTargets")
 local Registry = require("src.mods.Registry")
+local SafePath = require("src.mods.SafePath")
+local Sandbox = require("src.mods.Sandbox")
 local Schemas = require("src.mods.Schemas")
 local Semver = require("src.mods.Semver")
 local Events = require("src.mods.Events")
 local Gen2Compat = require("src.mods.Gen2Compat")
 local Hooks = require("src.mods.Hooks")
 local Runtime = require("src.mods.Runtime")
+local Steps = require("src.mods.Steps")
 
 local Loader = {}
 Loader.__index = Loader
@@ -72,10 +75,12 @@ local function orderedIds(mods, filter)
   return ids
 end
 
--- ------- dev-mode permissions tripwire
--- Attribution only: the shim delegates unconditionally and blocks nothing.
--- Installed once per process and only when the loader runs in dev mode, so a
--- player build has zero interposition.
+-- ------- the require gate
+-- Two jobs in one interposition.  The engine_internals/network scan is
+-- attribution only and stays dev-mode: it warns and delegates.  The
+-- Sandbox.moduleDenial check is not -- require("io") would hand back
+-- package.loaded.io and undo the whole mod environment -- so it is installed
+-- in player builds too, for any boot that has mods on it.
 
 local devShim = { installed = false, permissions = {}, warned = {}, depth = 0 }
 
@@ -135,7 +140,8 @@ end
 
 local function scanRequire(name)
   local modId = Runtime.currentMod
-  if not modId or type(name) ~= "string" then return end
+  if type(modId) ~= "string" then modId = Runtime.modRequire end
+  if type(modId) ~= "string" or type(name) ~= "string" then return end
   local granted = devShim.permissions[modId] or {}
   local function warnOnce(permission)
     local key = modId .. "|" .. permission .. "|" .. name
@@ -188,6 +194,7 @@ function Loader:_installDevShim()
   for id, mod in pairs(self.mods) do
     devShim.permissions[id] = mod.manifest.permissionSet
   end
+  devShim.dev = self.dev
   if devShim.installed then return end
   devShim.installed = true
   local delegate = require
@@ -195,12 +202,22 @@ function Loader:_installDevShim()
     -- only the mod's own call is the mod's doing; whatever that module
     -- requires in turn is the engine wiring itself up
     if devShim.depth == 0 then
-      scanRequire(name)
+      -- Backstop for the deny list Sandbox.envFor's require already applies:
+      -- an engine module requiring io is the engine wiring itself up, a mod
+      -- doing it is the hole this closes, and any future path that runs mod
+      -- code without a sandbox env still lands here.
+      local owner = Runtime.currentMod or Runtime.modRequire
+      if owner or callerIsMod(3) then
+        local id = type(owner) == "string" and owner or nil
+        local denial = Sandbox.moduleDenial(name, devShim.permissions[id])
+        if denial then error(("[%s] %s"):format(id or "mod", denial), 0) end
+      end
+      if devShim.dev or devShim.generation ~= 1 then scanRequire(name) end
       -- The Gen 1 name a mod asked for, answered by the Gen 2 arm behind it.
       -- Engine code keeps the real module: src/render/PaletteFX.lua:776
       -- requires src.core.Game on both generations and means it.
       if devShim.generation ~= 1 and Gen2Compat.serves(name)
-          and callerIsMod(3) then
+          and (owner or callerIsMod(3)) then
         local adapter = Gen2Compat.resolve(name, Runtime.currentMod)
         if adapter then
           local key = "adapter|" .. name
@@ -235,7 +252,7 @@ function Loader.new(opts)
     events = Events.new(), hooks = Hooks.new(), content = {}, assets = {},
     exports = {}, migrations = {}, order = {},
     modSave = {}, modOptions = {}, optionSchemas = {}, imageCache = {},
-    modInput = {},
+    modInput = {}, modEnv = {}, stepsQueues = {},
     fs = (opts and opts.fs) or (love and love.filesystem),
     dev = dev,
     -- Which generation this boot is (1 or 2).  Fixed at construction: the
@@ -357,11 +374,13 @@ function Loader:_writeOptionSchemas()
       -- demand; using it here means older mods do not need to migrate to
       -- mod.options:define just to appear in a launcher settings screen.
       if schema == nil and mod.manifest.options_schema and self.fs.load then
-        local chunk = self.fs.load(mod.path .. "/" .. mod.manifest.options_schema)
-        if chunk then
-          local ok, rows = pcall(chunk)
-          if ok and type(rows) == "table" then schema = rows end
-        end
+        local ok, rows = pcall(function()
+          local path = SafePath.join(mod.path, mod.manifest.options_schema,
+            "options_schema")
+          local chunk = Sandbox.loadFile(self.fs, path, self:_modEnv(mod))
+          return chunk and chunk()
+        end)
+        if ok and type(rows) == "table" then schema = rows end
       end
       if schema ~= nil then
         mods[id] = schema
@@ -998,6 +1017,40 @@ function Loader:_api(mod)
         return DateTime.dateTime(game, timestamp)
       end,
     },
+    -- The read-only part of love.system that device UIs legitimately need.
+    -- Do not expose the module: openURL and clipboard access stay sandboxed.
+    device = {
+      powerInfo = function()
+        local getPowerInfo = love and love.system and love.system.getPowerInfo
+        if not getPowerInfo then return "unknown", nil end
+        local state, percent = getPowerInfo()
+        return state, percent
+      end,
+    },
+    -- The native step bridge (#1186), behind the "steps" permission the
+    -- player sees in the mod manager: sync asks the platform to refresh
+    -- its count, poll hands this mod its copy of what the bridge
+    -- delivered.  The engine owns the pending file -- a mod never names a
+    -- path, it only receives { steps, from, to }.  available() answers
+    -- false without the permission (a probe stays quiet); the calls that
+    -- would do something name the missing permission instead, the way the
+    -- network gate does.
+    steps = (function()
+      if mod.manifest.permissionSet.steps then
+        loader.stepsQueues[modId] = loader.stepsQueues[modId] or {}
+        return {
+          available = function() return Steps.available() end,
+          sync = function() return Steps.sync() end,
+          poll = function() return Steps.poll(loader, modId) end,
+        }
+      end
+      local function refuse()
+        error(('[%s] mod.steps needs the "steps" permission in '
+          .. "manifest.json"):format(modId), 2)
+      end
+      return { available = function() return false end,
+               sync = refuse, poll = refuse }
+    end)(),
     -- namespaced per mod; M11 backs these with save.modData /
     -- options.modOptions, the shape mods compile against is already final
     save = {
@@ -1108,9 +1161,11 @@ function Loader:_api(mod)
   -- assets keeps the v1 alias to the content accessors and adds the file
   -- helpers on top, so mod.assets.pokemon and mod.assets:image both resolve
   api.assets = setmetatable({
-    path = function(_, relative) return mod.path .. "/" .. relative end,
+    path = function(_, relative)
+      return SafePath.join(mod.path, relative, "mod.assets:path")
+    end,
     image = function(_, relative)
-      local full = mod.path .. "/" .. relative
+      local full = SafePath.join(mod.path, relative, "mod.assets:image")
       local cached = loader.imageCache[full]
       if cached then return cached end
       assert(love and love.graphics,
@@ -1120,9 +1175,10 @@ function Loader:_api(mod)
       return image
     end,
   }, { __index = api.content })
+  -- the mod's own directory and nothing above it: PhysFS already refuses a
+  -- climb, but loader.fs is injectable and has no such floor
   function api:read(relative)
-    local path = self.path .. "/" .. relative
-    return loader.fs.read(path)
+    return loader.fs.read(SafePath.join(self.path, relative, "mod:read"))
   end
   -- mod.world materializes on first touch, like the image helper above: a
   -- headless load must not drag the world stack in, and the Game the facade
@@ -1166,9 +1222,21 @@ function Loader:_game()
   return engineRequire("src.core.Game")
 end
 
+-- The environment every chunk this mod authors runs in, built once per mod so
+-- its entry file and its options_schema share one globals table.
+function Loader:_modEnv(mod)
+  local id = mod.manifest.id
+  local env = self.modEnv[id]
+  if not env then
+    env = Sandbox.envFor({ modId = id, permissions = mod.manifest.permissionSet })
+    self.modEnv[id] = env
+  end
+  return env
+end
+
 function Loader:_loadMod(mod)
-  local path = mod.path .. "/" .. mod.manifest.entry
-  local chunk, err = self.fs.load(path)
+  local path = SafePath.join(mod.path, mod.manifest.entry, "manifest entry")
+  local chunk, err = Sandbox.loadFile(self.fs, path, self:_modEnv(mod))
   if not chunk then error(err or ("unable to load " .. path)) end
   local api = self:_api(mod)
   local result = chunk(api)
@@ -1200,6 +1268,7 @@ function Loader:_rollback(modId)
   self.optionSchemas[modId] = nil
   self.migrations[modId] = nil
   self.modSave[modId] = nil
+  self.stepsQueues[modId] = nil
 end
 
 -- a mod that explicitly swears it stays link-compatible while writing into a
@@ -1383,10 +1452,12 @@ function Loader:load(data)
   -- every touch: a mod captures the facade at file scope, before Game2 has a
   -- save or a world (src/mods/Gen2Compat.lua).
   Gen2Compat.bind(function() return self:_game() end)
-  -- Dev mode wants the permissions tripwire; a Gold boot with mods on it wants
-  -- the Gen 1-only require report, which is the difference between "the mod
-  -- does nothing" and knowing why.  A Gold boot with no mods pays nothing.
-  if self.dev or (self.generation ~= 1 and next(self.mods) ~= nil) then
+  -- Any boot with mods on it needs the gate, because require("io") is how a
+  -- mod would walk out of Sandbox.envFor.  Dev mode adds the permissions
+  -- tripwire on top, and a Gold boot the Gen 1-only require report -- the
+  -- difference between "the mod does nothing" and knowing why.  A boot with no
+  -- mods pays nothing.
+  if self.dev or next(self.mods) ~= nil then
     self:_installDevShim()
   end
   for _, mod in ipairs(ordered) do

src/mods/ManagerState.lua

@@ -8,6 +8,8 @@ local Font = require("src.render.Font")
 local GameVersion = require("src.core.GameVersion")
 local ModTargets = require("src.mods.ModTargets")
 local Runtime = require("src.mods.Runtime")
+local SafePath = require("src.mods.SafePath")
+local Sandbox = require("src.mods.Sandbox")
 local SaveData = require("src.core.SaveData")
 local Semver = require("src.mods.Semver")
 local Version = require("src.core.Version")
@@ -935,13 +937,18 @@ function ManagerState:schemaFor(m)
   local schema = loader.optionSchemas and loader.optionSchemas[m.id]
   if schema == nil and m.options_schema and m.path
       and loader.fs and loader.fs.load then
-    local chunk = loader.fs.load(m.path .. "/" .. m.options_schema)
-    if chunk then
-      local ok, rows = pcall(chunk)
-      if ok and type(rows) == "table" then
-        schema = rows
-        if loader.optionSchemas then loader.optionSchemas[m.id] = schema end
-      end
+    -- mod-authored code, so it runs in the same sandbox the entry chunk does
+    local ok, rows = pcall(function()
+      local path = SafePath.join(m.path, m.options_schema, "options_schema")
+      local mod = loader.mods and loader.mods[m.id]
+      local env = mod and loader._modEnv and loader:_modEnv(mod)
+        or Sandbox.envFor()
+      local chunk = Sandbox.loadFile(loader.fs, path, env)
+      return chunk and chunk()
+    end)
+    if ok and type(rows) == "table" then
+      schema = rows
+      if loader.optionSchemas then loader.optionSchemas[m.id] = schema end
     end
   end
   return schema

src/mods/Manifest.lua

@@ -3,13 +3,15 @@
 -- that need to stat a file, this owns shape, vocabulary and range grammar.
 local Logger = require("src.core.Logger")
 local ModTargets = require("src.mods.ModTargets")
+local SafePath = require("src.mods.SafePath")
 local Semver = require("src.mods.Semver")
 local Version = require("src.core.Version")
 
 local Manifest = {}
 
 Manifest.PROFILES = { content = true, overhaul = true, total_conversion = true }
-Manifest.PERMISSIONS = { network = true, filesystem = true, engine_internals = true }
+Manifest.PERMISSIONS = { network = true, filesystem = true,
+                         engine_internals = true, steps = true }
 
 -- link-relevant registries; a mod that writes into one of these while
 -- declaring affects_link = false gets an attributed warning from the loader
@@ -187,6 +189,9 @@ function Manifest.validate(raw, path)
   assert(type(raw.name) == "string" and raw.name ~= "", "manifest name is required")
   assert(type(raw.version) == "string" and raw.version ~= "", "manifest version is required")
   assert(type(raw.entry) == "string" and raw.entry ~= "", "manifest entry is required")
+  -- every manifest path is joined to the mod's own directory, so none of them
+  -- may climb out of it (src/mods/SafePath.lua)
+  local entry = SafePath.require(raw.entry, "manifest entry")
 
   -- absent means 1: full v1 compat, schema violations downgrade to warnings
   assert(raw.api == nil or tonumber(raw.api) ~= nil, "manifest api must be a number")
@@ -272,19 +277,24 @@ function Manifest.validate(raw, path)
   local affectsLink = profile ~= "content" and not language
   if type(raw.affects_link) == "boolean" then affectsLink = raw.affects_link end
 
-  local function optionalFile(value, field)
+  local function optionalString(value, field)
     if value == nil then return nil end
     assert(type(value) == "string" and value ~= "", field .. " must be a file path")
     return value
   end
 
+  local function optionalFile(value, field)
+    local text = optionalString(value, field)
+    return text and SafePath.require(text, field)
+  end
+
   local conflicts = mergeConflictLists(raw.conflicts, raw.incompatible)
 
   return {
     id = raw.id,
     name = raw.name,
     version = raw.version,
-    entry = raw.entry,
+    entry = entry,
     api = api,
     priority = tonumber(raw.priority) or 0,
     dependencies = array(raw.dependencies),
@@ -308,7 +318,8 @@ function Manifest.validate(raw, path)
     permissionSet = permissionSet,
     options_schema = optionalFile(raw.options_schema, "options_schema"),
     assets_transforms = optionalFile(raw.assets_transforms, "assets_transforms"),
-    force_enable_env = optionalFile(raw.force_enable_env, "force_enable_env"),
+    -- an env var name, not a path, so it keeps the plain string check
+    force_enable_env = optionalString(raw.force_enable_env, "force_enable_env"),
     path = path,
     raw = raw,
   }

src/mods/Runtime.lua

@@ -28,6 +28,11 @@ Runtime.errors = nil
 -- permissions tripwire knows there is nobody to attribute to
 Runtime.currentMod = nil
 
+-- set by the sandbox's require for the duration of one mod-initiated require,
+-- so the loader's gate can still attribute a lazy one made long after
+-- currentMod went back to nil (src/mods/Sandbox.lua)
+Runtime.modRequire = nil
+
 function Runtime.install(events, hooks, errors)
   Runtime.events, Runtime.hooks = events, hooks
   Runtime.errors = errors

src/mods/SafePath.lua

@@ -0,0 +1,38 @@
+-- One relative-path grammar for every path a mod supplies: a mod names files
+-- inside its own directory and nowhere else.  love.filesystem (PhysFS) already
+-- refuses "..", absolute paths and backslashes, but Loader.new takes an
+-- injected fs that has no such floor, so the rule lives here and not in
+-- whichever filesystem happens to be underneath.
+local SafePath = {}
+
+-- The normalized path, or nil when it could climb out of the root it is about
+-- to be joined to.  "." segments are dropped rather than rejected so a
+-- manifest that says "./main.lua" still loads.
+function SafePath.safe(rel)
+  if type(rel) ~= "string" or rel == "" then return nil end
+  if rel:sub(1, 1) == "/" then return nil end
+  if rel:find("\\", 1, true) then return nil end
+  if rel:match("^%a:") then return nil end -- windows drive-relative
+  local parts = {}
+  for segment in rel:gmatch("[^/]+") do
+    if segment == ".." then return nil end
+    if segment ~= "." then parts[#parts + 1] = segment end
+  end
+  if #parts == 0 then return nil end
+  return table.concat(parts, "/")
+end
+
+function SafePath.require(rel, what)
+  local safe = SafePath.safe(rel)
+  if not safe then
+    error(("%s must stay inside its root, got %q"):format(what, tostring(rel)), 0)
+  end
+  return safe
+end
+
+-- root .. "/" .. rel, with the traversal check in between
+function SafePath.join(root, rel, what)
+  return root .. "/" .. SafePath.require(rel, what or "path")
+end
+
+return SafePath

src/mods/Sandbox.lua

@@ -0,0 +1,228 @@
+-- The environment a mod's own code runs in.  Every chunk a mod authors -- the
+-- entry file, an options_schema, anything it hands to load() -- runs against
+-- this table instead of _G, so the only paths it can name are the ones the
+-- engine hands it (mod:read, mod.storage, mod.assets).
+--
+-- What this is and is not: raw io/os/ffi are the only way to name a file
+-- outside the game tree at all, and they are absent here, so the reported
+-- "any mod can rewrite anything in your home directory" hole closes by
+-- construction.  Inside the LÖVE tree this is defense in depth, not a security
+-- boundary: an engine module reached through require, or ImageData:encode,
+-- still writes in the save directory.
+--
+-- Lua 5.1/LuaJIT is the target, so setfenv is the mechanism; the 5.2+ arm
+-- exists because AssetTransform's sandbox needed it and getting this wrong
+-- silently hands the chunk the real globals.
+
+local Runtime = require("src.mods.Runtime")
+local SafePath = require("src.mods.SafePath")
+
+local Sandbox = {}
+
+-- Modules that hand a mod the disk, a raw socket or a fresh Lua state no
+-- matter what this file removes from the environment.  package.loaded.io is
+-- the one call that would undo every other rule here.
+local DENIED = {
+  io = "the filesystem", os = "the filesystem", debug = "the debug library",
+  package = "the module loader", ffi = "arbitrary C calls",
+}
+
+-- Same idea one level up: love.filesystem is reachable by name, and
+-- love.thread starts a Lua state this sandbox has no say over.
+local DENIED_PREFIX = { ["love"] = true, ["ffi"] = true }
+
+-- The wire, which is what the network permission governs.
+local NETWORK = { socket = true, enet = true, http = true, https = true,
+                  ssl = true, mime = true, ltn12 = true }
+
+local function head(name)
+  return (name:match("^([^%.]+)")) or name
+end
+
+-- nil when the require is allowed, else the message to fail it with.
+function Sandbox.moduleDenial(name, permissionSet)
+  if type(name) ~= "string" then return nil end
+  local root = head(name)
+  local reason = DENIED[root]
+  if reason then
+    return ("%s is not available to mods (it grants %s); use mod.storage, "
+      .. "mod:read and the engine API instead"):format(name, reason)
+  end
+  if DENIED_PREFIX[root] and name ~= root then
+    return ("%s is not available to mods; use mod.storage, mod:read and the "
+      .. "engine API instead"):format(name)
+  end
+  if NETWORK[root] and not (permissionSet or {}).network then
+    return ("%s needs the \"network\" permission in manifest.json"):format(name)
+  end
+  return nil
+end
+
+-- ------- the love facade
+
+-- Dropped, not narrowed: filesystem writes anywhere in the save directory
+-- (including another mod's storage), thread opens a Lua state with a full
+-- standard library, system.openURL launches whatever it is handed, and event
+-- lets a mod quit the game out from under the player.  Everything else LÖVE
+-- exposes passes through, so a new module in a future LÖVE is available
+-- without an edit here.
+-- value is the replacement to name in the error, or true when there is none
+local BLOCKED_LOVE = {
+  filesystem = "mod.storage and mod:read", thread = true,
+  system = "mod.device:powerInfo() for battery information, mod.steps for "
+    .. "the step bridge", event = true,
+}
+
+local loveProxy
+local function loveFacade()
+  if loveProxy or not _G.love then return loveProxy end
+  loveProxy = setmetatable({}, {
+    __index = function(_, key)
+      local hint = BLOCKED_LOVE[key]
+      if hint then
+        error(("love.%s is not available to mods%s"):format(key,
+          type(hint) == "string" and (", use " .. hint) or ""), 2)
+      end
+      return _G.love[key]
+    end,
+    __newindex = function(_, key)
+      error(("mods cannot assign love.%s"):format(tostring(key)), 2)
+    end,
+  })
+  return loveProxy
+end
+
+-- ------- the environment
+
+-- Absent on purpose: io, package, dofile, loadfile, getfenv, setfenv, debug,
+-- newproxy, module.  os keeps only the clock -- getenv is how the reported
+-- exploit found the user's home directory.
+local SAFE_OS = { time = true, date = true, clock = true, difftime = true }
+
+-- Per-mod copies, not the shared tables: a mod that assigns string.trim or
+-- replaces table.insert changes its own view and nobody else's.  The functions
+-- are the same objects, so state behind them (math.randomseed's RNG) is
+-- unaffected -- only the namespace is private.
+local function copy(source)
+  if type(source) ~= "table" then return source end
+  local out = {}
+  for key, value in pairs(source) do out[key] = value end
+  return out
+end
+
+local function baseGlobals()
+  local safeOs = {}
+  for key in pairs(SAFE_OS) do safeOs[key] = os[key] end
+  return {
+    assert = assert, error = error, ipairs = ipairs, next = next,
+    pairs = pairs, pcall = pcall, xpcall = xpcall, select = select,
+    tonumber = tonumber, tostring = tostring, type = type, unpack = unpack,
+    rawequal = rawequal, rawget = rawget, rawset = rawset, rawlen = rawlen,
+    setmetatable = setmetatable, getmetatable = getmetatable, print = print,
+    collectgarbage = collectgarbage, _VERSION = _VERSION,
+    coroutine = copy(coroutine), math = copy(math), string = copy(string),
+    table = copy(table), bit = copy(bit), jit = jit, os = safeOs,
+  }
+end
+
+-- setfenv on 5.1/LuaJIT; on 5.2+ the env has to be handed to load itself, so
+-- a caller there compiles through Sandbox.compile instead.
+function Sandbox.bind(chunk, env)
+  if setfenv then setfenv(chunk, env) end
+  return chunk
+end
+
+-- Bytecode is unreviewable and, on LuaJIT, a way out of any sandbox built out
+-- of environments.  Mods ship source.
+local function rejectBytecode(source, what)
+  if type(source) == "string" and source:sub(1, 1) == "\27" then
+    return nil, (what or "chunk") .. ": mods must ship Lua source, not bytecode"
+  end
+  return true
+end
+
+function Sandbox.compile(source, chunkname, env)
+  local ok, err = rejectBytecode(source, chunkname)
+  if not ok then return nil, err end
+  if setfenv then
+    local chunk, compileErr = loadstring(source, chunkname)
+    if not chunk then return nil, compileErr end
+    return setfenv(chunk, env)
+  end
+  return load(source, chunkname, "t", env)
+end
+
+-- The load() a mod sees.  Lua 5.1 gives a loaded chunk the GLOBAL environment
+-- rather than the caller's, so without this every sandboxed mod is one
+-- load(mod:read(...)) away from the real _G -- which is exactly how the
+-- multi-file mods in mods/ are written.
+local function sandboxedLoad(env)
+  return function(chunk, chunkname)
+    if type(chunk) == "function" then
+      local parts = {}
+      while true do
+        local piece = chunk()
+        if piece == nil or piece == "" then break end
+        parts[#parts + 1] = piece
+      end
+      chunk = table.concat(parts)
+    end
+    if type(chunk) ~= "string" then return nil, "load expects a string or reader" end
+    return Sandbox.compile(chunk, chunkname or "=(load)", env)
+  end
+end
+
+-- The require a mod sees: the deny list lives here rather than on a stack
+-- walk, because pcall(require, "io") puts a C frame where the walk would look.
+-- Runtime.modRequire is how the loader's gate identifies the caller for the
+-- Gen 2 facade once Runtime.currentMod has gone back to nil (a mod requiring
+-- lazily from an event handler).
+local function sandboxedRequire(modId, permissionSet)
+  return function(name, ...)
+    local denial = Sandbox.moduleDenial(name, permissionSet)
+    if denial then error(("[%s] %s"):format(modId or "mod", denial), 2) end
+    local previous = Runtime.modRequire
+    Runtime.modRequire = modId or true
+    local ok, result = pcall(_G.require, name, ...)
+    Runtime.modRequire = previous
+    if not ok then error(result, 0) end
+    return result
+  end
+end
+
+function Sandbox.envFor(opts)
+  opts = opts or {}
+  local env = baseGlobals()
+  env.love = loveFacade()
+  env.require = sandboxedRequire(opts.modId, opts.permissions)
+  local loader = sandboxedLoad(env)
+  env.load = loader
+  env.loadstring = loader
+  -- a mod's globals are its own: two mods no longer share a namespace, and
+  -- neither can reach the engine's
+  env._G = env
+  return env
+end
+
+-- fs.load keeps the real filesystem's handling of the file; the environment is
+-- swapped after the fact.  The 5.2+ arm has to go back to source, which is the
+-- only reason fs.read is touched here.
+function Sandbox.loadFile(fs, path, env)
+  if fs.read then
+    local ok, err = rejectBytecode(fs.read(path), path)
+    if not ok then return nil, err end
+  end
+  if setfenv then
+    local chunk, err = fs.load(path)
+    if not chunk then return nil, err end
+    return setfenv(chunk, env)
+  end
+  local source = fs.read and fs.read(path)
+  if not source then return nil, "unable to read " .. path end
+  return Sandbox.compile(source, "@" .. path, env)
+end
+
+Sandbox.safePath = SafePath.safe
+Sandbox.requirePath = SafePath.require
+
+return Sandbox

src/mods/Steps.lua

@@ -0,0 +1,84 @@
+-- The scoped seam for the native step bridge (#1186).
+--
+-- The iOS/Android builds count the player's real-world steps natively
+-- (#452, #489) and deliver them by writing steps_pending.json into the
+-- save-directory root.  Before the sandbox, the Pokéwalker mod called
+-- love.system.syncHealthSteps() and consumed that file itself; the sandbox
+-- blocks both, which is correct -- love.system launches URLs and the file
+-- API names paths -- but it left the bridge with no consumer at all.
+--
+-- This module is the narrow replacement, gated by the "steps" permission
+-- in manifest.json (the network model: a permission the player sees that
+-- genuinely gates a capability).  The engine owns the file: mods never
+-- learn its name or location, they receive only the three contract fields
+-- ({ steps, from, to }), each permissioned mod gets its own copy, and the
+-- merge-don't-overwrite anchor semantics stay on the native side where
+-- they always lived.
+--
+-- No frame pump: the file is looked for lazily when a mod polls, so a
+-- build with no permissioned mod installed never touches the bridge or
+-- the disk.
+
+local Json = require("src.link.Json")
+
+local Steps = {}
+
+-- The native contract's drop point, in the save-directory root (see
+-- mobile/ios and mobile/android step bridges).
+Steps.PENDING = "steps_pending.json"
+
+local function bridge()
+  return _G.love and _G.love.system and _G.love.system.syncHealthSteps
+end
+
+-- Whether this build carries the native bridge.  Desktop builds do not;
+-- a mod uses this to stay dormant without probing love.system.
+function Steps.available()
+  return bridge() ~= nil
+end
+
+-- Ask the native side to refresh its count.  Async: the result lands in
+-- the pending file and comes back through a later poll.  The platform's
+-- own consent sheet (HealthKit / ACTIVITY_RECOGNITION) still appears on
+-- first use, exactly as it did pre-sandbox.  false when there is no
+-- bridge to ask.
+function Steps.sync()
+  local fn = bridge()
+  if not fn then return false end
+  fn()
+  return true
+end
+
+-- Consume the pending file, if one has appeared, and fan its payload out
+-- to every permissioned mod's queue.  Only the contract fields travel;
+-- anything else in the file stays in the file's grave.  A malformed or
+-- empty delivery is dropped whole -- the native anchor only advances on a
+-- successful sync, so nothing is lost to a bad write.
+function Steps.pump(loader)
+  local fs = _G.love and _G.love.filesystem
+  if not (fs and fs.getInfo(Steps.PENDING, "file")) then return end
+  local raw = fs.read(Steps.PENDING)
+  fs.remove(Steps.PENDING)
+  if not raw then return end
+  local ok, decoded = pcall(Json.decode, raw)
+  if not ok or type(decoded) ~= "table" then return end
+  local steps = tonumber(decoded.steps)
+  if not steps or steps <= 0 then return end
+  local payload = { steps = steps, from = decoded.from, to = decoded.to }
+  for _, queue in pairs(loader.stepsQueues) do
+    queue[#queue + 1] = { steps = payload.steps, from = payload.from,
+                          to = payload.to }
+  end
+end
+
+-- The next delivery for this mod, or nil.  Each permissioned mod consumes
+-- its own queue, so two mods both see the same walk (pre-sandbox, whoever
+-- read the file first won).
+function Steps.poll(loader, modId)
+  Steps.pump(loader)
+  local queue = loader.stepsQueues[modId]
+  if not queue then return nil end
+  return table.remove(queue, 1)
+end
+
+return Steps