upspin

type Attribute byte

type BlockPacker interface {
	// Pack takes cleartext data and returns the packed ciphertext,
	// appending a DirBlock to the DirEntry.
	//
	// The ciphertext slice remains valid until the next call to Pack.
	Pack(cleartext []byte) (ciphertext []byte, err error)

	// SetLocation updates the Location field of the last-Packed DirBlock.
	SetLocation(Location)

	// Close updates the Signature for the DirEntry and releases any
	// resources associated with the packing operation.
	Close() error
}

type BlockUnpacker interface {
	// NextBlock returns the next DirBlock in the sequence and true,
	// or a zero DirBlock and false if there are no more blocks to unpack.
	NextBlock() (DirBlock, bool)

	// SeekBlock returns the nth DirBlock and true,
	// or a zero DirBlock and false if the nth block does not exist.
	SeekBlock(n int) (DirBlock, bool)

	// Unpack takes ciphertext returns the cleartext. If appropriate, the
	// result is verified as correct according to the block's Packdata.
	//
	// The cleartext slice remains valid until the next call to Unpack.
	Unpack(ciphertext []byte) (cleartext []byte, err error)

	// Close releases any resources associated with the unpacking
	// operation.
	Close() error
}

type Client interface {
	// Get returns the clear, decrypted data stored under the given name.
	// It is intended only for special purposes, since it will allocate memory
	// for the entire "blob" to return. The file-like API below can be less
	//  memory-intensive.
	Get(name PathName) ([]byte, error)

	// Lookup returns the directory entry for the named file. The
	// boolean determines whether, if the final path element is a link,
	// to return the DirEntry for the link (false) or for the target of
	// the link (true).
	Lookup(name PathName, followFinal bool) (*DirEntry, error)

	// Put stores the data at the given name. If something is already
	// stored with that name, it will no longer be available using the
	// name, although it may still exist in the storage server. (See
	// the documentation for Delete.) Like Get, it is not the usual
	// access method. The file-like API is preferred.
	//
	// A successful Put returns an incomplete DirEntry (see the
	// description of AttrIncomplete) containing only the
	// new sequence number.
	Put(name PathName, data []byte) (*DirEntry, error)

	// PutSequenced stores the data at the given name only if
	// there is no preexisting data stored with that name or if the
	// sequence number of the preexisting data matches that given.
	// PutSequenced with SeqIgnore is the same as Put.
	// On success any preexisting data will no longer be available using
	// the name, although it may still exist in the storage server. (See
	// the documentation for Delete.) Like Get, it is not the usual
	// access method. The file-like API is preferred.
	//
	// A successful PutSequenced returns an incomplete DirEntry (see the
	// description of AttrIncomplete) containing only the
	// new sequence number.
	PutSequenced(name PathName, seq int64, data []byte) (*DirEntry, error)

	// PutLink creates a link from the new name to the old name. The
	// new name must not look like the path to an Access or Group file.
	// If something is already stored with the new name, it is first
	// deleted from the directory but its storage is not deleted from
	// the Store. (See the documentation for Delete.) The old name is
	// not evaluated, that is, the resulting link will hold the
	// argument to PutLink even if it refers to a path that itself
	// contains links. The name is canonicalized, however (see
	// path.Clean).
	//
	// A successful PutLink returns an incomplete DirEntry (see the
	// description of AttrIncomplete) containing only the
	// new sequence number.
	PutLink(oldName, newName PathName) (*DirEntry, error)

	// PutDuplicate creates a new name for the references referred to
	// by the old name. Subsequent Puts to either name do not effect
	// the contents referred to by the other. There must be no existing
	// item with the new name. If the final element of the path name
	// is a link, PutDuplicate will duplicate the link and not the
	// link target.
	//
	// A successful PutDuplicate returns an incomplete DirEntry (see the
	// description of AttrIncomplete) containing only the
	// new sequence number.
	PutDuplicate(oldName, newName PathName) (*DirEntry, error)

	// MakeDirectory creates a directory with the given name, which
	// must not already exist. All but the last element of the path
	// name must already exist and be directories.
	//
	// A successful MakeDirectory returns an incomplete DirEntry (see the
	// description of AttrIncomplete) containing only the
	// new sequence number.
	MakeDirectory(dirName PathName) (*DirEntry, error)

	// Rename renames oldName to newName. The old name is no longer valid.
	// If the final element of the path name is a link, Rename will
	// Rename the link itself, not the link target.
	//
	// A successful Rename returns an incomplete DirEntry (see the
	// description of AttrIncomplete) containing only the
	// new sequence number.
	Rename(oldName, newName PathName) (*DirEntry, error)

	// SetTime sets the time in name's DirEntry. If the final element
	// of the path name is a link, SetTime will affect the link itself,
	// not the link target.
	SetTime(name PathName, t Time) error

	// Delete deletes the DirEntry associated with the name. The
	// storage referenced by the DirEntry is not deleted,
	// although the storage server may garbage collect unreferenced
	// data independently. If the final element of the path name is a
	// link, Delete will delete the link itself, not the link target.
	Delete(name PathName) error

	// Glob matches the pattern against the file names of the full
	// rooted tree. That is, the pattern must look like a full path
	// name, but elements of the path may contain metacharacters.
	// Matching is done using Go's path.Match elementwise. The user
	// name must be present in the pattern and is treated as a literal
	// even if it contains metacharacters. Note that if links are
	// evaluated while executing Glob, the Name fields of the returned
	// DirEntries might not match the original argument pattern.
	Glob(pattern string) ([]*DirEntry, error)

	// Open and Create are file-like methods similar to Go's os.File API.
	// The name, however, is a fully-qualified upspin PathName.
	Create(name PathName) (File, error)
	Open(name PathName) (File, error)

	// DirServer returns an error or a reachable bound DirServer for the user.
	DirServer(name PathName) (DirServer, error)
}

