Project / Relay
Sharing credentials without giving the server the keys.
Relay is an API for sending passwords and other secrets between users as encrypted messages. The server keeps a directory of public keys and a mailbox of ciphertext, and it is designed so that private keys and plaintext never reach it. The server side is built and tested. The browser client that generates keys and does the encryption is not built yet.
View the code on GitHub- status
- In progress
- server
- Flask REST API, built
- storage
- SQLite via SQLAlchemy
- auth
- JWT, HS256, 8 h expiry
- client
- Not built yet
The problem
Credentials end up sitting in chat history
Passwords, API keys and other secrets get shared over email or chat all the time. They stay there in plaintext, in the message history, on the provider's servers and on every device that synced the conversation.
The obvious fix, a backend that stores the secret and hands it over, moves the problem somewhere else. That backend now holds every secret, and anyone who gets into its database gets all of them. Relay splits the work so the server only handles things that are safe for it to hold:
The server
- Authenticates users
- Publishes each user's public key
- Stores encrypted messages and hands them only to their recipient
The client
- Generates the key pair and keeps the private key
- Encrypts with the recipient's public key before sending
- Decrypts with its own private key after receiving
How Relay works
Six steps from sign-up to decrypted credential
Everything below is taken from the server code. Steps that depend on the unbuilt client are marked as planned.
- 01
Register
POST /auth/register
Name, username, password, phone and email. Field lengths are checked, the password has to be at least 12 characters, and it is stored as a Werkzeug hash. A duplicate account gets a generic error that does not say which field was taken.
- 02
Log in
POST /auth/login
Returns a JWT access token that expires after 8 hours. Every route except register and login requires it as a Bearer token, and a user has one active session at a time: logging in again invalidates the previous token.
- 03
Publish a public key
POST /keys/addKey
The key is checked as a PEM RSA public key of at least 2048 bits and at most 16 KB, then stored as text and returned with a key_uid. A user can publish several keys over time, and the newest one is treated as current.
client, plannedThe client generates the key pair and uploads only the public half.
- 04
Find the recipient
GET /message/sendToPOST /keys/fetchPublicKey
The first route only confirms that a username exists, because Relay does not expose a user directory. The second returns a recipient's newest public key and its key_uid.
- 05
Encrypt and send
POST /message/send
The request carries the recipient, the ciphertext and the key_uid it was encrypted for. The server rejects self-sends and key_uids that do not belong to the recipient, caps the message at 5,000 characters and the recipient inbox at 1,000 stored messages, and stores the ciphertext under a random UUID message_uid.
client, plannedThe client encrypts the credential with the recipient's public key before this request.
- 06
Receive and decrypt
GET /message/inboxPOST /message/getMessageById
The inbox comes back paginated, up to 100 messages per page, newest first, with the sender, ciphertext, key_uid and expiry of each one. Expired messages are purged as the inbox loads, and the recipient can delete any message with POST /message/inbox/deleteMessage.
client, plannedThe client picks the private key matching key_uid and decrypts locally.
Architecture
A key directory and a mailbox
The Flask server moves opaque text around. It validates the format of an uploaded key but never uses it, and key generation, encryption and decryption belong on the client, which is why no private key appears on the server side of the diagram.
Sender's browser planned
- Encrypts with recipient's public key
Own private key stays here
sends password + public key, ciphertext with key_uid
gets JWT, recipient's newest public key + key_uid
Flask API
/authregister, login, logout/keyspublish, list, look up and delete public keys/messagestore, page and deliver ciphertext- JWT, one-session and rate-limit checks on protected routes
sends password, public key
gets JWT, ciphertext + key_uid + sender
Recipient's browser planned
- Decrypts with the key matching key_uid
Own private key stays here
SQLite
userspublic_keysencrypted_messages
Cryptographic model and trust boundary
Public-key encryption, kept on the client
Relay is built around one rule: the server should hold nothing that would be dangerous to leak. What is left is a directory of public keys, a mailbox of ciphertext, and the metadata needed to route both.
What the server holds
| Data | On the server | Detail |
|---|---|---|
| Passwords | Hash only | Werkzeug hashes; the plaintext is never stored or returned |
| Public keys | Stored | Validated as PEM RSA of at least 2048 bits, then served to any logged-in user |
| Ciphertext | Stored | Returned only to the recipient, and expires after 30 days by default |
| Metadata | Stored | Sender, recipient, key_uid and timestamps stay visible to the server |
| Private keys | Never | There is no field, route or column for them |
| Plaintext secrets | Never | Whatever the client sends is what gets stored, so encryption has to happen before the request |
Why a public key can sit on a server
Anything encrypted with a public key can only be decrypted with the matching private key, so the public half can be handed out while the private half stays on its owner's device.
The server checks keys, but never uses them
An upload is validated with the cryptography library: PEM SubjectPublicKeyInfo, RSA only, at least 2048 bits, at most 16 KB. That proves the key is well formed, not who it belongs to.
key_uid ties a message to a key
Each upload gets a key_uid built from the owner's UUID and the row id, and every message records the key_uid it was encrypted for, so publishing a new key does not orphan older messages.
Encryption still happens on the client
Key generation, encryption and decryption are declared client responsibilities and are not implemented in this repository, so the end-to-end story is a design rather than a working demonstration.
- Provides
- A key directory and a ciphertext mailbox: register a public key, fetch a recipient's newest key, address ciphertext to a key_uid. No private key or plaintext is ever stored.
- Does not provide
- Proof that a public key belongs to its owner. Relay decides which key to hand out, and there is no fingerprint, pinning or key transparency log to check it against.
- Does not provide
- Message signatures, a signed key-rotation chain or forward secrecy. A leaked private key decrypts every stored message that was encrypted for it.
Authentication and API
JWTs decide who is asking, not who can read
Authentication stops strangers from uploading keys under your name or reading your inbox. It does nothing for confidentiality. That part is the encryption's job.
- Login checks the password against its Werkzeug hash and issues an HS256 access token whose identity is the username. Tokens expire after 8 hours.
- A user has one active session. Logging in writes the new token's jti to the user record, so every earlier token stops working; logout clears it.
- Revocation is checked on every protected request: a token is rejected when its jti is no longer the current one, or when the user no longer exists.
- Protected routes read the user from the token, never from the request body. Inbox, message lookup and delete queries are all filtered by recipient, so guessing another message_uid returns 404.
- Uploading a public key asks for the account password on top of the JWT, so a stolen token cannot publish a key that senders would encrypt to.
Routes
| Method | Route | JWT | Purpose |
|---|---|---|---|
| POST | /auth/register | - | Create an account |
| POST | /auth/login | - | Verify password, issue an 8 hour JWT |
| POST | /auth/logout | required | End the current session |
| POST | /keys/addKey | required | Store a public key, return key_uid |
| GET | /keys/getAllKeys | required | List your own keys, newest first |
| POST | /keys/fetchPublicKey | required | Newest public key for a username |
| POST | /keys/deleteKey | required | Delete one of your keys |
| GET | /message/sendTo | required | Check that a username exists |
| POST | /message/send | required | Store ciphertext for a recipient |
| GET | /message/inbox | required | A page of your inbox, newest first |
| POST | /message/getMessageById | required | One of your messages by message_uid |
| POST | /message/inbox/deleteMessage | required | Delete one of your messages |
Rate limits
- POST /auth/register
- 5 requests per minute, keyed by client IP
- POST /auth/login
- 30 requests per minute, keyed by client IP
- POST /auth/login
- 5 failures per minute, keyed by submitted username
- POST /keys/addKey
- 5 wrong passwords per minute, keyed by the token's user
Only failed logins and wrong passwords consume the second quota, so normal use is never punished. The limits live in memory and count per process, so a multi-worker deployment needs a shared store, and behind a reverse proxy the real client IP has to be forwarded.
Security model
What it protects, and what it does not
Everything on the left is enforced in the server code and covered by the test suite. Everything on the right is a gap I know about.
Designed to protect against
A leaked database
It holds password hashes, public keys and ciphertext, and messages expire after 30 days by default. It never holds a private key or plaintext.
Reading someone else's inbox
Authorization lives in the queries: inbox, fetch and delete all filter on the recipient, so another user's message_uid returns 404.
Old or logged-out tokens
Tokens expire after 8 hours and a user has one active session, so a new login invalidates the previous token and logout clears the current one.
Encrypting to the wrong key
The server rejects a message whose key_uid does not belong to the recipient.
A stolen token trying to replace a key
Uploading a key requires the account password as well as the token, so a stolen token alone cannot publish a key that senders would then encrypt to.
Password guessing
Registration is limited to 5 requests per minute per IP, login to 30 per minute per IP plus 5 failures per minute per username, and key uploads to 5 wrong passwords per minute per account. Only failures consume the second quota, so normal use is never punished.
Does not protect against
Key substitution by the server
Relay decides which public key it hands out, and nothing lets a sender verify a fingerprint. A compromised server, or anyone with database write access, could serve a key they control.
A compromised browser
Once the client exists, XSS or a malicious extension could read private keys or plaintext before encryption.
Stolen tokens
A captured token works until it expires or the user logs in again. There are no nonces, so requests can be replayed in that window.
Private key loss or theft
There is no recovery, and no forward secrecy. A stolen key opens every message encrypted for it.
Rate limits that live in one process
Flask-Limiter is configured with in-memory storage, so limits are per process. A multi-worker deployment needs a shared store such as Redis, and behind a reverse proxy the real client IP has to be forwarded.
Transport and metadata
The Flask dev server speaks plain HTTP, so TLS would need a reverse proxy in front. Even with TLS, the server sees who messages whom and when.
Limitations and future work
Where it stands
Relay is a working server API with a test suite behind it, not a finished product. The client half of the design is still missing, so everything here describes the server as it stands today.
Implemented
- Registration with Werkzeug password hashes, length checks and generic duplicate errors
- JWT login with one active session per user, 8-hour expiry and jti-based revocation
- Public key upload with a password confirmation and PEM/RSA-2048 validation, plus listing and deletion
- Ciphertext send, paginated inbox, fetch and delete, all scoped to the recipient
- Opaque UUID message ids, key_uid ownership checks and a per-recipient inbox cap
- Message expiry (30 days by default) with a purge script for a scheduled job
- Rate limits on registration, login and key upload
- JSON error handlers that keep the right status code and never return exception text
- A pytest suite covering auth, authorization, key validation, rate limiting and retention
Not in the repository
- The client: key generation, encryption, decryption and private key storage
- Proof that a public key belongs to its owner - no fingerprints, pinning or key transparency log
- Message signatures and a signed key-rotation chain
- Forward secrecy or ephemeral session keys
- Production hardening: SQLite, the Flask development server, in-process rate limits and no TLS here
Future work
- Build the client and settle on the scheme - RSA alone only encrypts short payloads, so a hybrid with a symmetric cipher is likely
- Key fingerprint verification so a sender can check the key it fetched
- Signed key rotation and message signatures
- Ephemeral session keys for forward secrecy
- Redis-backed rate limiting and a WSGI server behind a TLS reverse proxy
- A protocol design document, which the repository still lacks
What I learned
Security concepts are different once you implement them
- [01]
Authentication is not encryption
A valid JWT says who is asking. It says nothing about who can read the data. Relay needs both, as separate layers.
- [02]
Decide what the server should know first
Designing the tables around "no private keys, no plaintext" is what made the server simple: a directory and a mailbox.
- [03]
Public keys still need trust
The encryption was never the hard part. Knowing the key really belongs to the recipient is, and the server controls that.
- [04]
Keys need versions
Adding key_uid meant working out what happens to older messages when someone uploads a new key.
- [05]
Authorization lives in the queries
Filtering every lookup by the token identity is what stops IDOR, so I attacked my own routes to check it.
- [06]
Review your own code like someone else wrote it
Writing this page, I found a delete route that never worked and an error handler that leaked exception text, and fixed both.