capsium 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 188f04acf4c1f13b7a4515798e1183f59473ffba9200d375ea31b7ec2ceb705f
-  data.tar.gz: '068cb0fbbfa415b6f07bb299e233c2f27f5161fe82b932c1379883fcba79a36f'
+  metadata.gz: 4d5f0f655cb66b0e6b49edcb70ad68b8e6670e0ca2cb0d5a77aef84c609a3c6b
+  data.tar.gz: 3f4f17221db2c72db65c14faa2b5e3a31cf026e5c5b1e0ffc331af872b8b0111
 SHA512:
-  metadata.gz: ed6d82167bc38448608ced953d1c906980e2fbbbc1297e1c79debe3aaf67508a9aa14237741c42be113b4daffe4e8c8d3e7a8c710f899acebeece1ce9b4dfde8
-  data.tar.gz: c1294b0ec91effddc6cf7da04cb4c128db2a31f2f82625b2a12b92c303be6bcfc566f4bf4a8c6658a187f623e8ba433cab24d275a0d880b82c3717775aec3aa5
+  metadata.gz: 4e3b9777dc6f0c498784959ab66cb89228657b6f8e85a43818c804c311371d86f78d9ffd3cf7f61e1ad743db08608fafdbe35d49d3936073f8d8281d66cd9816
+  data.tar.gz: 7cfb11cce09e70b03f94057c68adea6389022f50aa5b9573311f0cf0a8d606013bf60115e4f11bfb45a07460fd3dd5f22e93b34ef5dcb84cb052bc25c93cc6bb

data/.rubocop.yml

@@ -32,14 +32,18 @@ Metrics/ModuleLength:
     - 'spec/**/*'
 
 # Spec helpers take the parameters the fixtures need; the reactor
-# constructor takes one keyword per deploy-time concern.
+# constructor takes one keyword per deploy-time concern (keyword args
+# are self-documenting and not counted).
 Metrics/ParameterLists:
-  Max: 6
+  Max: 7
+  CountKeywordArgs: false
   Exclude:
     - 'spec/**/*'
 
 Metrics/ClassLength:
-  Max: 120
+  # The reactor (request dispatch + lifecycle) and the introspection
+  # endpoint set grew with the phase-3 follow-ons.
+  Max: 150
 
 Metrics/MethodLength:
   Max: 25

data/CHANGELOG.md

@@ -1,5 +1,202 @@
 # Changelog
 
