doc: document commando and commando-rune.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

doc/Makefile

@@ -13,6 +13,8 @@ MANPAGES := doc/lightning-cli.1 \
 	doc/lightning-checkmessage.7 \
 	doc/lightning-close.7 \
 	doc/lightning-connect.7 \
+	doc/lightning-commando.7 \
+	doc/lightning-commando-rune.7 \
 	doc/lightning-createonion.7 \
 	doc/lightning-createinvoice.7 \
 	doc/lightning-datastore.7 \

doc/index.rst

@@ -35,6 +35,8 @@ Core Lightning Documentation
    lightning-checkmessage <lightning-checkmessage.7.md>
    lightning-cli <lightning-cli.1.md>
    lightning-close <lightning-close.7.md>
+   lightning-commando <lightning-commando.7.md>
+   lightning-commando-rune <lightning-commando-rune.7.md>
    lightning-connect <lightning-connect.7.md>
    lightning-createinvoice <lightning-createinvoice.7.md>
    lightning-createonion <lightning-createonion.7.md>

doc/lightning-commando-rune.7.md

@@ -0,0 +1,101 @@
+lightning-commando-rune -- Command to Authorize Remote Peer Access
+===================================================================
+
+SYNOPSIS
+--------
+
+**commando-rune** [*rune*] [*restrictions*]
+
+DESCRIPTION
+-----------
+
+The **commando-rune** RPC command creates a base64 string called a
+*rune* which can be used to access commands on this node.  Each *rune*
+contains a unique id (a number starting at 0), and can have
+restrictions inside it.  Nobody can remove restrictions from a rune: if
+you try, the rune will be rejected.  There is no limit on how many
+runes you can issue: the node doesn't store them, but simply decodes
+and checks them as they are received.
+
+If *rune* is supplied, the restrictions are simple appended to that
+*rune* (it doesn't need to be a rune belonging to this node).  If no
+*rune* is supplied, a new one is constructed, with a new unique id.
+
+*restrictions* can be the string "readonly" (creates a rune which
+allows most *get* and *list* commands, and the *summary* command), or
+an array of restrictions, or a single resriction.
+
+Each restriction is a set of one or more alternatives, such as "method
+is listpeers", or "method is listpeers OR time is before 2023".
+Alternatives use a simple language to examine the command which is
+being run:
+
+* time: the current UNIX time, e.g. "time<1656759180".
+* id: the node_id of the peer, e.g. "id=024b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605".
+* method: the command being run, e.g. "method=withdraw".
+* pnameX: the parameter named X. e.g. "pnamedestination=1RustyRX2oai4EYYDpQGWvEL62BBGqN9T".
+
+RESTRICTION FORMAT
+------------------
+
+Restrictions are one or more altneratives, separated by `|`.  Each
+alternative is *name* *operator* *value*.  The valid names are shown
+above.  If a value contains `|`, `&` or `\\`, it must be preceeded by
+a `\\`.
+
+* `=`: passes if equal ie. identical. e.g. `method=withdraw`
+* `/`: not equals, e.g. `method/withdraw`
+* `^`: starts with, e.g. `id^024b9a1fa8e006f1e3937f`
+* `$`: ends with, e.g. `id$381df1cc449605`.
+* `~`: contains, e.g. `id~006f1e3937f65f66c40`.
+* `<`: is a decimal integer, and is less than. e.g. `time<1656759180`
+* `>`: is a decimal integer, and is greater than. e.g. `time>1656759180`
+* `{`: preceeds in alphabetical order (or matches but is shorter), e.g. `id{02ff`.
+* `}`: follows in alphabetical order (or matches but is longer), e.g. `id}02ff`.
+* `#`: a comment, ignored, e.g. `dumb example#`.
+* `!`: only passes if the *name* does *not* exist. e.g. `pnamedestination!`.
+       Every other operator except `#` fails if *name* does not exist!
+
+For example, the "readonly" restriction is actually two restrictions:
+
+1. `method^list|method^get|method=summary`: You may call list, get or summary.
+2.  `method/listdatastore`: But not listdatastore: that contains sensitive stuff!
+
+SHARING RUNES
+-------------
+
+Because anyone can add a restriction to a rune, you can always turn a
+normal rune into a read-only rune, or restrict access for 30 minutes
+from the time you give it to someone.  Adding restrictions before
+sharing runes is best practice.
+
+RETURN VALUE
+------------
+
+[comment]: # (GENERATE-FROM-SCHEMA-START)
+On success, an object is returned, containing:
+- **rune** (string): the resulting rune
+- **unique_id** (string): the id of this rune: this is set at creation and cannot be changed (even as restrictions are added)
+
+[comment]: # (GENERATE-FROM-SCHEMA-END)
+
+AUTHOR
+------
+
+Rusty Russell <<rusty@rustcorp.com.au>> wrote the original Python
+commando.py plugin, the in-tree commando plugin, and this manual page.
+
+Christian Decker came up with the name "commando", which almost
+excuses his previous adoption of the name "Eltoo".
+
+SEE ALSO
+--------
+
+lightning-commando(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:598337212d2e8a6833698e931f838d8cb424c353af4d7adf6891803ff0ee604b)

doc/lightning-commando.7.md

@@ -0,0 +1,52 @@
+lightning-commando -- Command to Send a Command to a Remote Peer
+================================================================
+
+SYNOPSIS
+--------
+
+**commando** *peer_id* *method* [*params*] [*rune*]
+
+DESCRIPTION
+-----------
+
+The **commando** RPC command is a homage to bad 80s movies.  It also
+sends a directly-connected *peer_id* a custom message, containing a
+request to run *method* (with an optional dictionary of *params*);
+generally the peer will only allow you to run a command if it has
+provided you with a *rune* which allows it.
+
+RETURN VALUE
+------------
+
+On success, the return depends on the *method* invoked.
+
+On failure, one of the following error codes may be returned:
+
+- -32600: Usually means peer is not connected
+- 19535: the local commando plugin discovered an error.
+- 19536: the remote commando plugin discovered an error.
+- 19537: the remote commando plugin said we weren't authorized.
+
+It can also fail if the peer does not respond, in which case it will simply
+hang awaiting a response.
+
+AUTHOR
+------
+
+Rusty Russell <<rusty@rustcorp.com.au>> wrote the original Python
+commando.py plugin, the in-tree commando plugin, and this manual page.
+
+Christian Decker came up with the name "commando", which almost
+excuses his previous adoption of the name "Eltoo".
+
+SEE ALSO
+--------
+
+lightning-commando-rune(7)
+
+RESOURCES
+---------
+
+Main web site: <https://github.com/ElementsProject/lightning>
+
+[comment]: # ( SHA256STAMP:6f4406cae30cab813b3bf4e1242af914276716a057e558474e29340665ee8c2f)

doc/schemas/commando-rune.request.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [],
+  "properties": {
+    "rune": {
+      "type": "string",
+      "description": "optional rune to add to"
+    },
+    "restrictions": {
+      "oneOf": [
+        {
+          "type": "array",
+          "description": "array of restrictions to add to rune",
+          "items": {
+            "type": "string"
+          }
+        },
+        {
+          "type": "string",
+          "description": "single restrictions to add to rune, or readonly."
+        }
+      ]
+    }
+  }
+}

doc/schemas/commando-rune.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "rune",
+    "unique_id"
+  ],
+  "properties": {
+    "rune": {
+      "type": "string",
+      "description": "the resulting rune"
+    },
+    "unique_id": {
+      "type": "string",
+      "description": "the id of this rune: this is set at creation and cannot be changed (even as restrictions are added)"
+    }
+  }
+}

doc/schemas/commando.request.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "peer_id",
+    "method"
+  ],
+  "properties": {
+    "peer_id": {
+      "type": "pubkey",
+      "description": "peer to command"
+    },
+    "method": {
+      "type": "string",
+      "description": "method to invoke on peer"
+    },
+    "params": {
+      "type": "object",
+      "description": "parameters for method"
+    },
+    "rune": {
+      "type": "string",
+      "description": "rune to authorize the command"
+    }
+  }
+}