capsium 0.1.2 → 0.3.0

data/lib/capsium/thor_ext.rb

@@ -60,7 +60,7 @@ module Capsium
         return if error.is_a?(Errno::EPIPE)
         raise if ENV["VERBOSE"] || !config.fetch(:exit_on_failure, true)
 
-        message = error.message.to_s
+        message = +error.message.to_s
         message.prepend("[#{error.class}] ") if message.empty? || !error.is_a?(Thor::Error)
 
         config[:shell]&.say_error(message, :red)

data/lib/capsium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Capsium
-  VERSION = "0.1.2"
+  VERSION = "0.3.0"
 end

data/lib/capsium.rb

@@ -1,15 +1,13 @@
 # frozen_string_literal: true
 
-require_relative "capsium/version"
-require "shale"
-require "shale/adapter/nokogiri"
-Shale.xml_adapter = Shale::Adapter::Nokogiri
-
 module Capsium
   class Error < StandardError; end
 
-  # Your code goes here...
+  autoload :VERSION, "capsium/version"
+  autoload :Cli, "capsium/cli"
+  autoload :Converters, "capsium/converters"
+  autoload :Package, "capsium/package"
+  autoload :Packager, "capsium/packager"
+  autoload :Reactor, "capsium/reactor"
+  autoload :ThorExt, "capsium/thor_ext"
 end
-
-require_relative "capsium/package"
-require_relative "capsium/packager"

data/sig/capsium/package/authentication.rbs

@@ -0,0 +1,23 @@
+module Capsium
+  class Package
+    # Loads a package's authentication.json (ARCHITECTURE.md section 4b).
+    class Authentication
+      attr_reader path: String
+      attr_reader config: AuthenticationConfig?
+
+      def initialize: (String path) -> void
+
+      def present?: () -> bool
+
+      def basic_auth: () -> BasicAuthConfig?
+
+      def oauth2: () -> OAuth2Config?
+
+      # Whether any authentication method is enabled.
+      def enabled?: () -> bool
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/authentication_config.rbs

@@ -0,0 +1,71 @@
+module Capsium
+  class Package
+    # The "basicAuth" object of authentication.json (ARCHITECTURE.md
+    # section 4b): Apache-style Basic authentication verified against an
+    # htpasswd file.
+    class BasicAuthConfig
+      attr_accessor enabled: bool
+      attr_accessor passwd_file: String?
+      attr_accessor realm: String
+
+      def initialize: (?enabled: bool enabled, ?passwd_file: String? passwd_file,
+                       ?realm: String? realm) -> void
+
+      def enabled?: () -> bool
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The "oauth2" object of authentication.json: an OAuth2
+    # authorization-code flow. The client secret is NEVER read from the
+    # package — it comes from deploy.json or reactor configuration.
+    class OAuth2Config
+      attr_accessor enabled: bool
+      attr_accessor provider: String?
+      attr_accessor client_id: String?
+      attr_accessor authorization_url: String?
+      attr_accessor token_url: String?
+      attr_accessor userinfo_url: String?
+      attr_accessor redirect_path: String
+      attr_accessor scopes: Array[String]
+
+      def initialize: (?enabled: bool enabled, ?provider: String? provider,
+                       ?client_id: String? client_id,
+                       ?authorization_url: String? authorization_url,
+                       ?token_url: String? token_url,
+                       ?userinfo_url: String? userinfo_url,
+                       ?redirect_path: String? redirect_path,
+                       ?scopes: Array[String] scopes) -> void
+
+      def enabled?: () -> bool
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The "authentication" object of authentication.json.
+    class AuthenticationData
+      attr_accessor basic_auth: BasicAuthConfig?
+      attr_accessor oauth2: OAuth2Config?
+
+      def initialize: (?basic_auth: BasicAuthConfig? basic_auth,
+                       ?oauth2: OAuth2Config? oauth2) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical authentication.json model (ARCHITECTURE.md section 4b).
+    class AuthenticationConfig
+      attr_accessor authentication: AuthenticationData?
+
+      def initialize: (?authentication: AuthenticationData? authentication) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/cipher.rbs

