SSCSM implementation

A server-sent CSM library.

API / Library / Programmer Tools

This is a mod library and is useless by itself.

How it works

Any client with the CSM installed will automatically attempt to request SSCSMs from the server via a mod channel. If the server has this mod installed, it will reply with a few messages containing the mod name and partially minified mod code. The CSM will then create a separate environment so SSCSMs cannot mess with existing CSMs (and so CSMs do not accidentally interfere with SSCSMs), and execute the SSCSMs inside this environment. Note that it is trivial for users to modify this environment. The server-side mod sends two "built-in" SSCSMs before and after all other SSCSMs to add extra helper functions (in the sscsm namespace), to execute register_on_mods_loaded callbacks and attempt to leave the mod channel.

Instructions

To create a SSCSM:

Preserving copyright and license notices

The minifier preserves comments starting with "copyright" or "license": (case-insensitive, excluding leading spaces).

Input:

-- Copyright: 1
-- License: 2
-- A normal comment.
--COPYRIGHT5

...

Output:

-- Copyright: 1
-- License: 2
--COPYRIGHT5
...

Server-side mod facing API

This API is subject to change.

sscsm.register(def)

Registers a server-provided CSM with the following definition table.

This definition table must have name and either code or file.

sscsm.register_on_sscsms_loaded(function(name))

Registers a function to be called when a client loads SSCSMs. Note that this function will not work unless CSMs have the ability to send chat messages as it relies on the SSCSM communication API described below.

Communication with SSCSMs

SSCSM provides an API inspired by csm_com for sending private messages to clients. Unlike mod channels, only the target client gets these messages. The internal communication protocol is currently unstable and will probably change in a future release.

Note that channel names must not contain \001/U+0001.

Maximum SSCSM size

Because of Minetest network protocol limitations, the amount of data that can be sent over mod channels is limited, and therefore the maximum SSCSM size is 65300 (to leave room for the player name and future expansion). The name of the SSCSM also counts towards this total.

Because of this size limitation, SSCSMs are passed through a primitive code minifier that removes some whitespace and comments, so even if your code is above this size limit it could still work.

Server-sent CSM facing API

SSCSMs can access most functions on client_lua_api.txt, as well as a separate sscsm namespace:

To communicate with the server-side mods, it is possible to open a mod channel.

CSM restriction flags example

minetest.register_chatcommand('m', {
    description = 'Alias for /msg',
    func = function(param)
        if sscsm.restrictions.chat_messages then
            return false, 'Sorry, csm_restriction_flags prevents chat messages'
                .. ' from being sent.'
        end
        minetest.run_server_chatcommand('msg', param)
    end,
})

Note that modifying sscsm.restrictions or sscsm.restriction_flags will not add or remove restrictions and is not recommended.

Security considerations

Do not trust any input sent to the server via SSCSMs (and do not store sensitive data in SSCSM code), as malicious users can and will inspect code and modify the output from SSCSMs.

I repeat, do not trust the client and/or SSCSMs with any sensitive information and do not trust any output from the client and/or SSCSMs. Make sure to rerun any privilege checks on the server.

Other recommendations

Although it is possible to kick clients that do not support SSCSMs, this has not been implemented. Some users may not want to allow servers to automatically download and run code locally for security reasons. Please try and make sure clients without SSCSMs do not suffer from major functionality loss.