capsium 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2b954beb33b36d3300f8ff418f643a9afbbf688fad4e8333b195ccb76b38b41
-  data.tar.gz: b2ef9e049b70ce3eb111ef0c136befaaf7a2f6a4d233ed9fb41a9d27d9c39e2c
+  metadata.gz: 188f04acf4c1f13b7a4515798e1183f59473ffba9200d375ea31b7ec2ceb705f
+  data.tar.gz: '068cb0fbbfa415b6f07bb299e233c2f27f5161fe82b932c1379883fcba79a36f'
 SHA512:
-  metadata.gz: e3c75b5ab47ef3b7fe5a8f20571a300c15b960951c032d9c8d01e3eff295a237c294288613449ed090c73e38df718986f412573deeafd0f33acd7a43ead76c41
-  data.tar.gz: 8bdb432b2b7efb4987d211608e8cb13828e2bf49d49cf921c3d9a7f7cc74f5a775ed6454e5bfd3e91a539a36fa0beb28395ff7910682d9d791f8c44db3eebe26
+  metadata.gz: ed6d82167bc38448608ced953d1c906980e2fbbbc1297e1c79debe3aaf67508a9aa14237741c42be113b4daffe4e8c8d3e7a8c710f899acebeece1ce9b4dfde8
+  data.tar.gz: c1294b0ec91effddc6cf7da04cb4c128db2a31f2f82625b2a12b92c303be6bcfc566f4bf4a8c6658a187f623e8ba433cab24d275a0d880b82c3717775aec3aa5

data/.gitignore

@@ -6,6 +6,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+/Gemfile.lock
 
 # rspec failure tracking
 .rspec_status

data/.rubocop.yml

@@ -1,12 +1,51 @@
-inherit_from:
-  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
-
-# local repo-specific modifications
-# ...
+plugins:
+  - rubocop-performance
 
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.2
   NewCops: enable
+  SuggestExtensions: false
   Exclude:
-    - 'lib/sts/mapper.rb'
     - 'vendor/**/*'
+
+Layout/LineLength:
+  Max: 100
+
+# Project convention: double-quoted string literals.
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+# Classes are intentionally undocumented for now; API docs land with a
+# later phase together with the RBS signatures.
+Style/Documentation:
+  Enabled: false
+
+# RSpec example groups and the gemspec are block-heavy by nature.
+Metrics/BlockLength:
+  Exclude:
+    - '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
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/CyclomaticComplexity:
+  Max: 8

data/CHANGELOG.md

@@ -0,0 +1,183 @@
+# 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
+
+- Migrated all package configuration models from shale to lutaml-model.
+- All configuration files now follow the canonical schemas
+  (ARCHITECTURE.md sections 2-6):
+  - `metadata.json`: `dependencies` is an object of `guid -> semver range`;
+    `name`/`version`/`description`/`guid`/`uuid` are the required fields.
+  - `manifest.json`: a `resources` object keyed by package-relative path
+    (`type`, `visibility`, optional `version`).
+  - `routes.json`: optional top-level `index` plus a `routes` array with
+    discriminated kinds (`resource` / `dataset` / handler).
+  - `storage.json`: `storage.dataSets` object; dataset `source` and
+    `schemaFile` are package-relative paths.
+- Legacy (pre-0.2) configuration files are accepted on read and normalized
+  to the canonical forms; writers emit only the canonical forms.
+- Manifest and routes auto-generation is deterministic (sorted); HTML files
+  get dual routes, the index HTML gets `/`, datasets get
+  `/api/v1/data/<id>`.
+- The reactor serves dataset routes as JSON, sets `Cache-Control: public,
+  max-age=31536000` on static resources (configurable), responds 501 to
+  handler routes, and rejects packages that fail integrity verification.
+- The CLI exits nonzero on errors.
+
+### Added
+
+- `security.json` with SHA-256 checksums over every package file, generated
+  at pack time; verified automatically on load (`Package#verify_integrity`,
+  `Capsium::Package::Security::IntegrityError` on mismatch).
+- `capsium package validate <path|cap>`: per-check validation report
+  (metadata formats, on-disk existence of manifest resources, route targets
+  and dataset sources, dataset JSON-schema validation, checksums, external
+  http(s) references in content), exit status 1 on any failure.
+- `capsium package unpack <cap> [-o dir]`.
+- `Capsium::Package::Validator` and `Capsium::Package::Security`.
+- Reactor introspection HTTP API (ARCHITECTURE.md section 7):
+  `GET /api/v1/introspect/metadata`, `/routes`, `/content-hashes` and
+  `/content-validity`, served as JSON by `Capsium::Reactor::Introspection`.
+  `content-hashes` is the SHA-256 of the `.cap` blob, or of the canonical
+  JSON serialization of the content checksums for directory sources;
+  `content-validity` re-verifies integrity live.
+- Zip-slip protection on `.cap` extraction: entries escaping the
+  destination (absolute paths, drive letters, `..` segments) raise
+  `Capsium::Packager::UnsafeEntryError`.
+- RBS signatures for the public API (`sig/`), kept green by the
+  `rbs:validate` rake task (part of the default rake task).
+- `Capsium::Package#cap_file_path`.
+
+### Removed
+
+- `Capsium::Protector` (bit-rotted, insecure; encryption/signing is
+  deferred to a later phase).
+- shale dependency (replaced by lutaml-model); base64 dependency.
+- Unused constants `Package::PACKAGING_FILE`, `Package::SIGNATURE_FILE`,
+  `Package::ENCRYPTED_PACKAGING_FILE`, `Routes::DEFAULT_INDEX_TARGET`.

data/Gemfile

@@ -4,3 +4,9 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in capsium.gemspec
 gemspec
+
+gem "rake", "~> 13.0"
+gem "rbs", "~> 4.0"
+gem "rspec", "~> 3.11"
+gem "rubocop", "~> 1.88"
+gem "rubocop-performance", "~> 1.26"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ribose Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.