{"id":30047801,"url":"https://github.com/prit342/signed-blob-service","last_synced_at":"2026-05-15T21:32:11.810Z","repository":{"id":307827181,"uuid":"1030802823","full_name":"prit342/signed-blob-service","owner":"prit342","description":"A complete blob storage system built using Go, gRPC, Protocol Buffers, and PostgreSQL. This service stores text blobs in a cryptographically signed format using RSA-PSS digital signatures, ensuring data integrity, authenticity, and non-repudiation. Also comes with a client.","archived":false,"fork":false,"pushed_at":"2025-08-02T12:04:05.000Z","size":48,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-02T13:31:54.252Z","etag":null,"topics":["cobra-cli","golang","grpc","rsa-cryptography"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prit342.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-02T11:02:56.000Z","updated_at":"2025-08-02T12:08:45.000Z","dependencies_parsed_at":"2025-08-02T13:32:08.822Z","dependency_job_id":"4efb859a-55b2-4233-8276-78f049b566e1","html_url":"https://github.com/prit342/signed-blob-service","commit_stats":null,"previous_names":["prit342/signed-blob-service"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/prit342/signed-blob-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prit342%2Fsigned-blob-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prit342%2Fsigned-blob-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prit342%2Fsigned-blob-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prit342%2Fsigned-blob-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prit342","download_url":"https://codeload.github.com/prit342/signed-blob-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prit342%2Fsigned-blob-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33080777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T20:25:35.270Z","status":"ssl_error","status_checked_at":"2026-05-15T20:25:34.732Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cobra-cli","golang","grpc","rsa-cryptography"],"created_at":"2025-08-07T09:59:32.657Z","updated_at":"2026-05-15T21:32:11.805Z","avatar_url":"https://github.com/prit342.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ Signed Blob Storage Service\n\nA complete blob storage system built using **Go**, **gRPC**, **Protocol Buffers**, and **PostgreSQL**. This service stores text blobs in a cryptographically signed format using RSA-PSS digital signatures, ensuring data integrity, authenticity, and non-repudiation.\n\nThe system provides both server-side storage and a command-line client for seamless interaction. When a blob is uploaded, the server generates a unique UUID and creates cryptographic signatures. Clients can then download the original content along with verification files including:\n\n- **`\u003cuuid\u003e.txt`** - The original blob content\n- **`\u003cuuid\u003e.sig`** - Base64-encoded RSA-PSS signature  \n- **`\u003cuuid\u003e.meta.json`** - Metadata with UUID, SHA-256 hash, and timestamp\n\nThis architecture enables secure, verifiable blob storage with complete offline verification capabilities using industry-standard cryptographic methods.\n\n## ✨ Features\n\n- **Secure Storage**: Store plain text blobs with automatic server-side digital signing\n- **RSA-PSS Signatures**: Modern probabilistic signature scheme using 2048-bit RSA keys\n- **Integrity Verification**: SHA-256 hashing ensures blob content has not been tampered with\n- **Client-Side Verification**: Retrieve public key to verify signatures independently\n- **UUID-Based Lookup**: Globally unique identifiers for efficient blob retrieval\n- **Size Limits**: Configurable blob size limits (currently 256KB maximum)\n- **Clean Architecture**: Well-structured codebase with proper separation of concerns\n- **Comprehensive Testing**: Unit tests, integration tests using testcontainers, and end-to-end cryptographic verification\n\n\n## 🧱 Tech Stack\n\n### Backend\n- **Go 1.22+**: Modern, performant backend language\n- **gRPC**: High-performance RPC framework with HTTP/2 support\n- **Protocol Buffers**: Efficient serialisation with strong typing via [Buf](https://buf.build/)\n- **PostgreSQL**: Robust relational database for blob storage\n- **RSA Cryptography**: Industry-standard digital signatures (RSASSA-PSS, PKCS#1 v2.1)\n### Development \u0026 Operations\n- **Docker Compose**: Multi-service development environment\n- **Testcontainers**: Isolated integration testing with real PostgreSQL instances\n- **Structured Logging**: JSON-formatted logs with source file information (`slog`)\n- **Database Migrations**: Version-controlled schema evolution and migrations using go-migrate\n\n\n## 📁 Project Structure\n\n| Directory | Purpose | Description |\n|-----------|---------|-------------|\n| `api/` | gRPC Service Implementation | Houses the main gRPC API service handlers and business logic |\n| `gen/` | Generated Protocol Buffer Code | Contains compiled Protocol Buffer definitions and gRPC service stubs |\n| `cmd/` | Application Entry Points | Contains main applications (server and client executables) |\n| `cmd/client/` | CLI Client Application | Command-line interface for interacting with the blob service |\n| `cmd/server/` | gRPC Server Application | Main server application that hosts the blob storage service |\n| `db-migrations/` | Database Schema | SQL migration files for PostgreSQL schema versioning used by go-migrate |\n| `e2e/` | Integration Tests | End-to-end tests using testcontainers with real database instances |\n| `internal/` | Private Application Code | Internal packages not meant for external import |\n| `internal/api/` | Service Implementation | gRPC service handlers and business logic |\n| `internal/store/` | Data Persistence | Database access layer and storage abstractions |\n| `proto/` | Protocol Buffer Definitions | Source `.proto` files defining the gRPC service interface |\n| `scripts/` | Development Scripts | Shell scripts for key generation, setup, and development tasks |\n| `signature/` | Cryptographic Operations | RSA-PSS signing and verification implementation |\n\n### Key Configuration Files\n\n| File | Purpose |\n|------|---------|\n| `buf.yaml` | Buf CLI configuration for Protocol Buffer management |\n| `buf.gen.yaml` | Code generation settings for Protocol Buffers |\n| `docker-compose.yaml` | Multi-service development environment (PostgreSQL + App) |\n| `Dockerfile` | Container image definition for the gRPC server |\n| `env-local-sample` | Environment variable template for local development |\n| `.golangci.yml` | Go linting configuration with project-specific rules |\n| `Makefile` | Build automation and development workflow commands |\n\n---\n\n## 📦 gRPC API Reference\n\nThe service exposes three core RPC methods:\n\n| Method | Purpose | Input | Output |\n|--------|---------|-------|--------|\n| `StoreBlob` | Upload and sign a text blob | `StoreBlobRequest` | `StoreBlobResponse` |\n| `GetSignedBlob` | Retrieve signed blob with signature | `GetSignedBlobRequest` | `GetSignedBlobResponse` |\n| `GetPublicKey` | Fetch server's public signing key | `GetPublicKeyRequest` | `GetPublicKeyResponse` |\n\n### Message Structures\n\n#### `BlobRecord` (Canonical Signed Structure)\n```protobuf\nmessage BlobRecord {\n  string uuid = 1;      // Server-generated UUID for identification\n  string blob = 2;      // Original user-submitted text blob  \n  string hash = 3;      // SHA-256 hash of the blob, hex-encoded\n  string timestamp = 4; // RFC3339 formatted timestamp (e.g., \"2025-07-30T16:52:13Z\")\n}\n```\n\n#### Key API Flows\n\n1. **Store Blob**: Client sends raw text → Server generates UUID, computes hash, adds timestamp → Signs entire `BlobRecord` → Stores in database\n2. **Retrieve Blob**: Client requests by UUID → Server returns original `BlobRecord` + RSA signature\n3. **Verify Signature**: Client can verify the signature using the public key to ensure data integrity\n\n\n## 🔐 Cryptographic Details\n\n### Digital Signature Algorithm\n- **Algorithm**: RSA-PSS (RSASSA-PSS) - Probabilistic Signature Scheme\n- **Key Size**: 2048 bits\n- **Hash Function**: SHA-256\n- **Salt Length**: Equal to hash length (32 bytes for SHA-256)\n- **Signed Data**: Protobuf-serialised `BlobRecord` (includes UUID, blob, hash, timestamp)\n\n### Security Properties\n- **Authenticity**: Signatures prove the blob was signed by the server's private key\n- **Integrity**: Any tampering with the blob content invalidates the signature\n- **Non-repudiation**: Server cannot deny having signed a blob\n- **Probabilistic**: Each signature includes random salt, making signatures non-deterministic (enhanced security)\n- **Provable Security**: RSA-PSS has stronger security proofs than PKCS#1 v1.5\n\n### Key Management\n- Private key stored securely on server (never transmitted)\n- Public key available via gRPC endpoint for client verification\n- Keys generated in PKCS#1 format for compatibility\n\n\n## 🛠️ Development Scripts\n\nThe project includes several utility scripts and Make targets for development and deployment:\n\n### Make Targets\n\nThe Makefile provides comprehensive build and development targets with built-in help:\n\n```bash\nmake help                 # Display all available targets with descriptions\nmake                      # Same as 'make help' (default target)\n```\n\n**Key targets organised by category:**\n\n```bash\n# Build \u0026 Development\nmake generate-proto       # Generate Go code from Protocol Buffer definitions\nmake build                # Build Docker images with generated code and RSA keys  \nmake run                  # Start the service stack (requires prior build)\nmake build-and-run        # Build and start the complete service in one command\n\n# Testing \u0026 Quality Assurance  \nmake unit-test            # Run unit tests for all Go packages\nmake e2e-test             # Run end-to-end integration tests using testcontainers\nmake test                 # Run complete test suite (unit + integration tests)\n\n# Client Application\nmake build-client         # Build the command-line client application\n\n# Maintenance\nmake clean                # Remove generated files and Docker resources\n```\n\n### Shell Scripts\n\n```bash\n./generate-rsa-keys.sh    # Generate 2048-bit RSA private key in PKCS#1 format\n```\n- Creates `private_key.pem` with proper permissions (644)\n- Converts from PKCS#8 to PKCS#1 format for Go compatibility\n- Validates key format before completion\n\n### Build \u0026 run\n```bash\nmake build-and-run        # One-step build and run with latest changes\n```\n\n### Testing\n```bash\nmake unit-test            # run all unit tests\nmake e2e-test             # run end-to-end test using testcontainers\nmake test                 # Run all tests\n```\n\n### Testing the API\n\n- Run the gRPC server in one terminal:\n```\nmake check\nmake build-and-run\n```\n\n- Build the client in another terminal:\n```bash\nmake build-client\n```\n\n- Create a file with some contents:\n```bash\necho hello-world \u003e /tmp/test.txt\n```\n\n- Upload/Put the file:\n\n```\n❯ ./client --server localhost:55555 put /tmp/test.txt\n2025/08/02 11:37:49 Blob stored successfully with UUID: 9de22b2a-9d35-42d8-8b7e-fd2570aca13b\n```\n\n- Download the same content along with signature to a local folder download:\n\n```bash\n❯ mkdir downloads  \n❯ ./client --server localhost:55555 get 9de22b2a-9d35-42d8-8b7e-fd2570aca13b --dir ./downloads \n2025/08/02 11:40:44 ✅ Blob content saved to: ./downloads/9de22b2a-9d35-42d8-8b7e-fd2570aca13b.txt\n2025/08/02 11:40:44 ✅ Signature saved to:    ./downloads/9de22b2a-9d35-42d8-8b7e-fd2570aca13b.sig\n2025/08/02 11:40:44 ℹ️ Metadata saved to:     ./downloads/9de22b2a-9d35-42d8-8b7e-fd2570aca13b.meta.json\n\n```\n- Download public key from the server:\n```bash\n❯ ./client --server localhost:55555 get-public-key public.pem\n2025/08/02 11:41:50 ✅ Public key saved to file: public.pem\n\n```\n\n- Verify the downloaded files using the local public key (offline verification):\n\n```bash\n./client verify 9de22b2a-9d35-42d8-8b7e-fd2570aca13b --dir downloads --public-key public.pem\n2025/08/02 11:43:37 ✅ Hash matches: d79f2e37784e5cd8631963896ebc6c9c66934af94a1854504717eaec04bc3d09\n2025/08/02 11:43:37 ✅ Signature verification successful!\n```\n\n## 🔧 Configuration\n- All the environment variables are documented in the sample `env-local-sample` file that can be used for testing.\n\n\n## License\nMIT License\n\n\n## 🚀 Future Improvements\n\n- **Tracing**: Add OpenTelemetry support for tracing and metrics\n- **Metrics Collection**: Implement Prometheus metrics for blob operations, signature performance, and database queries\n- **Health Checks**: Enhanced health endpoints with dependency status (database, key availability)\n- **External Key Management**: Integration with AWS KMS, Azure Key Vault, and HashiCorp Vault\n- **TLS Mutual Authentication**: Client certificate validation for enhanced security\n- **Caching Layer**: Redis integration for frequently accessed blobs and public keys\n- **REST API**: Optional HTTP REST interface alongside gRPC for broader client compatibility\n- **Go Tool**: Use `go tool` for installing various command line utilities and migrate to go 1.24\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprit342%2Fsigned-blob-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprit342%2Fsigned-blob-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprit342%2Fsigned-blob-service/lists"}