capsium 0.2.0 → 0.6.0

data/sig/capsium/package/signer.rbs

@@ -0,0 +1,66 @@
+module Capsium
+  class Package
+    # Signs and verifies Capsium packages with RSA-SHA256 digital
+    # signatures (05x-packaging "Digital Signature Using X.509",
+    # 05x-security "Digital Signatures"). The signed payload is the
+    # concatenation, in sorted package-relative path order, of the raw
+    # bytes of every file covered by the security.json integrity
+    # checksums (everything except security.json and signature.sig).
+    class Signer
+      ALGORITHM: String
+      MIN_KEY_BITS: Integer
+
+      # Package-relative name of the embedded public key PEM recorded in
+      # security.json digitalSignatures.publicKey.
+      PUBLIC_KEY_FILE: String
+
+      # Structural problems: no signature declared, missing signature or
+      # key files, unloadable keys, checksum-covered files missing.
+      class SignatureError < Capsium::Error
+      end
+
+      # A signature is declared but does not match the package contents.
+      class SignatureMismatchError < SignatureError
+      end
+
+      # Signature operations requested on an unsigned package.
+      class UnsignedPackageError < SignatureError
+      end
+
+      attr_reader package_path: String
+
+      def initialize: (String package_path) -> void
+
+      # Signs a package directory in place, or a .cap file (unpacked,
+      # signed, recompressed). Returns the signed path.
+      def self.sign_package: (String path, String private_key_path, ?String? certificate_path) -> String
+
+      # Verifies the declared signature of a package directory or .cap
+      # file (false on mismatch; raises typed SignatureError subclasses
+      # on structural problems, e.g. an unsigned package). The signer is
+      # selected from the declared digitalSignatures certificateType:
+      # OpenPGP packages verify through OpenPgpSigner.
+      def self.verify_package: (String path, ?String? public_key_path) -> bool
+
+      # The signer class matching a package's declared signature scheme:
+      # OpenPgpSigner when security.json declares
+      # digitalSignatures.certificateType "OpenPGP", Signer otherwise.
+      def self.signer_class_for: (String package_path) -> (singleton(Signer) | singleton(OpenPgpSigner))
+
+      # Signs the package directory in place: embeds the public key PEM,
+      # regenerates security.json (checksums plus digitalSignatures) and
+      # writes the raw RSA-SHA256 signature to signature.sig. Returns the
+      # path of the written signature file.
+      def sign: (String private_key_path, ?String? certificate_path) -> String
+
+      # True when the declared signature verifies against the payload;
+      # false on mismatch. Raises typed SignatureError subclasses on
+      # structural problems.
+      def verify: (?String? public_key_path) -> bool
+
+      def verify!: (?String? public_key_path) -> bool
+
+      def signed?: () -> bool
+    end
+  end
+end

data/sig/capsium/package/storage_config.rbs

@@ -1,5 +1,23 @@
 module Capsium
   class Package
+    # A single storage layer entry (ARCHITECTURE.md section 5a): a
+    # package-relative directory mirroring the content/ tree. Layers are
+    # stacked bottom -> top in declaration order; "visibility: private"
+    # layers are hidden from dependent packages.
+    class LayerConfig
+      attr_accessor path: String?
+      attr_accessor writable: bool
+      attr_accessor visibility: String
+
+      def initialize: (?path: String? path, ?writable: bool writable,
+                       ?visibility: String? visibility) -> void
+
+      def private?: () -> bool
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
     # A single dataset entry (ARCHITECTURE.md section 5): schema-backed
     # file (via "source") or SQLite ("databaseFile" + "table").
     class DatasetConfig
@@ -29,11 +47,13 @@ module Capsium
       def to_hash: () -> Hash[String, untyped]
     end
 
-    # The "storage" object holding the dataSets map.
+    # The "storage" object holding the dataSets map and the layers stack.
     class StorageData
       attr_accessor data_sets: Hash[String, DatasetConfig]
+      attr_accessor layers: Array[LayerConfig]
 
-      def initialize: (?data_sets: Hash[String, DatasetConfig] data_sets) -> void
+      def initialize: (?data_sets: Hash[String, DatasetConfig] data_sets,
+                       ?layers: Array[LayerConfig] layers) -> void
 
       def data_sets_from_json: (StorageData model, untyped value) -> void
 
