capsium 0.2.0 → 0.6.0

data/lib/capsium/package/metadata.rb

@@ -11,7 +11,7 @@ module Capsium
 
       def_delegators :@config, :to_json, :to_hash, :name, :version,
                      :description, :guid, :uuid, :author, :license,
-                     :repository, :dependencies
+                     :repository, :dependencies, :read_only
 
       def initialize(path)
         @path = path

data/lib/capsium/package/metadata_config.rb

@@ -36,6 +36,7 @@ module Capsium
       attribute :repository, Repository
       attribute :dependencies, :hash, default: {}
       attribute :read_only, :boolean
+      attribute :modules, :string, collection: true
 
       json do
         map :name, to: :name
@@ -48,6 +49,7 @@ module Capsium
         map :repository, to: :repository
         map :dependencies, to: :dependencies
         map "readOnly", to: :read_only
+        map :modules, to: :modules
       end
 
       def self.from_json(json)
@@ -88,7 +90,13 @@ module Capsium
         problems << "version must be semver" if invalid?(version, SEMVER_PATTERN)
         problems << "guid must be a URI" if guid && !uri?(guid)
         problems << "uuid is not a valid UUID" if invalid?(uuid, UUID_PATTERN)
-        problems
+        problems + module_errors
+      end
+
+      def module_errors
+        return [] if modules.nil? || modules.all? { |mod| mod.match?(KEBAB_CASE_PATTERN) }
+
+        ["modules must be kebab-case module identifiers"]
       end
 
       def invalid?(value, pattern)

data/lib/capsium/package/open_pgp.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # OpenPGP support (signatures per ARCHITECTURE.md section 6a and
+    # encryption per section 6b) through the rnp gem's binding to
+    # librnp.
+    #
+    # rnp is a soft dependency: it is only required when an OpenPGP
+    # feature is actually used, and this module is the single place that
+    # loads it. When the rnp gem or the librnp shared library cannot be
+    # loaded, the entry points raise OpenPgpUnavailableError with
+    # installation guidance.
+    module OpenPgp
+      # The rnp gem or the librnp shared library is not available.
+      class OpenPgpUnavailableError < Capsium::Error; end
+
+      # A key file is unreadable or holds no suitable OpenPGP key.
+      class KeyError < Capsium::Error; end
+
+      UNAVAILABLE_MESSAGE =
+        "OpenPGP support requires librnp and the rnp gem " \
+        "(e.g. `brew install rnp` and `gem install rnp`)"
+
+      # One loaded key file: the Rnp context holding the key material
+      # and the selected key within it.
+      LoadedKey = Data.define(:rnp, :key)
+
+      # A fresh Rnp context. Raises OpenPgpUnavailableError when the rnp
+      # gem or librnp cannot be loaded.
+      def self.rnp
+        require "rnp"
+        Rnp.new
+      rescue LoadError
+        raise OpenPgpUnavailableError, UNAVAILABLE_MESSAGE
+      end
+
+      # Loads the OpenPGP key at key_path (armored or binary, public or
+      # secret — the format is auto-detected) into a fresh Rnp context.
+      # With secret: true the selected key must hold secret key material
+      # (signing, decryption); otherwise any loaded key is selected
+      # (verification, encryption). Raises KeyError when the file is
+      # unreadable or holds no suitable key.
+      def self.load_key(key_path, secret: false)
+        instance = rnp
+        instance.load_keys(input: Rnp::Input.from_string(File.binread(key_path)),
+                           format: "GPG")
+        key = select_key(instance, secret: secret)
+        return LoadedKey.new(rnp: instance, key: key) if key
+
+        raise KeyError, "no suitable #{secret ? 'secret' : 'public'} OpenPGP key in: #{key_path}"
+      rescue Errno::ENOENT, Rnp::Error
+        raise KeyError, "cannot load OpenPGP key: #{key_path}"
+      end
+
+      def self.select_key(instance, secret:)
+        keys = instance.keyids.map { |keyid| instance.find_key(keyid: keyid) }
+        return keys.find(&:secret_key_present?) if secret
+
+        keys.first
+      end
+      private_class_method :select_key
+    end
+  end
+end

data/lib/capsium/package/open_pgp_cipher.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Capsium
+  class Package
+    # Encrypts and decrypts whole Capsium packages with OpenPGP key
+    # management (ARCHITECTURE.md section 6b) through librnp
+    # (Capsium::Package::OpenPgp). Parallel to the RSA-OAEP-SHA256
+    # Cipher — same encrypted .cap layout, same AES-256-GCM content
+    # encryption, same typed errors — with the DEK carried as an armored
+    # OpenPGP message instead of an RSA-wrapped blob:
+    #
+    #   {"encryption": {"algorithm": "AES-256-GCM",
+    #                   "keyManagement": "OpenPGP",
+    #                   "message": <armored OpenPGP message with the DEK>,
+    #                   "iv": <base64>, "authTag": <base64>}}
+    #
+    # Keys are OpenPGP key files (armored or binary, auto-detected):
+    # encryption needs the recipient's public key, decryption the
+    # secret key.
+    class OpenPgpCipher < Cipher
+      KEY_MANAGEMENT = "OpenPGP"
+
+      # The OpenPGP symmetric cipher protecting the DEK message.
+      CIPHER_NAME = "AES256"
+
+      private
+
+      # The encryption envelope carrying the DEK as an armored OpenPGP
+      # message to the recipient's public key.
+      def envelope_for(dek, gcm_iv, auth_tag, recipient)
+        message = recipient.rnp.encrypt(
+          input: Rnp::Input.from_string(dek),
+          recipients: recipient.key, cipher: CIPHER_NAME, armored: true
+        )
+        EncryptionConfig.new(
+          encryption: EncryptionEnvelope.new(
+            algorithm: ALGORITHM, key_management: KEY_MANAGEMENT,
+            message: message,
+            iv: Base64.strict_encode64(gcm_iv), auth_tag: Base64.strict_encode64(auth_tag)
+          )
+        )
+      end
+
+      # Recovers the DEK by decrypting the envelope's OpenPGP message.
+      # Reached only after the rnp binding loaded successfully (the
+      # secret key is loaded first), so the Rnp error constants are
+      # defined here.
+      def unwrap_dek(envelope, secret_key)
+        secret_key.rnp.decrypt(input: Rnp::Input.from_string(envelope.message.to_s))
+      rescue Rnp::Error
+        # No suitable key, or a malformed or tampered message.
+        raise DecryptionError, "decryption failed: wrong key or tampered package"
+      end
+
+      def load_public_key(public_key_path)
+        OpenPgp.load_key(public_key_path)
+      end
+
+      def load_private_key(private_key_path)
+        OpenPgp.load_key(private_key_path, secret: true)
+      end
+    end
+  end
+end

