Wallet Instance Lifecycle (#252)

* feat: Add Wallet Attestation request flow

* Apply suggestions from code review

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

* Apply suggestions from code review

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

* Add nonce endpoint reference

* Update docs/en/wallet-attestation.rst

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

* chore: Wallet Attestation editorials and some normative verbs

* chore: wallet solution editorials

* Remove type

* Remove type

* chore: standards editorials and removed unused token revocation

* defind terms removea misleading element, wallet solution removed auth endpoint pointing to SIOP

* Apply suggestions from code review

Co-authored-by: fmarino-ipzs <[email protected]>

* Update docs/en/defined-terms.rst

Co-authored-by: fmarino-ipzs <[email protected]>

* Update docs/en/wallet-attestation.rst

Co-authored-by: fmarino-ipzs <[email protected]>

* wallet instance lifecycle

* Update docs/en/wallet-attestation.rst

Co-authored-by: fmarino-ipzs <[email protected]>

* Update docs/en/wallet-attestation.rst

Co-authored-by: fmarino-ipzs <[email protected]>

* Update docs/en/wallet-attestation.rst

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

* refactor

* Add Warning

* Add Warning

* Include other wscd technologies

* Rename Wallet Hardware Key Tag to Cryptographic Hardware Key

* Rename Wallet Hardware Key Tag to Cryptographic Hardware Key

* Apply suggestions from code review

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

* Update docs/en/wallet-attestation.rst

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

* add clarification

* clarify revocation

* Apply suggestions from code review

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

* Apply suggestions from code review

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

* Apply suggestions from code review

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

* Update docs/en/wallet-solution.rst

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

* Apply suggestions from code review

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

* image

---------

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

docs/en/wallet-attestation.rst

@@ -493,7 +493,74 @@ The body of the Wallet Attestation JWT MUST contain:
       -
     * - **presentation_definition_uri_supported**
       - Boolean value specifying whether the Wallet Instance supports the transfer of presentation_definition by reference. MUST be set to false.
-      -
+
+Wallet Instance Lifecycle
+-----------------------------
+
+The ability of the Wallet Instance to obtain a Wallet Attestation is bound to its current state.
+The Wallet Instance assesses its current state based on the Credentials stored locally and the Wallet Attestation issued by the Wallet Provider.
+
+The lifecycle of a Wallet Instance encompasses all the potential states it can configure, along with the transitions from one state to another. This lifecycle is depicted in the diagram below:
+
+.. figure:: ../../images/wallet_instance_lifecycle.svg
+   :name: Wallet Instance Lifecycle
+   :alt: Illustration representing the Wallet Instance lifecycle, with the states explained below.
+   :target: https://www.plantuml.com/plantuml/uml/SoWkIImgAStDuOhMYbNGrRLJyCm32kNafAPOAMH2c5mAG00N1YloBqWjIYp9pCzBpB5IA4ijoaoh1Ab25WUh2qlCoKm1gW1HYIMf83KGCKnJClDmg799JKmkoIm3IW1DAaejoyzEHRSBfpfCbmEzQQLGceVaDOH6x4emxS9KWd0mfgH3QbuAC801
+
+
+A Wallet Instance SHOULD obtain a Wallet Attestation if it's in either `Installed`, `Operational` or `Valid` state; that implies that a `Deactivated` Wallet Instance cannot obtain a Wallet Attestation hence it cannot interact with other entities of the ecosystem, such as PID/(Q)EAA Providers and Relying Parties.
+
+States
+~~~~~~~~~~~~~~~~~~
+.. list-table::
+   :widths: 20 60
+   :header-rows: 1
+
+   * - **State**
+     - **Description**
+   * - `Installed`
+     - The User has installed the Wallet Solution on the device.
+   * - `Operational`
+     - The Wallet Instance has been verified and the Wallet Hardware Key has been registered; no valid PID is present in the storage.
+   * - `Valid`
+     - A valid PID is present in the storage.
+   * - `Deactivated`
+     - The Wallet Instance has been revoked and its Wallet Hardware Key has been marked as not usable.
+
+Transitions
+~~~~~~~~~~~~~~~~~~
+.. list-table::
+   :widths: 20 60
+   :header-rows: 1
+
+   * - **Transition**
+     - **Description**
+   * - `install`
+     - The User performs a fresh installation or restores the initial state of the Wallet Instance on the device.
+   * - `verify`
+     - The Wallet Instance has been verified by the Wallet Provider and its Wallet Hardware Key has been registered.
+   * - `validate`
+     - The Wallet Instance obtains a valid PID.
+   * - `invalidate`
+     - The PID expires or gets revoked.
+   * - `revoke`
+     - The Wallet Provider marks the Wallet Instance as not usable.
+   * - `uninstall`
+     - The User removes the Wallet Instance from the device.
+
+Revocations
+~~~~~~~~~~~~~~~~~~
+As mentioned in the *Wallet Instance initialization and registration* section above, a Wallet Instance is bound to a Wallet Hardware Key and it's uniquely identified by it.
+The Wallet Instance SHOULD send its public Wallet Hardware Key with the Wallet Provider, thus the Wallet Provider MUST identify a Wallet Instance by its Wallet Hardware Key.
+
+When a Wallet Instance is not usable anymore, the Wallet Provider MUST revoke it. The revocation process is a unilateral action taken by the Wallet Provider, and it MUST be performed when the Wallet Instance is in the `Operational` or `Valid` state.
+A Wallet Instance becomes unusable for several reasons, such as: the User requests the revocation, the Wallet Provider detects a security issue, or the Wallet Instance is no longer compliant with the Wallet Provider's security requirements.
+
+The details of the revocation mechanism used by the Wallet Provider as well as the data model for maintaining the Wallet Instance references is delegated to the Wallet Provider's implementation.
+
+During the *Wallet Instance initialization and registration* phase the Wallet Provider MAY associate the Wallet Instance with a specific User, subject to obtaining the User's consent. The Wallet Provider MUST evaluate the operating system and general technical capabilities of the device to check compliance with the technical and security requirements and to produce the Wallet Instance metadata.
+When the User consents to being linked with the Wallet Instance, they gain the ability to directly request Wallet revocation from the Wallet Provider, and it also allows the Wallet Provider to revoke the Wallet Instance associated with that User.
+
 
 
 .. _token endpoint: wallet-solution.html#wallet-attestation