capsium 0.1.2 → 0.3.0

data/lib/capsium/package/routes_config.rb

@@ -1,72 +1,202 @@
 # frozen_string_literal: true
 
-require "shale"
+require "json"
+require "lutaml/model"
 
 module Capsium
   class Package
-    class RouteTarget < Shale::Mapper
-      attribute :file, Shale::Type::String
-      attribute :dataset, Shale::Type::String
+    # The "responseRewrite" object of an inherited route (05x-routing
+    # section "Route Inheritance"): replaces the served body and/or
+    # overrides response headers.
+    class ResponseRewrite < Lutaml::Model::Serializable
+      attribute :body, :string
+      attribute :headers, :hash
 
-      def fs_path(manifest)
-        return unless file
+      json do
+        map :body, to: :body
+        map :headers, to: :headers
+      end
+    end
+
+    # A single route entry (ARCHITECTURE.md section 4). Kinds are
+    # discriminated by key, MECE:
+    # - {path, resource, headers?, visibility?} -- static file
+    # - {path, dataset, accessControl?}        -- dataset route
+    # - {path, method, handler, ...}           -- dynamic handler (parsed,
+    #   accepted-and-ignored; reactors respond 501)
+    #
+    # Route inheritance (05x-routing): a resource of the form
+    # "<dependency-guid>/<path>" (a URI, i.e. containing "://") pulls
+    # content from a dependency package; "remap" replaces the serving
+    # path; "responseRewrite"/"responseHeaders" post-process the
+    # response; "requestHeaders" are recorded for forwarding reactors
+    # (the Ruby reactor serves statically and does not forward, so they
+    # do not alter its responses).
+    class Route < Lutaml::Model::Serializable
+      DATASET_PATH_PREFIX = "/api/v1/data/"
+
+      attribute :path, :string
+      attribute :resource, :string
+      attribute :headers, :hash
+      attribute :headers_file, :string
+      attribute :visibility, :string, values: Resource::VISIBILITIES
+      attribute :dataset, :string
+      attribute :access_control, :hash
+      attribute :http_method, :string
+      attribute :handler, :string
+      attribute :remap, :string
+      attribute :response_rewrite, ResponseRewrite
+      attribute :response_headers, :hash
+      attribute :request_headers, :hash
+
+      json do
+        map :path, to: :path
+        map :resource, to: :resource
+        map :headers, to: :headers
+        map "headersFile", to: :headers_file
+        map :visibility, to: :visibility
+        map :dataset, to: :dataset
+        map "accessControl", to: :access_control
+        map "method", to: :http_method
+        map :handler, to: :handler
+        map :remap, to: :remap
+        map "responseRewrite", to: :response_rewrite
+        map "responseHeaders", to: :response_headers
+        map "requestHeaders", to: :request_headers
+      end
+
+      def kind
+        return :resource if resource
+        return :dataset if dataset
+
+        :handler
+      end
+
+      def dataset_route?
+        kind == :dataset
+      end
+
+      def handler_route?
+        kind == :handler
+      end
+
+      # The URL path this route answers at: the remapped path when the
+      # route remaps an inherited route, its own path otherwise.
+      def serving_path
+        remap || path
+      end
+
+      # Whether the resource addresses content of a dependency package
+      # ("<dependency-guid>/<path>" — a URI rather than a
+      # package-relative path).
+      def dependency_reference?
+        resource.is_a?(String) && resource.include?("://")
+      end
+
+      # Whether the route carries route-inheritance attributes.
+      def inherited?
+        dependency_reference? || !remap.nil? || !response_rewrite.nil? ||
+          !response_headers.nil? || !request_headers.nil?
+      end
+
+      def fs_path(package_path)
+        return unless resource
 
-        manifest.path_to_content_file(manifest.lookup(file)&.file)
+        File.join(package_path, resource)
       end
 
       def mime(manifest)
-        manifest.lookup(file)&.mime
-      end
-
-      def validate(manifest, storage)
-        if file
-          target_path = fs_path(manifest)
-          unless target_path && File.exist?(target_path) && target_path.to_s.start_with?(manifest.content_path.to_s)
-            raise "Route target does not exist or is outside of the content directory: #{target_path}"
-          end
-        elsif dataset
-          unless storage.datasets.any? { |ds| ds.config.name == dataset }
-            raise "Dataset target does not exist: #{dataset}"
-          end
-        else
-          raise "Route target must have either a file or a dataset"
+        manifest.type_for(resource)
+      end
+
+      def validate_target(package_path, storage, merged_view: nil)
+        return if handler_route?
+        return if dependency_reference?
+
+        if dataset_route?
+          return if storage.dataset(dataset)
+
+          raise Error, "Route dataset does not exist: #{dataset}"
         end
