capsium 0.2.0 → 0.6.0

data/lib/capsium/reactor/data_api.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Capsium
+  class Reactor
+    # REST CRUD over a mount's datasets (ARCHITECTURE.md sections 5 and
+    # 5a): JSON item append/read/replace/delete against the overlay-
+    # merged collection. Writes go only to the mount's writable overlay;
+    # the immutable package never changes on disk.
+    class DataApi
+      include Responses
+
+      PREFIX = "/api/v1/data/"
+      COLLECTION_PATTERN = %r{\A/api/v1/data/(?<dataset>[^/]+)\z}
+      ITEM_PATTERN = %r{\A/api/v1/data/(?<dataset>[^/]+)/(?<id>[^/]+)\z}
+
+      def self.path?(inner_path)
+        inner_path.start_with?(PREFIX)
+      end
+
+      def initialize(mount)
+        @mount = mount
+      end
+
+      # The declared dataset route a data path addresses (the collection
+      # route, also for item paths), or nil when the package does not
+      # route this dataset — undeclared datasets are not served.
+      def route_for(inner_path)
+        match = COLLECTION_PATTERN.match(inner_path) || ITEM_PATTERN.match(inner_path)
+        return nil unless match
+
+        route = @mount.routes.resolve("#{PREFIX}#{match[:dataset]}")
+        route if route&.dataset == match[:dataset]
+      end
+
+      def handle(inner_path, request, response)
+        route = route_for(inner_path)
+        return respond_not_found(response) unless route
+
+        dataset = @mount.package.storage.dataset(route.dataset)
+        return respond_not_found(response) unless dataset
+
+        collection = COLLECTION_PATTERN.match(inner_path)
+        if collection
+          handle_collection(dataset, request, response)
+        else
+          handle_item(dataset, ITEM_PATTERN.match(inner_path)[:id], request, response)
+        end
+      end
+
+      private
+
+      def handle_collection(dataset, request, response)
+        case request.request_method
+        when "GET" then respond_json(response, 200, @mount.dataset_data(dataset))
+        when "POST" then append_item(dataset, request, response)
+        else respond_method_not_allowed(response)
+        end
+      end
+
+      def handle_item(dataset, id, request, response)
+        case request.request_method
+        when "GET" then read_item(dataset, id, response)
+        when "PUT" then replace_item(dataset, id, request, response)
+        when "DELETE" then delete_item(dataset, id, response)
+        else respond_method_not_allowed(response)
+        end
+      end
+
+      def append_item(dataset, request, response)
+        return unless writable?(dataset, response)
+
+        item = parse_body(request, response)
+        return if item.nil?
+
+        id = @mount.overlay.append_item(dataset, item)
+        response["Location"] = "#{request.path}/#{id}"
+        respond_json(response, 201, item)
+      rescue Overlay::Error => e
+        respond_overlay_error(response, e)
+      end
+
+      def read_item(dataset, id, response)
+        respond_json(response, 200, @mount.overlay.item(dataset, id))
+      rescue Overlay::ItemNotFoundError
+        respond_not_found(response)
+      end
+
+      def replace_item(dataset, id, request, response)
+        return unless writable?(dataset, response)
+
+        item = parse_body(request, response)
+        return if item.nil?
+
+        @mount.overlay.replace_item(dataset, id, item)
+        respond_json(response, 200, item)
+      rescue Overlay::ItemNotFoundError
+        respond_not_found(response)
+      rescue Overlay::Error => e
+        respond_overlay_error(response, e)
+      end
+
+      def delete_item(dataset, id, response)
+        return unless writable?(dataset, response)
+
+        @mount.overlay.delete_item(dataset, id)
+        response.status = 204
+      rescue Overlay::ItemNotFoundError
+        respond_not_found(response)
+      end
+
+      # Write guards: 403 for a read-only mount, 501 for a SQLite
+      # dataset (not file-backed JSON/YAML).
+      def writable?(dataset, response)
+        unless @mount.writable?
+          respond_error(response, 403, "package #{@mount.package.name} is read-only")
+          return false
+        end
+        if dataset.config.sqlite?
+          respond_error(response, 501,
+                        "dataset #{dataset.name} is SQLite; writes are not supported")
+          return false
+        end
+        true
+      end
+
+      # The JSON request body, or nil after answering 400 (invalid JSON)
+      # or 422 (a null body cannot be an item).
+      def parse_body(request, response)
+        body = JSON.parse(request.body.to_s)
+        if body.nil?
+          respond_error(response, 422, "request body must not be null")
+          return nil
+        end
+
+        body
+      rescue JSON::ParserError => e
+        respond_error(response, 400, "invalid JSON body: #{e.message}")
+        nil
+      end
+
+      def respond_overlay_error(response, error)
+        case error
+        when Overlay::ConflictError then respond_error(response, 409, error.message)
+        when Overlay::SchemaViolationError
+          respond_error(response, 422, "schema validation failed",
+                        messages: error.messages)
+        else respond_error(response, 422, error.message)
+        end
+      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