+## 0.6.0
+
+### Added
+
+- OpenPGP signatures and encryption through librnp (new `rnp` gem
+  dependency, loaded lazily — a typed
+  `Capsium::Package::OpenPgp::OpenPgpUnavailableError` with
+  installation guidance is raised when the gem or librnp is missing):
+  - `Capsium::Package::OpenPgpSigner` (parallel to the RSA-SHA256/X.509
+    `Signer`, same construction semantics and `Signer::SignatureError`
+    taxonomy): `capsium package sign PATH --openpgp --key SEC.asc`
+    writes an armored detached OpenPGP signature (SHA-256) over the
+    canonical section-6a payload to `signature.sig`, embeds the armored
+    public key as `signature.pub.asc` and records
+    `"digitalSignatures": {"certificateType": "OpenPGP", ...}` in
+    security.json. Verification auto-detects the scheme from
+    `certificateType` (`Signer.verify_package`,
+    `Package#verify_signature`, the load-time signature gate and
+    `capsium package verify-signature` all dispatch); `--openpgp
+    --cert PUB.asc` verifies with an explicit OpenPGP public key.
+  - `Capsium::Package::OpenPgpCipher < Cipher` (same encrypted .cap
+    layout and AES-256-GCM content encryption): `capsium package
+    encrypt PATH --openpgp --recipient PUB.asc -o OUT.cap` protects the
+    DEK as an armored OpenPGP message
+    (`signature.json`: `{"encryption": {"algorithm": "AES-256-GCM",
+    "keyManagement": "OpenPGP", "message", "iv", "authTag"}}`).
+    Decryption auto-detects the key management from the envelope
+    (`Cipher.for_encrypted`, `Cipher.key_management`), and
+    `Package.new(decryption_key:)` accepts OpenPGP secret keys
+    (armored or binary) transparently. `Cipher`'s envelope/DEK handling
+    was refactored into subclass seams; the RSA-OAEP-SHA256 path is
+    unchanged.
+  - `Capsium::Package::OpenPgp` is the single lazy loader of the rnp
+    binding and the key-file loader (armor/format auto-detection,
+    `OpenPgp::KeyError` for unreadable or unsuitable keys).
+  - The OpenPGP specs skip cleanly when librnp cannot load, so CI
+    without librnp stays green; see README "OpenPGP support (librnp)".
+- Encapsulated packages (bundled dependencies): `capsium package pack
+  --bundle-deps` (alias `--bundle`; `Packager#pack` option
+  `bundle_deps: true`) resolves every declared `metadata.dependencies`
+  entry through the store -> registry chain and embeds the resolved
+  `.cap` files inside the parent under `packages/`, producing a fully
+  self-contained package that activates with no store or registry. The
+  `packages/index.json` manifest maps each dependency GUID to its
+  embedded file, resolved version and SHA-256
+  (`Capsium::Package::Bundle`). Loading resolves bundled dependencies
+  FIRST — including from inside a parent `.cap` — before the store ->
+  registry chain, and passes the bundle down so re-declared transitive
+  dependencies resolve from it (one-level bundling policy: the parent's
+  `metadata.dependencies` must list the transitive closure). The
+  manifest SHA-256 is re-verified at resolution
+  (`Security::IntegrityError` on mismatch) and each bundled package's
+  own `security.json`/signature is verified at activation. `pack`
+  gained `--store`/`--registry` options; `capsium package validate`
+  resolves bundled dependency layers, so fallthrough routes of
+  encapsulated packages validate.
+
+## 0.5.0
+
+### Added
+
+- Multiple mounted packages per reactor: `capsium reactor serve`
+  accepts multiple sources — positional arguments, repeatable
+  `--mount PATH=SOURCE` options and/or a JSON mount config
+  (`--config FILE`: `{"mounts": [{"path", "source", "store"?}]}`).
+  Default mount points: the first source at `/`, each additional one at
+  `/<metadata.name>/`; duplicate prefixes raise
+  `Capsium::Reactor::MountConflictError`. Requests dispatch by
+  longest-prefix mount matching (`Capsium::Reactor::Mount`); the
+  `/api/v1/introspect/*` endpoints aggregate ALL mounted packages,
+  `/package/<name>/{status,metadata,logs}` resolve by package name
+  (404 for unknown names), metrics/logs stay reactor-global, and
+  `Capsium::Reactor#cleanup` cleans up every mounted package.
+  Single-source invocation is unchanged.
+- Writable packages (ARCHITECTURE.md section 5a): a mounted package
+  whose metadata does not declare `"readOnly": true` gets an
+  append-only overlay layer in the reactor workdir (`--workdir DIR`,
+  default a temporary directory removed on cleanup), always the
+  topmost layer of the merged view (`MergedView` gained
+  `extra_layers`). The immutable base never changes on disk and every
+  write is visible on the next request (hot-swap); overlay state
+  (content files, `.capsium-tombstones`, per-dataset JSON operation
+  logs) persists in the workdir.
+- REST CRUD over datasets (`Capsium::Reactor::DataApi`):
+  `POST /api/v1/data/<dataset>` appends an item (201 + Location +
+  stored item; id convention is the `id` field else the 1-based index
+  as a string), `GET /<id>` reads one item, `PUT /<id>` replaces and
+  `DELETE /<id>` deletes. Statuses: 400 for malformed JSON, 403 with a
+  clear body on read-only packages, 404 for unknown datasets/items,
+  405 for wrong verbs, 409 for duplicate/mismatched ids, 422 with the
+  schema errors when the candidate document violates the dataset's
+  JSON schema, 501 for SQLite datasets. Undeclared datasets are not
+  served and route-level `accessControl` still applies.
+- Content writes (`Capsium::Reactor::ContentApi`): `PUT <route>`
+  creates/overwrites a content file (creating its route on demand;
+  text bodies only for v1) and `DELETE <route>` records a tombstone so
+  the path 404s even when a lower layer holds the file (404 when
+  nothing to delete).
+- GraphQL (new `graphql` dependency): every mounted package with
+  datasets answers `<mount>/graphql` (POST, or GET with `?query=`)
+  with a schema auto-derived from the package's storage
+  (`Capsium::Reactor::GraphqlSchema`): a query field `<dataset>`
+  (list) with an optional `id:` argument (single item) plus
+  `create<Dataset>`/`update<Dataset>`/`delete<Dataset>` mutations
+  matching the REST semantics including schema validation. Item types
+  are inferred from the dataset's JSON schema when present, else map
+  to a permissive JSON scalar; SQLite datasets are skipped. Not-found
+  items, schema violations, duplicates and read-only mutations land in
+  the `errors` array (no 500s on user error).
+- Save composite: `POST /package/<name>/save`
+  (`Capsium::Reactor::PackageSaver`) folds the base package plus its
+  overlay into a NEW versioned `.cap` (`<name>-<version+patch>.cap`)
+  in the workdir — overlay content files replace, tombstones delete,
+  dataset mutation logs replay into the dataset files, and manifest,
+  routes and security.json are regenerated — returning the `.cap`
+  path and its SHA-256. The saved package passes
+  `capsium package validate`. Read-only packages get 403, unknown
+  names 404, non-POST 405.
+
+### Changed
+
+- `Capsium::Reactor::Introspection.new` now takes the list of served
+  packages (aggregation); `/introspect/status` `packagesLoaded`
+  reflects the mount count.
+- The reactor dispatch, endpoint and response handling are split into
+  `Capsium::Reactor::Serving` (mount request serving),
+  `Capsium::Reactor::Endpoints` (reactor-level endpoints) and
+  `Capsium::Reactor::Responses` (HTTP response writers).
+- WEBrick's `ProcHandler` (GET/POST/PUT only) is extended with
+  `do_DELETE`/`do_PATCH` aliases so the writable-package REST verbs
+  reach the mounted procs.
+- `Metrics/ParameterLists` rubocop no longer counts keyword args (the
+  reactor constructor takes one keyword per deploy-time concern).
+
+## 0.4.0
+
+### Added
+
+- Static registries (ARCHITECTURE.md section 4a follow-on): a registry
+  is a directory or a static https base URL holding an `index.json`
+  (`packages` -> GUID -> `name` + `versions` -> version -> `file`,
+  `sha256`, `size`) with `.cap` files stored relative to the registry
+  root, so any static host (GitHub Pages, S3, nginx) can serve one.
+  `Capsium::Registry.fetch(ref)` returns `Registry::Local` (read-write
+  directory) or `Registry::Remote` (read-only https base URL over
+  net/http with redirect following and timeouts; plain http for
+  loopback hosts only). `Registry#resolve` picks the newest version
+  satisfying a semver constraint via the built-in
+  `Version`/`VersionRange` matcher.
+- `Registry::Local#push`: validates the `.cap` with
+  `Capsium::Package::Validator` (`Registry::InvalidPackageError` on
+  failure), copies it into the registry directory and atomically
+  rewrites `index.json` (tmp + rename) with recomputed sha256 and size.
+- `Registry#install`: fetches the resolved `.cap`, verifies it against
+  the sha256 declared in the index (`Registry::ChecksumMismatchError`
+  on mismatch) and installs it into the package store as
+  `<name>-<version>.cap`, atomically updating the store's own
+  `index.json` (`Package::Store#install`). All registry failures are
+  typed `Registry::RegistryError` subclasses
+  (`RegistryNotConfiguredError`, `InvalidRegistryError`,
+  `InvalidPackageError`, `PackageNotFoundError`,
+  `UnsatisfiableConstraintError`, `ChecksumMismatchError`,
+  `FetchError`).
+- `capsium package push PACKAGE --registry DIR` and
+  `capsium install GUID [--constraint RANGE] [--registry DIR_OR_URL]
+  [--store DIR]`; the registry defaults to `CAPSIUM_REGISTRY`, the
+  store to `CAPSIUM_STORE` (typed errors when unconfigured).
+- `capsium reactor serve capsium://GUID` (install-then-serve with
+  `--registry`/`--store`/`--constraint`), and dependency-resolution
+  fallback for composite packages: `Package::DependencyResolver` (and
+  `Capsium::Package.new`/`Capsium::Reactor.new` through their new
+  `registry:` keyword) installs a dependency from the configured
+  registry when the store has no package for its GUID — fallback chain
+  store -> registry -> typed error (`DependencyNotFoundError` /
+  `UnsatisfiableDependencyError`).
+- Reactor-level and per-package introspection endpoints (ARCHITECTURE.md
+  section 7 follow-ons), extending `Capsium::Reactor::Introspection`:
+  `GET /introspect/status` (`{status, uptime, packagesLoaded}`),
+  `GET /introspect/config` (port, store dir, cacheControl, authEnabled,
+  registry — deploy.json values and registry URL credentials are never
+  exposed) and `GET /introspect/metrics`
+  (`{uptime, requestsTotal, requestsByStatus}`) backed by the new
+  thread-safe in-memory `Capsium::Reactor::Metrics` counter wired into
+  the serving path, plus `GET /package/<name>/status`,
+  `GET /package/<name>/metadata` and `GET /package/<name>/logs` (the
+  reactor serves one package; any other name is a 404). `logs` returns
+  the last N lines (`?lines=N`, default 100) from the new
+  `Capsium::LogBuffer`, a small thread-safe ring buffer recording key
+  serving events (reactor start, package reload, one line per served
+  request). All endpoints are GET-only JSON (405 otherwise) and gated
+  when `authentication.json` enables authentication.
+
+### Changed
+
+- `Metrics/ClassLength` rubocop budget raised to 150 for the reactor
+  and introspection classes grown by the phase-3 endpoints.
+
 ## 0.3.0
 
 ### Added

