capsium 0.2.0 → 0.3.0

data/lib/capsium/reactor/oauth2.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+module Capsium
+  class Reactor
+    # OAuth2 authorization-code flow client (05x-authentication), used by
+    # the Authenticator. Talks to the provider over net/http; the client
+    # secret never comes from the package. State is a random nonce signed
+    # with the session HMAC key (CSRF protection, self-contained).
+    class OAuth2
+      # The token exchange or userinfo fetch failed at the provider.
+      class FlowError < Capsium::Error; end
+
+      GRANT_TYPE = "authorization_code"
+
+      attr_reader :config
+
+      def initialize(config, client_secret:, session:, base_url: nil)
+        @config = config
+        @client_secret = client_secret
+        @session = session
+        @base_url = base_url
+      end
+
+      # The provider URL the login endpoint redirects the browser to.
+      def authorization_url(request)
+        params = {
+          "response_type" => "code",
+          "client_id" => @config.client_id,
+          "redirect_uri" => callback_uri(request),
+          "state" => generate_state
+        }
+        params["scope"] = @config.scopes.join(" ") unless @config.scopes.empty?
+        "#{@config.authorization_url}?#{URI.encode_www_form(params)}"
+      end
+
+      def valid_state?(state)
+        nonce, signature = state.to_s.split(".", 2)
+        return false if nonce.nil? || nonce.empty? || signature.nil?
+
+        Reactor.secure_compare(@session.sign(nonce), signature)
+      end
+
+      # Exchanges the authorization code and fetches the userinfo claims.
+      # Returns the raw userinfo hash; raises FlowError on provider
+      # errors.
+      def complete(code, request)
+        userinfo(exchange_code(code, callback_uri(request)))
+      end
+
+      def callback_uri(request)
+        "#{base_url_for(request)}#{@config.redirect_path}"
+      end
+
+      private
+
+      def generate_state
+        nonce = SecureRandom.hex(16)
+        "#{nonce}.#{@session.sign(nonce)}"
+      end
+
+      def base_url_for(request)
+        @base_url || "http://#{request['Host']}"
+      end
+
+      def exchange_code(code, redirect_uri)
+        response = Net::HTTP.post_form(
+          URI(@config.token_url),
+          "grant_type" => GRANT_TYPE, "code" => code,
+          "redirect_uri" => redirect_uri, "client_id" => @config.client_id,
+          "client_secret" => @client_secret
+        )
+        unless response.is_a?(Net::HTTPSuccess)
+          raise FlowError, "token exchange failed (HTTP #{response.code})"
+        end
+
+        JSON.parse(response.body).fetch("access_token") do
+          raise FlowError, "token response without access_token"
+        end
+      rescue JSON::ParserError
+        raise FlowError, "token response was not JSON"
+      end
+
+      def userinfo(access_token)
+        uri = URI(@config.userinfo_url)
+        response = Net::HTTP.start(uri.host, uri.port,
+                                   use_ssl: uri.scheme == "https") do |http|
+          http.get(uri.request_uri,
+                   "authorization" => "Bearer #{access_token}",
+                   "accept" => "application/json")
+        end
+        unless response.is_a?(Net::HTTPSuccess)
+          raise FlowError, "userinfo request failed (HTTP #{response.code})"
+        end
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise FlowError, "userinfo response was not JSON"
+      end
+    end
+  end
+end