data/lib/capsium/reactor/endpoints.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Capsium
+  class Reactor
+    # Serving of the reactor-level endpoints (introspection reports,
+    # per-package save), mixed into Reactor.
+    module Endpoints
+      include Responses
+
+      private
+
+      def serve_introspection(request, response)
+        return respond_method_not_allowed(response) unless request.request_method == "GET"
+
+        report = @introspection.report_for(request.path, params: request.query)
+        return respond_not_found(response) if report.nil?
+
+        respond_json(response, 200, report)
+      end
+
+      # POST /package/<name>/save: folds the mounted package's base plus
+      # its overlay into a new versioned .cap in the workdir.
+      def serve_package_save(request, response)
+        return respond_method_not_allowed(response) unless request.request_method == "POST"
+
+        name = PACKAGE_SAVE_PATTERN.match(request.path)[:name]
+        mount = @mounts.find { |candidate| candidate.package.name == name }
+        return respond_not_found(response) unless mount
+        return respond_error(response, 403, "package #{name} is read-only") unless mount.writable?
+
+        respond_json(response, 200, PackageSaver.new(mount).save(@workdir))
+      end
+    end
+  end
+end

data/lib/capsium/reactor/graphql_api.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "graphql"
+require "json"
+
+module Capsium
+  class Reactor
+    # GraphQL over a mount's datasets (POST and GET <mount>/graphql):
+    # executes the schema GraphqlSchema derives from the package's
+    # storage and maps the overlay's typed errors into the "errors"
+    # array (never a 500 on user error). Query fields read the merged
+    # collection; mutations match the REST semantics, schema validation
+    # included.
+    class GraphqlApi
+      include Responses
+
+      PATH = "/graphql"
+
+      def self.path?(inner_path)
+        inner_path == PATH
+      end
+
+      def initialize(mount)
+        @mount = mount
+        @schema = GraphqlSchema.new(mount, self).build
+      end
+
+      def handle(request, response)
+        case request.request_method
+        when "POST" then handle_post(request, response)
+        when "GET" then handle_get(request, response)
+        else respond_method_not_allowed(response)
+        end
+      end
+
+      # Query/mutation resolvers (public; called from the derived
+      # schema's fields).
+      def collection(dataset, id: nil)
+        return @mount.overlay.items(dataset) if id.nil?
+
+        [@mount.overlay.item(dataset, id)]
+      rescue Overlay::Error => e
+        raise execution_error(e)
+      end
+
+      def create_item(dataset, item:)
+        ensure_writable!
+        @mount.overlay.append_item(dataset, item)
+        item
+      rescue Overlay::Error => e
+        raise execution_error(e)
+      end
+
+      def update_item(dataset, id:, item:)
+        ensure_writable!
+        @mount.overlay.replace_item(dataset, id, item)
+        item
+      rescue Overlay::Error => e
+        raise execution_error(e)
+      end
+
+      def remove_item(dataset, id:)
+        ensure_writable!
+        @mount.overlay.delete_item(dataset, id)
+        true
+      rescue Overlay::Error => e
+        raise execution_error(e)
+      end
+
+      private
+
+      def handle_post(request, response)
+        payload = JSON.parse(request.body.to_s)
+        unless payload.is_a?(Hash) && payload["query"].is_a?(String)
+          return respond_error(response, 400, "GraphQL POST body must be " \
+                                              '{"query": "...", "variables": {...}}')
+        end
+
+        execute(response, payload["query"], variables: payload["variables"],
+                                            operation_name: payload["operationName"])
+      rescue JSON::ParserError => e
+        respond_error(response, 400, "invalid JSON body: #{e.message}")
+      end
+
+      def handle_get(request, response)
+        query = request.query["query"]
+        return respond_error(response, 400, "missing GraphQL query") if query.nil?
+
+        execute(response, query, variables: parse_variables(request.query["variables"]),
+                                 operation_name: request.query["operationName"])
+      end
+
+      def parse_variables(raw)
+        return nil if raw.nil?
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def execute(response, query, variables:, operation_name:)
+        result = @schema.execute(query, variables: variables || {},
+                                        operation_name: operation_name)
+        respond_json(response, 200, result.to_h)
+      end
+
+      def ensure_writable!
+        return if @mount.writable?
+
+        raise GraphQL::ExecutionError, "package #{@mount.package.name} is read-only"
+      end
+
+      def execution_error(error)
+        message = if error.is_a?(Overlay::SchemaViolationError)
+                    error.messages.join("; ")
+                  else
+                    error.message
+                  end
+        GraphQL::ExecutionError.new(message)
+      end
+    end
+  end
+end

