About ShrimPG

ShrimPG — Open Source Password Manager. Password manager written in Go, using postgreSQL database

k

Published by

krev3tka

Visit View Profile

README.md

View on GitHub

ShrimPG 🦐

Shrimp-powered Password Gate — secure, fast, and elegant.

ShrimPG Logo

...

ShrimPG is a secure secrets management system designed with a focus on cryptographic integrity, modularity, and clean architecture.

Architecture Overview

The project follows a layered architecture, decoupling business logic from storage and security concerns:

API Layer: RESTful handlers with session-based middleware.
Logic Layer: Password validation and user context management.
Security Layer: High-level cryptographic primitives (AES-GCM, Argon2/Scrypt).
Storage Layer: PostgreSQL 16 with volume persistence.

Security Workflow

Zero-Password Storage: The Master Password is never stored in the database.
Cryptographic Auth: Authentication is verified by attempting to decrypt a "master_check" record. If decryption fails, the key is invalid.
Unique Salting: Every password entry uses a unique 12-byte salt for key derivation, protecting against rainbow table attacks.
Graceful Shutdown: The server ensures all database transactions are completed and connections are closed properly before exiting.

Tech Stack

Core: Go (Golang) 1.26+
Database: PostgreSQL 16
Infrastructure: Docker & Docker Compose
Auth: Token-based Session Management

Getting Started

Prerequisites

Docker & Docker Compose

Installation

Clone the repository:


git clone [https://github.com/Krev3tka/ShrimPG.git](https://github.com/Krev3tka/ShrimPG.git)
cd ShrimPG

Start the infrastructure:
```
 docker-compose up --build -d
```

API Reference

The server enforces TLS (ListenAndServeTLS), so all endpoints must be accessed via https://. For local testing with self-signed certs, use curl -k to bypass verification.

User Registration (POST /api/v1/register)



 curl -k -X POST [https://127.0.0.1:8080/api/v1/register](https://127.0.0.1:8080/api/v1/register) \
   -H "Content-Type: application/json" \
   -d '{"username": "your_username", "password": "your_master_password"}'

User Login (POST /api/v1/login)


 curl -k -X POST [https://127.0.0.1:8080/api/v1/login](https://127.0.0.1:8080/api/v1/login) \
   -H "Content-Type: application/json" \
   -d '{"username": "your_username", "password": "your_master_password"}'

Expected Response: JSON

{"token": "YOUR_TOKEN"}

User Logout (POST /api/v1/logout)



 curl -k -X POST [https://127.0.0.1:8080/api/v1/logout](https://127.0.0.1:8080/api/v1/logout) \
   -H "Authorization: Bearer <YOUR_SESSION_TOKEN>"

Create Password Entry (POST /api/v1/passwords/create)



 curl -k -X POST [https://127.0.0.1:8080/api/v1/passwords/create](https://127.0.0.1:8080/api/v1/passwords/create) \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer <YOUR_TOKEN>" \
   -d '{"service": "github.com", "login": "your_username", "password": "secret_password"}'

Get Specific Password (POST or GET /api/v1/passwords/get)

Note: Service name must be passed in the JSON body (max 40 chars).



curl -k -X GET [https://127.0.0.1:8080/api/v1/passwords/get](https://127.0.0.1:8080/api/v1/passwords/get) \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_SESSION_TOKEN>" \
  -d '{"service": "github.com"}'

Delete Password Entry (DELETE /api/v1/passwords/delete) Note: Service name must be passed in the JSON body.



 curl -k -X DELETE [https://127.0.0.1:8080/api/v1/passwords/delete](https://127.0.0.1:8080/api/v1/passwords/delete) \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer <YOUR_SESSION_TOKEN>" \
   -d '{"service": "github.com"}'

List All Passwords (GET /api/v1/passwords/list)



 curl -k -X GET [https://127.0.0.1:8080/api/v1/passwords/list](https://127.0.0.1:8080/api/v1/passwords/list) \
   -H "Authorization: Bearer <YOUR_TOKEN>"

Roadmap

[x] PostgreSQL Integration: Docker-ready with volume persistence.
[x] Session-based Auth: Secure middleware with master-key validation.
[x] CRUD Core: Fully functional REST API for password management.
[ ] TUI client, based on BubbleTea framework.

License

Distributed under the GNU GPL v3 License. See LICENSE for more information.

Built with 🦐 passion by Krev3tka

ShrimPG