Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/luk3yx/minetest-sscsm

Lua implementation of Server-Sent CSMs for Minetest
https://github.com/luk3yx/minetest-sscsm

Last synced: 18 days ago
JSON representation

Lua implementation of Server-Sent CSMs for Minetest

Awesome Lists containing this project

README 

        
# Minetest server-sent CSM proof-of-concept



[![Build status](https://github.com/luk3yx/minetest-sscsm/workflows/build/badge.svg)](https://github.com/luk3yx/minetest-sscsm/actions)



[Source](https://git.minetest.land/luk3yx/sscsm)



Attempts to run server-sent CSMs locally in a sandbox.



## 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:



 - Install this mod onto a server.

 - Enable mod channels on the server (add `enable_mod_channels = true` to

     minetest.conf).

 - Allow CSMs to send chat messages if you haven't already (add

     `csm_restriction_flags = 60` to minetest.conf).

 - Create SSCSMs with the API.

 - Install the CSM (in the `csm/` directory) onto clients and enable it.



### Preserving copyright and license notices



The minifier preserves comments starting with "copyright" or "license":

(case-insensitive, excluding leading spaces).



Input:



```lua

-- Copyright: 1

-- License: 2

-- A normal comment.

--COPYRIGHT5



...

```



Output:



```lua

-- 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.



 - `name` *(string)*: The name of the server-provided CSM. Please use the

        `modname:sscsmname` convention. Cannot start with a colon or contain

        newlines.

 - `code` *(string)*: The code to be sent to clients.

 - `file` *(string)*: The file to read the code from, read during the

        `register()` call.

 - `depends` *(list)*: A list of SSCSMs that must be loaded before this one.



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](https://github.com/DS-Minetest/csm_com) for sending private messages

to clients. Unlike mod channels, only the target client gets these messages.

Although the API is stable, the internal protocol will probably change in the

future as better CSM API functions are added.



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



 - `sscsm.com_send(player_or_name, channel, msg)`: Sends `msg`

    (a JSON-compatible object) to `player_or_name` on the SSCSM com channel

    `channel`. Channel names should be `modname` or `modname:name` to prevent

    conflicts. *Although the theoretical limit for server-to-client messages is

    128MiB, I strongly recommend not sending large messages when not

    necessary.*

 - `sscsm.com_send_all(channel, msg)`: Sends `msg` to all clients that are

    running SSCSMs.

 - `sscsm.register_on_com_receive(channel, function(name, msg))`: Registers a

    function to be called when a message on `channel` is received from the

    client. `msg` may be any JSON-compatible type, so checking the type of this

    object is strongly recommended.

 - `sscsm.has_sscsms_enabled(name)`: Returns `true` if `name` has enabled

    SSCSMs. This will not be `true` immediately after players join, however.



#### 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](https://github.com/minetest/minetest/blob/master/doc/client_lua_api.txt), as well as a separate `sscsm` namespace:



 - `sscsm.register_on_mods_loaded(callback)`: Runs the callback once all SSCSMs

    are loaded.

 - `sscsm.register_chatcommand(...)`: Similar to

    `minetest.register_chatcommand`, however overrides commands starting in `/`

    instead. This can be used to make some commands have instantaneous

    responses. The command handler is only added once `register_chatcommand`

    has been called.

 - `sscsm.unregister_chatcommand(name)`: Unregisters a chatcommand.

 - `sscsm.get_player_control()`: Alternative for

    `minetest.localplayer:get_control()` that works with Minetest 5.2.0 and

    below.

    - The `LMB` and `RMB` fields are deprecated and will probably be removed in

      the future, use `dig` and `place` instead.

 - `sscsm.every(interval, func, ...)`: Calls `func` every `interval` seconds

    with any extra parameters specified. Use `minetest.register_globalstep`

    instead if `interval` is `0`.

 - `sscsm.restriction_flags`: The `csm_restriction_flags` setting set in

    the server's `minetest.conf`.

 - `sscsm.restrictions`: A table based on `csm_restriction_flags`:

    - `chat_messages`: When `true`, SSCSMs can't send chat messages or run

        server chatcommands.

    - `read_itemdefs`: When `true`, SSCSMs can't read item definitions.

    - `read_nodedefs`: When `true`, SSCSMs can't read node definitions.

    - `lookup_nodes_limit`: When `true`, any get_node calls are restricted.

    - `read_playerinfo`: When `true`, `minetest.get_player_names()` will return

        `nil`.

 - `sscsm.com_send(channel, msg)`: Sends `msg` (a JSON-compatible object) to

    the server. *Note that client-to-server messages cannot be long, for plain

    strings the channel and message combined must be at most 492 characters.*

 - `sscsm.register_on_com_receive(channel, function(msg))`: Registers a

    function to be called when a message on `channel` is received from the

    server.

 - `sscsm.global_exists(name)`: Deprecated, use `minetest.global_exists(name)`

    instead.



### CSM restriction flags example



```lua

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.