type Config interface {
	// The name of the user requesting access.
	UserName() UserName

	// Factotum holds the user's cryptographic keys and encapsulates crypto operations.
	Factotum() Factotum

	// Packing is the Packing to use when creating new data items, although
	// it may be overridden by the implementation, such as to use a cleartext
	// packing for a globally readable ("read:all")  file.
	Packing() Packing

	// KeyEndpoint is the endpoint of the KeyServer to contact to retrieve keys.
	KeyEndpoint() Endpoint

	// DirEndpoint is the endpoint of the DirServer in which to place new data items. It is
	// usually the location of the user's root.
	DirEndpoint() Endpoint

	// StoreEndpoint is the endpoint of the StoreServer in which to place new data items.
	StoreEndpoint() Endpoint

	// CacheEndpoint is the endpoint of the cache server between the client and the StoreServer and DirServers.
	CacheEndpoint() Endpoint

	// Value returns the value for the given configuration key.
	Value(key string) string
}

type DEHash []byte

type Dialer interface {
	// Dial connects to the service and performs any needed authentication.
	Dial(Config, Endpoint) (Service, error)
}

type DirBlock struct {
	Location Location // Location of data in store.
	Offset   int64    // Byte offset of start of block's data in file.
	Size     int64    // Length of block data in bytes.
	Packdata []byte   // Information maintained by the packing algorithm.
}

type DirEntry struct {
	// Fields contributing to the signature.
	SignedName PathName   // The full path name of the file used for signing.
	Link       PathName   // The link target, iff the DirEntry has Attr=AttrLink.
	Attr       Attribute  // Attributes for the DirEntry.
	Packing    Packing    // Packing used for every block in file.
	Time       Time       // Time associated with file; might be when it was last written.
	Blocks     []DirBlock // Descriptors for each block. A nil or empty slice represents an empty file.
	Packdata   []byte     // Information maintained by the packing algorithm.

	// Field determining the key used for the signature, hence also tamper-resistant.
	Writer UserName // Writer of the file, often the same as owner.

	// Fields not included in the signature.
	Name     PathName // The full path name of the file. Only the last element can be a link.
	Sequence int64    // The sequence (version) number of the item.
}

