Merge pull request #32 from federated-catalogue-enhancements-2026/CAT-FR-CO-03_part3_trust-framework-bundle-overrides

CAT-FR-CO-03 part 3 - dynamic framework bundle overrides

Author: noVaSon

federated-catalogue/src/docs/architecture/chapters/05_building_block_view.adoc

@@ -401,7 +401,8 @@ Format-specific JWT unwrapping is delegated back to the matching `CredentialForm
 
 A trust framework's identity, ontology, and SHACL shapes are packaged together as a **bundle** under `classpath:trustframeworks/<bundle-id>/`.
 The catalogue ships with the `gaia-x-2511` bundle and discovers any additional bundles dropped on the classpath at boot.
-See ADR 10 for the full rationale.
+An optional filesystem override directory (env var `FEDERATED_CATALOGUE_TRUST_FRAMEWORKS_OVERRIDE_PATH`) may be mounted at deployment time; bundles found there are merged onto their classpath counterparts by `id` or registered as new bundles when no classpath match exists.
+See ADR 10 for the full rationale and overlay deep-merge rules.
 
 [options="header",cols="1,3"]
 |===
@@ -412,7 +413,7 @@ See ADR 10 for the full rationale.
 | `properties:` block in `framework.yaml` | Framework-specific runtime values consumed by the bundle's own beans (e.g. `trust_anchor_url` read by `LoirePolicyEnforcer`). Not interpreted by the registry.
 |===
 
-`TrustFrameworkBundleLoader` scans `classpath:trustframeworks/*/framework.yaml` at startup and constructs a `TrustFrameworkBundle` (config + ontology + shapes) per directory.
+`TrustFrameworkBundleLoader` scans `classpath:trustframeworks/*/framework.yaml` at startup, and additionally scans the filesystem override directory when `FEDERATED_CATALOGUE_TRUST_FRAMEWORKS_OVERRIDE_PATH` is set, constructing a `TrustFrameworkBundle` (config + ontology + shapes) per directory.
 Bundles that fail to load are logged at WARN and skipped — they do not abort the load of remaining bundles.
 
 `TrustFrameworkRegistry` indexes the loaded bundles and exposes role resolution to the verification pipeline:
@@ -459,7 +460,8 @@ classDiagram
         +UNKNOWN$
     }
     class TrustFrameworkBundleLoader {
-        +loadFromClasspath() List~TrustFrameworkBundle~
+        <<scans classpath + optional filesystem overlay>>
+        +load() List~TrustFrameworkBundle~
     }
     class TrustFrameworkService {
         +isEnabled(family) boolean

federated-catalogue/src/docs/architecture/chapters/07_deployment_view.adoc

@@ -24,6 +24,12 @@ NOTE: CAT-NFR-01footnote:[Enhancement of the XFSC Federated Catalogue. 2025. htt
 
 <<img_deployment_view>> shows the default ports for the components' interaction. The connection settings (hostnames, ports) are configurable. It is recommended to replace the default credentials. To store persistent data, the `Federated Catalogue Server`, `PostgreSQL` as well as the graph database (Neo4j or Fuseki) require a volume, which must be mounted into the container. Non-RDF assets are stored in a separate File Store directory (`federated-catalogue.file-store.asset.location`), which also requires a persistent volume in production.
 
+**Trust Framework Bundle Override Directory.**
+An optional read-only directory can be mounted into the container and pointed to by the env var `FEDERATED_CATALOGUE_TRUST_FRAMEWORKS_OVERRIDE_PATH`.
+The expected layout is `<mount-point>/<bundle-id>/framework.yaml` (plus optional sibling `ontology.ttl` and `shapes.ttl` files), mirroring the classpath structure.
+Use this mount to customise bundle properties — for example to point `trust_anchor_url` or `service_url` at in-cluster targets — or to add new bundles entirely, without rebuilding the JAR.
+See ADR 10 for overlay deep-merge semantics.
+
 Kubernetesfootnote:[https://kubernetes.io/[Kubernetes]] is the recommended infrastructure for production deployment. For development, Dockerfootnote:[https://www.docker.com/[Docker: Accelerated, Containerized Application Development]] in combination with docker-compose can be used.
 
 === Admin UI — Keycloak Setup

federated-catalogue/src/docs/architecture/chapters/08_concepts.adoc

@@ -33,7 +33,7 @@ As default, all components should log to Standard out. Log aggregation is realiz
 
 === Trust Framework Bundles
 
-Each supported trust framework is delivered as a self-contained classpath bundle (`framework.yaml` + ontology + SHACL shapes) under `trustframeworks/<bundle-id>/`.
+Each supported trust framework is delivered as a self-contained bundle (`framework.yaml` + ontology + SHACL shapes), either packaged with the JAR or supplied at deployment time as a filesystem directory, under `trustframeworks/<bundle-id>/`.
 A `TrustFrameworkRegistry` bean indexes all bundles at boot and resolves credential subject types to bundle-defined roles, replacing the previous hardcoded URI-to-enum mapping.
 See ADR 10 for the design rationale and <<_trust_framework_bundles_and_role_resolution,Building Block View — Trust Framework Bundles and Role Resolution>> for the runtime structure.
 
@@ -76,6 +76,25 @@ The resulting list is short by design (typically three to ten entries) and stabl
 When the conformity body is silent on such a class — no validation component, no criteria document, no test payload — the safe default is a defensive mapping: route the class to the most semantically adjacent existing role via `additional_roots` so credentials of that type, if they ever appear, land somewhere rather than being rejected.
 Document the mapping inline with a pointer to what would un-block dropping it (typically: confirmation from the conformity body that the class is never issued at the top level).
 
+==== Deploying Bundle Overlays
+
+A bundle overlay lets operators customise an existing bundle or add a new one at deployment time, without rebuilding the JAR.
+Set `FEDERATED_CATALOGUE_TRUST_FRAMEWORKS_OVERRIDE_PATH` (Spring property: `federated-catalogue.trust-frameworks.override-path`) to a directory mounted read-only into the container.
+The loader expects the layout `<override-path>/<bundle-id>/framework.yaml` (same as the classpath layout), with optional sibling `ontology.ttl` and `shapes.ttl` files.
+
+When the `id` in a filesystem `framework.yaml` matches a classpath bundle, the file is treated as an overlay: it only needs to declare `id` plus the fields to change.
+Nested maps merge recursively (filesystem wins per leaf key); lists and scalars replace wholesale when the overlay supplies them; sibling TTL files are inherited from the classpath bundle when the overlay directory omits them.
+A filesystem entry whose `id` has no classpath match is loaded as a brand-new bundle and must declare all mandatory fields.
+See ADR 10 for the full deep-merge rules.
+
+.Minimal overlay example — override the Trust Anchor URL for the `gaia-x-2511` bundle
+[source,yaml]
+----
+id: gaia-x-2511
+properties:
+  trust_anchor_url: "https://did-server/api/trustAnchor/chain/file"
+----
+
 ==== Type Dispatch and the OWL Toggle
 
 When a credential arrives, the catalogue maps its `credentialSubject` type URI to a trust-framework role through three tiers, in order:

federated-catalogue/src/docs/architecture/chapters/09_architecture_decisions.adoc

@@ -357,13 +357,13 @@ Fixes DSO immediately but deepens every structural problem above.
 2. **SHACL-driven discovery, retain enum:** Replace hardcoded URIs with runtime discovery; keep `TrustFrameworkBaseClass` enum as the routing label.
 Fixes DSO and enables new frameworks via config, but the fixed enum still couples the API and storage schema to Gaia-X concepts.
 
-3. **Bundle-per-framework with explicit role declarations (chosen):** Each trust framework is a self-contained classpath bundle (ontology + SHACL + a YAML config that declares the framework's roles).
+3. **Bundle-per-framework with explicit role declarations (chosen):** Each trust framework is a self-contained bundle (ontology + SHACL + a YAML config that declares the framework's roles), packaged with the JAR or supplied at deployment time as a filesystem directory.
 At startup the catalogue loads all bundles, builds a `<typeUri> → <ResolvedRole>` index by walking each declared role's subclass closure, and routes credentials by role string.
 No trust-framework concept exists in Java source — only in the bundle configs.
 
 **Decision:** Option 3 — bundle-per-framework with explicit role declarations and dynamic subclass-closure indexing.
 
-**Bundle layout (classpath resources):**
+**Bundle layout:**
 
 ----
 trustframeworks/
@@ -373,7 +373,12 @@ trustframeworks/
     shapes.ttl          # SHACL shapes (optional for non-SHACL bundles)
 ----
 
-The `TrustFrameworkBundleLoader` scans `classpath:trustframeworks/*/framework.yaml` at boot.
+Bundles ship from two sources:
+
+* **Classpath** (`classpath:trustframeworks/*/framework.yaml`): bundles packaged in the JAR; scanned first.
+* **Filesystem overlay directory** (optional, configured via `FEDERATED_CATALOGUE_TRUST_FRAMEWORKS_OVERRIDE_PATH`): a runtime-configurable directory whose subdirectories follow the same `<bundle-id>/framework.yaml` layout.
+When set, the loader scans it after the classpath and merges its entries into the classpath result.
+
 A bundle that fails to load is logged at WARN and skipped — it does not abort loading of remaining bundles.
 
 **`framework.yaml` format:**
@@ -400,6 +405,34 @@ roles:
 properties: { }                          # framework-specific metadata (reserved)
 ----
 
+**Deployment-time overlays:**
+
+The filesystem overlay directory exists to customise bundle properties — most commonly the URL of an external service the bundle calls, such as `properties.trust_anchor_url` — without rebuilding the JAR.
+It also allows new bundles to be added at deployment time for environments that need them.
+
+Resolution rule for filesystem entries:
+
+* The filesystem `framework.yaml` is parsed for its `id` field first.
+If `id` is missing or blank the entry is skipped with a warning.
+* If `id` matches a classpath bundle, the filesystem entry is treated as an **overlay**: it is deep-merged onto the classpath base.
+The filesystem file therefore only needs to declare `id` plus the fields it changes.
+* If `id` is new (no classpath match), the entry is treated as a **new bundle** and must declare all mandatory fields (`id`, `family`, `namespace`, `validation_type`, `roles`).
+
+Merge semantics for overlays:
+
+* Nested maps (e.g. `properties:`, `roles:`) merge recursively; the filesystem value wins at each leaf key.
+* Lists (e.g. `additional_roots`, `types`) and scalars (e.g. `namespace`, `validation_type`) replace wholesale when the filesystem provides them.
+* Sibling files (`ontology.ttl`, `shapes.ttl`) are inherited from the classpath bundle when the overlay directory does not ship its own.
+
+Minimal overlay example — redirect the Gaia-X bundle's trust anchor URL to an in-cluster service without copying the rest of the bundle:
+
+[source,yaml]
+----
+id: gaia-x-2511
+properties:
+  trust_anchor_url: "https://did-server/api/trustAnchor/chain/file"
+----
+
 **Role declaration is a manual, per-framework curation step — not auto-derivable.**
 The `roles:` map is the bundle author's hand-written declaration of which classes the catalogue dispatches on as top-level credential subjects.
 It cannot be extracted from the ontology, because trust-framework ontologies do not mark classes as "catalogue roles":
@@ -458,7 +491,7 @@ It is independent of role resolution: any credential whose subject type URI is r
 **Multi-framework side-by-side:** Multiple bundles load simultaneously.
 Namespaces are disjoint by construction; resolution is unambiguous.
 A VP containing credentials from different frameworks routes each credential through its own bundle's role.
-Adding a new framework is a classpath-resource change — drop a new `trustframeworks/<bundle-id>/` directory containing `framework.yaml` plus the ontology/SHACL files; no Java changes.
+Adding a new framework is a bundle drop-in — either as a classpath resource baked into a custom JAR or as a directory under the deployment-time overlay path, in both cases containing `framework.yaml` plus the ontology/SHACL files; no Java changes.
 
 **Removed configuration:** the `federated-catalogue.verification.{participant,resource,service-offering}.type` properties (and the `service-offering.additional-types` workaround) are no longer read.
 Type URIs are now declared exclusively in each bundle's `framework.yaml`.

federated-catalogue/src/docs/architecture/chapters/12_glossary.adoc

@@ -90,8 +90,11 @@ The identifier must be a valid IRI (see ADR 7).
 |fcmeta:hasMachineReadable
 |RDF property in the protected `fcmeta:` namespace written to the graph DB when an asset link is created. Points from a human-readable asset's IRI to its machine-readable counterpart's IRI.
 
+|Bundle Overlay
+|A `framework.yaml` placed in the trust-framework filesystem override directory that shares an `id` with a classpath bundle. The overlay's fields deep-merge onto the classpath base (see ADR 10), allowing deployment-time customisation of bundle properties without rebuilding the JAR.
+
 |Trust Framework Bundle
-|A self-contained, classpath-loaded unit (`framework.yaml` + `ontology.ttl` + `shapes.ttl`) defining a single trust-framework profile. Discovered at boot under `trustframeworks/<bundle-id>/`. Indexed by `TrustFrameworkRegistry` to drive role resolution. See ADR 10.
+|A self-contained, classpath- or filesystem-loaded unit (`framework.yaml` + `ontology.ttl` + `shapes.ttl`) defining a single trust-framework profile. Discovered at boot under `trustframeworks/<bundle-id>/` (classpath) and/or in the filesystem override directory. Filesystem entries can either overlay a classpath bundle by `id` or introduce a new bundle. Indexed by `TrustFrameworkRegistry` to drive role resolution. See ADR 10.
 
 |Framework Profile (id)
 |Stable identifier of a single trust-framework bundle (e.g. `gaia-x-2511`). Acts as the registry key and the `frameworkProfileId` of every `ResolvedRole` it produces.