## Vaults

A vault is a file containing encrypted secrets. It is split 
into a header containing information about the encoding and 
cipher algorithm as well as a *name* (which is unencrypted). 
Vault identifiers are UUID v4.

The file format is designed to be easy to manipulate via random 
access seeking so that secrets can be inserted, updated and 
deleted efficiently.

In the header of a vault file is a summary which contains the vault 
name, identifier, cipher, and other information. It could be 
considered to be a *pointer* to a vault.

Some vaults are considered to be special and are marked with 
bit flags to indicate these properties, some examples:

* Default vault, the primary vault for an account
* Archive vault , archived secrets can be moved here
* Contacts vault, a vault just for contacts
* Authenticator, vault for 2FA secrets (TOTP)

## Event Log

An event log is an alternative representation of a vault which  
is an append-only file for events, an in-memory merkle tree 
keeps track of the *commits* to the event log.

The primary purpose of the event log is to allow efficient 
syncing of vaults between different devices.

Event logs can be *reduced* to a vault file and a vault file 
can be *split* into an event log.

Over time an event log may grow very large or the owner may wish 
to discard deleted and old versions of edited secrets so an event 
log can be *compacted* to a sequence of events that will match 
the data in the corresponding vault file but discard the history. 
The process of compaction rewrites the entire merkle tree for the 
event log so is a very destructive operation from the point of view 
of syncing between devices as the merkle trees on the different 
devices will have completely diverged.

If the password of a vault is changed the entire event log 
(and therefore merkle tree) needs to be rewritten.

In the case of *compaction* or a change in password for a 
vault great care must be taken to ensure the new data can 
be synced at the same time.

Assuming an event log has not been rewritten then it also 
allows an owner to *time travel* to an earlier point in the 
history and recover deleted or edited secrets.

See the [sync docs](/doc/sync.md) for more information 
on event logs.

## Folder

Folder is the term used to refer to the combined vault and event 
log files which represent the entirety of the data required 
for a collection of secrets.

## Signing Key

The account signing key is an ECDSA (Secp256k1 curve) private 
key used to uniquely identify an account and verify account 
ownership by signing requests to a remote service.

## Account Address

An account address is an Ethereum-style address derived from 
the public key of the account signing key used to uniquely 
identify an account. An account address is used as the identifier 
so that remote servers (used for syncing data) can allow account 
creation and modification without requiring any sign-up which 
may expose personally identifiable information (PII) to the server.

## Identity Vault

The identity vault is a special kind of vault whose purpose is 
to protect the account signing key, provide a single password 
account sign in flow and to store delegated passwords. 
Delegated passwords are passwords for other folders managed 
by the account owner.

## Primary Password

The primary password is the password used to unlock the identity 
vault granting access to an account.

## Device Vault

The device vault contains the signing key that identifies a single 
device and a collection of other trusted devices.

A trusted device contains meta data about a device (operating system, 
hostname, hardware information etc) that allows the owner to easily 
identify the device and the public key of the device's signing key.

The device vault must never leave that device.

Device vaults are not included in backup archives, they are lazily 
created when an account owner signs in so after restoring from a 
backup archive a new device signing key would be created and the 
account owner would need to pair with other devices to add them 
to the collection of trusted devices again.

## Cloud Account

A cloud account refers to a paid subscription to a cloud-hosted 
syncing service.

## Recovery Group

A recovery group is a collection of participants that have been 
allocated shares in the private key used for social recovery. Members 
of a recovery group may or may not be subscribers to a cloud account.

## Recovery Pack

A recovery pack is a mapping of vault identifiers (UUID v4) to 
the password for the corresponding vault. This is the map that 
will be encrypted during social recovery group creation.

The recovery pack must be encrypted using a secret only known to 
the account owner, afterwards it can be sent to a trusted 
third-party service for long-term storage.

The owner can then split the private key used to encrypt the 
recovery pack and distribute it to members of the recovery group. 

## Executor

The executor is a member of the recovery group that is authorized to 
perform the final decryption of the account owner's data.

See SOCIAL-RECOVERY.md for more information on the social recovery protocol.

## Files

Files can be *internal* (embedded in a folder) or *external* which 
encrypts the file data and stores it in a location determined by convention.

The convention for file storage is the vault identifier followed by the secret identifier and then the SHA256 hash of the encrypted file data.

Internal files are considered legacy and  *not recommended* as they 
increase the size of folders and have negative performance implications.

Support for internal files may be removed in the future so use with caution.

## User Data

User data is optional additional data that can be assigned to a secret, for example, a user might add a comment to the user data to give additional instructions to a recovery group on how to use a secret.

## Custom Fields

Custom fields are additional fields that can be assigned to the *user data* for a secret. They allow end users to manage additional data assigned to a secret adding flexibility to the shape of secret data.

Custom fields are implemented as nested secrets so whilst it is technically possible to nest custom fields it it not recommended.

It is possible to use any secret type for a custom field but that may be overwhelming from a user experience point of view so we recommend restricting the types available to custom fields, for example, limiting custom fields to notes, links, passwords and files gives a lot of flexibility without offering too many choices.

Some secret types such as *Link* and *Password* are intended to only be used in custom fields.

At the moment custom fields are not included in the search index, we may change this later.
