ucan

Documentation

Index

• func IsExpired(ucan UCANView) bool
• func IsTooEarly(ucan UCANView) bool
• func Now() uint64
• type Ability
• type Capability
  • func NewCapability[Caveats any](can Ability, with Resource, nb Caveats) Capability[Caveats]
• type CaveatBuilder
• type Fact
• type FactBuilder
• type Link
• type MapBuilder
• type Nonce
• type Option
  • func WithExpiration(exp uint64) Option
  • func WithFacts(fct []FactBuilder) Option
  • func WithNonce(nnc string) Option
  • func WithNotBefore(nbf uint64) Option
  • func WithProofs(prf []Link) Option
• type Principal
• type Resource
• type Signer
• type UCANView
  • func Issue(issuer Signer, audience Principal, capabilities []Capability[CaveatBuilder], ...) (UCANView, error)
  • func NewUCANView(model *udm.UCANModel) (UCANView, error)
• type UTCUnixTimestamp
• type Verifier
• type Version

Functions

func IsExpired

func IsExpired(ucan UCANView) bool

IsExpired checks if a UCAN is expired.

func IsTooEarly

func IsTooEarly(ucan UCANView) bool

IsTooEarly checks if a UCAN is not active yet.

func Now

func Now() uint64

Now returns a UTC Unix timestamp for comparing it against time window of the UCAN.

Types

type Ability

type Ability = string

Ability is a string that represents some action that a UCAN holder can do. It MUST have format `${string}/${string}` | "*"

type Capability

type Capability[Caveats any] interface {
	Can() Ability
	With() Resource
	Nb() Caveats
}

Capability represents an ability that a UCAN holder can perform with some resource.

func NewCapability

func NewCapability[Caveats any](can Ability, with Resource, nb Caveats) Capability[Caveats]

type CaveatBuilder

type CaveatBuilder = MapBuilder

type Fact

type Fact = map[string]any

A map of arbitrary facts and proofs of knowledge. The enclosed data MUST be self-evident and externally verifiable. It MAY include information such as hash preimages, server challenges, a Merkle proof, dictionary data, etc. See https://github.com/ucan-wg/spec/#325-facts

type FactBuilder

type FactBuilder = MapBuilder

type Link

type Link = ipld.Link

Link is an IPLD link to UCAN data.

type MapBuilder

type MapBuilder interface {
	Build() (map[string]datamodel.Node, error)
}

MapBuilder builds a map of string => datamodel.Node from the underlying data.

type Nonce

type Nonce = string

https://github.com/ucan-wg/spec/#324-nonce

type Option

type Option func(cfg *ucanConfig) error

Option is an option configuring a UCAN.

func WithExpiration

func WithExpiration(exp uint64) Option

WithExpiration configures the expiration time in UTC seconds since Unix epoch.

func WithFacts

func WithFacts(fct []FactBuilder) Option

WithFacts configures the facts for the UCAN.

func WithNonce

func WithNonce(nnc string) Option

WithNonce configures the nonce value for the UCAN.

func WithNotBefore

func WithNotBefore(nbf uint64) Option

WithNotBefore configures the time in UTC seconds since Unix epoch when the UCAN will become valid.

func WithProofs

func WithProofs(prf []Link) Option

WithProofs configures the proofs for the UCAN.

type Principal

type Principal interface {
	DID() did.DID
}

Principal is a DID object representation with a `did` accessor for the DID.

type Resource

type Resource = string

Resorce is a string that represents resource a UCAN holder can act upon. It MUST have format `${string}:${string}`

type Signer

type Signer interface {
	Principal
	crypto.Signer

	// SignatureCode is an integer corresponding to the byteprefix of the
	// signature algorithm. It is used to tag the [signature] so it can self
	// describe what algorithm was used.
	//
	// [signature]: https://github.com/ucan-wg/ucan-ipld/#25-signature
	SignatureCode() uint64

	// SignatureAlgorithm is the name of the signature algorithm. It is a human
	// readable equivalent of the `SignatureCode`, however it is also used as the
	// last segment in [Nonstandard Signatures], which is used as an `alg` field
	// of the JWT header.
	//
	// [Nonstandard Signatures]: https://github.com/ucan-wg/ucan-ipld/#251-nonstandard-signatures
	SignatureAlgorithm() string
}

Signer is an entity that can sign UCANs with keys from a `Principal`.

type UCANView

type UCANView interface {
	// Model references the underlying IPLD datamodel instance.
	Model() *udm.UCANModel
	// Issuer is the signer of the UCAN.
	Issuer() Principal
	// Audience is the principal delegated to.
	Audience() Principal
	// Version is the spec version the UCAN conforms to.
	Version() Version
	// Capabilities are claimed abilities that can be performed on a resource.
	Capabilities() []Capability[any]
	// Expiration is the time in seconds since the Unix epoch that the UCAN
	// becomes invalid.
	Expiration() UTCUnixTimestamp
	// NotBefore is the time in seconds since the Unix epoch that the UCAN
	// becomes valid.
	NotBefore() UTCUnixTimestamp
	// Nonce is a randomly generated string to provide a unique
	Nonce() Nonce
	// Facts are arbitrary facts and proofs of knowledge.
	Facts() []Fact
	// Proofs of delegation.
	Proofs() []Link
	// Signature of the UCAN issuer.
	Signature() signature.SignatureView
}

UCANView represents a decoded "view" of a UCAN that can be used in your domain logic, etc.

func Issue

func Issue(issuer Signer, audience Principal, capabilities []Capability[CaveatBuilder], options ...Option) (UCANView, error)

Issue creates a new signed token with a given issuer. If expiration is not set it defaults to 30 seconds from now.

func NewUCANView

func NewUCANView(model *udm.UCANModel) (UCANView, error)

NewUCANView creates a UCAN view from the underlying data model. Please note that this function does no verification of the model and it is callers responsibility to ensure that:

1. Data model is correct contains all the field etc.
2. Payload of the signature will match paylodad when model is serialized with DAG-JSON.

In other words you should never use this function unless you've parsed or decoded a valid UCAN and want to wrap it into a view.

type UTCUnixTimestamp

type UTCUnixTimestamp = uint64

UTCUnixTimestamp is a timestamp in seconds since the Unix epoch.

type Verifier

type Verifier interface {
	Principal
	signature.Verifier
}

Verifier is an entity that can verify UCAN signatures against a `Principal`.

type Version

type Version = string

Version of the UCAN spec used to produce a specific UCAN. It MUST have format `${number}.${number}.${number}`