Apply suggestions from code review

Co-authored-by: Giuseppe De Marco <[email protected]>

docs/en/pid-eaa-issuance.rst

@@ -19,7 +19,7 @@ The relevant entities and interfaces involved in the issuance flow are:
     - *(Q)EAA Issuer*: It represents the issuer of (Q)EAAs. It is composed of:
 
       - OpenID4VCI Component: based on the “OpenID for Verifiable Credential Issuance” specification  `[OIDC4VCI. Draft 13] <https://openid.bitbucket.io/connect/openid-4-verifiable-credential-issuance-1_0.html>`_ to release (Q)EAAs.
-      - Relying Party: It represents the component to authenticate the End-User with the PID. The (Q)EAA Issuer then acts as a verifier and sends a presentation request to the Wallet Instance according to [`OpenID4VP`_]. The Wallet Instance MUST have a valid PID obtained prior to starting a transaction with the (Q)EAA Issuer.
+      - Relying Party: It represents the component to authenticate the User with the PID. The (Q)EAA Issuer acts as a verifier and it sends a presentation request to the Wallet Instance according to [`OpenID4VP`_]. The Wallet Instance MUST have a valid PID obtained prior to starting a transaction with the (Q)EAA Issuer.
 
 
 High-Level PID flow
@@ -34,14 +34,14 @@ The :numref:`fig_High-Level-Flow-ITWallet-PID-Issuance` shows a general architec
 
     PID Issuance - General architecture and high level flow
 
-In the following the main operations are detailed:
+Below a detailed description for each step represented in the previous picture:
 
     0. **Wallet Instance Setup**: the first time the Wallet Instance is started a preliminary setup phase MUST be carried out. It consists of the release of a verifiable proof issued by the Attestation Service provided by the Wallet Provider that asserts the genuineness, the authenticity and the compliance with a trust framework of the Wallet Instance. The verifiable proof binds a public key corresponding to a local private key generated by the Wallet Instance. 
     1. **Obtaining the trusted PID Provider**: the Wallet Instance queries the Trust Anchor to fetch the trusted PID Provider. 
     2. **Obtaining of PID Provider metadata**: the Wallet Instance establishes the trust to the PID Provider according to the Trust Model, obtaining the Metadata that discloses the formats of the PID, the algorithms supported, and any other parameter required for interoperability needs.
     3. **PID request**: following the Authorization Code Flow in `[OIDC4VCI. Draft 13] <https://openid.bitbucket.io/connect/openid-4-verifiable-credential-issuance-1_0.html>`_ the Wallet Instance requests a PID to the PID Provider. A fresh key pairs is generated by the Wallet Instance, the public key is used by PID Provider for the key binding of the PID. The PID Provider checks the Wallet Instance by means of the Wallet Attestation and the Trust Chain related to the Wallet Provider
     4. **End-user authentication**: the PID Provider authenticates the End-User with LoA High, acting as an IAM Proxy to the National eID system. 
-    5. **PID issuance**: once the User authentication with LoA High happens, the User gives their consent, and the PID Provider releases a PID bound to the key material held by the requesting Wallet instance.
+    5. **PID issuance**: once the User authentication with LoA High happens, the User gives their consent, and the PID Provider releases a PID bound to the key material held by the requesting Wallet Instance.
 
 The Wallet Instance Setup phase is described in Section [...]. In the following Section the steps from 1 to 5 are further expanded into more technical detailed steps. 
 
@@ -60,12 +60,12 @@ The :numref:`fig_High-Level-Flow-ITWallet-QEAA-Issuance` shows a general archite
 
     (Q)EAA Issuance - General architecture and high level flow
 
-In the following the main operations are detailed:
+Below the description of the most relevant operations involved in the (Q)EAA issuance:
 
     1. **Obtaining the trusted (Q)EAA Issuer**: the Wallet Instance queries the Trust Anchor to fetch the trusted (Q)EAA Issuer. 
     2. **Obtaining of (Q)EAA Issuer metadata**: the Wallet Instance establishes the trust to the (Q)EAA Issuer according to the Trust Model, obtaining the Metadata that discloses the formats of the (Q)EAA, the algorithms supported, and any other parameter required for interoperability needs.
     3. **(Q)EAA request**: following the Authorization Code Flow in `[OIDC4VCI. Draft 13] <https://openid.bitbucket.io/connect/openid-4-verifiable-credential-issuance-1_0.html>`_ the Wallet Instance requests a (Q)EAA to the (Q)EAA Issuer. A fresh key pairs is generated by the Wallet Instance, the public key is used by (Q)EAA Issuer for the key binding of the (Q)EAA. The (Q)EAA Issuer checks the Wallet Instance by means of the Wallet Attestation and the Trust Chain related to the Wallet Provider