data/lib/capsium/reactor/serving.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "marcel"
+require "pathname"
+
+module Capsium
+  class Reactor
+    # Serving of resolved routes (static files through the merged view,
+    # datasets, handler-route 501s), mixed into Reactor. Includes route
+    # inheritance processing per 05x-routing.
+    module Serving
+      private
+
+      def serve_route(route, response)
+        case route.kind
+        when :dataset then serve_dataset(route.dataset, response)
+        when :resource then serve_file(route, response)
+        else respond_not_implemented(response)
+        end
+      end
+
+      def serve_file(route, response)
+        content_path = @merged_view.resolve(route.resource)
+        return respond_not_found(response) unless content_path
+
+        body, headers = inherited_processing(route, File.read(content_path),
+                                             headers_for(route))
+        response.status = 200
+        response["Content-Type"] = content_type_for(route, content_path)
+        headers.each { |name, value| response[name] = value }
+        response.body = body
+      end
+
+      # Route inheritance processing (05x-routing section "Route
+      # Inheritance"): responseRewrite replaces the body and/or overrides
+      # headers; responseHeaders are merged over the served headers.
+      # requestHeaders are parsed and exposed on the route for forwarding
+      # reactors; this reactor serves statically without an upstream, so
+      # they do not alter its responses.
+      def inherited_processing(route, body, headers)
+        rewrite = route.response_rewrite
+        if rewrite
+          body = rewrite.body unless rewrite.body.nil?
+          headers = headers.merge(rewrite.headers) if rewrite.headers
+        end
+        headers = headers.merge(route.response_headers) if route.response_headers
+        [body, headers]
+      end
+
+      # The route's declared MIME type, detected from the resolved file
+      # for resources the manifest does not list (dependency content
+      # reached through inheritance, layer-only files).
+      def content_type_for(route, content_path)
+        route.mime(@package.manifest) ||
+          Marcel::MimeType.for(Pathname.new(content_path),
+                               name: File.basename(content_path))
+      end
+
+      def headers_for(route)
+        route.headers || (@cache_control ? { "Cache-Control" => @cache_control } : {})
+      end
+
+      def serve_dataset(dataset_name, response)
+        dataset = @package.storage.dataset(dataset_name)
+        if dataset
+          response.status = 200
+          response["Content-Type"] = "application/json"
+          response.body = JSON.generate(dataset.data)
+        else
+          respond_not_found(response)
+        end
+      end
+    end
+  end
+end

data/lib/capsium/reactor/session.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+require "securerandom"
+
+module Capsium
+  class Reactor
+    # HMAC-SHA256 signed session cookies (05x-authentication: "Session
+    # via signed cookie"). The cookie value is
+    # "base64url(JSON payload).hmac hex" — signed, not encrypted, so it
+    # carries only the identity claims. The signing secret comes from
+    # deploy.json (sessionSecret) or is generated and persisted
+    # reactor-side (never in the package).
+    class Session
+      COOKIE_NAME = "capsium_session"
+      SECRET_BYTES = 32
+
+      def self.hmac(secret, data)
+        OpenSSL::HMAC.hexdigest("SHA256", secret, data)
+      end
+
+      attr_reader :secret
+
+      def initialize(secret: nil, state_file: nil)
+        @secret = secret || self.class.load_or_generate_secret(state_file)
+      end
+
+      # HMAC-SHA256 of data with the session secret (hex).
+      def sign(data)
+        self.class.hmac(@secret, data)
+      end
+
+      # The persisted reactor-side secret: loaded from state_file when
+      # present, generated and written (mode 0600) otherwise.
+      def self.load_or_generate_secret(state_file)
+        raise Error, "session secret or state_file is required" unless state_file
+
+        return File.read(state_file).strip if File.file?(state_file)
+
+        secret = SecureRandom.hex(SECRET_BYTES)
+        File.write(state_file, secret, perm: 0o600)
+        secret
+      end
+
+      def encode(payload)
+        data = Base64.urlsafe_encode64(JSON.generate(payload), padding: false)
+        "#{data}.#{self.class.hmac(@secret, data)}"
+      end
+
+      # The verified payload, or nil when the cookie is missing or the
+      # signature does not match.
+      def decode(cookie_value)
+        data, signature = cookie_value.to_s.split(".", 2)
+        return if data.nil? || signature.nil?
+
+        expected = self.class.hmac(@secret, data)
+        return unless Reactor.secure_compare(expected, signature)
+
+        JSON.parse(Base64.urlsafe_decode64(data))
+      rescue JSON::ParserError, ArgumentError
+        nil
+      end
+
+      # The identity for a request's Cookie header, or nil.
+      def identity_from(request)
+        cookie = request["Cookie"].to_s.split(/;\s*/).find do |part|
+          part.start_with?("#{COOKIE_NAME}=")
+        end
+        return unless cookie
+
+        decode(cookie.delete_prefix("#{COOKIE_NAME}="))
+      end
+
+      # A Set-Cookie value establishing the identity session.
+      def cookie_for(identity)
+        "#{COOKIE_NAME}=#{encode(identity)}; Path=/; HttpOnly; SameSite=Lax"
+      end
+    end
+  end
+end

data/lib/capsium/reactor.rb

@@ -2,24 +2,36 @@
 
 require "json"
 require "listen"
+require "tmpdir"
 require "webrick"
 
 module Capsium
   class Reactor
+    autoload :Authenticator, "capsium/reactor/authenticator"
+    autoload :Deploy, "capsium/reactor/deploy"
+    autoload :Htpasswd, "capsium/reactor/htpasswd"
     autoload :Introspection, "capsium/reactor/introspection"
