capsium 0.1.2 → 0.3.0

data/lib/capsium/package/cipher.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "base64"
+require "fileutils"
+require "json"
+require "openssl"
+require "tmpdir"
+require "zip"
+
+module Capsium
+  class Package
+    # Encrypts and decrypts whole Capsium packages (05x-packaging
+    # "Encryption", 05x-security "Encrypted information").
+    #
+    # An encrypted .cap is a zip containing exactly:
+    #
+    #   metadata.json   (cleartext, per the standard: name/version stay
+    #                    readable without the key)
+    #   signature.json  (the encryption envelope)
+    #   package.enc     (AES-256-GCM ciphertext of the inner, plaintext
+    #                    .cap zip holding content/, the configuration
+    #                    files and data/)
+    #
+    # The envelope:
+    #
+    #   {"encryption": {"algorithm": "AES-256-GCM",
+    #                   "keyManagement": "RSA-OAEP-SHA256",
+    #                   "encryptedDek": <base64>, "iv": <base64>,
+    #                   "authTag": <base64>}}
+    #
+    # A random 256-bit data encryption key (DEK) encrypts the inner zip;
+    # the DEK is wrapped with the recipient's RSA public key using OAEP
+    # with SHA-256 (MGF1-SHA-256). The OCB/OpenPGP alternatives mentioned
+    # by the standard are intentionally out of scope.
+    class Cipher
+      ALGORITHM = "AES-256-GCM"
+      KEY_MANAGEMENT = "RSA-OAEP-SHA256"
+      ENCRYPTED_FILE = "package.enc"
+      ENVELOPE_FILE = "signature.json"
+      RSA_OPTIONS = { "rsa_padding_mode" => "oaep",
+                      "rsa_oaep_md" => "SHA256", "rsa_mgf1_md" => "SHA256" }.freeze
+
+      # Structural problems: unreadable input, missing zip entries,
+      # unsupported envelope algorithms, unloadable keys.
+      class CipherError < Capsium::Error; end
+
+      # An encrypted package was opened without a private key.
+      class KeyRequiredError < CipherError; end
+
+      # Decryption failed: wrong private key or tampered ciphertext.
+      class DecryptionError < CipherError; end
+
+      # Whether the path (.cap file or uncompressed directory) is an
+      # encrypted package, i.e. contains package.enc.
+      def self.encrypted?(path)
+        return File.file?(File.join(path, ENCRYPTED_FILE)) if File.directory?(path)
+        return false unless File.file?(path)
+
+        Zip::File.open(path) { |zip| !zip.find_entry(ENCRYPTED_FILE).nil? }
+      rescue Zip::Error
+        false
+      end
+
+      # Encrypts the package at source_path (a .cap file, or a package
+      # directory which is packed first) for the recipient's RSA public
+      # key (or X.509 certificate) and writes the encrypted .cap to
+      # output_path.
+      def encrypt(source_path, public_key_path, output_path)
+        public_key = load_public_key(public_key_path)
+        with_cap_file(source_path) do |cap_path|
+          envelope, ciphertext = encrypt_bytes(File.binread(cap_path), public_key)
+          write_encrypted_cap(output_path, read_source(cap_path, Package::METADATA_FILE),
+                              envelope, ciphertext)
+        end
+        output_path
+      end
+
+      # Decrypts the encrypted package at encrypted_path (.cap file or
+      # uncompressed directory) with the recipient's RSA private key and
+      # writes the plaintext .cap to output_path.
+      def decrypt(encrypted_path, private_key_path, output_path)
+        private_key = load_private_key(private_key_path)
+        envelope = load_envelope(encrypted_path)
+        ciphertext = read_source(encrypted_path, ENCRYPTED_FILE)
+        File.binwrite(output_path, decrypt_bytes(ciphertext, envelope, private_key))
+        output_path
+      end
+
+      # Decrypts an encrypted package into a fresh temporary directory
+      # and returns the directory path.
+      def self.decrypt_to_directory(source_path, private_key_path)
+        Dir.mktmpdir.tap do |tmp|
+          inner_cap = File.join(tmp, "inner.cap")
+          new.decrypt(source_path, private_key_path, inner_cap)
+          package_path = File.join(tmp, File.basename(source_path.to_s, ".cap"))
+          FileUtils.mkdir_p(package_path)
+          Packager.new.unpack(inner_cap, package_path)
+          FileUtils.rm_f(inner_cap)
+          return package_path
+        end
+      end
+
+      private
+
+      def with_cap_file(source_path)
+        return yield source_path if File.file?(source_path) && File.extname(source_path) == ".cap"
+        raise CipherError, "cannot encrypt: #{source_path}" unless File.directory?(source_path)
+
+        Dir.mktmpdir do |dir|
+          cap_path = File.join(dir, "inner.cap")
+          Packager.new.compress_package(Capsium::Package.new(source_path), cap_path)
+          yield cap_path
+        end
+      end
+
+      def encrypt_bytes(plaintext, public_key)
+        cipher = OpenSSL::Cipher.new(ALGORITHM.downcase)
+        cipher.encrypt
+        dek = cipher.random_key
+        iv = cipher.random_iv
+        ciphertext = cipher.update(plaintext) + cipher.final
+        envelope = EncryptionEnvelope.new(
+          algorithm: ALGORITHM, key_management: KEY_MANAGEMENT,
+          encrypted_dek: Base64.strict_encode64(public_key.encrypt(dek, RSA_OPTIONS)),
+          iv: Base64.strict_encode64(iv), auth_tag: Base64.strict_encode64(cipher.auth_tag)
+        )
+        [EncryptionConfig.new(encryption: envelope), ciphertext]
+      end
+
+      def decrypt_bytes(ciphertext, envelope, private_key)
+        dek = private_key.decrypt(Base64.strict_decode64(envelope.encrypted_dek), RSA_OPTIONS)
+        cipher = OpenSSL::Cipher.new(ALGORITHM.downcase)
+        cipher.decrypt
+        cipher.key = dek
+        cipher.iv = Base64.strict_decode64(envelope.iv)
+        cipher.auth_tag = Base64.strict_decode64(envelope.auth_tag)
+        cipher.update(ciphertext) + cipher.final
+      rescue ArgumentError
+        raise CipherError, "invalid Base64 in the encryption envelope"
+      rescue OpenSSL::PKey::PKeyError, OpenSSL::Cipher::CipherError
+        # DEK unwrap failure or GCM tag verification failure (wrong key
+        # or tampered ciphertext), or a malformed envelope iv/authTag.
+        raise DecryptionError, "decryption failed: wrong key or tampered package"
+      end
+
+      def write_encrypted_cap(output_path, metadata_json, envelope, ciphertext)
+        FileUtils.rm_f(output_path)
+        Zip::File.open(output_path, create: true) do |zip|
+          zip.get_output_stream(Package::METADATA_FILE) { |stream| stream.write(metadata_json) }
+          zip.get_output_stream(ENVELOPE_FILE) { |stream| stream.write(envelope.to_json) }
+          zip.get_output_stream(ENCRYPTED_FILE) { |stream| stream.write(ciphertext) }
+        end
+      end
+
+      def load_envelope(encrypted_path)
+        envelope = EncryptionConfig.from_json(read_source(encrypted_path, ENVELOPE_FILE)).encryption
+        return envelope if envelope && supported_envelope?(envelope)
+
+        raise CipherError, "missing or unsupported encryption envelope in: #{encrypted_path}"
+      rescue Lutaml::Model::Error, JSON::ParserError => e
+        raise CipherError, "invalid encryption envelope in #{encrypted_path}: #{e.message}"
+      end
+
+      def supported_envelope?(envelope)
+        [envelope.algorithm, envelope.key_management] == [ALGORITHM, KEY_MANAGEMENT]
+      end
+
+      def read_source(path, entry_name)
+        return File.binread(File.join(path, entry_name)) if File.directory?(path)
+
+        Zip::File.open(path) do |zip|
+          entry = zip.find_entry(entry_name)
+          raise CipherError, "entry missing in #{path}: #{entry_name}" unless entry
+
+          return entry.get_input_stream.read
+        end
+      rescue Errno::ENOENT, Zip::Error => e
+        raise CipherError, "cannot read #{entry_name} in #{path}: #{e.message}"
+      end
+
+      def load_public_key(public_key_path)
+        pem = File.read(public_key_path)
+        OpenSSL::PKey::RSA.new(pem)
+      rescue OpenSSL::PKey::PKeyError
+        OpenSSL::X509::Certificate.new(pem).public_key
+      rescue OpenSSL::X509::CertificateError, Errno::ENOENT
+        raise CipherError, "cannot load public key or certificate: #{public_key_path}"
+      end
+
+      def load_private_key(private_key_path)
+        OpenSSL::PKey::RSA.new(File.read(private_key_path))
+      rescue OpenSSL::PKey::PKeyError, Errno::ENOENT
+        raise CipherError, "cannot load private key: #{private_key_path}"
+      end
+    end
+  end
+end

