capsium 0.2.0 → 0.6.0

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
@@ -55,6 +72,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 +91,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.
@@ -98,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
@@ -106,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]
@@ -151,20 +184,326 @@ 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
+----
+
+==== 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] [--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.
+
+=== 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>"
+  }
+}
+----
+
+==== 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 | --key secret.asc] [--openpgp] [-o decrypted.cap]
+----
+
+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.
+
+=== 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] [--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, 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).
+
+=== 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.
 
-The reactor takes a local package directory or `.cap` file; serving
-directly from a URL is not supported.
+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
 
@@ -189,6 +528,251 @@ 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:
+
+[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 ->
+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
+----
+
+[[_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):
+
+[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 +787,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 +820,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
@@ -293,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.