ucan

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 2, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

pkg/ucan/capabilities.go

Package ucan provides UCAN delegation validation utilities.

internal/ucan/issuer.go

Index

Constants

View Source 
const (
	ErrCodeDelegationExpired           = "DELEGATION_EXPIRED"
	ErrCodeDelegationWrongAudience     = "DELEGATION_WRONG_AUDIENCE"
	ErrCodeDelegationMissingCapability = "DELEGATION_MISSING_CAPABILITY"
	ErrCodeDelegationWrongResource     = "DELEGATION_WRONG_RESOURCE"
	ErrCodeDelegationInvalidSignature  = "DELEGATION_INVALID_SIGNATURE"
	ErrCodeDelegationParseError        = "DELEGATION_PARSE_ERROR"
	ErrCodeRevocationNotAuthorized     = "REVOCATION_NOT_AUTHORIZED"
	ErrCodeDelegationNotFound          = "DELEGATION_NOT_FOUND"
	ErrCodeDelegationFetchError        = "DELEGATION_FETCH_ERROR"
	ErrCodeInvocationNotAuthorized     = "INVOCATION_NOT_AUTHORIZED"
	ErrCodeDelegationNoAuthority       = "DELEGATION_NO_AUTHORITY"
)

Error codes for delegation validation

Variables

This section is empty.

Functions

func CapabilityAllows 

func CapabilityAllows(held, required, resource string) bool

CapabilityAllows checks if a held capability grants the required capability.

func DIDToPublicKey 

func DIDToPublicKey(did string) (ed25519.PublicKey, error)

DIDToPublicKey extracts the public key from a DID.

func ExtractSpaceDID 

func ExtractSpaceDID(dlg delegation.Delegation) (string, error)

ExtractSpaceDID extracts the space DID from a delegation's capabilities. All capabilities must have the same resource (the space DID).

func FetchDelegation 

func FetchDelegation(ctx context.Context, fetcher BlobFetcher, cid string) (delegation.Delegation, error)

FetchDelegation fetches a delegation from storage by CID and parses it. The delegation must be stored as a CAR file in the space.

func FormatDelegation 

func FormatDelegation(dlg delegation.Delegation) (string, error)

FormatDelegation encodes a delegation to base64 string.

func ParseDelegation 

func ParseDelegation(encoded string) (delegation.Delegation, error)

ParseDelegation parses a base64-encoded UCAN delegation.

func ParseDelegationFromCAR 

func ParseDelegationFromCAR(data []byte) (delegation.Delegation, error)

ParseDelegationFromCAR parses a delegation from CAR-encoded bytes.

func ParseResourceGroup 

func ParseResourceGroup(resource string) (types.GroupID, error)

ParseResourceGroup extracts the group ID from a resource URI.

func RequiredCapability 

func RequiredCapability(operation string) string

RequiredCapability returns the required capability for an operation.

func RequiredStorachaCapabilities 

func RequiredStorachaCapabilities() []string

RequiredStorachaCapabilities returns the capabilities needed for log operations on a customer's Storacha space.

func ValidateDelegation 

func ValidateDelegation(dlg delegation.Delegation, serviceDID string, spaceDID string) error

ValidateDelegation checks that a delegation grants required capabilities for the service to write to the customer's space.

func ValidateDelegationForAppend 

func ValidateDelegationForAppend(delegationStr string, serviceDID string, spaceDID string) (delegation.Delegation, error)

ValidateDelegationForAppend validates an optional new delegation for append. If delegationStr is empty, returns nil (use existing delegation). If provided, validates the new delegation.

func ValidateDelegationForCreate 

func ValidateDelegationForCreate(delegationStr string, serviceDID string, spaceDID string) (delegation.Delegation, error)

ValidateDelegationForCreate validates a delegation for log creation. This is the entry point for create handler.

func ValidateInvocationAuthority 

func ValidateInvocationAuthority(invocationIssuerDID string, dlg delegation.Delegation) error

ValidateInvocationAuthority checks if the invocation issuer has authority to use the provided delegation.

The invocation issuer must be the delegation issuer. This ensures that only the principal who created the delegation can use it to invoke operations.