@@ -0,0 +1,51 @@
+module Capsium
+  class Package
+    # Encrypts and decrypts whole Capsium packages (05x-packaging
+    # "Encryption", 05x-security "Encrypted information"). An encrypted
+    # .cap is a zip containing metadata.json (cleartext), signature.json
+    # (the encryption envelope) and package.enc (AES-256-GCM of the inner
+    # plaintext .cap zip). The random DEK is wrapped with the recipient's
+    # RSA public key using OAEP with SHA-256. OCB/OpenPGP are out of
+    # scope.
+    class Cipher
+      ALGORITHM: String
+      KEY_MANAGEMENT: String
+      CIPHER_NAME: String
+      ENCRYPTED_FILE: String
+      ENVELOPE_FILE: String
+      RSA_OPTIONS: Hash[String, String]
+
+      # Structural problems: unreadable input, missing zip entries,
+      # unsupported envelope algorithms, unloadable keys.
+      class CipherError < Capsium::Error
+      end
+
+      # An encrypted package was opened without a private key.
+      class KeyRequiredError < CipherError
+      end
+
+      # Decryption failed: wrong private key or tampered ciphertext.
+      class DecryptionError < CipherError
+      end
+
+      # Whether the path (.cap file or uncompressed directory) is an
+      # encrypted package, i.e. contains package.enc.
+      def self.encrypted?: (String | Pathname path) -> bool
+
+      # Encrypts the package at source_path (a .cap file, or a package
+      # directory which is packed first) for the recipient's RSA public
+      # key (or X.509 certificate) and writes the encrypted .cap to
+      # output_path. Returns output_path.
+      def encrypt: (String source_path, String public_key_path, String output_path) -> String
+
+      # Decrypts the encrypted package at encrypted_path (.cap file or
+      # uncompressed directory) with the recipient's RSA private key and
+      # writes the plaintext .cap to output_path. Returns output_path.
+      def decrypt: (String | Pathname encrypted_path, String private_key_path, String output_path) -> String
+
+      # Decrypts an encrypted package into a fresh temporary directory
+      # and returns the directory path.
+      def self.decrypt_to_directory: (String | Pathname source_path, String private_key_path) -> String
+    end
+  end
+end

data/sig/capsium/package/composition.rbs

@@ -0,0 +1,20 @@
+module Capsium
+  class Package
+    # Composite-package support (ARCHITECTURE.md section 4a), mixed into
+    # Package: metadata.dependencies resolution against a package store
+    # and load-time validation of dependency resource references.
+    module Composition
+      private
+
+      def resolve_dependencies: ((Store | String)? store, Array[String] chain) -> Array[ResolvedDependency]
+
+      def validate_dependency_references!: () -> void
+
+      def validate_dependency_reference: (Route route, ResolvedDependency dependency, String reference) -> void
+
+      def dependency_for: (String reference) -> ResolvedDependency?
+
+      def dependency_views: () -> Array[[String, MergedView]]
+    end
+  end
+end

data/sig/capsium/package/dataset.rbs

@@ -0,0 +1,28 @@
+module Capsium
+  class Package
+    # A loaded dataset. "source"/"schemaFile"/"databaseFile" are
+    # package-relative paths resolved against the package directory.
+    class Dataset
+      attr_reader name: String
+      attr_reader config: DatasetConfig
+      attr_reader data: untyped
+      attr_reader package_path: String
+
+      def initialize: (name: String name, config: DatasetConfig config,
+                       package_path: String package_path) -> void
+
+      def source_path: () -> String
+
+      def schema_path: () -> String?
+
+      def load_data: () -> untyped
+
+      def validate: () -> bool
+
+      # File-existence and schema validations; empty when valid.
+      def validation_errors: () -> Array[String]
+
+      def to_json: (*untyped args) -> String
+    end
+  end
+end

data/sig/capsium/package/dependency_resolver.rbs

@@ -0,0 +1,49 @@
+module Capsium
+  class Package
+    # Base error for composite-package dependency resolution
+    # (ARCHITECTURE.md section 4a).
+    class DependencyError < Capsium::Error
+    end
+
+    # No package in the store provides the dependency GUID.
+    class DependencyNotFoundError < DependencyError
+    end
+
+    # The store provides the GUID but no version satisfies the range.
+    class UnsatisfiableDependencyError < DependencyError
+    end
+
+    # A dependency cycle was detected while resolving.
+    class CircularDependencyError < DependencyError
+    end
+
+    # A dependent route references a dependency resource that is not
+    # exported (private) and therefore not visible to dependents.
+    class DependencyVisibilityError < DependencyError
+    end
+
+    # One resolved dependency: the declared GUID and range, the .cap it
+    # resolved to and the loaded package.
+    class ResolvedDependency
+      def self.new: (String guid, String range, String path, Package package) -> void
+
+      def guid: () -> String
+      def range: () -> String
+      def path: () -> String
+      def package: () -> Package
+      def version: () -> String?
+    end
+
+    # Orchestrates metadata.dependencies resolution against a package
+    # store: circularity checks plus store lookup.
+    class DependencyResolver
+      attr_reader store: Store
+
+      def initialize: (Store | String? store) -> void
+
+      # The newest store .cap satisfying the dependency, raising typed
+      # errors for circular, missing or unsatisfiable dependencies.
+      def resolve_path: (String guid, String range, chain: Array[String] chain) -> String
+    end
+  end
+end

