libsf

Documentation

Index

• Constants
• Variables
• func GenerateItemEncryptionKey() (string, error)
• func GenerateRandomBytes(n int) ([]byte, error)
• func TimeFromToken(token string) time.Time
• func TokenFromTime(t time.Time) (token string)
• type Auth
• type Client
  • func NewClient(c *http.Client, apiversion string, endpoint string) (Client, error)
  • func NewDefaultClient(endpoint string) (Client, error)
• type ConflictItem
• type Item
  • func (i *Item) Seal(mk, ak string) error
  • func (i *Item) Unseal(mk, ak string) error
• type Note
  • func (n *Note) GetSortingField() string
  • func (n *Note) ParseRaw() error
  • func (n *Note) SaveRaw()
  • func (n *Note) SetUpdatedAtNow()
  • func (n *Note) UpdatedAt() time.Time
• type SFError
  • func (e *SFError) Error() string
• type SyncItems
  • func NewSyncItems() SyncItems
• type UnsavedItem

Constants

const (
	// APIVersion20161215 allows to use the API version 20161215.
	APIVersion20161215 = "20161215"
	// APIVersion20190520 allows to use the API version 20190520.
	APIVersion20190520 = "20190520"

	// APIVersion is the version used by default client.
	APIVersion = APIVersion20190520
)

const (
	// ContentTypeUserPreferences for items that holds user's preferences.
	ContentTypeUserPreferences = "SN|UserPreferences"
	// ContentTypePrivileges for items that holds note's privileges.
	ContentTypePrivileges = "SN|Privileges"
	// ContentTypeComponent are items that describes an editor extension.
	ContentTypeComponent = "SN|Component"
	// ContentTypeNote are the items with user's written data.
	ContentTypeNote = "Note"
)

Variables

var (
	// ErrUnsupportedVersion is raised when user params version is lesser than `002`.
	ErrUnsupportedVersion = errors.New("libsf: unsupported version")
	// ErrLowPasswordCost occurred when cost of password is too low for the used KDF.
	ErrLowPasswordCost = errors.New("libsf: low password cost")
)

Functions

func GenerateItemEncryptionKey

func GenerateItemEncryptionKey() (string, error)

GenerateItemEncryptionKey generates a key that will be split in half, each being 256 bits. So total length will need to be 512.

func GenerateRandomBytes

func GenerateRandomBytes(n int) ([]byte, error)

GenerateRandomBytes returns securely generated random bytes. It will return an error if the system's secure random number generator fails to function correctly, in which case the caller should not continue.

func TimeFromToken

func TimeFromToken(token string) time.Time

TimeFromToken retrieves datetime from cursor/sync token.

func TokenFromTime

func TokenFromTime(t time.Time) (token string)

TokenFromTime generates cursor/sync token for given time.

Types

type Auth

type Auth interface {
	// Email returns the email used for authentication.
	Email() string
	// Version returns the encryption scheme version.
	Version() string
	// IntegrityCheck checks if the Auth params are valid.
	IntegrityCheck() error
	// SymmetricKeyPair returns the password, master_key and auth_key for the given uip (plaintext password of the user).
	// https://github.com/standardfile/standardfile.github.io/blob/master/doc/spec.md#client-instructions
	SymmetricKeyPair(uip string) (pw, mk, ak string)
}

An Auth holds all the params needed to create the credentials and cipher keys.

type Client

type Client interface {
	// GetAuthParams returns the parameters of a user from StandardFile server.
	GetAuthParams(email string) (Auth, error)
	// Login connects the Client to the StandardFile server.
	Login(email, password string) error
	// BearerToken returns the authentication used for requests sent to the StandardFile server.
	BearerToken() string
	// SetBearerToken sets the authentication used for requests sent to the StandardFile server.
	SetBearerToken(token string)
	// SyncItems synchronizes local items with the StandardFile server.
	SyncItems(si SyncItems) (SyncItems, error)
}

A Client defines all interactions that can be performed on a StandardFile server.

func NewClient

func NewClient(c *http.Client, apiversion string, endpoint string) (Client, error)

