capsium 0.1.2 → 0.3.0

data/lib/capsium/package.rb

@@ -1,89 +1,100 @@
 # frozen_string_literal: true
 
-# lib/capsium/package.rb
 require "fileutils"
-require "json"
-require "yaml"
-require "csv"
-require "sqlite3"
-require "zip"
-require_relative "package/manifest"
-require_relative "package/metadata"
-require_relative "package/routes"
-require_relative "package/dataset"
-require_relative "package/storage"
-require_relative "packager"
+require "pathname"
+require "tmpdir"
 
 module Capsium
   class Package
-    attr_reader :name, :path, :manifest, :metadata, :routes, :datasets,
-                :storage, :load_type
+    autoload :Cipher, "capsium/package/cipher"
+    autoload :CircularDependencyError, "capsium/package/dependency_resolver"
+    autoload :Composition, "capsium/package/composition"
+    autoload :Authentication, "capsium/package/authentication"
+    autoload :AuthenticationConfig, "capsium/package/authentication_config"
+    autoload :AuthenticationData, "capsium/package/authentication_config"
+    autoload :BasicAuthConfig, "capsium/package/authentication_config"
+    autoload :Dataset, "capsium/package/dataset"
+    autoload :DatasetConfig, "capsium/package/storage_config"
+    autoload :DependencyError, "capsium/package/dependency_resolver"
+    autoload :DependencyNotFoundError, "capsium/package/dependency_resolver"
+    autoload :DependencyResolver, "capsium/package/dependency_resolver"
+    autoload :DependencyVisibilityError, "capsium/package/dependency_resolver"
+    autoload :DigitalSignatures, "capsium/package/security_config"
+    autoload :EncryptionConfig, "capsium/package/encryption_config"
+    autoload :EncryptionEnvelope, "capsium/package/encryption_config"
+    autoload :IntegrityChecks, "capsium/package/security_config"
+    autoload :LayerConfig, "capsium/package/storage_config"
+    autoload :Manifest, "capsium/package/manifest"
+    autoload :ManifestConfig, "capsium/package/manifest_config"
+    autoload :MergedView, "capsium/package/merged_view"
+    autoload :Metadata, "capsium/package/metadata"
+    autoload :MetadataData, "capsium/package/metadata_config"
+    autoload :OAuth2Config, "capsium/package/authentication_config"
+    autoload :Preparation, "capsium/package/preparation"
+    autoload :Repository, "capsium/package/metadata_config"
+    autoload :ResolvedDependency, "capsium/package/dependency_resolver"
+    autoload :Resource, "capsium/package/manifest_config"
+    autoload :ResponseRewrite, "capsium/package/routes_config"
+    autoload :Route, "capsium/package/routes_config"
+    autoload :Routes, "capsium/package/routes"
+    autoload :RoutesConfig, "capsium/package/routes_config"
+    autoload :Security, "capsium/package/security"
+    autoload :SecurityConfig, "capsium/package/security_config"
+    autoload :SecurityData, "capsium/package/security_config"
+    autoload :Signer, "capsium/package/signer"
+    autoload :Storage, "capsium/package/storage"
+    autoload :StorageConfig, "capsium/package/storage_config"
+    autoload :StorageData, "capsium/package/storage_config"
+    autoload :Store, "capsium/package/store"
+    autoload :Testing, "capsium/package/testing"
+    autoload :UnsatisfiableDependencyError, "capsium/package/dependency_resolver"
+    autoload :Validator, "capsium/package/validator"
+    autoload :Verification, "capsium/package/verification"
+    autoload :Version, "capsium/package/version"
+    autoload :VersionRange, "capsium/package/version"
+
+    include Verification
+    include Composition
+    include Preparation
+
+    attr_reader :name, :path, :manifest, :metadata, :routes, :storage,
+                :security, :load_type, :resolved_dependencies, :authentication
 
     MANIFEST_FILE = "manifest.json"
     METADATA_FILE = "metadata.json"
-    PACKAGING_FILE = "packaging.json"
-    SIGNATURE_FILE = "signature.json"
     STORAGE_FILE = "storage.json"
     ROUTES_FILE = "routes.json"
+    SECURITY_FILE = "security.json"
+    SIGNATURE_FILE = "signature.sig"
+    AUTHENTICATION_FILE = "authentication.json"
     CONTENT_DIR = "content"
     DATA_DIR = "data"
-    ENCRYPTED_PACKAGING_FILE = "package.enc"
 
