Documentation

Index

Constants

View Source
const (
	// TypeRegister is the value of Permission.Type for the temporary permissions
	// allowed by registerToken
	TypeRegister = "register"

	// TypeWebapp is the value of Permission.Type for an application
	TypeWebapp = "app"

	// TypeKonnector is the value of Permission.Type for an application
	TypeKonnector = "konnector"

	// TypeOauth is the value of Permission.Type for a oauth permission doc
	TypeOauth = "oauth"

	// TypeCLI is the value of Permission.Type for a command-line permission doc
	TypeCLI = "cli"

	// TypeShareByLink is the value of Permission.Type for a share (by link) permission doc
	TypeShareByLink = "share"

	// TypeSharePreview is the value of Permission.Type to preview a
	// cozy-to-cozy sharing
	TypeSharePreview = "share-preview"

	// TypeShareInteract is the value of Permission.Type for reading and
	// writing a note in a shared folder.
	TypeShareInteract = "share-interact"
)
View Source
const (
	GET    = Verb("GET")
	POST   = Verb("POST")
	PUT    = Verb("PUT")
	PATCH  = Verb("PATCH")
	DELETE = Verb("DELETE")
)

All possible Verbs, a subset of http methods

View Source
const DocTypeVersion = "1"

DocTypeVersion represents the doctype version. Each time this document structure is modified, update this value

View Source
const RefSep = "/"

RefSep is used to separate doctype and value for a referenced selector

Variables

View Source
var (
	// ErrInvalidToken is used when the token is invalid (the signature is not
	// correct, the domain is not the good one, etc.)
	ErrInvalidToken = echo.NewHTTPError(http.StatusBadRequest,
		"Invalid JWT token")

	// ErrInvalidAudience is used when the audience is not expected
	ErrInvalidAudience = echo.NewHTTPError(http.StatusBadRequest,
		"Invalid audience for JWT token")

	// ErrExpiredToken is used when the token has expired and the client should
	// refresh it
	ErrExpiredToken = echo.NewHTTPError(http.StatusBadRequest,
		"Expired token")

	// ErrBadScope is used when the given scope is malformed
	ErrBadScope = echo.NewHTTPError(http.StatusBadRequest,
		"Permission scope is empty or malformed")

	// ErrNotSubset is returned on requests attempting to create a Set of
	// permissions which is not a subset of the request's own token.
	ErrNotSubset = echo.NewHTTPError(http.StatusForbidden,
		"Attempt to create a larger permission set")

	// ErrOnlyAppCanCreateSubSet is returned if a non-app attempts to create
	// sharing permissions.
	ErrOnlyAppCanCreateSubSet = echo.NewHTTPError(http.StatusForbidden,
		"Only apps can create sharing permissions")

	// ErrNotParent is used when the permissions should have a specific parent.
	ErrNotParent = echo.NewHTTPError(http.StatusForbidden,
		"Permissions can be updated only by its parent")
)

ALL : the default VerbSet allows all Verbs

Functions

func CheckDoctypeName

func CheckDoctypeName(doctype string, authorizeWildcard bool) error

CheckDoctypeName will return an error if the doctype name is invalid. A doctype name must be composed of lowercase letters, digits, . and _ characters to be valid.

func CheckReadable

func CheckReadable(doctype string) error

CheckReadable will abort the context and returns false if the doctype is unreadable

func CheckWritable

func CheckWritable(doctype string) error

CheckWritable will abort the echo context if the doctype is unwritable

func DestroyKonnector

func DestroyKonnector(db prefixer.Prefixer, slug string) error

DestroyKonnector remove all Permission docs for a given konnector

func DestroyWebapp

func DestroyWebapp(db prefixer.Prefixer, slug string) error

DestroyWebapp remove all Permission docs for a given app

func ForceWebapp

func ForceWebapp(db prefixer.Prefixer, slug string, set Set) error

ForceWebapp creates or updates a Permission doc for a given webapp

func GetPermissionsForIDs

func GetPermissionsForIDs(db prefixer.Prefixer, doctype string, ids []string) (map[string]*VerbSet, error)

GetPermissionsForIDs gets permissions for several IDs returns for every id the combined allowed verbset

