capsium 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9746224c88e5a4a3b2aabe9609af2348235d6efe09dcd37fa71c710f08594829
-  data.tar.gz: fcbf1c6857f12bede912bb25d32dc83ddb84cd97757425dcf642af9e785e9478
+  metadata.gz: 188f04acf4c1f13b7a4515798e1183f59473ffba9200d375ea31b7ec2ceb705f
+  data.tar.gz: '068cb0fbbfa415b6f07bb299e233c2f27f5161fe82b932c1379883fcba79a36f'
 SHA512:
-  metadata.gz: fce42689914eda35768a2dfa4dfa74b5c00e8b760ddb50cb6b44b810a20b1423e0a31392eaefff1270408c6ed83d4b56c10a895a54f609ff71afd117b6950194
-  data.tar.gz: a45f5ea52966810c8ab183f0ec3407287eb7c87b34f82555242372d08b944edea2c372fdabe836f5e8ef0ff7ee793bed10fcc0a6ca21e486acd2466f7fbb1b93
+  metadata.gz: ed6d82167bc38448608ced953d1c906980e2fbbbc1297e1c79debe3aaf67508a9aa14237741c42be113b4daffe4e8c8d3e7a8c710f899acebeece1ce9b4dfde8
+  data.tar.gz: c1294b0ec91effddc6cf7da04cb4c128db2a31f2f82625b2a12b92c303be6bcfc566f4bf4a8c6658a187f623e8ba433cab24d275a0d880b82c3717775aec3aa5

data/.rubocop.yml

@@ -26,6 +26,18 @@ Metrics/BlockLength:
     - 'spec/**/*'
     - 'capsium.gemspec'
 
+# Spec helpers take the parameters the fixtures need.
+Metrics/ModuleLength:
+  Exclude:
+    - 'spec/**/*'
+
+# Spec helpers take the parameters the fixtures need; the reactor
+# constructor takes one keyword per deploy-time concern.
+Metrics/ParameterLists:
+  Max: 6
+  Exclude:
+    - 'spec/**/*'
+
 Metrics/ClassLength:
   Max: 120
 

data/CHANGELOG.md

@@ -1,5 +1,130 @@
 # Changelog
 
