Add Identity docs (#3256)

* update references

* update

* update

* remove alias_output page

* Refactor resolve and update examples for IOTA Identity

* Update docs/content/developer/iota-identity/how-tos/decentralized-identifiers/create.mdx

* Update docs/content/references/iota-identity/iota-did-method-spec.mdx

Co-authored-by: Yasir <[email protected]>

* remove wasm content

* minor spelling fixes

* update contribution links

* reworked introduction

* update examples references

* update links to releage tag, update referenced lines

* update example reference for alternative revoking

* Update docs/content/references/iota-identity/iota-did-method-spec.mdx

* Update docs/content/developer/iota-identity/getting-started/rust.mdx

* update include isntructions

* remove outdated video

* readd revocation specification

* Add missing page

* No special headers please

* Fix broken links

* Remove tags

* add sidebar

* remove sidebar entries

* fix sidebar

* update developer overview

* fix sidebar link

* fix developer overview link

* fix DID method spec

* Fix images

* remove duplicate example DID

* Apply suggestions from code review

Co-authored-by: Lucas Tortora <[email protected]>

* task(devx): Move Identity docs and update Nav (#4381)

* Moved Identity docs and gave them their own nav link

* fix sidebar

* fix ref links

* fix ref links

* fix  links

* fix sidebar

* fix sidebars

* add @saucelabs/theme-github-codeblock
fix sidebar

* add @saucelabs/theme-github-codeblock
fix sidebar

* fix nav

* fix link

* fix syntax highlighting

* remove DID delete include

---------

Co-authored-by: Enrico Marconi <[email protected]>
Co-authored-by: Yasir <[email protected]>
Co-authored-by: Yasir <[email protected]>
Co-authored-by: Sebastian Wolfram <[email protected]>
Co-authored-by: Dr-Electron <[email protected]>
Co-authored-by: Lucas Tortora <[email protected]>

docs/content/_snippets/not-available-on-testnet.mdx

@@ -1,5 +1,5 @@
 :::info Mainnet Only
 
-IOTA EVM and IOTA Identity are not available on the IOTA Move Testnet.
+IOTA EVM is not available on the IOTA Move Testnet.
 
 :::

docs/content/developer/developer.mdx

@@ -44,6 +44,12 @@ Go to [Cryptography](cryptography.mdx).
 
 Get aquainted with IOTA by solving challenges of increasing complexity in the [Capture the Flag section](iota-move-ctf/introduction.mdx).
 
+## Decentralized Identity
+
+IOTA offers a Decentralized Identity framework which can be utilized to provide and use digital decentralized identities for People, Organizations, Things and Objects. 
+
+Go to the [IOTA Identity Framework](/iota-identity/) section.
+
 ## Advanced Topics
 
 The Advanced Topics section includes guides for advanced solutions (like asset tokenization). These topics assume you are familiar with Move and the IOTA blockchain.
@@ -75,12 +81,3 @@ Go to the [Developer Cheat Sheet](dev-cheat-sheet.mdx).
 Everything you need to know about our Layer 2 EVM Support, including working with the IOTA EVM and ShimmerEVM chains. 
 
 Go to [EVM Smart Contracts](https://wiki.iota.org/isc/introduction/).
-
-## Decentralized Identity
-
-<NotAvailableOnTestnet />
-
-IOTA also offers a Decentralized Identity framework which can be utilized to provide and use digital decentralized identities for People, Organizations, Things and Objects. 
-
-Go to the [IOTA Identity Framework](https://wiki.iota.org/identity.rs/welcome/) section.
-

docs/content/iota-identity/contribute.mdx

@@ -0,0 +1,35 @@
+---
+title: Contribute to the project
+sidebar_label: Contribute
+description: Contribute to IOTA Identity by joining the Identity initiative, via the projects GitHub repository, documentation, or sharing your knowledge.
+image: /img/identity/icon.png
+tags:
+  - reference
+  - identity
+---
+
+**Thanks for thinking about contributing to the project! You can contribute using the following ways.**
+
+## Contribute to the Project's GitHub Repository
+
+All of the code is open source and hosted on [GitHub](https://github.com/iotaledger/identity.rs) where you can:
+
+- [Report a bug](https://github.com/iotaledger/identity.rs/issues/new/choose).
+- [Suggest a new feature](https://github.com/iotaledger/identity.rs/blob/main/.github/CONTRIBUTING.md).
+- [Contribute to the documentation](#contribute-to-the-documentation).
+
+## Contribute to the Documentation
+
+This documentation is also open source and hosted on GitHub.
+
+If you want to contribute new documentation or fix an error, see the [contribution guidelines](https://docs.iota.org/references/contribute/contribution-process).
+
+## Share Your Knowledge
+
+Helping others is an important part of any open source ecosystem.
+
+By sharing your knowledge with others, you can provide a lot of value to the community and maybe inspire someone else to learn and contribute.
+
+Take a look at what discussions are going on in the `#identity` channel on [Discord](https://discord.iota.org).
+
+Thanks :heart:

docs/content/iota-identity/explanations/about-identity-objects.mdx

@@ -0,0 +1,47 @@
+---
+title: Identity object
+description: The IOTA `Identity` Move object.
+image: /img/identity/icon.png
+tags:
+  - explanation
+  - identity
+  - did
+  - getting-started
+---
+
+# Identity Object
+
+An Identity Object is a **shared** _Move_ object that stores a single DID Document on the network, allowing both
+on-chain and off-chain actors to interact with it.
+
+The Identity Object's unique ID is used to derive the actual DID of the DID Document it contains.
+
+## Identity's Access Control
+
+An `Identity` is a shared object and is thus accessible by anyone. For this reason, it is of paramount importance to 
+limit the use of an `Identity`'s APIs - especially its mutable ones - to only the intended actors.
+
+### Controllers and `ControllerCap`
+
+The [DID specification](https://www.w3.org/TR/did-core/) defines **DID controller** as the entity allowed to make changes to
+a DID document. Since an `Identity` may be viewed as a simple wrapper over a DID Document, we extend the definition of _DID controller_ to be:
+_the entity allowed to make changes to an `Identity`_.
+
+In order to allow a broader range of actors to act as an `Identity`'s controller - e.g. an `Identity` controlling another `Identity` -
+a controller is identified through its **controller capability** `ControllerCap`.
+A `ControllerCap` is a _Move_ object that acts as a blind token, allowing anyone who presents it to the corresponding `Identity` to access
+the `Identity`'s APIs that are only invocable by its controllers.
+
+### Voting power and threshold
+
+When an `Identity` has more than a single controller, an access control (AC) policy for the `Identity` must be established. Such a policy is 
+represented by an unsigned integer **threshold** that is established upon the `Identity`'s creation. Together with the `Identity`'s threshold, each controller
+is assigned with a **voting power**, i.e. an unsigned integer that acts as a sort of _weight_ in the evaluation of an AC control policy.   
+
+### Proposals
+
+Whenever a controller wants to make a change to its `Identity`, a **proposal** encapsulating that change is created instead of carrying out the update
+right away. In order to execute the changes contained in a `Proposal` enough controllers need to approve it. The exact number of approvals depends on 
+the controllers' voting powers as well as the `Identity`'s threshold. 
+`Proposal`s keep track of the approvals they receive by internally storing the sum of all approving controllers' voting powers in a field called `votes`.
+A `Proposal` can only be executed after `votes` exceeds `Identity`'s threshold.

docs/content/iota-identity/explanations/decentralized-identifiers.mdx

@@ -0,0 +1,135 @@
+---
+description: The Decentralized Identifiers (DID) standard from W3C is the fundamental standard that supports the concept of a decentralized digital identity. Explore the basic aspects of the DID standard.
+image: /img/identity/icon.png
+tags:
+    - explanation
+    - identity
+    - did
+    - getting-started
+    - verification-method
+    - verifiable-credentials
+---
+
+# Decentralized Identifiers (DID)
+
+:::info TL;DR
+
+DIDs are unique identifiers that can be resolved to DID Documents containing public keys and URIs for identity verification and public information.
+
+Adhering to the W3C's DID specifications, IOTA's implementation ensures interoperability and security within its ledger.
+
+DIDs support self-sovereign identity, allowing identity owners to control their creation and destruction,
+while facilitating encrypted communication.
+
+:::
+
+A DID is a unique identifier that can be resolved to a DID Document. This document contains data such as public keys, enabling the holder to prove ownership over their personal data, but also URIs that link to public information about the identity. DIDs are the fundamental building blocks of decentralized digital identity.
+This implementation complies with the [DID specifications v1.0](https://www.w3.org/TR/did-core//) from the World Wide Web Consortium (W3C).
+
+In the IOTA Identity framework, we have implemented the DID standard according to the `iota` [DID Method Specification](../../references/iota-identity/iota-did-method-spec.mdx). Other implementations of DID on IOTA must follow the `iota` DID Method Specification if they want to use the `iota` method name. Libraries implementing the `iota` DID Method Specification are provided for [Rust](../getting-started/rust.mdx).
+
+## Decentralized Identifiers
+
+A Decentralized Identifier, or DID, is a unique identifier that is tied to a subject. This subject can be anything, like a person, an organization, an IoT device, or even an object. The identifier can be used by the subject to identify themselves through a digital format, providing a basis for online identification. The identifier looks like a set of random characters that includes some prefixes to determine which standard and implementation is used:
+
+`did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe`
+
+The World Wide Web Consortium (W3C) is a well-known standardization body that has standardized how DIDs should look and work.
+This provides a basis for different technologies that implement the [DID standard](https://www.w3.org/TR/did-spec-registries/#did-methods) to achieve interoperability.
+Keep in mind that, unfortunately, most of these methods are outdated and not maintained.
+
+## DID Documents
+
+The purpose of a DID is to help navigate to a DID Document,
+which is a document containing more information regarding the identity subject.
+This document contains data such as public keys, enabling the subject to prove ownership over their personal data,
+but can contain additional information on how to interact with the subject.
+
+The identifier contains all information to resolve a DID, providing the latest DID Document.
+The first three characters `did` indicate that the DID standard from W3C must be used to resolve the identifier.
+It is followed by a unique method name, in our case `iota`, to indicate that the IOTA method is used.
+
+The IOTA method is a specific implementation following the [IOTA DID Method Specification](../../references/iota-identity/iota-did-method-spec.mdx).
+This provides unique rules for the protocol to follow in order to manage a DID Document.
+In our case, it describes how DID Documents are uploaded and queried to and from the IOTA ledger.
+
+Lastly, a DID also contains a set of random characters that are unique per identity and resolve to a single DID Document.
+
+:::tip Requires basic knowledge of Asymmetric Encryption
+
+The following sections require some basic knowledge of Asymmetric Encryption.
+Please read or view some materials on the subject before continuing.
+
+:::
+
+### DID Document Anatomy
+
+A DID Document mostly contains two important pieces of data: verification methods and services.
+
+#### Verification Methods
+
+Verification methods contain public key material that can be used to prove ownership over the identity,
+by cryptographically signing something with the associated private key.
+The public key can be used to verify that the identity subject signed the data and therefore controls the private key.
+Ownership over the private keys, therefore, proves ownership over the identity.
+
+This also means that it is very important to keep the private keys safe and secure.
+In addition, the public keys allow users to send encrypted data to the identity that only the identity owner can decrypt.
+
+:::caution
+
+Never share your private keys, seeds, passphrases with anyone. Not even IOTA Foundation members.
+This may lead to loss of funds or control over your own digital identity.
+
+:::
+
+#### Services
+
+Services are URIs that point to more information about the identity.
+This could be something as simple as a website for an organizational identity.
+These services are publicly available for all to read,
+and should not contain Personal Identifiable Information (PII) in the case of human identities.
+
+## Why Use DIDs?
+
+DIDs allow any subject to have a unique identifier that they can prove ownership of,
+and at the same time provide a way to send them encrypted messages.
+The Identity is Self-Sovereign, meaning the subject is always in control;
+whether it is [creating](../how-tos/decentralized-identifiers/create.mdx), [updating](../how-tos/decentralized-identifiers/update.mdx), or [destroying](../how-tos/decentralized-identifiers/delete.mdx) it.
+
+### Verifiable Credentials
+
+DIDs become more interesting when you combine them with [verifiable credentials (VC)](verifiable-credentials.mdx).
+In essence, verifiable credentials (VCs) are signed statements by trusted third parties about a certain identity.
+The signer, or Issuer, is referenced by the DID and so is the subject, often called the holder.
+The holder controls a copy of this statement and can share it with other parties, the _Verifiers_,
+who can verify the statement and check which party made the statement without asking the Issuer.
+Instead, they can verify the issuer's signature by checking the issuer's DID Document.
+
+This puts Holders back in control over their own data,
+while making the data much more trustworthy as it has become verifiable.
+
+## Why Use Iota Identity Over Other Implementations?
+
+IOTA Identity is a framework to implement Self-Sovereign Identities on IOTA.
+Inherently, IOTA provides some unique features that have a major impact on the usability of the framework.
+
+### Availability and Accessibility
+
+DID Documents are stored in the ledger state and are covered storage deposit.
+This guarantees that all nodes will have an up-to-date copy of the latest DID Document.
+Resolving a DID into its document can usually be done by any IOTA node in the network.
+This solves many issues regarding availability, accessibility, and synchronization.
+
+### Layer1 Interactions
+
+DID Documents are stored in [Identity objects](./about-identity-objects.mdx).
+This allows them to directly interact with other Layer 1 artifacts like NFTs and coins.
+
+For instance, an Identity object representing a DID can hold coins or control NFTs.
+Transferring funds between DIDs is also possible on Layer 1.
+
+### Ease-of-use
+
+IOTA Identity abstracts the details of the DID standard by providing easy-to-use APIs that allow standardized behavior.
+It also allows more flexible and complex management of DID Documents.

docs/content/iota-identity/explanations/verifiable-credentials.mdx

@@ -0,0 +1,74 @@
+---
+description: Verifiable credentials are statements about the holder. They can be verified online or in person, and the holder decides who to share them with.
+image: /img/identity/icon.png
+tags:
+  - explanation
+  - identity
+  - verifiable-credentials
+---
+# Verifiable Credentials
+
+:::info TL;DR
+
+Verifiable credentials (VCs) are digital statements that can be cryptographically proven, like a digital passport,
+and are used within systems to assert certain properties or capabilities of an entity.
+
+In the IOTA Identity framework, this is managed with decentralized identifiers (DIDs) on the IOTA network.
+Subjects and issuers use their DIDs for the creation and verification of credentials.
+
+:::
+
+Credentials are statements about an entity,
+such as properties that the entity possesses or capabilities that they have,
+like a driver's license, passports, or a person's age.
+Verifiable credentials (VCs) are statements (e.g., Alice has a driver's license)
+that can be cryptographically verified by a third party, either online or in person.
+Additionally, the holder of the VC decides what is shared and who it is shared with.
+
+There are several types of actors that play different roles in a Verifiable Credential system.
+We'll start with a common example of how things work in the world today using physical credentials and centralized databases,
+and outline the roles that various entities play in the Verifiable Credential system.
+
+## Example - Passport Issuance
+
+A government (the _issuer_) issues a passport asserting citizenship (the _Verifiable Credential_) to Alice (the _subject_ and _Holder_),
+and writes the information to a database (the _Verifiable Data Registry_).
+When crossing the border, Alice (the _Holder_) presents her passport to a border agent (the _Verifier_),
+who can verify that Alice (the _subject_) is indeed a citizen.
+
+
+
+**Subject:** An entity about which claims are made – in this example, that Alice (the _subject_) is a citizen of this country.
+
+**Holder:** Any entity with a verifiable credential – Alice (the _Holder_) possesses the passport (the _VC_).
+
+**Issuer:** An entity which asserts claims about a subject – The governing body (the _issuer_), which is trusted, issues Alice a passport.
+
+**Verifier:** An entity which checks if the VC a holder presents is legitimate – The border agent (the _Verifier_) trusts the government (the _issuer_) which issued Alice her passport and validates that Alice (the _subject_) is a citizen.
+
+:::note
+
+See the [Verifiable Credentials Data Model 1.0 Specification](https://w3c.github.io/vc-data-model/) for more information.
+
+:::
+
+## Verifiable Credentials in IOTA
+
+In the IOTA Identity framework, instead of a physical passport being given to Alice and its information written
+into a centralized database owned by the government, Alice receives a digital verifiable credential,
+and the information required for verification in the future is written to the Tangle.
+
+At a high level, the creation and verification of a VC on IOTA works as follows:
+
+
+The first step is to create a verifiable credential that requires the subject (Alice) and issuer (the government) to
+have [DIDs](./decentralized-identifiers.mdx) published on the Tangle and a set of statements being asserted (that Alice has a passport).
+The issuer signs the credential with their private key and publishes the public key to the Tangle.
+
+Once the issuer is confident that the credential satisfies its expectations,
+the credential is stored and transmitted to the subject in a secure manner (off-chain).
+
+Validation is performed by looking up the issuer's public key on the Tangle,
+the holder proving ownership of their DID to the verifier (evidence),
+and validating that the issuing party has indeed signed the credential.
+

docs/content/iota-identity/explanations/verifiable-presentations.mdx

@@ -0,0 +1,39 @@
+# Verifiable Presentations
+
+A verifiable presentation is the recommended data format for sharing one or more [verifiable credentials](./verifiable-credentials.mdx).
+It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for validation.
+
+For instance, after an issuer [creates and issues](./../how-tos/verifiable-credentials/create.mdx) a [verifiable credential](./verifiable-credentials.mdx) to a holder, such as a university issuing a degree to a graduate,
+the holder stores it securely until asked to present it.
+A company could then request proof of that university degree: the holder can [create a verifiable presentation](./../how-tos/verifiable-credentials/create.mdx)
+containing their credential, already signed by their university, and present it to the company to [validate](./../how-tos/verifiable-credentials/create.mdx#validate-a-vc).
+
+Note that verifiable presentations that contain personal data should, as with verifiable credentials, be transmitted and stored securely off-chain to satisfy data privacy regulations such as [GDPR](https://gdpr.eu/).
+
+:::note
+
+See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/#presentations) for more information on verifiable presentations.
+
+:::
+
+## Security Considerations
+
+### Replay Attacks
+
+A malicious actor could potentially store a verifiable presentation without a challenge
+and replayed to a different verifier, impersonating the holder.
+This is because the holder's signature on a presentation would still be seen as valid indefinitely,
+until they [rotate](https://www.w3.org/TR/did-core/#verification-method-rotation) the verification method used.
+
+To mitigate this, verifiers should always send a unique challenge when requesting a verifiable presentation.
+This challenge can be set as the `nonce` property of the JWS by the holder during signing.
+The digital signature prevents these properties from being altered as it would invalidate the signature, effectively preventing a malicious
+actor from injecting different values into old verifiable presentations. A presentation without a challenge in its proof that matches what was
+sent by the verifier should be considered invalid.
+
+The challenge string should be sufficiently random and unique for each verifiable presentation requested by a verifier to avoid
+being predicted. 
+
+Holders may additionally specify that their signature on a verifiable presentation expires after a short duration, as
+per `JwtPresentationOptions`. However, verifiers and different implementations could ignore that property,
+so setting a signature expiration alone should not be relied upon.