func GetTokenFromShortcode

func GetTokenFromShortcode(db prefixer.Prefixer, shortcode string) (string, error)

GetTokenFromShortcode retrieves the token doc for a given sharing shortcode

func MatchType

func MatchType(r Rule, doctype string) bool

MatchType returns true if the rule type matches the given doctype

func TrimWildcard

func TrimWildcard(doctype string) string

TrimWildcard returns the given doctype without the wildcard suffix

Types

type Claims

type Claims struct {
	jwt.StandardClaims
	Scope     string `json:"scope,omitempty"`
	SessionID string `json:"session_id,omitempty"`
	SStamp    string `json:"stamp,omitempty"`
}

Claims is used for JWT used in OAuth2 flow and applications token

func (*Claims) Expired

func (claims *Claims) Expired() bool

Expired returns true if a Claim is expired

func (*Claims) IssuedAtUTC

func (claims *Claims) IssuedAtUTC() time.Time

IssuedAtUTC returns a time.Time struct of the IssuedAt field in UTC location.

type Fetcher

type Fetcher interface {
	ID() string
	DocType() string
	Fetch(field string) []string
}

Fetcher is an interface for an object to see if it matches a rule.

type Permission

type Permission struct {
	PID         string            `json:"_id,omitempty"`
	PRev        string            `json:"_rev,omitempty"`
	Type        string            `json:"type,omitempty"`
	SourceID    string            `json:"source_id,omitempty"`
	Permissions Set               `json:"permissions,omitempty"`
	ExpiresAt   *time.Time        `json:"expires_at,omitempty"`
	Codes       map[string]string `json:"codes,omitempty"`
	ShortCodes  map[string]string `json:"shortcodes,omitempty"`

	Client   interface{}            `json:"-"` // Contains the *oauth.Client client pointer for Oauth permission type
	Metadata *metadata.CozyMetadata `json:"cozyMetadata,omitempty"`
}

Permission is a storable object containing a set of rules and several codes

func CreateKonnectorSet

func CreateKonnectorSet(db prefixer.Prefixer, slug string, set Set, version string) (*Permission, error)

CreateKonnectorSet creates a Permission doc for a konnector

func CreateShareInteractSet

func CreateShareInteractSet(db prefixer.Prefixer, sharingID string, codes map[string]string, subdoc Permission) (*Permission, error)

CreateShareInteractSet creates a Permission doc for reading/writing a note inside a sharing

func CreateSharePreviewSet

func CreateSharePreviewSet(db prefixer.Prefixer, sharingID string, codes, shortcodes map[string]string, subdoc Permission) (*Permission, error)

CreateSharePreviewSet creates a Permission doc for previewing a sharing

func CreateShareSet

func CreateShareSet(db prefixer.Prefixer, parent *Permission, sourceID string, codes, shortcodes map[string]string, subdoc Permission, expiresAt *time.Time) (*Permission, error)

CreateShareSet creates a Permission doc for sharing by link

func CreateWebappSet

func CreateWebappSet(db prefixer.Prefixer, slug string, set Set, version string) (*Permission, error)

CreateWebappSet creates a Permission doc for an app

func GetByID

func GetByID(db prefixer.Prefixer, id string) (*Permission, error)

GetByID fetch a permission by its ID

func GetForCLI

func GetForCLI(claims *Claims) (*Permission, error)

GetForCLI create a non-persisted permissions doc for the command-line

func GetForKonnector

func GetForKonnector(db prefixer.Prefixer, slug string) (*Permission, error)

GetForKonnector retrieves the Permission doc for a given konnector

func GetForRegisterToken

func GetForRegisterToken() *Permission

GetForRegisterToken create a non-persisted permissions doc with hard coded registerToken permissions set

func GetForShareCode

func GetForShareCode(db prefixer.Prefixer, tokenCode string) (*Permission, error)

GetForShareCode retrieves the Permission doc for a given sharing code

func GetForShareInteract

func GetForShareInteract(db prefixer.Prefixer, sharingID string) (*Permission, error)

GetForShareInteract retrieves the Permission doc for a given sharing to read/write a note

func GetForSharePreview

