capsium 0.1.2 → 0.3.0

data/sig/capsium/package/verification.rbs

@@ -0,0 +1,24 @@
+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 (RSA-SHA256) against the
+      # checksum-covered payload. 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

@@ -0,0 +1,61 @@
+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
+
+    attr_reader name: String
+    attr_reader path: String
+    attr_reader manifest: Manifest
+    attr_reader metadata: Metadata
+    attr_reader routes: Routes
+    attr_reader storage: Storage
+    attr_reader security: Security
+    attr_reader load_type: Symbol
+    attr_reader resolved_dependencies: Array[ResolvedDependency]
+    attr_reader authentication: Authentication
+
+    # 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. `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,
+                     ?dependency_chain: Array[String] dependency_chain) -> void
+
+    def solidify: () -> void
+
+    def load_package: () -> void
+
+    # 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.
+    def merged_view: (?exported_only: bool exported_only) -> 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]
+  end
+end

data/sig/capsium/packager.rbs

@@ -0,0 +1,32 @@
+module Capsium
+  # Packs a package directory into a .cap file (generating
+  # security.json) and unpacks .cap files with zip-slip protection.
+  class Packager
+    class FileAlreadyExistsError < StandardError
+    end
+
+    # Raised when a .cap archive contains an entry whose name would be
+    # written outside the destination directory (zip-slip).
+    class UnsafeEntryError < Capsium::Error
+    end
+
+    DRIVE_LETTER_PATTERN: Regexp
+
+    def pack: (Package package, ?Hash[Symbol, untyped] options) -> String
+
+    def unpack: (String cap_file_path, String destination) -> void
+
+    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/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/htpasswd.rbs

@@ -0,0 +1,36 @@
+module Capsium
+  class Reactor
+    # Apache htpasswd verification (05x-authentication). Supported hash
+    # formats: bcrypt ($2a$/$2b$/$2y$), Apache apr1 MD5 and md5-crypt
+    # ($apr1$/$1$), unsalted SHA-1 ({SHA}), and a crypt(3) fallback for
+    # the rest (platform-dependent).
+    class Htpasswd
+      # md5-crypt as deployed by Apache htpasswd, OpenSSL and glibc.
+      module Md5Crypt
+        ITOA64: String
+        DIGEST_GROUPS: Array[Array[Integer]]
+
+        def self.verify: (String hash, String password) -> bool
+
+        def self.digest: (String password, String salt, String magic) -> String
+
+        def self.initial_digest: (String password, String salt, String magic) -> String
+
+        def self.stretch_digest: (Integer iteration, String password, String salt, String final) -> String
+
+        def self.to64: (String final) -> String
+      end
+
+      attr_reader path: String
+
+      def initialize: (String path) -> void
+
+      def usernames: () -> Array[String]
+
+      def verify?: (String username, String password) -> bool
+    end
+
+    # Constant-time string comparison (length-check first).
+    def self.secure_compare: (String own, String theirs) -> bool
+  end
+end

data/sig/capsium/reactor/introspection.rbs

@@ -0,0 +1,31 @@
+module Capsium
+  class Reactor
+    # Monitoring HTTP API reports for the package this reactor serves
+    # (ARCHITECTURE.md section 7).
+    class Introspection
+      METADATA_PATH: String
+      ROUTES_PATH: String
+      CONTENT_HASHES_PATH: String
+      CONTENT_VALIDITY_PATH: String
+      PATHS: Array[String]
+
+      attr_reader package: Package
+
+      def initialize: (Package package) -> void
+
+      def endpoint?: (String path) -> bool
+
+      # The report body for an introspection endpoint, or nil when the
+      # path is not an introspection endpoint.
+      def report_for: (String path) -> Hash[Symbol, untyped]?
+
+      def metadata_report: () -> Hash[Symbol, untyped]
+
+      def routes_report: () -> Hash[Symbol, untyped]
+
+      def content_hashes_report: () -> Hash[Symbol, untyped]
+
+      def content_validity_report: () -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/capsium/reactor/oauth2.rbs

