chore: promote dev to main

.gitignore

@@ -16,3 +16,6 @@ _diagrams/.$*
 
 # the publisher writes this to the root on every build
 Requirements-fromNarrative.json
+
+# editor settings
+.vscode/

TODO.md

@@ -1,21 +1,25 @@
 # Pendientes
 
-Este archivo reúne lo que el repositorio tiene marcado como pendiente. Cada entrada dice dónde vive, para que al resolverla se borren las dos cosas a la vez, la marca en su archivo y la línea de aquí.
+Este archivo reúne lo que el repositorio tiene marcado como pendiente. Cada entrada dice a qué parte de la guía afecta, para que al resolverla se actualice esa parte y se borre la línea de aquí.
 
 ## Marcas en las páginas
 
-1. **Rehacer en draw.io los diagramas de la sección 2.2.** Los tres diagramas de las pestañas son un mock en PlantUML y deben quedar como la Figura 2-1. En `input/pagecontent/volume-1-actors.md:8`.
-2. **Alinear el tratamiento de la aplicación del paciente.** Figura como cliente en el Authorization Server y puede ser un cliente confidencial cuando tiene backend propio, y de eso depende si se la considera miembro y qué le exigen ATNA, CT y la auditoría. En `input/pagecontent/volume-1-groupings.md:31` (requiere discusión previa).
-3. **Comprobar con pruebas qué guarda el registro de mensajes de X-Road.** Hay que saber si conserva los mensajes completos y cómo se configura, y reflejar el resultado en esa opción y en las decisiones de política de la sección 2.6. En `input/pagecontent/volume-1-options.md:37`.
+1. **Rehacer en draw.io los diagramas de la sección 2.2.** Los tres diagramas de las pestañas son un mock en PlantUML y deben quedar como la Figura 2-1. Afecta a las figuras de la sección 2.2 en `input/pagecontent/volume-1-actors.md`.
+2. **Alinear el tratamiento de la aplicación del paciente.** Figura como cliente en el Authorization Server y puede ser un cliente confidencial cuando tiene backend propio, y de eso depende si se la considera miembro y qué le exigen ATNA, CT y la auditoría. Afecta a la sección 2.4 en `input/pagecontent/volume-1-groupings.md` (requiere discusión previa).
+3. **Comprobar con pruebas qué guarda el registro de mensajes de X-Road.** Hay que saber si conserva los mensajes completos y cómo se configura, y reflejar el resultado en esa opción y en las decisiones de política de la sección 2.6. Afecta a la Opción de Canal de Interconexión en `input/pagecontent/volume-1-options.md`.
+4. **Definir la auditoría de una aplicación del paciente sin backend propio.** La aplicación ya opera casi como un miembro, pero puede no tener backend propio y hacer todo su flujo en el navegador de la persona, y por eso la sección 2.4 la deja por ahora fuera de ATNA y de CT. Hay que probar si ese flujo tiene limitantes y, si no las tiene, auditarla como a un miembro más. Va junto con el punto 2, porque los dos deciden si la aplicación se trata como miembro. Afecta a la Tabla 3-1 y a la auditoría de `input/pagecontent/volume-2.md`.
 
 ## Páginas declaradas pero no escritas
 
-La estructura completa de la guía ya está en `sushi-config.yaml`, comentada hasta que cada parte exista. Son treinta páginas repartidas así.
+La estructura completa de la guía ya está en `sushi-config.yaml`, comentada hasta que cada parte exista. Son diecinueve páginas repartidas así.
 