data/README.adoc

@@ -42,6 +42,23 @@ Alternatively, you can install the gem directly using:
 gem install capsium
 ----
 
+=== OpenPGP support (librnp)
+
+OpenPGP signatures and encryption are provided through the `rnp` gem
+(a declared dependency) bound to the *librnp* shared library, which
+must be installed separately:
+
+[source,bash]
+----
+brew install rnp    # homebrew-core formula, provides librnp
+# or build librnp from source: https://github.com/rnpgp/rnp
+----
+
+The binding is loaded lazily, only when an OpenPGP feature is used, so
+the gem works without librnp until then; OpenPGP commands raise a
+typed `Capsium::Package::OpenPgp::OpenPgpUnavailableError` with
+installation guidance when the library is missing.
+
 == What is a Capsium package?
 
 A Capsium package is a structured collection of content, data, metadata, and
@@ -105,7 +122,7 @@ Capsium provides a CLI to help you pack and manage your packages.
 
 [source,bash]
 ----
-capsium package pack [--force/-f] path-to-package
+capsium package pack [--force/-f] [--bundle-deps/--bundle] [--store DIR] [--registry REF] path-to-package
 ----
 
 This command generates `manifest.json`/`routes.json` when absent, writes
@@ -113,6 +130,15 @@ This command generates `manifest.json`/`routes.json` when absent, writes
 directory into `{package-name}-{package-version}.cap` (name and version from
 `metadata.json`).
 
