changes to the Notiication obligation: to as Array, support for Decis…

.github/workflows/jekyll-gh-pages.yml

@@ -26,6 +26,13 @@ jobs:
 
       - name: Convert working version of Authz API 1.0 to rfc xml
         run: kramdown-rfc2629 api/authorization-api-1_0.md > api/authorization-api-1_0.xml
+      - name: Fix RFC9110 xrefs in generated XML
+        run: |
+          echo "Checking for RFC9110 xrefs in api/authorization-api-1_0.xml"
+          grep -n 'target="RFC9110"' api/authorization-api-1_0.xml || echo "none found"
+          # Replace any <xref target="RFC9110" section="...">text</xref> with a ulink to the RFC HTML+fragment.perl -0777 -pe 's#<xref\s+([^>]*?)target="RFC9110"([^>]*?)section="([^"]+)"([^>]*?)>(.*?)</xref>#<ulink url="https://www.rfc-editor.org/rfc/rfc9110.html#section-$3">$5</ulink>#igs' -i api/authorization-api-1_0.xml
+          echo "Replacement done. Sample lines:"
+          grep -n 'rfc9110.html' api/authorization-api-1_0.xml | head -n 5 || true
       - name: Render Authz API 1.0 HTML
         run: xml2rfc api/authorization-api-1_0.xml --html -o authorization-api-1_0.html
       - name: Render Index HTML (this is the current working draft of the spec)

api/authorization-api-1_0.md

@@ -1394,24 +1394,24 @@ The following table provides an overview of the API endpoints defined in this bi
 
 ### JSON Serialization {#transport-https-json-serialization}
 
-This section specifies the serialization of the information model entities and API schemas defined in this document to the JSON format {{RFC8259}}. The top-level element of all request and response bodies MUST be a JSON object ({{Section 4 of RFC8259}}). Implementations SHOULD also adhere to the security recommendations in JSON Payload Considerations ({{security-json}}).
+This section specifies the serialization of the information model entities and API schemas defined in this document to the JSON format {{RFC8259}}. The top-level element of all request and response bodies MUST be a JSON object (Section 4 of {{RFC8259}}). Implementations SHOULD also adhere to the security recommendations in JSON Payload Considerations ({{security-json}}).
 
 The data types defined in this specification are mapped to JSON types as follows:
 
 Object:
-: Represented as a JSON object ({{Section 4 of RFC8259}}). The values of its members can be any valid JSON value as defined in {{Section 3 of RFC8259}}, including other objects and arrays, unless specified otherwise.
+: Represented as a JSON object (Section 4 of {{RFC8259}}). The values of its members can be any valid JSON value as defined in Section 3 of {{RFC8259}}, including other objects and arrays, unless specified otherwise.
 
 Array:
-: Represented as a JSON array ({{Section 5 of RFC8259}}).
+: Represented as a JSON array (Section 5 of {{RFC8259}}).
 
 String:
-: Represented as a JSON string ({{Section 7 of RFC8259}}).
+: Represented as a JSON string (Section 7 of {{RFC8259}}).
 
 Integer:
-: Represented as a JSON number ({{Section 6 of RFC8259}}). Note the recommendation in {{security-json}} to not encode values that exceed IEEE 754 double-precision.
+: Represented as a JSON number (Section 6 of {{RFC8259}}). Note the recommendation in {{security-json}} to not encode values that exceed IEEE 754 double-precision.
 
 Boolean:
-: Represented as the JSON literals `true` or `false` ({{Section 3 of RFC8259}}).
+: Represented as the JSON literals `true` or `false` (Section 3 of {{RFC8259}}).
 
 If a required attribute in the information model is omitted, the server MUST return a "Bad Request" error, as defined in {{error-responses}}.
 

profiles/authzen-obligations-profile-1_0.md

@@ -289,13 +289,13 @@ The following is a non-normative example of a `step-up` obligation:
 
 ## notification {#obligation-notification}
 
-The `notification` obligation requires the PEP to transmit a message to a destination. This specification is transport-agnostic: the destination MAY be an email address, a phone number, a pub/sub topic, a webhook, or any other implementation-meaningful identifier.
+The `notification` obligation requires the PEP to transmit a message to one or more destinations. This specification is transport-agnostic: a destination MAY be an email address, a phone number, a pub/sub topic, a webhook, or any other implementation-meaningful identifier.
 
 Obligation-specific members:
 
 to:
 
-: REQUIRED. A String. An implementation-specific identifier for the destination of the notification (e.g., an email address such as `manager@example.com`, or a queue/topic name). The identifier MUST be unique and meaningful within the deploying implementer's environment.
+: REQUIRED. A JSON array of Strings, each an implementation-specific identifier for a destination of the notification (e.g., an email address such as `manager@example.com`, or a queue/topic name). The array MUST contain at least one element. Each identifier MUST be unique and meaningful within the deploying implementer's environment. The PEP MUST transmit the notification to every destination listed in the array; the obligation is satisfied only when transmission to all listed destinations succeeds. If transmission to any listed destination fails, the PEP cannot comply with the obligation, and, per {{non-compliance}}, MUST treat the overall response as a DENY, regardless of whether the original `decision` was `true` or `false`.
 
 body:
 
@@ -305,21 +305,38 @@ topic:
 
 : OPTIONAL. A String. A short, high-level subject or purpose for the message, e.g., an email subject line, or a routing topic identifier for a pub/sub transport.
 
-The following is a non-normative example of a `notification` obligation:
+If the AuthZEN request that gave rise to this decision included a `context.decision_subject` element -- an implementation-defined identifier for the entity the authorization request pertains to, which is typically distinct from the requesting `subject` (for example, the patient whose record a doctor is requesting access to) -- the PDP MUST include that identifier as an additional destination in the `to` array of every `notification` obligation it issues for that decision, so that the decision subject is notified alongside any other configured destinations.
+
+The following is a non-normative example of a `notification` obligation with a single destination:
 
 ~~~ json
 {
   "type": "notification",
   "id": "obl-2",
   "properties": {
-    "to": "manager@example.com",
+    "to": ["manager@example.com"],
     "topic": "Unauthorized access attempt",
     "body": "User jdoe attempted to access patient record 4471 outside of business hours."
   }
 }
 ~~~
 {: #fig-obligation-notification title="Non-normative example of a notification obligation"}
 
+The following is a non-normative example of a `notification` obligation issued for a request that included a `context.decision_subject` of `patient-4471`, in addition to a statically configured destination:
+
+~~~ json
+{
+  "type": "notification",
+  "id": "obl-2b",
+  "properties": {
+    "to": ["manager@example.com", "patient-4471"],
+    "topic": "Medical record accessed",
+    "body": "User jdoe accessed patient record 4471 under emergency access provisions."
+  }
+}
+~~~
+{: #fig-obligation-notification-decision-subject title="Non-normative example of a notification obligation with a decision_subject destination"}
+
 ## session_termination {#obligation-session-termination}
 
 The `session_termination` obligation requires the PEP to initiate whatever flow is necessary to terminate all active sessions belonging to the specified subject, including, where the deployment spans a federation, sessions established at other participating parties (e.g., via {{OIDC-LOGOUT}} front-channel or back-channel logout mechanisms, or via a {{SSF}} implementation).
@@ -492,7 +509,7 @@ The following is a non-normative example of a Search response listing three cand
           "type": "notification",
           "id": "obl-2",
           "properties": {
-            "to": "manager@example.com",
+            "to": ["manager@example.com"],
             "topic": "Protected Document Access",
             "body": "User AliceSmith attempted to read Document "doc-2" from Europe."
           }