data/lib/capsium/package/composition.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # Composite-package support (ARCHITECTURE.md section 4a), mixed into
+    # Package: metadata.dependencies resolution against a package store
+    # and load-time validation of dependency resource references.
+    module Composition
+      private
+
+      # Resolves metadata.dependencies against the package store (the
+      # `store` argument, else CAPSIUM_STORE). Each resolved dependency
+      # loads recursively with an extended circularity chain; its
+      # exported content becomes lower read-only layers of this
+      # package's merged view.
+      def resolve_dependencies(store, chain)
+        declared = @metadata.dependencies
+        return [] if declared.empty?
+
+        resolver = DependencyResolver.new(store || Store.default)
+        chain += [@metadata.guid]
+        declared.map do |guid, range|
+          cap_path = resolver.resolve_path(guid, range, chain: chain)
+          ResolvedDependency.new(
+            guid: guid, range: range, path: cap_path,
+            package: Package.new(cap_path, store: resolver.store,
+                                           dependency_chain: chain)
+          )
+        end
+      end
+
+      # Every route resource given as a URI ("<dependency-guid>/<path>")
+      # must address a resolved dependency and a resource that dependency
+      # exports; anything else is a load-time error (section 4a).
+      def validate_dependency_references!
+        @routes.config.routes.each do |route|
+          reference = route.resource
+          next unless route.dependency_reference?
+
+          dependency = dependency_for(reference)
+          unless dependency
+            raise DependencyError,
+                  "route #{route.path} references unknown dependency: #{reference}"
+          end
+
+          validate_dependency_reference(route, dependency, reference)
+        end
+      end
+
+      def validate_dependency_reference(route, dependency, reference)
+        inner = reference.delete_prefix("#{dependency.guid}/")
+        return if dependency.package.merged_view(exported_only: true).resolve(inner)
+
+        if dependency.package.merged_view.resolve(inner)
+          raise DependencyVisibilityError,
+                "route #{route.path} references a private resource of " \
+                "dependency #{dependency.guid}: #{inner}"
+        end
+        raise DependencyError,
+              "route #{route.path} references a resource missing from " \
+              "dependency #{dependency.guid}: #{inner}"
+      end
+
+      def dependency_for(reference)
+        @resolved_dependencies
+          .sort_by { |dependency| -dependency.guid.length }
+          .find { |dependency| reference.start_with?("#{dependency.guid}/") }
+      end
+
+      def dependency_views
+        @resolved_dependencies.map do |dependency|
+          [dependency.guid, dependency.package.merged_view(exported_only: true)]
+        end
+      end
+    end
+  end
+end

