validator

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2024 License: Apache-2.0, MIT Imports: 22 Imported by: 10

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Access 

func Access[Caveats any](invocation invocation.Invocation, context ValidationContext[Caveats]) (Authorization[Caveats], Unauthorized)

Access finds a valid path in a proof chain of the given invocation.Invocation by exploring every possible option. On success an Authorization object is returned that illustrates the valid path. If no valid path is found Unauthorized error is returned detailing all explored paths and where they proved to fail.

func Authorize 

func Authorize[Caveats any](match Match[Caveats], context ClaimContext) (Authorization[Caveats], InvalidClaim)

Authorize verifies whether any of the delegated proofs grant capability.

func Claim 

func Claim[Caveats any](capability CapabilityParser[Caveats], proofs []delegation.Proof, context ClaimContext) (Authorization[Caveats], Unauthorized)

Claim attempts to find a valid proof chain for the claimed CapabilityParser given set of `proofs`. On success an Authorization object with detailed proof chain is returned and on failure Unauthorized error is returned with details on paths explored and why they have failed.

func DefaultDerives 

func DefaultDerives[Caveats any](claimed, delegated ucan.Capability[Caveats]) failure.Failure

func IsSelfIssued 

func IsSelfIssued[Caveats any](capability ucan.Capability[Caveats], issuer did.DID) bool

func NewPrincipalAlignmentError 

func NewPrincipalAlignmentError(audience ucan.Principal, delegation delegation.Delegation) failure.Failure

func ResolveAbility 

func ResolveAbility(pattern string, can ucan.Ability) ucan.Ability

ResolveAbility resolves ability `pattern` of the delegated capability from the ability of the claimed capability. If pattern matches returns claimed ability otherwise returns "".

  • pattern "*" can "store/add" → "store/add"
  • pattern "store/*" can "store/add" → "store/add"
  • pattern "*" can "store/add" → "store/add"
  • pattern "*" can "store/add" → ""
  • pattern "*" can "store/add" → ""
  • pattern "*" can "store/add" → ""

func ResolveMatch 

func ResolveMatch[Caveats any](match Match[Caveats], context ClaimContext) (sources []Source, errors []ProofError)

func ResolveResource 

func ResolveResource(source string, uri ucan.Resource) ucan.Resource

ResolveResource resolves `source` resource of the delegated capability from the resource `uri` of the claimed capability. If `source` is `"ucan:*""` or matches `uri` then it returns `uri` back otherwise it returns "".

  • source "ucan:*" uri "did:key:zAlice" → "did:key:zAlice"
  • source "ucan:*" uri "https://example.com" → "https://example.com"
  • source "did:*" uri "did:key:zAlice" → ""
  • source "did:key:zAlice" uri "did:key:zAlice" → "did:key:zAlice"

func ResolveSources 

func ResolveSources(source Source, context ClaimContext) (sources []Source, errors []ProofError)

func Select 

func Select[Caveats any](matcher Matcher[Caveats], capabilities []Source) (matches []Match[Caveats], errors []DelegationError, unknowns []ucan.Capability[any])

func VerifySession 

func VerifySession(dlg delegation.Delegation, prfs []delegation.Delegation, ctx ClaimContext) (Authorization[vdm.AttestationModel], Unauthorized)

VerifySession attempts to find an authorization session - an `ucan/attest` capability delegation where `with` matches `ctx.Authority()` and `nb.proof` matches given delegation.

https://github.com/storacha-network/specs/blob/main/w3-session.md#authorization-session

Types

type Authorization 

type Authorization[Caveats any] interface {
	Audience() ucan.Principal
	Capability() ucan.Capability[Caveats]
	Delegation() delegation.Delegation
	Issuer() ucan.Principal
	Proofs() []Authorization[Caveats]
}

func ConvertUnknownAuthorization 

func ConvertUnknownAuthorization[Caveats any](auth Authorization[Caveats]) Authorization[any]

