BlindVault

BlindVault is a privacy-preserving credential issuance and redemption service built on BLS12-381 blind signatures and DLEQ proofs.

Purpose

BlindVault enables clients to request unbiased blind credentials, verify that the server signed them with a derived public key, and consume them without revealing the underlying secret material.

Features

• Blind credential issuance using BLS12-381 blind signatures
• DLEQ proof of correct signing key usage
• Epoch and credential class key derivation from a single master seed
• Replay protection using deterministic nullifiers
• Redis-backed nullifier and revocation stores for production
• JWT-protected issuance and admin endpoints
• Health and Prometheus metrics endpoints
• Optional demo endpoints for local testing and examples

Quickstart

1. Create configs/config.yaml for local development or set the environment variables directly.
2. Set a master seed using the preferred environment variables:

export BLINDVAULT_MASTER_SEED_HEX=<32-byte-hex-seed>
# or, for file-based secret injection:
export BLINDVAULT_SEED_FILE=/path/to/seed.txt

3. Run the server. The server accepts an optional .env file via --env-file and will apply YAML values before environment overrides unless --env-override is used:

go run ./cmd/server/main.go --config configs/config.yaml
# or load a local env file first
# go run ./cmd/server/main.go --config configs/config.yaml --env-file .env --env-override

4. Validate health:

curl http://localhost:8080/health

5. Optional: scrape Prometheus metrics:

curl http://localhost:8080/metrics

Documentation

• docs/api_reference.md — API endpoints, request and response formats, and errors
• docs/client_reference.md — Go client library and CLI usage
• docs/deployment_guide.md — deployment, Docker Compose, Redis setup, and health checks
• docs/crypto_spec.md — cryptographic specification, DLEQ proof details, and security assumptions
• docs/crypto_vectors.md — generated test vector placeholder
• CONTRIBUTING.md — contribution process and testing guidelines

Client package and CLI

BlindVault includes a high-level Go client wrapper in pkg/client and a command-line interface in cmd/bv.

Build the CLI:

go build -o bv ./cmd/bv

Examples:

bv blind --message "hello" --server http://localhost:8080
bv unblind --signature <blind_signature_hex> --id <request_id>
bv redeem --signature <unblinded_signature_hex> --witness <witness_hex> --class tier_gold --epoch 2026-01

The blind command returns JSON with blinded, witness, and request_id. The verify command validates a DLEQ proof locally, unblind converts a blind signature into an unblinded one using the stored request state, and redeem submits the credential to /v1/credential/consume.

Client state is persisted to ~/.blindvault/state.json.

Running tests

go test ./...
go test -v ./pkg/crypto

Generating crypto vectors

go run scripts/generate_vectors.go --output docs/crypto_vectors.md

Configuration

The server reads the YAML config first and then applies environment overrides. The preferred secret-loading paths are:

• BLINDVAULT_MASTER_SEED_HEX for in-memory secrets
• BLINDVAULT_SEED_FILE for a mounted or generated secret file

Common runtime overrides include:

• BLINDVAULT_MODE
• ACTIVE_EPOCH
• SUPPORTED_EPOCHS
• DST
• AUTH_SECRET
• JWT_ISSUER
• JWT_AUDIENCE
• REDIS_ADDR
• REDIS_PASSWORD
• REDIS_DB
• REDIS_EXPIRATION
• REVOCATION_REDIS_ADDR
• REVOCATION_REDIS_PASSWORD
• REVOCATION_REDIS_DB
• USE_MEMORY_STORE
• USE_DEMO
• LISTEN_ADDR
• RATE_LIMIT_REQUESTS
• RATE_LIMIT_BURST
• MAX_CLIENTS

Development vs production

The default development config intentionally includes a local seed, in-memory storage, and demo endpoints:

mode: "development"
listen_addr: ":8080"
blindvault_master_seed_hex: "..."
active_epoch: "2026-01"
use_memory_store: true
use_demo: true

Production mode rejects inline seed values in the YAML config, forbids use_memory_store, forbids use_demo, requires jwt_issuer and jwt_audience, and enforces stricter secret length requirements.

Notes

Use use_memory_store: true and use_demo: true only for local testing. Production deployment should use Redis, protect the master seed and JWT secret with a secrets manager, and keep admin authorization separate from application user identity flows.