feat(docs): Add IOTA Identity content

.typos.toml

@@ -25,6 +25,8 @@ ratatui = "ratatui"
 groth = "groth"
 strat = "strat"
 mistic = "mistic"
+# Identity
+AAS = "AAS"
 # actual typos purposedly used in tests
 assing = "assing"
 tring = "tring"

docs/content/developer/iota-identity/contact.mdx

@@ -0,0 +1,13 @@
+---
+title: Contact
+sidebar_label: Contact
+description: Get in touch with the project maintainers.
+image: /img/identity/icon.png
+---
+
+If you found a security related issue, please follow the [responsible disclosure policy](https://github.com/iotaledger/identity.rs/security/policy).
+
+For everything else, you can get in contact with the project by:
+
+- Creating an [issue](https://github.com/iotaledger/identity.rs/issues/new/choose) on [GitHub](https://github.com/iotaledger/identity.rs).
+- Joining the `identity` channel on the [IOTA Discord](https://discord.iota.org/).

docs/content/developer/iota-identity/contribute.mdx

@@ -0,0 +1,44 @@
+---
+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
+---
+
+**Thanks for thinking about contributing to the project! You can contribute using the following ways.**
+
+## Join the Identity Initiative
+
+The [Identity Initiative](https://github.com/iota-community/X-Team_IOTA_Identity) is a collaborative effort to help improve the developer experience that includes:
+
+- Quality assurance and review.
+- Documentation.
+- Code samples.
+
+If you would like to get involved, join the [#x-team-identity](https://discord.com/channels/397872799483428865/773274309861834782) channel on [Discord](https://discord.iota.org).
+
+## 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://github.com/iotaledger/iota-wiki/blob/main/.github/CONTRIBUTING.md).
+
+## 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-discussion` channel on [Discord](https://discord.iota.org).
+
+Thanks :heart:

docs/content/developer/iota-identity/explanations/about-alias-outputs.mdx

@@ -0,0 +1,61 @@
+---
+title: Alias Outputs
+description: UTXO Alias Output
+image: /img/identity/icon.png
+tags:
+  - explanation
+  - did
+  - getting-started
+---
+
+# Alias Outputs
+
+:::info TL;DR
+
+The IOTA DID method uses Alias Outputs for storing DID Documents.
+Alias Outputs are created via transactions,
+and require a storage deposit to cover the data storage.
+The deposit is refundable upon destruction of the output.
+
+Each Alias Output has an `Alias ID` that becomes the basis for the DID,
+and which can be transferred through transactions to update DID Documents.
+
+:::
+
+
+The IOTA DID method uses the IOTA ledger, which is based on the unspent transaction output (_UTXO_) model,
+as well as the features of the Stardust upgrade,
+which are fundamental to the IOTA DID method.
+
+The Alias Output is used to store a DID Document on the ledger.
+It is a specific implementation of the UTXO _state machine_ that can hold arbitrary data in its `State Metadata`.
+The Alias Output has two kinds of controllers, a state controller and a governor.
+
+The state controller can only execute state transitions, which update the data in the `State Metadata`.
+
+The governor, on the contrary, can't update the `State Metadata` but can change controllers and even destroy the Alias Output.
+
+A controller can be either Ed25519 Address, Alias Address or an _NFT_ Address. Only one of each of these types can be set for an Alias Output.
+
+To create a new Alias Output, a transaction must be made that includes another Output as input,
+a Basic Output, for example, and the new Alias Output as output.
+
+### Storage Deposit
+
+The arbitrary data stored in the `State Metadata` of the Alias output must be covered by a
+storage deposit.
+This helps to control the ledger size from growing uncontrollably while guaranteeing the data
+is indefinitely stored on the ledger, which is important for resolving DID Documents.
+This deposit is fully refundable and can be reclaimed when the output is destroyed.
+
+Both the state controller and the governor can control the tokens stored in the Alias Output.
+_Nodes_ expose an API to calculate the required deposit depending on the size of the data stored.
+
+### Alias ID
+
+Each Alias Output has an `Alias ID`. This ID is assigned after a transaction creates the Alias Output.
+The actual DID is derived from this `Alias ID`, so it will be unknown before publishing the transaction.
+Consequently, the DID inside the `State Metadata` is replaced by the placeholder `did:0:0` to indicate self.
+
+If a transaction has an Alias Output as input, its `Alias ID` can be kept by one of its outputs.
+This feature is necessary for updating the DID Documents since the DID itself is derived from the `Alias ID`.

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

@@ -0,0 +1,143 @@
+---
+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
+    - 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) and [WASM](../getting-started/wasm.mdx).
+
+An example of a DID conforming to the `iota` method specification:
+`did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe`
+
+## 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 [Alias Outputs](./about-alias-outputs.mdx),
+this allows them to directly interact with Layer 1 artifacts like NFTs and native assets.
+
+For instance, an Alias Output representing a DID can hold native assets 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.
+
+### Secure Storage
+
+IOTA Identity provides a
+Stronghold solution
+for managing secrets securely, without requiring developers to reinvent the security wheel.

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

@@ -0,0 +1,73 @@
+---
+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
+  - 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 Tangle.
+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/developer/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](#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.