capsium 0.1.2 → 0.2.0

data/lib/capsium/package/metadata_config.rb

@@ -1,17 +1,105 @@
-require "shale"
+# frozen_string_literal: true
+
+require "json"
+require "lutaml/model"
+require "uri"
 
 module Capsium
   class Package
-    class Dependency < Shale::Mapper
-      attribute :name, Shale::Type::String
-      attribute :version, Shale::Type::String
+    class Repository < Lutaml::Model::Serializable
+      attribute :type, :string
+      attribute :url, :string
+
+      json do
+        map :type, to: :type
+        map :url, to: :url
+      end
     end
 
-    class MetadataData < Shale::Mapper
-      attribute :name, Shale::Type::String
-      attribute :version, Shale::Type::String
-      attribute :description, Shale::Type::String # Add description attribute
-      attribute :dependencies, Dependency, collection: true
+    # Canonical metadata.json model (ARCHITECTURE.md section 2).
+    #
+    # The legacy gem form of "dependencies" (an array of {name, version}
+    # objects) is accepted on read and normalized to the canonical object
+    # form; writers emit only the object form.
+    class MetadataData < Lutaml::Model::Serializable
+      KEBAB_CASE_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/
+      SEMVER_PATTERN = /\A\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\z/
+      UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+      attribute :name, :string
+      attribute :version, :string
+      attribute :description, :string
+      attribute :guid, :string
+      attribute :uuid, :string
+      attribute :author, :string
+      attribute :license, :string
+      attribute :repository, Repository
+      attribute :dependencies, :hash, default: {}
+      attribute :read_only, :boolean
+
+      json do
+        map :name, to: :name
+        map :version, to: :version
+        map :description, to: :description
+        map :guid, to: :guid
+        map :uuid, to: :uuid
+        map :author, to: :author
+        map :license, to: :license
+        map :repository, to: :repository
+        map :dependencies, to: :dependencies
+        map "readOnly", to: :read_only
+      end
+
+      def self.from_json(json)
+        doc = JSON.parse(json)
+        doc["dependencies"] = normalize_dependencies(doc["dependencies"])
+        super(JSON.generate(doc))
+      end
+
+      def self.normalize_dependencies(dependencies)
+        return {} if dependencies.nil?
+        return dependencies unless dependencies.is_a?(Array)
+
+        dependencies.to_h { |dep| [dep["name"], dep["version"]] }
+      end
+      private_class_method :normalize_dependencies
+
+      # Field-level format validations (ARCHITECTURE.md section 2).
+      # Returns a list of human-readable problems; empty when valid.
+      def format_errors
+        presence_errors + format_field_errors
+      end
+
+      private
+
+      def presence_errors
+        problems = []
+        problems << "name is missing" if name.to_s.empty?
+        problems << "version is missing" if version.to_s.empty?
+        problems << "description is missing" if description.to_s.empty?
+        problems << "guid is missing" if guid.to_s.empty?
+        problems << "uuid is missing" if uuid.to_s.empty?
+        problems
+      end
+
+      def format_field_errors
+        problems = []
+        problems << "name must be kebab-case" if invalid?(name, KEBAB_CASE_PATTERN)
+        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
+      end
+
+      def invalid?(value, pattern)
+        !value.nil? && !value.match?(pattern)
+      end
+
+      def uri?(value)
+        URI.parse(value).is_a?(URI::Generic)
+      rescue URI::InvalidURIError
+        false
+      end
     end
   end
 end

data/lib/capsium/package/routes.rb

@@ -1,27 +1,22 @@
 # frozen_string_literal: true
 
-# lib/capsium/package/routes.rb
-require "json"
-require "fileutils"
-require_relative "routes_config"
+require "forwardable"
 
 module Capsium
   class Package
     class Routes
       extend Forwardable
-      attr_reader :config
 
-      def_delegators :@config, :to_json
+      attr_reader :path, :config, :manifest, :storage
 
-      attr_reader :path, :config, :index, :manifest, :storage
+      def_delegators :@config, :to_hash
 
-      ROUTES_FILE = "routes.json"
-      DEFAULT_INDEX_TARGET = "content/index.html"
       INDEX_ROUTE = "/"
+      INDEX_RESOURCE = "content/index.html"
+      DATASET_ROUTE_PREFIX = "/api/v1/data/"
 
       def initialize(path, manifest, storage)
         @path = path
-        @dir = File.dirname(path)
         @manifest = manifest
         @storage = storage
         @config = if File.exist?(path)
@@ -29,8 +24,6 @@ module Capsium
                   else
                     generate_routes
                   end
-        validate_index_path(@config.resolve(INDEX_ROUTE)&.target&.file)
-        validate
       end
 
       def resolve(url_path)
@@ -38,12 +31,10 @@ module Capsium
       end
 
       def add_route(route, target)
-        validate_route_target(route, target)
         @config.add(route, target)
       end
 
       def update_route(route, updated_route, updated_target)
-        validate_route_target(updated_route, updated_target)
         @config.update(route, updated_route, updated_target)
       end
 
@@ -51,48 +42,55 @@ module Capsium
         @config.remove(route)
       end
 
