esdb_capability_verifier (reckon_db v1.6.0)

View Source

Server-side capability token verification for reckon-db.

Verifies UCAN-inspired capability tokens for authorization decisions. Tokens are created client-side (reckon-gater) and verified server-side here.

Verification steps:

  1. Decode token (JWT or binary format, auto-detected)
  2. Verify Ed25519 signature using issuer's public key from DID
  3. Check token is not expired (exp less than now)
  4. Check token is active (nbf less than or equal to now, if present)
  5. Check token is not revoked (via gossip list)
  6. Match resource URI against request
  7. Match action against permitted actions

See also: esdb_capability, esdb_identity.

Summary

Types

capability/0
capability_error/0
capability_grant/0
verification_result/0
verify_opts/0

Functions

authorize(Token, Resource, Action)

Authorize a request with a capability token

authorize(Token, Resource, Action, Opts)

Authorize a request with options

check_permission(Capability, Resource, Action)

Check if a verified capability grants permission for resource/action

extract_token_cid(Capability)

Extract a content-addressed identifier for a token

is_revoked(TokenCID)

Check if a token CID is revoked

verify(Token)

Verify a capability token

verify(Token, Opts)

Verify a capability token with options

Types

capability/0

-type capability() ::
          #capability{alg :: binary(),
                      typ :: binary(),
                      iss :: binary(),
                      aud :: binary(),
                      nbf :: integer() | undefined,
                      exp :: integer(),
                      iat :: integer(),
                      nnc :: binary(),
                      att :: [capability_grant()],
                      fct :: map(),
                      prf :: [binary()],
                      sig :: binary() | undefined}.

capability_error/0

-type capability_error() ::
          {invalid_signature, binary()} |
          {expired, integer()} |
          {not_yet_valid, integer()} |
          {revoked, binary()} |
          {invalid_delegation, binary()} |
          {insufficient_permissions, binary()} |
          {invalid_resource, binary()} |
          {invalid_action, binary()} |
          {parse_error, term()}.

capability_grant/0

-type capability_grant() :: #{with := binary(), can := binary()}.

verification_result/0

-type verification_result() ::
          #verification_result{capability :: capability(),
                               issuer_chain :: [binary()],
                               resource :: binary(),
                               action :: binary(),
                               verified_at :: integer()}.

verify_opts/0

-type verify_opts() :: #{skip_signature => boolean(), skip_revocation => boolean(), now => integer()}.

Functions

authorize(Token, Resource, Action)

-spec authorize(binary(), binary(), binary()) ->
                   {ok, verification_result()} | {error, capability_error()}.

Authorize a request with a capability token

Verifies the token AND checks it grants permission for the specified resource and action.

authorize(Token, Resource, Action, Opts)

-spec authorize(binary(), binary(), binary(), verify_opts()) ->
                   {ok, verification_result()} | {error, capability_error()}.

Authorize a request with options

check_permission(Capability, Resource, Action)

-spec check_permission(capability(), binary(), binary()) -> ok | {error, capability_error()}.

Check if a verified capability grants permission for resource/action

The capability should already be verified (signature, expiration). This function only checks the grants against the requested resource/action.

extract_token_cid(Capability)

-spec extract_token_cid(capability()) -> binary().

Extract a content-addressed identifier for a token

Uses SHA-256 hash of the token's core fields (excluding signature). This CID can be used for revocation.

is_revoked(TokenCID)

-spec is_revoked(binary()) -> boolean().

Check if a token CID is revoked

Currently returns false (not revoked) as revocation gossip is not yet implemented. This will be integrated with a gossip-based revocation list in Phase 4.

verify(Token)

-spec verify(binary()) -> {ok, capability()} | {error, capability_error()}.

Verify a capability token

Decodes the token and verifies: - Signature is valid (Ed25519) - Token is not expired - Token is not revoked

Does NOT check permissions against a specific resource/action. Use authorize/3 for full authorization.

verify(Token, Opts)

-spec verify(binary(), verify_opts()) -> {ok, capability()} | {error, capability_error()}.

Verify a capability token with options