ConvertUnknownAuthorization converts an Authorization[Caveats] to Authorization[any]

func NewAuthorization 

func NewAuthorization[Caveats any](match Match[Caveats], proofs []Authorization[Caveats]) Authorization[Caveats]

type BadSignature 

type BadSignature interface {
	InvalidProof
	Issuer() ucan.Principal
	Audience() ucan.Principal
	Delegation() delegation.Delegation
	// contains filtered or unexported methods
}

BadSignature is a signature that could not be verified or has been verified invalid. i.e. it is an UnverifiableSignature or an InvalidSignature.

func VerifySignature 

func VerifySignature(dlg delegation.Delegation, vfr principal.Verifier) (delegation.Delegation, BadSignature)

VerifySignature verifies the delegation was signed by the passed verifier.

type CanIssueFunc 

type CanIssueFunc[Caveats any] func(capability ucan.Capability[Caveats], issuer did.DID) bool

CanIssue informs validator whether given capability can be issued by a given DID or whether it needs to be delegated to the issuer.

type CanIssuer 

type CanIssuer[Caveats any] interface {
	// CanIssue informs validator whether given capability can be issued by a
	// given DID or whether it needs to be delegated to the issuer.
	CanIssue(capability ucan.Capability[Caveats], issuer did.DID) bool
}

type CapabilityParser 

type CapabilityParser[Caveats any] interface {
	Matcher[Caveats]
	Selector[Caveats]
	Can() ucan.Ability
	// New creates a new capability from the passed options.
	New(with ucan.Resource, nb Caveats) ucan.Capability[Caveats]
	// Delegate creates a new signed token for this capability. If expiration is
	// not set it defaults to 30 seconds from now.
	Delegate(issuer ucan.Signer, audience ucan.Principal, with ucan.Resource, nb Caveats, options ...delegation.Option) (delegation.Delegation, error)
	// Invoke creates an invocation of this capability.
	Invoke(issuer ucan.Signer, audience ucan.Principal, with ucan.Resource, nb Caveats, options ...delegation.Option) (invocation.IssuedInvocation, error)
}

func NewCapability 

func NewCapability[Caveats any](
	can ucan.Ability,
	with schema.Reader[string, ucan.Resource],
	nb schema.Reader[any, Caveats],
	derives DerivesFunc[Caveats],
) CapabilityParser[Caveats]

type ClaimContext 

type ClaimContext interface {
	Validator
	RevocationChecker[any]
	CanIssuer[any]
	ProofResolver
	PrincipalParser
	PrincipalResolver
}

type DIDKeyResolutionError 

type DIDKeyResolutionError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (DIDKeyResolutionError) DID 

func (dkre DIDKeyResolutionError) DID() did.DID

func (DIDKeyResolutionError) Error 

func (dkre DIDKeyResolutionError) Error() string

func (DIDKeyResolutionError) Unwrap 

func (dkre DIDKeyResolutionError) Unwrap() error

type DelegationError 

type DelegationError interface {
	failure.Failure
	Causes() []DelegationSubError
	Context() any
	// contains filtered or unexported methods
}

func NewDelegationError 

func NewDelegationError(causes []DelegationSubError, context interface{}) DelegationError

type DelegationSubError 

type DelegationSubError interface {
	failure.Failure
	// contains filtered or unexported methods
}

go hack for union type -- unexported method cannot be implemented outside module limiting satisfying types

type Derivable 

type Derivable[Caveats any] interface {
	// Derives determines if a capability is derivable from another. Return `nil`
	// to indicate the delegated capability can be derived from the claimed
	// capability.
	Derives(claimed, delegated ucan.Capability[Caveats]) failure.Failure
}

type DerivesFunc 

type DerivesFunc[Caveats any] func(claimed, delegated ucan.Capability[Caveats]) failure.Failure

DerivesFunc determines if a capability is derivable from another. Return `nil` to indicate the delegated capability can be derived from the claimed capability.

