capsium 0.1.1 → 0.2.0

data/lib/capsium/package/routes_config.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "json"
+require "lutaml/model"
+
+module Capsium
+  class Package
+    # 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)
+    class Route < Lutaml::Model::Serializable
+      DATASET_PATH_PREFIX = "/api/v1/data/"
+
+      attribute :path, :string
+      attribute :resource, :string
+      attribute :headers, :hash
+      attribute :headers_file, :string
+      attribute :visibility, :string, values: Resource::VISIBILITIES
+      attribute :dataset, :string
+      attribute :access_control, :hash
+      attribute :http_method, :string
+      attribute :handler, :string
+
+      json do
+        map :path, to: :path
+        map :resource, to: :resource
+        map :headers, to: :headers
+        map "headersFile", to: :headers_file
+        map :visibility, to: :visibility
+        map :dataset, to: :dataset
+        map "accessControl", to: :access_control
+        map "method", to: :http_method
+        map :handler, to: :handler
+      end
+
+      def kind
+        return :resource if resource
+        return :dataset if dataset
+
+        :handler
+      end
+
+      def dataset_route?
+        kind == :dataset
+      end
+
+      def handler_route?
+        kind == :handler
+      end
+
+      def fs_path(package_path)
+        return unless resource
+
+        File.join(package_path, resource)
+      end
+
+      def mime(manifest)
+        manifest.type_for(resource)
+      end
+
+      def validate_target(package_path, storage)
+        return if handler_route?
+
+        if dataset_route?
+          return if storage.dataset(dataset)
+
+          raise Error, "Route dataset does not exist: #{dataset}"
+        end
+        validate_resource_target(package_path)
+      end
+
+      private
+
+      def validate_resource_target(package_path)
+        target_path = fs_path(package_path)
+        return if target_path && File.exist?(target_path)
+
+        raise Error, "Route resource does not exist: #{resource}"
+      end
+    end
+
+    # Canonical routes.json model: optional top-level "index" plus a
+    # "routes" array. The legacy gem form ({path, target: {file|dataset}})
+    # is accepted on read and normalized; writers emit only the canonical
+    # form.
+    class RoutesConfig < Lutaml::Model::Serializable
+      attribute :index, :string
+      attribute :routes, Route, collection: true, default: []
+
+      json do
+        map :index, to: :index
+        map :routes, with: { from: :routes_from_json, to: :routes_to_json }
+      end
+
+      def self.from_json(json)
+        doc = JSON.parse(json)
+        doc["routes"] = (doc["routes"] || []).map { |route| normalize_route(route) }
+        super(JSON.generate(doc))
+      end
+
+      def self.normalize_route(route)
+        target = route.delete("target")
+        return route unless target.is_a?(Hash)
+
+        route.merge("resource" => target["file"], "dataset" => target["dataset"]).compact
+      end
+      private_class_method :normalize_route
+
+      def routes_from_json(model, value)
+        model.routes = (value || []).map { |route| Route.from_json(JSON.generate(route)) }
+      end
+
+      # Writers emit the canonical form only: deterministic, sorted by path.
+      def routes_to_json(model, doc)
+        doc["routes"] = model.routes.sort_by(&:path).map do |route|
+          JSON.parse(route.to_json)
+        end
+      end
+
+      def resolve(path)
+        routes.detect { |route| route.path == path }
+      end
+
+      def add(path, target)
+        route = Route.new(path: path, resource: target)
+        self.routes = routes + [route]
+        route
+      end
+
+      def update(path, updated_path, updated_target)
+        route = resolve(path)
+        route.path = updated_path
+        route.resource = updated_target
+        route
+      end
+
+      def remove(path)
+        self.routes = routes.reject { |route| route.path == path }
+      end
+
+      def sort!
+        self.routes = routes.sort_by(&:path)
+        self
+      end
+    end
+  end
+end

