A grant is a signed blob stating that an audience holds an access level over a subject. An access level is one of four ordered words. A revocation is a signed blob that cuts a grant. There is no other kind of authority statement. Public publishing, private spaces, sharing with one person, share links, group membership, agents, devices and sites are all grants, and HM24's Capability, its visibility field and its siteUrl trust are all replaced by grants.

The model is the Keyline proposal from Ink & Switch, which the team adopted as its foundation for private document hierarchies: authority is a graph whose nodes are principals, groups and resources and whose edges are signed delegations at an access level; access composes along a path and is capped at the lowest level on the path; delegations are late-bound; revocations cut edges; admins keep their revocation power forever. Stem writes that model as two blob types and one evaluation procedure.

A Grant has four parts.

subject: what is covered. A node, by default with its whole subtree in the placement tree, or exactly that node when exact is set; or a group. A subject whose node is omitted names the space root and covers the whole space.

audience: who receives the access. One of the five audience kinds: everyone, a key, a group, a bearer secret, or the readers of another node.

access: one of sync, read, write, admin.

signer: the principal whose authority this grant spends. The signer must hold, at evaluation time, at least access over the subject. proof names the grant through which the signer holds it, as a hint for fetching; evaluation does not trust the hint.

Optional expires ends the grant at a time by the evaluating peer's clock. This is the one place a clock is consulted, and it is the evaluating peer's own clock, never a timestamp in a blob. Optional label is a public note.

The levels are totally ordered: sync < read < write < admin. A principal's level over a node is the highest level any live path in the graph gives it. The space owner, the key that is the space, holds admin over the space root permanently and without a grant: it is the origin of every path in the space.

Operations by level

A grant on a node covers the node and every node placed under it, unless exact is set. Coverage follows placement at evaluation time: a node moved under a covered node becomes covered, a node moved out stops being covered. Grants are therefore evaluated against the placement tree as it is now, never against where a node was when the grant was signed.

Readers compose the same way, as described in Privacy: a node with access mode inherit has its parent's readers plus the audiences of grants that cover it; a node with own has only the grants that cover it; a node with target has the readers of the node it targets.

A grant on a group makes the group's members. A principal is a member of group G when it holds a live grant whose subject is G at read or above. An admin on G may add and remove members by issuing and revoking such grants. A grant whose audience is {kind: group, group: G} then means "every live member of G".

A Group is a permanode: a signed blob with a random nonce whose CID is the group's id and whose signer is its owner and permanent admin. It has no members of its own; membership is grants with the group as subject. The roadmap records the decision to want a group concept, "one capability granting several keys at once", and to prefer a permanode per space whose admins are permanent with admin removal done by rotating the permanode. Stem generalises that: a space is already a group (its root node, with the space key as permanent admin), and any owner or admin may create further groups for teams, sharing circles or roles.

Groups are flat at issuance for evaluation purposes: a grant to a group is expanded to the group's live members when readers are materialised, and a group may itself be a member of another group, with nesting bounded to a depth the daemon enforces (two levels in the first implementation). This is the "flatten at issuance, cap nesting" position from the permissions investigation.

Admin rotation