+    autoload :OAuth2, "capsium/reactor/oauth2"
+    autoload :Serving, "capsium/reactor/serving"
+    autoload :Session, "capsium/reactor/session"
+
+    include Serving
 
     DEFAULT_PORT = 8864
     DEFAULT_CACHE_CONTROL = "public, max-age=31536000"
 
     attr_reader :package, :package_path, :routes, :port, :cache_control,
-                :server, :server_thread, :introspection
+                :server, :server_thread, :introspection, :authenticator
 
     def initialize(package:, port: DEFAULT_PORT,
-                   cache_control: DEFAULT_CACHE_CONTROL, do_not_listen: false)
-      @package = package.is_a?(String) ? Package.new(package) : package
+                   cache_control: DEFAULT_CACHE_CONTROL, do_not_listen: false,
+                   store: nil, deploy: nil)
+      @package = package.is_a?(String) ? Package.new(package, store: store) : package
       @package_path = @package.path
+      @store = store
       @port = port
       @cache_control = cache_control
+      @deploy_config = Deploy.load(deploy)
       setup_server(do_not_listen)
       load_state
       mount_routes
@@ -32,14 +44,29 @@ module Capsium
     end
 
     def handle_request(request, response)
+      if @authenticator.endpoint?(request.path)
+        @authenticator.serve_endpoint(request, response)
+        return
+      end
+
+      identity = @authenticator.authenticate(request)
+      return @authenticator.challenge(response) if @authenticator.enabled? && identity.nil?
       return serve_introspection(request, response) if @introspection.endpoint?(request.path)
 
       route = @routes.resolve(request.path)
-      route ? serve_route(route, response) : respond_not_found(response)
+      return respond_not_found(response) unless route
+
+      case @authenticator.authorize(identity, route.access_control)
+      when :unauthenticated then return @authenticator.challenge(response)
+      when :forbidden then return respond_forbidden(response)
+      end
+
+      serve_route(route, response)
     end
 
     def mount_routes
-      paths = @routes.config.routes.map(&:path) + Introspection::PATHS
+      paths = @routes.config.routes.map(&:serving_path) +
+              Introspection::PATHS + @authenticator.endpoints
       paths.each do |path|
         @server.mount_proc(path.to_s) { |req, res| handle_request(req, res) }
       end
@@ -87,13 +114,21 @@ module Capsium
     end
 
     def load_package
-      @package = Package.new(@package_path)
+      @package = Package.new(@package_path, store: @store)
       load_state
     end
 
     def load_state
       @routes = @package.routes
+      @merged_view = @package.merged_view
       @introspection = Introspection.new(@package)
+      @authenticator = Authenticator.new(
+        @package.authentication,
+        deploy: @deploy_config,
+        package_path: @package.path,
+        base_url: @deploy_config.base_url,
+        state_file: File.join(Dir.tmpdir, "capsium-#{@package.name}-session-secret")
+      )
     end
 
     def serve_introspection(request, response)
@@ -104,43 +139,10 @@ module Capsium
       response.body = JSON.generate(@introspection.report_for(request.path))
     end
 
-    def serve_route(route, response)
-      case route.kind
-      when :dataset then serve_dataset(route.dataset, response)
-      when :resource then serve_file(route, response)
-      else respond_not_implemented(response)
-      end
-    end
-
-    def serve_file(route, response)
-      content_path = route.fs_path(@package.path)
-      if content_path && File.exist?(content_path)
-        response.status = 200
-        response["Content-Type"] = route.mime(@package.manifest) || "application/octet-stream"
-        headers_for(route).each { |name, value| response[name] = value }
-        response.body = File.read(content_path)
-      else
-        respond_not_found(response)
-      end
-    end
-
-    def headers_for(route)
-      route.headers || (@cache_control ? { "Cache-Control" => @cache_control } : {})
-    end
-
-    def serve_dataset(dataset_name, response)
-      dataset = @package.storage.dataset(dataset_name)
-      if dataset
-        response.status = 200
-        response["Content-Type"] = "application/json"
-        response.body = JSON.generate(dataset.data)
-      else
-        respond_not_found(response)
-      end
-    end
-
     def respond_not_found(response) = respond_text(response, 404, "Not Found")
 
+    def respond_forbidden(response) = respond_text(response, 403, "Forbidden")
+
     def respond_not_implemented(response) = respond_text(response, 501, "Not Implemented")
 
     def respond_method_not_allowed(response) = respond_text(response, 405, "Method Not Allowed")