+        validate_resource_target(package_path, merged_view)
       end
-    end
 
-    class Route < Shale::Mapper
-      attribute :path, Shale::Type::String
-      attribute :target, RouteTarget
+      private
+
+      def validate_resource_target(package_path, merged_view)
+        found = if merged_view
+                  merged_view.resolve(resource)
+                else
+                  target_path = fs_path(package_path)
+                  target_path && File.exist?(target_path)
+                end
+        return if found
+
+        raise Error, "Route resource does not exist: #{resource}"
+      end
     end
 
-    class RoutesConfig < Shale::Mapper
-      attribute :routes, Route, collection: true
+    # Canonical routes.json model: optional top-level "index" plus a
+    # "routes" array. The legacy gem form ({path, target: {file|dataset}})
+    # is accepted on read and normalized; writers emit only the canonical
+    # form.
+    class RoutesConfig < Lutaml::Model::Serializable
+      attribute :index, :string
+      attribute :routes, Route, collection: true, default: []
+
+      json do
+        map :index, to: :index
+        map :routes, with: { from: :routes_from_json, to: :routes_to_json }
+      end
+
+      def self.from_json(json)
+        doc = JSON.parse(json)
+        doc["routes"] = (doc["routes"] || []).map { |route| normalize_route(route) }
+        super(JSON.generate(doc))
+      end
+
+      def self.normalize_route(route)
+        target = route.delete("target")
+        return route unless target.is_a?(Hash)
+
+        route.merge("resource" => target["file"], "dataset" => target["dataset"]).compact
+      end
+      private_class_method :normalize_route
+
+      def routes_from_json(model, value)
+        model.routes = (value || []).map { |route| Route.from_json(JSON.generate(route)) }
+      end
+
+      # Writers emit the canonical form only: deterministic, sorted by path.
+      def routes_to_json(model, doc)
+        doc["routes"] = model.routes.sort_by(&:path).map do |route|
+          JSON.parse(route.to_json)
+        end
+      end
 
-      def resolve(route)
-        routes.detect { |r| r.path == route }
+      def resolve(path)
+        routes.detect { |route| route.serving_path == path }
       end
 
-      def add(route, target)
-        target = RouteTarget.new(file: target) if target.is_a?(String)
-        r = Route.new(path: route, target: target)
-        @routes << r
-        r
+      def add(path, target)
+        route = Route.new(path: path, resource: target)
+        self.routes = routes + [route]
+        route
       end
 
-      def update(route, updated_route, updated_target)
-        r = resolve(route)
-        r.path = updated_route
-        r.target = updated_target
-        r
+      def update(path, updated_path, updated_target)
+        route = resolve(path)
+        route.path = updated_path
+        route.resource = updated_target
+        route
       end
 
-      def remove(route)
-        r = resolve(route)
-        @routes.delete(r)
+      def remove(path)
+        self.routes = routes.reject { |route| route.path == path }
       end
 
       def sort!
-        @routes.sort_by!(&:path)
+        self.routes = routes.sort_by(&:path)
         self
       end
     end