type DirServer interface {
	Dialer
	Service

	// Lookup returns the directory entry for the named file.
	//
	// If the returned error is ErrFollowLink, the caller should
	// retry the operation as outlined in the description for
	// ErrFollowLink. Otherwise in the case of error the
	// returned DirEntry will be nil.
	Lookup(name PathName) (*DirEntry, error)

	// Put stores the DirEntry in the directory server. The entry
	// may be a plain file, a link, or a directory. (Only one of
	// these attributes may be set.)
	// In practice the data for the file should be stored in
	// a StoreServer as specified by the blocks in the entry,
	// all of which should be stored with the same packing.
	//
	// Within the DirEntry, several fields have special properties.
	// Time represents a timestamp for the item. It is advisory only
	// but is included in the packing signature and so should usually
	// be set to a non-zero value.
	//
	// Sequence represents a sequence number that is incremented
	// after each Put. If it is neither 0 nor -1, the DirServer will
	// reject the Put operation if the file does not exist or, for an
	// existing item, if the Sequence is not the same as that
	// stored in the metadata. If it is -1, Put will fail if there
	// is already an item with that name.
	//
	// The Name field of the DirEntry identifies where in the directory
	// tree the entry belongs. The SignedName field, which usually has the
	// same value, is the name used to sign the DirEntry to guarantee its
	// security. They may differ if an entry appears in multiple locations,
	// such as in its original location plus within a second tree holding
	// a snapshot of the original tree but starting from a different root.
	//
	// Most software will concern itself only with the Name field unless
	// generating or validating the entry's signature.
	//
	// All but the last element of the path name must already exist
	// and be directories or links. The final element, if it exists,
	// must not be a directory. If something is already stored under
	// the path, the new location and packdata replace the old.
	//
	// If the returned error is ErrFollowLink, the caller should
	// retry the operation as outlined in the description for
	// ErrFollowLink (with the added step of updating the
	// Name field of the argument DirEntry). For any other error,
	// the return DirEntry will be nil.
	//
	// A successful Put returns an incomplete DirEntry (see the
	// description of AttrIncomplete) containing only the
	// new sequence number.
	Put(entry *DirEntry) (*DirEntry, error)

	// Glob matches the pattern against the file names of the full
	// rooted tree. That is, the pattern must look like a full path
	// name, but elements of the path may contain metacharacters.
	// Matching is done using Go's path.Match elementwise. The user
	// name must be present in the pattern and is treated as a literal
	// even if it contains metacharacters.
	// If the caller has no read permission for the items named in the
	// DirEntries, the returned Location and Packdata fields are cleared.
	//
	// If the returned error is ErrFollowLink, one or more of the
	// returned DirEntries is a link (the others are completely
	// evaluated). The caller should retry the operation for those
	// DirEntries as outlined in the description for ErrFollowLink,
	// updating the pattern as appropriate. Note that any returned
	// links may only partially match the original argument pattern.
	//
	// If the pattern evaluates to one or more name that identifies
	// a link, the DirEntry for the link is returned, not the target.
	// This is analogous to passing false as the second argument
	// to Client.Lookup.
	Glob(pattern string) ([]*DirEntry, error)

	// Delete deletes the DirEntry for a name from the directory service.
	// It does not delete the data it references; use StoreServer.Delete
	// for that. If the name identifies a link, Delete will delete the
	// link itself, not its target.
	//
	// If the returned error is ErrFollowLink, the caller should
	// retry the operation as outlined in the description for
	// ErrFollowLink. (And in that case, the DirEntry will never
	// represent the full path name of the argument.) Otherwise, the
	// returned DirEntry will be nil whether the operation succeeded
	// or not.
	Delete(name PathName) (*DirEntry, error)

	// WhichAccess returns the DirEntry of the Access file that is
	// responsible for the access rights defined for the named item.
	// WhichAccess requires that the calling user have at least one access
	// right granted for the argument name. If not, WhichAccess will return
	// a "does not exist" error, even if the item and/or the Access file
	// exist.
	//
	// If the returned error is ErrFollowLink, the caller should
	// retry the operation as outlined in the description for
	// ErrFollowLink. Otherwise, in the case of error the returned
	// DirEntry will be nil.
	WhichAccess(name PathName) (*DirEntry, error)

	// Watch returns a channel of Events that describe operations that
	// affect the specified path and any of its descendants, beginning
	// at the specified sequence number for the corresponding user root.
	//
	// If sequence is 0, all events known to the DirServer are sent.
	//
	// If sequence is WatchCurrent, the server first sends a sequence
	// of events describing the entire tree rooted at name. The Events are
	// sent in sequence such that a directory is sent before its contents.
	// After the full tree has been sent, the operation proceeds as normal.
	//
	// If sequence is WatchNew, the server sends only new events.
	//
	// If the sequence is otherwise invalid, this is reported by the
	// server sending a single event with a non-nil Error field with
	// Kind=errors.Invalid. The events channel is then closed.
	//
	// When the provided done channel is closed the event channel
	// is closed by the server.
	//
	// To receive an event for a given path under name, the caller must have
	// one or more of the Upspin access rights to that path. Events for
	// which the caller does not have enough rights to watch will not be
	// sent. If the caller has rights but not Read, the entry will be
	// present but incomplete (see the description of AttrIncomplete). If
	// the name does not exist, Watch will succeed and report events if and
	// when it is created.
	//
	// If the caller does not consume events in a timely fashion
	// the server will close the event channel.
	//
	// If this server does not support this method it returns
	// ErrNotSupported.
	//
	// The only errors returned by the Watch method itself are
	// to report that the name is invalid or refers to a non-existent
	// root, or that the operation is not supported.
	Watch(name PathName, sequence int64, done <-chan struct{}) (<-chan Event, error)
}