This supports delegation chains: - Alice (space owner) delegates to FriendB - FriendB creates a new delegation to the service (with Alice's as proof) - FriendB signs the invocation - inv.Issuer (FriendB) == dlg.Issuer (FriendB) ✓

This prevents delegation theft: - Eve finds FriendB's delegation - Eve signs an invocation - inv.Issuer (Eve) != dlg.Issuer (FriendB) ✗

func ValidateProofChain 

func ValidateProofChain(dlg delegation.Delegation, spaceDID string) error

ValidateProofChain validates that the delegation issuer has authority over the space. This ensures the delegation traces back to the space owner through a valid proof chain.

Valid scenarios: 1. Direct: Space owner delegates directly to service (issuer == spaceDID) 2. Chain: Space owner → Agent → Service (proof chain traces to spaceDID) 3. Sub-delegation: Space owner → Agent → FriendB → Service (proof chain traces to spaceDID)

Invalid scenario: - Eve creates delegation for Alice's space with no proofs (issuer != spaceDID, no proof chain)

func ValidateRevocationAuthority 

func ValidateRevocationAuthority(revokerDID string, dlgToRevoke delegation.Delegation) error

ValidateRevocationAuthority checks if revokerDID has authority to revoke the delegation. A principal can revoke a delegation if: 1. They are the issuer of the delegation, OR 2. They are upstream in the proof chain (issued a proof that the delegation depends on)

Types

type BlobFetcher 

type BlobFetcher interface {
	FetchBlob(ctx context.Context, cid string) ([]byte, error)
}

BlobFetcher is an interface for fetching blobs by CID. This is used to fetch delegations from storage for revocation.

type CapabilityInfo 

type CapabilityInfo struct {
	With string
	Can  string
}

CapabilityInfo represents a validated capability

func ExtractDelegationCapabilities 

func ExtractDelegationCapabilities(dlg delegation.Delegation) []CapabilityInfo

ExtractDelegationCapabilities extracts capabilities from a delegation for debugging.

type DelegationError 

type DelegationError struct {
	Code    string
	Message string
}

DelegationError represents an error with delegation validation.

func NewDelegationError 

func NewDelegationError(code, message string) *DelegationError

NewDelegationError creates a new delegation error.

func (*DelegationError) Error 

func (e *DelegationError) Error() string

type DelegationInfo 

type DelegationInfo struct {
	Issuer       string           `json:"issuer"`
	Audience     string           `json:"audience"`
	Capabilities []CapabilityInfo `json:"capabilities"`
	Expiration   *time.Time       `json:"expiration,omitempty"`
}

DelegationInfo contains information about a delegation for logging/debugging.

func GetDelegationInfo 

func GetDelegationInfo(dlg delegation.Delegation) DelegationInfo

GetDelegationInfo extracts information from a delegation for logging.

type GoUCANIssuer 

type GoUCANIssuer struct {
	// contains filtered or unexported fields
}

GoUCANIssuer creates and signs UCANs using go-ucanto.

func NewGoUCANIssuer 

func NewGoUCANIssuer(privateKey ed25519.PrivateKey) (*GoUCANIssuer, error)

NewGoUCANIssuer creates a new UCAN issuer using go-ucanto.

func (*GoUCANIssuer) DID 

func (i *GoUCANIssuer) DID() string

DID returns the issuer's DID.

func (*GoUCANIssuer) IssueDelegatedUCAN 

func (i *GoUCANIssuer) IssueDelegatedUCAN(
	ctx context.Context,
	audienceDID string,
	capabilities []CapabilityInfo,
	parentProofs []delegation.Delegation,
	ttl time.Duration,
) (delegation.Delegation, error)

IssueDelegatedUCAN creates a delegated UCAN with specific capabilities using go-ucanto.

func (*GoUCANIssuer) IssueRootUCAN 

func (i *GoUCANIssuer) IssueRootUCAN(
	ctx context.Context,
	audienceDID string,
	groupID types.GroupID,
	ttl time.Duration,
) (delegation.Delegation, error)

IssueRootUCAN creates a root UCAN granting full control to an audience using go-ucanto.

type Issuer 

type Issuer struct {
	// contains filtered or unexported fields
}

Issuer creates and signs UCANs.

func NewIssuer 

func NewIssuer(privateKey ed25519.PrivateKey, publicKey ed25519.PublicKey) *Issuer

NewIssuer creates a new UCAN issuer.

func (*Issuer) DID 

func (i *Issuer) DID() string

DID returns the issuer's DID.

func (*Issuer) IssueDelegatedUCAN 

func (i *Issuer) IssueDelegatedUCAN(
	audience ed25519.PublicKey,
	capabilities []CapabilityInfo,
	proofs []delegation.Delegation,
	ttl time.Duration,
) (delegation.Delegation, error)

IssueDelegatedUCAN creates a delegated UCAN with specific capabilities.

func (*Issuer) IssueRootUCAN deprecated 

func (i *Issuer) IssueRootUCAN(
	audience ed25519.PublicKey,
	groupID types.GroupID,
	ttl time.Duration,
) (delegation.Delegation, error)

Deprecated: IssueRootUCAN is no longer used in the simplified delegation model. Authorization is now handled via Storacha space delegations. This method is kept for backward compatibility with tests.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.