capsium 0.2.0 → 0.6.0

data/lib/capsium/package/signer.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Capsium
+  class Package
+    # Signs and verifies Capsium packages with RSA-SHA256 digital
+    # signatures (05x-packaging "Digital Signature Using X.509",
+    # 05x-security "Digital Signatures").
+    #
+    # Signed payload construction (deterministic, openssl-verifiable): the
+    # concatenation, in sorted package-relative path order, of the raw
+    # bytes of every file covered by the security.json integrity checksums
+    # — i.e. every package file except security.json and signature.sig.
+    # The signature itself is the raw RSA-SHA256 signature over that
+    # payload, stored in signature.sig. Equivalent openssl verification:
+    #
+    #   openssl dgst -sha256 -verify pubkey.pem -signature signature.sig payload.bin
+    #
+    # where payload.bin is the concatenation described above.
+    class Signer
+      ALGORITHM = "RSA-SHA256"
+      MIN_KEY_BITS = 2048
+
+      # Package-relative name of the embedded public key PEM recorded in
+      # security.json digitalSignatures.publicKey.
+      PUBLIC_KEY_FILE = "signature.pub.pem"
+
+      # Structural problems: no signature declared, missing signature or
+      # key files, unloadable keys, checksum-covered files missing.
+      class SignatureError < Capsium::Error; end
+
+      # A signature is declared but does not match the package contents.
+      class SignatureMismatchError < SignatureError; end
+
+      # Signature operations requested on a package whose security.json
+      # declares no digitalSignatures.
+      class UnsignedPackageError < SignatureError; end
+
+      attr_reader :package_path
+
+      def initialize(package_path)
+        @package_path = package_path
+      end
+
+      # Signs a package directory in place, or a .cap file (unpacked,
+      # signed, recompressed). Returns the signed path.
+      def self.sign_package(path, private_key_path, certificate_path = nil)
+        return new(path).sign(private_key_path, certificate_path) unless cap?(path)
+
+        Packager.new.transform_cap(path) { |dir| new(dir).sign(private_key_path, certificate_path) }
+        path
+      end
+
+      # Verifies the declared signature of a package directory or .cap
+      # file (false on mismatch; raises typed SignatureError subclasses
+      # on structural problems, e.g. an unsigned package). The signer is
+      # selected from the declared digitalSignatures certificateType:
+      # OpenPGP packages verify through OpenPgpSigner.
+      def self.verify_package(path, public_key_path = nil)
+        return signer_class_for(path).new(path).verify(public_key_path) unless cap?(path)
+
+        Packager.new.with_unpacked_cap(path) do |dir|
+          signer_class_for(dir).new(dir).verify(public_key_path)
+        end
+      end
+
+      # The signer class matching a package's declared signature scheme:
+      # OpenPgpSigner when security.json declares
+      # digitalSignatures.certificateType "OpenPGP", Signer otherwise.
+      def self.signer_class_for(package_path)
+        security = Security.new(File.join(package_path, Package::SECURITY_FILE))
+        return OpenPgpSigner if security.digital_signatures&.certificate_type ==
+                                OpenPgpSigner::CERTIFICATE_TYPE
+
+        self
+      end
+
+      def self.cap?(path)
+        File.extname(path) == ".cap"
+      end
+      private_class_method :cap?
+
+      # Signs the package directory in place: embeds the public key PEM,
+      # regenerates security.json (checksums plus digitalSignatures) and
+      # writes the raw RSA-SHA256 signature to signature.sig. When a
+      # certificate is given it must match the private key, and the
+      # certificate's public key is embedded instead.
+      def sign(private_key_path, certificate_path = nil)
+        private_key = load_private_key(private_key_path)
+        File.write(public_key_path, public_pem_for(private_key, certificate_path))
+        security = Security.generate(@package_path, digital_signatures: digital_signatures)
+        security.save_to_file
+        File.binwrite(signature_path, private_key.sign("SHA256", payload(security)))
+        signature_path
+      end
+
+      # True when the declared signature verifies against the payload.
+      # Without an explicit key path, the embedded public key is used.
+      # Raises typed SignatureError subclasses on structural problems.
+      def verify(public_key_path = nil)
+        signature = read_signature
+        data = payload(declared_security)
+        public_key(public_key_path).verify("SHA256", signature, data)
+      rescue OpenSSL::PKey::PKeyError
+        false
+      end
+
+      def verify!(public_key_path = nil)
+        return true if verify(public_key_path)
+
+        raise SignatureMismatchError,
+              "digital signature does not match the package contents"
+      end
+
+      def signed?
+        declared_security.signed?
+      end
+
+      private
+
+      def declared_security
+        Security.new(File.join(@package_path, Package::SECURITY_FILE))
+      end
+
+      def digital_signatures
+        DigitalSignatures.new(public_key: PUBLIC_KEY_FILE, signature_file: Package::SIGNATURE_FILE)
+      end
+
+      # The canonical signed payload: the concatenation, in sorted
+      # package-relative path order, of the bytes of every file covered by
+      # the integrity checksums.
+      def payload(security)
+        security.checksums.keys.sort.map do |relative_path|
+          file_path = File.join(@package_path, relative_path)
+          unless File.file?(file_path)
+            raise SignatureError, "file covered by checksums is missing: #{relative_path}"
+          end
+
+          File.binread(file_path)
+        end.join
+      end
+
+      def read_signature
+        unless signed?
+          raise UnsignedPackageError,
+                "package is not signed (security.json declares no digitalSignatures)"
+        end
+        return File.binread(signature_path) if File.file?(signature_path)
+
+        raise SignatureError, "signature file missing: #{signature_file_name}"
+      end
+
+      def signature_file_name
+        declared_security.digital_signatures.signature_file || Package::SIGNATURE_FILE
+      end
+
+      def signature_path
+        File.join(@package_path, signature_file_name)
+      end
+
+      def public_key_path
+        File.join(@package_path, PUBLIC_KEY_FILE)
+      end
+
+      def public_key(public_key_path)
+        pem, source = public_key_pem(public_key_path)
+        OpenSSL::PKey::RSA.new(pem)
+      rescue OpenSSL::PKey::PKeyError
+        certificate_public_key(pem, source)
+      end
+
+      def public_key_pem(public_key_path)
+        return [File.read(public_key_path), public_key_path] if public_key_path
+
+        embedded = declared_security.digital_signatures&.public_key || PUBLIC_KEY_FILE
+        embedded_path = File.join(@package_path, embedded)
+        return [File.read(embedded_path), embedded] if File.file?(embedded_path)
+
+        raise SignatureError, "public key file missing: #{embedded}"
+      end
+
+      def certificate_public_key(pem, source)
+        OpenSSL::X509::Certificate.new(pem).public_key
+      rescue OpenSSL::X509::CertificateError
+        raise SignatureError, "cannot load public key or certificate: #{source}"
+      end
+
+      def load_private_key(private_key_path)
+        key = OpenSSL::PKey::RSA.new(File.read(private_key_path))
+        return key if key.n.num_bits >= MIN_KEY_BITS
+
+        raise SignatureError, "RSA key too short: minimum #{MIN_KEY_BITS} bits required"
+      rescue OpenSSL::PKey::PKeyError, Errno::ENOENT
+        raise SignatureError, "cannot load private key: #{private_key_path}"
+      end
+
+      def public_pem_for(private_key, certificate_path)
+        return private_key.public_key.to_pem unless certificate_path
+
+        certificate = load_certificate(certificate_path)
+        unless certificate.check_private_key(private_key)
+          raise SignatureError, "certificate does not match the private key: #{certificate_path}"
+        end
+
+        certificate.public_key.to_pem
+      end
+
+      def load_certificate(certificate_path)
+        OpenSSL::X509::Certificate.new(File.read(certificate_path))
+      rescue OpenSSL::X509::CertificateError, Errno::ENOENT
+        raise SignatureError, "cannot load certificate: #{certificate_path}"
+      end
+    end
+  end
+end