+## 0.3.0
+
+### Added
+
+- Digital signatures (RSA-SHA256, X.509) per the packaging and security
+  standard clauses: `Capsium::Package::Signer` signs a package directory in
+  place (`signature.sig` plus the embedded public key PEM, recorded as
+  `security.digitalSignatures {publicKey, signatureFile}` in
+  `security.json`) and verifies declared signatures. The signed payload is
+  the concatenation, in sorted package-relative path order, of the raw
+  bytes of every checksum-covered file (everything except `security.json`
+  and `signature.sig`) — verifiable independently with
+  `openssl dgst -sha256 -verify`.
+- Signed packages are verified automatically on load:
+  `Capsium::Package#verify_signature`/`#verify_signature!`/`#signed?`;
+  a mismatch raises `Capsium::Package::Signer::SignatureMismatchError`,
+  so the reactor refuses to serve tampered signed packages.
+- `capsium package sign PATH --key KEY.pem [--cert CERT.pem]` and
+  `capsium package verify-signature PATH [--cert CERT.pem]` (exit status 1
+  on unsigned packages and verification failures). Both accept a package
+  directory or a `.cap` file.
+- Whole-package encryption (AES-256-GCM, RSA-OAEP-SHA256 wrapped DEK) per
+  the packaging standard's encryption clause: `Capsium::Package::Cipher`
+  encrypts a package directory or `.cap` into the standard encrypted
+  layout (`metadata.json` cleartext, `signature.json` encryption envelope,
+  `package.enc` AES-256-GCM of the inner `.cap` zip) and decrypts it back.
+  The OCB/OpenPGP alternatives mentioned by the standard are intentionally
+  not implemented.
+- `capsium package encrypt PATH --public-key PUB.pem -o OUT.cap` and
+  `capsium package decrypt PATH --private-key PRIV.pem [-o OUT.cap]`.
+- `Capsium::Package.new(path, decryption_key:)` transparently decrypts an
+  encrypted `.cap` (or uncompressed encrypted directory) on load; without
+  a key it raises `Capsium::Package::Cipher::KeyRequiredError` (the
+  reactor refuses to serve), and a wrong key or tampered ciphertext raises
+  `Capsium::Package::Cipher::DecryptionError` (GCM authentication).
+- `Capsium::Packager#transform_cap`/`#with_unpacked_cap` helpers for
+  in-place `.cap` transformations.
+- The Capsium package testing YAML DSL (05x-testing): packages declare
+  tests in `tests/*.yaml` files (top-level `tests` list), and
+  `capsium package test PATH` runs them with per-test `PASS`/`FAIL`
+  output, a summary line and proper exit codes. Supported test types:
+  `route` (expected status, optional `response_contains` and
+  `expected_content_type` against a reactor started for the run),
+  `file` (existence, optional `contains`), `data_validation` (dataset
+  rows validated against a JSON schema, JSON and YAML formats) and
+  `config` (configuration files parsed and the known package configs
+  validated against their canonical models). Implemented as an
+  open/closed registry of `Capsium::Package::Testing::TestCase`
+  subclasses run by `Capsium::Package::Testing::TestSuite`; invalid
+  test definitions are reported as failures instead of aborting the run.
+- Layered storage (ARCHITECTURE.md section 5a): `storage.layers` stacks
+  overlay directories over `content/` (bottom -> top in declaration
+  order), each mirroring the `content/` tree.
+  `Capsium::Package::MergedView` — the merged-view home shared by the
+  package (validation) and the reactor (serving) — resolves content
+  top-first, honors `.capsium-tombstones` deletions (a tombstoned path
+  resolves 404 even when a lower layer holds the file, and a tombstone
+  also suppresses dependency content below it), and hides
+  `visibility: private` layers and non-exported resources in the
+  exported-only view dependents get. Packages without a `layers` config
+  behave exactly as before (single implicit `content/` layer).
+- Composite packages (ARCHITECTURE.md section 4a):
+  `metadata.dependencies` (GUID -> semver range) resolve against a
+  package store (`CAPSIUM_STORE` or `--store`) of
+  `<name>-<version>.cap` files plus an optional `index.json` (GUID ->
+  file); the newest satisfying version wins via the built-in semver
+  matcher `Capsium::Package::Version`/`VersionRange` (`>=`, `^`, `~`,
+  exact, `*`, `x`-wildcards/partials, comma/space conjunctions — no new
+  runtime dependency). Resolution is recursive with circularity
+  detection and raises typed errors:
+  `Capsium::Package::DependencyNotFoundError`,
+  `UnsatisfiableDependencyError`, `CircularDependencyError`,
+  `DependencyVisibilityError`.
+- Resolved dependencies become read-only layers below all of the
+  dependent's own layers, and only `exported` resources are visible;
+  routes may address dependency content explicitly as
+  `"<dependency-guid>/<path>"` and declare the route-inheritance
+  attributes of 05x-routing: `remap` (replaces the serving path),
+  `responseRewrite` (`body`, `headers`), `responseHeaders` (merged over
+  served headers) and `requestHeaders` (parsed and exposed for
+  forwarding reactors; a documented no-op for this static reactor).
+  Referencing a dependency's private or missing resource is a load-time
+  error. `capsium package info` prints the resolved dependency tree;
+  `capsium reactor serve` accepts `--store`.
+- Authentication (05x-authentication, ARCHITECTURE.md section 4b):
+  `authentication.json` declares `basicAuth {enabled, passwdFile,
+  realm}` and `oauth2 {enabled, provider, clientId, authorizationUrl,
+  tokenUrl, userinfoUrl, redirectPath, scopes}`; the reactor enforces
+  it via `Capsium::Reactor::Authenticator`. Basic authentication
+  challenges (401 + `WWW-Authenticate`) and verifies against the
+  htpasswd file — bcrypt via the new `bcrypt` runtime dependency, plus
+  pure-Ruby md5-crypt (`$apr1$`/`$1$` as deployed by
+  htpasswd/OpenSSL/glibc), `{SHA}` and a `crypt(3)` fallback.
+  OAuth2 runs the authorization-code flow over net/http: `/auth/login`
+  redirects with HMAC-signed state, the callback exchanges the code at
+  `tokenUrl`, fetches the userinfo claims and establishes an
+  HMAC-SHA256 signed session cookie (`Capsium::Reactor::Session`).
+  Secrets never come from the package: `clientSecret`/`sessionSecret`
+  and role assignments live in `deploy.json` (`--deploy` or
+  `CAPSIUM_DEPLOY`); without a configured session secret the reactor
+  generates one and persists it (mode 0600) outside the package.
+  Dataset-route `accessControl {roles, authenticationRequired}` is
+  enforced after authentication: 401 unauthenticated, 403 unauthorized.
+- The `content-validity` introspection entry now reports `signed` and
+  `encrypted` status, plus `signatureValid` when the package declares a
+  signature; `Capsium::Package#encrypted?` reports whether the package
+  was loaded from an encrypted source.
+
+### Changed
+
+- Integrity checksums now exclude `signature.sig` in addition to
+  `security.json` (the signature signs the checksum-covered payload, so it
+  cannot be part of it).
+- `capsium package pack` drops signing artifacts (`signature.sig`,
+  embedded public key) when repacking: signing is a post-pack step.
+- The reactor serves resources through `Package#merged_view` (the
+  overlay-aware resolution path); behavior is unchanged for packages
+  without layers.
+- Loading a package with declared `metadata.dependencies` now resolves
+  them eagerly against the package store (`store:` or `CAPSIUM_STORE`);
+  a package whose dependencies cannot resolve (including normalized
+  pre-0.2 dependency declarations) fails to load with a typed error.
+- `Metrics/ParameterLists` rubocop budget raised to 6 for the reactor
+  constructor's per-concern keywords.
+
 ## 0.2.0
 
 ### Changed

