feat(cid): calculate the CID for decoded and newly created Tokeners

[smoyer64]

This PR adds functions to calculate a UCAN CID for an Envelope. CIDs are calculated during creation of a new Delegation via New() or Root() and for all decoding functions provided by the envelope package. Please also review the exported API which as follows:

$ go doc -all ./delegation
package delegation // import "github.com/ucan-wg/go-ucan/delegation"

Package delegation implements the UCAN delegation specification with an
immutable Token type as well as methods to convert the Token to and from the
envelope-enclosed, signed and DAG-CBOR-encoded form that should most commonly be
used for transport and storage.

[delegation]: https://github.com/ucan-wg/delegation/tree/v1_ipld
[envelope]: https://github.com/ucan-wg/spec#envelope

CONSTANTS

const Tag = "ucan/[email protected]"
    Tag is the string used as a key within the SigPayload that identifies that
    the TokenPayload is a delegation.

[Tag]: https://github.com/ucan-wg/delegation/tree/v1_ipld#type-tag


TYPES

type Option func(*Token) error
    Option is a type that allows optional fields to be set during the creation
    of a Token.

func WithExpiration(exp time.Time) Option
    WithExpiration set's the Token's optional "expiration" field to the value of
    the provided time.Time.

func WithMeta(key string, val any) Option
    WithMeta adds a key/value pair in the "meta" field.

    WithMeta can be used multiple times in the same call. Accepted types for the
    value are: bool, string, int, int32, int64, []byte, and ipld.Node.

func WithNonce(nonce []byte) Option
    WithNonce sets the Token's nonce with the given value. If this option is not
    used, a random 12-byte nonce is generated for this required field.

func WithNotBefore(nbf time.Time) Option
    WithNotBefore set's the Token's optional "notBefore" field to the value of
    the provided time.Time.

func WithSubject(sub did.DID) Option
    WithSubject sets the Tokens's optional "subject" field to the value of
    provided did.DID.

    This Option should only be used with the New constructor - since Subject
    is a required parameter when creating a Token via the Root constructor,
    any value provided via this Option will be silently overwritten.

type Token struct {
        // Has unexported fields.
}
    Token is an immutable type that holds the fields of a UCAN delegation.

func Decode(b []byte, decFn codec.Decoder) (*Token, error)
    Decode unmarshals the input data using the format specified by the provided
    codec.Decoder into a View.

    An error is returned if the conversion fails, or if the resulting View is
    invalid.

func DecodeReader(r io.Reader, decFn codec.Decoder) (*Token, error)
    DecodeReader is the same as Decode, but accept an io.Reader.

func FromDagCbor(data []byte) (*Token, error)
    FromDagCbor unmarshals the input data into a View.

    An error is returned if the conversion fails, or if the resulting View is
    invalid.

func FromDagCborReader(r io.Reader) (*Token, error)
    FromDagCborReader is the same as FromDagCbor, but accept an io.Reader.

func FromDagJson(data []byte) (*Token, error)
    FromDagJson unmarshals the input data into a View.

    An error is returned if the conversion fails, or if the resulting View is
    invalid.

func FromDagJsonReader(r io.Reader) (*Token, error)
    FromDagJsonReader is the same as FromDagJson, but accept an io.Reader.

func FromSealed(data []byte) (*Token, error)
    FromSealed decodes the provided binary data from the DAG-CBOR format,
    verifies that the envelope's signature is correct based on the public key
    taken from the issuer (iss) field and calculates the CID of the incoming
    data.

func FromSealedReader(r io.Reader) (*Token, error)
    FromSealedReader is the same as Unseal but accepts an io.Reader.

func New(privKey crypto.PrivKey, aud did.DID, cmd command.Command, pol policy.Policy, opts ...Option) (*Token, error)
    New creates a validated Token from the provided parameters and options.

func Root(privKey crypto.PrivKey, aud did.DID, cmd command.Command, pol policy.Policy, opts ...Option) (*Token, error)

func (t *Token) Audience() did.DID
    Audience returns the did.DID representing the Token's audience.

func (t *Token) CID() cid.Cid
    CID returns the content identifier of the Token model when enclosed in an
    Envelope and encoded to DAG-CBOR. Returns cid.Undef if the token has not
    been serialized or deserialized yet.

func (t *Token) Command() command.Command
    Command returns the capability's command.Command.

func (t *Token) Encode(privKey crypto.PrivKey, encFn codec.Encoder) ([]byte, error)
    Encode marshals a View to the format specified by the provided
    codec.Encoder.

func (t *Token) EncodeWriter(w io.Writer, privKey crypto.PrivKey, encFn codec.Encoder) error
    EncodeWriter is the same as Encode but accepts an io.Writer.

func (t *Token) Expiration() *time.Time
    Expiration returns the time at which the Token expires.

func (t *Token) Issuer() did.DID
    Issuer returns the did.DID representing the Token's issuer.

func (t *Token) Meta() *meta.Meta
    Meta returns the Token's metadata.

func (t *Token) Nonce() []byte
    Nonce returns the random Nonce encapsulated in this Token.

func (t *Token) NotBefore() *time.Time
    NotBefore returns the time at which the Token becomes "active".

func (t *Token) Policy() policy.Policy
    Policy returns the capability's policy.Policy.

func (t *Token) Subject() did.DID
    Subject returns the did.DID representing the Token's subject.

    This field may be did.Undef for delegations that are [Powerlined] but must
    be equal to the value returned by the Issuer method for root tokens.

func (t *Token) ToDagCbor(privKey crypto.PrivKey) ([]byte, error)
    ToDagCbor marshals the View to the DAG-CBOR format.

func (t *Token) ToDagCborWriter(w io.Writer, privKey crypto.PrivKey) error
    ToDagCborWriter is the same as ToDagCbor but it accepts an io.Writer.

func (t *Token) ToDagJson(privKey crypto.PrivKey) ([]byte, error)
    ToDagJson marshals the View to the DAG-JSON format.

func (t *Token) ToDagJsonWriter(w io.Writer, privKey crypto.PrivKey) error
    ToDagJsonWriter is the same as ToDagJson but it accepts an io.Writer.

func (t *Token) ToSealed(privKey crypto.PrivKey) ([]byte, cid.Cid, error)
    ToSealed wraps the delegation token in an envelope, generates the signature,
    encodes the result to DAG-CBOR and calculates the CID of the resulting
    binary data.

func (t *Token) ToSealedWriter(w io.Writer, privKey crypto.PrivKey) (cid.Cid, error)
    ToSealedWriter is the same as Seal but accepts an io.Writer.