mesh-contracts/seats/node-reads/seat.json

{
  "format": 1,
  "seat": "node-reads",
  "scope": "node",
  "grain": "seat-list",
  "decision": "novox/hq ADR 0310",
  "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\". Read as the holder's own account, which holds no secret: a component it may not reach says so. At most 200 paths in one call.",
      "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.",
      "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.",
      "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.",
      "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.",
      "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.",
      "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"
      }
    }
  ]
}