data/lib/capsium/thor_ext.rb

@@ -60,7 +60,7 @@ module Capsium
         return if error.is_a?(Errno::EPIPE)
         raise if ENV["VERBOSE"] || !config.fetch(:exit_on_failure, true)
 
-        message = error.message.to_s
+        message = +error.message.to_s
         message.prepend("[#{error.class}] ") if message.empty? || !error.is_a?(Thor::Error)
 
         config[:shell]&.say_error(message, :red)

data/lib/capsium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Capsium
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/sig/capsium/package/authentication.rbs

@@ -0,0 +1,23 @@
+module Capsium
+  class Package
+    # Loads a package's authentication.json (ARCHITECTURE.md section 4b).
+    class Authentication
+      attr_reader path: String
+      attr_reader config: AuthenticationConfig?
+
+      def initialize: (String path) -> void
+
+      def present?: () -> bool
+
+      def basic_auth: () -> BasicAuthConfig?
+
+      def oauth2: () -> OAuth2Config?
+
+      # Whether any authentication method is enabled.
+      def enabled?: () -> bool
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/authentication_config.rbs

@@ -0,0 +1,71 @@
+module Capsium
+  class Package
+    # The "basicAuth" object of authentication.json (ARCHITECTURE.md
+    # section 4b): Apache-style Basic authentication verified against an
+    # htpasswd file.
+    class BasicAuthConfig
+      attr_accessor enabled: bool
+      attr_accessor passwd_file: String?
+      attr_accessor realm: String
+
+      def initialize: (?enabled: bool enabled, ?passwd_file: String? passwd_file,
+                       ?realm: String? realm) -> void
+
+      def enabled?: () -> bool
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The "oauth2" object of authentication.json: an OAuth2
+    # authorization-code flow. The client secret is NEVER read from the
+    # package — it comes from deploy.json or reactor configuration.
+    class OAuth2Config
+      attr_accessor enabled: bool
+      attr_accessor provider: String?
+      attr_accessor client_id: String?
+      attr_accessor authorization_url: String?
+      attr_accessor token_url: String?
+      attr_accessor userinfo_url: String?
+      attr_accessor redirect_path: String
+      attr_accessor scopes: Array[String]
+
+      def initialize: (?enabled: bool enabled, ?provider: String? provider,
+                       ?client_id: String? client_id,
+                       ?authorization_url: String? authorization_url,
+                       ?token_url: String? token_url,
+                       ?userinfo_url: String? userinfo_url,
+                       ?redirect_path: String? redirect_path,
+                       ?scopes: Array[String] scopes) -> void
+
+      def enabled?: () -> bool
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The "authentication" object of authentication.json.
+    class AuthenticationData
+      attr_accessor basic_auth: BasicAuthConfig?
+      attr_accessor oauth2: OAuth2Config?
+
+      def initialize: (?basic_auth: BasicAuthConfig? basic_auth,
+                       ?oauth2: OAuth2Config? oauth2) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical authentication.json model (ARCHITECTURE.md section 4b).
+    class AuthenticationConfig
+      attr_accessor authentication: AuthenticationData?
+
+      def initialize: (?authentication: AuthenticationData? authentication) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/cipher.rbs

@@ -0,0 +1,51 @@
+module Capsium
+  class Package
+    # Encrypts and decrypts whole Capsium packages (05x-packaging
+    # "Encryption", 05x-security "Encrypted information"). An encrypted
+    # .cap is a zip containing metadata.json (cleartext), signature.json
+    # (the encryption envelope) and package.enc (AES-256-GCM of the inner
+    # plaintext .cap zip). The random DEK is wrapped with the recipient's
+    # RSA public key using OAEP with SHA-256. OCB/OpenPGP are out of
+    # scope.
+    class Cipher
+      ALGORITHM: String
+      KEY_MANAGEMENT: String
+      CIPHER_NAME: String
+      ENCRYPTED_FILE: String
+      ENVELOPE_FILE: String
+      RSA_OPTIONS: Hash[String, String]
+
+      # Structural problems: unreadable input, missing zip entries,
+      # unsupported envelope algorithms, unloadable keys.
+      class CipherError < Capsium::Error
+      end
+
+      # An encrypted package was opened without a private key.
+      class KeyRequiredError < CipherError
+      end
+
+      # Decryption failed: wrong private key or tampered ciphertext.
+      class DecryptionError < CipherError
+      end
+
+      # Whether the path (.cap file or uncompressed directory) is an
+      # encrypted package, i.e. contains package.enc.
+      def self.encrypted?: (String | Pathname path) -> bool
+
+      # Encrypts the package at source_path (a .cap file, or a package
+      # directory which is packed first) for the recipient's RSA public
+      # key (or X.509 certificate) and writes the encrypted .cap to
+      # output_path. Returns output_path.
+      def encrypt: (String source_path, String public_key_path, String output_path) -> String
+
+      # Decrypts the encrypted package at encrypted_path (.cap file or
+      # uncompressed directory) with the recipient's RSA private key and
+      # writes the plaintext .cap to output_path. Returns output_path.
+      def decrypt: (String | Pathname encrypted_path, String private_key_path, String output_path) -> String
+
+      # Decrypts an encrypted package into a fresh temporary directory
+      # and returns the directory path.
+      def self.decrypt_to_directory: (String | Pathname source_path, String private_key_path) -> String
+    end
+  end
+end