data/README.adoc

@@ -55,6 +55,7 @@ manifest.json     # auto-generated at load/pack time when absent
 routes.json       # auto-generated when absent
 storage.json      # optional (only when datasets exist)
 security.json     # generated at pack time (SHA-256 checksums)
+authentication.json # optional (user authentication)
 content/          # served content root (URL space mirrors paths below it)
 data/             # datasets (optional)
 ----
@@ -73,9 +74,15 @@ Paths inside the configuration files are package-relative POSIX paths.
   full filename); the index HTML additionally gets `/`.
 * **storage.json**: dataset definitions under `storage.dataSets`, either
   schema-backed files (`source`, `schemaFile`, `schemaType: json-schema`)
-  or SQLite (`databaseFile`, `table`).
+  or SQLite (`databaseFile`, `table`). `storage.layers` declares overlay
+  layers (see "Layered storage" below).
 * **security.json**: `security.integrityChecks.checksums` holds a SHA-256 hex
-  digest for every file in the package except `security.json` itself.
+  digest for every file in the package except `security.json` itself and
+  `signature.sig`. When the package is signed, `security.digitalSignatures`
+  records `{ "publicKey", "signatureFile" }`.
+* **authentication.json**: optional user authentication (see
+  "Authentication" below): `authentication.basicAuth` and/or
+  `authentication.oauth2`.
 
 Legacy (pre-0.2) configuration files are still accepted on read and
 normalized to the canonical forms; writers emit only the canonical forms.
@@ -151,20 +158,186 @@ Runs a per-check report and exits with status 1 on any failure:
 
 [source,bash]
 ----