@@ -54,6 +74,10 @@ module Capsium
 
       def data_sets: () -> Hash[String, DatasetConfig]
 
+      # The configured storage layers, bottom -> top (empty when the
+      # package uses the single implicit content/ layer).
+      def layers: () -> Array[LayerConfig]
+
       def to_json: (*untyped args) -> String
       def to_hash: () -> Hash[String, untyped]
     end

data/sig/capsium/package/store.rbs

@@ -0,0 +1,43 @@
+module Capsium
+  class Package
+    # A package store directory (ARCHITECTURE.md section 4a):
+    # "<name>-<version>.cap" files plus an optional index.json mapping
+    # dependency GUID -> file name. Dependencies resolve to the newest
+    # version satisfying their semver range.
+    class Store
+      INDEX_FILE: String
+      CAP_GLOB: String
+
+      # One store .cap with its identity per its metadata.json.
+      class CatalogEntry
+        def self.new: (String path, String? guid, Version version) -> void
+
+        def path: () -> String
+        def guid: () -> String?
+        def version: () -> Version
+      end
+
+      attr_reader dir: String
+
+      # The store configured via the CAPSIUM_STORE environment variable,
+      # or nil when unset.
+      def self.default: () -> Store?
+
+      def initialize: (String dir) -> void
+
+      # The newest .cap providing the dependency GUID whose version
+      # satisfies the range string. Raises DependencyNotFoundError or
+      # UnsatisfiableDependencyError when it cannot.
+      def find: (String guid, String range_string) -> String
+
+      # Every .cap in the store with its metadata identity (memoized).
+      def catalog: () -> Array[CatalogEntry]
+
+      # Installs the .cap at source_path into the store as file_name,
+      # records guid -> file_name in index.json (atomically) and returns
+      # the installed path.
+      def install: (String source_path, guid: String guid,
+                    file_name: String file_name) -> String
+    end
+  end
+end

data/sig/capsium/package/testing/config_test.rbs

@@ -0,0 +1,21 @@
+module Capsium
+  class Package
+    module Testing
+      # A "config" test (05x-testing): the configuration file must exist
+      # in the package and parse as the declared format; known Capsium
+      # package configs are additionally validated against their
+      # canonical models.
+      class ConfigTest < TestCase
+        FORMATS: Array[String]
+
+        attr_reader format: String
+        attr_reader config_file: String
+
+        def initialize: (name: String name, format: String format,
+                         config_file: String config_file) -> void
+
+        def run: (Context context) -> TestCase::Result
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/context.rbs

@@ -0,0 +1,14 @@
+module Capsium
+  class Package
+    module Testing
+      # What a test run needs: the extracted package directory and, when
+      # route tests run, the base URL of the reactor serving the package.
+      class Context
+        attr_reader package_path: String
+        attr_reader base_url: String?
+
+        def initialize: (package_path: String package_path, base_url: String? base_url) -> void
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/data_validation_test.rbs

@@ -0,0 +1,22 @@
+module Capsium
+  class Package
+    module Testing
+      # A "data_validation" test (05x-testing): the rows of the data
+      # file (format: json or yaml) must validate against the JSON
+      # schema file.
+      class DataValidationTest < TestCase
+        FORMATS: Array[String]
+
+        attr_reader format: String
+        attr_reader data_file: String
+        attr_reader schema_file: String
+
+        def initialize: (name: String name, format: String format,
+                         data_file: String data_file,
+                         schema_file: String schema_file) -> void
+
+        def run: (Context context) -> TestCase::Result
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/file_test.rbs

@@ -0,0 +1,17 @@
+module Capsium
+  class Package
+    module Testing
+      # A "file" test (05x-testing): the file must exist in the package;
+      # optionally its content must contain a string.
+      class FileTest < TestCase
+        attr_reader path: String
+        attr_reader contains: String?
+
+        def initialize: (name: String name, path: String path,
+                         ?contains: String? contains) -> void
+
+        def run: (Context context) -> TestCase::Result
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/report.rbs

