simonwep / genesis

🧞 A simple, generic, fast and lightweight json api for frontend apps. Store your frontend-data as-is without messing around with a database!

Genesis

A generic json api for small, private frontend apps (WIP)

Summary

This project is designed specifically for small, personal projects requiring a straightforward, simple storage API that you can host yourself including simplified user management.

Usage

First, create a .env and specify the initial usernames and passwords for access. Make sure to fill out GENESIS_JWT_SECRET with a secure, random string, for that you can use openssl rand -hex 32. You can specify the remaining values, but the defaults are good for medium-sized projects such as ocular.

Second, start the server via go run .. That's it. Head to the api documentation to see how to use it.

The json is pre-processed by the minify package to minimize and validate it.

Using docker

You can run genesis using docker by using pre-build images:

docker run -p 8080:8080 -v "$(pwd)/.data:/app/.data" --env-file .env ghcr.io/simonwep/genesis:latest

Genesis should then be accessible under port 8080.

API

The API is kept as simple as possible, there is nothing more than user, data and account management.

Authentication and account

• POST /login - Authenticates a user.
  • Takes either a user and password as json object and returns the user-data and a session cookie or, if a session-cookie exists, the current user.
  • Returns 401 the password is invalid or the user doesn't exist.
• POST /logout - Invalidates the current refresh token and logs out a user.
• POST /account/update
  • Takes a newPassword and currentPassword as json object.
  • Returns 200 if the password was successfully updated, otherwise 400.

The JWT token is returned as strict same-site, secure and http-only cookie!
When changing the password, the new password must fulfill the same requirements for adding a new user.

Data endpoints

• GET /data - Retrieves all data from the current user as object.
• GET /data/:key - Retrieves the data stored for the given key. Returns 204 if there is no content.
• POST /data/:key - Stores / overrides the data for key.
• DELETE /data/:key - Removes the data for key, always returns 200, even if key doesn't exist.

Validation parameters for those endpoints are defined in .env.
This includes a key-pattern, the max amount per user and a size-limit.

User management

These endpoints can only be used by admins!

• GET /user - Fetch all users as { name: string, admin: boolean }[].
• POST /user - Create a user, takes a json object with user, password and admin (all mandatory, admin is a boolean).
• POST /user/:name - Update a user by name, takes a json object with password and admin (both optional).
• DELETE /user/:name - Delete a user by name.

The username is validated against the pattern defined in .env.
The length must be between 3 and 32, the password between 8 and 64.