type Descriptor 

type Descriptor[Caveats any] interface {
	Derivable[Caveats]
	Can() ucan.Ability
	With() schema.Reader[string, ucan.Resource]
	Nb() schema.Reader[any, Caveats]
}

type EscalatedCapabilityError 

type EscalatedCapabilityError[Caveats any] struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func NewEscalatedCapabilityError 

func NewEscalatedCapabilityError[Caveats any](claimed ucan.Capability[Caveats], delegated ucan.Capability[Caveats], cause error) EscalatedCapabilityError[Caveats]

func (EscalatedCapabilityError[Caveats]) Error 

func (ece EscalatedCapabilityError[Caveats]) Error() string

func (EscalatedCapabilityError[Caveats]) Unwrap 

func (ece EscalatedCapabilityError[Caveats]) Unwrap() error

type ExpiredError 

type ExpiredError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (ExpiredError) Error 

func (ee ExpiredError) Error() string

func (ExpiredError) ToIPLD 

func (ee ExpiredError) ToIPLD() (datamodel.Node, error)

type InvalidCapability 

type InvalidCapability interface {
	failure.Failure
	// contains filtered or unexported methods
}

InvalidCapability is an error produced when parsing capabilities.

func ParseCapability 

func ParseCapability[O any](descriptor Descriptor[O], source Source) (ucan.Capability[O], InvalidCapability)

func ResolveCapability 

func ResolveCapability[Caveats any](descriptor Descriptor[Caveats], claimed ucan.Capability[Caveats], source Source) (ucan.Capability[Caveats], InvalidCapability)

ResolveCapability resolves delegated capability `source` from the `claimed` capability using provided capability `parser`. It is similar to ParseCapability except `source` here is treated as capability pattern which is matched against the `claimed` capability. This means we resolve `can` and `with` fields from the `claimed` capability and... TODO: inherit all missing `nb` fields from the claimed capability.

type InvalidClaim 

type InvalidClaim interface {
	failure.Failure
	Issuer() ucan.Principal
	Delegation() delegation.Delegation
}

func NewInvalidClaimError 

func NewInvalidClaimError[Caveats any](
	match Match[Caveats],
	delegationErrors []DelegationError,
	unknownCapabilities []ucan.Capability[any],
	invalidProofs []ProofError,
	failedProofs []InvalidClaim,
) InvalidClaim

type InvalidClaimError 

type InvalidClaimError[Caveats any] struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (InvalidClaimError[Caveats]) Delegation 

func (ice InvalidClaimError[Caveats]) Delegation() delegation.Delegation

func (InvalidClaimError[Caveats]) DelegationErrors 

func (ice InvalidClaimError[Caveats]) DelegationErrors() []DelegationError

func (InvalidClaimError[Caveats]) Error 

func (ice InvalidClaimError[Caveats]) Error() string

func (InvalidClaimError[Caveats]) FailedProofs 

func (ice InvalidClaimError[Caveats]) FailedProofs() []InvalidClaim

func (InvalidClaimError[Caveats]) InvalidProofs 

func (ice InvalidClaimError[Caveats]) InvalidProofs() []ProofError

func (InvalidClaimError[Caveats]) Issuer 

func (ice InvalidClaimError[Caveats]) Issuer() ucan.Principal

func (InvalidClaimError[Caveats]) UnknownCapabilities 

func (ice InvalidClaimError[Caveats]) UnknownCapabilities() []ucan.Capability[any]

type InvalidProof 

type InvalidProof interface {
	failure.Failure
	// contains filtered or unexported methods
}

func NewExpiredError 

func NewExpiredError(delegation delegation.Delegation) InvalidProof

func NewNotValidBeforeError 

func NewNotValidBeforeError(delegation delegation.Delegation) InvalidProof

func NewSessionEscalationError 

func NewSessionEscalationError(delegation delegation.Delegation, cause error) InvalidProof

func Validate 