-    def initialize(path, load_type: nil)
+    # Loads a package directory or .cap file. Composite packages
+    # (metadata.dependencies, ARCHITECTURE.md section 4a) resolve against
+    # the package store given as `store` (directory path or Store) or via
+    # CAPSIUM_STORE. `dependency_chain` is internal: the ancestor GUIDs
+    # used for circular-dependency detection during recursive resolution.
+    def initialize(path, load_type: nil, decryption_key: nil, store: nil,
+                   dependency_chain: [])
+      @decryption_key = decryption_key
       @original_path = Pathname.new(path).expand_path
-      @path = prepare_package(@original_path)
+      @path = prepare_package(@original_path).to_s
       @load_type = load_type || determine_load_type(path)
       create_package_structure
       load_package
       @name = metadata.name
-    end
-
-    def prepare_package(path)
-      return path if File.directory?(path)
-
-      if File.file?(path)
-        return decompress_cap_file(path) if File.extname(path) == ".cap"
-
-        raise "Error: The package must have a .cap extension"
-      end
-
-      raise "Invalid package path: #{path}"
+      @resolved_dependencies = resolve_dependencies(store, dependency_chain)
+      validate_dependency_references!
+      verify_integrity!
+      verify_signature!
     end
 
     def solidify
       @manifest.save_to_file
       @metadata.save_to_file
       @routes.save_to_file
-      @storage.save_to_file
-    end
-
-    def decompress_cap_file(file_path)
-      temp_dir = Dir.mktmpdir
-      metadata_path = File.join(temp_dir, METADATA_FILE)
-
-      # Extract metadata.json first
-      Zip::File.open(file_path) do |zip_file|
-        if entry = zip_file.find_entry(METADATA_FILE)
-          entry.extract(metadata_path)
-        end
-      end
-
-      metadata = Metadata.new(metadata_path)
-      package_name = metadata.name
-      package_version = metadata.version
-
-      package_path = File.join(temp_dir, "#{package_name}-#{package_version}")
-      FileUtils.mkdir_p(package_path)
-
-      Zip::File.open(file_path) do |zip_file|
-        zip_file.each do |entry|
-          entry_path = File.join(package_path, entry.name)
-          FileUtils.mkdir_p(File.dirname(entry_path))
-          entry.extract(entry_path)
-        end
-      end
-
-      package_path
+      @storage.save_to_file unless @storage.empty?
     end
 
     def load_package
@@ -94,61 +105,36 @@ module Capsium
       @manifest = Manifest.new(manifest_path)
       @storage = Storage.new(storage_path)
       @routes = Routes.new(routes_path, @manifest, @storage)
+      @security = Security.new(security_path)
+      @authentication = Authentication.new(authentication_path)
     end
 
     def cleanup
-      return unless @path != @original_path && File.directory?(@path)
-
-      FileUtils.remove_entry(@path)
-    end
-
-    def package_files
-      @packager.package_files
+      @resolved_dependencies.each { |dependency| dependency.package.cleanup }
+      FileUtils.remove_entry(@path) if @path != @original_path.to_s && File.directory?(@path)
     end
 
-    def content_files
-      Dir.glob(File.join(content_path, "**", "*")).select do |file|
-        File.file?(file)
-      end
-    end
-
-    def determine_load_type(path)
-      return :directory if File.directory?(path)
-      return :cap_file if File.extname(path) == ".cap"
-
-      :unsaved
-    end
-
-    private
-
-    def create_package_structure
-      FileUtils.mkdir_p(@path)
-      FileUtils.mkdir_p(content_path)
-      FileUtils.mkdir_p(data_path)
-    end
+    def datasets = storage.datasets
 
-    def content_path
-      File.join(@path, CONTENT_DIR)
+    # The merged content view across the storage layers (ARCHITECTURE.md
+    # section 5a); exported_only gives the dependent-package view (section 4a).
+    # Resolved dependencies act as read-only layers below all own layers.
+    def merged_view(exported_only: false)
+      @merged_views ||= {}
+      @merged_views[exported_only] ||=
+        MergedView.new(@path, storage: @storage, manifest: @manifest,
+                              dependency_views: dependency_views,
+                              exported_only: exported_only)
     end
 
-    def data_path
-      File.join(@path, DATA_DIR)
+    # The .cap file this package was loaded from, or nil when loaded
+    # from a directory.
+    def cap_file_path
+      @original_path.to_s if load_type == :cap_file
     end
 