data/lib/capsium/package/dataset.rb

@@ -1,72 +1,105 @@
 # frozen_string_literal: true
 
-require "json"
-require "yaml"
 require "csv"
-require "sqlite3"
-require "shale"
+require "forwardable"
+require "json"
 require "json-schema"
-require_relative "dataset_config"
+require "sqlite3"
+require "yaml"
 
 module Capsium
   class Package
+    # A loaded dataset. "source"/"schemaFile"/"databaseFile" are
+    # package-relative paths (ARCHITECTURE.md section 5), resolved against
+    # the package directory.
     class Dataset
-      attr_reader :config, :data, :data_path
+      attr_reader :name, :config, :data, :package_path
 
       extend Forwardable
 
       def_delegators :@config, :to_json
 
-      def initialize(config:, data_path: nil)
+      def initialize(name:, config:, package_path:)
+        @name = name
         @config = config
-        @data_path = data_path || config.source
+        @package_path = package_path
         @data = load_data
       end
 
+      def source_path
+        File.join(@package_path, @config.backing_file)
+      end
+
+      def schema_path
+        return unless @config.schema_file
+
+        File.join(@package_path, @config.schema_file)
+      end
+
       def load_data
+        return nil unless File.file?(source_path)
+
         case @config.format
-        when "yaml" then YAML.load_file(@data_path)
-        when "json" then JSON.parse(File.read(@data_path))
-        when "csv" then CSV.read(@data_path, headers: true)
-        when "tsv" then CSV.read(@data_path, col_sep: "\t", headers: true)
+        when "yaml" then YAML.load_file(source_path)
+        when "json" then JSON.parse(File.read(source_path))
+        when "csv" then CSV.read(source_path, headers: true)
+        when "tsv" then CSV.read(source_path, col_sep: "\t", headers: true)
         when "sqlite" then load_sqlite_data
         else