func GetForSharePreview(db prefixer.Prefixer, sharingID string) (*Permission, error)

GetForSharePreview retrieves the Permission doc for a given sharing preview

func GetForWebapp

func GetForWebapp(db prefixer.Prefixer, slug string) (*Permission, error)

GetForWebapp retrieves the Permission doc for a given webapp

func GetPermissionsByDoctype

func GetPermissionsByDoctype(db prefixer.Prefixer, permType, doctype string, cursor couchdb.Cursor) ([]Permission, error)

GetPermissionsByDoctype returns the list of all permissions of the given type (shared-with-me by example) that have at least one rule for the given doctype. The cursor will be modified in place.

func UpdateKonnectorSet

func UpdateKonnectorSet(db prefixer.Prefixer, slug string, set Set) (*Permission, error)

UpdateKonnectorSet creates a Permission doc for a konnector

func UpdateWebappSet

func UpdateWebappSet(db prefixer.Prefixer, slug string, set Set) (*Permission, error)

UpdateWebappSet creates a Permission doc for an app

func (*Permission) AddRules

func (p *Permission) AddRules(rules ...Rule)

AddRules add some rules to the permission doc

func (p *Permission) CanUpdateShareByLink(child *Permission) bool

CanUpdateShareByLink check if the child permissions can be updated by p (p can be the parent or it has a superset of the permissions).

func (*Permission) Clone

func (p *Permission) Clone() couchdb.Doc

Clone implements couchdb.Doc

func (*Permission) DocType

func (p *Permission) DocType() string

DocType implements jsonapi.Doc

func (*Permission) Expired

func (p *Permission) Expired() bool

Expired returns true if the permissions are no longer valid

func (*Permission) ID

func (p *Permission) ID() string

ID implements jsonapi.Doc

func (*Permission) PatchCodes

func (p *Permission) PatchCodes(codes map[string]string)

PatchCodes replace the permission docs codes

func (*Permission) RemoveRule

func (p *Permission) RemoveRule(rule Rule)

RemoveRule remove a rule from the permission doc

func (*Permission) Rev

func (p *Permission) Rev() string

Rev implements jsonapi.Doc

func (*Permission) Revoke

func (p *Permission) Revoke(db prefixer.Prefixer) error

Revoke destroy a Permission

func (*Permission) SetID

func (p *Permission) SetID(id string)

SetID implements jsonapi.Doc

func (*Permission) SetRev

func (p *Permission) SetRev(rev string)

SetRev implements jsonapi.Doc

type Rule

type Rule struct {
	// Type is the JSON-API type or couchdb Doctype
	Type string `json:"type"`

	// Title is a human readable (i18n key) header for this rule
	Title string `json:"-"`

	// Description is a human readable (i18n key) purpose of this rule
	Description string `json:"description,omitempty"`

	// Verbs is a subset of http methods.
	Verbs VerbSet `json:"verbs,omitempty"`

	// Selector is the field which must be one of Values.
	Selector string   `json:"selector,omitempty"`
	Values   []string `json:"values,omitempty"`
}

Rule represent a single permissions rule, ie a Verb and a type

func UnmarshalRuleString

func UnmarshalRuleString(in string) (Rule, error)

UnmarshalRuleString parse a scope formated rule

func (Rule) MarshalScopeString

func (r Rule) MarshalScopeString() (string, error)

MarshalScopeString transform a Rule into a string of the shape io.cozy.files:GET:io.cozy.files.music-dir

func (Rule) Merge

func (r Rule) Merge(r2 Rule) (*Rule, error)

Merge merges the rule2 in rule1 Rule1 name & description are kept

func (Rule) SomeValue

func (r Rule) SomeValue(predicate func(v string) bool) bool

SomeValue returns true if any value statisfy the predicate

func (Rule) TranslationKey

func (r Rule) TranslationKey() string

TranslationKey returns a string that can be used as a key for translating a description of this rule

func (Rule) ValuesChanged

func (r Rule) ValuesChanged(old, current Fetcher) bool

ValuesChanged returns true if the value for the given selector has changed

func (Rule) ValuesContain

func (r Rule) ValuesContain(values ...string) bool

ValuesContain returns true if all the values are in r.Values