@@ -0,0 +1,31 @@
+module Capsium
+  class Reactor
+    # OAuth2 authorization-code flow client (05x-authentication), used by
+    # the Authenticator. Talks to the provider over net/http; the client
+    # secret never comes from the package.
+    class OAuth2
+      # The token exchange or userinfo fetch failed at the provider.
+      class FlowError < Capsium::Error
+      end
+
+      GRANT_TYPE: String
+
+      attr_reader config: Package::OAuth2Config
+
+      def initialize: (Package::OAuth2Config config, client_secret: String client_secret,
+                       session: Session session, ?base_url: String? base_url) -> void
+
+      # The provider URL the login endpoint redirects the browser to.
+      def authorization_url: (untyped request) -> String
+
+      def valid_state?: (String? state) -> bool
+
+      # Exchanges the authorization code and fetches the userinfo
+      # claims. Returns the raw userinfo hash; raises FlowError on
+      # provider errors.
+      def complete: (String? code, untyped request) -> Hash[String, untyped]
+
+      def callback_uri: (untyped request) -> String
+    end
+  end
+end

data/sig/capsium/reactor/serving.rbs

@@ -0,0 +1,22 @@
+module Capsium
+  class Reactor
+    # Serving of resolved routes (static files through the merged view,
+    # datasets, handler-route 501s), mixed into Reactor. Includes route
+    # inheritance processing per 05x-routing.
+    module Serving
+      private
+
+      def serve_route: (Package::Route route, untyped response) -> untyped
+
+      def serve_file: (Package::Route route, untyped response) -> untyped
+
+      def inherited_processing: (Package::Route route, String body, Hash[String, String] headers) -> [String, Hash[String, String]]
+
+      def content_type_for: (Package::Route route, String content_path) -> String
+
+      def headers_for: (Package::Route route) -> Hash[String, String]
+
+      def serve_dataset: (String dataset_name, untyped response) -> untyped
+    end
+  end
+end

data/sig/capsium/reactor/session.rbs

@@ -0,0 +1,36 @@
+module Capsium
+  class Reactor
+    # HMAC-SHA256 signed session cookies (05x-authentication). The
+    # signing secret comes from deploy.json (sessionSecret) or is
+    # generated and persisted reactor-side (never in the package).
+    class Session
+      COOKIE_NAME: String
+      SECRET_BYTES: Integer
+
+      def self.hmac: (String secret, String data) -> String
+
+      # The persisted reactor-side secret: loaded from state_file when
+      # present, generated and written (mode 0600) otherwise.
+      def self.load_or_generate_secret: (String? state_file) -> String
+
+      attr_reader secret: String
+
+      def initialize: (?secret: String? secret, ?state_file: String? state_file) -> void
+
+      # HMAC-SHA256 of data with the session secret (hex).
+      def sign: (String data) -> String
+
+      def encode: (Hash[String, untyped] payload) -> String
+
+      # The verified payload, or nil when the cookie is missing or the
+      # signature does not match.
+      def decode: (String? cookie_value) -> Hash[String, untyped]?
+
+      # The identity for a request's Cookie header, or nil.
+      def identity_from: (untyped request) -> Hash[String, untyped]?
+
+      # A Set-Cookie value establishing the identity session.
+      def cookie_for: (Hash[String, untyped] identity) -> String
+    end
+  end
+end

data/sig/capsium/reactor.rbs

@@ -0,0 +1,35 @@
+module Capsium
+  # Rack-free WEBrick reactor: serves the package routes plus the
+  # Monitoring HTTP API (ARCHITECTURE.md section 7) and reloads the
+  # package on filesystem changes.
+  class Reactor
+    include Serving
+
+    DEFAULT_PORT: Integer
+    DEFAULT_CACHE_CONTROL: String
+
+    attr_reader package: Package
+    attr_reader package_path: String
+    attr_reader routes: Package::Routes
+    attr_reader port: Integer
+    attr_reader cache_control: String?
+    attr_reader server: untyped
+    attr_reader server_thread: Thread?
+    attr_reader introspection: Introspection
+    attr_reader authenticator: Authenticator
+
+    def initialize: (package: Package | String package, ?port: Integer port,
+                     ?cache_control: String? cache_control,
+                     ?do_not_listen: bool do_not_listen,
+                     ?store: (Package::Store | String)? store,
+                     ?deploy: (Hash[String, untyped] | String)? deploy) -> void
+
+    def serve: () -> untyped
+
+    def handle_request: (untyped request, untyped response) -> untyped
+
+    def mount_routes: () -> void
+
+    def restart_server: () -> Thread
+  end
+end

data/sig/capsium.rbs

@@ -1,4 +1,6 @@
 module Capsium
+  class Error < StandardError
+  end
+
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
 end