-          raise "Unsupported data file type: #{@config.format}"
+          raise Error, "Unsupported data file type: #{@config.format}"
         end
       end
 
       def validate
-        return unless @config.schema
+        return true unless @config.schema_file && @config.schema_type == "json-schema"
 
-        schema_path = File.join(File.dirname(@data_path), @config.schema)
-        schema = YAML.load_file(schema_path) if @config.format == "yaml"
-        schema = JSON.parse(File.read(schema_path)) if @config.format == "json"
+        JSON::Validator.validate!(load_schema, @data.to_json)
+      end
 
-        case @config.format
-        when "yaml" then YAML.load_file(@data_path)
-        when "json" then JSON.parse(File.read(@data_path))
-        else
-          raise "Validation is only supported for YAML and JSON formats"
+      # File-existence and schema validations for this dataset. Returns a
+      # list of human-readable problems; empty when valid.
+      def validation_errors
+        problems = []
+        unless File.file?(source_path)
+          problems << "dataset source missing on disk: #{@config.backing_file}"
         end
-
-        JSON::Validator.validate!(schema, @data.to_json)
+        problems.concat(schema_validation_errors)
+        problems
       end
 
-      def save_to_file(output_path)
-        File.write(output_path, to_json)
+      private
+
+      def schema_validation_errors
+        return [] unless @config.schema_file
+        unless File.file?(schema_path)
+          return ["dataset schema missing on disk: #{@config.schema_file}"]
+        end
+
+        validate
+        []
+      rescue JSON::Schema::ValidationError => e
+        ["dataset #{@name} fails schema validation: #{e.message}"]
       end
 
-      private
+      def load_schema
+        case File.extname(schema_path).downcase
+        when ".yaml", ".yml" then YAML.load_file(schema_path)
+        else JSON.parse(File.read(schema_path))
+        end
+      end
 
       def load_sqlite_data
-        db = SQLite3::Database.new(@data_path)
-        tables = db.execute("SELECT name FROM sqlite_master WHERE type='table';")
-        data = {}
-        tables.each do |table|
-          table_name = table.first
-          data[table_name] = db.execute("SELECT * FROM #{table_name};")
+        db = SQLite3::Database.new(source_path)
+        tables = @config.table ? [@config.table] : sqlite_tables(db)
+        tables.to_h do |table_name|
+          [table_name, db.execute("SELECT * FROM #{table_name};")]
         end
-        data
+      ensure
+        db&.close
+      end
+
+      def sqlite_tables(db)
+        db.execute("SELECT name FROM sqlite_master WHERE type='table';").map(&:first)
       end
     end
   end

