Skip to content

[EPIC] Secret Management System (Password Vault) #173

New issue
New issue
Open
Open
[EPIC] Secret Management System (Password Vault)#173
Labels
area: securitypriority: hightype: feature
@kevalyq

Description

@kevalyq
kevalyq
opened on Nov 16, 2025

🎯 Vision

Implement a comprehensive Secret Management System (Password Vault) that enables users to securely store, manage, and share encrypted secrets (passwords, API keys, documents) with file attachments and fine-grained access control.

📋 Sub-Issues & Work Plan

Implementation Phases

🎯 Success Criteria

  • ✅ Encrypted Storage: All secrets encrypted at rest using tenant DEK
  • ✅ File Attachments: Support for encrypted file uploads (images, PDFs, docs)
  • ✅ RBAC Integration: Permission-based access control (read, write, admin) - Phase 3 COMPLETE
  • ✅ Sharing: Secure secret sharing between users - Phase 3 COMPLETE
  • ✅ API Complete: RESTful API with comprehensive tests (≥80% coverage)
  • ✅ Frontend Ready: API supports PWA offline-first requirements
  • 📅 Frontend UI: Secret Vault UI with offline support - Phase 4 Pending

📚 Technical Architecture

Key Features

Core Secret Management:

  • ✅ Create, read, update, delete secrets
  • ✅ Field-level encryption using TenantKey DEK
  • ✅ Blind indexes for searchable metadata (title)
  • ✅ Full-text search capability (optional)
  • ✅ Versioning support

File Attachments:

  • ✅ Encrypted file storage (server-side encryption)
  • ✅ Metadata management (filename, size, type)
  • ✅ Download/preview endpoints
  • ✅ Size limits (configurable, 10MB default)
  • ✅ Supported types: images, PDFs, documents

Access Control: ✅ Phase 3 COMPLETE

  • ✅ Owner-based permissions (creator has full access)
  • ✅ Shared access via SecretShare model (grant read/write/admin to users/roles)
  • ✅ Permission hierarchy (admin > write > read)
  • ✅ Expiration support for temporary shares
  • ✅ XOR constraint (share with user OR role, not both)
  • ✅ Granter can revoke their own shares
  • ✅ Attachment permissions respect share permissions

Frontend Integration: 📅 Phase 4

🔗 Related Issues

Frontend (SecPal/frontend):

API (this repo):

🗂️ Database Schema (Overview)

-- secrets table ✅ Implemented
CREATE TABLE secrets (
    id UUID PRIMARY KEY,
    tenant_id BIGINT NOT NULL REFERENCES tenant_keys(id),
    owner_id UUID NOT NULL REFERENCES users(id),
    title_enc TEXT NOT NULL,
    title_idx VARCHAR(64) NOT NULL,
    username_enc TEXT,
    password_enc TEXT,
    url_enc TEXT,
    notes_enc TEXT,
    tags JSONB,
    expires_at TIMESTAMP,
    version INT DEFAULT 1,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    deleted_at TIMESTAMP,
    INDEX idx_secrets_title (title_idx),
    INDEX idx_secrets_owner (owner_id),
    INDEX idx_secrets_expires (expires_at)
);

-- secret_attachments table ✅ Implemented
CREATE TABLE secret_attachments (
    id UUID PRIMARY KEY,
    secret_id UUID NOT NULL REFERENCES secrets(id) ON DELETE CASCADE,
    tenant_id BIGINT NOT NULL REFERENCES tenant_keys(id),
    filename_enc TEXT NOT NULL,
    file_size BIGINT NOT NULL,
    mime_type VARCHAR(255) NOT NULL,
    storage_path TEXT NOT NULL,
    checksum_sha256 VARCHAR(64),
    uploaded_by UUID NOT NULL REFERENCES users(id),
    created_at TIMESTAMP NOT NULL,
    INDEX idx_attachments_secret (secret_id)
);

-- secret_shares table ✅ Implemented (Phase 3)
CREATE TABLE secret_shares (
    id UUID PRIMARY KEY,
    secret_id UUID NOT NULL REFERENCES secrets(id) ON DELETE CASCADE,
    user_id UUID REFERENCES users(id) ON DELETE CASCADE,
    role_id BIGINT REFERENCES roles(id) ON DELETE CASCADE,
    permission ENUM('read', 'write', 'admin') NOT NULL,
    granted_by UUID NOT NULL REFERENCES users(id),
    granted_at TIMESTAMP NOT NULL,
    expires_at TIMESTAMP,
    UNIQUE(secret_id, user_id),
    UNIQUE(secret_id, role_id),
    CHECK((user_id IS NOT NULL AND role_id IS NULL) OR 
          (user_id IS NULL AND role_id IS NOT NULL))
);

🔒 Security Considerations

Encryption:

  • ✅ All secret fields use EncryptedWithDek cast
  • ✅ File contents encrypted at rest (server-side encryption)
  • 📅 Client-side encryption optional (frontend Phase 4)
  • ✅ Never log decrypted secrets

Access Control:

  • ✅ Owner always has full access
  • ✅ Shared access requires explicit grant (Phase 3 COMPLETE)
  • ✅ Permission checks at controller + policy level (defense-in-depth)
  • ✅ XOR constraint enforced (user OR role, not both)
  • ✅ Granter can revoke their own shares

GDPR Compliance:

  • ✅ Right to access (user can export their secrets)
  • ✅ Right to erasure (soft delete implemented)
  • ✅ Audit trail via granted_by, granted_at tracking

📈 Phase 3 Completion Details

PRs Merged:

Test Coverage:

  • 73 Secret Management tests
  • 439 total tests (1381 assertions)
  • ≥80% coverage achieved

API Endpoints Added:

  • 5 Secret CRUD endpoints
  • 3 Secret Sharing endpoints
  • Full documentation in docs/guides/secret-sharing.md

🚫 Non-Goals (Future Epics)

  • Password generation UI (frontend feature)
  • Browser extension (separate project)
  • 2FA/OTP storage (Phase 5)
  • Secret templates (Phase 5)
  • Bulk import/export (Phase 5)
  • Secret history/versioning UI (Phase 4)

📋 Implementation Timeline

Phase 1 (Week 1-2): Secret Model + CRUD API - Issue #174 ✅ Complete
Phase 2 (Week 2-3): File Attachments API - Issue #175 ✅ Complete
Phase 3 (Week 3-4): Sharing & Access Control - Issue #182 ✅ Complete (19.11.2025)
Phase 4 (Week 4-5): Frontend Secret Vault UI - TBD 📅 Next

Total Estimated Effort: 4-5 weeks
Current Progress: ~75% (Phase 1, 2, 3 complete - Backend DONE)

🔗 Dependencies

Requires (Already Implemented):

Blocks:

Type: Epic
Priority: High (Core Business Feature)
Target Milestone: v0.3.0
Backend Status: ✅ COMPLETE (Phase 1-3 done)
Frontend Status: 📅 Pending (Phase 4 next)

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: securitypriority: hightype: feature

    Type

    No type

    Projects

    SecPal Roadmap

    Status

    🚧 In Progress

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions