From 3efc800f3f33409e4ad856bc91e83d3325fd0cb0 Mon Sep 17 00:00:00 2001
From: Sam Hadow <sam.hadow@inbox.lv>
Date: Wed, 12 Mar 2025 16:19:55 +0100
Subject: [PATCH] readme update

---
 readme.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/readme.md b/readme.md
index e69de29..fc0e5d1 100644
--- a/readme.md
+++ b/readme.md
@@ -0,0 +1,48 @@
+## What is this repository?
+E2EE client-server messaging app proof of concept. 
++ Accounts are identified by an [Ed25519](https://ed25519.cr.yp.to/) public key.
++ Login using the private key to solve a cryptographic challenge in the browser.
++ [Ascon](https://ascon.isec.tugraz.at/specification.html) inspired AEAD using [Keccak sponge construction](https://keccak.team/sponge_duplex.html) in the browser.
++ Diffie Hellman key exchange using [X25519](https://datatracker.ietf.org/doc/html/rfc8032) to establish a new shared secret every 5 messages sent.
++ Shared secret derived in 2 secrets using Keccak sponge construction. These secrets are then used in a sending ratchet and a receiving ratchet used to derive encryption keys similar to [Signal protocol](https://signal.org/docs/specifications/doubleratchet/)
+
+
+## how to build and run the app:
+### using the makefile:
+(add a volume in the command creating the database container if you need data persistency)
+```
+make
+```
+### manually:
+##### build
+```
+podman build -t e2ee-messaging-service .
+```
+##### run
+```
+podman pod create --name=e2ee -p 3333:3333
+podman run -d --pod=e2ee \
+-e POSTGRES_PASSWORD="password" \
+-e POSTGRES_DB="e2ee" \
+-e POSTGRES_USER="e2ee" \
+-e POSTGRES_INITDB_ARGS="--encoding=UTF-8 --lc-collate=C --lc-ctype=C" \
+-v /PATH/TO/DB:/var/lib/postgresql/data:Z \
+--name=e2ee-db docker.io/library/postgres:16
+podman run -d --pod=e2ee \
+-e POSTGRES_PASSWORD="password" \
+-e POSTGRES_DB="e2ee" \
+-e POSTGRES_USER="e2ee" \
+-e SHARED_SECRET="change-me" \
+--name=e2ee-app e2ee-messaging-service:latest
+```
+notes: 
+1) You can use docker instead of podman provided the e2ee nodejs app can communicate with the database with a network or changing the POSTGRES_HOST env variable accordingly.   
+2) You can use [podman secrets](https://docs.podman.io/en/latest/markdown/podman-secret.1.html) instead of writing your secrets in configuration files.   
+
+## unit tests
+```
+npm test
+```
+
+note:
+1) The makefile automatically runs the unit tests before building the container.