@@ -0,0 +1,20 @@
+module Capsium
+  class Package
+    module Testing
+      # The outcome of a test suite run: one Result per test case.
+      class Report
+        attr_reader results: Array[TestCase::Result]
+
+        def initialize: (?Array[TestCase::Result] results) -> void
+
+        def <<: (TestCase::Result result) -> Report
+
+        def ok?: () -> bool
+
+        def failures: () -> Array[TestCase::Result]
+
+        def summary: () -> String
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/route_test.rbs

@@ -0,0 +1,22 @@
+module Capsium
+  class Package
+    module Testing
+      # A "route" test (05x-testing): requests the URL path from the
+      # reactor serving the package and checks the expected status, and
+      # optionally the content type and a response body substring.
+      class RouteTest < TestCase
+        attr_reader url: String
+        attr_reader expected_status: Integer
+        attr_reader response_contains: String?
+        attr_reader expected_content_type: String?
+
+        def initialize: (name: String name, url: String url,
+                         expected_status: Integer expected_status,
+                         ?response_contains: String? response_contains,
+                         ?expected_content_type: String? expected_content_type) -> void
+
+        def run: (Context context) -> TestCase::Result
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/test_case.rbs

@@ -0,0 +1,41 @@
+module Capsium
+  class Package
+    module Testing
+      # Base class for one test of the Capsium testing YAML DSL
+      # (05x-testing). Subclasses implement a test kind and register
+      # themselves under their DSL type name (open/closed registry).
+      class TestCase
+        # The outcome of running one test.
+        class Result
+          attr_reader name: String
+          attr_reader ok: bool
+          attr_reader messages: Array[String]
+
+          def initialize: (name: String name, ok: bool ok, messages: Array[String] messages) -> void
+
+          def ok?: () -> bool
+        end
+
+        # Raised for invalid test definitions.
+        class DefinitionError < Capsium::Error
+        end
+
+        attr_reader name: String
+
+        def initialize: (name: String name) -> void
+
+        # Runs the test against the context and returns a Result.
+        def run: (Context context) -> Result
+
+        def self.register: (String type, singleton(TestCase) klass) -> void
+
+        def self.types: () -> Hash[String, singleton(TestCase)]
+
+        # Builds a test case from a YAML definition hash (string keys).
+        def self.build: (untyped definition) -> TestCase
+
+        def self.from_h: (Hash[String, untyped] definition) -> TestCase
+      end
+    end
+  end
+end

data/sig/capsium/package/testing/test_suite.rbs

@@ -0,0 +1,20 @@
+module Capsium
+  class Package
+    module Testing
+      # Loads and runs the package's tests/*.yaml suites (05x-testing).
+      # Route tests are served by a reactor on an ephemeral port for the
+      # duration of the run.
+      class TestSuite
+        TESTS_DIR: String
+
+        attr_reader package: Capsium::Package
+
+        def initialize: (Capsium::Package package) -> void
+
+        def test_files: () -> Array[String]
+
+        def run: () -> Report
+      end
+    end
+  end
+end

data/sig/capsium/package/testing.rbs

@@ -0,0 +1,7 @@
+module Capsium
+  class Package
+    # Runner for the Capsium package testing YAML DSL (05x-testing).
+    module Testing
+    end
+  end
+end

data/sig/capsium/package/verification.rbs

@@ -0,0 +1,26 @@
+module Capsium
+  class Package
+    # Integrity and digital-signature verification of a loaded package
+    # (ARCHITECTURE.md section 6), mixed into Package.
+    module Verification
+      # Verifies the package against security.json. Returns a list of
+      # typed errors; empty when no security.json is present or all
+      # checksums match.
+      def verify_integrity: () -> Array[Security::ChecksumMismatch | Security::MissingFile | Security::UncheckedFile]
+
+      def verify_integrity!: () -> void
+
+      # Whether security.json declares a digital signature for this package.
+      def signed?: () -> bool
+
+      # Verifies the declared digital signature against the
+      # checksum-covered payload, through the signer matching the
+      # declared certificateType (OpenPgpSigner for OpenPGP, the
+      # RSA-SHA256 Signer otherwise). True when the package is unsigned
+      # or the signature verifies; false on mismatch.
+      def verify_signature: () -> bool
+
+      def verify_signature!: () -> void
+    end
+  end
+end

data/sig/capsium/package/version.rbs