-      def validate
-        @config.routes.each do |route|
-          route.target.validate(@manifest, @storage)
-        end
-      end
-
       def to_json(*_args)
-        @config.sort!.to_json
+        @config.to_json
       end
 
       def save_to_file(output_path = @path)
         File.write(output_path, to_json)
       end
 
+      # Auto-generation (ARCHITECTURE.md section 4): every manifest
+      # resource gets a route at its path relative to content/; HTML files
+      # get two routes (basename without extension and full filename); the
+      # index HTML additionally gets "/"; every dataset in storage gets
+      # /api/v1/data/<id>. Output is deterministic (sorted by path).
+      def generate_routes
+        routes = resource_routes + dataset_routes
+        RoutesConfig.new(index: index_resource, routes: routes.sort_by(&:path))
+      end
+
       private
 
-      def generate_routes
-        r = RoutesConfig.new
-        manifest.config.sort!.content.each_with_object({}) do |data_item, _hash|
-          relative_path = data_item.file.sub(/^#{Package::CONTENT_DIR}/o, "")
-          r.add(relative_path, data_item.file)
-
-          # Ensure the index route is included
-          if File.basename(relative_path, ".*") == "index"
-            r.add("/index", data_item.file)
-            r.add("/", data_item.file)
-          end
-        end
+      def index_resource
+        INDEX_RESOURCE if @manifest.resources.key?(INDEX_RESOURCE)
+      end
 
-        r
+      def resource_routes
+        @manifest.resources.keys.flat_map do |resource_path|
+          routes_for_resource(resource_path)
+        end.uniq(&:path)
       end
 
-      def validate_index_path(index_path)
-        return unless index_path
+      def routes_for_resource(resource_path)
+        url_path = resource_path.sub(%r{\A#{Package::CONTENT_DIR}/}o, "")
+        routes = [Route.new(path: "/#{url_path}", resource: resource_path)]
+        return routes unless File.extname(resource_path) == ".html"
 
-        target_path = @manifest.path_to_content_file(index_path)
-        raise "Index file does not exist: #{target_path}" unless File.exist?(target_path)
-        raise "Index file is not an HTML file: #{target_path}" unless File.extname(target_path).downcase == ".html"
+        basename = File.basename(url_path, ".html")
+        routes << Route.new(path: "/#{basename}", resource: resource_path)
+        routes << Route.new(path: INDEX_ROUTE, resource: resource_path) if index?(resource_path)
+        routes
       end
 
-      def validate_route_target(route, target)
-        # Add any necessary validation logic for the route and target
+      def index?(resource_path)
+        resource_path == INDEX_RESOURCE
+      end
+
+      def dataset_routes
+        @storage.dataset_names.map do |name|
+          Route.new(path: "#{DATASET_ROUTE_PREFIX}#{name}", dataset: name)
+        end
       end
     end
   end

data/lib/capsium/package/routes_config.rb

@@ -1,72 +1,148 @@
 # frozen_string_literal: true
 
-require "shale"
+require "json"
+require "lutaml/model"
 
 module Capsium
   class Package
-    class RouteTarget < Shale::Mapper
-      attribute :file, Shale::Type::String
-      attribute :dataset, Shale::Type::String
+    # 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/"
 
-      def fs_path(manifest)
-        return unless file
+      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
 
-        manifest.path_to_content_file(manifest.lookup(file)&.file)
+      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.lookup(file)&.mime
-      end
-
-      def validate(manifest, storage)
-        if file
-          target_path = fs_path(manifest)
-          unless target_path && File.exist?(target_path) && target_path.to_s.start_with?(manifest.content_path.to_s)
-            raise "Route target does not exist or is outside of the content directory: #{target_path}"
-          end
-        elsif dataset
-          unless storage.datasets.any? { |ds| ds.config.name == dataset }
-            raise "Dataset target does not exist: #{dataset}"
-          end
-        else
-          raise "Route target must have either a file or a dataset"
+        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
-    end
 
-    class Route < Shale::Mapper
-      attribute :path, Shale::Type::String
-      attribute :target, RouteTarget
+      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
 
-    class RoutesConfig < Shale::Mapper
-      attribute :routes, Route, collection: true
+    # 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(route)
-        routes.detect { |r| r.path == route }
+      def resolve(path)
+        routes.detect { |route| route.path == path }
       end
 
-      def add(route, target)
-        target = RouteTarget.new(file: target) if target.is_a?(String)
-        r = Route.new(path: route, target: target)
-        @routes << r
-        r
+      def add(path, target)
+        route = Route.new(path: path, resource: target)
+        self.routes = routes + [route]
+        route
       end
 
-      def update(route, updated_route, updated_target)
-        r = resolve(route)
-        r.path = updated_route
-        r.target = updated_target
-        r
+      def update(path, updated_path, updated_target)
+        route = resolve(path)
+        route.path = updated_path
+        route.resource = updated_target
+        route
       end
 
-      def remove(route)
-        r = resolve(route)
-        @routes.delete(r)
+      def remove(path)
+        self.routes = routes.reject { |route| route.path == path }
       end
 
       def sort!
-        @routes.sort_by!(&:path)
+        self.routes = routes.sort_by(&:path)
         self
       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