Part of Stem. This page defines the Grant blob, the only record that confers authority.
A Grant says: this audience holds this access level over this subject, and here is the grant through which I, the signer, hold it myself.
Fields
The schema extends blob: type, signer, sig, ts as on every signed blob.
field | type | required | meaning |
|---|---|---|---|
| literal | yes | Blob type tag. |
| yes | What the grant covers. | |
| yes | Who receives the access. | |
| yes | The level conferred, capped at the signer's own level over the subject. | |
| no | The Grant through which the signer holds authority over the subject. Omitted when the signer owns the subject's space or group. | |
| no | When the grant stops being live, by the evaluating peer's clock. Omitted means never. | |
| string, at most 512 characters | no | A public, immutable note. |
Rules
Root authority. The owner of a space is a permanent admin of its space root, and so of every node in the space; the owner of a group is its permanent admin. Grants signed by the owner need no proof. A grant whose subject names a space and omits node covers the whole space.
Creating in another owner's space. A key that holds write on a node may create nodes under it in a space it does not own, setting space on the Node blob to the owner. The owner signs nothing for that; the grant is the whole authorization.
Delegation. Any holder may issue a grant at a level not above its own effective level over the subject, on a subject that is the same node or a descendant (or the same group). The peer checks this against the evaluated graph, not against proof.
Late binding. A grant is live when its signer currently holds sufficient authority over its subject and no live Revocation names it and it has not expired. If the signer's own authority disappears, the grants it issued stop being live; if another path restores it, they come back. Peers holding the same grants and revocations compute the same result in any arrival order. The algorithm is the two-pass evaluation in Authority.
Expiry. expires is compared with the evaluating peer's own clock. Timestamps on blobs are never used to order grants against one another; only causal structure and the clock-against-expiry comparison matter.
Proof as a hint. proof tells a peer which grant to fetch before this one can be evaluated, so authority arrives first. A wrong or missing proof does not invalidate a grant whose signer does hold authority; it only slows its acceptance.
What a grant does not do. It does not encrypt. A grant constrains what honest peers serve; bytes already served stay where they are, and the disclosure ledger says where that is. The schema has no key slot yet; the sync level is reserved so that an encryption layer can arrive without redesign.
Everything is a grant
HM24 concept | Stem |
|---|---|
publishing a public document | Grant on the space root (or the node) with audience |
a private space document | no |
sharing a document with one outsider | Grant on the node with audience |
anyone-with-the-link | Grant on the node with audience |
member of a space | Grant on the space root with audience |
WRITER capability | Grant on the space root or on a node with audience |
AGENT capability | Grant on the space root with audience |
a team that can be managed at once | a Group plus grants whose audience is the group |
letting a collaborator invite others | Grant at |
a site that publishes the space | Grant on the space root with audience |
unpublishing | a Revocation of the |
Today (HM24)
A Capability is signed only by the space owner, grants WRITER or AGENT, is scoped by path prefix, cannot be re-delegated, and has no expiry or revocation; its audience field is used only on short-lived authentication tokens. Read access does not exist as a grant: a private document is readable by the owner and root writers because the code says so. Stem keeps the certificate shape and widens it to read, admin, groups, delegation, expiry and revocation.
Example
The owner shares a private document with a collaborator's key, read-only, for thirty days:
{
"type": "Grant",
"signer": {"/": {"bytes": "7QEE...Starlight"}},
"sig": {"/": {"bytes": "..."}},
"ts": 1759910400000,
"subject": {"kind": "node", "space": {"/": {"bytes": "7QEE...Starlight"}}, "node": "bafyreiv4seh2kvj72ceuvw75efr6edt4sywb5wkh7dnsipzz7fk4zri3r2"},
"audience": {"kind": "key", "key": {"/": {"bytes": "7QEE...Collaborator"}}},
"access": "read",
"expires": 1762502400000,
"label": "Draft review"
}See also
Capability and Permissions: HM24.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime