capsium 0.2.0 → 0.3.0

data/lib/capsium/package/preparation.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+
+module Capsium
+  class Package
+    # Package-source preparation (ARCHITECTURE.md section 1), mixed into
+    # Package: directory/.cap/encrypted-cap detection, extraction and
+    # decryption into a readable package directory.
+    module Preparation
+      def prepare_package(path)
+        return decrypt_cap_file(path) if Cipher.encrypted?(path)
+        return path if File.directory?(path)
+        raise Error, "Invalid package path: #{path}" unless File.file?(path)
+        raise Error, "The package must have a .cap extension" unless File.extname(path) == ".cap"
+
+        decompress_cap_file(path)
+      end
+
+      def decompress_cap_file(file_path)
+        package_path = File.join(Dir.mktmpdir, package_stem(file_path))
+        FileUtils.mkdir_p(package_path)
+        Packager.new.unpack(file_path, package_path)
+        package_path
+      end
+
+      # Decrypts an encrypted package (.cap file or uncompressed directory)
+      # into a temporary directory and returns its path. The metadata.json
+      # of an encrypted package stays cleartext, but everything else is
+      # only readable with the recipient's private key.
+      def decrypt_cap_file(source_path)
+        unless @decryption_key
+          raise Cipher::KeyRequiredError,
+                "Package is encrypted; provide the private key via decryption_key:"
+        end
+
+        Cipher.decrypt_to_directory(source_path, @decryption_key)
+      end
+
+      def determine_load_type(path)
+        return :directory if File.directory?(path)
+
+        File.extname(path) == ".cap" ? :cap_file : :unsaved
+      end
+
+      # Whether the package was loaded from an encrypted source
+      # (ARCHITECTURE.md section 6b layout).
+      def encrypted?
+        Cipher.encrypted?(@original_path)
+      end
+
+      private
+
+      def package_stem(file_path)
+        File.basename(file_path, ".cap")
+      end
+
+      def create_package_structure
+        FileUtils.mkdir_p(content_path)
+        FileUtils.mkdir_p(data_path)
+      end
+
+      def content_path = File.join(@path, CONTENT_DIR)
+
+      def data_path = File.join(@path, DATA_DIR)
+
+      def routes_path = File.join(@path, ROUTES_FILE)
+
+      def storage_path = File.join(@path, STORAGE_FILE)
+
+      def metadata_path = File.join(@path, METADATA_FILE)
+
+      def manifest_path = File.join(@path, MANIFEST_FILE)
+
+      def security_path = File.join(@path, SECURITY_FILE)
+
+      def authentication_path = File.join(@path, AUTHENTICATION_FILE)
+    end
+  end
+end

data/lib/capsium/package/routes_config.rb

@@ -5,12 +5,33 @@ require "lutaml/model"
 
 module Capsium
   class Package
+    # 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
+
+      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/"
 
@@ -23,6 +44,10 @@ module Capsium
       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
@@ -34,6 +59,10 @@ module Capsium
         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
@@ -51,6 +80,25 @@ module Capsium
         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
 
@@ -61,22 +109,28 @@ module Capsium
         manifest.type_for(resource)
       end
 
-      def validate_target(package_path, storage)
+      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)
+        validate_resource_target(package_path, merged_view)
       end
 
       private
 
-      def validate_resource_target(package_path)
-        target_path = fs_path(package_path)
-        return if target_path && File.exist?(target_path)
+      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
@@ -121,7 +175,7 @@ module Capsium
       end
 
       def resolve(path)
-        routes.detect { |route| route.path == path }
+        routes.detect { |route| route.serving_path == path }
       end
 
       def add(path, target)

data/lib/capsium/package/security.rb

@@ -8,7 +8,8 @@ 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.
+    # security.json itself and signature.sig (the signature signs the
+    # checksum-covered payload, so it cannot be part of it).
     class Security
       extend Forwardable
 
@@ -39,13 +40,14 @@ module Capsium
         @config = config || load_config
       end
 
-      def self.generate(package_path)
+      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)
@@ -62,13 +64,28 @@ module Capsium
           File.file?(file)
         end
         files.map { |file| file.delete_prefix("#{package_path}/") }
-             .reject { |relative_path| relative_path == SECURITY_FILE }
+             .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

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

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,109 @@
+# frozen_string_literal: true
+
+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
+
+      private
+
+      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