CLI command
skarbiec request file
Record what an agent asks for, why and for whom, so a decider can answer it.
Invocation#
skarbiec request file --kind secret|device|membership --resource <resource> --action <action> --reason <text> --agent <name> [--harness <name>] [--host <name>] [--person <name>] [--decider owner|admin|<uid>] [--dual-control] [--purpose <p> --target <t> --ttl-seconds <N> --max-uses <N> [--delegation-depth <N>] | --for-consumer <name>] [--to <base-url> --consumer <name> --token-file <path>]Purpose#
Record what an agent asks for, why and for whom, so a decider can answer it.
Required inputs and options#
- --kind, --resource, --action, --reason and --agent are required. A secret request names either a bounded capability (--purpose, --target, and the asked --ttl-seconds and --max-uses, with an optional --delegation-depth) or a standing consumer grant (--for-consumer); device and membership requests take neither, since they are recorded for the product that owns them. --decider names owner, admin or one recipient's uid; --dual-control asks for two deciders. --to files the request into another host's register through POST /v1/access-requests as --consumer, whose request:<kind> grant there allows it, with the bearer read from the owner-only --token-file.
Output and state effects#
- Writes a pending record and journals it, and prints ok, status pending, request_id and dual_control; a request resolving to an item tagged dual-control needs two deciders whatever was asked. With --to it prints the other host's answer and journals access-request-sent with the host, the consumer and the request id.
Refusals#
- A flag other than those above exits 2 before the register is touched (arguments-flag-unknown). Each refusal of the filing exits before anything is recorded: a kind that is not secret, device or membership (request-kind-unknown), a value that is not one line of text without surrounding space (request-text-unfit), a count that is not a whole number of at least one (request-number-unfit), a decider that is no uid or role (request-decider-unfit), a bounded capability for an action other than read (request-capability-action), a consumer name that is not exact (request-consumer-unfit), a secret request naming neither or both grants, a device or membership request with grant flags (request-record-grant), and a resource no item declares. --to without --consumer is refused naming both, and --token in argv is refused naming --token-file.
- skarbiec.request.register request-register-not-json — exit 1: reading the access request register {path}; fix: restore {path} from a backup taken before the damage, or move it aside and file the open requests again; it is a JSON object holding a requests list
- skarbiec.request.register request-register-damaged — exit 1: reading the access request register {path}; fix: restore {path} from a backup taken before the damage, or move it aside and file the open requests again; it is a JSON object holding a requests list
- skarbiec.request.register request-record-damaged — exit 1: reading access request {id} from the register {path}; fix: remove the record {id} from {path} and file the request again; skarbiec request list shows the others
- skarbiec.request.register request-record-field-unreadable — exit 1: reading access request {id} from the register {path}; fix: remove the record {id} from {path} and file the request again; skarbiec request list shows the others
- skarbiec.request.register request-recipient-damaged — exit 1: reading {by}'s recipient record to decide access request {id}; fix: restore {by}'s recipient record from a backup taken before the damage; skarbiec recipient list shows the record and skarbiec doctor names what else is wrong
- skarbiec.request.register request-id-unavailable — exit 69: drawing a request id from /dev/urandom; fix: file the request again; if it fails again, the operating system's random source is broken and skarbiec doctor on this host says what else is
- skarbiec.request.register request-grant-unanswered — exit 1: issuing the {form} grant access request {id} names; fix: deny the request with skarbiec request deny {id} --by <uid> and issue the grant with skarbiec grant {leaf}