data/lib/capsium/package/storage_config.rb

@@ -49,12 +49,34 @@ module Capsium
       end
     end
 
-    # The "storage" object holding the dataSets map.
+    # A single storage layer entry (ARCHITECTURE.md section 5a). "path" is
+    # a package-relative directory mirroring the content/ tree; layers are
+    # stacked bottom -> top in declaration order. "visibility: private"
+    # layers are hidden from dependent packages.
+    class LayerConfig < Lutaml::Model::Serializable
+      attribute :path, :string
+      attribute :writable, :boolean, default: false
+      attribute :visibility, :string, values: Resource::VISIBILITIES, default: "exported"
+
+      json do
+        map :path, to: :path
+        map :writable, to: :writable
+        map :visibility, to: :visibility
+      end
+
+      def private?
+        visibility == "private"
+      end
+    end
+
+    # The "storage" object holding the dataSets map and the layers stack.
     class StorageData < Lutaml::Model::Serializable
       attribute :data_sets, :hash, default: {}
+      attribute :layers, LayerConfig, collection: true, default: []
 
       json do
         map "dataSets", with: { from: :data_sets_from_json, to: :data_sets_to_json }
+        map :layers, to: :layers
       end
 
       def data_sets_from_json(model, value)
@@ -101,6 +123,12 @@ module Capsium
       def data_sets
         storage ? storage.data_sets : {}
       end
