mesh-sdk/go/catalogue/reads.go

package catalogue

// ReadsSeat is the role that reads a node's files and accounts (novox/hq ADR 0310).
const ReadsSeat = "node-reads"

// ReadsSecretPlaces is the word the holder of node-reads is given: the places on its node where a secret is
// kept, as a JSON list of absolute paths, each refused by name before any read (novox/hq ADR 0310 §5).
const ReadsSecretPlaces = "MESH_SECRET_PLACES"

// readsVerbs is the contract every holder of node-reads serves (novox/hq ADR 0310 §2). The bounds are the
// build's to set and each verb's description to state (ADR 0310, Consequences); the holder states them in
// every answer it cuts.
func readsVerbs() []Verb {
	return []Verb{
		{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.",
			Input: schema(map[string]string{
				"paths":  "one absolute path, or several separated by line breaks",
				"follow": "\"true\": also say where the path leads once every link is followed",
			}, []string{"paths"}, "follow"),
			Replaces: []string{"stat", "ls -ld", "namei -l", "findmnt -T"}},
		{Name: "readlink", Description: "What one link points to, as written, and where the path leads once every " +
			"link is followed, and whether that exists.",
			Input:    schema(map[string]string{"path": "an absolute path"}, []string{"path"}),
			Replaces: []string{"readlink", "readlink -f", "realpath"}},
		{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.",
			Input:    schema(map[string]string{"path": "an absolute path to a directory"}, []string{"path"}),
			Replaces: []string{"ls", "ls -la"}},
		{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.",
			Input: schema(map[string]string{
				"path":  "an absolute path to a file",
				"from":  "the first line to answer, counted from 1 (optional)",
				"lines": "how many lines to answer (optional)",
				"bytes": "the most bytes to answer, up to 262144 (optional, 65536 unless given)",
			}, []string{"path"}),
			Replaces: []string{"cat", "head", "tail", "less"}},
		{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.",
			Input: schema(map[string]string{
				"text":    "the fixed string to find",
				"path":    "an absolute path to a file or a directory",
				"depth":   "how many directories deep, up to 8 (optional)",
				"matches": "the most matches to answer, up to 500 (optional)",
				"case":    "\"false\": match whatever the case (optional)",
			}, []string{"text", "path"}, "case"),
			Replaces: []string{"grep", "grep -r", "grep -F"}},
		{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.",
			Input: schema(map[string]string{
				"name":  "an account's name or number (optional)",
				"group": "a group's name or number (optional)",
			}, nil),
			Replaces: []string{"getent passwd", "getent group", "id", "groups"}},
	}
}