data/lib/capsium/package/dependency_resolver.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # Base error for composite-package dependency resolution
+    # (ARCHITECTURE.md section 4a).
+    class DependencyError < Capsium::Error; end
+
+    # No package in the store provides the dependency GUID.
+    class DependencyNotFoundError < DependencyError; end
+
+    # The store provides the GUID but no version satisfies the range.
+    class UnsatisfiableDependencyError < DependencyError; end
+
+    # A dependency cycle was detected while resolving.
+    class CircularDependencyError < DependencyError; end
+
+    # A dependent route references a dependency resource that is not
+    # exported (private) and therefore not visible to dependents.
+    class DependencyVisibilityError < DependencyError; end
+
+    # One resolved dependency: the declared GUID and range, the .cap it
+    # resolved to and the loaded package.
+    ResolvedDependency = Data.define(:guid, :range, :path, :package) do
+      def version
+        package.metadata.version
+      end
+    end
+
+    # Orchestrates metadata.dependencies resolution against a package
+    # store: circularity checks plus store lookup. Package loads the
+    # resolved .cap itself (recursively, with an extended chain).
+    class DependencyResolver
+      attr_reader :store
+
+      def initialize(store)
+        if store.nil?
+          raise DependencyError,
+                "metadata.dependencies declared but no package store " \
+                "configured (set CAPSIUM_STORE or pass store:)"
+        end
+
+        @store = store.is_a?(Store) ? store : Store.new(store.to_s)
+      end
+
+      # The newest store .cap satisfying the dependency. Raises
+      # CircularDependencyError when the GUID is already being resolved
+      # up-chain, DependencyNotFoundError when the store has no package
+      # for it and UnsatisfiableDependencyError when no stored version
+      # satisfies the range.
+      def resolve_path(guid, range, chain:)
+        if chain.include?(guid)
+          raise CircularDependencyError,
+                "circular dependency: #{(chain + [guid]).join(' -> ')}"
+        end
+
+        @store.find(guid, range)
+      end
+    end
+  end
+end

data/lib/capsium/package/encryption_config.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Capsium
+  class Package
+    # The "encryption" object of signature.json in an encrypted package
+    # (05x-packaging "Encryption"): the AES-256-GCM envelope with the
+    # RSA-OAEP-SHA256 wrapped data encryption key (DEK), all binary
+    # values Base64-encoded.
+    class EncryptionEnvelope < Lutaml::Model::Serializable
+      attribute :algorithm, :string
+      attribute :key_management, :string
+      attribute :encrypted_dek, :string
+      attribute :iv, :string
+      attribute :auth_tag, :string
+
+      json do
+        map :algorithm, to: :algorithm
+        map "keyManagement", to: :key_management
+        map "encryptedDek", to: :encrypted_dek
+        map :iv, to: :iv
+        map "authTag", to: :auth_tag
+      end
+    end
+
+    # The signature.json file of an encrypted package. In this phase it
+    # carries only the encryption envelope (digital signatures over
+    # encrypted packages are a later phase).
+    class EncryptionConfig < Lutaml::Model::Serializable
+      attribute :encryption, EncryptionEnvelope
+
+      json do
+        map :encryption, to: :encryption
+      end
+    end
+  end
+end

data/lib/capsium/package/manifest.rb

@@ -1,51 +1,56 @@
 # frozen_string_literal: true
 
-# lib/capsium/package/manifest.rb
-require "json"
+require "forwardable"
 require "marcel"
-require "shale"
-require_relative "manifest_config"
+require "pathname"
 
 module Capsium
   class Package
     class Manifest
       extend Forwardable
-      attr_accessor :path, :content_path, :config
 
-      def_delegators :@config, :to_json
+      attr_reader :path, :content_path, :config
+
+      def_delegators :@config, :to_hash
 
       def initialize(path)
         @path = path
         @content_path = File.join(File.dirname(@path), Package::CONTENT_DIR)
-
         @config = if File.exist?(path)
                     ManifestConfig.from_json(File.read(path))
                   else