+
+      # The configured storage layers, bottom -> top (empty when the
+      # package uses the single implicit content/ layer).
+      def layers
+        storage ? storage.layers : []
+      end
     end
   end
 end

data/lib/capsium/package/store.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "zip"
+
+module Capsium
+  class Package
+    # A package store directory (ARCHITECTURE.md section 4a): a directory
+    # of "<name>-<version>.cap" files plus an optional index.json mapping
+    # dependency GUID -> file name. Dependencies resolve to the newest
+    # version satisfying their semver range; an index.json entry pins the
+    # GUID to a specific file (still range-checked).
+    class Store
+      INDEX_FILE = "index.json"
+      CAP_GLOB = "*.cap"
+
+      # One store .cap with its identity per its metadata.json.
+      CatalogEntry = Data.define(:path, :guid, :version)
+
+      attr_reader :dir
+
+      # The store configured via the CAPSIUM_STORE environment variable,
+      # or nil when unset.
+      def self.default
+        dir = ENV.fetch("CAPSIUM_STORE", nil)
+        dir.nil? || dir.empty? ? nil : new(dir)
+      end
+
+      def initialize(dir)
+        unless File.directory?(dir)
+          raise DependencyError, "Package store directory not found: #{dir}"
+        end
+
+        @dir = dir
+      end
+
+      # The newest .cap providing the dependency GUID whose version
+      # satisfies the range string.
+      def find(guid, range_string)
+        range = VersionRange.parse(range_string)
+        indexed = indexed_path(guid)
+        return indexed_satisfying(indexed, guid, range_string, range) if indexed
+
+        candidates = catalog.select { |entry| entry.guid == guid }
+        if candidates.empty?
+          raise DependencyNotFoundError,
+                "no package for dependency #{guid} in store #{@dir}"
+        end
+
+        satisfying = candidates.select { |entry| range.satisfied_by?(entry.version) }
+        return satisfying.max_by(&:version).path unless satisfying.empty?
+
+        versions = candidates.map { |entry| entry.version.to_s }.sort.join(", ")
+        raise UnsatisfiableDependencyError,
+              "no version of #{guid} satisfies '#{range_string}' " \
+              "(store has: #{versions})"
+      end
+
+      # Every .cap in the store with its metadata identity (memoized).
+      def catalog
+        @catalog ||= Dir.glob(File.join(@dir, CAP_GLOB)).map do |path|
+          catalog_entry(path)
+        end
+      end
+
+      # Installs the .cap at source_path into the store as file_name
+      # (conventionally "<name>-<version>.cap"), records guid ->
+      # file_name in index.json (atomically, tmp + rename) and returns
+      # the installed path. Used by registry installs
+      # (Capsium::Registry#install).
+      def install(source_path, guid:, file_name:)
+        destination = File.join(@dir, file_name)
+        tmp = "#{destination}.tmp-#{Process.pid}"
+        FileUtils.cp(source_path, tmp)
+        File.rename(tmp, destination)
+        record_index(guid, file_name)
+        destination
+      end
+
+      private
+
+      # Records guid -> file_name in the store's index.json and drops
+      # the memoized catalog so the new .cap is found.
+      def record_index(guid, file_name)
+        index = load_index.merge(guid => file_name)
+        path = File.join(@dir, INDEX_FILE)
+        tmp = "#{path}.tmp-#{Process.pid}"
+        File.write(tmp, JSON.pretty_generate(index))
+        File.rename(tmp, path)
+        @load_index = index
+        @catalog = nil
+      end
+
+      def indexed_path(guid)
+        file = load_index[guid]
+        file && File.join(@dir, file)
+      end
+
+      def indexed_satisfying(path, guid, range_string, range)
+        unless File.file?(path)
+          raise DependencyNotFoundError,
+                "#{INDEX_FILE} maps #{guid} to a missing file: #{path}"
+        end
+
+        entry = catalog_entry(path)
+        return entry.path if range.satisfied_by?(entry.version)
+
+        raise UnsatisfiableDependencyError,
+              "indexed #{guid} #{entry.version} does not satisfy '#{range_string}'"
+      end
+
+      def catalog_entry(cap_path)
+        metadata = read_metadata(cap_path)
+        CatalogEntry.new(path: cap_path, guid: metadata["guid"],
+                         version: Version.parse(metadata["version"].to_s))
+      end
+
+      def read_metadata(cap_path)
+        Zip::File.open(cap_path) do |zip|
+          entry = zip.find_entry(Package::METADATA_FILE)
+          raise DependencyError, "no #{Package::METADATA_FILE} in #{cap_path}" unless entry
+
+          JSON.parse(entry.get_input_stream.read)
+        end
+      end
+
+      def load_index
+        @load_index ||= begin
+          path = File.join(@dir, INDEX_FILE)
+          File.file?(path) ? JSON.parse(File.read(path)) : {}
+        end
+      end
+    end
+  end
+end