-capsium package info|manifest|routes|metadata|storage path-to-package
+capsium package info|manifest|routes|metadata|storage path-to-package [--store DIR]
 ----
 
+`info` additionally prints the resolved dependency tree for composite
+packages (declared GUID and range, resolved version, store `.cap`), see
+"Composite packages" below.
+
+=== Signing a package
+
+[source,bash]
+----
+capsium package sign path-to-package-or-cap --key private.pem [--cert cert.pem]
+----
+
+Signs the package with an RSA private key (minimum 2048 bits) using
+RSA-SHA256, per the packaging standard's digital signature clause. Signing
+is a post-pack step: `pack` drops signing artifacts, so sign the packed
+directory or the `.cap` file itself.
+
+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 — i.e. every package file except `security.json` and
+`signature.sig`. The signature over that payload is stored as raw bytes in
+`signature.sig`, the signer's public key PEM is embedded as
+`signature.pub.pem`, and `security.json` records:
+
+[source,json]
+----
+{
+  "security": {
+    "digitalSignatures": {
+      "publicKey": "signature.pub.pem",
+      "signatureFile": "signature.sig"
+    }
+  }
+}
+----
+
+When `--cert` is given, the X.509 certificate must match the private key,
+and the certificate's public key is embedded instead.
+
+The payload construction is openssl-compatible; to verify a signed package
+independently, concatenate the checksum-covered files in sorted order and
+run:
+
+[source,bash]
+----
+openssl dgst -sha256 -verify signature.pub.pem -signature signature.sig payload.bin
+----
+
+=== Verifying a package signature
+
+[source,bash]
+----
+capsium package verify-signature path-to-package-or-cap [--cert cert-or-public-key.pem]
+----
+
+Verifies the declared signature against the package contents (using the
+embedded public key, or the given certificate/public key) and exits with
+status 1 when the package is unsigned or the signature does not match.
+Packages that declare a signature are also verified automatically on load —
+a mismatch raises `Capsium::Package::Signer::SignatureMismatchError`, so a
+tampered signed package cannot be served by the reactor.
+
+=== Encrypting a package
+
+[source,bash]
+----
+capsium package encrypt path-to-package-or-cap --public-key public.pem -o encrypted.cap
+----
+
+Encrypts the whole package for the recipient's RSA public key (or X.509
+certificate), per the packaging standard's encryption clause: the
+encrypted `.cap` is a zip containing `metadata.json` (cleartext, so
+name/version stay readable), `signature.json` (the encryption envelope)
+and `package.enc` — the AES-256-GCM ciphertext of the inner plaintext
+`.cap` zip (content, configuration files, data). A random 256-bit data
+encryption key (DEK) encrypts the inner zip and is wrapped with the
+recipient's public key using RSA-OAEP with SHA-256:
+
+[source,json]
+----
+{
+  "encryption": {
+    "algorithm": "AES-256-GCM",
+    "keyManagement": "RSA-OAEP-SHA256",
+    "encryptedDek": "<base64>",
+    "iv": "<base64>",
+    "authTag": "<base64>"
+  }
+}
+----
+
+The OCB/OpenPGP alternatives mentioned by the standard are intentionally
+not implemented.
+
+=== Decrypting a package
+
+[source,bash]
+----
+capsium package decrypt encrypted.cap --private-key private.pem [-o decrypted.cap]
+----
+
+Decrypts an encrypted package with the recipient's RSA private key and
+writes the plaintext `.cap` (default output: `<name>-decrypted.cap`).
+Decryption fails with a typed error when the key does not match or the
+ciphertext was tampered with (GCM authentication). Loading an encrypted
+package without a key raises `Capsium::Package::Cipher::KeyRequiredError`
+— the reactor refuses to serve it.
+
+=== Testing a package
+
+[source,bash]
+----
+capsium package test path-to-package-or-cap
+----
+
+Runs the package's test suite declared in the Capsium testing YAML DSL
+(05x-testing): all `tests/*.yaml` files in the package, each holding a
+top-level `tests` list. Every test has a `name` and a `type`; the four
+supported types:
+
+* `route` — requests the URL path from a reactor started for the run and
+  checks `expected_status`, plus optional `response_contains` (body
+  substring) and `expected_content_type`. Absolute URLs are accepted;
+  only their path (and query) is used.
+* `file` — the file at `path` must exist in the package; optional
+  `contains` checks a content substring.
+* `data_validation` — the rows of `data_file` (format `json` or `yaml`)
+  must validate against the JSON schema at `schema_file`. Array data
+  validates row by row.
+* `config` — `config_file` (format `json` or `yaml`) must exist and
+  parse; the known package configs (`metadata.json`, `manifest.json`,
+  `routes.json`, `storage.json`, `security.json`) are additionally
+  validated against their canonical models.
+
+Example:
+
+[source,yaml]
+----
+tests:
+  - name: Home Route Test
+    type: route
+    url: "/home"
+    expected_status: 200
+    response_contains: "Welcome"
+
+  - name: Config File Exists
+    type: file
+    path: "metadata.json"
+
+  - name: JSON Data Validation
+    type: data_validation
+    format: json
+    data_file: "data/animals.json"
+    schema_file: "data/animals.schema.json"
+
+  - name: Metadata Config Validation
+    type: config
+    format: json
+    config_file: "metadata.json"
+----
+
+Each test is reported as `PASS`/`FAIL` with messages; the command exits
+with status 1 when any test fails (or a test definition is invalid).
+
 == CLI: Reactor
 
 === Starting a reactor on your package
 
 [source,bash]
 ----