@@ -0,0 +1,39 @@
+module Capsium
+  class Package
+    # A semantic version (MAJOR.MINOR.PATCH[-prerelease][+build]) with
+    # semver precedence ordering.
+    class Version
+      include Comparable
+
+      PATTERN: Regexp
+
+      attr_reader major: Integer
+      attr_reader minor: Integer
+      attr_reader patch: Integer
+      attr_reader prerelease: String?
+
+      def self.parse: (String string) -> Version
+
+      def initialize: (Integer major, Integer minor, Integer patch,
+                       ?String? prerelease) -> void
+
+      def <=>: (Version other) -> Integer
+
+      def to_s: () -> String
+    end
+
+    # A semver range for metadata.dependencies (ARCHITECTURE.md section
+    # 4a): "*", exact versions, wildcards/partials, caret, tilde,
+    # comparison operators and comma/space conjunctions.
+    class VersionRange
+      NUMERIC_PART: Regexp
+      WILDCARD_PART: Regexp
+
+      def self.parse: (String string) -> VersionRange
+
+      def initialize: (Array[[String, Version]] bounds) -> void
+
+      def satisfied_by?: (String | Version version) -> bool
+    end
+  end
+end

data/sig/capsium/package.rbs

@@ -2,11 +2,17 @@ module Capsium
   # A Capsium package loaded from a directory or a .cap file
   # (ARCHITECTURE.md section 1).
   class Package
+    include Verification
+    include Composition
+    include Preparation
+
     MANIFEST_FILE: String
     METADATA_FILE: String
     STORAGE_FILE: String
     ROUTES_FILE: String
     SECURITY_FILE: String
+    SIGNATURE_FILE: String
+    AUTHENTICATION_FILE: String
     CONTENT_DIR: String
     DATA_DIR: String
 
@@ -18,36 +24,43 @@ module Capsium
     attr_reader storage: Storage
     attr_reader security: Security
     attr_reader load_type: Symbol
+    attr_reader resolved_dependencies: Array[ResolvedDependency]
+    attr_reader authentication: Authentication
 
-    def initialize: (String | Pathname path, ?load_type: Symbol? load_type) -> void
-
-    def prepare_package: (Pathname path) -> (String | Pathname)
+    # 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`
+    # or via CAPSIUM_REGISTRY when the store has no package for a
+    # dependency GUID. `dependency_chain` is internal: the ancestor GUIDs
+    # used for circular-dependency detection during recursive resolution.
+    def initialize: (String | Pathname path, ?load_type: Symbol? load_type,
+                     ?decryption_key: String? decryption_key,
+                     ?store: (Store | String)? store,
+                     ?registry: (Capsium::Registry | String)? registry,
+                     ?dependency_chain: Array[String] dependency_chain,
+                     ?bundle: Bundle? bundle) -> void
 
     def solidify: () -> void
 
-    def decompress_cap_file: (String | Pathname file_path) -> String
-
     def load_package: () -> void
 
-    # Removes the temporary extraction directory of a .cap-loaded
-    # package; a no-op for directory loads.
+    # Removes the temporary extraction directories of the package and its
+    # resolved dependencies; a no-op for directory loads.
     def cleanup: () -> void
 
     def datasets: () -> Array[Dataset]
 
+    # 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).
+    def merged_view: (?exported_only: bool exported_only, ?extra_layers: Array[MergedView::Layer] extra_layers) -> MergedView
+
     # The .cap file this package was loaded from, or nil when loaded
     # from a directory.
     def cap_file_path: () -> String?
 
     def content_files: () -> Array[String]
-
-    def determine_load_type: (String | Pathname path) -> Symbol
-
-    # 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: () -> Array[Security::ChecksumMismatch | Security::MissingFile | Security::UncheckedFile]
-
-    def verify_integrity!: () -> void
   end
 end

data/sig/capsium/packager.rbs

@@ -18,6 +18,15 @@ module Capsium
 
     def compress_package: (Package package, String cap_file) -> void
 
+    # Unpacks a .cap into a temporary directory, yields it for read-only
+    # inspection and returns the block's value.
+    def with_unpacked_cap: (String cap_path) { (String dir) -> untyped } -> untyped
+
+    # Unpacks a .cap into a temporary directory, yields it for
+    # modification, then recompresses the result back over cap_path.
+    # Returns cap_path.
+    def transform_cap: (String cap_path) { (String dir) -> untyped } -> String
+
     def relative_path_current: (String absolute_path) -> String
   end
 end