-1. **El Volumen 2 entero**, once páginas contando su portada y el índice de transacciones, con ITI-65, ITI-67, ITI-68, ITI-83, ITI-104, ITI-90 y las tres transacciones propias HIX-1, HIX-2 y HIX-3, desde la línea 69.
-2. **La sección de conformidad**, seis páginas con las ediciones soportadas, la matriz de requisitos, las desviaciones respecto a IHE, las extensiones propias y los artefactos, desde la línea 107.
+1. **Las consideraciones entre perfiles y despliegue del Volumen 1**, una página, en la línea 67.
+2. **El Volumen 3 entero**, ocho páginas contando su portada, con los metadatos del puntero, la identidad del paciente, los recursos del directorio, los claims de autorización, el consentimiento y las etiquetas de seguridad, los registros de auditoría y la terminología, desde la línea 83.
+3. **La sección de conformidad**, seis páginas con las ediciones soportadas, la matriz de requisitos, las desviaciones respecto a IHE, las extensiones propias y los artefactos, desde la línea 99.
+4. **Tres apéndices**, la justificación del diseño, las referencias y el historial de cambios, desde la línea 115.
+5. **La página de descargas**, una página, en la línea 121.
 
-Nota: las dependencias en el archivo de sushi están comentadas para evitar problemas con el CI de despliegue durante la escritura de estas páginas. En el release formal se descomentaran y se hará la integration completa a la guía.
+Nota: las dependencias del archivo de sushi ya están activas. Queda la integración completa de sus artefactos en la guía para el release formal.
 
 ## Capacidades aplazadas a una versión posterior
 

_diagrams/hix-2-hix-1-recorrido.plantuml