-                    ManifestConfig.new(content: generate_manifest)
+                    ManifestConfig.new(resources: generate_manifest)
                   end
       end
 
+      # Auto-generation (ARCHITECTURE.md section 3): scan content/
+      # recursively, detect MIME types, default visibility "exported",
+      # deterministic (sorted) output.
       def generate_manifest
-        files = Dir[File.join(@content_path, "**", "*")].reject do |f|
-          File.directory?(f)
+        content_files.sort.to_h do |file_path|
+          [relative_path(file_path),
+           Resource.new(type: mime_from_path(file_path), visibility: "exported")]
         end
+      end
 
-        files.sort.map do |file_path|
-          ManifestConfigItem.new(
-            file: relative_path(file_path),
-            mime: mime_from_path(file_path),
-          )
-        end
+      def resources
+        @config.resources
       end
 
-      def lookup(filename)
-        @config.content.detect do |data_item|
-          data_item.file == filename
-        end
+      def lookup(path)
+        resources[path]
+      end
+
+      def type_for(path)
+        resource = lookup(path)
+        resource&.type
+      end
+
+      def to_json(*_args)
+        @config.to_json
       end
 
       def save_to_file(output_path = @path)
-        @config.content.sort_by!(&:file)
         File.write(output_path, to_json)
       end
 
@@ -65,11 +70,17 @@ module Capsium
 
       private
 
+      def content_files
+        Dir.glob(File.join(@content_path, "**", "*")).select do |file|
+          File.file?(file)
+        end
+      end
+
       def mime_from_path(path)
         Marcel::MimeType.for(
           Pathname.new(path),
           name: File.basename(path),
-          extension: File.extname(path),
+          extension: File.extname(path)
         )
       end
     end

data/lib/capsium/package/manifest_config.rb

@@ -1,17 +1,62 @@
-require "shale"
+# frozen_string_literal: true
+
+require "json"
+require "lutaml/model"
 
 module Capsium
   class Package
-    class ManifestConfigItem < Shale::Mapper
-      attribute :file, Shale::Type::String
-      attribute :mime, Shale::Type::String
+    # A single manifest resource entry (ARCHITECTURE.md section 3).
+    class Resource < Lutaml::Model::Serializable
+      VISIBILITIES = %w[exported private].freeze
+
+      attribute :type, :string
+      attribute :visibility, :string, values: VISIBILITIES, default: "exported"
+      attribute :version, :string
+
+      json do
+        map :type, to: :type
+        map :visibility, to: :visibility
+        map :version, to: :version
+      end
     end
 
-    class ManifestConfig < Shale::Mapper
-      attribute :content, ManifestConfigItem, collection: true
+    # Canonical manifest.json model: an object keyed by package-relative
+    # resource path. The legacy gem form ({"content": [{file, mime}]}) is
+    # accepted on read and normalized; writers emit only the object form.
+    class ManifestConfig < Lutaml::Model::Serializable
+      attribute :resources, :hash, default: {}
+
+      json do
+        map :resources, with: { from: :resources_from_json, to: :resources_to_json }
+      end
+
+      def self.from_json(json)
+        doc = JSON.parse(json)
+        doc["resources"] ||= legacy_resources(doc.delete("content")) if doc.key?("content")
+        super(JSON.generate(doc))
+      end
+
+      def self.legacy_resources(content)
+        (content || []).to_h do |item|
+          [item["file"], { "type" => item["mime"], "visibility" => "exported" }]
+        end
+      end
+      private_class_method :legacy_resources
+
+      def resources_from_json(model, value)
+        model.resources = (value || {}).to_h do |path, attributes|
+          [path, Resource.from_json(JSON.generate(attributes))]
+        end
+      end
+
+      def resources_to_json(model, doc)
+        doc["resources"] = model.resources.sort.to_h do |path, resource|
+          [path, JSON.parse(resource.to_json)]
+        end
+      end
 
       def sort!
-        @content.sort_by!(&:file)
+        self.resources = resources.sort.to_h
         self
       end
     end