data/lib/capsium/package/open_pgp_signer.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Package
+    # Signs and verifies Capsium packages with OpenPGP detached
+    # signatures (ARCHITECTURE.md section 6a) through librnp
+    # (Capsium::Package::OpenPgp). Parallel to the RSA-SHA256/X.509
+    # Signer with the same construction semantics and the same error
+    # taxonomy (Signer::SignatureError subclasses), so loaders and the
+    # CLI handle both schemes uniformly.
+    #
+    # The signed payload is identical to the Signer's: the
+    # concatenation, in sorted package-relative path order, of the raw
+    # bytes of every file covered by the security.json integrity
+    # checksums. signature.sig holds the armored detached OpenPGP
+    # signature (SHA-256) over that payload; the signer's armored
+    # public key is embedded as signature.pub.asc and security.json
+    # records:
+    #
+    #   "digitalSignatures": { "certificateType": "OpenPGP",
+    #     "publicKey": "signature.pub.asc",
+    #     "signatureFile": "signature.sig" }
+    #
+    # Keys are OpenPGP key files (armored or binary, auto-detected);
+    # signing needs a secret key, verification a public one.
+    class OpenPgpSigner
+      ALGORITHM = "OpenPGP"
+      CERTIFICATE_TYPE = "OpenPGP"
+      HASH = "SHA256"
+
+      # Package-relative name of the embedded armored OpenPGP public key
+      # recorded in security.json digitalSignatures.publicKey.
+      PUBLIC_KEY_FILE = "signature.pub.asc"
+
+      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), with the OpenPGP secret key at
+      # secret_key_path. Returns the signed path.
+      def self.sign_package(path, secret_key_path)
+        return new(path).sign(secret_key_path) unless cap?(path)
+
+        Packager.new.transform_cap(path) { |dir| new(dir).sign(secret_key_path) }
+        path
+      end
+
+      # Verifies the declared OpenPGP signature of a package directory
+      # or .cap file (false on mismatch; raises typed
+      # Signer::SignatureError subclasses on structural problems, e.g.
+      # an unsigned package). public_key_path is an OpenPGP public key
+      # file; without it the key embedded in the package is used.
+      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 armored public
+      # key, regenerates security.json (checksums plus digitalSignatures
+      # with certificateType "OpenPGP") and writes the armored detached
+      # OpenPGP signature to signature.sig.
+      def sign(secret_key_path)
+        loaded = OpenPgp.load_key(secret_key_path, secret: true)
+        File.write(public_key_path, loaded.key.export_public(armored: true))
+        security = Security.generate(@package_path, digital_signatures: digital_signatures)
+        security.save_to_file
+        signature = loaded.rnp.detached_sign(
+          input: Rnp::Input.from_string(payload(security)),
+          signers: loaded.key, hash: HASH, armored: true
+        )
+        File.write(signature_path, signature)
+        signature_path
+      end
+
+      # True when the declared signature verifies against the payload.
+      # Without an explicit key path, the embedded public key is used.
+      def verify(public_key_path = nil)
+        signature = read_signature
+        data = payload(declared_security)
+        loaded = verification_key(public_key_path)
+        signature_matches(loaded, data, signature)
+      end
+
+      def verify!(public_key_path = nil)
+        return true if verify(public_key_path)
+
+        raise Signer::SignatureMismatchError,
+              "digital signature does not match the package contents"
+      end
+
+      def signed?
+        declared_security.signed?
+      end
+
+      private
+
+      # Reached only after the rnp binding loaded successfully (the
+      # verification key is loaded first), so the Rnp error constants
+      # are defined here.
+      def signature_matches(loaded, data, signature)
+        loaded.rnp.detached_verify(data: Rnp::Input.from_string(data),
+                                   signature: Rnp::Input.from_string(signature))
+        true
+      rescue Rnp::InvalidSignatureError
+        false
+      end
+
+      def declared_security
+        Security.new(File.join(@package_path, Package::SECURITY_FILE))
+      end
+
+      def digital_signatures
+        DigitalSignatures.new(certificate_type: CERTIFICATE_TYPE,
+                              public_key: PUBLIC_KEY_FILE,
+                              signature_file: Package::SIGNATURE_FILE)
+      end
+
+      # The canonical signed payload (ARCHITECTURE.md section 6a,
+      # identical to Signer's): 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 Signer::SignatureError,
+                  "file covered by checksums is missing: #{relative_path}"
+          end
+
+          File.binread(file_path)
+        end.join
+      end
+
+      def read_signature
+        unless signed?
+          raise Signer::UnsignedPackageError,
+                "package is not signed (security.json declares no digitalSignatures)"
+        end
+        return File.binread(signature_path) if File.file?(signature_path)
+
+        raise Signer::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 verification_key(public_key_path)
+        return OpenPgp.load_key(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 OpenPgp.load_key(embedded_path) if File.file?(embedded_path)
+
+        raise Signer::SignatureError, "public key file missing: #{embedded}"
+      end
+    end
+  end
+end

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/security_config.rb

@@ -19,13 +19,17 @@ module Capsium
       end
     end
 
-    # The "digitalSignatures" object of security.json. Signing is a later
-    # phase; the model parses the canonical fields only.
+    # The "digitalSignatures" object of security.json. certificateType
+    # selects the signature scheme: absent means RSA-SHA256 (X.509),
+    # "OpenPGP" an OpenPGP signature (the publicKey then holds an
+    # armored OpenPGP public key).
     class DigitalSignatures < Lutaml::Model::Serializable
+      attribute :certificate_type, :string
       attribute :public_key, :string
       attribute :signature_file, :string
 
       json do
+        map "certificateType", to: :certificate_type
         map "publicKey", to: :public_key
         map "signatureFile", to: :signature_file
       end