+With `--bundle-deps` (alias `--bundle`) a package that declares
+`metadata.dependencies` is packed as an *encapsulated* package: every
+declared dependency is resolved through the store -> registry chain
+(`--store`/`CAPSIUM_STORE`, `--registry`/`CAPSIUM_REGISTRY`) and embedded
+under `packages/`, so the resulting `.cap` activates with no store or
+registry at all (see <<_encapsulated_packages_bundled_dependencies>>).
+A declared dependency that cannot be resolved aborts the pack with a
+typed dependency error.
+
 .Sample `pack` command
 ====
 [source,bash]
@@ -208,16 +234,45 @@ run:
 openssl dgst -sha256 -verify signature.pub.pem -signature signature.sig payload.bin
 ----
 
+==== OpenPGP signatures
+
+[source,bash]
+----
+capsium package sign path-to-package-or-cap --openpgp --key secret.asc
+----
+
+With `--openpgp`, `--key` is an OpenPGP secret key file (armored or
+binary, auto-detected) and the package is signed through librnp with the
+same canonical payload: `signature.sig` holds the armored detached
+OpenPGP signature (SHA-256), the armored public key is embedded as
+`signature.pub.asc`, and `security.json` records the scheme:
+
+[source,json]
+----
+{
+  "security": {
+    "digitalSignatures": {
+      "certificateType": "OpenPGP",
+      "publicKey": "signature.pub.asc",
+      "signatureFile": "signature.sig"
+    }
+  }
+}
+----
+
 === Verifying a package signature
 
 [source,bash]
 ----
