Skip to content

SPV_IMPLEMENTATION.md

Latest commit

 

History

History
306 lines (233 loc) · 7.98 KB

SPV_IMPLEMENTATION.md

File metadata and controls

306 lines (233 loc) · 7.98 KB
Raw

SPV Interceptor Implementation Summary

Overview

This implementation adds a Sealed Provenance Vault (SPV) middleware that intercepts media uploads flagged for encryption and routes them through the KMS service before they reach external storage.

Implementation Details

Files Created

  1. backend/src/middlewares/spv.middleware.ts

    • Main middleware that intercepts upload requests
    • Checks req.body.isSealed flag
    • Routes file buffer to KMS service for encryption
    • Attaches encrypted data to request for downstream processing

  2. backend/src/services/spv.service.ts

    • Business logic for SPV operations
    • File encryption using AES-256-GCM
    • SPV record management (create, read, update)
    • File decryption functionality
    • Integration with KMS key management

  3. backend/src/controllers/spv.controller.ts

    • HTTP request/response handling
    • Input validation
    • Error handling with appropriate status codes
    • Asset and SPV record creation
    • CRUD operations for SPV records

  4. backend/src/routes/spv.routes.ts

    • API endpoint definitions
    • Multer configuration for file uploads
    • Middleware chain setup
    • Route handlers

  5. backend/src/middlewares/README.md

    • Comprehensive documentation
    • API endpoint specifications
    • Security features
    • Integration guide

  6. backend/src/middlewares/spv.middleware.test.md

    • Testing guide with Postman examples
    • cURL command examples
    • Error scenario testing
    • Database verification steps

Files Modified

  1. backend/package.json

    • Added multer dependency for file uploads
    • Added @types/multer dev dependency

  2. backend/src/index.ts

    • Imported SPV routes
    • Registered /api/v1/spv endpoint

Architecture Compliance

✅ Strict Layered Architecture: Implements Controller → Service → Model pattern

✅ Data Source: All data retrieved from MongoDB database (no mock objects)

✅ API Versioning: All endpoints use /api/v1/ prefix

✅ Production Ready:

  • Robust error handling with specific error messages
  • Strong TypeScript typings throughout
  • Input validation for all endpoints
  • Secure encryption using AES-256-GCM
  • Environment variable configuration

API Endpoints

POST /api/v1/spv/upload

Upload and encrypt a file for SPV protection.

Request:

  • Method: POST
  • Content-Type: multipart/form-data
  • Body:
    • file: File to upload
    • isSealed: boolean (true to encrypt)
    • userId: MongoDB ObjectId
    • accessType: 'private' | 'public_with_conditions' | 'nft_holders_only' | 'specific_users'
    • allowedUsers: Array of user IDs (optional)
    • nftContractAddress: Stellar contract address (optional)

Response (201):

{
  "status": "success",
  "message": "Encrypted asset uploaded and SPV record created successfully",
  "data": {
    "assetId": "...",
    "spvRecordId": "...",
    "fileName": "...",
    "isEncrypted": true,
    "encryptionKeyVersion": "v1",
    "isSealed": true,
    "accessType": "private",
    "createdAt": "..."
  }
}

GET /api/v1/spv/records/:assetId

Retrieve SPV record by asset ID.

GET /api/v1/spv/records/user/:userId

Retrieve all SPV records for a specific user.

PATCH /api/v1/spv/records/:id/seal

Update the sealed status of an SPV record.

Security Features

  1. AES-256-GCM Encryption: Industry-standard authenticated encryption
  2. Key Versioning: Tracks which KMS key version encrypted each file
  3. Master Key Protection: Symmetric keys encrypted with master key
  4. Access Control Policies: Multiple access types supported
  5. Input Validation: All inputs validated before processing
  6. Error Sanitization: Sensitive details hidden in production mode

Middleware Flow

Client Request
    ↓
Multer (file upload handling)
    ↓