data/lib/capsium/package/testing/config_test.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Capsium
+  class Package
+    module Testing
+      # A "config" test (05x-testing): the configuration file must exist
+      # in the package and parse as the declared format (json or yaml).
+      # The known Capsium package configs (metadata.json, manifest.json,
+      # routes.json, storage.json, security.json) are additionally
+      # validated against their canonical models.
+      class ConfigTest < TestCase
+        FORMATS = %w[json yaml].freeze
+
+        attr_reader :format, :config_file
+
+        def initialize(name:, format:, config_file:)
+          super(name: name)
+          @format = format
+          @config_file = config_file
+        end
+
+        def run(context)
+          problems = config_problems(context)
+          Result.new(name: name, ok: problems.empty?, messages: problems)
+        end
+
+        private
+
+        def config_problems(context)
+          return ["unsupported config format: #{format}"] unless FORMATS.include?(format)
+
+          full_path = File.join(context.package_path, config_file.delete_prefix("/"))
+          return ["config file missing in package: #{config_file}"] unless File.file?(full_path)
+
+          parse(full_path)
+          model_problems(full_path)
+        rescue JSON::ParserError, Psych::SyntaxError => e
+          ["cannot parse #{config_file}: #{e.message}"]
+        end
+
+        def parse(full_path)
+          format == "yaml" ? YAML.load_file(full_path) : JSON.parse(File.read(full_path))
+        end
+
+        def model_problems(full_path)
+          case File.basename(config_file)
+          when Package::METADATA_FILE then Metadata.new(full_path).config.format_errors
+          when Package::MANIFEST_FILE then probe { ManifestConfig.from_json(File.read(full_path)) }
+          when Package::ROUTES_FILE then probe { RoutesConfig.from_json(File.read(full_path)) }
+          when Package::STORAGE_FILE then probe { StorageConfig.from_json(File.read(full_path)) }
+          when Package::SECURITY_FILE then probe { SecurityConfig.from_json(File.read(full_path)) }
+          else []
+          end
+        end
+
+        def probe
+          yield
+          []
+        rescue StandardError => e
+          [e.message]
+        end
+      end
+
+      TestCase.register("config", ConfigTest)
+    end
+  end
+end

data/lib/capsium/package/testing/context.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    module Testing
+      # What a test run needs: the extracted package directory and, when
+      # route tests run, the base URL of the reactor serving the package.
+      Context = Data.define(:package_path, :base_url)
+    end
+  end
+end

