Blockchain Secrets Vault is a zero‑trust distributed secrets storage system that combines AES‑GCM envelope encryption, blockchain‑anchored ACL enforcement, and Merkle‑verified audit events. Secrets are stored off‑chain in encrypted form, while access rights and audit integrity are validated on‑chain via a Solidity smart contract. The platform includes a reactive WebFlux API, a dedicated KMS module with key rotation, an encrypted persistence layer, an audit writer that publishes event hashes to the blockchain, and optional Kubernetes/Grafana production deployment stack.
The project demonstrates:
- Zero-trust architecture
- Blockchain-based access control
- AES-GCM envelope encryption with DEK/KEK separation
- Key rotation
- On-chain access auditing
- Microservice architecture
Full diagram: docs/architecture.md
Secrets API contract: docs/api/secrets-api.md
- Secrets API - CRUD over secrets and API contract for the MVP. KMS encryption/decryption and blockchain ACL checks are planned follow-up work (#8, #9).
- KMS Service - KEK generation, per-secret DEK envelope encryption, key rotation.
- Blockchain ACL Contract - stores ACL (who can read/write), revocations, and access audit.
- Audit Writer - writes hashes of access events to the blockchain.
- Secrets UI - secrets management, ACL management, audit viewing.
- Java 25+, Spring Boot, Spring WebFlux, Spring Security
- Maven multi-module
- Web3j
- AES-GCM, RSA/ECDSA
- PostgreSQL / Redis
- Hardhat, Solidity
SecretsAcl.solcontract
- Dependency-free HTML, CSS, and JavaScript UI MVP
- Node.js built-in test runner with coverage gates
- Docker Compose, optional Kubernetes (manifests + Helm chart)
Kubernetes deployment docs: k8s/README.md
blockchain-secrets-vault/
├─ backend/ # Spring Boot multi-module services
├─ blockchain/ # Hardhat project and Solidity contracts
├─ frontend/ # Secrets management UI
├─ docs/ # architecture and API documentation
└─ ROADMAP.md
Serve frontend/ from the same origin as the backend to use the default
/api/v1/secrets endpoint. Opening frontend/index.html directly via file://
will not work with the default API base URL.
Run frontend tests and coverage checks:
cd frontend
npm testThe docker-compose.yml file allows you to run the project in Docker, including:
- PostgreSQL - infrastructure service for future persistence work (port 5432)
- Redis - infrastructure service for future caching/integration work (port 6379)
- Blockchain - Hardhat node (port 8545)
- Backend (Secrets API) - Spring Boot application (port 8081)
- Frontend - Nginx web interface on
localhost:8080with/api/reverse proxy tosecrets-api:8080inside the Docker network
At the moment, the Secrets API still uses an in-memory repository, so secret data does not persist across API restarts even though Postgres and Redis containers are available in the stack.
- Docker (version 20.10+)
- Docker Compose (version 2.0+)
Create a .env file in the repository root before the first start:
POSTGRES_PASSWORD=secretsvault-local-dev
SPRING_PROFILES_ACTIVE=dev
SECRETS_AUTH_PASSWORD=replace-with-a-strong-password
SECRETS_AUTH_JWT_SECRET=replace-with-a-32-byte-or-longer-secretThe auth variables are required by secrets-api, and the JWT secret must be at
least 32 bytes long.
Then start the stack:
docker compose up -dThe -d flag runs containers in the background.
# All services
docker compose logs -f
# Specific service
docker compose logs -f secrets-api
docker compose logs -f blockchaindocker compose downdocker compose down -v| Service | URL | Port |
|---|---|---|
| Frontend | http://localhost:8080 | 8080 |
| Backend API | http://localhost:8081 | 8081 |
| Blockchain (Hardhat) | http://localhost:8545 | 8545 |
| PostgreSQL | localhost:5432 | 5432 |
| Redis | localhost:6379 | 6379 |
Open http://localhost:8080 for the UI. The frontend proxies /api/* calls to
secrets-api inside the Docker network, so the browser does not need a
separate backend base URL. Published ports are bound to 127.0.0.1, so the
stack stays local to the development machine by default.
Variables are stored in the .env file:
POSTGRES_PASSWORD=secretsvault-local-dev
SPRING_PROFILES_ACTIVE=dev
SECRETS_AUTH_PASSWORD=replace-with-a-strong-password
SECRETS_AUTH_JWT_SECRET=replace-with-a-32-byte-or-longer-secretModify the .env file to configure the database password, Spring profile, and
Secrets API authentication values used by Docker Compose.
# Check status of all containers
docker compose ps
# View logs of specific services
docker compose logs postgres
docker compose logs redisdocker compose exec postgres psql -U secretsvault -d secretsvaultdocker compose exec redis redis-cli# Rebuild all
docker compose build --no-cache
# Rebuild specific service
docker compose build --no-cache secrets-apidocker compose restart secrets-apidocker compose logs -f --tail=100 [service-name]If a port is already used by another application, modify the port mapping in docker-compose.yml:
services:
frontend:
ports:
- "127.0.0.1:8082:8080" # Use 8082 instead of 8080Check the logs:
docker compose logs [service-name]docker compose down
docker compose build --no-cache
docker compose up -ddocker compose down -v --remove-orphans
docker compose build --no-cache
docker compose up -dAll services are connected to the blockchain-vault-network bridge network, allowing them to communicate using hostnames:
postgres:5432redis:6379blockchain:8545secrets-api:8080
docker statsdocker compose down --remove-orphans
docker image prune -fdocker image prune -f removes dangling images across Docker on the machine.
Review the command before running it if you are working on multiple projects.
docker compose configSee ROADMAP.md and the project board.
MIT