data/lib/capsium/package/security.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "digest"
+require "forwardable"
+require "json"
+
+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.
+    class Security
+      extend Forwardable
+
+      class IntegrityError < Capsium::Error; end
+
+      ChecksumMismatch = Data.define(:path, :expected, :actual) do
+        def message
+          "checksum mismatch: #{path}"
+        end
+      end
+      MissingFile = Data.define(:path, :expected) do
+        def message
+          "checksum listed but file missing: #{path}"
+        end
+      end
+      UncheckedFile = Data.define(:path) do
+        def message
+          "file not covered by checksums: #{path}"
+        end
+      end
+
+      attr_reader :path, :config
+
+      def_delegators :@config, :to_json, :to_hash
+
+      def initialize(path, config = nil)
+        @path = path
+        @config = config || load_config
+      end
+
+      def self.generate(package_path)
+        config = SecurityConfig.new(
+          security: SecurityData.new(
+            integrity_checks: IntegrityChecks.new(
+              checksum_algorithm: "SHA-256",
+              checksums: checksums_for(package_path)
+            )
+          )
+        )
+        new(File.join(package_path, SECURITY_FILE), config)
+      end
+
+      def self.checksums_for(package_path)
+        package_files(package_path).sort.to_h do |relative_path|
+          [relative_path, Digest::SHA256.file(File.join(package_path, relative_path)).hexdigest]
+        end
+      end
+
+      def self.package_files(package_path)
+        files = Dir.glob(File.join(package_path, "**", "*")).select do |file|
+          File.file?(file)
+        end
+        files.map { |file| file.delete_prefix("#{package_path}/") }
+             .reject { |relative_path| relative_path == SECURITY_FILE }
+      end
+
+      def present?
+        !@config.nil?
+      end
+
+      def checksums
+        present? ? config.checksums : {}
+      end
+
+      def verify(package_path)
+        expected = checksums
+        errors = verify_present_files(package_path, expected)
+        expected.each do |relative_path, checksum|
+          next if File.file?(File.join(package_path, relative_path))
+
+          errors << MissingFile.new(path: relative_path, expected: checksum)
+        end
+        errors
+      end
+
+      def verify!(package_path)
+        errors = verify(package_path)
+        return if errors.empty?
+
+        raise IntegrityError,
+              "Package integrity check failed: #{errors.map(&:path).join(', ')}"
+      end
+
+      def save_to_file(output_path = @path)
+        File.write(output_path, to_json)
+      end
+
+      private
+
+      def load_config
+        return unless File.exist?(@path)
+
+        SecurityConfig.from_json(File.read(@path))
+      end
+
+      def verify_present_files(package_path, expected)
+        self.class.package_files(package_path).filter_map do |relative_path|
+          file_path = File.join(package_path, relative_path)
+          if expected.key?(relative_path)
+            actual = Digest::SHA256.file(file_path).hexdigest
+            unless actual == expected[relative_path]
+              next ChecksumMismatch.new(path: relative_path, expected: expected[relative_path],
+                                        actual: actual)
+            end
+          else
+            UncheckedFile.new(path: relative_path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/capsium/package/security_config.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Capsium
+  class Package
+    # The "integrityChecks" object of security.json (ARCHITECTURE.md
+    # section 6): SHA-256 checksums over every package file except
+    # security.json itself, keyed by package-relative path.
+    class IntegrityChecks < Lutaml::Model::Serializable
+      ALGORITHMS = %w[SHA-256].freeze
+
+      attribute :checksum_algorithm, :string, values: ALGORITHMS, default: "SHA-256"
+      attribute :checksums, :hash, default: {}
+
+      json do
+        map "checksumAlgorithm", to: :checksum_algorithm
+        map :checksums, to: :checksums
+      end
+    end
+
+    # The "digitalSignatures" object of security.json. Signing is a later
+    # phase; the model parses the canonical fields only.
+    class DigitalSignatures < Lutaml::Model::Serializable
+      attribute :public_key, :string
+      attribute :signature_file, :string
+
+      json do
+        map "publicKey", to: :public_key
+        map "signatureFile", to: :signature_file
+      end
+    end
+
+    # The "security" object of security.json.
+    class SecurityData < Lutaml::Model::Serializable
+      attribute :integrity_checks, IntegrityChecks
+      attribute :digital_signatures, DigitalSignatures
+
+      json do
+        map "integrityChecks", to: :integrity_checks
+        map "digitalSignatures", to: :digital_signatures
+      end
+    end
+
+    # Canonical security.json model (generated at pack time).
+    class SecurityConfig < Lutaml::Model::Serializable
+      attribute :security, SecurityData
+
+      json do
+        map :security, to: :security
+      end
+
+      def checksums
+        return {} unless security&.integrity_checks
+
+        security.integrity_checks.checksums
+      end
+    end
+  end
+end

data/lib/capsium/package/storage.rb

@@ -1,51 +1,51 @@
 # frozen_string_literal: true
 
-# lib/capsium/package/storage.rb
-require "json"
+require "forwardable"
 
 module Capsium
   class Package
     class Storage
-      attr_reader :datasets
+      extend Forwardable
 
-      DATA_DIR = "data"
+      attr_reader :path, :config, :datasets
+
+      def_delegators :@config, :to_json, :to_hash
 
       def initialize(path)
         @path = path
         @dir = File.dirname(path)
-        @datasets_path = File.join(@dir, DATA_DIR)
-        @datasets = load_datasets || generate_datasets
+        @config = if File.exist?(path)
+                    StorageConfig.from_json(File.read(path))
+                  else
+                    StorageConfig.new
+                  end
+        @datasets = load_datasets
       end
 
-      def load_datasets
-        return unless File.exist?(@path)
+      def data_sets
+        @config.data_sets
+      end
 
-        storage_data = JSON.parse(File.read(@path))
-        @datasets = storage_data["storage"]
+      def load_datasets
+        data_sets.map do |name, dataset_config|
+          dataset_config.to_dataset(name, @dir)
+        end
       end
 
-      def as_json
-        { datasets: datasets.map(&:as_json) }
+      def dataset(name)
+        @datasets.find { |dataset| dataset.name == name }
       end
 
-      def to_json(*_args)
-        JSON.pretty_generate(as_json)
+      def dataset_names
+        data_sets.keys.sort
       end
 
-      def save_to_file(output_path = @path)
-        File.open(output_path, "w") do |file|
-          file.write(to_json)
-        end
+      def empty?
+        data_sets.empty?
       end
 
-      def generate_datasets
-        datasets = []
-        paths = File.join(@datasets_path, "*.{yaml,yml,json,csv,tsv,sqlite,db}")
-        Dir.glob(paths).each do |file_path|
-          datasets << Dataset.new(file_path, @datasets_path)
-          # dataset_info[:table] = dataset.table_name if dataset.type == :sqlite
-        end
-        datasets
+      def save_to_file(output_path = @path)
+        File.write(output_path, to_json)
       end
     end
   end

data/lib/capsium/package/storage_config.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+require "lutaml/model"
+
+module Capsium
+  class Package
+    # A single dataset entry (ARCHITECTURE.md section 5). Paths are
+    # package-relative POSIX paths. Kinds: schema-backed file (via
+    # "source") or SQLite ("databaseFile" + "table").
+    class DatasetConfig < Lutaml::Model::Serializable
+      FORMATS = {
+        ".yaml" => "yaml", ".yml" => "yaml", ".json" => "json",
+        ".csv" => "csv", ".tsv" => "tsv",
+        ".sqlite" => "sqlite", ".db" => "sqlite"
+      }.freeze
+      SCHEMA_TYPES = %w[json-schema].freeze
+
+      attribute :source, :string
+      attribute :schema_file, :string
+      attribute :schema_type, :string, values: SCHEMA_TYPES
+      attribute :database_file, :string
+      attribute :table, :string
+
+      json do
+        map :source, to: :source
+        map "schemaFile", to: :schema_file
+        map "schemaType", to: :schema_type
+        map "databaseFile", to: :database_file
+        map :table, to: :table
+      end
+
+      def format
+        FORMATS.fetch(File.extname(backing_file).downcase) do
+          raise Error, "Unsupported data file type: #{File.extname(backing_file)}"
+        end
+      end
+
+      def sqlite?
+        !database_file.nil?
+      end
+
+      def backing_file
+        database_file || source.to_s
+      end
+
+      def to_dataset(name, package_path)
+        Dataset.new(name: name, config: self, package_path: package_path)
+      end
+    end
+
+    # The "storage" object holding the dataSets map.
+    class StorageData < Lutaml::Model::Serializable
+      attribute :data_sets, :hash, default: {}
+
+      json do
+        map "dataSets", with: { from: :data_sets_from_json, to: :data_sets_to_json }
+      end
+
+      def data_sets_from_json(model, value)
+        model.data_sets = (value || {}).to_h do |name, attributes|
+          [name, DatasetConfig.from_json(JSON.generate(attributes))]
+        end
+      end
+
+      def data_sets_to_json(model, doc)
+        doc["dataSets"] = model.data_sets.sort.to_h do |name, dataset|
+          [name, JSON.parse(dataset.to_json)]
+        end
+      end
+    end
+
+    # Canonical storage.json model. The legacy gem form
+    # ({"datasets": [{name, source, format, schema}]}) is accepted on read
+    # and normalized; writers emit only the canonical form.
+    class StorageConfig < Lutaml::Model::Serializable
+      attribute :storage, StorageData
+
+      json do
+        map :storage, to: :storage
+      end
+
+      def self.from_json(json)
+        doc = JSON.parse(json)
+        doc["storage"] ||= { "dataSets" => legacy_data_sets(doc.delete("datasets")) }
+        super(JSON.generate(doc))
+      end
+
+      def self.legacy_data_sets(datasets)
+        (datasets || []).to_h do |item|
+          entry = { "source" => item["source"] }
+          if item["schema"]
+            entry["schemaFile"] = item["schema"]
+            entry["schemaType"] = "json-schema"
+          end
+          [item["name"], entry]
+        end
+      end
+      private_class_method :legacy_data_sets
+
+      def data_sets
+        storage ? storage.data_sets : {}
+      end
+    end
+  end
+end

data/lib/capsium/package/validator.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+require "marcel"
+require "pathname"
+require "tmpdir"
+
+module Capsium
+  class Package
+    # Validates a package directory or .cap file against the canonical
+    # schemas (ARCHITECTURE.md sections 2-6) and reports one result per
+    # check. Used by `capsium package validate`.
+    class Validator
+      CheckResult = Data.define(:name, :ok, :messages) do
+        def ok?
+          ok
+        end
+      end
+
+      EXTERNAL_REFERENCE_PATTERN = %r{(?:src|href)\s*=\s*["']https?://}in
+      TEXT_CONTENT_MIME = %r{\Atext/|application/(json|javascript|xml)|image/svg\+xml}
+
+      def initialize(package_path)
+        @given_path = package_path
+      end
+
+      def run
+        Dir.mktmpdir do |dir|
+          @package_path = prepare(dir)
+          [metadata_check, manifest_check, routes_check,
+           storage_check, security_check, content_check]
+        end
+      end
+
+      def valid?
+        run.all?(&:ok?)
+      end
+
+      private
+
+      def prepare(dir)
+        return @given_path if File.directory?(@given_path)
+
+        destination = File.join(dir, "package")
+        Packager.new.unpack(@given_path, destination)
+        destination
+      end
+
+      def metadata_check
+        path = metadata_path(METADATA_FILE)
+        return failure("metadata", ["metadata.json is missing"]) unless File.exist?(path)
+
+        result("metadata", Metadata.new(path).config.format_errors)
+      rescue StandardError => e
+        failure("metadata", ["metadata.json is not valid: #{e.message}"])
+      end
+
+      def manifest_check
+        manifest = Manifest.new(metadata_path(MANIFEST_FILE))
+        missing = manifest.resources.keys.reject do |path|
+          File.file?(File.join(@package_path, path))
+        end
+        result("manifest", missing.map { |path| "resource missing on disk: #{path}" })
+      rescue StandardError => e
+        failure("manifest", ["manifest.json is not valid: #{e.message}"])
+      end
+
+      def routes_check
+        manifest = Manifest.new(metadata_path(MANIFEST_FILE))
+        storage = Storage.new(metadata_path(STORAGE_FILE))
+        routes = Routes.new(metadata_path(ROUTES_FILE), manifest, storage)
+        problems = route_problems(routes, storage) + index_problems(routes)
+        result("routes", problems)
+      rescue StandardError => e
+        failure("routes", ["routes.json is not valid: #{e.message}"])
+      end
+
+      def route_problems(routes, storage)
+        routes.config.routes.flat_map do |route|
+          route_target_problems(route, storage)
+        end
+      end
+
+      def route_target_problems(route, storage)
+        problems = []
+        if route.dataset_route? && !route.path.start_with?(Route::DATASET_PATH_PREFIX)
+          problems << "dataset route #{route.path} not under #{Route::DATASET_PATH_PREFIX}"
+        end
+        route.validate_target(@package_path, storage)
+        problems
+      rescue Error => e
+        problems + [e.message]
+      end
+
+      def index_problems(routes)
+        index = routes.config.index
+        return ["index route is missing"] if index.nil?
+        unless File.file?(File.join(@package_path, index))
+          return ["index missing on disk: #{index}"]
+        end
+        return [] if File.extname(index).downcase == ".html"
+
+        ["index is not an HTML file: #{index}"]
+      end
+
+      def storage_check
+        storage = Storage.new(metadata_path(STORAGE_FILE))
+        problems = storage.datasets.flat_map(&:validation_errors)
+        result("storage", problems)
+      rescue StandardError => e
+        failure("storage", ["storage.json is not valid: #{e.message}"])
+      end
+
+      def security_check
+        security = Security.new(metadata_path(SECURITY_FILE))
+        return result("security", []) unless security.present?
+
+        result("security", security.verify(@package_path).map(&:message))
+      end
+
+      def content_check
+        offenders = Dir.glob(File.join(@package_path, CONTENT_DIR, "**", "*")).select do |file|
+          File.file?(file) && text_file?(file) &&
+            File.binread(file).match?(EXTERNAL_REFERENCE_PATTERN)
+        end
+        result("content", offenders.map do |file|
+          "external reference in #{file.delete_prefix("#{@package_path}/")}"
+        end)
+      end
+
+      def text_file?(path)
+        mime = Marcel::MimeType.for(Pathname.new(path), name: File.basename(path))
+        mime.match?(TEXT_CONTENT_MIME)
+      end
+
+      def metadata_path(file_name)
+        File.join(@package_path, file_name)
+      end
+
+      def result(name, problems)
+        CheckResult.new(name: name, ok: problems.empty?, messages: problems)
+      end
+
+      def failure(name, messages)
+        CheckResult.new(name: name, ok: false, messages: messages)
+      end
+    end
+  end
+end