capsium 0.2.0 → 0.6.0

data/lib/capsium/package.rb

@@ -6,58 +6,98 @@ require "tmpdir"
 
 module Capsium
   class Package
+    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 :Bundle, "capsium/package/bundle"
     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 :OpenPgp, "capsium/package/open_pgp"
+    autoload :OpenPgpCipher, "capsium/package/open_pgp_cipher"
+    autoload :OpenPgpSigner, "capsium/package/open_pgp_signer"
+    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
+                :security, :load_type, :resolved_dependencies, :authentication
 
     MANIFEST_FILE = "manifest.json"
     METADATA_FILE = "metadata.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"
 
-    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, falling back to the registry given as `registry`
+    # (Capsium::Registry or reference) or via CAPSIUM_REGISTRY when the
+    # store has no package for a dependency GUID. Dependencies bundled
+    # under packages/ (encapsulated packages, Capsium::Package::Bundle)
+    # resolve first, without any store or registry. `dependency_chain`
+    # is internal: the ancestor GUIDs used for circular-dependency
+    # detection during recursive resolution. `bundle` is internal too:
+    # the ancestor bundle serving re-declared transitive dependencies.
+    def initialize(path, load_type: nil, decryption_key: nil, store: nil,
+                   registry: nil, dependency_chain: [], bundle: nil)
+      @decryption_key = decryption_key
       @original_path = Pathname.new(path).expand_path
       @path = prepare_package(@original_path).to_s
       @load_type = load_type || determine_load_type(path)
       create_package_structure
       load_package
       @name = metadata.name
+      @resolved_dependencies = resolve_dependencies(store, registry, dependency_chain, bundle)
+      validate_dependency_references!
       verify_integrity!
-    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 Error, "Invalid package path: #{path}"
+      verify_signature!
     end
 
     def solidify
@@ -67,13 +107,6 @@ module Capsium
       @storage.save_to_file unless @storage.empty?
     end
 
-    def decompress_cap_file(file_path)
-      package_path = File.join(Dir.mktmpdir, package_stem(file_path))
-      FileUtils.mkdir_p(package_path)
-      Packager.new.unpack(file_path, package_path)
-      package_path
-    end
-
     def load_package
       # Mandatory
       @metadata = Metadata.new(metadata_path)
@@ -83,16 +116,34 @@ module Capsium
       @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.to_s && File.directory?(@path)
-
-      FileUtils.remove_entry(@path)
+      @resolved_dependencies.each { |dependency| dependency.package.cleanup }
+      FileUtils.remove_entry(@path) if @path != @original_path.to_s && File.directory?(@path)
     end
 
-    def datasets
-      storage.datasets
+    def datasets = storage.datasets
+
+    # 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.
+    # extra_layers stack above everything (the reactor's writable overlay);
+    # views with extra layers are built fresh, not memoized.
+    def merged_view(exported_only: false, extra_layers: [])
+      unless extra_layers.empty?
+        return MergedView.new(@path, storage: @storage, manifest: @manifest,
+                                     dependency_views: dependency_views,
+                                     exported_only: exported_only,
+                                     extra_layers: extra_layers)
+      end
+
+      @merged_views ||= {}
+      @merged_views[exported_only] ||=
+        MergedView.new(@path, storage: @storage, manifest: @manifest,
+                              dependency_views: dependency_views,
+                              exported_only: exported_only)
     end
 
     # The .cap file this package was loaded from, or nil when loaded
@@ -102,55 +153,7 @@ module Capsium
     end
 
     def content_files
-      Dir.glob(File.join(content_path, "**", "*")).select do |file|
-        File.file?(file)
-      end
+      Dir.glob(File.join(content_path, "**", "*")).select { |file| File.file?(file) }
     end
-
-    def determine_load_type(path)
-      return :directory if File.directory?(path)
-      return :cap_file if File.extname(path) == ".cap"
-
-      :unsaved
-    end
-
-    # Verifies the package against security.json (ARCHITECTURE.md section
-    # 6). Returns a list of typed errors; empty when no security.json is
-    # present or all checksums match.
-    def verify_integrity
-      return [] unless @security.present?
-
-      @security.verify(@path)
-    end
-
-    def verify_integrity!
-      @security.verify!(@path) if @security.present?
-    end
-
-    private
-
-    def package_stem(file_path)
-      File.basename(file_path, ".cap")
-    end
-
-    def create_package_structure
-      FileUtils.mkdir_p(@path)
-      FileUtils.mkdir_p(content_path)
-      FileUtils.mkdir_p(data_path)
-    end
-
-    def content_path = File.join(@path, CONTENT_DIR)
-
-    def data_path = File.join(@path, DATA_DIR)
-
-    def routes_path = File.join(@path, ROUTES_FILE)
-
-    def storage_path = File.join(@path, STORAGE_FILE)
-
-    def metadata_path = File.join(@path, METADATA_FILE)
-
-    def manifest_path = File.join(@path, MANIFEST_FILE)
-
-    def security_path = File.join(@path, SECURITY_FILE)
   end
 end

