barrel_caps (barrel_spaces v1.0.0)

View Source

Capability tokens for spaces: opaque random tokens verified against server-side grant documents in the _barrel_spaces registry, so revocation is immediate and no key material lives on disk (only a SHA-256 of the full token is stored).

Token shape: bsp_ + TokenId (16 base32 chars, names the grant doc grant:TokenId) + _ + Secret (40 base32 chars). Rights form a ladder: read < write < admin (admin covers grants, drops, branch/merge, and handoff issuance). A token is shown ONCE at grant time; treat it like a password.

Summary

Types

right/0

Functions

auth_context(Token)

Resolve a token into an authentication context: the seam the HTTP middleware and the MCP auth provider consume. Checks everything verify/3 checks except a specific space/right.

grant(SpaceId, Opts)

Issue a capability for a space. Opts: rights (default [read]), subject, label, issued_by (metadata binaries), expires_at (unix ms, 0 = never). Returns the token (shown once) and the stored grant.

list(SpaceId)

The grants of a space (hashes stripped).

revoke(TokenOrId)

Revoke a grant by full token or token id. Idempotent.

revoke_all(SpaceId)

Revoke every live grant of a space (drop_space calls this).

token_id(TokenId)

The grant-naming id inside a token (or a bare token id).

verify(Token, SpaceId, Right)

Verify a token grants Right on SpaceId. Fail closed: unknown, tampered, revoked, expired, wrong-space, and insufficient tokens all return errors that never echo token material.

Types

right/0

-type right() :: read | write | admin.

Functions

auth_context(Token)

-spec auth_context(binary()) ->
                      {ok,
                       #{space := binary(),
                         subject := binary(),
                         rights := [right()],
                         scopes := [binary()]}} |
                      {error, term()}.

Resolve a token into an authentication context: the seam the HTTP middleware and the MCP auth provider consume. Checks everything verify/3 checks except a specific space/right.

grant(SpaceId, Opts)

-spec grant(binary(), map()) -> {ok, Token :: binary(), Grant :: map()} | {error, term()}.

Issue a capability for a space. Opts: rights (default [read]), subject, label, issued_by (metadata binaries), expires_at (unix ms, 0 = never). Returns the token (shown once) and the stored grant.

list(SpaceId)

-spec list(binary()) -> {ok, [map()]}.

The grants of a space (hashes stripped).

revoke(TokenOrId)

-spec revoke(binary()) -> ok | {error, term()}.

Revoke a grant by full token or token id. Idempotent.

revoke_all(SpaceId)

-spec revoke_all(binary()) -> ok.

Revoke every live grant of a space (drop_space calls this).

token_id(TokenId)

-spec token_id(binary()) -> {ok, binary()} | error.

The grant-naming id inside a token (or a bare token id).

verify(Token, SpaceId, Right)

-spec verify(binary(), binary(), right()) ->
                {ok, map()} |
                {error, invalid_token | not_found | revoked | expired | wrong_space | forbidden}.

Verify a token grants Right on SpaceId. Fail closed: unknown, tampered, revoked, expired, wrong-space, and insufficient tokens all return errors that never echo token material.