-    def routes_path
-      File.join(@path, ROUTES_FILE)
-    end
-
-    def storage_path
-      File.join(@path, STORAGE_FILE)
-    end
-
-    def metadata_path
-      File.join(@path, METADATA_FILE)
-    end
-
-    def manifest_path
-      File.join(@path, MANIFEST_FILE)
+    def content_files
+      Dir.glob(File.join(content_path, "**", "*")).select { |file| File.file?(file) }
     end
   end
 end

data/lib/capsium/packager.rb

@@ -1,15 +1,22 @@
 # frozen_string_literal: true
 
-# lib/capsium/packager.rb
-require "json"
 require "fileutils"
-require "rubygems"
+require "pathname"
+require "tmpdir"
 require "zip"
 
 module Capsium
   class Packager
     class FileAlreadyExistsError < StandardError; end
 
+    # Raised when a .cap archive contains an entry whose name would be
+    # written outside the destination directory (absolute paths, drive
+    # letters, ".." segments) — zip-slip protection, on par with the Lua
+    # reactor's extractor.
+    class UnsafeEntryError < Capsium::Error; end
+
+    DRIVE_LETTER_PATTERN = %r{\A[A-Za-z]:[/\\]}
+
     def pack(package, options = {})
       directory = package.path
       output_file_name = "#{package.metadata.name}-#{package.metadata.version}.cap"
@@ -26,8 +33,10 @@ module Capsium
 
       Dir.mktmpdir do |dir|
         FileUtils.cp_r("#{directory}/.", dir)
+        strip_security_artifacts(dir)
         new_package = Package.new(dir)
         new_package.solidify
+        generate_security(new_package)
         new_cap_file_path = File.join(dir, output_file_name)
         compress_package(new_package, new_cap_file_path)
         puts "Package built at: #{new_cap_file_path}"
@@ -38,9 +47,10 @@ module Capsium
     end
 
     def unpack(cap_file_path, destination)
+      destination = File.expand_path(destination)
       Zip::File.open(cap_file_path) do |zip_file|
         zip_file.each do |entry|
-          entry_path = File.join(destination, entry.name)
+          entry_path = safe_entry_path(destination, entry.name)
           FileUtils.mkdir_p(File.dirname(entry_path))
           entry.extract(entry_path)
         end
@@ -48,15 +58,74 @@ module Capsium
     end
 
     def compress_package(package, cap_file)
-      Zip::File.open(cap_file, Zip::File::CREATE) do |zipfile|
-        Dir[File.join(package.path, "**", "**")].each do |file|
+      entries = Dir[File.join(package.path, "**", "**")].reject do |file|
+        File.expand_path(file) == File.expand_path(cap_file)
+      end
+      Zip::File.open(cap_file, create: true) do |zipfile|
+        entries.each do |file|
           zipfile.add(file.sub("#{package.path}/", ""), file)
         end
       end
     end
 
+    # Unpacks a .cap into a temporary directory, yields it for read-only
+    # inspection and returns the block's value.
+    def with_unpacked_cap(cap_path)
+      Dir.mktmpdir do |dir|
+        unpack(cap_path, dir)
+        yield dir
+      end
+    end
+
+    # Unpacks a .cap into a temporary directory, yields it for
+    # modification, then recompresses the result back over cap_path.
+    # The modified package is loaded (verifying integrity and any
+    # declared signature) before recompressing.
+    def transform_cap(cap_path)
+      with_unpacked_cap(cap_path) do |dir|
+        yield dir
+        Dir.mktmpdir do |tmp|
+          tmp_cap = File.join(tmp, File.basename(cap_path))
+          compress_package(Package.new(dir), tmp_cap)
+          FileUtils.mv(tmp_cap, cap_path)
+        end
+      end
+      cap_path
+    end
+
     def relative_path_current(absolute_path)
       Pathname.new(absolute_path).relative_path_from(Dir.pwd).to_s
     end
