<commit_before>package upspin

// A UserName is just a string representing a user.
// It is given a unique type so the API is clear.
// Example: <EMAIL>
type UserName string

// A PathName is just a string representing a full path name.
// It is given a unique type so the API is clear.
// Example: <EMAIL>/burrow/hoard
type PathName string

// Transport identifies the type of access required to reach the data, that is, the
// realm in which the network address within a Location is to be interpreted.
type Transport uint8

const (
	// InProcess indicates that contents are located in the current process,
	// typically in memory.
	InProcess Transport = iota

	// GCP indicates a Google Cloud Store instance.
	GCP

	// HTTP is a URL-encoded address.
	HTTP
)

// A Location identifies where a piece of data is stored and how to retrieve it.
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
}

// An Endpoint identifies an instance of a service, encompassing an address
// such as a domain name and information (the Transport) about how to interpret
// that address.
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
}

// A NetAddr is the network address of service. It is interpreted by Access's
// Dial method to connect to the service.
type NetAddr string

// A Reference is the key to find a piece of data in a given Store. It is decoupled
// from the address of the Store itself, but contains a unique identifier key
// such as a hash of the contents and a Packing defining how to unpack it.
type Reference struct {
	// Key identifies the data within the Store.
	Key string

	// Packing identifies how to unpack the original data using this Reference.
	Packing Packing
}

// A Packing identifies the technique for turning the data pointed to by
// a Reference into the user's data. This may involve checksum verification,
// decrypting, signature checking, or nothing at all.
// Secondary data such as encryption keys may be required to implement
// the packing. That data appears in the API as arguments and struct fields
// called packdata.
type Packing uint8

// Packer provides the implementation of a Packing. The pack package binds
// Packing values to the concrete implementations of this interface.
type Packer interface {
	// Packing returns the integer identifier of this Packing algorithm.
	Packing() Packing

	// Pack takes cleartext data, metadata and path name and
	// stores the ciphertext encoding in the supplied slice.
	// The ciphertext and cleartext slices must not overlap.
	// Pack might update the metadata.
	// The slice must be large enough; the PackLen method may be used to
	// find a suitable allocation size.
	// The returned count is the length of the ciphertext.
	Pack(context *Context, ciphertext, cleartext []byte, meta *Metadata, name PathName) (int, error)

	// Unpack takes ciphertext data and packing metadata and stores the
	// cleartext version in the supplied slice, which must be large enough.
	// The ciphertext and cleartext slices must not overlap.
	// Unpack might update the metadata.
	// It returns the path name and the number of bytes written to the slice.
	// The returned name will be empty if the ciphertext does not contain one.
	Unpack(context *Context, cleartext, ciphertext []byte, meta *Metadata, name PathName) (int, error)

	// PackLen returns an upper bound on the number of bytes required
	// to store the cleartext after packing. It might update the metadata.
	// Returns -1 if there is an error.
	PackLen(context *Context, cleartext []byte, meta *Metadata, name PathName) int

	// UnpackLen returns an upper bound on the number of bytes required
	// to store the unpacked cleartext. It might update the metadata.
	// Returns -1 if there is an error.
	UnpackLen(context *Context, ciphertext []byte, meta *Metadata) int
}

const (
	// The DebugPack packing is available for use in tests for any purpose.
	// It is never used in production.
	DebugPack Packing = iota

	// UnsafePack is an obfuscating packing that is
	// cryptographically unsound. It is similar to DebugPack, but
	// updates the metadata with wrapped keys and signs
	// messages. It should never be used in production.
	UnsafePack

	// PlainPack is the trivial, no-op packing. Bytes are copied untouched.
	PlainPack

	// EEp256Pack and EEp521Pack store AES-encrypted data, with metadata
	// including an ECDSA signature and ECDH-wrapped keys.
	// EEp256Pack packing uses AES-128, SHA-256, and curve P256.
	EEp256Pack
	// EEp521Pack packing uses AES-256, SHA-512, and curve P521.
	EEp521Pack
)

// User service.

// The User interface provides access to public information about users.
type User interface {
	Access

	// Lookup returns a list (slice) of Endpoints of Directory
	// services that may hold the root directory for the named
	// user and a list (slice) of public keys for that user. Those
	// earlier in the lists are better places to look.
	Lookup(userName UserName) ([]Endpoint, []PublicKey, error)
}

// A PublicKey is used when exchanging data with other users.
type PublicKey []byte
<commit_msg>upspin: lock down values for Packing<commit_after>package upspin

// A UserName is just a string representing a user.
// It is given a unique type so the API is clear.
// Example: <EMAIL>
type UserName string

// A PathName is just a string representing a full path name.
// It is given a unique type so the API is clear.
// Example: <EMAIL>/burrow/hoard
type PathName string

