custodian grant
Give a principal exactly the access it needs, one field at a time, and understand why a grant is refused.
A grant gives one principal access to one action on one field of one collection. Nothing is inherited and nothing is implied, so what a principal can see is answered by reading its grants. Be signed in with an operator token.
custodian grant create
Name the principal, the collection, and what the principal should be able to see:
custodian grant create liberty-agent --collection policies --token holder_tax_id --plain policy_numberEach flag names what the principal gets to see; the grant action it creates is:
| Flag | Grants | For |
|---|---|---|
--plain <fields> | read the plaintext | fields whose sensitivity is plain |
--plaintext <fields> | read the plaintext | a sensitive field — the one that needs care |
--masked <fields> | read the masked form | the named fields |
--token <fields> | read the token | the named fields |
--plain-all / --plaintext-all | read the plaintext across the whole collection | (asks first) |
--write | write across the collection | — does not permit reading |
--plain and --plaintext create the same action; the two names exist so the command
reads right where the fields are harmless and where they are not. A field list may be
comma- or space-separated, and each flag is repeatable.
--expires <duration> sets an expiry on every grant made, as 30d, 12h, 90m,
3600s or 2w.
Two rules to keep in mind
-
A write grant does not permit reading. A write-only principal cannot read the record back.
-
A grant on a collection covers none of its children. Each child collection needs its own grant. After a collection-wide grant on a parent, Custodian names the children it does not cover:
Note: this collection-wide grant on "policies" covers none of its child collections (claims). A grant on a collection does not reach its children — each needs its own grant.
Wildcards ask first
--plain-all and --plaintext-all grant plaintext across every field of the
collection. Because a wildcard is where silent over-permission comes from, Custodian
lists the fields it would cover and asks before sending:
read_plaintext across every field of "policies" is a wildcard grant. It would cover 4 fields: policy_number, premium, holder_tax_id, start_date.
Grant read_plaintext across all fields of "policies"? [y/N]Add the global --yes to answer it without a prompt.
When a grant is refused
The server refuses a dangerous grant — for example one that would let an agent read plaintext, an expiry already in the past, or a duplicate of a grant that already exists. When it does, Custodian prints the server's own explanation word for word, adds nothing of its own, creates no grant, and exits non-zero.
custodian grant list
Every grant, its identifier first, with the principal, collection, field (or all fields), action, expiry and state:
custodian grant list --principal liberty-agentGRANT PRINCIPAL COLLECTION FIELD ACTION EXPIRES STATE
grt_5Kd2… liberty-agent policies holder_tax_id read_token never live
grt_9Xa1… liberty-agent policies policy_number read_plaintext never liveLive grants show by default. --include-revoked and --include-expired widen the
list, each row stating its state. Filter with --principal, --collection and
--field.
custodian grant revoke
Removes one grant by the identifier grant list prints first:
custodian grant revoke grt_5Kd2…Every one of these commands accepts --json.