data/lib/capsium/reactor/graphql_schema.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "graphql"
+
+module Capsium
+  class Reactor
+    # Builds the GraphQL schema for a mounted package (ARCHITECTURE.md
+    # section 5): per dataset a query field "<dataset>" (list, optional
+    # "id:" argument for a single item) plus
+    # create<Dataset>/update<Dataset>/delete<Dataset> mutations.
+    # Item types are inferred from the dataset's JSON schema when
+    # present, else map to a permissive JSON scalar. Field resolvers
+    # delegate to the given API object's public methods.
+    class GraphqlSchema
+      # Permissive scalar carrying any JSON value (schema-less items,
+      # mutation inputs, nested structures).
+      class JsonScalar < GraphQL::Schema::Scalar
+        graphql_name("JSON")
+        description "An arbitrary JSON value"
+
+        def self.coerce_input(input_value, _context) = input_value
+
+        def self.coerce_result(ruby_value, _context) = ruby_value
+      end
+
+      def initialize(mount, api)
+        @mount = mount
+        @api = api
+      end
+
+      def build
+        api = @api
+        query_type = Class.new(GraphQL::Schema::Object) { graphql_name("Query") }
+        mutation_type = Class.new(GraphQL::Schema::Object) { graphql_name("Mutation") }
+        @mount.package.storage.datasets.each do |dataset|
+          next if dataset.config.sqlite?
+
+          add_dataset_fields(query_type, mutation_type, dataset, api)
+        end
+        Class.new(GraphQL::Schema) do
+          query(query_type)
+          mutation(mutation_type)
+        end
+      end
+
+      private
+
+      def add_dataset_fields(query_type, mutation_type, dataset, api)
+        name = graphql_name_for(dataset.name)
+        type = item_type_for(dataset, name)
+        add_query_field(query_type, name, type, dataset, api)
+        add_mutation_fields(mutation_type, name, type, dataset, api)
+      end
+
+      # "<dataset>" returns the merged item list; with "id:" the single
+      # matching item (a one-element list, not-found in "errors").
+      def add_query_field(query_type, name, type, dataset, api)
+        query_type.class_eval do
+          field name, [type], null: false, camelize: false do
+            argument :id, String, required: false
+          end
+          define_method(name) { |id: nil| api.collection(dataset, id: id) }
+        end
+      end
+
+      # create<Dataset>/update<Dataset>/delete<Dataset> with the same
+      # semantics (and schema validation) as the REST verbs.
+      def add_mutation_fields(mutation_type, name, type, dataset, api)
+        capitalized = name.sub(/\A./, &:upcase)
+        mutation_type.class_eval do
+          field "create#{capitalized}", type, null: true, camelize: false do
+            argument :item, JsonScalar, required: true
+          end
+          define_method("create#{capitalized}") { |item:| api.create_item(dataset, item: item) }
+
+          field "update#{capitalized}", type, null: true, camelize: false do
+            argument :id, String, required: true
+            argument :item, JsonScalar, required: true
+          end
+          define_method("update#{capitalized}") do |id:, item:|
+            api.update_item(dataset, id: id, item: item)
+          end
+
+          field "delete#{capitalized}", GraphQL::Types::Boolean, null: false, camelize: false do
+            argument :id, String, required: true
+          end
+          define_method("delete#{capitalized}") { |id:| api.remove_item(dataset, id: id) }
+        end
+      end
+
+      # The item type inferred from the dataset's JSON schema (the
+      # schema describes the collection; its "items" describe an item),
+      # else the permissive JSON scalar.
+      def item_type_for(dataset, name)
+        properties = item_properties(dataset.json_schema)
+        return JsonScalar if properties.nil? || properties.empty?
+
+        fields = properties.to_h { |property, spec| [property, graphql_type_for(spec)] }
+        Class.new(GraphQL::Schema::Object) do
+          graphql_name("#{name.sub(/\A./, &:upcase)}Item")
+          fields.each do |property, type|
+            field property, type, null: true, camelize: false
+            define_method(property) { object[property] }
+          end
+        end
+      end
+
+      def item_properties(schema)
+        return nil unless schema.is_a?(Hash)
+
+        if schema["type"] == "array" && schema["items"].is_a?(Hash)
+          schema["items"]["properties"]
+        elsif schema["type"] == "object"
+          schema["properties"]
+        end
+      end
+
+      def graphql_type_for(spec)
+        case spec.is_a?(Hash) ? spec["type"] : nil
+        when "string" then String
+        when "integer" then Integer
+        when "number" then Float
+        when "boolean" then GraphQL::Types::Boolean
+        when "array" then [graphql_type_for(spec["items"] || {})]
+        else JsonScalar
+        end
+      end
+
+      # Dataset names become GraphQL identifiers ("my-data" -> "myData").
+      def graphql_name_for(name)
+        parts = name.split(/[^a-zA-Z0-9]+/).reject(&:empty?)
+        return "data" if parts.empty?
+
+        parts.first.downcase + parts.drop(1).map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/capsium/reactor/htpasswd.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "base64"
+require "bcrypt"
+require "digest"
+require "openssl"
+
+module Capsium
+  class Reactor
+    # Apache htpasswd verification (05x-authentication). Supported hash
+    # formats:
+    # - bcrypt ($2a$/$2b$/$2y$, `htpasswd -B`) via the bcrypt gem
+    # - Apache apr1 MD5 ($apr1$, `htpasswd -m`) and md5-crypt ($1$),
+    #   pure-Ruby md5-crypt
+    # - unsalted SHA-1 ({SHA}, `htpasswd -s`)
+    # - anything else (DES, $5$/$6$) via the platform's crypt(3) —
+    #   support depends on the OS
+    class Htpasswd
+      # md5-crypt as deployed by Apache htpasswd, OpenSSL and glibc
+      # ($1$ and $apr1$ magics; identical except for the magic string).
+      # NOTE: Poul-Henning Kamp's original FreeBSD implementation mixed
+      # the magic in at the % 7 step where all deployed implementations
+      # mix in the password (see apr_md5.c, glibc crypt-md5.c).
+      module Md5Crypt
+        ITOA64 = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+        DIGEST_GROUPS = [[0, 6, 12], [1, 7, 13], [2, 8, 14], [3, 9, 15], [4, 10, 5]].freeze
+
+        def self.verify(hash, password)
+          _prefix, magic, salt, = hash.split("$", 4)
+          return false if salt.nil? || salt.empty?
+
+          Reactor.secure_compare(digest(password, salt, "$#{magic}$"), hash)
+        end
+
+        def self.digest(password, salt, magic)
+          final = initial_digest(password, salt, magic)
+          1000.times do |i|
+            final = stretch_digest(i, password, salt, final)
+          end
+          "#{magic}#{salt}$#{to64(final)}"
+        end
+
+        def self.initial_digest(password, salt, magic)
+          inner = Digest::MD5.digest(password + salt + password)
+          context = Digest::MD5.new
+          context << password << magic << salt
+          length = password.length
+          while length.positive?
+            context << inner[0, [16, length].min]
+            length -= 16
+          end
+          length = password.length
+          while length.positive?
+            context << (length.odd? ? "\0" : password[0])
+            length >>= 1
+          end
+          context.digest
+        end
+
+        def self.stretch_digest(iteration, password, salt, final)
+          context = Digest::MD5.new
+          context << (iteration.odd? ? password : final)
+          context << salt unless (iteration % 3).zero?
+          context << password unless (iteration % 7).zero?
+          context << (iteration.odd? ? final : password)
+          context.digest
+        end
+
+        # The custom base-64 of md5-crypt: digest triples permuted, first
+        # index to the high bits, 22 characters total.
+        def self.to64(final)
+          encoded = +""
+          DIGEST_GROUPS.each do |a, b, c|
+            value = final[c].ord | (final[b].ord << 8) | (final[a].ord << 16)
+            4.times do
+              encoded << ITOA64[value & 0x3f]
+              value >>= 6
+            end
+          end
+          value = final[11].ord
+          2.times do
+            encoded << ITOA64[value & 0x3f]
+            value >>= 6
+          end
+          encoded
+        end
+      end
+
+      attr_reader :path
+
+      def initialize(path)
+        raise Error, "htpasswd file not found: #{path}" unless File.file?(path)
+
+        @path = path
+        @entries = parse(path)
+      end
+
+      def usernames
+        @entries.keys
+      end
+
+      def verify?(username, password)
+        hash = @entries[username]
+        return false unless hash
+
+        verify_hash(hash, password)
+      end
+
+      private
+
+      def parse(path)
+        File.readlines(path, chomp: true).each_with_object({}) do |line, entries|
+          next if line.strip.empty? || line.start_with?("#")
+
+          username, hash = line.split(":", 2)
+          entries[username] = hash
+        end
+      end
+
+      def verify_hash(hash, password)
+        case hash
+        when /\A\$2[aby]\$/ then verify_bcrypt(hash, password)
+        when /\A\$(?:apr1|1)\$/ then Md5Crypt.verify(hash, password)
+        when /\A\{SHA\}/ then verify_sha1(hash, password)
+        else verify_crypt(hash, password)
+        end
+      end
+
+      # The bcrypt gem predates htpasswd's $2y$ tag; the variants are
+      # algorithmically identical, normalized here.
+      def verify_bcrypt(hash, password)
+        BCrypt::Password.new(hash.sub(/\A\$2y\$/, "$2a$")) == password
+      rescue BCrypt::Errors::InvalidHash
+        false
+      end
+
+      def verify_sha1(hash, password)
+        digest = "{SHA}#{Base64.strict_encode64(Digest::SHA1.digest(password))}"
+        Reactor.secure_compare(digest, hash)
+      end
+
+      def verify_crypt(hash, password)
+        computed = password.crypt(hash)
+        computed && Reactor.secure_compare(computed, hash)
+      end
+    end
+
+    # Constant-time string comparison (length-check first).
+    def self.secure_compare(own, theirs)
+      own.bytesize == theirs.bytesize &&
+        OpenSSL.fixed_length_secure_compare(own, theirs)
+    end
+  end
+end