data/lib/capsium/package/testing/data_validation_test.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+require "json-schema"
+require "yaml"
+
+module Capsium
+  class Package
+    module Testing
+      # A "data_validation" test (05x-testing): the rows of the data
+      # file (format: json or yaml) must validate against the JSON
+      # schema file. Array data validates row by row; a single document
+      # validates as one row.
+      class DataValidationTest < TestCase
+        FORMATS = %w[json yaml].freeze
+
+        attr_reader :format, :data_file, :schema_file
+
+        def initialize(name:, format:, data_file:, schema_file:)
+          super(name: name)
+          @format = format
+          @data_file = data_file
+          @schema_file = schema_file
+        end
+
+        def run(context)
+          problems = validation_problems(context)
+          Result.new(name: name, ok: problems.empty?, messages: problems)
+        end
+
+        private
+
+        def validation_problems(context)
+          return ["unsupported data format: #{format}"] unless FORMATS.include?(format)
+
+          schema = load_structured(context, schema_file)
+          rows = load_structured(context, data_file)
+          rows = [rows] unless rows.is_a?(Array)
+          rows.each_with_index.flat_map { |row, index| row_problems(schema, row, index) }
+        rescue Errno::ENOENT, JSON::ParserError, Psych::SyntaxError => e
+          ["cannot load data or schema: #{e.message}"]
+        end
+
+        def load_structured(context, relative_path)
+          full_path = File.join(context.package_path, relative_path.delete_prefix("/"))
+          if File.extname(full_path).match?(/\A\.ya?ml\z/i)
+            YAML.load_file(full_path)
+          else
+            JSON.parse(File.read(full_path))
+          end
+        end
+
+        def row_problems(schema, row, index)
+          JSON::Validator.fully_validate(schema, row).map do |message|
+            "row #{index}: #{message}"
+          end
+        end
+      end
+
+      TestCase.register("data_validation", DataValidationTest)
+    end
+  end
+end

data/lib/capsium/package/testing/file_test.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    module Testing
+      # A "file" test (05x-testing): the file must exist in the package;
+      # optionally its content must contain a string.
+      class FileTest < TestCase
+        attr_reader :path, :contains
+
+        def initialize(name:, path:, contains: nil)
+          super(name: name)
+          @path = path
+          @contains = contains
+        end
+
+        def run(context)
+          problems = existence_problems(context) + contains_problems(context)
+          Result.new(name: name, ok: problems.empty?, messages: problems)
+        end
+
+        private
+
+        def full_path(context)
+          File.join(context.package_path, path.delete_prefix("/"))
+        end
+
+        def existence_problems(context)
+          return [] if File.file?(full_path(context))
+
+          ["file missing in package: #{path}"]
+        end
+
+        def contains_problems(context)
+          return [] unless contains && File.file?(full_path(context))
+          return [] if File.read(full_path(context)).include?(contains)
+
+          ["file #{path} does not contain #{contains.inspect}"]
+        end
+      end
+
+      TestCase.register("file", FileTest)
+    end
+  end
+end

data/lib/capsium/package/testing/report.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    module Testing
+      # The outcome of a test suite run: one Result per test case.
+      class Report
+        attr_reader :results
+
+        def initialize(results = [])
+          @results = results
+        end
+
+        def <<(result)
+          @results << result
+          self
+        end
+
+        def ok?
+          @results.all?(&:ok?)
+        end
+
+        def failures
+          @results.reject(&:ok?)
+        end
+
+        def summary
+          "#{@results.size} tests, #{failures.size} failures"
+        end
+      end
+    end
+  end
+end

data/lib/capsium/package/testing/route_test.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Capsium
+  class Package
+    module Testing
+      # A "route" test (05x-testing): requests the URL path from the
+      # reactor serving the package and checks the expected status, and
+      # optionally the content type and a response body substring.
+      class RouteTest < TestCase
+        attr_reader :url, :expected_status, :response_contains, :expected_content_type
+
+        def initialize(name:, url:, expected_status:, response_contains: nil,
+                       expected_content_type: nil)
+          super(name: name)
+          @url = url
+          @expected_status = expected_status
+          @response_contains = response_contains
+          @expected_content_type = expected_content_type
+        end
+
+        def run(context)
+          response = Net::HTTP.get_response(URI.join(context.base_url, request_path))
+          problems = status_problems(response) + content_type_problems(response) +
+                     body_problems(response)
+          Result.new(name: name, ok: problems.empty?, messages: problems)
+        end
+
+        private
+
+        # The DSL allows absolute URLs; only their path (and query) is
+        # used — the runner always targets its own reactor.
+        def request_path
+          uri = URI.parse(url)
+          uri.host ? uri.request_uri : url
+        end
+
+        def status_problems(response)
+          return [] if response.code.to_i == expected_status
+
+          ["expected status #{expected_status}, got #{response.code}"]
+        end
+
+        def content_type_problems(response)
+          return [] unless expected_content_type
+          return [] if response.content_type == expected_content_type
+
+          ["expected content type #{expected_content_type}, got #{response.content_type}"]
+        end
+
+        def body_problems(response)
+          return [] unless response_contains
+          return [] if response.body.to_s.include?(response_contains)
+
+          ["response does not contain #{response_contains.inspect}"]
+        end
+      end
+
+      TestCase.register("route", RouteTest)
+    end
+  end
+end