@@ -0,0 +1,118 @@
+@startuml hix-2-hix-1-recorrido
+skinparam shadowing false
+skinparam backgroundColor white
+skinparam defaultFontName Verdana
+skinparam defaultFontSize 12
+skinparam defaultFontColor #222222
+skinparam sequenceMessageAlign center
+skinparam sequenceArrowThickness 1.75
+skinparam ParticipantPadding 4
+skinparam BoxPadding 4
+skinparam RoundCorner 8
+
+skinparam sequence {
+  ArrowColor #333333
+  LifeLineBorderColor #B5B5B5
+  ParticipantBorderColor #666666
+  ParticipantBackgroundColor white
+  ParticipantFontSize 12
+  BoxBorderColor #D6D6D6
+  BoxBackgroundColor #F6F7F8
+  BoxFontColor #555555
+  BoxFontSize 11
+  GroupBorderColor #B5B5B5
+  GroupBorderThickness 1
+  GroupHeaderFontColor #555555
+  GroupHeaderFontStyle plain
+  GroupFontColor #555555
+  GroupFontStyle plain
+  GroupFontSize 11
+  DividerBackgroundColor white
+  DividerBorderColor #C62828
+  DividerFontColor #C62828
+  DividerFontSize 11
+}
+
+skinparam legend {
+  FontSize 11
+  BackgroundColor white
+  BorderColor #D6D6D6
+}
+
+skinparam note {
+  BackgroundColor #EAF5EC
+  BorderColor #9CC9A6
+}
+
+hide footbox
+
+' Colores de los tokens
+!$SOL = "<color:#2E6DB4><b>token del solicitante</b></color>"
+!$ACT = "<color:#6B6B6B><b>token de actor</b></color>"
+!$INT = "<color:#2E8540><b>token mediado</b></color>"
+!$NO = "#C62828"
+
+' La audiencia de cada token, dicha en claro
+!$AUD_SOL = "<color:#2E6DB4><size:11>audiencia: la infraestructura central</size></color>"
+!$AUD_ACT = "<color:#6B6B6B><size:11>audiencia: el Authorization Server</size></color>"
+!$AUD_INT = "<color:#2E8540><size:11><b>audiencia: solo el Laboratorio</b></size></color>"
+
+box "Miembro solicitante"
+  participant "Hospital" as H
+end box
+
+box "Infraestructura central"
+  participant "Record Locator\nService (RLS)" as RLS
+  participant "Authorization\nServer" as AS
+end box
+
+box "Custodio"
+  participant "Laboratorio" as LAB
+end box
+
+box "Otro custodio"
+  participant "Clínica" as CLI
+end box
+
+H -[#2E6DB4]> RLS : (1) pide el documento [ITI-68]\ncon el $SOL\n$AUD_SOL
+
+RLS -[#2E6DB4]> AS : (2) comprueba [ITI-102]\nel $SOL
+AS --> RLS : sigue vigente
+
+group Opcional [si no tiene un token de actor vigente]
+  RLS -[#6B6B6B]> AS : (3) pide su $ACT [ITI-71]
+  AS -[#6B6B6B]-> RLS : $ACT\n$AUD_ACT
+end
+
+group Intercambio de tokens [HIX-1]
+  RLS -> AS : (4) pide un token para acceder al Laboratorio\n<b>en nombre del solicitante</b>\n<b>presenta</b>: el $SOL y el $ACT
+
+  AS -[#2E8540]-> RLS : $INT\n<color:#2E8540><size:11>permite al RLS actuar en nombre del solicitante</size></color>\n$AUD_INT
+end
+
+RLS -[#2E8540]> LAB : (5) pide el documento [ITI-68]\ncon el $INT
+
+note left of LAB
+  (6) valida el token con las JWKs
+  y lo acepta: su audiencia
+  es el Laboratorio
+end note
+
+LAB --> RLS : documento
+RLS --> H : (7) documento
+
+== Lo que nunca ocurre ==
+
+H -[$NO]->x LAB : <color:$NO>el solicitante no llega a ningún custodio por su cuenta:</color>\n<color:$NO>solo a través del RLS, que es quien usa un</color> $INT
+
+RLS -[$NO]->x H : <color:$NO>el</color> $INT\n<color:$NO>nunca llega al solicitante</color>
+
+RLS -[$NO]->x LAB : <color:$NO>el</color> $SOL <color:$NO>y el</color> $ACT\n<color:$NO>nunca llegan a un custodio:</color>\n<color:$NO>su audiencia no es ningún custodio</color>
+
+RLS -[$NO]->x CLI : <color:$NO>el</color> $INT <color:$NO>no vale ante la Clínica:</color>\n<color:$NO>su audiencia es solo el Laboratorio</color>
+
+legend bottom
+  La <b>audiencia</b> de un token dice ante quién vale. Cualquier otro lo rechaza.
+endlegend
+
+@enduml

_diagrams/hix-2-hix-1.plantuml

@@ -0,0 +1,24 @@
+@startuml hix-2-hix-1
+skinparam shadowing false
+skinparam defaultFontName Verdana
+skinparam defaultFontSize 11
+skinparam sequenceMessageAlign center
+skinparam ParticipantPadding 8
+skinparam sequence {
+  ArrowColor #333333
+  LifeLineBorderColor #999999
+  ParticipantBorderColor #555555
+  ParticipantBackgroundColor white
+  GroupBorderColor #999999
+}
+
+participant "Record Locator\nService" as RLS
+participant "Authorization\nServer" as AS
+
+opt sin token de actor vigente
+  RLS -> AS : [ITI-71] Get Access Token\n(client_credentials, token propio del RLS)
+  AS --> RLS : token de actor (aud = Authorization Server)
+end
+RLS -> AS : [HIX-1] Mediated Token Exchange\n(subject_token, actor_token, resource, scope)
+AS --> RLS : JWT (aud = destino, sub = solicitante,\nact = RLS, vida ≤ 120 s)
+@enduml

_diagrams/hix-2-hix-2.plantuml

@@ -0,0 +1,33 @@
+@startuml hix-2-hix-2
+skinparam shadowing false
+skinparam defaultFontName Verdana
+skinparam defaultFontSize 11
+skinparam sequenceMessageAlign center
+skinparam ParticipantPadding 8
+skinparam sequence {
+  ArrowColor #333333
+  LifeLineBorderColor #999999
+  ParticipantBorderColor #555555
+  ParticipantBackgroundColor white
+  ActorBorderColor #555555
+  ActorBackgroundColor white
+  GroupBorderColor #999999
+}
+
+actor "Persona" as P
+participant "Aplicación\ndel paciente" as APP
+participant "Authorization\nServer" as AS
+participant "Master Patient\nIndex" as PMIR
+
+APP -> AS : [HIX-2] Petición de autorización\n(response_type = code, resource = RLS,\nlaunch/patient, PKCE S256)
+AS <-> P : autenticación y consentimiento
+AS -> PMIR : [ITI-83] identidad verificada
+PMIR --> AS : identidad maestra
+AS --> APP : redirección (code, state)
+APP -> AS : [HIX-2] Petición de token\n(authorization_code, code_verifier)
+AS --> APP : token (aud = RLS), id_token,\nrefresh_token (con offline_access), patient
+opt renovación, fuera de ITI-71 (token vencido y refresh token vigente)
+  APP -> AS : [HIX-2] Petición de token (refresh_token)
+  AS --> APP : token nuevo, mismo patient, sin ITI-83
+end
+@enduml

_diagrams/hix-actores-hospital.plantuml

@@ -29,7 +29,7 @@ rectangle "Hospital (consumidor)" as HOSP #DAE8FC {
   rectangle "MHD Document Consumer" <<inner>> as H2
   rectangle "PIXm / PDQm Consumer" <<inner>> as H3
 }
-rectangle "Authorization Server (STS)" as STS #F5F5F5 {
+rectangle "Authorization Server" as STS #F5F5F5 {
   rectangle "IUA Authorization Server" <<inner>> as STS1
   rectangle "OpenID Provider" <<inner>> as STS2
   rectangle "PIXm Consumer" <<inner>> as STS3
@@ -38,16 +38,20 @@ rectangle "Record Locator Service (Mediador)" as RLS #D5E8D4 {
   rectangle "IUA Resource Server" <<inner>> as RLS1
   rectangle "IUA Authorization Client" <<inner>> as RLS0
   rectangle "MHD Document Responder" <<inner>> as RLS2
-  rectangle "MHD Document Consumer (delegated)" <<inner>> as RLS3
-  rectangle "PIXm / PDQm Consumer (delegated)" <<inner>> as RLS4
+  rectangle "MHD Document Consumer" <<inner>> as RLS3
+  rectangle "PIXm Consumer" <<inner>> as RLS4
+}
+rectangle "Master Patient Index" as MPI #FFF2CC {
+  rectangle "PIXm Manager" <<inner>> as MPI1
+  rectangle "PDQm Supplier" <<inner>> as MPI2
 }
 rectangle "Custodio" as CUST #FFE6CC {
   rectangle "IUA Resource Server" <<inner>> as CUST1
-  rectangle "MHD Document Responder" <<inner>> as CUST2
+  rectangle "Servicio que aloja el contenido" <<inner>> as CUST2
 }
 H1 --> STS1 : [ITI-71] Get Access Token\natención: purpose_of_use = TREAT\nemergencia: purpose_of_use = ETREAT
-H3 --> RLS4 : atención: [ITI-83] resuelve su identificador local\nemergencia: [ITI-78] busca por datos demográficos
-H2 --> RLS2 : [ITI-67] Find Document References\n[ITI-68] Retrieve Document
-STS1 <-- RLS0 : [HIX-1] Custodian Token Exchange
-RLS3 --> CUST2 : [ITI-68] Retrieve Document\ntoken derivado, aud = custodio
+H3 --> MPI : atención: [ITI-83] resuelve su identificador local\nemergencia: [ITI-78] busca por datos demográficos
+H2 --> RLS2 : [ITI-66] Find Document Lists\n[ITI-67] Find Document References\n[ITI-68] Retrieve Document
+STS1 <-- RLS0 : [HIX-1] Mediated Token Exchange
+RLS3 --> CUST2 : [ITI-68] Retrieve Document\ntoken mediado, aud = custodio
 @enduml

_diagrams/hix-actores-laboratorio.plantuml

@@ -28,23 +28,29 @@ rectangle "Laboratorio (custodio)" as LAB #DAE8FC {
   rectangle "IUA Authorization Client" <<inner>> as L1
   rectangle "PIXm Patient Identity Source" <<inner>> as L2
   rectangle "MHD Document Source" <<inner>> as L3
-  rectangle "MHD Document Responder" <<inner>> as L4
+  rectangle "Servicio que aloja el contenido" <<inner>> as L4
   rectangle "IUA Resource Server" <<inner>> as L5
 }
-rectangle "Authorization Server (STS)" as STS #F5F5F5 {
+rectangle "Authorization Server" as STS #F5F5F5 {
   rectangle "IUA Authorization Server" <<inner>> as STS1
   rectangle "OpenID Provider" <<inner>> as STS2
   rectangle "PIXm Consumer" <<inner>> as STS3
 }