-capsium reactor serve my_package.cap [--port 8864]
+capsium reactor serve my_package.cap [--port 8864] [--store DIR] [--deploy deploy.json]
 ----
 
 The reactor takes a local package directory or `.cap` file; serving
-directly from a URL is not supported.
+directly from a URL is not supported. `--store` (or `CAPSIUM_STORE`)
+resolves composite-package dependencies; `--deploy` (or
+`CAPSIUM_DEPLOY`) points at the reactor-side `deploy.json` with
+authentication secrets (see "Authentication" below).
 
 === Reactor introspection API
 
@@ -189,6 +362,116 @@ content checksums — the same data `security.json` integrityChecks carry.
 `content-validity` re-verifies the package against `security.json` on
 every request and reports the outcome with a UTC `lastChecked`
 timestamp; `reason` lists the integrity errors when `valid` is false.
+The entry also reports `signed` and `encrypted` status, plus
+`signatureValid` when the package declares a signature.
+
+== Layered storage
+
+`storage.layers` stacks overlay directories over `content/` (bottom ->
+top in declaration order), each mirroring the `content/` tree:
+
+[source,json]
+----
+{ "storage": { "layers": [
+    { "path": "base",    "writable": false, "visibility": "exported" },
+    { "path": "updates", "writable": true,  "visibility": "private" }
+] } }
+----
+
+A request resolves against layers from the TOP down; the first hit
+wins. Deletions are recorded as tombstones: a `.capsium-tombstones`
+JSON file (an array of `content/`-relative paths) in a writable layer;
+a tombstoned path resolves 404 even when a lower layer holds the file,
+while a file reappearing above the tombstone is served again. Packages
+without a `layers` config behave exactly as before (single implicit
+`content/` layer). `visibility: private` layers are hidden from
+dependent packages (see below), as are resources whose manifest
+visibility is `private`.
+
+== Composite packages
+
+`metadata.dependencies` maps a dependency GUID to a semver range
+(`>=1.0.0`, `^1.2.3`, `~1.2.3`, exact, `*`, `1.x`/`1.2.x`, partials,
+and comma/space conjunctions like `>=1.0.0, <2.0.0`). Dependencies
+resolve against a *package store* — a directory of
+`<name>-<version>.cap` files plus an optional `index.json` (GUID ->
+file) — given via `CAPSIUM_STORE` or `--store`; the newest satisfying
+version wins.
+
+On load, each resolved dependency's exported content becomes read-only
+layers below all of the dependent's own layers. Routes may address
+dependency content explicitly (`"resource": "<dependency-guid>/content/app.js"`)
+or declare route-inheritance attributes per 05x-routing: `remap`
+(replaces the serving path), `responseRewrite` (`body`, `headers`),
+`responseHeaders` (merged over served headers) and `requestHeaders`
+(parsed and exposed for forwarding reactors; this reactor serves
+statically, so they do not alter its responses). Referencing a
+dependency's private or missing resource is a load-time error, as are
+circular, missing or unsatisfiable dependencies.
+
+[source,bash]
+----
+capsium package info my-composite-package --store ./store
+capsium reactor serve my-composite-package --store ./store
+----
+
+== Authentication
+
+`authentication.json` enables user authentication (05x-authentication):
+
+[source,json]
+----
+{ "authentication": {
+    "basicAuth": { "enabled": true, "passwdFile": "auth/.htpasswd", "realm": "capsium" },
+    "oauth2": { "enabled": true, "provider": "google", "clientId": "...",
+                "authorizationUrl": "...", "tokenUrl": "...", "userinfoUrl": "...",
+                "redirectPath": "/auth/callback", "scopes": ["openid", "email"] }
+} }
+----
+
+When enabled, the reactor challenges every unauthenticated request
+(`401`, with `WWW-Authenticate: Basic realm="..."` when basicAuth is
+enabled) and verifies credentials against the htpasswd file. Supported
+hashes: bcrypt (`htpasswd -B`, via the `bcrypt` gem), Apache apr1 MD5
+and md5-crypt (`$apr1$`/`$1$`, pure Ruby), unsalted SHA-1 (`{SHA}`),
+and a platform `crypt(3)` fallback for the rest.
+
+With OAuth2, `/auth/login` redirects to the provider with HMAC-signed
+state; the callback exchanges the code at `tokenUrl`, fetches the
+userinfo claims and establishes an HMAC-SHA256 signed session cookie
+(`capsium_session`, `HttpOnly; SameSite=Lax`). Provider errors during
+the exchange answer `502`; a tampered state answers `401`.
+
+Route-level `accessControl` on dataset routes is enforced after
+authentication — `401` unauthenticated, `403` when the identity lacks a
+required role:
+
+[source,json]
+----
+{ "path": "/api/v1/data/animals", "dataset": "animals",
+  "accessControl": { "roles": ["admin"], "authenticationRequired": true } }
+----
+
+Secrets NEVER come from the package. They live in `deploy.json`
+(`--deploy` or `CAPSIUM_DEPLOY`):
+
+[source,json]
+----
+{
+  "baseUrl": "http://localhost:8864",
+  "authentication": {
+    "basicAuth": { "passwdFile": "/secure/outside/package/.htpasswd" },
+    "oauth2": { "clientSecret": "..." },
+    "sessionSecret": "...",
+    "roles": { "alice": ["admin"] }
+  }
+}
+----
+
+`roles` assigns roles by identity name (basic-auth username, OAuth2
+email or subject); userinfo `roles` claims are honored too. Without a
+configured `sessionSecret`, the reactor generates one and persists it
+(mode `0600`) outside the package.
 
 == Programmatically managing packages
 