data/lib/capsium/packager.rb

@@ -16,31 +16,16 @@ module Capsium
     class UnsafeEntryError < Capsium::Error; end
 
     DRIVE_LETTER_PATTERN = %r{\A[A-Za-z]:[/\\]}
+    DOT_ENTRIES = [".", ".."].freeze
 
     def pack(package, options = {})
-      directory = package.path
       output_file_name = "#{package.metadata.name}-#{package.metadata.version}.cap"
-      output_directory = File.dirname(directory)
-      cap_file_path = File.join(output_directory, output_file_name)
-
-      if File.exist?(cap_file_path) && !options[:force]
-        raise FileAlreadyExistsError,
-              "Package target already exists, aborting: `#{relative_path_current(cap_file_path)}`"
-      elsif File.exist?(cap_file_path)
-        puts "Package target already exists, overwriting: `#{relative_path_current(cap_file_path)}`"
-        FileUtils.rm_f(cap_file_path)
-      end
+      cap_file_path = File.join(File.dirname(package.path), output_file_name)
+      check_target(cap_file_path, options)
 
       Dir.mktmpdir do |dir|
-        FileUtils.cp_r("#{directory}/.", dir)
-        FileUtils.rm_f(File.join(dir, Package::SECURITY_FILE))
-        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}"
-        FileUtils.mv(new_cap_file_path, cap_file_path)
+        build_cap(package, dir, output_file_name, options)
+        FileUtils.mv(File.join(dir, output_file_name), cap_file_path)
         puts "Package created: #{relative_path_current(cap_file_path)}"
         return cap_file_path
       end
@@ -58,8 +43,9 @@ module Capsium
     end
 
     def compress_package(package, cap_file)
-      entries = Dir[File.join(package.path, "**", "**")].reject do |file|
-        File.expand_path(file) == File.expand_path(cap_file)
+      entries = Dir.glob(File.join(package.path, "**", "**"), File::FNM_DOTMATCH).reject do |file|
+        File.expand_path(file) == File.expand_path(cap_file) ||
+          DOT_ENTRIES.include?(File.basename(file))
       end
       Zip::File.open(cap_file, create: true) do |zipfile|
         entries.each do |file|
@@ -68,12 +54,93 @@ module Capsium
       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
 
+    # Guards the pack target: without :force an existing .cap aborts,
+    # with :force it is removed first.
+    def check_target(cap_file_path, options)
+      if File.exist?(cap_file_path) && !options[:force]
+        raise FileAlreadyExistsError,
+              "Package target already exists, aborting: `#{relative_path_current(cap_file_path)}`"
+      end
+      return unless File.exist?(cap_file_path)
+
+      puts "Package target already exists, overwriting: `#{relative_path_current(cap_file_path)}`"
+      FileUtils.rm_f(cap_file_path)
+    end
+
+    # Builds the .cap inside the temporary directory: copy, optional
+    # dependency bundling, solidify, security.json, compress.
+    def build_cap(package, directory, output_file_name, options)
+      FileUtils.cp_r("#{package.path}/.", directory)
+      strip_security_artifacts(directory)
+      bundle_dependencies(directory, options) if options[:bundle_deps]
+      new_package = load_packed_package(directory, options)
+      new_package.solidify
+      generate_security(new_package)
+      built_path = File.join(directory, output_file_name)
+      compress_package(new_package, built_path)
+      puts "Package built at: #{built_path}"
+    end
+
+    # Loads the copied package directory for solidification, with the
+    # pack-time store/registry available for dependency resolution.
+    def load_packed_package(directory, options)
+      Package.new(directory, store: options[:store], registry: options[:registry])
+    end
+
+    # Encapsulated packing (`pack --bundle-deps`): resolves every
+    # declared dependency through the store -> registry chain and embeds
+    # the resolved .cap files under packages/ (Capsium::Package::Bundle),
+    # so the packed package activates with no store or registry. Only
+    # the declared dependencies are bundled — the one-level policy: the
+    # parent's metadata.dependencies must list the transitive closure.
+    # Typed dependency errors (DependencyNotFoundError,
+    # UnsatisfiableDependencyError) propagate for unresolvable
+    # dependencies.
+    def bundle_dependencies(directory, options)
+      metadata = Package::Metadata.new(File.join(directory, Package::METADATA_FILE))
+      declared = metadata.dependencies
+      return if declared.empty?
+
+      resolver = Package::DependencyResolver.new(
+        options[:store] || Package::Store.default, registry: options[:registry]
+      )
+      resolutions = declared.map do |guid, range|
+        [guid, resolver.resolve_path(guid, range, chain: [metadata.guid])]
+      end
+      Package::Bundle.write(directory, resolutions)
+    end
+
     # Resolves an entry name against the destination and returns the
     # absolute target path, raising UnsafeEntryError when the entry would
     # escape the destination (zip-slip).
