github.com/storacha/go-ucanto@v0.7.2/ucan/ucan.go (about)

     1  package ucan
     2  
     3  import (
     4  	"encoding/json"
     5  
     6  	"github.com/ipld/go-ipld-prime"
     7  	"github.com/storacha/go-ucanto/did"
     8  	"github.com/storacha/go-ucanto/ucan/crypto"
     9  	"github.com/storacha/go-ucanto/ucan/crypto/signature"
    10  )
    11  
    12  // Resorce is a string that represents resource a UCAN holder can act upon.
    13  // It MUST have format `${string}:${string}`
    14  type Resource = string
    15  
    16  // Ability is a string that represents some action that a UCAN holder can do.
    17  // It MUST have format `${string}/${string}` | "*"
    18  type Ability = string
    19  
    20  // UnknownCapability is a capability whose Nb type is unknown
    21  type UnknownCapability interface {
    22  	json.Marshaler
    23  	Can() Ability
    24  	With() Resource
    25  }
    26  
    27  // Capability represents an ability that a UCAN holder can perform with some
    28  // resource.
    29  type Capability[Caveats any] interface {
    30  	UnknownCapability
    31  	Nb() Caveats
    32  }
    33  
    34  // Principal is a DID object representation with a `did` accessor for the DID.
    35  type Principal interface {
    36  	DID() did.DID
    37  }
    38  
    39  // Link is an IPLD link to UCAN data.
    40  type Link = ipld.Link
    41  
    42  // Version of the UCAN spec used to produce a specific UCAN.
    43  // It MUST have format `${number}.${number}.${number}`
    44  type Version = string
    45  
    46  // UTCUnixTimestamp is a timestamp in seconds since the Unix epoch.
    47  type UTCUnixTimestamp = int
    48  
    49  // https://github.com/ucan-wg/spec/#324-nonce
    50  type Nonce = string
    51  
    52  // A map of arbitrary facts and proofs of knowledge. The enclosed data MUST
    53  // be self-evident and externally verifiable. It MAY include information such
    54  // as hash preimages, server challenges, a Merkle proof, dictionary data, etc.
    55  // See https://github.com/ucan-wg/spec/#325-facts
    56  type Fact = map[string]any
    57  
    58  // Signer is an entity that can sign UCANs with keys from a `Principal`.
    59  type Signer interface {
    60  	Principal
    61  	crypto.Signer
    62  
    63  	// SignatureCode is an integer corresponding to the byteprefix of the
    64  	// signature algorithm. It is used to tag the [signature] so it can self
    65  	// describe what algorithm was used.
    66  	//
    67  	// [signature]: https://github.com/ucan-wg/ucan-ipld/#25-signature
    68  	SignatureCode() uint64
    69  
    70  	// SignatureAlgorithm is the name of the signature algorithm. It is a human
    71  	// readable equivalent of the `SignatureCode`, however it is also used as the
    72  	// last segment in [Nonstandard Signatures], which is used as an `alg` field
    73  	// of the JWT header.
    74  	//
    75  	// [Nonstandard Signatures]: https://github.com/ucan-wg/ucan-ipld/#251-nonstandard-signatures
    76  	SignatureAlgorithm() string
    77  }
    78  
    79  // Verifier is an entity that can verify UCAN signatures against a `Principal`.
    80  type Verifier interface {
    81  	Principal
    82  	signature.Verifier
    83  }