+rectangle "Master Patient Index" as MPI #FFF2CC {
+  rectangle "PIXm Manager" <<inner>> as MPI1
+}
+rectangle "Document Registry" as DR #E1D5E7 {
+  rectangle "MHD Document Recipient" <<inner>> as DR1
+}
 rectangle "Record Locator Service (Mediador)" as RLS #D5E8D4 {
   rectangle "IUA Authorization Client" <<inner>> as RLS0
   rectangle "IUA Resource Server" <<inner>> as RLS1
-  rectangle "MHD Document Consumer (delegated)" <<inner>> as RLS3
+  rectangle "MHD Document Consumer" <<inner>> as RLS3
 }
 L1 --> STS1 : [ITI-71] Get Access Token\npurpose_of_use = TREAT
-L2 --> RLS : [ITI-104] Patient Identity Feed\nidentidad local + identificador nacional
-L3 --> RLS : [ITI-65] Provide Document Bundle\npuntero con custodio y securityLabel
-STS1 <-u- RLS0 : [HIX-1] Custodian Token Exchange
-RLS3 --> L4 : [ITI-68] Retrieve Document\ntoken derivado, aud = laboratorio\ncuando otro miembro recupera
+L2 --> MPI1 : [ITI-104] Patient Identity Feed\nidentidad local + identificador nacional
+L3 --> DR1 : [ITI-65] Provide Document Bundle\npuntero con custodio y securityLabel
+STS1 <-u- RLS0 : [HIX-1] Mediated Token Exchange
+RLS3 --> L4 : [ITI-68] Retrieve Document\ntoken mediado, aud = laboratorio\ncuando otro miembro recupera
 L4 -[hidden]-> RLS1
 @enduml