func Validate(dlg delegation.Delegation, prfs []delegation.Delegation, ctx ClaimContext) (delegation.Delegation, InvalidProof)

Validate a delegation to check it is within the time bound and that it is authorized by the issuer.

func VerifyAuthorization 

func VerifyAuthorization(dlg delegation.Delegation, prfs []delegation.Delegation, ctx ClaimContext) (delegation.Delegation, InvalidProof)

VerifyAuthorization verifies that delegation has been authorized by the issuer. If issued by the did:key principal checks that the signature is valid. If issued by the root authority checks that the signature is valid. If issued by the principal identified by other DID method attempts to resolve a valid `ucan/attest` attestation from the authority, if attestation is not found falls back to resolving did:key for the issuer and verifying its signature.

type InvalidSignature 

type InvalidSignature interface {
	BadSignature
	// contains filtered or unexported methods
}

InvalidSignature is a signature that is verified to be invalid.

func NewInvalidSignatureError 

func NewInvalidSignatureError(delegation delegation.Delegation, verifier ucan.Verifier) InvalidSignature

type InvalidSignatureError 

type InvalidSignatureError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (InvalidSignatureError) Audience 

func (ise InvalidSignatureError) Audience() ucan.Principal

func (InvalidSignatureError) Delegation 

func (ise InvalidSignatureError) Delegation() delegation.Delegation

func (InvalidSignatureError) Error 

func (ise InvalidSignatureError) Error() string

func (InvalidSignatureError) Issuer 

func (ise InvalidSignatureError) Issuer() ucan.Principal

type MalformedCapability 

type MalformedCapability interface {
	InvalidCapability
	DelegationSubError
	Capability() ucan.Capability[any]
	// contains filtered or unexported methods
}

func NewMalformedCapabilityError 

func NewMalformedCapabilityError(capability ucan.Capability[any], cause error) MalformedCapability

type MalformedCapabilityError 

type MalformedCapabilityError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (MalformedCapabilityError) Capability 

func (mce MalformedCapabilityError) Capability() ucan.Capability[any]

func (MalformedCapabilityError) Error 

func (mce MalformedCapabilityError) Error() string

type Match 

type Match[Caveats any] interface {
	Selector[Caveats]
	Source() []Source
	Value() ucan.Capability[Caveats]
	Proofs() []delegation.Delegation
	Prune(context CanIssuer[Caveats]) Match[Caveats]
}

func NewMatch 

func NewMatch[Caveats any](source Source, capability ucan.Capability[Caveats], descriptor Descriptor[Caveats]) Match[Caveats]

type Matcher 

type Matcher[Caveats any] interface {
	Match(source Source) (Match[Caveats], InvalidCapability)
}

type NotValidBeforeError 

type NotValidBeforeError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (NotValidBeforeError) Error 

func (nvbe NotValidBeforeError) Error() string

func (NotValidBeforeError) ToIPLD 

func (nvbe NotValidBeforeError) ToIPLD() (datamodel.Node, error)

type PrincipalAlignmentError 

type PrincipalAlignmentError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (PrincipalAlignmentError) Error 

func (pae PrincipalAlignmentError) Error() string

type PrincipalParser 

type PrincipalParser interface {
	ParsePrincipal(str string) (principal.Verifier, error)
}

PrincipalParser provides verifier instances that can validate UCANs issued by a given principal.

type PrincipalParserFunc 

type PrincipalParserFunc func(str string) (principal.Verifier, error)

type PrincipalResolver 

type PrincipalResolver interface {
	ResolveDIDKey(did did.DID) (did.DID, UnresolvedDID)
}

PrincipalResolver is used to resolve a key of the principal that is identified by DID different from did:key method. It can be passed into a UCAN validator in order to augmented it with additional DID methods support.

type PrincipalResolverFunc 

type PrincipalResolverFunc func(did did.DID) (did.DID, UnresolvedDID)

PrincipalResolverFunc resolves the key of a principal that is identified by DID different from did:key method.

