Policy Spec Guide
What a policy's actions, resources and principals are, how roles and a
resource's [access] use one, and where its boundaries are. Each field
is in the Policy Spec reference.
# ci.toml
schema = 1
name = "ci"
version = 1
# A grant: every action it names, on every resource it names.
[[allow]]
actions = ["cloud.read", "cloud.use"]
on = ["cloud:aws", "cloud:ci-*"]
[[allow]]
actions = ["box.*"]
on = ["box:ci-*"]
# How much: each left out is no limit but the service's own.
[limits]
boxes = 2 # boxes at once
cpus = 4 # CPUs a box
memory_gb = 8 # memory a box, in GB
disk_gb = 40 # disk a box, in GB
hours = 12 # how long a box livesA policy holds at most 64 grants. A key it doesn't have is refused by its name, as an empty table is.
Actions
An action is <kind>.<verb>, from one list: a verb the list doesn't
hold can't be granted or checked. Three verbs a kind: what's read,
what's used, what changes it.
Agent actions
agent.read reads an agent's status and logs, agent.message messages
it (a teammate's message, a post to its webhook), and agent.admin
starts, stops, moves it or changes its spec.
Team actions
team.read reads a team, team.member is on it (its chats, its
folder, its spec), and team.admin changes who's on it and what each
reaches.
Bucket actions
bucket.read reads and lists a bucket or a path of it, bucket.write
writes there, and bucket.share shares it. A path is the resource's id
after the bucket's, bucket:team-r7/drafts/, and a pattern reaches what
it begins, bucket:team-r7/drafts/*.
Cloud actions
cloud.read reads a cloud's boxes and limits. cloud.use has boxes
made on it within those limits, and cloud.admin accepts it and changes
who may use it.
Box actions
box.read reads a box, box.ssh reaches it over SSH, and box.admin
makes, deletes or resizes it. These verbs apply to box resources rather
than cloud resources.
Grant patterns
A grant's actions takes an action, <kind>.* (every verb of a
kind), or * (every action, the owner's). Its actions and its
resources are of one kind: box.ssh on cloud:aws is refused.
Resources
A resource is named by its id, <kind>:<id>; another account's is
<account>/<kind>:<id>, as in acct-7f3a/cloud:mac. A name without an
account is the principal's own account's.
Resource patterns
A grant's on takes a name or a pattern. A * ends a pattern or is
one; nothing else is a pattern, so a grant reads as what it reaches.
One resource
cloud:aws reaches that cloud alone. cloud:ci-* reaches every cloud
whose id begins ci-, within the principal's account unless an account
is named explicitly.
Clouds of one or every account
cloud:* reaches every cloud of the principal's account. */cloud:*
reaches clouds of any account where the resource's [access] lets the
principal in.
Every resource of the account
* reaches everything of the principal's account. Cross-account access
still needs an account-qualified pattern and the resource's own
[access] permission.
Principals
Each principal has a permanent id, <kind>:<id>, its id after its kind
of the characters A-Z a-z 0-9 . _ : / -, at most 128, and its kind
one of two.
Users
user: identifies a person: you, signed in, or someone a connection
vouches for. A machine is never a principal: its signer signs for its
user, so what a machine does, its user does.
Services
service: identifies a program acting on its own. An agent acts as a
service for its lifetime. A caller that creates a temporary service principal
supplies its expiry when constructing the checked principal.
Ends
A principal may end: the service that holds it says when, and a check after then is refused.
Roles
A role is a Policy Spec given to principals. Roles keeps its grants and
holders together, and the service loads those grants into a principal
snapshot before authorizing an operation. Updating the role changes newly
constructed snapshots rather than mutating existing ones.
Role Names and Patterns
A role's name uses lowercase letters, digits, and -, beginning with a
letter and at most 64 characters long. Renaming creates a new role. Patterns
on agents, teams, or buckets end a segment with *, alone or after /,
such as bucket:team-r7/*. The decision identifies the matching role and
grant, so a caller can explain why access was allowed.
A resource's [access]
The resource keeper supplies Access when constructing a checked Resource.
Its TOML representation maps a verb of the resource's kind to a list: * (anyone), an account (acct-<id>, every principal of it) or
a principal. A cloud's [access] with use = ["acct-7f3a"] lets every
principal of that account have boxes made on it, when their own
policy allows it too. Inside the account, the principal's policy alone
decides, and [access] isn't read.
Caller Responsibilities
allows checks the supplied principal, action, resource, and time without
reading a store or reaching a service. Authenticate the principal and obtain
current resource ownership and access rules before constructing those inputs.
Refresh Role Snapshots
Roles::of returns policy copies, and Principal::with_roles keeps those
copies in the principal. A role update does not mutate existing principals.
Reconstruct the snapshot from current roles when an operation must observe
revocation or changed grants.
Enforce Limits Separately
The authorization decision does not meter [limits]. The resource keeper
supplies projected Usage to Limits::admits and enforces the result while
serializing resource allocation, so simultaneous requests cannot bypass a
quota by each observing the same earlier usage.
Whole-Pattern Grants
allows_all checks whether a grant covers the whole requested pattern within
the principal's account. allows_all_with_access can check one explicitly
named other account using access obtained from that resource's keeper.
Neither accepts an unrestricted any-account pattern as proof of access.
Policy boundaries
A policy states grants and limits. Its principal and the service that holds it determine when it ends and who receives it; the policy keeps no separate deny or conditional rule system.
- No deny rules. What isn't granted is refused; a narrower principal is made rather than a wider one denied.
- No conditions on a grant. No address, time or hours: an end is
the principal's, and how much is
[limits]. - Not who it's given to. The service that holds the principal holds which policy it has.
The cases every check is held to are in tests/specs/policy/
of this workspace, each a policy and the answers it gives.