diff --git a/README.md b/README.md index 5513afd..d4b51c7 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,18 @@ # XFSC Documentation -This repository contains the XFSC documentation about the components, architecture and more. \ No newline at end of file +This repository contains the XFSC documentation about the components, architecture and more. + +## Rendering docs locally + +A Dockerized AsciiDoc toolchain with Mermaid diagram support is available under [`tools/asciidoctor/`](tools/asciidoctor/). Build the image once, then use it to render any document: + +```bash +# Build +docker build -t xfsc-asciidoctor tools/asciidoctor/ + +# Render to HTML +docker run --rm -v "$(pwd)":/documents xfsc-asciidoctor \ + asciidoctor -r asciidoctor-diagram path/to/document.adoc +``` + +See the [full README](tools/asciidoctor/README.md) for PDF output and more examples. \ No newline at end of file diff --git a/federated-catalogue/src/docs/architecture/chapters/01_introduction_and_goals.adoc b/federated-catalogue/src/docs/architecture/chapters/01_introduction_and_goals.adoc index 7859b1a..307056d 100644 --- a/federated-catalogue/src/docs/architecture/chapters/01_introduction_and_goals.adoc +++ b/federated-catalogue/src/docs/architecture/chapters/01_introduction_and_goals.adoc @@ -20,6 +20,12 @@ The requirements for implementing the Gaia-X Federated Catalogue are given in it * The specification of a requirement turned out to be unsatisfiable for conceptual or practical reasons. * The understanding of an underlying concept had evolved during the further work of the Gaia-X Technical Committee and its working groups after the original publication of the requirements specification. +The catalogue specification has been updated with new requirements, identified by IDs starting with CAT-FR-*. +While these requirements are not fully implemented yet, they are planned to be completed by 2026. +The catalogue's architecture is designed to support the implementation of these new requirements. +In cases of conflict, the newer requirements take precedence over the older ones. + +For more details, refer to the document "Enhancement of the XFSC Federated Catalogue" footnote:[Enhancement of the XFSC Federated Catalogue. 2025. https://github.com/eclipse-xfsc/docs/blob/9a178c30f76610e5924fd72c39d259d6a8ae0461/federated-catalogue/src/docs/CAT%20Enhancement/CAT_Enhancement_Specifications%20v1.0.pdf]. === Quality Goals diff --git a/federated-catalogue/src/docs/architecture/chapters/05_building_block_view.adoc b/federated-catalogue/src/docs/architecture/chapters/05_building_block_view.adoc index fdfbcbd..dad1d17 100644 --- a/federated-catalogue/src/docs/architecture/chapters/05_building_block_view.adoc +++ b/federated-catalogue/src/docs/architecture/chapters/05_building_block_view.adoc @@ -74,9 +74,21 @@ The Graph Database can be considered as a kind of search index. The single sourc Generically returning the Self-Description files containing claims that influence query response is not possible. To get the relevant Self-Description files, the query to the Graph Database can be formulated to return the Gaia-X entity that is the __credentialSubject__ of a Verifiable Credential. Then this can be used as a filter for the Self-Description endpoint, to download the Self-Description file. -Neo4j is used as implementation of the Graph database. +The graph database backend is **pluggable**. The implementation is selected via the `graphstore.impl` configuration property: -[IMPORTANT] +[options="header",cols="1,2,2"] +|=== +| Value | Backend | Query Language +| `neo4j` | Neo4j (default) | openCypher +| `fuseki` | Apache Jena Fuseki | SPARQL-star +| `dummy` | No-op (for testing) | — +|=== + +Both backends implement the same `GraphStore` interface. Core services contain no backend-specific logic. + +===== Neo4j backend + +[IMPORTANT] .Limitation: queries to non-Enterprise Neo4j Graph database return empty record when no results found, rather than empty list. ==== When there is no data in the Graph database, i.e., no claims extracted from Self-Description, there is still a configuration node for the neosemantics modulefootnote:[https://neo4j.com/labs/neosemantics/4.0/config/[Configuring Neo4j to use RDF data]], which enables Neo4j to support the RDF data model, which is required here. @@ -89,6 +101,10 @@ However this revoke operation is only supported in Neo4j enterprise.footnote:[ht We chose not to implement a workaround that involves query rewriting, as this may have harmful side effects. ==== +===== Fuseki backend + +The Fuseki backend uses Apache Jena with RDF-star. Claims are stored as RDF-star triple nodes: `<< subject predicate object >> cred:credentialSubject credentialSubjectUri`. Queries must use SPARQL-star syntax. Results are shuffled unless the query contains an `ORDER BY` clause. + ==== File Store The File Store is responsible to persist all file based content submitted to the catalogue. These are Self-Descriptions and Schemas. @@ -112,7 +128,14 @@ The catalogue implementation is structured into two main components _fc-service- | Service | Component, controlling the workflows and interactions between the subcomponents. | Authorization | Handling the authorization, and user management in combination with the _Service_ and _Authentication_ component. | Authentication | This component stores the users and participant metadata. -| Verification | Responsible for applied the defined verification rules on the Self-Descriptions. Also extracts the claims from the Verifiable Presentation (_Claim Extractor_). Also contains a component to periodically revalidate submitted Self-Descriptions (_Revalidation Service_). +| Verification +a| Responsible for applying the defined verification rules on the Self-Descriptions and extracting claims from Verifiable Presentations. + +* **Verification pipeline:** Syntactic, semantic, and cryptographic verification of Self-Descriptions. The SD is checked as a whole — if VC verification fails, the entire SD verification fails. +* **Strategy pattern:** `VerificationServiceImpl` acts as a thin Context that delegates to a `VerificationStrategy` implementation (currently `CredentialVerificationStrategy`). +* **Schema Validation Service:** Automatic SHACL schema validation has been disabled in the upload flow and extracted to a dedicated service. +* **Revalidation Service:** Periodically revalidates submitted Self-Descriptions. +* **Claim Extractor:** Extracts claims from Verifiable Presentations. | Graph Store | Interface and logic for communicating with the Graph DB. | Schema Store @@ -173,75 +196,100 @@ Notes: * The SD is checked as a whole. If the verification of the VCs fails, the verification of the whole SD fails. -[source,java] ----- -/** - * Validation Self-Description interface. - */ -@Service -public interface VerificationService { +[mermaid, width=2000] +.... +classDiagram + class VerificationService { + <> + +verifyParticipantSelfDescription(payload) VerificationResultParticipant + +verifyOfferingSelfDescription(payload) VerificationResultOffering + +verifyResourceSelfDescription(payload) VerificationResultResource + +verifySelfDescription(payload) VerificationResult + +verifySelfDescription(payload, verifySemantics, verifySchema, verifyVPSig, verifyVCSig) VerificationResult + +extractClaims(payload) List~SdClaim~ + +verifySelfDescriptionAgainstSchema(payload, schema) SchemaValidationResult + +verifySelfDescriptionAgainstCompositeSchema(payload) SchemaValidationResult + } + note for VerificationService "verifySelfDescriptionAgainstSchema and\nverifySelfDescriptionAgainstCompositeSchema\nare deprecated — use SchemaValidationService directly" +.... - /** - * The function validates the Self-Description as JSON and tries to parse the json handed over. - * - * @param payload ContentAccessor to SD which should be syntactically validated. - * @return a Participant metadata validation result. If the validation fails, the reason explains the issue. - */ - VerificationResultParticipant verifyParticipantSelfDescription(ContentAccessor payload) throws VerificationException; +[#_verification_strategy_pattern] +===== Verification Strategy Pattern - /** - * The function validates the Self-Description as JSON and tries to parse the json handed over. - * - * @param payload ContentAccessor to SD which should be syntactically validated. - * @return a Verification result. If the verification fails, the reason explains the issue. - */ - VerificationResultOffering verifyOfferingSelfDescription(ContentAccessor payload) throws VerificationException; +The `VerificationServiceImpl` follows the Strategy pattern. It acts as a thin Context that maintains per-request verification toggles (`verifySemantics`, `verifySchema`, `verifyVPSignature`, `verifyVCSignature`) and delegates all verification and claim extraction logic to a `VerificationStrategy` injected via Spring's `@Qualifier`. - /** - * The function validates the Self-Description as JSON and tries to parse the json handed over. - * - * @param payload ContentAccessor to SD which should be syntactically validated. - * @return a Self-Description metadata validation result. If the validation fails, the reason explains the issue. - */ - VerificationResult verifySelfDescription(ContentAccessor payload) throws VerificationException; +The `resolveStrategy(ContentAccessor)` method selects the appropriate strategy for a given payload. Currently it always resolves to `CredentialVerificationStrategy`. - /** - * The function validates the Self-Description against the composite schema. - * - * @param payload ContentAccessor to SD which should be validated. - * @return the result of the semantic validation. - */ - SemanticValidationResult verifySelfDescriptionAgainstCompositeSchema(ContentAccessor payload); +[mermaid, width=2000] +.... +classDiagram + class VerificationServiceImpl { + -verifySemantics : boolean + -verifySchema : boolean + -verifyVPSignature : boolean + -verifyVCSignature : boolean + +resolveStrategy(payload) VerificationStrategy + } + class VerificationStrategy { + <> + +verifySelfDescription(payload, strict, expectedClass, flags) VerificationResult + +extractClaims(payload) List~SdClaim~ + +setBaseClassUri(baseClass, uri) void + } + class CredentialVerificationStrategy { + +verifySelfDescription(payload, strict, expectedClass, flags) VerificationResult + +extractClaims(payload) List~SdClaim~ + } + VerificationServiceImpl --> VerificationStrategy : delegates to + VerificationStrategy <|.. CredentialVerificationStrategy +.... - /** - * The function validates the Self-Description as JSON and tries to parse the json handed over. - * - * @param payload - * @param verifySemantics - * @param verifySchema - * @param verifySignatures - * @return - * @throws VerificationException - */ - VerificationResult verifySelfDescription(ContentAccessor payload, - boolean verifySemantics, boolean verifySchema, boolean verifySignatures) throws VerificationException; +`VerificationServiceImpl` injects the strategy via `@Qualifier("credentialVerificationStrategy")`, providing compile-time safety. The `resolveStrategy(ContentAccessor)` method currently always resolves to `CredentialVerificationStrategy`. - /** - * Extract claims from the given payload. This does not do any validation of the payload. - * - * @param payload The payload to extract claims from. - * @return The list of extracted claims. - */ - List extractClaims(ContentAccessor payload); -} ----- +[#_upload_schema_validation_configuration] +===== Schema Validation Configuration + +Automatic SHACL schema validation during asset upload is disabled by default. This behavior is controlled by the `schema` verification property. +[options="header",cols="2,1,3"] +|=== +| Property | Default | Description +| `federated-catalogue.verification.schema` | `false` | Enable/disable automatic SHACL schema validation during asset upload. +|=== + +**When disabled (default):** + +* Assets are stored regardless of SHACL Shape conformity +* No validation errors on upload for non-conforming assets +* SHACL Shapes remain uploadable and available for on-demand validation. + +**When enabled:** + +* Assets are validated against all stored SHACL Shapes during upload +* Upload is rejected if the asset is invalid against any stored shape + +[#_schema_validation_service] +===== Schema Validation Service + +Automatic schema validation has been **disabled in the upload verification flow**. The Schema Validation Service was extracted from the `VerificationService` to provide on-demand SHACL schema validation of stored assets. + +[mermaid, width=2000] +.... +classDiagram + class SchemaValidationService { + <> + +validateSelfDescriptionAgainstSchema(payload, schema) SchemaValidationResult + +validateSelfDescriptionAgainstCompositeSchema(payload) SchemaValidationResult + +validateClaimsAgainstSchema(claims, schema) SchemaValidationResult + +validateClaimsAgainstCompositeSchema(claims) SchemaValidationResult + } +.... ===== Revalidation Service This component periodically revalidates existing Self-Descriptions. It checks if the signatures are still valid (e.g. not expired or referencing DID is still available). If the validation of a Self-Description fails, it's either set to state _deprecated_ or _eol_. This will remove the Self-Description from the Graph Database. -Semantic revalidation is not needed here. It is done every time a new Schema is added. +Semantic revalidation is not needed here. Schema revalidation against SHACL shapes is performed by the `SchemaValidationService` every time a new Schema is added or updated. ===== Claim Extractor @@ -249,7 +297,7 @@ This component is used by the _Verification Service_ to extract Claims from Self ==== Graph Store -The Graph Store is the interface for interacting with the Graph Database. It receives claims (extracted from Self-Descriptions) and adds them to the graph database. The Graph Database only contains claims from active Self-Descriptions and offers an openCypher query interface. External ontologies are not queried when processing requests. +The Graph Store is the interface for interacting with the Graph Database. It receives claims (extracted from Self-Descriptions) and adds them to the graph database. The Graph Database only contains claims from active Self-Descriptions and offers a query interface (openCypher for the Neo4j backend, SPARQL-star for the Fuseki backend). External ontologies are not queried when processing requests. [source,java] ---- diff --git a/federated-catalogue/src/docs/architecture/chapters/06_runtime_view.adoc b/federated-catalogue/src/docs/architecture/chapters/06_runtime_view.adoc index a00fd56..cf6cd21 100644 --- a/federated-catalogue/src/docs/architecture/chapters/06_runtime_view.adoc +++ b/federated-catalogue/src/docs/architecture/chapters/06_runtime_view.adoc @@ -571,7 +571,7 @@ sequenceDiagram VerificationService --> VerificationService:[Verify Syntax] VerificationService --> VerificationService:[Verify Semantic] VerificationService --> VerificationService:[Extract SD Type] - VerificationService --> VerificationService:[Verify Schema] + Note over VerificationService: Schema validation disabled by default (verifySchema=false) VerificationService --> VerificationService:[Verify Signatures] VerificationService --> VerificationService:[Extract Participant] VerificationService --> VerificationService:[Extract Claims] @@ -771,6 +771,10 @@ When calling `GET /query` a HTML page with a query input form is displayed. ==== Query the catalogue +The query endpoint accepts an optional `queryLanguage` query parameter to select the query language. The default is `OPENCYPHER` (for the Neo4j backend). When the Fuseki backend is configured, use `queryLanguage=SPARQL` to issue SPARQL-star queries. Queries in a language not supported by the active backend are rejected with HTTP 501. + +Only read queries are allowed. Write queries (e.g., `CREATE`/`DELETE` in openCypher, `INSERT`/`DELETE` in SPARQL) are rejected with HTTP 500. + [mermaid, width=2000] .... sequenceDiagram @@ -778,7 +782,7 @@ sequenceDiagram actor User participant API participant Graph as Graph-DB - User ->> + API: POST /query + User ->> + API: POST /query?queryLanguage={OPENCYPHER|SPARQL} API ->> + Graph: queryData(sdQuery) Graph ->> Graph: validateQuery() Note right of Graph: Only read queries are allowed @@ -802,10 +806,20 @@ sequenceDiagram participant API participant VerificationService User ->> + API:POST /verifications/self-descriptions - API ->> + VerificationService:verifySelfDescription(sd) + API ->> + VerificationService:verifySelfDescription(sd, verifySemantics, verifySchema, verifyVPSig, verifyVCSig) VerificationService --> VerificationService:[Verify Syntax] - VerificationService --> VerificationService:[Verify Signatures] - VerificationService --> VerificationService:[Verify Schema] + opt verifySemantics (default true) + VerificationService --> VerificationService:[Verify Semantic] + VerificationService ->> VerificationService:[Extract SD Type] + end + opt verifySchema (default false) + VerificationService ->> SchemaValidationService:[Validate Claims vs SHACL] + SchemaValidationService -->> VerificationService:SemanticValidationResult + end + opt verifyVPSig / verifyVCSig (default true) + VerificationService --> VerificationService:[Verify Signatures] + end + VerificationService ->> VerificationService:[Extract Claims] VerificationService -->> - API:VerificationResult API -->> -User: VerificationResult .... @@ -869,19 +883,20 @@ sequenceDiagram ==== Verify Self-Description -The verification of SDs consists out of three parts (syntactic, cryptographic, semanticaverification). -Besides verifing the SD additional tasks are executed (e.g., parsing, claim extraction). +The verification of SDs consists of four parts (syntactic, semantic, schema, and trust verification). +Besides verifying the SD additional tasks are executed (e.g., parsing, claim extraction). + +`VerificationServiceImpl` acts as a thin Context in the Strategy pattern: it resolves per-request verification toggles and delegates all verification and claim extraction logic to a `VerificationStrategy` (currently `CredentialVerificationStrategy`). The strategy contains the full VP/VC parsing, semantic validation, schema validation, signature verification, and claim extraction logic. See <<_verification_strategy_pattern>> for details. -The syntactic verification is done by parsing the SD. +The syntactic verification is done by parsing the SD. Any syntactic issue will rise there. The semantic verification is conducted after the parsing of the Self-Description. -The uploaded Self-Descriptions are checked against a composite schema of type SHACL. -If a Self-Description is not conforming against the composite schema, a verification exception will be -thrown with a message containing the validation report that holds the cause. In that case, -the verification process will not proceed, and claims will not be extracted. +Automatic schema validation against stored SHACL shapes has been **disabled in the upload verification flow**. Self-Descriptions are accepted regardless of their conformity to stored SHACL shapes. On-demand schema validation of stored assets against specific SHACL shapes is available through the dedicated `SchemaValidationService` (see <<_schema_validation_service>>). + +NOTE: For backward compatibility, automatic schema validation during upload can be re-enabled via the configuration property `federated-catalogue.verification.schema=true`. -The cryptographic verification (trust verification) checks all proofs in the SD if the signature, the offered key and the content match. +The trust verification checks all proofs in the SD if the signature, the offered key and the content match. When Gaia-X Trust Framework validation is enabled, the key is additionally validated against the Gaia-X Trust Anchor Registry to verify a valid trust anchor chain. When this setting is disabled (the default), signature verification still ensures that signatures are valid and match the content. When checking whether the proofs match the Self-Description or the contained Verifiable Credentials, the JSON object is normalized using the Universal RDF Dataset Canonicalization Algorithm URDNA2015footnote:[https://w3c-ccg.github.io/rdf-dataset-canonicalization/spec/#dfn-urdna2015[RDF Dataset Canonicalization. A Standard RDF Dataset Canonicalization Algorithm. W3C, Final Community Group Report 15 October 2022]] as specified by Gaia-X. This allows a robust signing of Self-Descriptions. @@ -898,16 +913,12 @@ sequenceDiagram VerificationService --> VerificationService:[Verify Syntax] VerificationService --> VerificationService:[Verify Semantic] VerificationService ->> VerificationService:[Extract SD Type] - VerificationService --> VerificationService:[Verify Schema] + Note over VerificationService: Schema validation disabled by default VerificationService --> VerificationService:[Verify Signatures] VerificationService ->> VerificationService:[Extract Claims] VerificationService ->> VerificationService:[Extract Participant] .... -image:06_verification_flow.png[Verification Workflow] -//// -This is the source code for the figure above. Directly added the figure due to a bug in mmdc - [mermaid, width=2000] .... flowchart LR @@ -921,8 +932,10 @@ flowchart LR end subgraph three [Schema Validation] direction TB - threeA([Extract Claims]) - threeA --> threeB(Check claims vs SHACL) + threeA{{verification.schema
enabled?}} + threeA --> |yes| threeB([Extract Claims]) + threeB --> threeC(Check claims vs SHACL
via SchemaValidationService) + threeA --> |no — default| threeD([Skip schema validation]) end subgraph four [Trust Verification] direction TB @@ -946,4 +959,4 @@ flowchart LR C{{Configuration-dependent step}} end .... -//// + diff --git a/federated-catalogue/src/docs/architecture/chapters/07_deployment_view.adoc b/federated-catalogue/src/docs/architecture/chapters/07_deployment_view.adoc index 69a5005..3aec893 100644 --- a/federated-catalogue/src/docs/architecture/chapters/07_deployment_view.adoc +++ b/federated-catalogue/src/docs/architecture/chapters/07_deployment_view.adoc @@ -13,13 +13,13 @@ ifndef::imagesdir[:imagesdir: ../../images] == Deployment View -The Federated Catalogue is provided as a container based application. The different components are shown in <>. The main component is the `Federated Catalogue Server`. It requires a PostgreSQL-Serverfootnote:[https://www.postgresql.org/[PostgreSQL: The world's most advanced open source database]] instance to store Self-Description metadata and a Neo4jfootnote:[https://neo4j.com/[Neo4j Graph Data Platform | Graph Database Management System]] instance to store the Self-Description graph and to support the query interface of the catalogue. +The Federated Catalogue is provided as a container based application. The different components are shown in <>. The main component is the `Federated Catalogue Server`. It requires a PostgreSQL-Serverfootnote:[https://www.postgresql.org/[PostgreSQL: The world's most advanced open source database]] instance to store Self-Description metadata and a graph database instance to store the Self-Description graph and to support the query interface of the catalogue. The graph database backend is pluggable, selected via the `graphstore.impl` configuration property. Supported backends are Neo4jfootnote:[https://neo4j.com/[Neo4j Graph Data Platform | Graph Database Management System]] (openCypher queries) and Apache Jena Fusekifootnote:[https://jena.apache.org/documentation/fuseki2/[Apache Jena Fuseki]] (SPARQL-star queries). [#img_deployment_view,reftext='Figure {counter:refnum}'] image::07_deployment_view.png[title="Deployment View"] In addition, a Keycloak instance is needed to handle authentication. Keycloak, as well as the portal, used to interact with the Federated Catalogue, is considered out of scope for the Federated Catalogue itself. -<> 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 `Neo4J` require a volume, which must be mounted into the container. +<> 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. 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. diff --git a/federated-catalogue/src/docs/architecture/chapters/08_concepts.adoc b/federated-catalogue/src/docs/architecture/chapters/08_concepts.adoc index 0d1e42c..5865896 100644 --- a/federated-catalogue/src/docs/architecture/chapters/08_concepts.adoc +++ b/federated-catalogue/src/docs/architecture/chapters/08_concepts.adoc @@ -18,7 +18,7 @@ Data is persisted in the following components: * Federated Catalogue Server: Self-Description and Schema files (Filesystem) * Metadata Store: Self-Description and Schema metadata (PostgreSQL) -* Graph store: Self-Description graph (Neo4j) +* Graph store: Self-Description graph (Neo4j or Fuseki, depending on `graphstore.impl` configuration) During the deployment it must be ensured that volumes are mounted to store the persistent data in the mentioned components. diff --git a/federated-catalogue/src/docs/architecture/chapters/13_appendix.adoc b/federated-catalogue/src/docs/architecture/chapters/13_appendix.adoc index 1b68854..a0a8b43 100644 --- a/federated-catalogue/src/docs/architecture/chapters/13_appendix.adoc +++ b/federated-catalogue/src/docs/architecture/chapters/13_appendix.adoc @@ -15,6 +15,8 @@ ifndef::imagesdir[:imagesdir: ../../images] These examples demonstrate how to interact with the xref:05_building_block_view#_graph_database[Graph Database]. +NOTE: The examples below use **openCypher** syntax, which applies to the **Neo4j** backend (`graphstore.impl=neo4j`). When using the **Fuseki** backend (`graphstore.impl=fuseki`), equivalent queries must be expressed in **SPARQL-star** syntax via the `POST /query?queryLanguage=SPARQL` endpoint. See <> for SPARQL-star equivalents. + All of the following examples have the same structure: Data:: @@ -279,3 +281,44 @@ MATCH (n:ServiceOffering) WHERE n.name = "Elastic Search DB" RETURN n.uri LIMIT ---- [{n.uri=http://w3id.org/gaia-x/indiv#serviceElasticSearch.json}] ---- + +[[sparql_star_examples]] +==== SPARQL-star Examples (Fuseki backend) + +The following examples show equivalent queries for the Fuseki backend using SPARQL-star syntax. These are sent via `POST /query?queryLanguage=SPARQL`. + +===== All triples + +Retrieve all triples stored in the graph: + +[source,sparql] +---- +SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 100 +---- + +===== All claims with credential subject + +Retrieve all Self-Description claims together with the credential subject they belong to, using RDF-star syntax: + +[source,sparql] +---- +PREFIX cred: +SELECT ?s ?p ?o ?cs +WHERE { + << ?s ?p ?o >> cred:credentialSubject ?cs +} +LIMIT 100 +---- + +===== Claims for a specific credential subject + +Retrieve claims belonging to a specific Self-Description: + +[source,sparql] +---- +PREFIX cred: +SELECT ?s ?p ?o +WHERE { + << ?s ?p ?o >> cred:credentialSubject +} +---- diff --git a/federated-catalogue/src/docs/images/06_verification_flow.png b/federated-catalogue/src/docs/images/06_verification_flow.png index 32beb26..2dcbe9d 100644 --- a/federated-catalogue/src/docs/images/06_verification_flow.png +++ b/federated-catalogue/src/docs/images/06_verification_flow.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:b33c86c549327953c75dc03bc110ed173d531673917c9ccbddc4248ac1e98da1 -size 103072 +oid sha256:f2a5fcf229f0b1b9b8248d7d8555032d33815aa73c17d48d6eb3015e3bb8748f +size 107647 diff --git a/tools/asciidoctor/Dockerfile b/tools/asciidoctor/Dockerfile new file mode 100644 index 0000000..fa5264b --- /dev/null +++ b/tools/asciidoctor/Dockerfile @@ -0,0 +1,32 @@ +FROM asciidoctor/docker-asciidoctor:1.102.0 +LABEL org.opencontainers.image.title="xfsc-asciidoctor" + +# Install Chromium (native ARM/x86 via Alpine) and Mermaid CLI. +# PUPPETEER_SKIP_DOWNLOAD prevents Puppeteer from pulling its own +# x86-only Chromium binary — we use the system package instead. (Fix for arm64 host architectures) +ENV PUPPETEER_SKIP_DOWNLOAD=true +ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser + +# Puppeteer config for mmdc: --no-sandbox is required inside containers due to +# Linux kernel namespace restrictions (applies to root and non-root users alike). +# Wrap mmdc so it always passes -p with the puppeteer config. +# asciidoctor-diagram calls mmdc directly, and older versions don't forward +# the puppeteerConfigFile attribute, so a wrapper is the most reliable fix. +# Run as a non-root user to reduce the attack surface of the container. +RUN apk add --no-cache nodejs npm chromium font-noto \ + && npm install -g @mermaid-js/mermaid-cli \ + && npm cache clean --force \ + && printf '{\n "executablePath": "/usr/bin/chromium-browser",\n'\ +' "args": ["--no-sandbox", "--disable-gpu",'\ +' "--disable-dev-shm-usage"]\n}\n'\ + > /usr/local/share/puppeteer-config.json \ + && REAL_MMDC=$(which mmdc) \ + && mv "$REAL_MMDC" "${REAL_MMDC}.real" \ + && printf '#!/bin/sh\n'\ +'exec "$(dirname "$0")/mmdc.real"'\ +' -p /usr/local/share/puppeteer-config.json "$@"\n'\ + > "$REAL_MMDC" \ + && chmod +x "$REAL_MMDC" \ + && addgroup -S asciidoc \ + && adduser -S -G asciidoc asciidoc +USER asciidoc diff --git a/tools/asciidoctor/README.md b/tools/asciidoctor/README.md new file mode 100644 index 0000000..7df51be --- /dev/null +++ b/tools/asciidoctor/README.md @@ -0,0 +1,59 @@ +# xfsc-asciidoctor + +Docker image for rendering AsciiDoc documents with Mermaid diagram support. Based on the official [asciidoctor/docker-asciidoctor](https://github.com/asciidoctor/docker-asciidoctor) image, extended with Chromium and the Mermaid CLI (`mmdc`). + +## Build + +```bash +docker build -t xfsc-asciidoctor docs/tools/asciidoctor/ +``` + +## Prerequisites + +Some image files in the repository are stored with **Git LFS**. If they haven't been fetched yet, the renderer will warn about "unrecognised format" images. Pull LFS objects before rendering: + +```bash +git lfs pull +``` + +## Usage + +Run from the repository root so that all doc sources are available inside the container. + +### HTML output + +```bash +docker run --rm -v "$(pwd)":/documents xfsc-asciidoctor \ + asciidoctor -r asciidoctor-diagram path/to/document.adoc +``` + +### PDF output + +```bash +docker run --rm -v "$(pwd)":/documents xfsc-asciidoctor \ + asciidoctor-pdf -r asciidoctor-diagram path/to/document.adoc +``` + +### Example — render the architecture doc + +```bash +docker run --rm -v "$(pwd)":/documents xfsc-asciidoctor \ + asciidoctor -r asciidoctor-diagram \ + ./federated-catalogue/src/docs/architecture/catalogue-architecture.adoc +``` + +Note that the path is relative to the directory you run the command from (pwd). +The above example assumes you're in the repository root. +Adjust the path accordingly if you're running it from somewhere else. + +The rendered file will be written next to the source (e.g. `catalogue-architecture.html`). + +## What's included + +| Component | Purpose | +|---|---| +| asciidoctor | AsciiDoc → HTML renderer | +| asciidoctor-pdf | AsciiDoc → PDF renderer | +| asciidoctor-diagram | Processes embedded diagram blocks (Mermaid, PlantUML, etc.) | +| @mermaid-js/mermaid-cli (`mmdc`) | Renders Mermaid diagrams to SVG/PNG | +| Chromium | Headless browser used by Mermaid CLI via Puppeteer | \ No newline at end of file