+
+    private
+
+    # Resolves an entry name against the destination and returns the
+    # absolute target path, raising UnsafeEntryError when the entry would
+    # escape the destination (zip-slip).
+    def safe_entry_path(destination, entry_name)
+      entry_path = File.expand_path(entry_name, destination)
+      return entry_path if contained?(entry_path, destination) &&
+                           !entry_name.match?(DRIVE_LETTER_PATTERN)
+
+      raise UnsafeEntryError,
+            "Refusing to extract unsafe zip entry: #{entry_name}"
+    end
+
+    def contained?(entry_path, destination)
+      entry_path.start_with?("#{destination}#{File::SEPARATOR}")
+    end
+
+    def generate_security(package)
+      security = Package::Security.generate(package.path)
+      security.save_to_file
+    end
+
+    # security.json is regenerated on pack; signing artifacts are dropped
+    # because signing is a post-pack step (`capsium package sign`).
+    def strip_security_artifacts(directory)
+      FileUtils.rm_f(File.join(directory, Package::SECURITY_FILE))
+      FileUtils.rm_f(File.join(directory, Package::SIGNATURE_FILE))
+      FileUtils.rm_f(File.join(directory, Package::Signer::PUBLIC_KEY_FILE))
+    end
   end
 end

data/lib/capsium/reactor/authenticator.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Capsium
+  class Reactor
+    # Request authentication and route authorization for the reactor
+    # (05x-authentication, ARCHITECTURE.md section 4b).
+    #
+    # When the package's authentication.json enables basicAuth, every
+    # route is challenged (401 + WWW-Authenticate) until valid htpasswd
+    # credentials arrive. When oauth2 is enabled, the login and callback
+    # endpoints run the authorization-code flow and establish a signed
+    # session cookie. Route-level accessControl is enforced after
+    # authentication: 401 when unauthenticated, 403 when the identity
+    # lacks a required role.
+    class Authenticator
+      LOGIN_PATH = "/auth/login"
+
+      attr_reader :authentication, :deploy
+
+      def initialize(authentication, deploy:, package_path:, base_url: nil,
+                     state_file: nil)
+        @authentication = authentication
+        @deploy = deploy
+        @package_path = package_path
+        @base_url = base_url
+        @state_file = state_file
+        build_oauth2_flow if oauth2_enabled?
+      end
+
+      def enabled?
+        @authentication.enabled?
+      end
+
+      # The paths this authenticator answers itself (OAuth2 login and
+      # callback), mounted by the reactor.
+      def endpoints
+        oauth2_enabled? ? [LOGIN_PATH, @authentication.oauth2.redirect_path] : []
+      end
+
+      def endpoint?(path)
+        endpoints.include?(path)
+      end
+
+      def serve_endpoint(request, response)
+        if request.path == LOGIN_PATH
+          response.status = 302
+          response["Location"] = @oauth2_flow.authorization_url(request)
+          response.body = "Redirecting to the identity provider"
+        else
+          handle_callback(request, response)
+        end
+      end
+
+      # The identity for a request — from the session cookie or Basic
+      # credentials — or nil. An identity always carries "roles"
+      # (possibly empty).
+      def authenticate(request)
+        identity = @session&.identity_from(request)
+        identity || authenticate_basic(request)
+      end
+
+      # 401, with a Basic challenge when basicAuth is enabled.
+      def challenge(response)
+        response.status = 401
+        response["Content-Type"] = "text/plain"
+        response["WWW-Authenticate"] = %(Basic realm="#{realm}") if basic_enabled?
+        response.body = "Unauthorized"
+      end
+
+      # :ok, :unauthenticated or :forbidden for a route's accessControl
+      # ({"roles": [...], "authenticationRequired": bool}).
+      def authorize(identity, access_control)
+        return :ok unless access_control
+        return :unauthenticated if unauthenticated?(identity, access_control)
+        return :forbidden unless roles_allowed?(identity, access_control["roles"])
+
+        :ok
+      end
+
+      private
+
+      def unauthenticated?(identity, access_control)
+        access_control.fetch("authenticationRequired", true) && identity.nil?
+      end
+
+      def roles_allowed?(identity, roles)
+        return true if roles.nil? || roles.empty?
+        return false if identity.nil?
+
+        roles.intersect?(identity["roles"])
+      end
+
+      def basic_enabled? = !!@authentication.basic_auth&.enabled?
+
+      def oauth2_enabled? = !!@authentication.oauth2&.enabled?
+
+      def realm = @authentication.basic_auth&.realm || "capsium"
+
+      def authenticate_basic(request)
+        return unless basic_enabled?
+
+        credentials = basic_credentials(request["Authorization"])
+        return unless credentials
+
+        username, password = credentials
+        return unless htpasswd.verify?(username, password)
+
+        { "name" => username, "roles" => Array(@deploy.roles[username]) }
+      end
+
+      def basic_credentials(header)
+        return unless header&.start_with?("Basic ")
+
+        Base64.decode64(header.delete_prefix("Basic ")).split(":", 2)
+      rescue ArgumentError
+        nil
+      end
+
+      def htpasswd
+        @htpasswd ||= Htpasswd.new(htpasswd_path)
+      end
+
+      # deploy.json's basicAuth.passwdFile overrides the package's
+      # (reactor-side secret storage); the package's passwdFile is
+      # package-relative otherwise.
+      def htpasswd_path
+        @deploy.passwd_file ||
+          File.join(@package_path, @authentication.basic_auth.passwd_file.to_s)
+      end
+
+      def build_oauth2_flow
+        secret = @deploy.client_secret
+        if secret.nil? || secret.empty?
+          raise Error,
+                "oauth2 is enabled but no clientSecret is configured " \
+                "(deploy.json or CAPSIUM_DEPLOY; never in the package)"
+        end
+
+        @session = Session.new(secret: @deploy.session_secret,
+                               state_file: @state_file)
+        @oauth2_flow = OAuth2.new(@authentication.oauth2, client_secret: secret,
+                                                          session: @session,
+                                                          base_url: @base_url)
+      end
+
+      def handle_callback(request, response)
+        query = request.query
+        return respond_invalid_state(response) unless @oauth2_flow.valid_state?(query["state"])
+
+        userinfo = @oauth2_flow.complete(query["code"], request)
+        response.status = 302
+        response["Location"] = "/"
+        response["Set-Cookie"] = @session.cookie_for(identity_from(userinfo))
+        response.body = "Authenticated"
+      rescue OAuth2::FlowError => e
+        response.status = 502
+        response["Content-Type"] = "text/plain"
+        response.body = "OAuth2 provider error: #{e.message}"
+      end
+
+      def respond_invalid_state(response)
+        response.status = 401
+        response["Content-Type"] = "text/plain"
+        response.body = "Invalid OAuth2 state"
+      end
+
+      def identity_from(userinfo)
+        name = userinfo["email"] || userinfo["sub"] || userinfo["name"]
+        {
+          "sub" => userinfo["sub"] || userinfo["id"],
+          "email" => userinfo["email"],
+          "name" => userinfo["name"],
+          "roles" => Array(userinfo["roles"]) | Array(@deploy.roles[name])
+        }.compact
+      end
+    end
+  end
+end