A grant whose signer is not the space owner spends authority the signer received from another grant. Delegation is capped: the issued level is at most the issuer's level over the subject, and the subject is at most the issuer's subject (a node in the issuer's covered subtree, or the same group). A grant that exceeds its issuer's authority is not invalid forever; it is stashed and becomes live if the issuer's authority grows to cover it. This is late binding: a grant works while its issuer has sufficient authority, stops working when that authority disappears, and recovers when another route restores it.

The proof field tells a fetching peer which grant to ask for first so that authority arrives before the blobs that rely on it. It is not consulted during evaluation, because the graph may contain a shorter or newer path than the one the signer knew about.

A Revocation names one grant by CID. It is valid when signed by:

the grant's signer (retraction);

the key the grant was issued to, when its audience is a key (renunciation);

any principal with admin over the grant's subject (administrative revocation).

A revocation does not delete anything. The grant blob remains in the store and in history; the evaluation treats the edge as cut. A revocation cannot be undone, but a new grant can be issued. Timestamps on grants and revocations are advisory: a revocation cuts the grant whenever it arrives, and a Node blob signed under the grant is re-evaluated when the revocation lands. Blobs that lose their authority are stashed, not deleted, so a mistaken revocation loses no data; a new grant unstashes them.

What revocation means for bytes already delivered is stated in Privacy: honest peers stop serving, the disclosure ledger says who already holds them, and nothing is un-sent.

The level a principal holds over a node is computed by two passes over the space's grants and revocations, and the result does not depend on the order in which the blobs arrived.

Positive pass. Build the graph from every grant, ignoring revocations and expiry. Starting from the owner (permanent admin over the space root), walk edges forward: an edge from signer to audience at level L over subject S is traversable when the signer's level over S in this pass is at least L. Record, for every principal, its admin reach: the subjects over which it holds admin in this pass. This pass exists so that an admin's power to revoke is not itself subject to the revocations it issues.

Live pass. Remove every grant that has a valid revocation (validity judged against the admin reach from the positive pass) or has expired by the local clock. Walk the remaining graph the same way from the owner. The level a principal holds over a node is the highest level at which it is reached over any subject that covers the node (the node itself or an ancestor, respecting exact).

Readers are then materialised per node, and every blob in the node's state is mapped to the node, as Privacy describes. Evaluation reruns for the affected subtree whenever a grant, a revocation, a Node blob that changes placement or access, or a group change is indexed. Because the procedure is deterministic over the set of blobs held, two peers holding the same blobs agree, which is the property sync needs.

Example

Agents. An agent key receives write on the subtree it is meant to work in, usually with expires, and read is implied. Today's AGENT role let a key act as the issuer for the whole space with no scope and no expiry; in Stem that is write on the space root, and it is the owner's choice to grant so much. An agent cannot issue grants, which is the point: the owner stays the only source of authority. Agents are described further in Agents and notifications.

Devices. Today every blob is signed by the account key, which lives on every device. Stem keeps that as the default, and adds the option of device keys: the account key grants a device key admin over the space root, the device then signs Node, Change, Grant and Revocation blobs with its own key, and losing the device means revoking one grant instead of abandoning the account. A device grant is a grant like any other; the account key remains the permanent admin.

Sites. Today a site's authority over a space is a siteUrl string in the home document plus an HTTPS lookup, and the roadmap wants it to become a signed relationship. In Stem the space root's attributes name the site's URL and peer id, and the owner issues Grant{subject: the space root, audience: key(site peer's account), access: sync}. The site is then an authority peer for the space, may hold and serve every blob of the space including private ones, and loses that standing with one revocation. Without the grant the URL is decorative.

Authentication is proving which account a connection or request speaks for; authority is what that account may do. They are different mechanisms and must not be confused. A peer authenticates to another with the Authenticate RPC, a signature by the account key over the two peer ids and a fresh timestamp, exactly as today's ephemeral capability does, and the binding lasts for the connection. An HTTP client authenticates with a bearer token obtained the same way. Once authenticated, every read is evaluated against the account's level over the node that covers the blob, and every write is evaluated against the signer of the blob, which may be the account or a key it delegated to. A write never needs a token: its authority is in the blob.

A Node, Change or Snapshot blob whose signer does not currently hold the required level is stored and stashed with reason PermissionDenied, exactly as today's unauthorized Refs are. A grant whose signer lacks the authority it spends is stashed the same way. When any grant, revocation or group change is indexed, the affected subtree is re-evaluated and stashed blobs whose signer is now authorized are applied. This is what makes arrival order irrelevant: a writer's blobs may reach a peer before the grant that authorizes them, and the outcome is the same.

The shipping model is documented in Permissions and Capability. The direction is in Where this is going under Permissions.