"title":"Command to Create/Update Rune for Authorizing Remote Peer Access",
"description":[
"The **createrune** 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 simply decodes and checks them as they are received.",
"",
"Oh, I almost forgot. Runes can also be invoked like in ancient times with the **invokerune** command. Feel the magical powers of a rune by invoking it."
],
"request":{
"required":[],
"properties":{
"rune":{
"type":"string",
"description":[
"If supplied, the restrictions are simple appended to that *rune* (it doesn't need to be a rune belonging to this node). If not supplied, a new *rune* is constructed, with a new unique id."
]
},
"restrictions":{
"description":[
"It can be the string `readonly`, or an array of restrictions.",
"Each restriction is an array of one or more alternatives, such as \"method is listpeers\", or \"method is listpeers OR time is before 2023\"."
],
"oneOf":[
{
"type":"array",
"description":[
"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\".",
" * per: how often the rune can be used, with suffix \"sec\" (default), \"min\", \"hour\", \"day\" or \"msec\", \"usec\" or \"nsec\". e.g. \"per=5sec\".",
" * rate: the rate limit, per minute, e.g. \"rate=60\" is equivalent to \"per=1sec\".",
" * pnum: the number of parameters. e.g. \"pnum<2\".",
" * pnameX: the parameter named X e.g. \"pnamedestination=1RustyRX2oai4EYYDpQGWvEL62BBGqN9T\". NOTE: until v24.05, X had to remove underscores from the parameter name (e.g. `pnameamount_msat` had to be specified as `pnameamountmsat`) but that is now fixed.",
"Let's create a rune which lets a specific peer (024b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605) run \"listpeers\" on themselves:",
"This allows `listpeers` with 1 argument (`pnum=1`), which is either by name (`pnameid`), or position (`parr0`). We could shorten this in several ways: either allowing only positional or named parameters, or by testing the start of the parameters only. Here's an example which only checks the first 9 bytes of the `listpeers` parameter:",
"Before we give this to our peer, let's add two more restrictions: that it only be usable for 24 hours from now (`time<`), and that it can only be used twice a minute (`rate=2`). `date +%s` can give us the current time in seconds:",
" \"summary\": \"id (of commanding peer) equal to '024b9a1fa8e006f1e3937f65f66c408e6da8e1ca728ea43222a7381df1cc449605'\"",
" },",
" {",
" \"alternatives\": [",
" \"method=listpeers\"",
" ],",
" \"summary\": \"method (of command) equal to 'listpeers'\"",
" },",
" {",
" \"alternatives\": [",
" \"pnum=1\"",
" ],",
" \"summary\": \"pnum (number of command parameters) equal to 1\"",
" },",
" {",
" \"alternatives\": [",
" \"pnameid^024b9a1fa8e006f1e393\",",
" \"parr0^024b9a1fa8e006f1e393\"",
" ],",
" \"summary\": \"pnameid (object parameter 'id') starts with '024b9a1fa8e006f1e393' OR parr0 (array parameter #0) starts with '024b9a1fa8e006f1e393'\"",
" },",
" {",
" \"alternatives\": [",
" \"time<1656920538\"",
" ],",
" \"summary\": \"time (in seconds since 1970) less than 1656920538 (approximately 19 hours 18 minutes from now)\"",
" },",
" {",
" \"alternatives\": [",
" \"rate=2\"",
" ],",
" \"summary\": \"rate (max per minute) equal to 2\"",
" }",
" ],",
" \"valid\": true",
"}",
"```"
],
"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.",
"",
"If a rune has a ratelimit, any derived rune will have the same id, and thus will compete for that ratelimit. You might want to consider adding a tighter ratelimit to a rune before sharing it, so you will keep the remainder. For example, if you rune has a limit of 60 times per minute, adding a limit of 5 times per minute and handing that rune out means you can still use your original rune 55 times per minute."