data/lib/capsium/reactor/deploy.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Capsium
+  class Reactor
+    # Reactor-side deployment configuration (deploy.json): everything
+    # that must NOT ship in the package — OAuth2 client secrets, the
+    # session signing secret, role assignments, an alternate htpasswd
+    # file, the public base URL. Shape:
+    #
+    #   {
+    #     "baseUrl": "http://localhost:8864",
+    #     "authentication": {
+    #       "basicAuth": { "passwdFile": "/secure/.htpasswd" },
+    #       "oauth2": { "clientSecret": "..." },
+    #       "sessionSecret": "...",
+    #       "roles": { "alice": ["admin"] }
+    #     }
+    #   }
+    #
+    # Loaded from an explicit path, an already-parsed Hash, or the
+    # CAPSIUM_DEPLOY environment variable; empty when unconfigured.
+    class Deploy
+      FILE = "deploy.json"
+      ENV_VAR = "CAPSIUM_DEPLOY"
+
+      attr_reader :config
+
+      def self.load(source)
+        return new(source) if source.is_a?(Hash)
+
+        path = source || ENV.fetch(ENV_VAR, nil)
+        return new({}) if path.nil? || path.to_s.empty?
+        raise Error, "deploy configuration not found: #{path}" unless File.file?(path)
+
+        new(JSON.parse(File.read(path)))
+      end
+
+      def initialize(config)
+        @config = config
+      end
+
+      def authentication
+        config["authentication"] || {}
+      end
+
+      def base_url
+        config["baseUrl"]
+      end
+
+      def client_secret
+        authentication.dig("oauth2", "clientSecret")
+      end
+
+      def session_secret
+        authentication["sessionSecret"]
+      end
+
+      def passwd_file
+        authentication.dig("basicAuth", "passwdFile")
+      end
+
+      # Role assignments keyed by identity name (basic-auth username,
+      # OAuth2 email or subject): {"alice": ["admin", "user"]}.
+      def roles
+        authentication["roles"] || {}
+      end
+    end
+  end
+end