// Transport identifies the type of access required to reach the data, that is, the
// realm in which the network address within a Location is to be interpreted.
type Transport uint8

const (
	// InProcess indicates that contents are located in the current process,
	// typically in memory.
	InProcess Transport = iota

	// GCP indicates a Google Cloud Store instance.
	GCP

	// HTTP is a URL-encoded address.
	HTTP
)

// A Location identifies where a piece of data is stored and how to retrieve it.
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
}

// An Endpoint identifies an instance of a service, encompassing an address
// such as a domain name and information (the Transport) about how to interpret
// that address.
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
}

// A NetAddr is the network address of service. It is interpreted by Access's
// Dial method to connect to the service.
type NetAddr string

// A Reference is the key to find a piece of data in a given Store. It is decoupled
// from the address of the Store itself, but contains a unique identifier key
// such as a hash of the contents and a Packing defining how to unpack it.
type Reference struct {
	// Key identifies the data within the Store.
	Key string

	// Packing identifies how to unpack the original data using this Reference.
	Packing Packing
}

// A Packing identifies the technique for turning the data pointed to by
// a Reference into the user's data. This may involve checksum verification,
// decrypting, signature checking, or nothing at all.
// Secondary data such as encryption keys may be required to implement
// the packing. That data appears in the API as arguments and struct fields
// called packdata.
type Packing uint8

// Packer provides the implementation of a Packing. The pack package binds
// Packing values to the concrete implementations of this interface.
type Packer interface {
	// Packing returns the integer identifier of this Packing algorithm.
	Packing() Packing

	// Pack takes cleartext data, metadata and path name and
	// stores the ciphertext encoding in the supplied slice.
	// The ciphertext and cleartext slices must not overlap.
	// Pack might update the metadata.
	// The slice must be large enough; the PackLen method may be used to
	// find a suitable allocation size.
	// The returned count is the length of the ciphertext.
	Pack(context *Context, ciphertext, cleartext []byte, meta *Metadata, name PathName) (int, error)

	// Unpack takes ciphertext data and packing metadata and stores the
	// cleartext version in the supplied slice, which must be large enough.
	// The ciphertext and cleartext slices must not overlap.
	// Unpack might update the metadata.
	// It returns the path name and the number of bytes written to the slice.
	// The returned name will be empty if the ciphertext does not contain one.
	Unpack(context *Context, cleartext, ciphertext []byte, meta *Metadata, name PathName) (int, error)

	// PackLen returns an upper bound on the number of bytes required
	// to store the cleartext after packing. It might update the metadata.
	// Returns -1 if there is an error.
	PackLen(context *Context, cleartext []byte, meta *Metadata, name PathName) int

	// UnpackLen returns an upper bound on the number of bytes required
	// to store the unpacked cleartext. It might update the metadata.
	// Returns -1 if there is an error.
	UnpackLen(context *Context, ciphertext []byte, meta *Metadata) int
}

const (
	// PlainPack is the trivial, no-op packing. Bytes are copied untouched.
	// It is the default packing but is, of course, insecure.
	PlainPack = 0

	// Packings from 1 through 16 are not for production use. This region
	// is reserved for debugging and other temporary packing implementations.

	// The DebugPack packing is available for use in tests for any purpose.
	// It is never used in production.
	DebugPack Packing = 1

	// UnsafePack is an obfuscating packing that is
	// cryptographically unsound. It is similar to DebugPack, but
	// updates the metadata with wrapped keys and signs
	// messages. It should never be used in production.
	UnsafePack = 2

	// Packings from 16 and above (as well as PlainPack=0) are fixed in
	// value and semantics and may be used in production.

	// EEp256Pack and EEp521Pack store AES-encrypted data, with metadata
	// including an ECDSA signature and ECDH-wrapped keys.
	// EEp256Pack packing uses AES-128, SHA-256, and curve P256.
	EEp256Pack = 16
	// EEp521Pack packing uses AES-256, SHA-512, and curve P521.
	EEp521Pack = 17
)

// User service.

// The User interface provides access to public information about users.
type User interface {
	Access

	// Lookup returns a list (slice) of Endpoints of Directory
	// services that may hold the root directory for the named
	// user and a list (slice) of public keys for that user. Those
	// earlier in the lists are better places to look.
	Lookup(userName UserName) ([]Endpoint, []PublicKey, error)
}

// A PublicKey is used when exchanging data with other users.
type PublicKey []byte

{'fraction_non_alphanumeric': 0.06100724572859827, 'fraction_numerical': 0.008319169872081582, 'mean_word_length': 3.500805152979066, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1152913', 'n_tokens_mistral': 3048, 'n_tokens_neox': 2883, 'n_words': 1649}