-    4. **End-user authentication**: the (Q)EAA Issuer authenticates the End-User with the PID owned by the User, acting as a verifier (Relying Party). 
+    4. **End-user authentication**: the (Q)EAA Issuer authenticates the User with the PID owned by the User, acting as a verifier (Relying Party). 
     5. **(Q)EAA issuance**: once the User authentication with a valid PID happens, the User gives their consent, and the (Q)EAA Issuer releases a (Q)EAA bound to the key material held by the requesting Wallet Instance.
 
 
@@ -87,11 +87,11 @@ The PID/(Q)EAA Issuance phase is based on the **Authorization Code Flow** with *
 
     PID/(Q)EAA Issuance - Detailed flow
 
-**Steps 1-4 (Discovery):** The User has selected a PID/(Q)EAA Issuer, and the Wallet Instance obtains the metadata for the selected PID/(Q)EAA Issuer.
+**Steps 1-4 (Discovery):** The User selects the PID/(Q)EAA Issuer, and the Wallet Instance obtains the metadata for the selected PID/(Q)EAA Issuer.
 
 .. note::
 
-    **Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Issuer is part of Federation and then it can consume its Metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the PID/(Q)EAA Issuer is represented within the section `Entity Configuration Credential Issuer`_.
+    **Federation Check:** The Wallet Instance needs to check if the PID/(Q)EAA Issuer is part of Federation, obtaining then its protocol specific metadata. A non-normative example of a response from the endpoint **.well-known/openid-federation** with the **Entity Configuration** and the **Metadata** of the PID/(Q)EAA Issuer is represented within the section `Entity Configuration Credential Issuer`_.
 
 
 **Steps 5-6 (PAR Request):** The Wallet Instance creates a PKCE code verifier that sends in a *pushed authorization request*, using the request parameter (see :rfc:`9126` Section 3) to the PID/(Q)EAA Issuer PAR endpoint. The Wallet Instance signs the request using its private key. A OAuth2 client authentication method MUST be involved, since in this flow the pushed authorization endpoint is a protected endpoint. The client authentication is based on the model defined in [:rfc:`7521`] using the Wallet Instance Attestation JWS inside the **client_assertion** parameter. The authorization_details [RAR :rfc:`9396`] parameter is extended to allow Wallet Instance to specify the types of the credentials when requesting authorization for the PID/(Q)EAA issuance.
@@ -176,7 +176,7 @@ The JWS payload of the request object is represented below:
 
 .. note::
 
-   **User Authentication and Consent:** The PID Provider performs the User authentication based on the requirements of eIDAS LoA High by means of national notified eIDAS scheme and asks the User consent for the PID issuance. 
+   **User Authentication and Consent:** The PID Provider performs the User authentication based on the requirements of eIDAS LoA High by means of national notified eIDAS scheme and requires the User consent for the PID issuance. 
    The (Q)EAA Issuer performs the User authentication requesting a valid PID to the Wallet Instance. The (Q)EAA Issuer MUST use [`OpenID4VP`_] to dynamically request presentation of the PID. From a protocol perspective, the (Q)EAA Issuer then acts as a verifier and sends a presentation request to the Wallet Instance. The Wallet Instance MUST have a valid PID obtained prior to starting a transaction with the (Q)EAA Issuer.
 
 **Steps 10-11 (Authorization Response):** The PID/(Q)EAA Issuer sends an authorization code to the Wallet Instance. 
@@ -190,7 +190,7 @@ The JWS payload of the request object is represented below:
     HTTP/1.1 302 Found
     Location: eudiw://start.wallet.example.org?code=SplxlOBeZQQYbYS6WxSbIA&state=fyZiOL9Lf2CeKuNT2JzxiLRDink0uPcd&iss=https%3A%2F%2Fpid-provider.example.org
 