@@ -203,6 +486,11 @@ require 'capsium'
 
 # Read a package directory or a .cap file
 package = Capsium::Package.new(path)
+
+# Read an encrypted .cap (raises Capsium::Package::Cipher::KeyRequiredError
+# without a key, Capsium::Package::Cipher::DecryptionError for a wrong key
+# or tampered ciphertext)
+package = Capsium::Package.new('encrypted.cap', decryption_key: 'private.pem')
 ----
 
 When `security.json` is present, the package is verified on load and
@@ -231,6 +519,45 @@ puts animals.data.inspect
 
 # Verifying integrity (returns a list of typed errors, empty when valid)
 errors = package.verify_integrity
+
+# Digital signatures (RSA-SHA256)
+package.signed?           # => security.json declares digitalSignatures
+package.verify_signature  # => true/false
+
+signer = Capsium::Package::Signer.new(package_dir)
+signer.sign('private.pem')                    # or sign('private.pem', 'cert.pem')
+signer.verify                                 # embedded public key
+signer.verify('cert-or-public-key.pem')       # explicit key
+signer.verify!                                # raises SignatureMismatchError
+
+# Whole-package encryption (AES-256-GCM, RSA-OAEP-SHA256 wrapped DEK)
+cipher = Capsium::Package::Cipher.new
+cipher.encrypt('pkg-1.0.0.cap', 'public.pem', 'encrypted.cap')
+cipher.decrypt('encrypted.cap', 'private.pem', 'decrypted.cap')
+Capsium::Package::Cipher.encrypted?('encrypted.cap')  # => true
+
+# Running the package's tests/*.yaml suite (05x-testing DSL)
+report = Capsium::Package::Testing::TestSuite.new(package).run
+report.ok?       # => true/false
+report.failures  # => failed TestCase::Result list
+report.summary   # => "7 tests, 0 failures"
+
+# Layered storage (5a): the merged overlay view shared with the reactor
+view = package.merged_view
+view.resolve('content/app.js')   # => absolute path of the topmost hit, or nil
+
+# Composite packages (4a): resolve metadata.dependencies against a store
+package = Capsium::Package.new(dir, store: './store')  # or CAPSIUM_STORE
+package.resolved_dependencies.each do |dep|
+  puts "#{dep.guid} (#{dep.range}) => #{dep.version} [#{dep.path}]"
+end
+view = package.merged_view                # own layers over dependency layers
+view = package.merged_view(exported_only: true)  # what dependents may see
+
+# Serving with authentication and a store
+reactor = Capsium::Reactor.new(package: dir, store: './store',
+                              deploy: 'deploy.json')
+reactor.serve
 ----
 
 === Packing and unpacking programmatically