type Endpoint struct {
	// Transport specifies how the network address is to be interpreted,
	// for instance that it is the URL of an HTTP service.
	Transport Transport

	// NetAddr returns the (typically) network address of the data.
	NetAddr NetAddr
}

type Event struct {
	// Entry is the DirEntry to which the event pertains. Its Sequence
	// field captures the ordering of events for this user.
	Entry *DirEntry

	// Delete is true only if the entry is being deleted;
	// otherwise it is being created or modified.
	Delete bool

	// Error is non-nil if an error occurred while waiting for events.
	// In that case, all other fields are zero.
	Error error
}

type Factotum interface {
	// DirEntryHash is a summary used in signing and verifying directory entries.
	DirEntryHash(n, l PathName, a Attribute, p Packing, t Time, dkey, hash []byte) DEHash

	// FileSign ECDSA-signs DirEntry fields and, in some packings, file contents.
	FileSign(hash DEHash) (Signature, error)

	// ScalarMult is the bare private key operator, used in unwrapping packed data.
	// Each call needs security review to ensure it cannot be abused as a signing
	// oracle. Read https://en.wikipedia.org/wiki/Confused_deputy_problem.
	ScalarMult(keyHash []byte, c elliptic.Curve, x, y *big.Int) (sx, sy *big.Int, err error)

	// Sign signs a slice of bytes with the factotum's private key.
	// The argument hash should be a cryptographic hash of the message you want to sign,
	// no longer than your key's curve order. Don't use without a security consult.
	Sign(hash []byte) (Signature, error)

	// HKDF cryptographically mixes salt, info, and the Factotum secret and
	// writes the result to out, which may be of any length but is typically
	// 8 or 16 bytes. The result is unguessable without the secret, and does
	// not leak the secret. For more information, see package
	// golang.org/x/crypto/hkdf.
	HKDF(salt, info, out []byte) error

	// Pop derives a Factotum that defaults to the previous key.
	Pop() Factotum

	// PublicKey returns the user's public key in canonical string format.
	PublicKey() PublicKey

	// PublicKeyFromHash returns the matching public key or an error.
	PublicKeyFromHash(keyHash []byte) (PublicKey, error)
}

type File interface {
	// Close releases the resources. For a writable file, it also
	// writes the accumulated data in a StoreServer. After a
	// Close, successful or not, all methods of File except Name
	// will fail.
	Close() error

	// Name returns the full path name of the File.
	Name() PathName

	// Read, ReadAt, Write, WriteAt and Seek implement
	// the standard Go interfaces io.Reader, etc.
	// Because of the nature of Upspin storage, the entire
	// item might need to be read into memory by the
	// implementation before Read can return any data.
	// Similarly, Write might accumulate all data and only
	// flush to storage once Close is called.
	Read(b []byte) (n int, err error)
	ReadAt(b []byte, off int64) (n int, err error)
	Write(b []byte) (n int, err error)
	WriteAt(b []byte, off int64) (n int, err error)
	Seek(offset int64, whence int) (ret int64, err error)
}

type KeyServer interface {
	Dialer
	Service

	// Lookup returns all public information about a user.
	Lookup(userName UserName) (*User, error)

	// Put sets or updates information about a user. The user's name must
	// match the authenticated user. The call can update any field except
	// the user name.
	// To add new users, see the signup subcommand of cmd/upspin.
	Put(user *User) error
}

type ListRefsItem struct {
	// Ref holds the reference name.
	Ref Reference
	// Size the length of the reference data.
	Size int64
}

type ListRefsResponse struct {
	// Refs holds the reference information.
	Refs []ListRefsItem
	// Next holds the token to fetch the next page,
	// or the empty string if this is the last page.
	Next string
}

type Location struct {
	// Endpoint identifies the machine or service where the data resides.
	Endpoint Endpoint

	// Reference is the key that will retrieve the data from the endpoint.
	Reference Reference
}

type NetAddr string