NewClient returns a new Client.

func NewDefaultClient

func NewDefaultClient(endpoint string) (Client, error)

NewDefaultClient returns a new Client with default HTTP client.

type ConflictItem

type ConflictItem struct {
	UnsavedItem Item   `json:"unsaved_item,omitempty"`
	ServerItem  Item   `json:"server_item,omitempty"`
	Type        string `json:"type"`
}

A ConflictItem is an object containing an item that can't be saved caused by conflicts. Used since API version 20190520.

type Item

type Item struct {
	ID        string     `json:"uuid"`
	CreatedAt *time.Time `json:"created_at"`
	UpdatedAt *time.Time `json:"updated_at"`

	UserID           string `json:"user_uuid"`
	Content          string `json:"content"`
	ContentType      string `json:"content_type"`
	EncryptedItemKey string `json:"enc_item_key"`
	Deleted          bool   `json:"deleted"`

	// Internal
	Version    string `json:"-"`
	AuthParams Auth   `json:"-"`
	Note       *Note  `json:"-"`
	// contains filtered or unexported fields
}

An Item holds all the data created by end user.

func (*Item) Seal

func (i *Item) Seal(mk, ak string) error

Seal encrypts Note to item's Content.

func (*Item) Unseal

func (i *Item) Unseal(mk, ak string) error

Unseal decrypts the item's Content into Note.

type Note

type Note struct {
	Title        string          `json:"title"`
	Text         string          `json:"text"`
	PreviewPlain string          `json:"preview_plain"`
	PreviewHTML  string          `json:"preview_html"`
	References   json.RawMessage `json:"references"` // unstructured data
	AppData      json.RawMessage `json:"appData"`    // unstructured data
	// contains filtered or unexported fields
}

A Note is plaintext Item content.

func (*Note) GetSortingField

func (n *Note) GetSortingField() string

GetSortingField returns the field on which all notes are sorted. Only for `SN|UserPreferences` items, it returns an empty string if nothing found.

func (*Note) ParseRaw

func (n *Note) ParseRaw() error

ParseRaw parses unstructured raw fields. Needed before using other methods on Note object.

func (*Note) SaveRaw

func (n *Note) SaveRaw()

SaveRaw persists the unstructured fields to raw data.

func (*Note) SetUpdatedAtNow

func (n *Note) SetUpdatedAtNow()

SetUpdatedAtNow sets current time as last update time.

func (*Note) UpdatedAt

func (n *Note) UpdatedAt() time.Time

UpdatedAt returns the last update time of the note. If not found or error, "zero" time is returned.

type SFError

type SFError struct {
	StatusCode int
	Err        struct {
		Message string `json:"message"`
	} `json:"error"`
}

An SFError reprensents an HTTP error returned by StandardFile server.

func (*SFError) Error

func (e *SFError) Error() string

type SyncItems

type SyncItems struct {
	// Common fields
	API              string `json:"api"` // Since 20190520
	ComputeIntegrity bool   `json:"compute_integrity"`
	Limit            int    `json:"limit"`
	SyncToken        string `json:"sync_token"`
	CursorToken      string `json:"cursor_token"`
	ContentType      string `json:"content_type"` // optional, only return items of these type if present

	// Fields used for request
	Items []*Item `json:"items"`

	// Fields used in response
	Retrieved []*Item `json:"retrieved_items"`
	Saved     []*Item `json:"saved_items"`

	// 20161215 fields
	Unsaved []*UnsavedItem `json:"unsaved"`

	// 20190520 fields
	Conflicts []*ConflictItem `json:"conflicts"`
}

A SyncItems is used when a client want to sync items.

func NewSyncItems

func NewSyncItems() SyncItems

NewSyncItems returns an empty SyncItems with initilized defaults.

type UnsavedItem

type UnsavedItem struct {
	Item  Item `json:"item"`
	Error struct {
		Message string `json:"message"`
		Tag     string `json:"tag"`
	} `json:"error"`
}

An UnsavedItem is an object containing an item that has not been saved. Used before API version 20190520.