data/sig/capsium/package/encryption_config.rbs

@@ -0,0 +1,35 @@
+module Capsium
+  class Package
+    # The "encryption" object of signature.json in an encrypted package:
+    # the AES-256-GCM envelope with the RSA-OAEP-SHA256 wrapped DEK, all
+    # binary values Base64-encoded.
+    class EncryptionEnvelope
+      attr_accessor algorithm: String?
+      attr_accessor key_management: String?
+      attr_accessor encrypted_dek: String?
+      attr_accessor iv: String?
+      attr_accessor auth_tag: String?
+
+      def initialize: (?algorithm: String? algorithm,
+                       ?key_management: String? key_management,
+                       ?encrypted_dek: String? encrypted_dek,
+                       ?iv: String? iv,
+                       ?auth_tag: String? auth_tag) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # The signature.json file of an encrypted package.
+    class EncryptionConfig
+      attr_accessor encryption: EncryptionEnvelope?
+
+      def initialize: (?encryption: EncryptionEnvelope? encryption) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/manifest.rbs

@@ -0,0 +1,34 @@
+module Capsium
+  class Package
+    # Loads, generates and writes manifest.json (ARCHITECTURE.md
+    # section 3).
+    class Manifest
+      attr_reader path: String
+      attr_reader content_path: String
+      attr_reader config: ManifestConfig
+
+      def initialize: (String path) -> void
+
+      # Auto-generation: scan content/ recursively, detect MIME types,
+      # default visibility "exported", deterministic (sorted) output.
+      def generate_manifest: () -> Hash[String, Resource]
+
+      def resources: () -> Hash[String, Resource]
+
+      def lookup: (String path) -> Resource?
+
+      def type_for: (String path) -> String?
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+
+      def save_to_file: (?String output_path) -> void
+
+      def path_to_content_file: (String path) -> Pathname
+
+      def content_file_exists?: (String path) -> bool
+
+      def relative_path: (String path) -> String
+    end
+  end
+end

data/sig/capsium/package/manifest_config.rbs

@@ -0,0 +1,38 @@
+module Capsium
+  class Package
+    # A single manifest resource entry (ARCHITECTURE.md section 3).
+    class Resource
+      VISIBILITIES: Array[String]
+
+      attr_accessor type: String?
+      attr_accessor visibility: String
+      attr_accessor version: String?
+
+      def initialize: (?type: String? type, ?visibility: String? visibility,
+                       ?version: String? version) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical manifest.json model: an object keyed by package-relative
+    # resource path. The legacy array form is normalized on read;
+    # writers emit only the object form.
+    class ManifestConfig
+      attr_accessor resources: Hash[String, Resource]
+
+      def initialize: (?resources: Hash[String, Resource] resources) -> void
+
+      def self.from_json: (String json) -> instance
+
+      def resources_from_json: (ManifestConfig model, untyped value) -> void
+
+      def resources_to_json: (ManifestConfig model, Hash[String, untyped] doc) -> void
+
+      def sort!: () -> ManifestConfig
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/merged_view.rbs

@@ -0,0 +1,46 @@
+module Capsium
+  class Package
+    # The merged (overlay) view of a package's content, per ARCHITECTURE.md
+    # section 5a. Shared by Package (validation) and Reactor (serving).
+    class MergedView
+      # A single read layer: an absolute root directory mirroring the
+      # content/ tree, plus its parsed tombstone set.
+      class Layer
+        def self.new: (String root, String visibility, Set[String] tombstones) -> void
+
+        def file?: (String content_relative_path) -> bool
+
+        def absolute: (String content_relative_path) -> String
+
+        def root: () -> String
+
+        def visibility: () -> String
+
+        def tombstones: () -> Set[String]
+      end
+
+      TOMBSTONE_FILE: String
+      CONTENT_PREFIX: String
+
+      attr_reader package_path: String
+      attr_reader layers: Array[Layer]
+      attr_reader dependency_views: Array[[String, MergedView]]
+
+      def initialize: (String package_path, storage: Storage storage,
+                       manifest: Manifest manifest,
+                       ?dependency_views: Array[[String, MergedView]] dependency_views,
+                       ?exported_only: bool exported_only) -> void
+
+      # The absolute filesystem path serving a resource reference: a
+      # package-relative content path ("content/app.js"), or a dependency
+      # reference ("<dependency-guid>/content/app.js"). nil when no layer
+      # provides the path or it is tombstoned. Non-content paths never
+      # resolve through the view.
+      def resolve: (String? reference) -> String?
+
+      # The [GUID, view] pair whose GUID prefixes the reference (longest
+      # GUID first, so nested GUIDs address the innermost dependency).
+      def dependency_pair_for: (String reference) -> [String, MergedView]?
+    end
+  end
+end

