coffer/Design.org

* Communication
** Frame 
   Header ::: content-length: u16 | message-type: u8 ::: 3 byte, fixed
   Body   ::: content: [u8; content-length]          ::: conent-length byte, variable

   Unsigned integers in network byte order.

** Message Types
   
   | Ordinal | Type        | Body Format     | Direction | Transitions              | Description                               |
   |---------+-------------+-----------------+-----------+--------------------------+-------------------------------------------|
   |    0x00 | Hello       | Client PK       | C -> S    | Link, KeyNotFound, Error | Initiates communication                   |
   |    0x01 | Link        | <empty>         | S -> C    | Get, Bye                 | Link established, communication can start |
   |    0x02 | Get         | <empt>          | C -> S    | OkGet, Error             | Retrieve a secrets for the client         |
   |    0x03 | OkGet       | Coffer (sealed) | S -> C    | Bye                      | Send secrets to the client                |
   |    0x99 | Bye         | Client PK       | C -> S    | •                        | Close connection                          |
   |    0xaa | KeyNotFound | Client PK       | S -> C    | •                        | PK unknown to server                      |
   |    0xff | Error       | UTF-8 String    | S -> C    | •                        | Generic server error with reason          |

   - Seal is determined by communication direction:
     C -> S: sealed by server public key, client private key
     S -> C: sealed by client public key, server private key
   - Secrets returned as sealed cbor

* Coffer
  - Sharded KV-Store
  - Keys are UTF-8 Strings
  - Typed values as defined by TOML: String, Integer, Float, Boolean
    - No Dates support
    - No binary data support
    - Floats and Integers are 32 bit

* Coffer Server
  A ~coffer-server~ can support multiple clients by means of /sharding/ the
  keyspace. Clients are uniquely identified by their public key.
  
  - A client can only access its /shard/ identified by its public key
  - All server responses are sealed by the client's public key and server's
    private key. No secrets can be extracted or communication data collected
    except the private keys are compromised.
  - All server requests are sealed by the server's public and client's private
    key. No tampered requests can be sent or communication data collected except
    the private keys are compromised.

* Coffer Definition (TOML)
  Encrypted Authentication: SK of coffer-companion, PK of coffer-server

  #+BEGIN_SRC yaml
    # IDs (public keys) of clients
    file.id = "AAAA-AAAA-AAAA-AAAA"
    bin.id = "FFFF-FFFF-FFFF-FFFF"

    # Secrets for a named client (defined in clients)
    [file]
    secretkey = "secret value"
    secretkey2 = "secret value2"
  #+END_SRC

* Coffer Response
  Encrypted Authentication: SK of coffer-server, PK of coffer-client
  Format: cbor
  
  CofferResponse = List<CofferSecret>
  
  CofferSecret {
    key: UTF-8 String,
    value: CofferValue
  }

  CofferValue = String | Integer | Float | Boolean | Date