-**Steps 12-13 (DPoP Proof for Token Endpoint)**: The Wallet Instance creates a key for DPoP and a fresh DPoP proof for the token request to the PID/(Q)EAA Issuer. DPoP provides a way to bind the access token to a certain sender (Wallet Instance) `[DPoP-draft16] <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-16>`_. Thus, it mitigates the misuse of leaked or stolen Access Tokens at the Credential Endpoint of PID/(Q)EAA Issuer as the attacker needs to present a valid DPoP proof.
+**Steps 12-13 (DPoP Proof for Token Endpoint)**: The Wallet Instance creates a key for DPoP and a fresh DPoP proof for the token request to the PID/(Q)EAA Issuer. DPoP provides a way to bind the access token to a certain sender (Wallet Instance) `[DPoP-draft16] <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-16>`_. This mitigates the misuse of leaked or stolen Access Tokens at the Credential Endpoint of PID/(Q)EAA Issuer as the attacker needs to present a valid DPoP proof.
 
 **Step 14 (Token Request):** The Wallet Instance sends a token request to the PID/(Q)EAA Issuer token endpoint using the authorization *code*, *code_verifier*, *DPoP proof* and *private_key_jwt*.
 
@@ -233,7 +233,7 @@ The JWS payload of the request object is represented below:
     }
 
 
-**Steps 16-18 (DPoP Proof for Credential Endpoint):** The Wallet Instance creates a new key pair to which the new credential shall be bound. Then, it creates a proof of possession with the new key and the *c_nonce* obtained in **Step 15** and it creates a DPoP proof for the request to the PID/(Q)EAA credential issuance endpoint.  
+**Steps 16-18 (DPoP Proof for Credential Endpoint):** The Wallet Instance creates a new key pair to which the new credential SHALL be bound. Then, it creates a proof of possession with the new key and the *c_nonce* obtained in **Step 15** and it creates a DPoP proof for the request to the PID/(Q)EAA credential issuance endpoint.  
 
 **Step 19 (Credential Request):** The Wallet Instance sends a PID/(Q)EAA issuance request to the PID/(Q)EAA credential endpoint. It contains the *access token*, the *DPoP proof*, the *credential type*, the *proof* (proof of possession of the key) and the *format*.
 
@@ -293,7 +293,7 @@ Where the decoded content of the JWT is represented below:
 
 
 
-**Steps 20-22 (Credential Response):** The PID/(Q)EAA Issuer checks the *DPoP proof* and whether the *access token* is valid and suitable for the requested PID/(Q)EAA. It also checks the proof of possession for the key material the new credential shall be bound to. If all checks succeed, the PID/(Q)EAA Issuer creates a new credential bound to the key material and sends it to the Wallet Instance. The Wallet Instance MUST perform the PID/(Q)EAA integrity and authenticity checks and if it is successful can proceed with secure storage of the credential. 
+**Steps 20-22 (Credential Response):** The PID/(Q)EAA Issuer checks the *DPoP proof* and whether the *access token* is valid and suitable for the requested PID/(Q)EAA. It also checks the proof of possession for the key material the new credential SHALL be bound to. If all checks succeed, the PID/(Q)EAA Issuer creates a new credential bound to the key material and sends it to the Wallet Instance. The Wallet Instance MUST perform the PID/(Q)EAA integrity and authenticity checks before proceeding with the secure storage of the credential. 
 
 .. code-block:: http
 
@@ -384,10 +384,10 @@ The JWT payload is given by the following parameters:
       - It MUST be set to the identifier of the PID/(Q)EAA Issuer.
       - :rfc:`9126` and :rfc:`7519`.
     * - **exp**
-      - UNIX Timestamp with the expiry time of the JWT, coded as NumericDate.
+      - UNIX Timestamp with the expiry time of the JWT.
       - :rfc:`9126` and :rfc:`7519`.
     * - **iat**
-      - UNIX Timestamp with the time of JWT issuance, coded as NumericDate.
+      - UNIX Timestamp with the time of JWT issuance.
       - :rfc:`9126` and :rfc:`7519`.
     * - **response_type**
       - It MUST be set as in the :ref:`Table of the HTTP parameters <table_http_request_claim>`.
