Lint AsciiDoc links (#252)

* Lint AsciiDoc links

* Prefix absolute paths with git root

* Ignore hashes

* Fix typo and check for existence

* Eliminate docsdir

* Exclude images but include other URLs

* Strip fragments

* Output path

* Fix path substitution bug

* Only verify http links

* Try GET if HEAD fails

* Try OPTIONS before HEAD

* Add exceptions

* Fix dots and warn

* Use globs

* Replace welcome package links

* Fix dead links

* Rearrange actions

* Remove references to epa branch

Author: Johennes

.github/actions/lint-links/action.yml

@@ -0,0 +1,64 @@
+name: Lint Links
+
+runs:
+  using: "composite"
+  steps:
+    - name: Verify links
+      shell: bash
+      run: |
+        function warn {
+          >&2 echo -e "\033[0;33m$@\033[0m"
+        }
+
+        function err {
+          >&2 echo -e "\033[0;31m$@\033[0m"
+        }
+
+        rc=0
+
+        while read -r file; do
+          echo "Checking $file"
+
+          pushd "$(dirname "$file")" > /dev/null
+
+          while read -r location; do
+            echo "Checking location $location"
+
+            if [[ "$location" == http* ]]; then
+              if ! curl -X OPTIONS --silent --fail "$location" 2>&1 > /dev/null; then
+                if ! curl --head --silent --fail "$location" 2>&1 > /dev/null; then
+                  if ! curl --silent --fail "$location" 2>&1 > /dev/null; then
+                    # Some URLs are examples or the endpoints helpfully support neither OPTIONS nor HEAD
+                    if [[ "$location" = *example* ]] || \
+                       [[ "$location" = https://idp-ref.app.ti-dienste.de/auth* ]] || \
+                       [[ "$location" = https://idp.app.ti-dienste.de/auth* ]] || \
+                       [[ "$location" = https://idp-ref.app.ti-dienste.de/token* ]] || \
+                       [[ "$location" = https://idp.app.ti-dienste.de/token* ]] || \
+                       [[ "$location" = https://idp-ref.app.ti-dienste.de ]];
+                    then
+                      warn "$file references non-verifiable location $location"
+                    else
+                      err "$file references non-existent location $location"
+                      rc=1
+                    fi
+                  fi
+                fi
+              fi
+            else
+              # Strip fragments and prefix absolute paths with repo root
+              path=${location/\#*/}
+              if [[ "$path" == /* ]]; then
+                path=$(git rev-parse --show-toplevel)/$path
+              fi
+
+              if [[ ! -e "$path" ]]; then
+                err "$file references non-existent location $location"
+                rc=1
+              fi
+            fi
+          done < <(grep -hoE 'link:[^\[]*|image::?[^\[]*|https?://[^\["[:space:]]*' "$(basename "$file")" | grep -v '^image:' | sed -E "s/^link:+//g")
+
+          popd > /dev/null
+        done < <(find . -type f -name "*.adoc")
+
+        exit $rc

.github/workflows/lint.yml

@@ -5,11 +5,10 @@ on:
   push:
     branches:
     - main
-    - tim-epa-fdv
   workflow_dispatch:
 
 jobs:
-  asciidoc:
+  asciidoc-images:
     runs-on: ubuntu-latest
 
     steps:
@@ -19,6 +18,16 @@ jobs:
       - name: Lint
         uses: gematik/github-image-actions/.github/actions/[email protected]
 
+  asciidoc-links:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Lint
+        uses: ./.github/actions/lint-links
+
   drawio:
     runs-on: ubuntu-latest
 

README.adoc

@@ -14,8 +14,8 @@ ifndef::env-github[:source-style: source]
 
 image::meta/gematik_logo.svg[gematik,width="70%"]
 
-image:https://github.com/gematik/api-ti-messenger/actions/workflows/lint.yml/badge.svg?branch=tim-epa-fdv[link="https://github.com/gematik/api-ti-messenger/actions/workflows/lint.yml"]
-image:https://github.com/gematik/api-ti-messenger/actions/workflows/generate-images.yml/badge.svg?branch=tim-epa-fdv[link="https://github.com/gematik/api-ti-messenger/actions/workflows/generate-images.yml"]
+image:https://github.com/gematik/api-ti-messenger/actions/workflows/lint.yml/badge.svg[link="https://github.com/gematik/api-ti-messenger/actions/workflows/lint.yml"]
+image:https://github.com/gematik/api-ti-messenger/actions/workflows/generate-images.yml/badge.svg[link="https://github.com/gematik/api-ti-messenger/actions/workflows/generate-images.yml"]
 
 image:https://img.shields.io/badge/Release%20Notes-v1.1.1-red?style=plastic&logo=github&logoColor=red[link="ReleaseNotes.md"] +
 image:https://img.shields.io/badge/I_TiMessengerContactManagement-v1.0.1-blue?style=plastic&logo=github&logoColor=blue[link=/src/openapi/TiMessengerContactManagement.yaml"] +
@@ -101,11 +101,10 @@ TI-Messenger Dokumentation
 │   └──── link:images/generated[generated] (draw.io & PlantUML gerenderte Bilder)
 ├─ link:samples[samples] (Codebeispiele, Postman Collections, etc)
 ├─ link:src[src] (Quellen)
-│   ├──── link:src/drawio[drawio] (Quellen der drawio-Diagramme)
-│   ├──── link:src/openapi[openapi] (Schnittstellenbeschreibungen)
-│   │    ├── link:src/openapi/TiMessengerContactManagement.yaml[TiMessengerContactManagement.yaml] (API-Beschreibung der Freigabeliste)
-│   │    └── link:src/openapi/TiMessengerTestTreiber.yaml[TiMessengerTestTreiber.yaml] (API-Beschreibung der TestTreiber-Schnittstelle)
-│   └──── link:src/plantuml[plantuml] (Quellen der plantuml-Diagramme)
+│   ├──── link:src/images[images] (Quellen der draw.io- und PlantUML-Diagramme)
+│   └──── link:src/openapi[openapi] (Schnittstellenbeschreibungen)
+│        ├── link:src/openapi/TiMessengerContactManagement.yaml[TiMessengerContactManagement.yaml] (API-Beschreibung der Freigabeliste)
+│        └── link:src/openapi/TiMessengerTestTreiber.yaml[TiMessengerTestTreiber.yaml] (API-Beschreibung der TestTreiber-Schnittstelle)
 ├── link:README.adoc[README.adoc]
 ├── link:CODE_OF_CONDUCT.md[CODE_OF_CONDUCT.md]
 ├── link:CONTRIBUTING.md[CONTRIBUTING.md]
@@ -130,12 +129,9 @@ Die nachfolgende Tabelle enthält die in der vorliegenden Online Dokumentation r
 |===
 
 == 💡 Onboarding
-Hersteller und Anbieter eines *TI-Messenger-Dienstes* können das von der gematik bereitgestellte https://gematikde.sharepoint.com/:w:/s/PTNeo/EczX7AFGfBdNrCYghzGsHz4BbSoYhV63QMmDCdz7x9zLpg?e=7wG3c[Welcome Package] zum Onboarding nutzen. Dieses Welcome Package ist als "Schritt-für-Schritt"-Anleitung gedacht, um Hersteller und Anbieter beim Onboarding des *TI-Messenger-Dienstes* zu unterstützen.
+Hersteller und Anbieter eines *TI-Messenger-Dienstes* können das von der gematik im https://fachportal.gematik.de/anwendungen/ti-messenger[Fachportal] bereitgestellte Welcome Package zum Onboarding nutzen. Dieses Welcome Package ist als "Schritt-für-Schritt"-Anleitung gedacht, um Hersteller und Anbieter beim Onboarding des *TI-Messenger-Dienstes* zu unterstützen.
 
 == Weiterführende Seiten
-*Anwendungsfälle* +
-link:docs/anwendungsfaelle/TI-Messenger-Anwendungsfaelle.adoc[- Anwendungsfälle] 
-
 *Produkttypen* +
 link:docs/Fachdienst/Fachdienst.adoc[- TI-Messenger-Fachdienst] +
 link:docs/Client/Client.adoc[- TI-Messenger-Client] +
@@ -146,11 +142,9 @@ link:docs/IDP/idp.adoc[- Zentraler IDP-Dienst] +
 link:docs/Primaersystem/Primaersystem.adoc[- Primärsystem] +
 
 *Diverses* +
-https://gematikde.sharepoint.com/:w:/s/PTNeo/EczX7AFGfBdNrCYghzGsHz4BbSoYhV63QMmDCdz7x9zLpg?e=7wG3c[- Welcome Package [DE]] +
-https://gematikde.sharepoint.com/:w:/s/PTNeo/ETwc10F5Ha1KmlM8NEsetl8BtEumSDgu56AK-PNiZ0-e1Q?e=ySZROI[- Welcome Package [EN]] +
-https://gematikde.sharepoint.com/sites/EXTAuthenticator/Freigegebene%20Dokumente/Forms/AllItems.aspx?id=%2Fsites%2FEXTAuthenticator%2FFreigegebene%20Dokumente%2FVer%C3%B6ffentlichte%20Version%20%2D%20gematik%20Authenticator&p=true&ga=1[- gematik Authenticator] +
+https://fachportal.gematik.de/anwendungen/ti-messenger[- TI-Messenger im gematik Fachportal]
+https://fachportal.gematik.de/hersteller-anbieter/komponenten-dienste/authenticator[- Authenticator im gematik Fachportal] +
 https://github.com/gematik/TI-Messenger-Testsuite[- TI-Messenger-Testsuite] +
-link:docs/samples[- Codebeispiele & Requestsammlungen] +
 link:docs/FAQ/FAQ.adoc[- Fragen und Antworten zur aktuellen Spezifikation [FAQ]]
 
 *Referenz-Implementierungen* +

docs/Authenticator/authenticator.adoc

@@ -7,7 +7,6 @@ ifdef::env-github[]
 endif::[]
 
 :imagesdir: ../../images
-:docsdir: ../docs
 :toc: macro
 :toclevels: 6
 :toc-title: Table of Contents
@@ -26,7 +25,7 @@ Für die Authentifizierung mittels Smartcard stellt die gematik einen eigenen *A
 Die Aufgabe des *Authenticators* ist, dass von der *Relying Party* benötigte `ID_TOKEN` mit Zustimmung des Akteurs und nach eingehender Überprüfung dessen Identität am `Authorization-Endpunkt` des *IDP-Dienstes* zu beantragen. Die für die Beantragung des `ID_TOKEN` notwendigen Informationen bekommt der *Authenticator* von der *Relying Party* in der `Authorization Request URL` übergeben. Der von der gematik bereitgestellte *Authenticator* bezieht die Informationen für die notwendige elektronische Signatur im Challenge-Response-Verfahren zum Signieren des `CHALLENGE_TOKEN` von der Smartcard und fordert hierbei den Akteur zur PIN-Eingabe auf. Hierfür nutzt der *Authenticator* die notwendigen Operationen vom Konnektor. Der *Authenticator* fordert im Zusammenhang mit der PIN-Abfrage im selben Dialog die Consent-Freigabe des `USER_CONSENT` durch den Akteur ein, damit dieser durch die PIN-Eingabe seine Willenserklärung abgibt und der Verwendung seiner Daten in diesen `claims` zustimmt. 
 
 == Download und Konfiguration des Authenticators
-Die gematik stellt einen https://gematikde.sharepoint.com/sites/EXTAuthenticator/Freigegebene%20Dokumente/Forms/AllItems.aspx?id=%2Fsites%2FEXTAuthenticator%2FFreigegebene%20Dokumente%2FVer%C3%B6ffentlichte%20Version%20%2D%20gematik%20Authenticator&p=true&ga=1[Authenticator] gemäß *[gemSpec_IDP_Frontend]* bereit, der die Authentisierung eines Akteurs am zentralen *IDP-Dienst* unter Verwendung einer Smartcard (SMC-B / HBA) - in Kombination mit einem Konnektor und einem eHealth-Kartenterminal - ermöglicht. 
+Die gematik stellt einen https://fachportal.gematik.de/hersteller-anbieter/komponenten-dienste/authenticator[Authenticator] gemäß *[gemSpec_IDP_Frontend]* bereit, der die Authentisierung eines Akteurs am zentralen *IDP-Dienst* unter Verwendung einer Smartcard (SMC-B / HBA) - in Kombination mit einem Konnektor und einem eHealth-Kartenterminal - ermöglicht. 
 
 CAUTION: Voraussetzungen für die Nutzung des von der gematik bereitgestellten *Authenticators* sind: +
 - Konnektor, +
@@ -50,6 +49,6 @@ WARNING: Der Parameter `cardType` wird erst mit dem Authenticator 4.4 unterstüt
 TIP: Sollten sich in den Konnektor-Terminals mehrere SMC-Bs befinden, erfolgt ab Version 4.0.0 des *Authenticators* keine Fehlermeldung mehr, sondern es erscheint ein Auswahldialog mit den vorhandenen SMC-Bs und detaillierten Informationen wie z.B. Kartenhalter und iccsn. Der Benutzer hat nun die Möglichkeit eine SMC-B Karte für den weiteren Auth.-Flow auszuwählen oder diesen durch 'Abbrechen' komplett zu beenden.
 
 == Entwickleroption
-Innerhalb der link:https://gematikde.sharepoint.com/sites/EXTAuthenticator/Freigegebene%20Dokumente/Forms/AllItems.aspx?ga=1&id=%2Fsites%2FEXTAuthenticator%2FFreigegebene%20Dokumente%2FVer%C3%B6ffentlichte%20Version%20%2D%20gematik%20Authenticator%2FMockvariante%20Alpha%2DVersion%20%28TEST%2DONLY%29&viewid=19543cfb%2D531c%2D4ed7%2Da8c1%2D1fbd4aa0d244[Entwicklervariante] des *Authenticators* ist ein Mockmodus integriert, der die Verwendung eines Konnektors simulieren kann. Somit können Funktionstests auch ohne physisch vorhandenen Konnektor durchgeführt werden. Diese Funktion soll die Entwicklung mit dem *Authenticator* vereinfachen, da sie neben einem speziellen Mockmodus auch mehr Logging-Möglichkeiten zur Verfügung stellt. Eine Anleitung für den Mockmodus ist link:https://wiki.gematik.de/display/GAKB/Gematik+Authenticator+-+Entwicklervariante+mit+Mockmodus[hier] zu finden.
+Innerhalb der Entwicklervariante des https://fachportal.gematik.de/hersteller-anbieter/komponenten-dienste/authenticator[Authenticators] ist ein Mockmodus integriert, der die Verwendung eines Konnektors simulieren kann. Somit können Funktionstests auch ohne physisch vorhandenen Konnektor durchgeführt werden. Diese Funktion soll die Entwicklung mit dem *Authenticator* vereinfachen, da sie neben einem speziellen Mockmodus auch mehr Logging-Möglichkeiten zur Verfügung stellt. Eine Anleitung für den Mockmodus ist link:https://wiki.gematik.de/display/GAKB/Gematik+Authenticator+-+Entwicklervariante+mit+Mockmodus[hier] zu finden.
 
 Hersteller die den gematik *Authenticator* für eine smartcardbasierte Authentisierung an ihrer Fachanwendung bzw. ihren Fachdienst anbinden möchten, können die link:https://wiki.gematik.de/display/GAKB/Gematik+Authenticator+SDK+Dokumentation[SDK-Dokumentation] der gematik verwenden. Zusätzlich ist der Quellcode des *Authenticator* link:https://github.com/gematik/app-Authenticator[hier] einsehbar.

docs/Fachdienst/Fachdienst.adoc

@@ -45,25 +45,25 @@ Die gematik stellt ein IT Service Management System für die TI-Anbieter zur Ver
 * für die Beantragung der `TI-Provider-Credentials` für die Anbieterschnittstelle des *VZD-FHIR-Directory* und +
 * die Registrierung des *Registrierungs-Dienstes* beim zentralen *IDP-Dienst* der gematik. 
 
-Hierfür ist es erforderlich, dass sich ein Anbieter eines *TI-Messenger-Dienstes* beim TI-ITSM-System ongeboardet wird. Weitere Information sind im https://gematikde.sharepoint.com/:w:/s/PTNeo/EczX7AFGfBdNrCYghzGsHz4BbSoYhV63QMmDCdz7x9zLpg?e=7wG3c[Welcome Package] Schritt 4 zu finden. Das TI-ITSM-System ist unter der folgenden Internetseite erreichbar: https://www.ti-itsm.de
+Hierfür ist es erforderlich, dass sich ein Anbieter eines *TI-Messenger-Dienstes* beim TI-ITSM-System ongeboardet wird. Weitere Information können dem im https://fachportal.gematik.de/anwendungen/ti-messenger[Fachportal] bereitgestelltem Welcome Package (Schritt 4) entnommen werden. Das TI-ITSM-System ist unter der folgenden Internetseite erreichbar: https://www.ti-itsm.de
 
 ==== Zugang zum PKI-Management-System (PMS)
-Um das Signaturzertifikat (welches für die Signatur des `RegService-OpenID-Token` benötigt wird) abrufen zu können, müssen vorher ein Benutzeraccount und Berechtigungen über weitere Service-Requests für die Organisation und den Benutzer (nur Root-User) im TI-ITSM-System beantragt werden. Weitere Informationen sind im link:https://gematikde.sharepoint.com/:w:/s/PTNeo/EczX7AFGfBdNrCYghzGsHz4BbSoYhV63QMmDCdz7x9zLpg?e=7wG3c[Welcome Package] Schritt 6 zu entnehmen. 
+Um das Signaturzertifikat (welches für die Signatur des `RegService-OpenID-Token` benötigt wird) abrufen zu können, müssen vorher ein Benutzeraccount und Berechtigungen über weitere Service-Requests für die Organisation und den Benutzer (nur Root-User) im TI-ITSM-System beantragt werden. Weitere Information können dem im https://fachportal.gematik.de/anwendungen/ti-messenger[Fachportal] bereitgestelltem Welcome Package (Schritt 6) entnommen werden.
 
 Zugang zum PMS:
 
 * RU/TU: https://www-testref.tms.ti-dienste.de
 * PU: https://auth.ti-dienste.de/my.policy
 
 ==== Erstellung des Signaturzertifikates für den Anbeiter
-Für die Signierung eines `RegService-OpenID-Token` durch den *Registrierungs-Dienst* eines *TI-Messenger-Fachdienstes* wird ein Signaturzertifikat der PKI der Telematikinfrastruktur benötigt. Das Zertifikat muss den Typ `C.FD.SIG` und die technische Rolle `oid_tim` haben. Die Beantragung des Signaturzertifikates erfolg über das TI-ITSM-System und ist anschließend über das PMS abrufbar (siehe hierzu https://gematikde.sharepoint.com/:w:/s/PTNeo/EczX7AFGfBdNrCYghzGsHz4BbSoYhV63QMmDCdz7x9zLpg?e=7wG3c[Welcome Package] Schritt 6)
+Für die Signierung eines `RegService-OpenID-Token` durch den *Registrierungs-Dienst* eines *TI-Messenger-Fachdienstes* wird ein Signaturzertifikat der PKI der Telematikinfrastruktur benötigt. Das Zertifikat muss den Typ `C.FD.SIG` und die technische Rolle `oid_tim` haben. Die Beantragung des Signaturzertifikates erfolg über das TI-ITSM-System und ist anschließend über das PMS abrufbar. Weitere Information können dem im https://fachportal.gematik.de/anwendungen/ti-messenger[Fachportal] bereitgestelltem Welcome Package (Schritt 6) entnommen werden.
 
 
 ==== Beantragung der TI-Provider-Credentials am VZD-FHIR-Directory
 Initial muss der Anbieter eines *TI-Messenger-Dienstes* `TI-Provider-Credentials` für den Zugriff auf den Endpunkt `/tim-provider-services` des *FHIR-Proxy* beantragen. Die TIM-Provider-Services-Zugangsdaten erhält der Anbieter über eine weitere Serviceanfrage im gematik TI-ITSM-System. Hierbei muss das Signaturzertifikat bei der Beantragung mit übergeben werden. Dadurch wird sichergestellt, dass nur registrierte Anbieter eines *TI-Messenger-Dienstes* `RegService-OpenID-Token` am `/owner-authenticate`-Endpunkt des *Auth-Service* des *VZD-FHIR-Directory* gegen ein `owner-accesstoken` eintauschen können.
 
 === Bekanntmachung des Registrierungs-Dienstes am zentralen IDP-Dienst
 
-Es besteht bereits eine abgeschlossene Scope-Registrierung am zentralen *IDP-Dienst* für den *TI-Messenger-Dienst*. Daher ist es nur erforderlich ber der gematik eine `client_id` für den *Registrierungs-Dienst* zu beantragen. Hierfür benötigt die gematik im Registrierungsformular die `redirect_uri` des *Registrierungs-Dienstes*, die zu der `client_id` registriert wird. Das Registrierungsformular kann unter [email protected] angefragt werden. Nach der Registrierung erhält der Anbieter die registrierte `client_id` sowie den Download-Endpunkt des Discovery Documentes des zentralen *IDP-Dienstes*. Weitere Informationen sind im https://gematikde.sharepoint.com/:w:/s/PTNeo/EczX7AFGfBdNrCYghzGsHz4BbSoYhV63QMmDCdz7x9zLpg?e=7wG3c[Welcome Package] Schritt 5 zu finden. 
+Es besteht bereits eine abgeschlossene Scope-Registrierung am zentralen *IDP-Dienst* für den *TI-Messenger-Dienst*. Daher ist es nur erforderlich ber der gematik eine `client_id` für den *Registrierungs-Dienst* zu beantragen. Hierfür benötigt die gematik im Registrierungsformular die `redirect_uri` des *Registrierungs-Dienstes*, die zu der `client_id` registriert wird. Das Registrierungsformular kann unter [email protected] angefragt werden. Nach der Registrierung erhält der Anbieter die registrierte `client_id` sowie den Download-Endpunkt des Discovery Documentes des zentralen *IDP-Dienstes*. Weitere Information können dem im https://fachportal.gematik.de/anwendungen/ti-messenger[Fachportal] bereitgestelltem Welcome Package (Schritt 5) entnommen werden.