_diagrams/hix-actores-paciente.plantuml

@@ -28,7 +28,7 @@ rectangle "Aplicación del paciente" as APP #DAE8FC {
   rectangle "IUA Authorization Client" <<inner>> as APP1
   rectangle "MHD Document Consumer" <<inner>> as APP2
 }
-rectangle "Authorization Server (STS)" as STS #F5F5F5 {
+rectangle "Authorization Server" as STS #F5F5F5 {
   rectangle "IUA Authorization Server" <<inner>> as STS1
   rectangle "OpenID Provider" <<inner>> as STS2
   rectangle "PIXm Consumer" <<inner>> as STS3
@@ -37,15 +37,15 @@ rectangle "Record Locator Service (Mediador)" as RLS #D5E8D4 {
   rectangle "IUA Resource Server" <<inner>> as RLS1
   rectangle "IUA Authorization Client" <<inner>> as RLS0
   rectangle "MHD Document Responder" <<inner>> as RLS2
-  rectangle "MHD Document Consumer (delegated)" <<inner>> as RLS3
-  rectangle "PIXm / PDQm Consumer (delegated)" <<inner>> as RLS4
+  rectangle "MHD Document Consumer" <<inner>> as RLS3
+  rectangle "PIXm Consumer" <<inner>> as RLS4
 }
 rectangle "Custodio" as CUST #FFE6CC {
   rectangle "IUA Resource Server" <<inner>> as CUST1