type Packer interface {
	// Packing returns the integer identifier of this Packing algorithm.
	Packing() Packing

	// String returns the name of this packer.
	String() string

	// Pack returns a BlockPacker that packs blocks
	// into the given DirEntry.
	Pack(Config, *DirEntry) (BlockPacker, error)

	// Unpack returns a BlockUnpacker that unpacks blocks
	// from the given DirEntry.
	Unpack(Config, *DirEntry) (BlockUnpacker, error)

	// PackLen returns an upper bound on the number of bytes required
	// to store the cleartext after packing.
	// PackLen might update the entry's Packdata field.
	// PackLen returns -1 if there is an error.
	PackLen(config Config, cleartext []byte, entry *DirEntry) int

	// UnpackLen returns an upper bound on the number of bytes
	// required to store the unpacked cleartext.
	// UnpackLen might update the entry's Packdata field.
	// UnpackLen returns -1 if there is an error.
	UnpackLen(config Config, ciphertext []byte, entry *DirEntry) int

	// ReaderHashes returns SHA-256 hashes of the public keys able to decrypt the
	// associated ciphertext.
	ReaderHashes(packdata []byte) ([][]byte, error)

	// Share updates each packdata element to enable all the readers,
	// and only those readers, to be able to decrypt the associated ciphertext,
	// which is held separate from this call. It is used to repair incorrect
	// key wrapping after access rights are changed.
	// In case of error, Share skips processing for that reader or packdata.
	// If packdata[i] is nil on return, it was skipped.
	// Share trusts the caller to check the arguments are not malicious.
	// To enable all Upspin users to decrypt the ciphertext, include
	// AllReadersKey among the provided reader keys.
	//
	// TODO: It would be nice if DirServer provided a method to report
	// which items need updates, so this could be automated.
	Share(config Config, readers []PublicKey, packdata []*[]byte)

	// Name updates the DirEntry to refer to a new path. If the new
	// path is in a different directory, the wrapped keys are reduced to
	// only that of the Upspin user invoking the method. The Packdata
	// in entry must contain a wrapped key for that user.
	Name(config Config, entry *DirEntry, path PathName) error

	// SetTime changes the Time field in a DirEntry and recomputes
	// its signature.
	SetTime(config Config, entry *DirEntry, time Time) error

	// Countersign updates the signatures in the DirEntry when a writer
	// is in the process of switching to a new key. It checks that
	// the first existing signature verifies under the old key, copies
	// that one over the second existing signature, and creates a new
	// first signature using the key from factotum.
	Countersign(oldKey PublicKey, f Factotum, d *DirEntry) error

	// UnpackableByAll reports whether the packed data may be unpacked by
	// all Upspin users. Access and Group files must have this property, as
	// should any files for which access.AllUsers have the read permission.
	UnpackableByAll(d *DirEntry) (bool, error)
}

type Packing uint8

type PathName string

type PublicKey string

type Refdata struct {
	Reference Reference     // The reference itself.
	Volatile  bool          // If true, the data might change on every Get and cannot be cached.
	Duration  time.Duration // For non-volatile data, the predicted cacheable lifetime; 0 means forever.
}

type Reference string

type Service interface {
	// Endpoint returns the network endpoint of the server.
	Endpoint() Endpoint

	// Close closes the connection to the service and releases all resources used.
	// A Service may not be re-used after close.
	Close()
}

type Signature struct {
	R, S *big.Int
}

type StoreServer interface {
	Dialer
	Service

	// Get attempts to retrieve the data identified by the reference.
	// Three things might happen:
	// 1. The data is in this StoreServer. It is returned. The Location slice
	// and error are nil. Refdata contains information about the data.
	// 2. The data is not in this StoreServer, but may be in one or more
	// other locations known to the store. The slice of Locations
	// is returned. The data, Refdata, Locations, and error are nil.
	// 3. An error occurs. The data, Locations and Refdata are nil
	// and the error describes the problem.
	Get(ref Reference) ([]byte, *Refdata, []Location, error)

	// Put puts the data into the store and returns the reference
	// to be used to retrieve it.
	Put(data []byte) (*Refdata, error)

	// Delete permanently removes all storage space associated
	// with the reference. After a successful Delete, calls to Get with the
	// same reference will fail. If the reference is not found, an error is
	// returned. Implementations may disable this method except for
	// privileged users.
	Delete(ref Reference) error
}

type Time int64

type Transport uint8

type User struct {
	// Name represents the user's name as an e-mail address, such as ann@example.com.
	Name UserName

	// Dirs is a slice of DirServer endpoints where the user's root directory may be located,
	// which should be contacted in order when trying to access the user's tree. Multiple
	// entries represent mirrors, which are as yet unimplemented. TODO.
	Dirs []Endpoint

	// Stores is a slice of StoreServer endpoints where the user's data is primarily written to,
	// which should be contacted in order when trying to access the user's data. Multiple
	// entries represent mirrors, which are as yet unimplemented. TODO.
	Stores []Endpoint

	// PublicKey is the user's current public key.
	PublicKey PublicKey
}

type UserName string