func (Rule) ValuesMatch

func (r Rule) ValuesMatch(o Fetcher) bool

ValuesMatch returns true if any value statisfy the predicate

type Set

type Set []Rule

Set is a Set of rule

func Diff

func Diff(set1, set2 Set) (Set, error)

Diff returns a the differences between two sets. Useful to see what rules had been added between a original manifest permissions and now.

TODO: We are ignoring removed values/verbs between rule 1 and rule 2. - At the moment, it onlys show the added values, verbs and rules

func MergeExtraPermissions

func MergeExtraPermissions(perms, extraPermissions Set) (Set, error)

MergeExtraPermissions merges rules from "extraPermissions" set by adding them in the "perms" one

func UnmarshalScopeString

func UnmarshalScopeString(in string) (Set, error)

UnmarshalScopeString parse a Scope string into a permission Set

func (Set) Allow

func (s Set) Allow(v Verb, o Fetcher) bool

Allow returns true if the set allows to apply verb to given doc

func (Set) AllowID

func (s Set) AllowID(v Verb, doctype, id string) bool

AllowID returns true if the set allows to apply verb to given type & id

func (Set) AllowOnFields

func (s Set) AllowOnFields(v Verb, o Fetcher, fields ...string) bool

AllowOnFields returns true if the set allows to apply verb to given doc on the specified fields.

func (Set) AllowWholeType

func (s Set) AllowWholeType(v Verb, doctype string) bool

AllowWholeType returns true if the set allows to apply verb to every document from the given doctypes (ie. r.values == 0)

func (Set) HasSameRules

func (s Set) HasSameRules(other Set) bool

HasSameRules returns true if the two sets have exactly the same rules.

func (*Set) IsSubSetOf

func (s *Set) IsSubSetOf(parent Set) bool

IsSubSetOf returns true if any document allowed by the set would have been allowed by parent.

func (Set) MarshalJSON

func (s Set) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaller on Set. Note that the JSON representation is a key-value object, but the golang Set is an ordered slice. In theory, JSON objects have no order on their keys, but here, we try to keep the same order on decoding/encoding. See docs/permissions.md for more details on the structure.

func (Set) MarshalScopeString

func (s Set) MarshalScopeString() (string, error)

MarshalScopeString transforms a Set into a string for Oauth Scope (a space separated concatenation of its rules)

func (*Set) RuleInSubset

func (s *Set) RuleInSubset(r2 Rule) bool

RuleInSubset returns true if any document allowed by the rule is allowed by the set.

func (Set) Some

func (s Set) Some(predicate func(Rule) bool) bool

Some returns true if the predicate return true for any of the rule.

func (*Set) UnmarshalJSON

func (s *Set) UnmarshalJSON(j []byte) error

UnmarshalJSON parses a json formated permission set

type Verb

type Verb string

Verb is one of GET,POST,PUT,PATCH,DELETE

type VerbSet

type VerbSet map[Verb]struct{}

VerbSet is a Set of Verbs

func VerbSplit

func VerbSplit(in string) VerbSet

VerbSplit parse a string into a VerbSet Note: this does not check if Verbs are proper HTTP Verbs This behaviour is used in @event trigger

func Verbs

func Verbs(verbs ...Verb) VerbSet

Verbs is a utility function to create VerbSets

func (VerbSet) Contains

func (vs VerbSet) Contains(v Verb) bool

Contains check if VerbSet contains a Verb

func (VerbSet) ContainsAll

func (vs VerbSet) ContainsAll(verbs VerbSet) bool

ContainsAll check if VerbSet contains all passed verbs

func (VerbSet) MarshalJSON

func (vs VerbSet) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaller on VerbSet the VerbSet is converted to a json array

func (*VerbSet) Merge

func (vs *VerbSet) Merge(verbs *VerbSet)

Merge add verbs to the set

func (VerbSet) ReadOnly

func (vs VerbSet) ReadOnly() bool

ReadOnly returns true if the set contains only the verb GET

func (VerbSet) String

func (vs VerbSet) String() string

func (*VerbSet) UnmarshalJSON

func (vs *VerbSet) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaller on VerbSet it expects a json array