<!-- documentation/security_model - Describes the application's security model. -->

# Share File Systems - Security Model
This document briefly describes some of the various security decisions in place.

## HTTP GET
This application runs an HTTP server to route traffic.  This server only accepts GET type requests from a localhost browser for file assets.  All other GET requests are dropped.

### Browser
A web browser tab running the application will not accept or make HTTP requests to any other location than localhost.

## HTTP POST
All other traffic is passed as HTTP method POST.  Aside from a few exceptions this traffic must originate from a trusted agent or it is dropped.

### Trusted Agents
There are three levels of trusted agents: **device**, **share**, and **user** types.  Each of those three data types are named using a SHA3 512 hash.  In the unlikely case that hash collisions are discovered in this format user hashes are partly derived from the computer that generates them, device hashes partly generates from a user hash, and share hashes are partly generated from their respective device hash.

* *share* - A point of access to a given location on a given device.  Shares can be *full control* but are *read only* by default.
* *device* - These relationships allow interconnections between personal devices owned by the same person.  As such they allow full control access without content restrictions.
* *user* - A different person and their respective devices.  Users expose shares to other users, but not devices.

A user may contain 1 or more devices and each device many contain 0 or more shares.

## Challenges
The trusted agent triple provides some complications for routing data, but suppresses device identification between users.  This prevents direct fingerprinting of users and their content to specific devices.

It also makes security far more convenient for the end user since it is only the click of a single button to delete a share, which is completely non-disruptive for the user owning that share.  Deleting a share eliminates respective access from other users without any reconfiguration.

### Resolving Devices
Since device identifiers are not passed between users a device identifier must be resolved from a share.  This resolution occurs by walking the data model of a local user's devices matching a share hash and thus identifying the device on which that share is stored.  In most file system operations this is simplistic between most file system operations only require a single remote access point.

### Temporary Shares
Shares are used to pass data between devices of the same user since all devices are aware of each other and unrestricted to each other.  This means a must may request to copy files from a user with a share to a local device without a share.  In order for this to occur that remote user must be able to send traffic directly to a device without shares and without any visible identity.

In this case a temporary share is generated by merging there pieces of data to create a 269 character string and hashing it: `userHash + deviceHash + date integer`.  The the date integer used to generate that hash is prefixed to the hash to create a 141 character string to serve as a temporary share.  The temporary share is provided to the remote user so that they may spawn a HTTP client request to the local device within a limited time from the provide date integer.  The local device responds with the desired content if it can reproduce that hash using the provided date number and within an accepted duration after the share id was created.

Please note that date numbers are milliseconds since 1 JAN 1970 and will remain 13 digits until 20 NOV 2286.

### Routing File Copy Between Devices
Cut/copy operations greatly increase operational complexity between as there are one to three agents to consider: the agent on which the user directs the request, the source of files to copy, and the location to write those files.  

* **copy on self** - This most simple operation is to copy/paste files from location of a computer to another location of the same which, which also is the same computer the user is directing that action.  In this case there is only one agent and no traffic must be routed across the network.

* **copy to a different device** - Another scenario is when a user directs the transfer of files either to or from the the local computer to a different *device* type.  In this case two agents are involved, but since all agents are shared as devices a device does not have to be resolved from a share identifier.

* **copy from a second device to a third device** - Slightly more complicated is when a user directs the copy/paste of files from one *device* type to a different *device* type where neither of those are the local computer.  This requires that copy instructions are prepared on a local computer, send to a personal device.  That personal device prepares a list of all contents from the destination and sends the destination that list.  The destination then requests each file and writes them from a HTTP response.  Each time a file is written the status of transfer is broadcast to all devices.  Since all three computers are connected as personal devices of the same user no device identity must be resolved.

### Routing File Copy From Remote User to Personal Devices
All user type connections impose increased complexity.  Copying from a remote user to a personal device does not require a temporary share.  The remote user must have a share available in order for any of my local devices to access that remote user's files.

* **copy from remote user local device to my local device** - The most simple user copy scenario is to send copy instructions to the remote user.  The remote user must have a share available to access the requested files, but it can be read only since nothing is changed in the remote file system.  A file cut operation would require the remote user's share to be *full access*, because it will make a change to the remote file system.  The source device resolved from the remote user's share is the remote user's local device which generates a file list and sends it back to my local computer.  My local computer then requests each file from the generated list.

### Routing File Copy to Remote User From Personal Devices
All copy requests from my personal devices to a remote user will require a temporary share and the remote user's share must be *full access* in order for the remote user to allow writing files.

* **copy from local computer to user's local computer** - First, that distant user must have a share and that share must not be read only or you will not be allowed to write files.  My local computer sends a HTTP request to the remote user's current computer.  If that remote user's share points to a location on the remote user's current computer that remote user does not have to route between personal devices, but it does have to resolve it's local device from a share identifier.

* **copy from different device to user's local computer** - More complex is attempting to copy files to the remote user from a different personal device.  This only requires one additional step of routing that file copy message to the remote device.

* **copy from local device to a different user device** - In this case the file copy instructions must be passed to the remote user who then resolves a device from a share identifier.  Once that device is identified as a different device than the remote user's current computer that remote user's application has to route the instructions to that other device.

* **copy from different device to different user device** - This scenario simply accounts of the prior two scenarios in a single transaction.

* **copy from one user share to a different share of the same user** - This scenario is a bit more complex in that the remote user must resolve two different devices, process the file copy, and at each file write broadcast the status of changes to all local devices owned by that remote user as well as the originating user which will then broadcast it to all it's devices.

### Routing File Copy From a Remote User to a Different Remote User
Routing file copy tasks between two different external users is the most complex of the file copy tasks.  If the two external users are connected to each other the most direct path is for them to exchange instructions directly.  As a third party that remote connection isn't known, so in all cases we will assume the two external users are not aware of each other.  In this case all instructions must be routed through my device initiating the instructions.