SPV Middleware (checks isSealed flag)
    ↓
    ├─→ isSealed = false → Pass through (no encryption)
    │
    └─→ isSealed = true → Encrypt file buffer
                          ↓
                    Fetch active KMS key
                          ↓
                    Decrypt symmetric key
                          ↓
                    Encrypt file with AES-256-GCM
                          ↓
                    Attach encrypted data to request
                          ↓
Controller (create Asset & SPV records)
    ↓
Service (business logic)
    ↓
Model (database operations)
    ↓
Response to Client

Database Schema Integration

Asset Model

  • Links to encrypted file storage
  • Tracks encryption status and key version
  • Stores access policy

SPV Record Model

  • Links asset to KMS key
  • Defines access control policies
  • Tracks sealed status
  • Supports multiple access types

KMS Key Model

  • Stores encrypted symmetric keys
  • Tracks key versions
  • Manages key lifecycle (active/inactive)

Testing Instructions

Prerequisites

  1. MongoDB running on localhost:27017
  2. Environment variables configured in .env
  3. Dependencies installed: npm install
  4. KMS data seeded: npm run seed:kms

Test with Postman

  1. Start server: npm run dev
  2. POST to /api/v1/spv/upload with:
    • File attachment
    • isSealed=true
    • Valid userId from seed data
  3. Verify 201 response with encrypted asset details
  4. Check MongoDB for Asset and SPVRecord documents

Test with cURL

curl -X POST http://localhost:4000/api/v1/spv/upload \
  -F "file=@./test-image.jpg" \
  -F "isSealed=true" \
  -F "userId=507f1f77bcf86cd799439011" \
  -F "accessType=private"

Error Handling

The implementation handles all error scenarios:

  • 400 Bad Request: Missing/invalid parameters
  • 404 Not Found: No active KMS key or record not found
  • 500 Internal Server Error: Encryption or database errors

All errors return consistent JSON format:

{
  "status": "error",
  "message": "Human-readable error message",
  "error": "Detailed error (development only)"
}

Future Enhancements

  1. Actual storage integration (IPFS/S3/GridFS)
  2. Decryption endpoint with access control validation
  3. NFT ownership verification for gated access
  4. Audit logging for all encryption/decryption operations
  5. Streaming support for large files
  6. Rate limiting on upload endpoints
  7. File type validation and sanitization
  8. Virus scanning integration

Compliance Checklist

  • ✅ Strict Layered Architecture (Controller → Service → Model)
  • ✅ Data from database (no inline mocks)
  • ✅ Environment variables for configuration
  • ✅ API versioning (/api/v1/...)
  • ✅ Production-ready code quality
  • ✅ Robust error handling
  • ✅ Strong TypeScript typings
  • ✅ No TypeScript compilation errors
  • ✅ Comprehensive documentation
  • ✅ Testing guide provided

Installation

# Navigate to backend directory
cd backend

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your MongoDB URI and MASTER_KEY

# Seed KMS data
npm run seed:kms

# Start development server
npm run dev

Dependencies Added

  • multer@^1.4.5-lts.1: File upload handling
  • @types/multer@^1.4.12: TypeScript types for multer

Notes for Contributors

  1. The middleware is designed to be non-blocking for non-SPV uploads
  2. Encryption is performed in-memory before storage
  3. The implementation uses the existing KMS infrastructure
  4. All database operations use Mongoose models
  5. Error messages are sanitized in production mode
  6. The middleware can be easily extended for additional storage providers

Branch Information

  • Branch name: spv-interceptor
  • Base branch: main
  • Implementation directory: backend/src/middlewares/

PR Checklist

  • ✅ Code follows CONTRIBUTING.md guidelines
  • ✅ No inline mock objects or hardcoded values
  • ✅ API is versioned
  • ✅ Production-ready code quality
  • ✅ Comprehensive error handling
  • ✅ TypeScript compilation successful
  • ✅ Documentation provided
  • ✅ Testing guide included
  • ⏳ Screenshot of working API (to be added during testing)
  • ⏳ PR includes "Closes #[issue_id]" (to be added when creating PR)