ForgeFed

Projects & Grant Chains

2023-11-13 by Pere Lev

It's been 5 months since the previous blog post! Much longer than I hoped. The features I've been working on proved to be much more complex to implement, than I anticipated. With the frustration and exhaustion building up, I kept working in small chunks, and the result is finally here.

After all the many words below there's a demo as well.

Take a look at my task board for more context while reading.

Vervis and OCAPs

A bit of background just in case you missed it. I've been working in 2 channels:

One of my primary topics has been Object Capabilities (or OCAPs), which are decentralized authorization tokens. They're a core piece of how federated authorization works in ForgeFed. For more info about OCAPs, see the previous blog posts.

I'll just say this: Giving permission to access some resource is done in ForgeFed by sending a Grant activity. That activity can then be used as authorization when accessing the resource, by specifying the Grant's id URI.

Beyond Direct Grants

Until now, Vervis allowed working with projects only in the most direct way:

That sort of Grant is what I call a direct Grant. It goes straight from the resource to the person who's being given access.

This might work nicely on a very small scale, but if we want to be serious and effective about our work, we'd probably eventually face at least some of these 3 challenges:

  1. How do we meaningfully group components into projects? Much like on GitHub, GitLab, Gitea, Forgejo etc. a "repository" is actually a multi-component unit that contains code, issues, PRs, releases, kanban, wiki, CI, etc. etc.
  2. How do we create a flexible way to arrange projects according to the organizational structure of our team/company/organization, to make access management simple?
  3. How do we use OCAPs/Grants effectively to send out all the necessary authorizations, especially with the complexity of a federated situation?

Today we're visiting especially 1 and 3. A future blog post (along with the implementation of course) will touch point 2.

The Project Actor

Software development components can be collected under projects. I've implemented project creation, viewing and browsing, which is task V5 on my task list, in the following commits:

You'll see this stuff in action in the demo below.

Adding Components to Projects

So, now we can create projects. How do we add components into these projects? That part has been the bulk of my work in the last few months, because it involved the implementation of 2 complicated pieces:

  1. The latest full OCAP verification process already present in the ForgeFed specification, i.e. including support for OCAP chains (so far I've implemented only the simple direct mode)
  2. The sequence of activity handlers that implement the process of adding a component to a project

I've mentioned OCAP delegation before, but let's look at it again, perhaps with a simple example this time. Given:

When Alice wants to close one of the issues under C, what sort of token can she provide, in order to authorize the action? She doesn't have a direct Grant from C, only access to P, so how does this work?

The magic is OCAP chains. C gives P a special Grant that says: "Hi P! You can extend this Grant to whoever has access to you, so that they can access me as well." And now P can extend, or "delegate" this Grant, by sending Alice a new Grant that links to the Grant that P got from C. So we have a chain of 2 Grants:

  1. C gives a Grant to P, let's call it g
  2. P gives a Grant to Alice, let's call it h

So, when Alice wants to ask C to close one of the issues under it, she uses Grant h as the authorization token. Since h links back to g, C can follow the chain of Grants and verify they form a valid delegation of authority.

Did I succeed at making it sound much simpler than it really is? :)

Now let's look at the sequence of activities required for adding a project to a component. Here's an overview of one of the possible flows.

Given:

The process, if initiated by Bob, looks as follows:

  1. Bob sends an Invite activity, inviting C to become a component of P
  2. P approves the initial request and sends an Accept
  3. Alice, seeing the invite, sends an Accept to approve the operation on the component side
  4. C sees all of this and sends an Accept, thus the operation is now approved from both directions
  5. P sends to C a "delegate-Grant", i.e. a Grant that uses the special delegate role, authorizing C to start Grant chains with P as the target
  6. C receives the delegate-Grant and uses it as the authorization as it starts the Grant chain, sending a start-Grant to P
  7. P now extends this start-Grant as needed, by sending extension-Grants to its member people (and teams and parent projects)

I've implemented all of this, including just enough UI for a little demo, as tasks S4 and V8 on my list. The implementation clearly informed many details in the processes added to the specification (a reminder to the part of me that is tempted to trust theory alone).

The list of commits for this part is quite long, so if you're looking for the essence, the S2S and UI commits are probably the more interesting ones.

Teams and Longer Chains

The Grant chain I mentioned is very simple, just 2 Grants in it. Component sends a Grant to project, then project sends a Grant to Alice. Which might lead us to ask:

So let me clarify: The OCAP verification process can handle chains of any length, including chains that involve teams and hierarchies of teams and projects. Vervis itself doesn't yet allow to create these hierarchies (that belongs to my next tasks, so stay tuned), but the OCAP verification implementation already supports them. So you'll hopefully see them in action soon.

Same for teams themselves, even without hierarchies, they (teams) are only partially implemented, and that's why I haven't included them in the examples. They, too, are on my todo-list to implement soon as part of my next ForgeFed milestones.

Gradually, pieces of the puzzle are falling into place.

Thanks

Huge thanks to my fellow ForgeFed maintainers and developers for their continued work, including the careful review of my PRs!

Huge thanks to NLNet for funding my work on forge federation! (It's the 2nd year, and I'm considering to apply again when the time comes!)

Help Wanted

Perhaps you noticed Vervis has a quite unusable static-HTML UI. A while ago, mray and I started designing a pretty dynamic client application, and we made big progress with the design. But we stopped because I can't keep up on the development side.

Do you have passion for forge federation, and for turning software development into a community activity, where we develop and evolve our own tools, free to play, express ourselves, solve problems and address human needs, not confined to conflicting control and interests?

Do you have experience with frontend development, or willingness to learn?

Are you willing to give it a try, and if all goes well, apply for funding (with our support) to sustain your work?

Come chat with us on Matrix!

For more technical info about the tech stack etc., check out the Anvil repo.

If you aren't into frontend development, there's still plenty of other things to do: Backend development, packaging, documentation, illustration, redesigning of this website, etc. etc.

See It in Action

I recorded a little demo of all this! Watch it on my PeerTube instance.

If you want to play with things yourself, you can create account(s) on the demo instances - fig, grape, walnut - and try the things I've mentioned and done in the video:

If you encounter any bugs, let me know! Or open an issue

Comments

We have an account for ForgeFed on the Fediverse: https://floss.social/@forgefed

Right after publishing this post, I'll make a toot there to announce the post, and you can comment there :)