data/capsium.gemspec

@@ -33,6 +33,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 3.2.0"
 
+  spec.add_dependency "bcrypt"
   spec.add_dependency "csv"
   spec.add_dependency "json"
   spec.add_dependency "json-schema"

data/lib/capsium/cli/formatting.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Capsium
+  class Cli < Thor
+    # Output formatting helpers for CLI subcommands.
+    module Formatting
+      private
+
+      def format_result(result)
+        line = "#{result.ok? ? 'PASS' : 'FAIL'} #{result.name}"
+        return line if result.messages.empty?
+
+        "#{line}: #{result.messages.join('; ')}"
+      end
+
+      # The resolved dependency tree (ARCHITECTURE.md section 4a): one
+      # line per dependency showing the declared GUID and range, the
+      # resolved version and the store .cap it resolved to, nested.
+      def print_dependency_tree(package, indent = "")
+        package.resolved_dependencies.each do |dep|
+          puts "#{indent}- #{dep.guid} (#{dep.range}) => #{dep.version} [#{dep.path}]"
+          print_dependency_tree(dep.package, "#{indent}  ")
+        end
+      end
+    end
+  end
+end

data/lib/capsium/cli/package.rb

@@ -6,14 +6,17 @@ module Capsium
   class Cli
     class Package < Thor
       extend ThorExt::Start
+      include Formatting
 
       desc "info PACKAGE_PATH", "Display information about the package"
+      option :store, type: :string, desc: "Package store directory (default: CAPSIUM_STORE)"
 
       def info(path_to_package)
