Capsium

OpenPGP signatures and encryption are provided through the rnp gem (a declared dependency) bound to the librnp shared library, which must be installed separately:

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.

This command generates manifest.json/routes.json when absent, writes security.json with SHA-256 checksums of every package file, and packs the 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.

When -o is omitted, the package is unpacked into a directory named after the .cap file.

Extraction is zip-slip safe: entries whose names would escape the destination (absolute paths, drive letters, .. segments) are rejected with Capsium::Packager::UnsafeEntryError.

Runs a per-check report and exits with status 1 on any failure:

• metadata: required fields present and well-formed (kebab-case name, semver version, URI guid, UUID)

• manifest: every resource exists on disk

• routes: route targets exist; dataset routes live under /api/v1/data/; the index resolves to an existing HTML file

• storage: dataset sources (and schemas) exist; dataset data passes JSON-schema validation

• security: checksums match when security.json is present

• content: no external http(s) references in content/ files

info additionally prints the resolved dependency tree for composite packages (declared GUID and range, resolved version, store .cap), see "Composite packages" below.

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:

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:

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.

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:

Decrypts an encrypted package with the recipient’s private key and writes the plaintext .cap (default output: <name>-decrypted.cap). 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.

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:

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).

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); --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).

capsium reactor serve accepts multiple sources at once: positional arguments, repeatable --mount PATH=SOURCE options, a JSON mount config via --config, or any combination:

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.

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:

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):

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.

While serving, the reactor answers the Monitoring HTTP API (ARCHITECTURE.md section 7) as application/json:

Non-GET methods on these paths are answered 405 Method Not Allowed.

content-hashes is the SHA-256 of the .cap blob when the package was served from one. For a directory source there is no blob, so the hash covers the canonical (sorted-key) JSON serialization of the package 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.

The reactor also answers reactor-level and per-package introspection endpoints (07-reactor follow-ons), likewise GET-only JSON:

/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.

packages/
  index.json                  # bundled-dependencies manifest
  <name>-<version>.cap        # one per declared dependency

When security.json is present, the package is verified on load and Capsium::Package::Security::IntegrityError is raised on mismatch.

To run the tests, use the following command:

The linter and the RBS signature validation are part of the default rake task (bundle exec rake), or run them individually:

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.