data/sig/capsium/reactor/authenticator.rbs

@@ -0,0 +1,40 @@
+module Capsium
+  class Reactor
+    # Request authentication and route authorization for the reactor
+    # (05x-authentication, ARCHITECTURE.md section 4b).
+    class Authenticator
+      LOGIN_PATH: String
+
+      attr_reader authentication: Package::Authentication
+      attr_reader deploy: Deploy
+
+      def initialize: (Package::Authentication authentication,
+                       deploy: Deploy deploy, package_path: String package_path,
+                       ?base_url: String? base_url,
+                       ?state_file: String? state_file) -> void
+
+      def enabled?: () -> bool
+
+      # The paths this authenticator answers itself (OAuth2 login and
+      # callback), mounted by the reactor.
+      def endpoints: () -> Array[String]
+
+      def endpoint?: (String path) -> bool
+
+      def serve_endpoint: (untyped request, untyped response) -> untyped
+
+      # The identity for a request — from the session cookie or Basic
+      # credentials — or nil. An identity always carries "roles"
+      # (possibly empty).
+      def authenticate: (untyped request) -> Hash[String, untyped]?
+
+      # 401, with a Basic challenge when basicAuth is enabled.
+      def challenge: (untyped response) -> untyped
+
+      # :ok, :unauthenticated or :forbidden for a route's accessControl
+      # ({"roles": [...], "authenticationRequired": bool}).
+      def authorize: (Hash[String, untyped]? identity,
+                      Hash[String, untyped]? access_control) -> (:ok | :unauthenticated | :forbidden)
+    end
+  end
+end

data/sig/capsium/reactor/content_api.rbs

@@ -0,0 +1,19 @@
+module Capsium
+  class Reactor
+    # Content writes over the mount's overlay (ARCHITECTURE.md section
+    # 5a): PUT creates/overwrites a content file, DELETE records a
+    # tombstone. Text bodies only for v1.
+    class ContentApi
+      include Responses
+
+      WRITE_METHODS: Array[String]
+      CONTENT_PREFIX: String
+
+      def self.write_method?: (String method) -> bool
+
+      def initialize: (Mount mount) -> void
+
+      def handle: (String inner_path, untyped request, untyped response) -> untyped
+    end
+  end
+end

data/sig/capsium/reactor/data_api.rbs

@@ -0,0 +1,23 @@
+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.
+    class DataApi
+      include Responses
+
+      PREFIX: String
+      COLLECTION_PATTERN: Regexp
+      ITEM_PATTERN: Regexp
+
+      def self.path?: (String inner_path) -> bool
+
+      def initialize: (Mount mount) -> void
+
+      # The declared dataset route a data path addresses, or nil.
+      def route_for: (String inner_path) -> Package::Route?
+
+      def handle: (String inner_path, untyped request, untyped response) -> untyped
+    end
+  end
+end

data/sig/capsium/reactor/deploy.rbs

@@ -0,0 +1,34 @@
+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.
+    class Deploy
+      FILE: String
+      ENV_VAR: String
+
+      attr_reader config: Hash[String, untyped]
+
+      # Loads from an explicit path, an already-parsed Hash, or the
+      # CAPSIUM_DEPLOY environment variable; empty when unconfigured.
+      def self.load: (Hash[String, untyped] | String? source) -> Deploy
+
+      def initialize: (Hash[String, untyped] config) -> void
+
+      def authentication: () -> Hash[String, untyped]
+
+      def base_url: () -> String?
+
+      def client_secret: () -> String?
+
+      def session_secret: () -> String?
+
+      def passwd_file: () -> String?
+
+      # Role assignments keyed by identity name (basic-auth username,
+      # OAuth2 email or subject): {"alice": ["admin", "user"]}.
+      def roles: () -> Hash[String, Array[String]]
+    end
+  end
+end

data/sig/capsium/reactor/endpoints.rbs

@@ -0,0 +1,16 @@
+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: (untyped request, untyped response) -> untyped
+
+      # POST /package/<name>/save: folds base plus overlay into a new .cap.
+      def serve_package_save: (untyped request, untyped response) -> untyped
+    end
+  end
+end