Why OCapN

glowcap speaks OCapN, a protocol in which holding a reference to an object is the permission to use it.

How common protocols authorize

Services authorize requests through credentials such as cookies, API keys, and bearer tokens. A credential can grant an entire account’s access or just one operation on one resource. HTTP leaves that choice to the application.

The example below starts with a service that offers only an account-wide token. Scoped tokens could narrow that access. OCapN makes passing callable object references part of the protocol, including introductions between peers.

One job, delegated two ways

The same delegation story told twice, first with a bearer token, then with capability references. You Photos service Thumbnailer permission table your token request, carrying your token your token token, copied delete everything looked like you album album no permission table signed in once your reference account trash a reference to the album album only the album read-only your object read-only reads pass writes read-only read-only Print service introduction print they talk directly
  1. This service issues an account-wide token. Each request carries it, and the service allows whatever the account may do.
  2. You want the thumbnailer to shrink one album. Your token is the smallest thing you have to hand it, so the thumbnailer now holds everything your account can do.
  3. The thumbnailer has a bug, and it deletes your photos. Its token allowed deletion even though the job needed only reads.
  4. In the capability version, signing in returns a live reference to your album. Holding that reference lets you call the album's methods.
  5. You pass the thumbnailer a reference to that one album. That grant gives it no access to your other albums. Passing a reference like this is delegation.
  6. You would rather it could not delete anything, so you hand it a wrapper instead: an object of yours, running in your process, that forwards reads to the album and refuses the rest. The Photos service never knows the wrapper exists. Narrowing a grant this way is attenuation.
  7. When the job is done, you switch the wrapper off, and every copy of it stops working. Your own reference still works, and the Photos service is not involved. This is revocation.
  8. Later the thumbnailer needs your print service, so you send it a signed introduction. It presents the introduction to the print service, and the two talk over their own session from then on. This is a three-party handoff, and the path bypasses you.

How a reference travels

CapTP is OCapN’s protocol for calls between peers. Within a session, a reference travels as a position in a table, say slot 3. Each side records which objects it has shared with the other. Slot 3 names your album in this session, but carries no authority in another one.

A leaked bearer token can be reused at the service that accepts it, within its granted scope. A session-table position cannot be reused that way. Both still need a protected connection: CapTP alone does not encrypt traffic. Choosing a transport explains how glowcap protects a session and establishes peer identity.

a bearer token

Three unrelated holders present the same bearer token string to a service, and the service accepts every one of them. tok_9f3… you an app a stranger service

a capability reference

Two peers hold a keyed session and each keeps a private table, so only a table position crosses the pipe, and a copied position means nothing on any other pipe. you service 3: album slot 3 someone else slot 3 means nothing here
What crosses the wire is a position in a table that only the two ends of this session keep.

You get your first reference by signing in or redeeming a saved link called a sturdyref, an unguessable address that names one published object. After that, access moves by passing references inside sessions. A sturdyref is a bearer secret, and the methods of the object it names determine how much access it grants.

What OCapN is

OCapN is one message model over a choice of wire encodings and transports, so the same references travel over encrypted QUIC, a sealed TCP stream, or a browser DataChannel. Calls return promises you can keep calling through, so a chain of dependent calls crosses the network once instead of once per call. glowcap checks that it works with Spritely Goblins over CapTP 1.0, encoded in Syrup.

You can watch a three-party introduction in Rooms: choosing Message name directly gives you a direct reference to that member, and the exchange bypasses the room.

Where the idea comes from

Object references are familiar from ordinary programming. Object-capability systems make them the way code receives access: it uses the objects it can reach through references it holds, and delegates by passing those references onward.

The idea has been around since 1966, when a paper on programs sharing one machine gave it a name. Operating systems were built on it. KeyKOS ran commercial workloads from 1983, EROS and CapROS rebuilt the design, and seL4 holds the same rule under a machine-checked proof. The E language took it onto a network and produced CapTP, along with vats, containers that run their objects one call at a time, and promise pipelining.

Sandstorm runs web applications this way, giving every document its own isolated sandbox. Agoric runs financial contracts on a hardened JavaScript. Spritely Goblins brings the idea to current application languages, and OCapN is the standard that community is writing so the implementations can reach each other.

Keep going

  • Concepts explains the mechanisms one level down: locators and sturdyrefs, pipelining on the wire, the handoff stages, and how two peers agree on a wire format.
  • What about identity? covers how access, identity, and responsibility differ for people and agents.
  • The CapTP CLI ships a REPL with a guided mode: run glowcap repl, then type guide, and it walks these ideas against a live session while you type the verbs.
  • Start building runs a complete example, then shows dialing and listening on each transport, with a guide for the C ABI and every binding.
  • The capabilities glossary defines the terms.