{
  "format": 1,
  "seat": "node-files",
  "scope": "node",
  "grain": "seat-list",
  "domain": "Core",
  "decision": "novox/hq ADR 0394",
  "verbs": [
    {
      "name": "stat",
      "description": "Each component of one path or several, from / down: its type, owner and group (name and number), mode, whether it is a link and to what, and whether it is a mount point and of which file system. A link is not followed unless follow is \"true\".  At most 200 paths in one call. Read as the node's operator account, through sudo -n where its rights do not reach; a place a secret is kept, or a known credential file, is refused by name.",
      "replaces": [
        "stat",
        "ls -ld",
        "namei -l",
        "findmnt -T"
      ],
      "input": {
        "properties": {
          "follow": {
            "description": "\"true\": also say where the path leads once every link is followed",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "paths": {
            "description": "one absolute path, or several separated by line breaks",
            "type": "string"
          }
        },
        "required": [
          "paths"
        ],
        "type": "object"
      }
    },
    {
      "name": "readlink",
      "description": "What one link points to, as written, and where the path leads once every link is followed, and whether that exists. Read as the node's operator account, through sudo -n where its rights do not reach; a place a secret is kept, or a known credential file, is refused by name.",
      "replaces": [
        "readlink",
        "readlink -f",
        "realpath"
      ],
      "input": {
        "properties": {
          "path": {
            "description": "an absolute path",
            "type": "string"
          }
        },
        "required": [
          "path"
        ],
        "type": "object"
      }
    },
    {
      "name": "list",
      "description": "Every entry of one directory with its type, owner, group, mode, size and, for a link, its target. At most 2000 entries; a longer directory is cut and says so. A place a secret is kept is refused by name. Read as the node's operator account, through sudo -n where its rights do not reach; a place a secret is kept, or a known credential file, is refused by name.",
      "replaces": [
        "ls",
        "ls -la"
      ],
      "input": {
        "properties": {
          "path": {
            "description": "an absolute path to a directory",
            "type": "string"
          }
        },
        "required": [
          "path"
        ],
        "type": "object"
      }
    },
    {
      "name": "read",
      "description": "One text file, or a part of it by line: at most 256 KiB in one answer (64 KiB unless more is asked), cut at a line and said so. A binary file is refused; a place a secret is kept, or a known credential file, is refused by name; a line shaped like a secret is withheld and its number said. /proc and /sys are read as far as the holder's account may. Read as the node's operator account, through sudo -n where its rights do not reach; a place a secret is kept, or a known credential file, is refused by name.",
      "replaces": [
        "cat",
        "head",
        "tail",
        "less"
      ],
      "input": {
        "properties": {
          "bytes": {
            "description": "the most bytes to answer, up to 262144 (optional, 65536 unless given)",
            "type": "string"
          },
          "from": {
            "description": "the first line to answer, counted from 1 (optional)",
            "type": "string"
          },
          "lines": {
            "description": "how many lines to answer (optional)",
            "type": "string"
          },
          "path": {
            "description": "an absolute path to a file",
            "type": "string"
          }
        },
        "required": [
          "path"
        ],
        "type": "object"
      }
    },
    {
      "name": "search",
      "description": "Find a fixed string (never a pattern) in one file or under one directory: every matching line with its file and number. Bounded: at most 500 matches (100 unless more is asked), 8 directories deep (4 unless more is asked), 5000 files and 4 MiB per file; links are not followed and binary files are skipped. A place a secret is kept is skipped and named; a matching line shaped like a secret is withheld. The answer says which bound it met. Read as the node's operator account, through sudo -n where its rights do not reach; a place a secret is kept, or a known credential file, is refused by name.",
      "replaces": [
        "grep",
        "grep -r",
        "grep -F"
      ],
      "input": {
        "properties": {
          "case": {
            "description": "\"false\": match whatever the case (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "depth": {
            "description": "how many directories deep, up to 8 (optional)",
            "type": "string"
          },
          "matches": {
            "description": "the most matches to answer, up to 500 (optional)",
            "type": "string"
          },
          "path": {
            "description": "an absolute path to a file or a directory",
            "type": "string"
          },
          "text": {
            "description": "the fixed string to find",
            "type": "string"
          }
        },
        "required": [
          "text",
          "path"
        ],
        "type": "object"
      }
    },
    {
      "name": "account",
      "description": "One account or group by name or number, as this node's account files say: an account's number, group, home, shell and every group it is in; a group's number and members. With neither, every account and group. Never a password field. Read as the node's operator account, through sudo -n where its rights do not reach; a place a secret is kept, or a known credential file, is refused by name.",
      "replaces": [
        "getent passwd",
        "getent group",
        "id",
        "groups"
      ],
      "input": {
        "properties": {
          "group": {
            "description": "a group's name or number (optional)",
            "type": "string"
          },
          "name": {
            "description": "an account's name or number (optional)",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    {
      "name": "write",
      "description": "Write one text file whole, replacing what it holds; the old content goes to the node's trash. Refuses a path a module owns unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
      "replaces": [
        "tee",
        "\u003e"
      ],
      "input": {
        "properties": {
          "content": {
            "description": "the text to write",
            "type": "string"
          },
          "mode": {
            "description": "the file's mode, such as 0644 (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "override": {
            "description": "a reason, to change a path a module owns anyway (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "path": {
            "description": "an absolute path",
            "type": "string"
          },
          "reason": {
            "description": "why the file is changed, for the audit trail",
            "type": "string"
          }
        },
        "required": [
          "path",
          "content",
          "reason"
        ],
        "type": "object"
      }
    },
    {
      "name": "copy",
      "description": "Copy a file or directory to a path on this node. A target on another node (\u003cnode\u003e:/path) is refused: copying between nodes comes in step 2 (issue 903). An existing target is overwritten, the old one kept in the node's trash for 7 days. Refuses a path a module owns unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
      "replaces": [
        "cp",
        "cp -a",
        "ssh \u003cnode\u003e cp"
      ],
      "input": {
        "properties": {
          "from": {
            "description": "an absolute path",
            "type": "string"
          },
          "override": {
            "description": "a reason, to change a path a module owns anyway (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "reason": {
            "description": "why the file is changed, for the audit trail",
            "type": "string"
          },
          "to": {
            "description": "an absolute path on this node",
            "type": "string"
          }
        },
        "required": [
          "from",
          "to",
          "reason"
        ],
        "type": "object"
      }
    },
    {
      "name": "move",
      "description": "Move or rename a file or directory. A target on another node is refused: copying between nodes comes in step 2 (issue 903). An existing target is overwritten, the old one kept in the node's trash for 7 days. Refuses a path a module owns unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
      "replaces": [
        "mv"
      ],
      "input": {
        "properties": {
          "from": {
            "description": "an absolute path",
            "type": "string"
          },
          "override": {
            "description": "a reason, to change a path a module owns anyway (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "reason": {
            "description": "why the file is changed, for the audit trail",
            "type": "string"
          },
          "to": {
            "description": "an absolute path",
            "type": "string"
          }
        },
        "required": [
          "from",
          "to",
          "reason"
        ],
        "type": "object"
      }
    },
    {
      "name": "delete",
      "description": "Delete a file or directory into the node's trash, where restore can bring it back. Refuses a path a module owns unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
      "replaces": [
        "rm",
        "rm -r"
      ],
      "input": {
        "properties": {
          "override": {
            "description": "a reason, to change a path a module owns anyway (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "path": {
            "description": "an absolute path",
            "type": "string"
          },
          "reason": {
            "description": "why the file is changed, for the audit trail",
            "type": "string"
          },
          "recursive": {
            "description": "\"true\": delete a directory with what it holds",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          }
        },
        "required": [
          "path",
          "reason"
        ],
        "type": "object"
      }
    },
    {
      "name": "mkdir",
      "description": "Make a directory. Refuses a path a module owns unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
      "replaces": [
        "mkdir",
        "mkdir -p"
      ],
      "input": {
        "properties": {
          "override": {
            "description": "a reason, to change a path a module owns anyway (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "parents": {
            "description": "\"true\": make the missing parents too",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "path": {
            "description": "an absolute path",
            "type": "string"
          },
          "reason": {
            "description": "why the file is changed, for the audit trail",
            "type": "string"
          }
        },
        "required": [
          "path",
          "reason"
        ],
        "type": "object"
      }
    },
    {
      "name": "chmod",
      "description": "Change the mode of a file or directory. Refuses a path a module owns unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
      "replaces": [
        "chmod"
      ],
      "input": {
        "properties": {
          "mode": {
            "description": "the mode, such as 0644 or u+x",
            "type": "string"
          },
          "override": {
            "description": "a reason, to change a path a module owns anyway (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "path": {
            "description": "an absolute path",
            "type": "string"
          },
          "reason": {
            "description": "why the file is changed, for the audit trail",
            "type": "string"
          },
          "recursive": {
            "description": "\"true\": also everything under a directory",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          }
        },
        "required": [
          "path",
          "mode",
          "reason"
        ],
        "type": "object"
      }
    },
    {
      "name": "chown",
      "description": "Change the owner and group of a file or directory. Refuses a path a module owns unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
      "replaces": [
        "chown",
        "chgrp"
      ],
      "input": {
        "properties": {
          "group": {
            "description": "a group's name or number (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "override": {
            "description": "a reason, to change a path a module owns anyway (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "owner": {
            "description": "an account's name or number",
            "type": "string"
          },
          "path": {
            "description": "an absolute path",
            "type": "string"
          },
          "reason": {
            "description": "why the file is changed, for the audit trail",
            "type": "string"
          },
          "recursive": {
            "description": "\"true\": also everything under a directory",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          }
        },
        "required": [
          "path",
          "owner",
          "reason"
        ],
        "type": "object"
      }
    },
    {
      "name": "upload",
      "description": "Send one file of this node into a bucket of the object store, over a short signed link and never over the bus; answers the key (the file's SHA-256 when none is given), the size and the SHA-256. At most 100 MiB. A place a secret is kept, a known credential file, or a link to one is refused by name, before anything is sent. Read as the node's operator account, through sudo -n where its rights do not reach; a place a secret is kept, or a known credential file, is refused by name.",
      "input": {
        "properties": {
          "bucket": {
            "description": "the bucket the file goes into",
            "type": "string"
          },
          "key": {
            "description": "the object's key (optional; the file's SHA-256 when not given)",
            "type": "string"
          },
          "path": {
            "description": "an absolute path to a file",
            "type": "string"
          }
        },
        "required": [
          "path",
          "bucket"
        ],
        "type": "object"
      }
    },
    {
      "name": "download",
      "description": "Write one object of a bucket to a file of this node, over a short signed link and never over the bus; the old file goes to the node's trash. At most 100 MiB. The bytes must hash to sha256, or to the key when the key is a SHA-256; otherwise no file is written. Refuses a path a module owns unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
      "input": {
        "properties": {
          "bucket": {
            "description": "the bucket",
            "type": "string"
          },
          "key": {
            "description": "the object's key",
            "type": "string"
          },
          "override": {
            "description": "a reason, to change a path a module owns anyway (optional)",
            "type": "string"
          },
          "path": {
            "description": "an absolute path",
            "type": "string"
          },
          "reason": {
            "description": "why the file is changed, for the audit trail",
            "type": "string"
          },
          "sha256": {
            "description": "the SHA-256 the bytes must have (optional; the key when that is a SHA-256)",
            "type": "string"
          }
        },
        "required": [
          "bucket",
          "key",
          "path",
          "reason"
        ],
        "type": "object"
      }
    },
    {
      "name": "trash",
      "description": "What the node's trash holds: each deleted or replaced item with its id, original path and when it went.",
      "replaces": [
        "ls ~/.local/share/Trash"
      ],
      "input": {
        "properties": {},
        "type": "object"
      }
    },
    {
      "name": "restore",
      "description": "Put an item of the node's trash back where it was; refuses when something is there now. Refuses a path a module owns unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
      "replaces": [
        "trash-restore"
      ],
      "input": {
        "properties": {
          "id": {
            "description": "an id from trash",
            "type": "string"
          },
          "override": {
            "description": "a reason, to change a path a module owns anyway (optional)",
            "enum": [
              "true",
              "false"
            ],
            "type": "string"
          },
          "reason": {
            "description": "why the file is changed, for the audit trail",
            "type": "string"
          }
        },
        "required": [
          "id",
          "reason"
        ],
        "type": "object"
      }
    }
  ]
}