data/sig/capsium/package/composition.rbs

@@ -0,0 +1,20 @@
+module Capsium
+  class Package
+    # Composite-package support (ARCHITECTURE.md section 4a), mixed into
+    # Package: metadata.dependencies resolution against a package store
+    # and load-time validation of dependency resource references.
+    module Composition
+      private
+
+      def resolve_dependencies: ((Store | String)? store, Array[String] chain) -> Array[ResolvedDependency]
+
+      def validate_dependency_references!: () -> void
+
+      def validate_dependency_reference: (Route route, ResolvedDependency dependency, String reference) -> void
+
+      def dependency_for: (String reference) -> ResolvedDependency?
+
+      def dependency_views: () -> Array[[String, MergedView]]
+    end
+  end
+end

data/sig/capsium/package/dependency_resolver.rbs

@@ -0,0 +1,49 @@
+module Capsium
+  class Package
+    # Base error for composite-package dependency resolution
+    # (ARCHITECTURE.md section 4a).
+    class DependencyError < Capsium::Error
+    end
+
+    # No package in the store provides the dependency GUID.
+    class DependencyNotFoundError < DependencyError
+    end
+
+    # The store provides the GUID but no version satisfies the range.
+    class UnsatisfiableDependencyError < DependencyError
+    end
+
+    # A dependency cycle was detected while resolving.
+    class CircularDependencyError < DependencyError
+    end
+
+    # A dependent route references a dependency resource that is not
+    # exported (private) and therefore not visible to dependents.
+    class DependencyVisibilityError < DependencyError
+    end
+
+    # One resolved dependency: the declared GUID and range, the .cap it
+    # resolved to and the loaded package.
+    class ResolvedDependency
+      def self.new: (String guid, String range, String path, Package package) -> void
+
+      def guid: () -> String
+      def range: () -> String
+      def path: () -> String
+      def package: () -> Package
+      def version: () -> String?
+    end
+
+    # Orchestrates metadata.dependencies resolution against a package
+    # store: circularity checks plus store lookup.
+    class DependencyResolver
+      attr_reader store: Store
+
+      def initialize: (Store | String? store) -> void
+
+      # The newest store .cap satisfying the dependency, raising typed
+      # errors for circular, missing or unsatisfiable dependencies.
+      def resolve_path: (String guid, String range, chain: Array[String] chain) -> String
+    end
+  end
+end

data/sig/capsium/package/encryption_config.rbs

@@ -0,0 +1,35 @@
+module Capsium
+  class Package
+    # The "encryption" object of signature.json in an encrypted package:
+    # the AES-256-GCM envelope with the RSA-OAEP-SHA256 wrapped DEK, all
+    # binary values Base64-encoded.
+    class EncryptionEnvelope
+      attr_accessor algorithm: String?
+      attr_accessor key_management: String?
+      attr_accessor encrypted_dek: String?
+      attr_accessor iv: String?
+      attr_accessor auth_tag: String?
+
+      def initialize: (?algorithm: String? algorithm,
+                       ?key_management: String? key_management,
+                       ?encrypted_dek: String? encrypted_dek,
+                       ?iv: String? iv,
+                       ?auth_tag: String? auth_tag) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The signature.json file of an encrypted package.
+    class EncryptionConfig
+      attr_accessor encryption: EncryptionEnvelope?
+
+      def initialize: (?encryption: EncryptionEnvelope? encryption) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end