-capsium package verify-signature path-to-package-or-cap [--cert cert-or-public-key.pem]
+capsium package verify-signature path-to-package-or-cap [--cert cert-or-public-key] [--openpgp]
 ----
 
 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.
+The signature scheme is auto-detected from the declared
+`certificateType` (RSA-SHA256/X.509 by default, OpenPGP when recorded);
+`--openpgp` forces OpenPGP verification with an OpenPGP public key.
 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.
@@ -251,22 +306,50 @@ recipient's public key using RSA-OAEP with SHA-256:
 }
 ----
 
-The OCB/OpenPGP alternatives mentioned by the standard are intentionally
-not implemented.
+==== OpenPGP encryption
+
+[source,bash]
+----
+capsium package encrypt path-to-package-or-cap --openpgp --recipient public.asc -o encrypted.cap
+----
+
+With `--openpgp`, the DEK is protected as an armored OpenPGP message to
+the recipient's public key (through librnp) instead of the RSA-OAEP
+wrap; the content encryption and layout are identical, and the
+envelope records the key management:
+
+[source,json]
+----
+{
+  "encryption": {
+    "algorithm": "AES-256-GCM",
+    "keyManagement": "OpenPGP",
+    "message": "<armored OpenPGP message containing the DEK>",
+    "iv": "<base64>",
+    "authTag": "<base64>"
+  }
+}
+----
+
+The OCB alternative mentioned by the standard remains out of scope.
 
 === Decrypting a package
 
 [source,bash]
 ----
-capsium package decrypt encrypted.cap --private-key private.pem [-o decrypted.cap]
+capsium package decrypt encrypted.cap [--private-key private.pem | --key secret.asc] [--openpgp] [-o decrypted.cap]
 ----
 
-Decrypts an encrypted package with the recipient's RSA private key and
+Decrypts an encrypted package with the recipient's 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.
+The key management is auto-detected from the envelope — `--private-key`
+for RSA-OAEP, `--key` for an OpenPGP secret key (armored or binary);
+`--openpgp` forces the OpenPGP cipher. 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. `Capsium::Package.new(path, decryption_key:)` accepts either
+key format transparently.
 
 === Testing a package
 
@@ -330,14 +413,97 @@ with status 1 when any test fails (or a test definition is invalid).
 
 [source,bash]
 ----
-capsium reactor serve my_package.cap [--port 8864] [--store DIR] [--deploy deploy.json]
+capsium reactor serve my_package.cap [--port 8864] [--store DIR] [--deploy deploy.json] [--workdir DIR]
+capsium reactor serve capsium://example.com/story [--registry DIR_OR_URL] [--store DIR] [--constraint ">=1.0"]
 ----
 