@@ -94,5 +161,13 @@ module Capsium
       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/content_api.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Capsium
+  class Reactor
+    # Content writes over the mount's overlay (ARCHITECTURE.md section
+    # 5a): PUT creates/overwrites a content file (creating its route on
+    # demand), DELETE records a tombstone so the path 404s even when a
+    # lower layer holds the file. The immutable package never changes
+    # on disk. Text bodies only for v1.
+    class ContentApi
+      include Responses
+
+      WRITE_METHODS = %w[PUT DELETE].freeze
+      CONTENT_PREFIX = "#{Package::CONTENT_DIR}/".freeze
+
+      def self.write_method?(method)
+        WRITE_METHODS.include?(method)
+      end
+
+      def initialize(mount)
+        @mount = mount
+      end
+
+      def handle(inner_path, request, response)
+        return read_only(response) unless @mount.writable?
+
+        route = @mount.routes.resolve(inner_path)
+        return guard_route(route, inner_path, response) if route && !writable_route?(route)
+
+        case request.request_method
+        when "PUT" then put_content(inner_path, route, request, response)
+        when "DELETE" then delete_content(inner_path, route, response)
+        else respond_method_not_allowed(response)
+        end
+      end
+
+      private
+
+      # A route is writable when it is a plain resource route (or no
+      # route at all): dataset paths are the DataApi's, handler routes
+      # are not writable, dependency content stays immutable.
+      def writable_route?(route)
+        route.kind == :resource && !route.dependency_reference?
+      end
+
+      def guard_route(route, inner_path, response)
+        return respond_method_not_allowed(response) if route.kind == :dataset
+
+        respond_error(response, 400, "cannot write #{route.kind} content: #{inner_path}")
+      end
+
+      def put_content(inner_path, route, request, response)
+        relative = content_relative(resource_path(inner_path, route))
+        return unsafe_path(inner_path, response) if relative.nil?
+
+        @mount.overlay.write_content(relative, request.body.to_s)
+        resource = "#{Package::CONTENT_DIR}/#{relative}"
+        @mount.package.routes.add_route(inner_path, resource) unless route
+        respond_json(response, 200, { path: inner_path, resource: resource })
+      rescue Overlay::Error => e
+        respond_error(response, 400, e.message)
+      end
+
+      # Tombstones the served resource: 404 when the path is already
+      # tombstoned or nothing (here or in a lower layer) serves it.
+      def delete_content(inner_path, route, response)
+        relative = content_relative(resource_path(inner_path, route))
+        return unsafe_path(inner_path, response) if relative.nil?
+        return respond_not_found(response) if @mount.overlay.tombstones.include?(relative)
+        unless @mount.merged_view.resolve("#{Package::CONTENT_DIR}/#{relative}")
+          return respond_not_found(response)
+        end
+
+        @mount.overlay.delete_content(relative)
+        response.status = 204
+      rescue Overlay::Error => e
+        respond_error(response, 400, e.message)
+      end
+
+      def unsafe_path(inner_path, response)
+        respond_error(response, 400, "unsafe content path: #{inner_path}")
+      end
+
+      def read_only(response)
+        respond_error(response, 403, "package #{@mount.package.name} is read-only")
+      end
+
+      # The package resource a write addresses: the existing route's
+      # resource (overwrite what GET serves), else a content file
+      # derived from the URL path (created on demand).
+      def resource_path(inner_path, route)
+        route ? route.resource : "#{Package::CONTENT_DIR}/#{inner_path.delete_prefix('/')}"
+      end
+
+      # The content/-relative path for a package resource, nil for
+      # unsafe paths (outside content/, dot segments).
+      def content_relative(resource_path)
+        return nil unless resource_path.start_with?(CONTENT_PREFIX)
+
+        relative = resource_path.delete_prefix(CONTENT_PREFIX)
+        segments = relative.split("/")
+        return nil if segments.empty? || segments.any? { |s| s.empty? || s == ".." }
+
+        relative
+      end
+    end
+  end
+end