type ProofError 

type ProofError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func NewProofError 

func NewProofError(proof ucan.Link, cause error) ProofError

func (ProofError) Error 

func (pe ProofError) Error() string

func (ProofError) Proof 

func (pe ProofError) Proof() ucan.Link

func (ProofError) Unwrap 

func (pe ProofError) Unwrap() error

type ProofResolver 

type ProofResolver interface {
	// Resolve finds a delegation corresponding to an external proof link.
	ResolveProof(proof ucan.Link) (delegation.Delegation, UnavailableProof)
}

ProofResolver finds a delegations when external proof links are present in UCANs. If a resolver is not provided the validator may not be able to explore corresponding path within a proof chain.

type ProofResolverFunc 

type ProofResolverFunc func(proof ucan.Link) (delegation.Delegation, UnavailableProof)

Resolve finds a delegation corresponding to an external proof link.

type RevocationChecker 

type RevocationChecker[Caveats any] interface {
	// ValidateAuthorization validates that the passed authorization has not been
	// revoked. It returns `nil` if not revoked.
	ValidateAuthorization(auth Authorization[Caveats]) Revoked
}

type RevocationCheckerFunc 

type RevocationCheckerFunc[Caveats any] func(auth Authorization[Caveats]) Revoked

RevocationCheckerFunc validates that the passed authorization has not been revoked. It returns `nil` if not revoked.

type Revoked 

type Revoked interface {
	InvalidProof
	Delegation() delegation.Delegation
	// contains filtered or unexported methods
}

func NewRevokedError 

func NewRevokedError(delegation delegation.Delegation) Revoked

type RevokedError 

type RevokedError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (RevokedError) Delegation 

func (re RevokedError) Delegation() delegation.Delegation

func (RevokedError) Error 

func (re RevokedError) Error() string

type Selector 

type Selector[Caveats any] interface {
	Select(sources []Source) ([]Match[Caveats], []DelegationError, []ucan.Capability[any])
}

type SessionEscalationError 

type SessionEscalationError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (SessionEscalationError) Error 

func (see SessionEscalationError) Error() string

type Source 

type Source interface {
	Capability() ucan.Capability[any]
	Delegation() delegation.Delegation
}

func NewSource 

func NewSource(capability ucan.Capability[any], delegation delegation.Delegation) Source

type Unauthorized 

type Unauthorized interface {
	failure.Failure
	DelegationErrors() []DelegationError
	UnknownCapabilities() []ucan.Capability[any]
	InvalidProofs() []InvalidProof
	FailedProofs() []InvalidClaim
	// contains filtered or unexported methods
}

func NewUnauthorizedError 

func NewUnauthorizedError[Caveats any](
	capability CapabilityParser[Caveats],
	delegationErrors []DelegationError,
	unknownCapabilities []ucan.Capability[any],
	invalidProofs []InvalidProof,
	failedProofs []InvalidClaim,
) Unauthorized

type UnauthorizedError 

type UnauthorizedError[Caveats any] struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (UnauthorizedError[Caveats]) DelegationErrors 

func (ue UnauthorizedError[Caveats]) DelegationErrors() []DelegationError

func (UnauthorizedError[Caveats]) Error 

func (ue UnauthorizedError[Caveats]) Error() string

func (UnauthorizedError[Caveats]) FailedProofs 

func (ue UnauthorizedError[Caveats]) FailedProofs() []InvalidClaim

func (UnauthorizedError[Caveats]) InvalidProofs 

func (ue UnauthorizedError[Caveats]) InvalidProofs() []InvalidProof

func (UnauthorizedError[Caveats]) UnknownCapabilities 

func (ue UnauthorizedError[Caveats]) UnknownCapabilities() []ucan.Capability[any]

type UnavailableProof 

type UnavailableProof interface {
	InvalidProof
	Link() ucan.Link
	// contains filtered or unexported methods
}

func NewUnavailableProofError 

