skarbiec grant capability

Invocation#

skarbiec grant capability --agent <name> --purpose <text> --resource <resource> --target <name> --ttl <seconds> --max-uses <count> [--authorization-id <id>]

Purpose#

Issue one finite, use-counted redemption of an already declared grant, against a routed resource, for the local Unix-socket broker.

Required inputs and options#

• Requires exact agent, purpose, resource, and target, plus explicit positive whole-number --ttl seconds and --max-uses. Neither lifetime nor use count has a default or a product-imposed ceiling; both must fit their unsigned storage representation. Authorization id is optional.

Output and state effects#

• Stores capability metadata in private side state and prints capability_id plus status issued. It returns no credential value; the running skarbiec serve redeems it on its capability socket. Every issue and redemption first drops each capability that can no longer be redeemed (past its expiry, or spent or cancelled) together with the nonces it was redeemed with; redemption refuses such a capability whether or not its record remains, and the audit log keeps what was issued, redeemed and cancelled.

Refusals#

• Refuses missing or malformed names, missing or non-positive TTL or use count, an invalid authorization id, and a lifetime whose addition to the current epoch cannot be represented as an expiry timestamp. No capability is stored on refusal. A non-challenge resource whose route is missing or whose credential cannot serve is refused with a document on stdout and the same sentence as an error on stderr, naming the coordinate and the repair; argument and storage failures retain their own causal errors.