data/lib/capsium/package/security.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "digest"
+require "forwardable"
+require "json"
+
+module Capsium
+  class Package
+    # Loads, generates and verifies security.json (ARCHITECTURE.md
+    # section 6). Checksums cover every file in the package except
+    # security.json itself and signature.sig (the signature signs the
+    # checksum-covered payload, so it cannot be part of it).
+    class Security
+      extend Forwardable
+
+      class IntegrityError < Capsium::Error; end
+
+      ChecksumMismatch = Data.define(:path, :expected, :actual) do
+        def message
+          "checksum mismatch: #{path}"
+        end
+      end
+      MissingFile = Data.define(:path, :expected) do
+        def message
+          "checksum listed but file missing: #{path}"
+        end
+      end
+      UncheckedFile = Data.define(:path) do
+        def message
+          "file not covered by checksums: #{path}"
+        end
+      end
+
+      attr_reader :path, :config
+
+      def_delegators :@config, :to_json, :to_hash
+
+      def initialize(path, config = nil)
+        @path = path
+        @config = config || load_config
+      end
+
+      def self.generate(package_path, digital_signatures: nil)
+        config = SecurityConfig.new(
+          security: SecurityData.new(
+            integrity_checks: IntegrityChecks.new(
+              checksum_algorithm: "SHA-256",
+              checksums: checksums_for(package_path)
+            ),
+            digital_signatures: digital_signatures
+          )
+        )
+        new(File.join(package_path, SECURITY_FILE), config)
+      end
+
+      def self.checksums_for(package_path)
+        package_files(package_path).sort.to_h do |relative_path|
+          [relative_path, Digest::SHA256.file(File.join(package_path, relative_path)).hexdigest]
+        end
+      end
+
+      def self.package_files(package_path)
+        files = Dir.glob(File.join(package_path, "**", "*")).select do |file|
+          File.file?(file)
+        end
+        files.map { |file| file.delete_prefix("#{package_path}/") }
+             .reject { |relative_path| excluded?(relative_path) }
+      end
+
+      def self.excluded?(relative_path)
+        [SECURITY_FILE, SIGNATURE_FILE].include?(relative_path)
+      end
+
+      def present?
+        !@config.nil?
+      end
+
+      # The declared digitalSignatures block, or nil when absent.
+      def digital_signatures
+        return unless present? && config.security
+
+        config.security.digital_signatures
+      end
+
+      def signed?
+        !digital_signatures&.signature_file.nil?
+      end
+
+      def checksums
+        present? ? config.checksums : {}
+      end
+
+      def verify(package_path)
+        expected = checksums
+        errors = verify_present_files(package_path, expected)
+        expected.each do |relative_path, checksum|
+          next if File.file?(File.join(package_path, relative_path))
+
+          errors << MissingFile.new(path: relative_path, expected: checksum)
+        end
+        errors
+      end
+
+      def verify!(package_path)
+        errors = verify(package_path)
+        return if errors.empty?
+
+        raise IntegrityError,
+              "Package integrity check failed: #{errors.map(&:path).join(', ')}"
+      end
+
+      def save_to_file(output_path = @path)
+        File.write(output_path, to_json)
+      end
+
+      private
+
+      def load_config
+        return unless File.exist?(@path)
+
+        SecurityConfig.from_json(File.read(@path))
+      end
+
+      def verify_present_files(package_path, expected)
+        self.class.package_files(package_path).filter_map do |relative_path|
+          file_path = File.join(package_path, relative_path)
+          if expected.key?(relative_path)
+            actual = Digest::SHA256.file(file_path).hexdigest
+            unless actual == expected[relative_path]
+              next ChecksumMismatch.new(path: relative_path, expected: expected[relative_path],
+                                        actual: actual)
+            end
+          else
+            UncheckedFile.new(path: relative_path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/capsium/package/security_config.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Capsium
+  class Package
+    # The "integrityChecks" object of security.json (ARCHITECTURE.md
+    # section 6): SHA-256 checksums over every package file except
+    # security.json itself, keyed by package-relative path.
+    class IntegrityChecks < Lutaml::Model::Serializable
+      ALGORITHMS = %w[SHA-256].freeze
+
+      attribute :checksum_algorithm, :string, values: ALGORITHMS, default: "SHA-256"
+      attribute :checksums, :hash, default: {}
+
+      json do
+        map "checksumAlgorithm", to: :checksum_algorithm
+        map :checksums, to: :checksums
+      end
+    end
+
+    # The "digitalSignatures" object of security.json. Signing is a later
+    # phase; the model parses the canonical fields only.
+    class DigitalSignatures < Lutaml::Model::Serializable
+      attribute :public_key, :string
+      attribute :signature_file, :string
+
+      json do
+        map "publicKey", to: :public_key
+        map "signatureFile", to: :signature_file
+      end
+    end
+
+    # The "security" object of security.json.
+    class SecurityData < Lutaml::Model::Serializable
+      attribute :integrity_checks, IntegrityChecks
+      attribute :digital_signatures, DigitalSignatures
+
+      json do
+        map "integrityChecks", to: :integrity_checks
+        map "digitalSignatures", to: :digital_signatures
+      end
+    end
+
+    # Canonical security.json model (generated at pack time).
+    class SecurityConfig < Lutaml::Model::Serializable
+      attribute :security, SecurityData
+
+      json do
+        map :security, to: :security
+      end
+
+      def checksums
+        return {} unless security&.integrity_checks
+
+        security.integrity_checks.checksums
+      end
+    end
+  end
+end

data/lib/capsium/package/signer.rb

@@ -0,0 +1,201 @@
+# 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).
+      def self.verify_package(path, public_key_path = nil)
+        return new(path).verify(public_key_path) unless cap?(path)
+
+        Packager.new.with_unpacked_cap(path) { |dir| new(dir).verify(public_key_path) }
+      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