-        package = Capsium::Package.new(path_to_package)
+        package = Capsium::Package.new(path_to_package, store: options[:store])
         puts "Package Path: #{package.path}"
         puts "Routes: #{package.routes.to_hash}"
         puts "Manifest: #{package.manifest.to_hash}"
+        print_dependency_tree(package)
       end
 
       desc "manifest PATH_TO_PACKAGE",
@@ -73,13 +76,72 @@ module Capsium
         raise Thor::Error, "Package validation failed"
       end
 
-      private
+      desc "sign PACKAGE_PATH --key KEY.pem [--cert CERT.pem]",
+           "Sign the package (RSA-SHA256) and record the signature in security.json"
+      option :key, type: :string, required: true,
+                   desc: "Path to the RSA private key PEM (min 2048 bits)"
+      option :cert, type: :string,
+                    desc: "Path to the X.509 certificate PEM (must match the key)"
+
+      def sign(path_to_package)
+        Capsium::Package::Signer.sign_package(path_to_package, options[:key], options[:cert])
+        puts "Package signed: #{path_to_package}"
+      end
+
+      desc "verify-signature PACKAGE_PATH [--cert CERT.pem]",
+           "Verify the package digital signature declared in security.json"
+      option :cert, type: :string,
+                    desc: "Path to the X.509 certificate or public key PEM " \
+                          "(defaults to the key embedded in the package)"
+
+      def verify_signature(path_to_package)
+        unless Capsium::Package::Signer.verify_package(path_to_package, options[:cert])
+          raise Thor::Error, "Signature verification failed: #{path_to_package}"
+        end
+
+        puts "Signature valid: #{path_to_package}"
+      rescue Capsium::Package::Signer::SignatureError => e
+        raise Thor::Error, e.message
+      end
+
+      desc "encrypt PACKAGE_PATH --public-key PUB.pem -o OUT.cap",
+           "Encrypt a package (AES-256-GCM, RSA-OAEP-SHA256 wrapped DEK)"
+      option :public_key, type: :string, required: true,
+                          desc: "Path to the recipient RSA public key or X.509 certificate PEM"
+      option :output, type: :string, required: true, aliases: "-o",
+                      desc: "Output path for the encrypted .cap"
+
+      def encrypt(path_to_package)
+        Capsium::Package::Cipher.new.encrypt(
+          path_to_package, options[:public_key], options[:output]
+        )
+        puts "Package encrypted: #{options[:output]}"
+      end
+
+      desc "decrypt PACKAGE_PATH --private-key PRIV.pem [-o OUT.cap]",
+           "Decrypt an encrypted package"
+      option :private_key, type: :string, required: true,
+                           desc: "Path to the recipient RSA private key PEM"
+      option :output, type: :string, aliases: "-o",
+                      desc: "Output path (default: <name>-decrypted.cap)"
+
+      def decrypt(path_to_package)
+        output = options[:output] || "#{File.basename(path_to_package, '.cap')}-decrypted.cap"
+        Capsium::Package::Cipher.new.decrypt(path_to_package, options[:private_key], output)
+        puts "Package decrypted: #{output}"
+      end
 
-      def format_result(result)
-        line = "#{result.ok? ? 'PASS' : 'FAIL'} #{result.name}"
-        return line if result.messages.empty?
+      desc "test PACKAGE_PATH", "Run the package's tests/*.yaml suite (05x-testing DSL)"
 
-        "#{line}: #{result.messages.join('; ')}"
+      def test(path_to_package)
+        package = Capsium::Package.new(path_to_package)
+        report = Capsium::Package::Testing::TestSuite.new(package).run
+        report.results.each { |result| puts format_result(result) }
+        if report.results.empty?
+          puts "No tests found (#{Capsium::Package::Testing::TestSuite::TESTS_DIR}/*.yaml)"
+        end
+        puts report.summary
+        raise Thor::Error, "Package tests failed" unless report.ok?
       end
     end
   end