data/sig/capsium/package/metadata.rbs

@@ -0,0 +1,26 @@
+module Capsium
+  class Package
+    # Loads and writes metadata.json; field access is delegated to the
+    # wrapped MetadataData config (ARCHITECTURE.md section 2).
+    class Metadata
+      attr_reader path: String
+      attr_reader config: MetadataData
+
+      def initialize: (String path) -> void
+
+      def save_to_file: (?String output_path) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+      def name: () -> String?
+      def version: () -> String?
+      def description: () -> String?
+      def guid: () -> String?
+      def uuid: () -> String?
+      def author: () -> String?
+      def license: () -> String?
+      def repository: () -> Repository?
+      def dependencies: () -> Hash[String, String]
+    end
+  end
+end

data/sig/capsium/package/metadata_config.rbs

@@ -0,0 +1,49 @@
+module Capsium
+  class Package
+    # The repository object of metadata.json.
+    class Repository
+      attr_accessor type: String?
+      attr_accessor url: String?
+
+      def initialize: (?type: String? type, ?url: String? url) -> void
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+
+    # Canonical metadata.json model (ARCHITECTURE.md section 2). The
+    # legacy array form of "dependencies" is normalized on read; writers
+    # emit only the object form.
+    class MetadataData
+      KEBAB_CASE_PATTERN: Regexp
+      SEMVER_PATTERN: Regexp
+      UUID_PATTERN: Regexp
+
+      attr_accessor name: String?
+      attr_accessor version: String?
+      attr_accessor description: String?
+      attr_accessor guid: String?
+      attr_accessor uuid: String?
+      attr_accessor author: String?
+      attr_accessor license: String?
+      attr_accessor repository: Repository?
+      attr_accessor dependencies: Hash[String, String]
+      attr_accessor read_only: bool?
+
+      def initialize: (?name: String? name, ?version: String? version,
+                       ?description: String? description, ?guid: String? guid,
+                       ?uuid: String? uuid, ?author: String? author,
+                       ?license: String? license, ?repository: Repository? repository,
+                       ?dependencies: Hash[String, String] dependencies,
+                       ?read_only: bool? read_only) -> void
+
+      def self.from_json: (String json) -> instance
+
+      # Field-level format validations; empty when valid.
+      def format_errors: () -> Array[String]
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+    end
+  end
+end

data/sig/capsium/package/preparation.rbs

@@ -0,0 +1,23 @@
+module Capsium
+  class Package
+    # Package-source preparation (ARCHITECTURE.md section 1), mixed into
+    # Package: directory/.cap/encrypted-cap detection, extraction and
+    # decryption into a readable package directory.
+    module Preparation
+      def prepare_package: (Pathname path) -> (String | Pathname)
+
+      def decompress_cap_file: (String | Pathname file_path) -> String
+
+      # Decrypts an encrypted package (.cap file or uncompressed directory)
+      # into a temporary directory and returns its path. Raises
+      # Cipher::KeyRequiredError when no decryption_key was given.
+      def decrypt_cap_file: (String | Pathname source_path) -> String
+
+      def determine_load_type: (String | Pathname path) -> Symbol
+
+      # Whether the package was loaded from an encrypted source
+      # (ARCHITECTURE.md section 6b layout).
+      def encrypted?: () -> bool
+    end
+  end
+end

data/sig/capsium/package/routes.rbs

@@ -0,0 +1,37 @@
+module Capsium
+  class Package
+    # Loads, generates and writes routes.json (ARCHITECTURE.md
+    # section 4).
+    class Routes
+      INDEX_ROUTE: String
+      INDEX_RESOURCE: String
+      DATASET_ROUTE_PREFIX: String
+
+      attr_reader path: String
+      attr_reader config: RoutesConfig
+      attr_reader manifest: Manifest
+      attr_reader storage: Storage
+
+      def initialize: (String path, Manifest manifest, Storage storage) -> void
+
+      def resolve: (String url_path) -> Route?
+
+      def add_route: (String route, String target) -> Route
+
+      def update_route: (String route, String updated_route, String updated_target) -> Route
+
+      def remove_route: (String route) -> Array[Route]
+
+      def to_json: (*untyped args) -> String
+      def to_hash: () -> Hash[String, untyped]
+
+      def save_to_file: (?String output_path) -> void
+
+      # Auto-generation (ARCHITECTURE.md section 4): every manifest
+      # resource gets a route at its path relative to content/; HTML
+      # files get two routes; the index HTML additionally gets "/";
+      # every dataset gets /api/v1/data/<id>. Deterministic output.
+      def generate_routes: () -> RoutesConfig
+    end
+  end
+end