-The reactor takes a local package directory or `.cap` file; serving
-directly from a URL is not supported. `--store` (or `CAPSIUM_STORE`)
+The reactor takes a local package directory or `.cap` file, or a
+`capsium://` GUID which is installed from a registry first (see
+"Static registries" below). `--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).
+authentication secrets (see "Authentication" below); `--registry`
+(or `CAPSIUM_REGISTRY`) supplies the registry for `capsium://` GUIDs
+and for dependency fallback; `--workdir` holds the writable overlays
+and saved packages (default: a temporary directory — see "Writable
+packages" below).
+
+=== Serving multiple packages
+
+`capsium reactor serve` accepts multiple sources at once: positional
+arguments, repeatable `--mount PATH=SOURCE` options, a JSON mount
+config via `--config`, or any combination:
+
+[source,bash]
+----
+capsium reactor serve first.cap second.cap
+capsium reactor serve --mount /=first.cap --mount /api=second.cap
+capsium reactor serve --config mounts.json   # {"mounts": [{"path": "/", "source": "first.cap", "store": "..."}]}
+----
+
+Default mount points: the first source mounts at `/`, each additional
+source at `/<metadata.name>/`. Requests dispatch to mounts by
+longest-prefix matching, and every package's routes answer below its
+prefix (a package mounted at `/api` serves its `/index.html` route at
+`/api/index.html`). Two mounts claiming the same prefix fail with a
+`MountConflictError`. The introspection endpoints aggregate ALL
+mounted packages, `/package/<name>/...` resolves by name (404 for
+unknown names), and metrics/logs stay reactor-global. On shutdown the
+reactor cleans up every mounted package.
+
+=== Writable packages
+
+A mounted package whose metadata does not declare `"readOnly": true`
+is writable: the reactor keeps an append-only overlay layer for it in
+the workdir (`--workdir DIR`, default a temporary directory) which is
+always the topmost layer of the merged view (ARCHITECTURE.md section
+5a). The immutable `.cap` never changes on disk, and every write is
+visible on the next request (hot-swap — no restart needed). Overlay
+state persists in the workdir, so a later reactor over the same
+workdir sees it again.
+
+Dataset CRUD (JSON) under the dataset's route:
+
+[source]
+----
+POST   /api/v1/data/<dataset>          # append an item => 201 + Location + stored item
+GET    /api/v1/data/<dataset>/<id>     # one item => 200 (404 when absent)
+PUT    /api/v1/data/<dataset>/<id>     # replace an item => 200 (404 absent, 422 schema fail)
+DELETE /api/v1/data/<dataset>/<id>     # delete an item => 204 (404 absent)
+GET    /api/v1/data/<dataset>          # the merged collection (as before)
+----
+
+Item ids follow the `id` field when present, else the 1-based index as
+a string; a duplicate `id` on POST (or a mismatched one on PUT) is a
+`409`. The request body must satisfy the dataset's JSON schema when
+one is declared (violations are `422` with the schema errors);
+malformed JSON is `400`. Writes on a `"readOnly": true` package are
+`403` with a clear body; writes on a SQLite dataset are `501`;
+wrong verbs are `405`. Mutations persist as a per-dataset JSON
+operation log in the overlay.
+
+Content writes work on any route path (text bodies for v1):
+
+[source]
+----
+PUT    /<route>                        # create/overwrite a content file (route created on demand) => 200
+DELETE /<route>                        # tombstone: the path 404s even if a lower layer has it => 204
+----
+
+Every mounted package with datasets also answers GraphQL at
+`<mount>/graphql` (POST, or GET with `?query=`): the schema is derived
+from the package's datasets — a query field `<dataset>` (list) with an
+optional `id:` argument (single item) plus `create<Dataset>`,
+`update<Dataset>` and `delete<Dataset>` mutations matching the REST
+semantics. Item types are inferred from the dataset's JSON schema when
+present, else map to a permissive JSON scalar; SQLite datasets are
+skipped. Not-found items, schema violations and read-only mutations
+land in the GraphQL `errors` array (never a 500).
+
+`POST /package/<name>/save` folds base plus overlays into a NEW
+versioned `.cap` (`<name>-<version+patch>.cap`) in the workdir and
+returns its path and SHA-256; the saved package passes
+`capsium package validate`.
 
 === Reactor introspection API
 
@@ -365,6 +531,29 @@ 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.
 
+The reactor also answers reactor-level and per-package introspection
+endpoints (07-reactor follow-ons), likewise GET-only JSON:
+
+[source]
+----
+GET /introspect/status          # => {"status": "running", "uptime": <seconds>, "packagesLoaded": 1}
+GET /introspect/config          # => {"port", "storeDir", "cacheControl", "authEnabled", "registry"}
+GET /introspect/metrics         # => {"uptime", "requestsTotal", "requestsByStatus": {"200": n, ...}}
+GET /package/<name>/status      # => {"package", "version", "status": "loaded", "valid": true}
+GET /package/<name>/metadata    # => {"name", "version", "description", "author", "guid"}
+GET /package/<name>/logs[?lines=N]  # => {"package", "logs": ["<utc> GET / -> 200", ...]}
+----
+
+`/introspect/config` never exposes secrets (deploy.json values, or
+credentials embedded in a registry URL, are redacted). With multiple
+mounted packages the `/api/v1/introspect/*` endpoints aggregate all of
+them, and `/package/<name>/...` resolves by name (404 for unknown
+names). `logs` returns the last N lines (default 100) from a small
+in-memory ring buffer (`Capsium::LogBuffer`) recording key serving
+events; `metrics` counts requests by status in memory
+(`Capsium::Reactor::Metrics`). When authentication is enabled these
+endpoints are gated like any other route.
+
 == Layered storage
 
 `storage.layers` stacks overlay directories over `content/` (bottom ->
@@ -415,6 +604,118 @@ capsium package info my-composite-package --store ./store
 capsium reactor serve my-composite-package --store ./store
 ----
 
+[[_encapsulated_packages_bundled_dependencies]]
+== Encapsulated packages (bundled dependencies)
+
+`capsium package pack --bundle-deps` (alias `--bundle`) produces a
+*self-contained* package: the resolved dependency `.cap` files are
+embedded inside the parent, so the whole tree activates with no store
+and no registry. Layout inside the `.cap`:
+
+----
+packages/
+  index.json                  # bundled-dependencies manifest
+  <name>-<version>.cap        # one per declared dependency
+----
+
+`packages/index.json` maps each dependency GUID to its embedded file,
+the resolved version and the SHA-256 of the embedded `.cap`:
+
+[source,json]
+----
+{
+  "https://example.com/capsiums/base-package": {
+    "file": "packages/base-package-1.2.0.cap",
+    "version": "1.2.0",
+    "sha256": "<hex sha256 of the .cap>"
+  }
+}
+----
+
+Resolution order on load is *bundle first*: a dependency GUID found in
+`packages/index.json` resolves to the embedded `.cap` (this also works
+when the parent itself was loaded from a `.cap` — the embedded files
+are read out of the parent's extraction); anything not bundled falls
+back to the usual store -> registry chain. The bundle is passed down
+to the dependencies' own resolution, so a dependency's dependency
+resolves from the parent's bundle when the parent re-declares it.
+
+Bundling follows a *one-level policy*: only the dependencies declared
+in the parent's own `metadata.dependencies` are embedded. To make a
+whole tree self-contained, the parent's `metadata.dependencies` must
+list the transitive closure; a bundled dependency whose own
+dependencies are not re-declared by the parent still needs a store or
+registry at activation.
+
+Security: bundled `.cap` files are covered by the parent package's
+`security.json` checksums like every other file; the manifest SHA-256
+is re-verified when a bundled dependency is resolved
+(`Security::IntegrityError` on mismatch), the bundled version must
+still satisfy the declared range, and each bundled package's own
+`security.json` (and any declared signature) is verified when it is
+loaded — the usual activation checks. Serving (layers, visibility,
+route inheritance) is unchanged: bundled sources behave exactly like
+store-resolved ones.
+
+== Static registries
+
+A *registry* is a directory or a static https base URL holding an
+`index.json` plus `.cap` files stored relative to the registry root,
+so any static host (GitHub Pages, S3, nginx) can serve one:
+
+[source,json]
+----
+{
+  "packages": {
+    "https://github.com/capsiums/cap-story": {
+      "name": "story-of-claire",
+      "versions": {
+        "1.0.0": {
+          "file": "story-of-claire-1.0.0.cap",
+          "sha256": "<hex sha256 of the .cap>",
+          "size": 642047
+        }
+      }
+    }
+  }
+}
+----
+
+`Capsium::Registry.fetch(ref)` returns the implementation for a
+reference: `Registry::Local` for a directory (read-write) or
+`Registry::Remote` for an https base URL (read-only; plain http is
+accepted for loopback hosts only). Both resolve a GUID to the newest
+version satisfying a semver constraint and install it: the `.cap` is
+fetched, verified against the sha256 declared in the index
+(`Registry::ChecksumMismatchError` on mismatch) and recorded in the
+package store as `<name>-<version>.cap` with an updated store
+`index.json`. Failures are typed (`RegistryError` subclasses):
+`RegistryNotConfiguredError`, `InvalidRegistryError`,
+`InvalidPackageError`, `PackageNotFoundError`,
+`UnsatisfiableConstraintError`, `ChecksumMismatchError`, `FetchError`.
+
+[source,bash]
+----
+# Validate a .cap, copy it into a registry directory and record it in
+# index.json (atomically rewritten; sha256+size recomputed):
+capsium package push story-of-claire-1.0.0.cap --registry ./registry
+
+# Resolve, download, sha256-verify and install into the package store:
+capsium install https://github.com/capsiums/cap-story \
+  [--constraint ">=1.0"] [--registry DIR_OR_URL] [--store DIR]
+
+# Install-then-serve a capsium:// GUID:
+capsium reactor serve capsium://example.com/story \
+  [--registry DIR_OR_URL] [--store DIR] [--constraint ">=1.0"]
+----
+
+The registry comes from `--registry` or `CAPSIUM_REGISTRY` (a typed
+error when neither is set); the store from `--store` or
+`CAPSIUM_STORE`. Composite-package dependency resolution uses the same
+fallback chain: when the store has no package for a dependency GUID,
+the resolver installs it from the configured registry into the store
+(store -> registry -> typed error).
+
 == Authentication
 
 `authentication.json` enables user authentication (05x-authentication):
@@ -620,6 +921,14 @@ bundle exec rubocop
 bundle exec rbs -I sig validate
 ----
 
+The OpenPGP specs run only when librnp is available (`brew install rnp`,
+or built from https://github.com/rnpgp/rnp); without it they skip
+cleanly, so environments without librnp (e.g. CI images that do not
+install it) stay green. The CI workflow is the shared
+cimas/metanorma `generic-rake` workflow and does not install librnp —
+install it in a custom workflow step (macOS: `brew install rnp`) to run
+the OpenPGP specs there.
+
 == License
 
 Copyright Ribose.

data/capsium.gemspec

@@ -35,11 +35,13 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "bcrypt"
   spec.add_dependency "csv"
+  spec.add_dependency "graphql"
   spec.add_dependency "json"
   spec.add_dependency "json-schema"
   spec.add_dependency "listen"
   spec.add_dependency "lutaml-model", ">= 0.8", "< 1.0"
   spec.add_dependency "marcel"
+  spec.add_dependency "rnp", ">= 1.0"
   spec.add_dependency "rubyzip", ">= 2.3.2", "< 4.0"
   spec.add_dependency "sqlite3"
   spec.add_dependency "thor"