doc_vault 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fda91ff32053768d255c4761dae6e0650a7a9fbf04a36a0d25fe20f240ed5fcb
+  data.tar.gz: 74aeecbb04a088aeaea7c2f76e60eb3930165a044b13e3e62a7ca6c73c3de163
+SHA512:
+  metadata.gz: 7ed12ed1b2a51797ed200e281509c23097ab07bec11006dec0d7ba33ed3bec3c7dc9bafd74bf7a221e8ba961e99552a9be7842b039ed0acd54b6902751bfc09c
+  data.tar.gz: bc8d81a0230d353a7d348390b76a6af6ca659145dc80c369bd3364587c6e7fdc26b70a8ad0c75d835840d3401f80fa8460932113b6624c707bad18b1ca289ca9

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Jared Fraser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,172 @@
+# DocVault
+
+NOTE: THIS IS IN-DEVELOPMENT SOFTWARE, PLEASE DO NOT USE FOR ANYTHING SENSITIVE
+
+DocVault is a Ruby gem that provides a simple interface for storing and retrieving encrypted data or files in one or multiple SQLite databases.
+
+This gem is useful for ephemeral storage of sensitive data in text or file format that needs to be readily accessible. It enables seperation of data and per-user encryption keys. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'doc_vault'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install doc_vault
+```
+
+## Usage
+
+### Basic Usage
+
+Store a document:
+
+```ruby
+require 'doc_vault'
+
+# Store a document
+DocVault.store(
+  "This is my secret document",
+  id: "document_123",
+  bucket: "my_database",
+  key: "my_encryption_key"
+)
+```
+
+Retrieve a document:
+
+```ruby
+# Retrieve the document
+document = DocVault.retrieve(
+  "document_123",
+  bucket: "my_database", 
+  key: "my_encryption_key"
+)
+
+puts document # => "This is my secret document"
+```
+
+### Multiple Databases
+
+You can organize documents across different databases:
+
+```ruby
+# Store in different databases
+DocVault.store("Personal note", id: "note1", bucket: "personal", key: "personal_key")
+DocVault.store("Work document", id: "doc1", bucket: "work", key: "work_key")
+
+# Retrieve from specific databases
+personal_note = DocVault.retrieve("note1", bucket: "personal", key: "personal_key")
+work_doc = DocVault.retrieve("doc1", bucket: "work", key: "work_key")
+```
+
+### File Storage
+
+DocVault can store and retrieve File and Tempfile objects while preserving metadata:
+
+```ruby
+# Store a File object
+file = File.open("document.pdf", "rb")
+DocVault.store(file, id: "pdf_doc", bucket: "files", key: "file_key")
+file.close
+
+# Retrieve returns a Tempfile with the same content
+retrieved_file = DocVault.retrieve("pdf_doc", bucket: "files", key: "file_key")
+puts retrieved_file.class # => Tempfile
+puts retrieved_file.read  # => Original PDF content
+
+# Store a Tempfile - upload is a JPEG File object
+DocVault.store(upload, id: "photo", bucket: "uploads", key: "upload_key")
+upload.close
+
+# Retrieve with preserved metadata
+photo = DocVault.retrieve("photo", bucket: "uploads", key: "upload_key")
+puts photo.original_filename # => "photo.jpg"
+puts photo.content_type      # => "image/jpeg"
+puts File.extname(photo.path) # => ".jpg"
+```
+
+### Document Updates
+
+Documents with the same ID will be replaced:
+
+```ruby
+# Store initial document
+DocVault.store("Version 1", id: "doc", bucket: "db", key: "key")
+
+# Update the document
+DocVault.store("Version 2", id: "doc", bucket: "db", key: "key")
+
+# Retrieve returns the latest version
+doc = DocVault.retrieve("doc", bucket: "db", key: "key")
+puts doc # => "Version 2"
+```
+
+### Error Handling
+
+DocVault provides specific error types for different failure scenarios:
+
+```ruby
+begin
+  DocVault.retrieve("nonexistent", bucket: "db", key: "key")
+rescue DocVault::DocumentNotFoundError => e
+  puts "Document not found: #{e.message}"
+end
+
+begin
+  DocVault.retrieve("doc_id", bucket: "db", key: "wrong_key")
+rescue DocVault::EncryptionError => e
+  puts "Decryption failed: #{e.message}"
+end
+
+begin
+  DocVault.store("", id: "", bucket: "db", key: "key")
+rescue ArgumentError => e
+  puts "Invalid arguments: #{e.message}"
+end
+```
+
+### Configuration
+
+You can configure where DocVault stores its database files:
+
+```ruby
+# Configure database path using a block
+DocVault.configure do |config|
+  config.database_path = "/path/to/your/databases"
+end
+
+# Or configure directly
+DocVault.configuration.database_path = "/path/to/your/databases"
+```
+
+## Security
+
+- Documents are encrypted using AES-256-GCM
+- SQLite databases are created locally and can be secured using standard file system permissions
+- Database files can be culled with standard file retention tools
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/modsognir/doc_vault.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/doc_vault/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DocVault
+  class Configuration
+    attr_reader :database_path
+
+    def initialize
+      @database_path = Dir.pwd
+    end
+
+    def database_path=(path)
+      raise ArgumentError, "Database path cannot be nil" if path.nil?
+      raise ArgumentError, "Database path must be a valid directory" unless Dir.exist?(path) || path == Dir.pwd
+
+      @database_path = File.expand_path(path)
+    end
+
+    def full_database_path(db_name)
+      File.join(@database_path, "#{db_name}.db")
+    end
+  end
+end

data/lib/doc_vault/database.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "sqlite3"
+
+module DocVault
+  class Database
+    def initialize(db_name)
+      @db_name = db_name
+      @db_path = DocVault.configuration.full_database_path(db_name)
+      create_table_if_not_exists
+    end
+
+    def store(id, encrypted_document)
+      result = db.execute("INSERT OR REPLACE INTO documents (id, content) VALUES (?, ?)", [id, encrypted_document])
+      id if result
+    rescue SQLite3::Exception => e
+      raise DatabaseError, "Failed to store document: #{e.message}"
+    end
+
+    def retrieve(id)
+      result = db.execute("SELECT content FROM documents WHERE id = ?", [id])
+      result.empty? ? nil : result[0][0]
+    rescue SQLite3::Exception => e
+      raise DatabaseError, "Failed to retrieve document: #{e.message}"
+    end
+
+    private
+
+    def db
+      @db ||= SQLite3::Database.new(@db_path)
+    end
+
+    def create_table_if_not_exists
+      db.execute <<-SQL
+        CREATE TABLE IF NOT EXISTS documents (
+          id TEXT PRIMARY KEY,
+          content TEXT NOT NULL,
+          created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+          updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+        )
+      SQL
+    rescue SQLite3::Exception => e
+      raise DatabaseError, "Failed to create table: #{e.message}"
+    end
+  end
+end

data/lib/doc_vault/document_serializer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "tempfile"
+
+module DocVault
+  class DocumentSerializer
+    def self.serialize(document)
+      case document
+      when File, Tempfile
+        serialize_file(document)
+      when String
+        serialize_string(document)
+      else
+        raise ArgumentError, "Document must be a String, File, or Tempfile"
+      end
+    end
+
+    def self.deserialize(data)
+      parsed = JSON.parse(data)
+
+      case parsed["type"]
+      when "file"
+        deserialize_file(parsed)
+      when "string"
+        parsed["content"]
+      else
+        raise ArgumentError, "Unknown document type: #{parsed["type"]}"
+      end
+    rescue JSON::ParserError
+      raise ArgumentError, "Invalid serialized document data"
+    end
+
+    class << self
+      private
+
+      def serialize_file(file)
+        file.rewind
+        content = file.read
+        file.rewind
+
+        metadata = {
+          type: "file",
+          content: content,
+          original_filename: file.respond_to?(:original_filename) ? file.original_filename : nil,
+          content_type: file.respond_to?(:content_type) ? file.content_type : nil,
+          path: file.respond_to?(:path) ? file.path : nil,
+          size: content.length
+        }
+
+        JSON.generate(metadata)
+      end
+
+      def serialize_string(string)
+        JSON.generate({
+          type: "string",
+          content: string
+        })
+      end
+
+      def deserialize_file(parsed)
+        tempfile = Tempfile.new(["doc_vault", extract_extension(parsed)])
+        tempfile.binmode
+        tempfile.write(parsed["content"])
+        tempfile.rewind
+
+        # Add metadata as singleton methods if available
+        if parsed["original_filename"]
+          tempfile.define_singleton_method(:original_filename) { parsed["original_filename"] }
+        end
+
+        if parsed["content_type"]
+          tempfile.define_singleton_method(:content_type) { parsed["content_type"] }
+        end
+
+        tempfile
+      end
+
+      def extract_extension(parsed)
+        return "" unless parsed["original_filename"] || parsed["path"]
+
+        filename = parsed["original_filename"] || parsed["path"]
+        File.extname(filename)
+      end
+    end
+  end
+end

data/lib/doc_vault/encryption.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module DocVault
+  class Encryption
+    ALGORITHM = "AES-256-GCM"
+    IV_SIZE = 12
+    AUTH_TAG_SIZE = 16
+
+    def self.encrypt(data, key)
+      cipher = OpenSSL::Cipher.new(ALGORITHM)
+      cipher.encrypt
+
+      salt = OpenSSL::Random.random_bytes(16)
+      derived_key = OpenSSL::PKCS5.pbkdf2_hmac(key, salt, 100_000, 32, OpenSSL::Digest.new("SHA256"))
+      cipher.key = derived_key
+
+      iv = cipher.random_iv
+      encrypted = cipher.update(data) + cipher.final
+      auth_tag = cipher.auth_tag
+
+      combined = salt + iv + auth_tag + encrypted
+      Base64.strict_encode64(combined)
+    rescue OpenSSL::Cipher::CipherError
+      raise EncryptionError, "Encryption failed"
+    end
+
+    def self.decrypt(encrypted_data, key)
+      combined = Base64.strict_decode64(encrypted_data)
+
+      cipher = OpenSSL::Cipher.new(ALGORITHM)
+      cipher.decrypt
+
+      salt = combined[0, 16]
+      iv = combined[16, IV_SIZE]
+      auth_tag = combined[16 + IV_SIZE, AUTH_TAG_SIZE]
+      encrypted = combined[16 + IV_SIZE + AUTH_TAG_SIZE..]
+
+      derived_key = OpenSSL::PKCS5.pbkdf2_hmac(key, salt, 100_000, 32, OpenSSL::Digest.new("SHA256"))
+      cipher.key = derived_key
+      cipher.iv = iv
+      cipher.auth_tag = auth_tag
+
+      cipher.update(encrypted) + cipher.final
+    rescue OpenSSL::Cipher::CipherError, ArgumentError
+      raise EncryptionError, "Decryption failed"
+    end
+  end
+end

data/lib/doc_vault/retrieve_document.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module DocVault
+  class RetrieveDocument
+    def self.call(id:, bucket:, key:)
+      new(id:, bucket:, key:).call
+    end
+
+    def initialize(id:, bucket:, key:)
+      @id = id
+      @bucket = bucket
+      @key = key
+      validate_params
+    end
+
+    def call
+      database = Database.new(@bucket)
+      encrypted_doc = database.retrieve(@id)
+      raise DocumentNotFoundError, "Document with id '#{@id}' not found" unless encrypted_doc
+
+      decrypted_doc = Encryption.decrypt(encrypted_doc, @key)
+      DocumentSerializer.deserialize(decrypted_doc)
+    end
+
+    private
+
+    def validate_params
+      raise ArgumentError, "Document ID cannot be nil or empty" if @id.nil? || @id.to_s.strip.empty?
+      raise ArgumentError, "Database name cannot be nil or empty" if @bucket.nil? || @bucket.to_s.strip.empty?
+      raise ArgumentError, "Encryption key cannot be nil or empty" if @key.nil? || @key.to_s.strip.empty?
+    end
+  end
+end

data/lib/doc_vault/store_document.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module DocVault
+  class StoreDocument
+    def self.call(document:, id:, bucket:, key:)
+      new(document:, id:, bucket:, key:).call
+    end
+
+    def initialize(document:, id:, bucket:, key:)
+      @document = document
+      @id = id
+      @bucket = bucket
+      @key = key
+      validate_params
+    end
+
+    def call
+      database = Database.new(@bucket)
+      serialized_doc = DocumentSerializer.serialize(@document)
+      encrypted_doc = Encryption.encrypt(serialized_doc, @key)
+      database.store(@id, encrypted_doc)
+    end
+
+    private
+
+    def validate_params
+      raise ArgumentError, "Document cannot be nil" if @document.nil?
+      raise ArgumentError, "Document ID cannot be nil or empty" if @id.nil? || @id.to_s.strip.empty?
+      raise ArgumentError, "Database name cannot be nil or empty" if @bucket.nil? || @bucket.to_s.strip.empty?
+      raise ArgumentError, "Encryption key cannot be nil or empty" if @key.nil? || @key.to_s.strip.empty?
+
+      unless @document.is_a?(String) || @document.is_a?(File) || @document.is_a?(Tempfile)
+        raise ArgumentError, "Document must be a String, File, or Tempfile"
+      end
+    end
+  end
+end

data/lib/doc_vault/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DocVault
+  VERSION = "0.1.0"
+end

data/lib/doc_vault.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "doc_vault/version"
+require_relative "doc_vault/configuration"
+require_relative "doc_vault/database"
+require_relative "doc_vault/encryption"
+require_relative "doc_vault/document_serializer"
+require_relative "doc_vault/store_document"
+require_relative "doc_vault/retrieve_document"
+require "sqlite3"
+
+module DocVault
+  class Error < StandardError; end
+
+  class DatabaseError < Error; end
+
+  class EncryptionError < Error; end
+
+  class DocumentNotFoundError < Error; end
+
+  def self.store(document, id:, bucket:, key:)
+    StoreDocument.call(document:, id:, bucket:, key:)
+  end
+
+  def self.retrieve(id, bucket:, key:)
+    RetrieveDocument.call(id:, bucket:, key:)
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: doc_vault
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jared Fraser
+bindir: exe
+cert_chain: []
+date: 2025-08-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: Store and retrieve encrypted documents in SQLite
+email:
+- dev@jsf.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/doc_vault.rb
+- lib/doc_vault/configuration.rb
+- lib/doc_vault/database.rb
+- lib/doc_vault/document_serializer.rb
+- lib/doc_vault/encryption.rb
+- lib/doc_vault/retrieve_document.rb
+- lib/doc_vault/store_document.rb
+- lib/doc_vault/version.rb
+homepage: https://github.com/modsognir/doc_vault
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/modsognir/doc_vault
+  source_code_uri: https://github.com/modsognir/doc_vault
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Store and retrieve encrypted documents in SQLite
+test_files: []