func NewUnavailableProofError(link ucan.Link, cause error) UnavailableProof

func ProofUnavailable 

func ProofUnavailable(p ucan.Link) (delegation.Delegation, UnavailableProof)

func ResolveProofs 

func ResolveProofs(proofs []delegation.Proof, resolver ProofResolver) (dels []delegation.Delegation, errs []UnavailableProof)

ResolveProofs takes `proofs` from the delegation which may contain a delegation.Delegation or a link to one and attempts to resolve links by side loading them. It returns a set of resolved [delegation.Delegation]s and errors for the proofs that could not be resolved.

type UnavailableProofError 

type UnavailableProofError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (UnavailableProofError) Error 

func (upe UnavailableProofError) Error() string
func (upe UnavailableProofError) Link() ucan.Link

func (UnavailableProofError) Unwrap 

func (upe UnavailableProofError) Unwrap() error

type UnknownCapability 

type UnknownCapability interface {
	InvalidCapability
	Capability() ucan.Capability[any]
	// contains filtered or unexported methods
}

func NewUnknownCapabilityError 

func NewUnknownCapabilityError(capability ucan.Capability[any]) UnknownCapability

type UnknownCapabilityError 

type UnknownCapabilityError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (UnknownCapabilityError) Capability 

func (uce UnknownCapabilityError) Capability() ucan.Capability[any]

func (UnknownCapabilityError) Error 

func (uce UnknownCapabilityError) Error() string

type UnresolvedDID 

type UnresolvedDID interface {
	InvalidProof
	DID() did.DID
	// contains filtered or unexported methods
}

func FailDIDKeyResolution 

func FailDIDKeyResolution(d did.DID) (did.DID, UnresolvedDID)

func NewDIDKeyResolutionError 

func NewDIDKeyResolutionError(did did.DID, cause error) UnresolvedDID

type UnverifiableSignature 

type UnverifiableSignature interface {
	BadSignature
	Unwrap() error
	// contains filtered or unexported methods
}

UnverifiableSignature is a signature that cannot be verified. i.e. some error occurred when attempting to verify the signature.

func NewUnverifiableSignatureError 

func NewUnverifiableSignatureError(delegation delegation.Delegation, cause error) UnverifiableSignature

type UnverifiableSignatureError 

type UnverifiableSignatureError struct {
	failure.NamedWithStackTrace
	// contains filtered or unexported fields
}

func (UnverifiableSignatureError) Audience 

func (use UnverifiableSignatureError) Audience() ucan.Principal

func (UnverifiableSignatureError) Delegation 

func (use UnverifiableSignatureError) Delegation() delegation.Delegation

func (UnverifiableSignatureError) Error 

func (use UnverifiableSignatureError) Error() string

func (UnverifiableSignatureError) Issuer 

func (use UnverifiableSignatureError) Issuer() ucan.Principal

func (UnverifiableSignatureError) Unwrap 

func (use UnverifiableSignatureError) Unwrap() error

type ValidationContext 

type ValidationContext[Caveats any] interface {
	ClaimContext
	Capability() CapabilityParser[Caveats]
}

func NewValidationContext 

func NewValidationContext[Caveats any](
	authority principal.Verifier,
	capability CapabilityParser[Caveats],
	canIssue CanIssueFunc[any],
	validateAuthorization RevocationCheckerFunc[any],
	resolveProof ProofResolverFunc,
	parsePrincipal PrincipalParserFunc,
	resolveDIDKey PrincipalResolverFunc,
) ValidationContext[Caveats]

type Validator 

type Validator interface {
	Authority() principal.Verifier
}

Validator must provide a principal.Verifier corresponding to local authority.

A capability provider service will use one corresponding to own DID or it's supervisor's DID if it acts under it's authority.

This allows a service identified by non did:key e.g. did:web or did:dns to pass resolved key so it does not need to be resolved at runtime.

Source Files

View all Source files

Directories

Path Synopsis

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.