-  rectangle "MHD Document Responder" <<inner>> as CUST2
+  rectangle "Servicio que aloja el contenido" <<inner>> as CUST2
 }
-APP1 --> STS1 : [HIX-2] Patient Application Launch\npurpose_of_use = PATRQT, FAMRQT o PWATRNY\npaciente = identidad maestra
+APP1 --> STS1 : [HIX-2] Patient Application Launch\npurpose_of_use = PATRQT\npaciente = identidad maestra
 APP2 --> RLS2 : [ITI-67] Find Document References\n[ITI-68] Retrieve Document\ntoken aud = RLS, confinado al paciente
-STS1 <-- RLS0 : [HIX-1] Custodian Token Exchange
-RLS3 --> CUST2 : [ITI-68] Retrieve Document\ntoken derivado, aud = custodio
+STS1 <-- RLS0 : [HIX-1] Mediated Token Exchange
+RLS3 --> CUST2 : [ITI-68] Retrieve Document\ntoken mediado, aud = custodio
 @enduml

_diagrams/hix-delegacion.plantuml

@@ -34,9 +34,9 @@ rectangle "Custodios" as CUSTODIOS #F4F4F4 {
   rectangle "Custodio B" as B
 }
 
-M --> RLS : token del miembro\naud = RLS
+M --> RLS : token del miembro\naud = Resource Servers centrales
 RLS --> AS : intercambio [HIX-1]\nresource = custodio X
-AS --> RLS : token derivado\naud = custodio X\nsub = miembro\nact = RLS
+AS --> RLS : token mediado\naud = custodio X\nsub = miembro\nact = RLS
 RLS --> REG : token\naud = Document Registry
 RLS --> A : token\naud = Custodio A
 RLS --> B : token\naud = Custodio B

_diagrams/hix-flujo-identidad.plantuml

@@ -13,27 +13,21 @@ skinparam sequence {
 }
 
 participant "Fuente autoritativa\n(p. ej. EDUS)" as SRC
-participant "Registro de\nidentidad maestra" as PMIR
-participant "Record Locator\nService" as RLS
+participant "Master Patient\nIndex" as MPI
 participant "Custodio" as K
 participant "Consumidor" as C
 
 == Identidad maestra ==
-SRC -> PMIR : [ITI-93] Mobile Patient Identity Feed\n(identidad verificada)
-PMIR -> PMIR : crea o actualiza\nla identidad maestra
-PMIR --> SRC : 200
+SRC -> MPI : [ITI-93] Mobile Patient Identity Feed\n(identidad verificada)
+MPI -> MPI : crea o actualiza\nla identidad maestra
+MPI --> SRC : 200
 
 == Identidad local de un miembro ==
-K -> RLS : [ITI-104] Patient Identity Feed\n(Patient local + identificador comunitario)
-RLS -> RLS : dominio = organización del token
-RLS -> PMIR : [ITI-104] (delegado)
-PMIR -> PMIR : vincula la identidad local\ncon la identidad maestra
-PMIR --> RLS : 200, o 422 si la persona\nno existe en la comunidad
-RLS --> K : resultado
+K -> MPI : [ITI-104] Patient Identity Feed FHIR\n(Patient local + identificador nacional)
+MPI -> MPI : dominio = organización del token\nvincula la identidad local\ncon la identidad maestra
+MPI --> K : 200, o rechazo por defecto si la persona\nno tiene identidad maestra
 
 == Resolución ==
-C -> RLS : [ITI-83] Cross-reference Query\n(identificador local o comunitario)
-RLS -> PMIR : [ITI-83] (delegado)
-PMIR --> RLS : identificadores de la persona
-RLS --> C : identificadores permitidos\npor la política
+C -> MPI : [ITI-83] Cross-reference Query\n(identificador local o nacional)
+MPI --> C : solo la identidad maestra
 @enduml