Holochain Forum

Capability Delegation

Problem

An agent wants to maintain control over a resource but also wants to delegate their agency to another agent.

Examples

  • Alice is a CEO. She hires a ghost writer to publish blog articles in her name.
  • Bob controls the credit limit on a community currency. He’s going on a year-long sailing trip and wants Carol to manage that credit limit in his stead.

Solution

Use capability-based security to allow an agent to delegate the power to ‘call’ the zome functions in her DNA instance. In reality she is still calling the functions, but she’s doing it on behalf of her delegate.

Implementation

Holochain already uses capability-based security to secure local access to zome functions between zomes, bridged DNAs, and the RPC interface. You can build the basis of this pattern using the HDK functions commit_capability_grant() and commit_capability_claim().

Choose the zome functions in your DNA that can be delegated to other agents. For each of these functions, create a flow that lets one agent ask another agent for permission to call the function in their DNA instance. Here’s an example using a blog article posting function:

  1. Alice wants to ghost-write for Bob, so she calls a zome function request_post_capability() that takes Bob’s agent ID.
  2. This function uses a messaging technique, like node-to-node messaging, to ask Bob for permission to post() on his behalf.
  3. Bob decides whether to grant this permission to Alice, then commits a capability grant to his source chain detailing the terms of the grant.
  4. Bob sends the hash of the capability grant back to Alice; this hash is her capability token.
  5. Alice commits a capability claim to her source chain. It contains the token and a label that reminds her that Bob granted it for ghost-writing privileges.

When Alice wants to use the capability Bob granted her, she calls a delegated_post() zome function that’s similar to the original post function but takes an argument that lets her retrieve the capability claim from her source chain. This function doesn’t perform any local operations; it just uses a messaging mechanism to pass the function parameters and the capability token to Bob.

On the remote end, Bob uses the claim token to retrieve the grant from his source chain, makes sure the grant matches what Alices is trying to do, and calls his own post() function on her behalf. He passes the return value back to Alice.

Variations

  • Partial grant: Bob might choose to place limits on his grant, like the ability to only post until a certain date or under a certain category. Some of these can be enforced at grant-checking time; others may be mixed into the zome function call using partial application.
  • Transferable vs assigned: Holochain’s capability grants let you specify whether it can be used by anyone who holds the token (transferable) or a certain set of agents by public key (assigned).
  • Chained delegation: Alice might want to let Charlie ghost-write for Bob by giving Charlie a capability grant for her delegated_post function.
  • Asynchronous: If agents aren’t guaranteed to be online at the same time, use the Mailbox pattern rather than node-to-node messaging. If necessary, protect communications using Asynchronous Private Messaging.

Warnings

  • Think hard about the possible conditions to be placed on a grant. Agents can’t revoke a capability unless you give them a way to do it.
  • You’d normally use node-to-node messaging to request/grant a token or make a claim, but this only works when both agents are online. You could use the Mailbox pattern to negotiate these flows asynchronously, but watch out for privacy leaks as the data is on the DHT.
  • Once a transferable token has been leaked, anyone can use it. Agents should keep grants and claims secret!
  • Chained delegation can get pretty hairy pretty quickly.

Related patterns

This pattern isn’t appropriate for controlling access to public data on the DHT. Use these patterns instead:

1 Like

Hi Paul,

Thanks for the great write-up and the sharing of the patterns. I really like the 'problem > solution > implementation ’ format and the names of the patterns. It really helps with understanding the framework better and learning to think ‘the Holochain’-way.

Two remarks/questions:

  • “You’d normally use node-to-node messaging to request/grant a token or make a claim, but this only works when both agents are offline” - Shouldn’t this be online?
  • “When Alice wants to use the capability Bob granted him, he calls a delegated_post() zome” - Should be her/she, right?

ha, thanks for the catch! I’ll fix those now.