@@ -405,7 +405,7 @@ The JWT payload is given by the following parameters:
       - It MUST be set as in the :ref:`Table of the HTTP parameters <table_http_request_claim>`.
       - See :ref:`Table of the HTTP parameters <table_http_request_claim>`.
     * - **authorization_details**
-      - Array of JSON Object. Each JSON Object MUST include the following claims:
+      - Array of JSON Objects. Each JSON Object MUST include the following claims:
 
             - **type**: it MUST be set to ``openid_credential``,
             - **format**: it MUST be set to ``vc+sd-jwt``,
@@ -490,7 +490,7 @@ If the authentication is successful the PID/(Q)EAA Issuer redirects the User by
       - Unique *Authorization Code* that the Wallet Instance submits to the Token Endpoint.
       - [:rfc:`6749#section-4.1.2`], `Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants <https://www.rfc-editor.org/rfc/rfc7521>`_
     * - **state**
-      - The Wallet Instance MUST check the correspondence with the state value in the request object. It is defined as in the :ref:`Table of the JWT Request parameters <table_jwt_request>`.
+      - The Wallet Instance MUST check the correspondence with the ``state`` parameter value in the request object. It is defined as in the :ref:`Table of the JWT Request parameters <table_jwt_request>`.
       - [:rfc:`6749#section-4.1.2`].
     * - **iss**
       - Unique identifier of the PID/(Q)EAA Issuer who created the Authentication Response. The Wallet Instance MUST validate this parameter.
@@ -508,9 +508,9 @@ defined in :rfc:`6749`.
 Token Request
 ^^^^^^^^^^^^^^^
 
-The request to the PID/(Q)EAA Token endpoint  MUST be an HTTP request with method POST, where its body message is encoded in ``application/x-www-form-urlencoded`` format. The Wallet Instance sends the Token endpoint request with *private_key_jwt* authentication and a *DPoP proof* containing the mandatory parameters, defined in the table below.
+The request to the PID/(Q)EAA Token endpoint MUST be an HTTP request with method POST, where its body message is encoded in ``application/x-www-form-urlencoded`` format. The Wallet Instance sends the Token endpoint request with *private_key_jwt* authentication and a *DPoP proof* containing the mandatory parameters, defined in the table below.
 
-The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP header. The Token endpoint MUST validate the DPoP proof based on the steps defined in Section 4.3 of the DPoP specifications `[DPoP-draft16] <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-16>`_. Thus, this mitigates the misuse of leaked or stolen access tokens at the credential endpoint. If the DPoP proof is invalid, the Token endpoint returns an error response, according to Section 5.2 of [:rfc:`6749`] with ``invalid_dpop_proof`` as the value of the error parameter. 
+The Token endpoint MUST accept and validate the DPoP proof sent in the DPoP HTTP header. The Token endpoint MUST validate the DPoP proof according to Section 4.3 of the DPoP specifications `[DPoP-draft16] <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-dpop-16>`_. Thus, this mitigates the misuse of leaked or stolen access tokens at the credential endpoint. If the DPoP proof is invalid, the Token endpoint returns an error response, according to Section 5.2 of [:rfc:`6749`] with ``invalid_dpop_proof`` as the value of the error parameter. 
 
 
 .. list-table:: 
@@ -688,7 +688,7 @@ If the *DPoP proof* is invalid, the Credential endpoint returns an error respons
     - **Description**
     - **Reference**
   * - **credential_definition**
-    - JSON object containing the detailed description of the credential type. It MUST have at least the **type** sub claims which is a JSON array containing the type values the Wallet shall request in the subsequent Credential Request. It MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the PID/(Q)EAA Issuer metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``.
+    - JSON object containing the detailed description of the credential type. It MUST have at least the **type** sub claims which is a JSON array containing the type values the Wallet SHALL request in the Credential Request. It MUST be set in accordance to the type of the requested PID/(Q)EAA that is obtained from the PID/(Q)EAA Issuer metadata. For example, in the case of the PID, it MUST be set to ``PersonIdentificationData``.
     - `[OIDC4VCI. Draft 13] <https://openid.bitbucket.io/connect/openid-4-verifiable-credential-issuance-1_0.html>`_.
   * - **format** 
     - Format of the Credential to be issued. This MUST be `vc+sd-jwt`.