diff --git a/banners/identity-06-deprecation-migration.mdx b/banners/identity-06-deprecation-migration.mdx deleted file mode 100644 index b88a03ffb94..00000000000 --- a/banners/identity-06-deprecation-migration.mdx +++ /dev/null @@ -1,3 +0,0 @@ -This version of IOTA Identity is the last version targeting Chrysalis networks and is deprecated. Please upgrade to the latest version of [IOTA Identity for Stardust Networks](/identity.rs/0.7/introduction/). - -Also, with Identity Rust 0.6.3 and Wasm 0.6.1 a breaking change was introduced that requires a migration of existing Stronghold Snapshot files. You can find migration instructions [here](/identity.rs/0.6/tutorials/migrate-stronghold/). diff --git a/banners/identity-deprecated.mdx b/banners/identity-deprecated.mdx deleted file mode 100644 index 271441c16e4..00000000000 --- a/banners/identity-deprecated.mdx +++ /dev/null @@ -1 +0,0 @@ -This version of IOTA Identity is deprecated. Please upgrade to [Identity 0.6 for Chrysalis Networks](/identity.rs/welcome/) and follow the migration instructions for upgrading Stronghold Snapshot files [here](/identity.rs/tutorials/migrate-stronghold/), or upgrade to the latest version of [IOTA Identity for Stardust Networks](/identity.rs/0.7/introduction/). diff --git a/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx b/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx index 096ec3734ff..77efe77d1fa 100644 --- a/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx +++ b/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx @@ -20,21 +20,20 @@ See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/ ### Replay Attacks -A verifiable presentation without a challenge and domain properties could potentially be stored by a malicious actor +A verifiable presentation without a challenge could potentially be stored by a malicious actor 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 and domain when requesting a verifiable presentation. -These properties are then included in the proof section of the presentation by the holder during signing using [Proof Options](#proof-options). +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 and domain -in its proof that matches what was sent by the verifier should be considered invalid. +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. The domain, which does not need to be random, is an additional measure. In the unlikely occurrence -of two verifiers generating the same random challenge, the domain would sufficiently distinguish those requests. +being predicted. Holders may additionally specify that their signature on a verifiable presentation expires after a short duration, as -per [Proof Options](./../how-tos/verifiable-presentations/create-and-validate.mdx#proof-options). However, verifiers and different implementations could choose to ignore that property, -so setting a signature expiration alone should not be relied upon. \ No newline at end of file +per `JwtPresentationOptions`. However, verifiers and different implementations could choose to ignore that property, +so setting a signature expiration alone should not be relied upon. diff --git a/docs/build/identity.rs/1.0/docs/getting-started/rust.mdx b/docs/build/identity.rs/1.0/docs/getting-started/rust.mdx index 431e991c5f0..7bde26fd342 100644 --- a/docs/build/identity.rs/1.0/docs/getting-started/rust.mdx +++ b/docs/build/identity.rs/1.0/docs/getting-started/rust.mdx @@ -37,7 +37,7 @@ identity_iota = { git = "https://github.com/iotaledger/identity.rs", branch = "m ## Examples -To try out the [examples](https://github.com/iotaledger/identity.rs/tree/main/examples), you should: +To try out the [examples](https://github.com/iotaledger/identity.rs/tree/v1.0.0/examples), you should: 1. Clone the repository: diff --git a/docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx b/docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx index 69c4927da67..69ba1ccdb53 100644 --- a/docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx +++ b/docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx @@ -341,4 +341,4 @@ You may find it useful to see how the WASM bindings are being used in existing a ## [API Reference](/identity.rs/references/api/wasm) -## [Examples](https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/README.md) +## [Examples](https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/README.md) diff --git a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx index 5c3f0bccc25..306e841fa0b 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx @@ -45,14 +45,14 @@ you will need an output with actual Shimmer or IOTA funds to create a new Alias ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L52 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/0_create_did.rs#L52 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L40-L51 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L40-L51 ``` @@ -77,14 +77,14 @@ the DID inside the document. ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L59-L71 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/0_create_did.rs#L59-L71 ``` ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L55C44-L65 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L55C44-L65 ``` @@ -107,14 +107,14 @@ However, they must be unlocked in order perform a state or governance transition ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L75 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/0_create_did.rs#L75 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L70 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L70 ``` @@ -139,14 +139,14 @@ the DID Document is stored on the ledger and can be [resolved](resolve.mdx) usin ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L78 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/0_create_did.rs#L78 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L74 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L74 ``` @@ -159,14 +159,14 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0 ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/0_create_did.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/0_create_did.ts ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx index 465cafff339..46567c9a5ca 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx @@ -46,14 +46,14 @@ and optionally reclaiming the storage deposit. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/3_deactivate_did.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/3_deactivate_did.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/3_deactivate_did.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/3_deactivate_did.ts ``` @@ -92,14 +92,14 @@ The following example demonstrates a governor destroys an IOTA Identity and send ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/4_delete_did.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/4_delete_did.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/4_delete_did.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/4_delete_did.ts ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx index 87814227334..609fe4a759e 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx @@ -167,14 +167,14 @@ and [credentials](./../../explanations/verifiable-credentials.mdx). ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/5_custom_resolution.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/1_advanced/5_custom_resolution.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/4_custom_resolution.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/1_advanced/4_custom_resolution.ts ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx index c888221877b..70b966cfc99 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx @@ -520,14 +520,14 @@ Publish the updated DID Document inside the Alias Output taking into account the ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/1_update_did.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/1_update_did.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/1_update_did.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/1_update_did.ts ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx b/docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx index c01de0c4c23..b9147c92cff 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx @@ -165,14 +165,14 @@ You can learn more ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/6_domain_linkage.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/1_advanced/6_domain_linkage.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/5_domain_linkage.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/1_advanced/5_domain_linkage.ts ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx b/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx index 1e1fdb28673..50afe04ef92 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx @@ -119,14 +119,14 @@ This section shows the Rust and TypeScript `Memstore` implementations. ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/jwk_storage.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/lib/jwk_storage.ts ``` ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_storage/memstore.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/identity_storage/src/key_storage/memstore.rs ``` @@ -138,14 +138,14 @@ https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_sto ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/key_id_storage.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/lib/key_id_storage.ts ``` ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_id_storage/memstore.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/identity_storage/src/key_id_storage/memstore.rs ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx index 4d3ba898da4..34b09e5cee7 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx @@ -36,31 +36,12 @@ In the IOTA Identity Framework, you can create a Verifiable Credential with the - [**Evidence**](https://www.w3.org/TR/vc-data-model/#evidence): Optional list of objects that can be used by the issuer to provide the verifier with additional supporting information in a verifiable credential. - [**Non-Transferable**](https://www.w3.org/TR/vc-data-model/#nontransferable-property): Optional flag that indicates that a verifiable credential must only be encapsulated in a [verifiable presentation](./../../explanations/verifiable-presentations.mdx) whose proof was issued by the credential subject. -## Signing {#signing} - -After creation, the issuer signs the verifiable credential using one of their private keys, -embedding the digital signature in its [proof](https://www.w3.org/TR/vc-data-model/#proofs-signatures) section. - -This is what allows verifiers to independently validate the credential using the corresponding public key from the issuer's DID Document. -### Proof Options {#proof-options} -A digital signature on a verifiable credential both provides data integrity and proves the DID of the issuer. -The proof section embedded in a credential may also include additional metadata. -The following metadata properties can be configured by the framework and are optional and omitted by default: - -- **Created**: Timestamp of when the credential was signed, recommended. -- **Expires**: Timestamp after which the signature is no longer considered valid. Implementers should prefer to set the dedicated **Expiration Date** property on credentials instead. -- **Proof Purpose**: Indicates the purpose of the signature. - - **AssertionMethod**: To assert a claim. The signing verification method must have an [`assertionMethod`](https://www.w3.org/TR/did-core/#assertion) relationship to be valid. - - **Authentication**: To authenticate the signer. The signing verification method must have an [`authentication`](https://www.w3.org/TR/did-core/#authentication) relationship to be valid. - -Most verifiable credentials should be signed with the assertion method proof purpose -to clearly indicate that the signature is asserting a claim and restrict it to valid verification methods. -Whereas a proof may be attached to a [verifiable presentation](./../../explanations/verifiable-presentations.mdx) for authentication purposes. +## Signing {#signing} -Other metadata fields such as `challenge` and `domain` may be included, however they are more pertinent for [verifiable presentations](./../../explanations/verifiable-presentations.mdx). +After preparing the verifiable credential, the issuer creates a signed JWT containing VC in the claims using one of their private keys. This is what allows verifiers to independently validate the credential using the corresponding public key from the issuer's DID Document. ## Validation @@ -71,7 +52,7 @@ Verifiers should ensure certain properties of a credential are valid when receiv The IOTA Identity Framework supports the following checks during credential validation: - **Semantic structure**: Ensures the credential adheres to the specification. -- **Proof**: Verifies the signature against the DID Document of the issuer. +- **Signature**: Verifies the JWS against the DID Document of the issuer. - **Optional validations**: Additional checks on credential properties, and the signature can be configured by specifying [Validation Options](#validation-options). ### Validation Options @@ -80,7 +61,7 @@ These options specify conditions that specific properties in a credential must s - **Expiry Date**: Check that the [`expirationDate`](https://www.w3.org/TR/vc-data-model/#expiration) property, if present, is not before a specific datetime. Defaults to the current datetime if unset. - **Issuance Date**: Check that that [`issuanceDate`](https://www.w3.org/TR/vc-data-model/#issuance-date) property, if present, is not after a specific datetime. Defaults to the current datetime if unset. -- **Verifier Options**: Validates aspects of the credential signature and its metadata, see [Proof Options](#proof-options). +- **Verifier Options**: Validates aspects of the credential signature. ## Sharing Verifiable Credentials @@ -102,14 +83,14 @@ In this example, the issuer signs a `UniversityDegreeCredential` with Alice's na ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs#L67-L98 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/5_create_vc.rs#L67-L98 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L51-L74 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L51-L74 ``` @@ -123,14 +104,14 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0 ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs#L105-L113 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/5_create_vc.rs#L105-L113 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L83-L88 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L83-L88 ``` @@ -146,14 +127,14 @@ allowing Alice to take control of it and share it with anyone. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/5_create_vc.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx index 51efdcd78ee..25bd0cfb647 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx @@ -36,14 +36,14 @@ Each verifiable credential is associated with a unique index in the list. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs#L167 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/7_revoke_vc.rs#L167 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L156 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L156 ``` @@ -94,14 +94,14 @@ precise control over which credential is revoked. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs#L197-L204 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/7_revoke_vc.rs#L197-L204 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L192C1-L195 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L192C1-L195 ``` @@ -115,14 +115,14 @@ The following code exemplifies how you can revoke a [Verifiable Credential (VC)] ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/7_revoke_vc.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx index 7ae2620df99..ba5dc8874cb 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx @@ -13,8 +13,8 @@ import TabItem from '@theme/TabItem'; The IOTA Identity Framework enables holders tos easily construct [verifiable presentations](./../../explanations/verifiable-presentations.mdx). -As demonstrated in the [example](#example), -holders only need to pass in their credentials to present and sign the presentation. +As demonstrated in the [example](#example-code), +holders only need to pass in their credentials to create a JWT presentation. ## Properties @@ -34,49 +34,27 @@ However, the holder property should be included to satisfy [subject-holder relat After creation, the holder signs the verifiable presentation using a private key linked to one of the verification methods in their DID Document and transmits it to a verifier for validation. -## Proof Options +## Creation and Validation -A digital signature on a verifiable presentation provides data integrity, +Verifiable presentation can be issued as a JWT that provides data integrity, and also proves the [DID](../../explanations/decentralized-identifiers.mdx) of the holder. -### Metadata Properties - -The proof section embedded in a presentation may also include additional metadata. - -The following metadata properties can be configured by the framework and are optional and omitted by default: - -- **Created**: Timestamp of when the presentation was signed. -- **Expires**: Timestamp after which the presentation is no longer considered valid. -- **Challenge**: Arbitrary random string. Sent by the verifier and mitigates replay attacks; should be sufficiently random and uniquely generated per presentation request. -- **Domain**: Arbitrary string. Sent by the verifier and can help mitigate replay attacks when used with a challenge. -- **Proof Purpose**: Indicates the purpose of the signature. - - **AssertionMethod**: To assert a claim. The signing verification method must have an [`assertionMethod`](https://www.w3.org/TR/did-core/#assertion) relationship to be valid. - - **Authentication**: To authenticate the signer. The signing verification method must have an [`authentication`](https://www.w3.org/TR/did-core/#authentication) relationship to be valid. - :::note -Verifiers should always send a challenge and domain +Verifiers should always send a challenge to [mitigate replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations). - ::: -A verifier could also choose to ignore some or all of these options. -See [Proof Verifier Options](#proof-verifier-options) for more information. - -## Validation The IOTA Identity Framework provides several options for verifiers to validate various sections of a verifiable presentation. -See the [example](#example) for a demonstration of how to validate a presentation. +See the [example](#example-code) for a demonstration of how to validate a presentation. The framework checks: - **Semantic structure**: Ensures the presentation and its credentials adhere to the specification. - **Presentation proof**: Verifies the presentation signature against the DID Document of the holder. - **Credential proofs**: Verifies the credential signatures against the DID Documents of their respective issuers. -- **Optional validations**: Additional checks on signatures and credential fields can be configured by the verifier. -Note that a verifier may specify which DID Documents to use for the holder and issuers. -Otherwise, they are resolved from the Tangle automatically. Currently, the following are **not** checked automatically: @@ -91,25 +69,6 @@ against the given options. The default validation behavior may be modified by the following options. -### Proof Verifier Options - -While the framework always verifies that the digital signature on a verifiable presentation is valid, -a verifier may validate additional fields in the proof on a presentation. -Notably, to mitigate potential [replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations), -a verifier should always check that the challenge and domain fields match what was sent to the holder when -requesting the presentation. - -The following options are available: - -- **Method Scope**: check the signing verification method has a particular [verification relationship](https://www.w3.org/TR/did-core/#verification-relationships). Overridden by the proof purpose check. -- **Method Type**: check the signing verification method has a particular type. -- **Challenge**: check the challenge field matches this string. -- **Domain**: check the domain field matches this string. -- **Proof Purpose**: require a specific purpose on the proof. See [Proof Options](#proof-options). -- **Allow Expired**: accept proofs where the current datetime is after their expiration. Default is to reject expired proofs. - -See [Proof Options](#proof-options) for more information on setting these properties as a holder when signing a verifiable presentation. - ## Subject-Holder Relationship Specifies the expected relationship between the holder that signed the verifiable presentation and the subject @@ -117,7 +76,7 @@ specified in each [verifiable credential](./../../explanations/verifiable-creden This can be restricted by the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property, which indicates that a verifiable credential must only be encapsulated into a verifiable presentation whose holder matches the credential subject. -By default, the framework always enforces that the holder matches the subject on all credentials. +By default, the framework always enforces that the holder matches the subject. The following options are available to modify that behavior: @@ -132,13 +91,6 @@ for further discussion on the different subject-holder relationships. ::: -### Credential Validation Options - -These options specify conditions that all credentials in a verifiable presentation must satisfy. - -- **Expiry Date**: Check that the [`expirationDate`](https://www.w3.org/TR/vc-data-model/#expiration) property, if present, is not before a specific datetime. Defaults to the current datetime if unset. -- **Issuance Date**: Check that the [`issuanceDate`](https://www.w3.org/TR/vc-data-model/#issuance-date) property, if present, is not after a specific datetime. Defaults to the current datetime if unset. -- **Verifier Options**: See [Proof Verifier Options](#proof-verifier-options) for details. ## Example Code @@ -150,14 +102,14 @@ and finally validate it with various options. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/6_create_vp.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/6_create_vp.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/6_create_vp.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/6_create_vp.ts ``` diff --git a/docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx b/docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx index 87787af978b..731572cfa72 100644 --- a/docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx +++ b/docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx @@ -22,7 +22,7 @@ The IOTA DID Method Specification describes a method of implementing the [Decent ## Data Types & Subschema Notation -Data types and subschemas used throughout this TIP are defined in [TIP-21](https://github.com/iotaledger/tips/blob/main/tips/TIP-0021/tip-0021.md). +Data types and subschemas used throughout this TIP are defined in [TIP-21](https://github.com/iotaledger/tips/blob/v1.0.0/tips/TIP-0021/tip-0021.md). ## Introduction @@ -36,13 +36,13 @@ Data stored in an output and covered by the storage deposit will be stored in _a ### Alias Output -The [Alias Output](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md#alias-output) is a specific implementation of the [UTXO state machine](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md#chain-constraint-in-utxo). Some of its relevant properties are: +The [Alias Output](https://github.com/iotaledger/tips/blob/v1.0.0/tips/TIP-0018/tip-0018.md#alias-output) is a specific implementation of the [UTXO state machine](https://github.com/iotaledger/tips/blob/v1.0.0/tips/TIP-0018/tip-0018.md#chain-constraint-in-utxo). Some of its relevant properties are: - **Amount**: the amount of IOTA coins held by the output. - **Alias ID**: 32 byte array, a unique identifier of the alias, which is the BLAKE2b-256 hash of the Output ID that created it. - **State Index**: A counter that must increase by 1 every time the alias is state transitioned. -- **State Metadata**: Dynamically sized array of arbitrary bytes with a length up to `Max Metadata Length`, as defined in [TIP-22](https://github.com/iotaledger/tips/blob/main/tips/TIP-0022/tip-0022.md). Can only be changed by the state controller. +- **State Metadata**: Dynamically sized array of arbitrary bytes with a length up to `Max Metadata Length`, as defined in [TIP-22](https://github.com/iotaledger/tips/blob/v1.0.0/tips/TIP-0022/tip-0022.md). Can only be changed by the state controller. - **Unlock Conditions**: - State Controller Address Unlock Condition - Governor Address Unlock Condition diff --git a/docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx b/docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx index e44aa2c11b0..8b90194d32d 100644 --- a/docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx +++ b/docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx @@ -175,7 +175,7 @@ This section describes the rationale behind some of the design decisions of this ### Compression and maximum size -Considering that messages published to the Tangle cannot exceed [32 KiB](https://github.com/iotaledger/tips/blob/main/tips/TIP-0006/tip-0006.md#message-validation) in size, and that larger messages have increased requirements, the use of compression was assessed. +Considering that messages published to the Tangle cannot exceed [32 KiB](https://github.com/iotaledger/tips/blob/v1.0.0/tips/TIP-0006/tip-0006.md#message-validation) in size, and that larger messages have increased requirements, the use of compression was assessed. The precise size of a serialized bitmap varies based on the number and distribution of revoked indices. When indices are revoked uniformly randomly, roughly 100,000 - 200,000 can be achieved in a DID Document with compression, and significantly more if consecutive indices are revoked. ZLIB [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)] was chosen for having a free and open source software licence and being one of the most widely used compression schemes, which enhances the accessibility of this specification. Some other assessed algorithms produced only marginally better compression ratios but had far fewer existing implementations across different programming languages. diff --git a/docs/build/identity.rs/1.1/docs/contact.mdx b/docs/build/identity.rs/1.1/docs/contact.mdx new file mode 100644 index 00000000000..8b7ebd10372 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/contact.mdx @@ -0,0 +1,17 @@ +--- +title: Contact +sidebar_label: Contact +description: Get in touch with the project maintainers. +image: /img/Identity_icon.png +keywords: + - Contact + - GitHub + - Maintainers +--- + +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/). diff --git a/docs/build/identity.rs/1.1/docs/contribute.mdx b/docs/build/identity.rs/1.1/docs/contribute.mdx new file mode 100644 index 00000000000..a0eaf770efa --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/contribute.mdx @@ -0,0 +1,49 @@ +--- +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 +keywords: + - Contribute + - GitHub + - Identity Initiative + - Documentation + - Discord + - 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](/identity.rs/contribute#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: diff --git a/docs/build/identity.rs/1.1/docs/explanations/about-alias-outputs.mdx b/docs/build/identity.rs/1.1/docs/explanations/about-alias-outputs.mdx new file mode 100644 index 00000000000..c35fae16080 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/explanations/about-alias-outputs.mdx @@ -0,0 +1,64 @@ +--- +title: Alias Outputs +description: UTXO Alias Ouput +image: /img/Identity_icon.png +keywords: + - public keys + - utxo + - Method Specification + - Decentralized Identifiers + - overview + - DLT +--- + +# 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](/learn/protocols/stardust/core-concepts/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 baed on the unspent transaction output (_UTXO_) model, +as well as the features of the [Stardust](/introduction/stardust/explanations/what_is_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](/learn/protocols/stardust/core-concepts/multi-asset-ledger/). 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](/learn/protocols/stardust/core-concepts/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`. diff --git a/docs/build/identity.rs/1.1/docs/explanations/decentralized-identifiers.mdx b/docs/build/identity.rs/1.1/docs/explanations/decentralized-identifiers.mdx new file mode 100644 index 00000000000..0ef071011eb --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/explanations/decentralized-identifiers.mdx @@ -0,0 +1,144 @@ +--- +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 +keywords: + - public keys + - Method Specification + - Decentralized Identifiers + - overview + - DLT +--- + +# 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](/identity.rs/references/specifications/iota-did-method-spec/). 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](/identity.rs/references/specifications/iota-did-method-spec/). +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](/learn/protocols/stardust/core-concepts/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](/learn/protocols/stardust/core-concepts/multi-asset-ledger/). + +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](/stronghold.rs/welcome/ 'Stronghold is an open-source software library that was originally built to protect IOTA Seeds, but can be used to protect any digital secret.') solution +for managing secrets securely, without requiring developers to reinvent the security wheel. diff --git a/docs/build/identity.rs/1.1/docs/explanations/verifiable-credentials.mdx b/docs/build/identity.rs/1.1/docs/explanations/verifiable-credentials.mdx new file mode 100644 index 00000000000..7fce9d87eab --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/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 +keywords: + - verifiable + - credentials + - person +--- +# 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. + diff --git a/docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx b/docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx new file mode 100644 index 00000000000..a0a68dafc3e --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/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. diff --git a/docs/build/identity.rs/1.1/docs/faq.mdx b/docs/build/identity.rs/1.1/docs/faq.mdx new file mode 100644 index 00000000000..8ed2b4ce200 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/faq.mdx @@ -0,0 +1,53 @@ +--- +title: Frequently Asked Questions +sidebar_label: FAQ +description: Frequently Asked Question regarding IOTA Identity. +image: /img/Identity_icon.png +keywords: + - FAQ + - Frequently Asked Question + - Troubleshooting + - IOTA Identity +--- + +This page contains frequently asked questions regarding the Identity Library and Self-Sovereign Identity in general. + +### What programming languages are supported by the IOTA Identity framework? + +We currently provide a Rust library and a JavaScript library for both the browser and Node.js via WebAssembly (Wasm) bindings. See the "Programming Languages" section for more information. + +### Do I need to have IOTA tokens to start building with IOTA Identity? + +You need IOTA tokens to create identities, in order to pay the storage deposit. + +### How do I prove control over my DID? + +Control over an identity is ultimately tied to the control over cryptographic key material (something you have). + +### How do I store my private keys? + +Theoretically, you can store the keys however you like. Where possible, we provide a secure default using IOTA Stronghold, a secure software implementation for isolating digital secrets with encrypted storage. For even better guarantees, you could look into hardware-based key storage. + +### Do I need a Permanode to use IOTA Identity? + +You can get started without one, but currently, you require access to a Permanode (a node that stores the entire history of the Tangle) to reliably resolve the history of identities. + +### Can I use IOTA Identity on Android or iOS? + +We currently do not supply dedicated bindings for Kotlin or Swift. There has been some success running the Wasm bindings on mobile, however. + +### Can I use IOTA Identity on embedded devices? + +We currently do not supply dedicated bindings catering to embedded devices with restricted capabilities. You can try to compile the Rust library for your target platform or use a gateway in front of the devices to handle IOTA Identity interactions. + +### What should I do if my private key is compromised? + +If you still have control over your identity, rotate the key material ASAP! If an attacker has locked you out of your identity, there is not much you can do. Notify contacts that your identity has been compromised and start fresh with a new one. For this reason, we suggest using different keys for day-to-day signing and authentication operations and instead storing private keys capable of updating your DID Document securely and separately. + +### Are verifiable credentials stored on the Tangle? + +Verifiable credentials, particularly those with personal identifiable information, are supposed to be stored securely off-Tangle on user devices or systems. As a user, you are in charge of storing your credentials securely and sharing them with other parties on a need-to-know basis. + +### Do I need to hide my DID? Will people be able to identify me by my DID? + +A DID Document should not contain any information linking back to you as a person. However, there is the chance of entities correlating information about you from your DID if used across multiple issuers and verifiers. To minimize this risk, it is advisable to use different DIDs for different use cases. diff --git a/docs/build/identity.rs/1.1/docs/getting-started/rust.mdx b/docs/build/identity.rs/1.1/docs/getting-started/rust.mdx new file mode 100644 index 00000000000..b9560fba4e6 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/getting-started/rust.mdx @@ -0,0 +1,68 @@ +--- +sidebar_label: Rust +description: Getting started with the IOTA Identity Rust Library. +image: /img/Identity_icon.png +keywords: + - Rust + - Identity +--- +# Getting Started with Rust + +## Requirements + +- [Rust](https://www.rust-lang.org/) (>= 1.62) +- [Cargo](https://doc.rust-lang.org/cargo/) (>= 1.62) + +## Include the Library + +To include IOTA Identity in your project, add it as a dependency in your `Cargo.toml`: + +### Latest Stable Release + +This version is published to crates.io and is **stable**, following semantic versioning. + +```toml +[dependencies] +identity_iota = { version = "1.1.0" } +``` + +### Development Release + +This version matches the `main` branch of this repository. It has all the **latest features**, but as such, it **may also have undocumented breaking changes**. + +```toml +[dependencies] +identity_iota = { git = "https://github.com/iotaledger/identity.rs", branch = "main"} +``` + +## Examples + +To try out the [examples](https://github.com/iotaledger/identity.rs/tree/v1.1.0/examples), you should: + +1. Clone the repository: + +```bash +git clone https://github.com/iotaledger/identity.rs +``` + +2. Build the repository: + +```bash +cargo build +``` + +3. Run your first example: + +```bash +cargo run --example getting_started +``` + +## API Reference + +You can find the API reference for the Rust library on [docs.rs](https://docs.rs/identity_iota/latest/identity_iota/index.html). + +If you would like to build the documentation, locally you can do so with the following command: + +``` +RUSTDOCFLAGS='--cfg docsrs' cargo +nightly doc -p identity_iota --all-features --no-deps --open +``` diff --git a/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx b/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx new file mode 100644 index 00000000000..1126e5db643 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx @@ -0,0 +1,339 @@ +--- +sidebar_label: Wasm +description: Getting started with the IOTA Identity WASM Library. +image: /img/Identity_icon.png +keywords: + - WASM + - install + - npm + - yarn + - build + - nodejs + - webpack +--- +# Getting Started with Wasm + +## Minimum Requirements + +- [Node.js](https://nodejs.org/en) (>= `v16`) + +## Install the Library + +You can install the latest stable version of the library by running the following command: + +```bash npm2yarn +npm install @iota/identity-wasm +``` + +## Build the Library + +Alternatively, you can build the bindings yourself if you have Rust installed. +If not, refer to [rustup.rs](https://rustup.rs) for the installation. + +### Requirements + +- [Node.js](https://nodejs.org/en) (>= `v16`) +- [Rust](https://www.rust-lang.org/) (>= 1.62) +- [Cargo](https://doc.rust-lang.org/cargo/) (>= 1.62) + +### 1. Install `wasm-bindgen-cli` + +If you want to build the library from source, +you will first need to manually install [`wasm-bindgen-cli`](https://github.com/rustwasm/wasm-bindgen). +A manual installation is required because we use the [Weak References](https://rustwasm.github.io/wasm-bindgen/reference/weak-references.html) feature, +which [`wasm-pack` does not expose](https://github.com/rustwasm/wasm-pack/issues/930). + +```bash +cargo install --force wasm-bindgen-cli +``` + +### 2. Install Dependencies + +After installing `wasm-bindgen-cli`, you can install the necessary dependencies using the following command: + +```bash npm2yarn +npm install +``` + +### 3. Build + + + + + +You can build the bindings for `node.js` using the following command: + +```bash npm2yarn +npm run build:nodejs +``` + + + + + +You can build the bindings for the `web` using the following command: + +```bash npm2yarn +npm run build:web +``` + + + + +## NodeJS Usage + +The following code creates a new IOTA DID Document suitable for publishing to a local test network, like the +[IOTA Sandbox](/iota-sandbox/welcome/). + + + + +```typescript +const { + KeyPair, + KeyType, + MethodScope, + IotaDocument, + IotaVerificationMethod, + IotaService, + MethodRelationship, + IotaIdentityClient, +} = require('@iota/identity-wasm/node'); +const { Client } = require('@iota/client-wasm/node'); + +// The endpoint of the IOTA node to use. +const API_ENDPOINT = 'http://127.0.0.1:14265'; + +/** Demonstrate how to create a DID Document. */ +async function main() { + // Create a new client with the given network endpoint. + const client = new Client({ + primaryNode: API_ENDPOINT, + localPow: true, + }); + + const didClient = new IotaIdentityClient(client); + + // Get the Bech32 human-readable part (HRP) of the network. + const networkHrp = await didClient.getNetworkHrp(); + + // Create a new DID document with a placeholder DID. + // The DID will be derived from the Alias Id of the Alias Output after publishing. + const document = new IotaDocument(networkHrp); + + // Insert a new Ed25519 verification method in the DID document. + let keypair = new KeyPair(KeyType.Ed25519); + let method = new IotaVerificationMethod( + document.id(), + keypair.type(), + keypair.public(), + '#key-1', + ); + document.insertMethod(method, MethodScope.VerificationMethod()); + + // Attach a new method relationship to the existing method. + document.attachMethodRelationship( + document.id().join('#key-1'), + MethodRelationship.Authentication, + ); + + // Add a new Service. + const service = new IotaService({ + id: document.id().join('#linked-domain'), + type: 'LinkedDomains', + serviceEndpoint: 'https://iota.org/', + }); + document.insertService(service); + + console.log(`Created document `, JSON.stringify(document.toJSON(), null, 2)); +} + +main(); +``` + +### Expected Output + +``` +Created document { + "doc": { + "id": "did:iota:0x0000000000000000000000000000000000000000000000000000000000000000", + "verificationMethod": [ + { + "id": "did:iota:0x0000000000000000000000000000000000000000000000000000000000000000#key-1", + "controller": "did:iota:0x0000000000000000000000000000000000000000000000000000000000000000", + "type": "Ed25519VerificationKey2018", + "publicKeyMultibase": "z4SxypezRxr1YdMAJBePfHGxZ9hNZ53WVixZq3PbUcztW" + } + ], + "authentication": [ + "did:iota:0x0000000000000000000000000000000000000000000000000000000000000000#key-1" + ], + "service": [ + { + "id": "did:iota:0x0000000000000000000000000000000000000000000000000000000000000000#linked-domain", + "type": "LinkedDomains", + "serviceEndpoint": "https://iota.org/" + } + ] + }, + "meta": { + "created": "2022-09-09T11:29:32Z", + "updated": "2022-09-09T11:29:32Z" + } +} +``` + +## Web Usage + +### Set Up + +The library loads the WASM file with an HTTP GET request, so you must copy the `.wasm` file the root of the `dist` folder. + +#### Rollup + +- Install `rollup-plugin-copy`: + +```bash npm2yarn +npm install rollup-plugin-copy --save-dev +``` + +- Add the copy plugin usage to the `plugins` array under `rollup.config.js`: + +```js +// Include the copy plugin +import copy from 'rollup-plugin-copy'; + +// Add the copy plugin to the `plugins` array of your rollup config: +copy({ + targets: [ + { + src: 'node_modules/@iota/client-wasm/web/wasm/client_wasm_bg.wasm', + dest: 'public', + rename: 'client_wasm_bg.wasm', + }, + { + src: 'node_modules/@iota/identity-wasm/web/identity_wasm_bg.wasm', + dest: 'public', + rename: 'identity_wasm_bg.wasm', + }, + ], +}); +``` + +#### Webpack + +- Install `copy-webpack-plugin`: + +```bash npm2yarn +npm install copy-webpack-plugin --save-dev +``` + +```js +// Include the copy plugin +const CopyWebPlugin= require('copy-webpack-plugin'); + +// Add the copy plugin to the `plugins` array of your webpack config: + +new CopyWebPlugin({ + patterns: [ + { + from: 'node_modules/@iota/client-wasm/web/wasm/client_wasm_bg.wasm', + to: 'client_wasm_bg.wasm' + }, + { + from: 'node_modules/@iota/identity-wasm/web/identity_wasm_bg.wasm', + to: 'identity_wasm_bg.wasm' + } + ] +}), +``` + +### Web Usage Example + +```typescript +import * as client from '@iota/client-wasm/web'; +import * as identity from '@iota/identity-wasm/web'; + +/** Demonstrate how to create a DID Document. */ +async function createDocument() { + // Create a new client with the given network endpoint. + const iotaClient = new client.Client({ + primaryNode: API_ENDPOINT, + localPow: true, + }); + + const didClient = new identity.IotaIdentityClient(iotaClient); + + // Get the Bech32 human-readable part (HRP) of the network. + const networkHrp = await didClient.getNetworkHrp(); + + // Create a new DID document with a placeholder DID. + // The DID will be derived from the Alias Id of the Alias Output after publishing. + const document = new identity.IotaDocument(networkHrp); + + // Insert a new Ed25519 verification method in the DID document. + let keypair = new identity.KeyPair(identity.KeyType.Ed25519); + let method = new identity.IotaVerificationMethod( + document.id(), + keypair.type(), + keypair.public(), + '#key-1', + ); + document.insertMethod(method, identity.MethodScope.VerificationMethod()); + + // Attach a new method relationship to the existing method. + document.attachMethodRelationship( + document.id().join('#key-1'), + identity.MethodRelationship.Authentication, + ); + + // Add a new Service. + const service = new identity.IotaService({ + id: document.id().join('#linked-domain'), + type: 'LinkedDomains', + serviceEndpoint: 'https://iota.org/', + }); + document.insertService(service); + + console.log(`Created document `, JSON.stringify(document.toJSON(), null, 2)); +} + +client + .init() + .then(() => identity.init()) + .then(() => { + await createDocument(); + }); + +// or + +(async () => { + await client.init(); + await identity.init(); + + await createDocument(); +})(); + +// Default path is "identity_wasm_bg.wasm", but you can override it like this +await identity.init('./static/identity_wasm_bg.wasm'); +``` + +You need to call `identity.init().then()`, +or `await identity.init()` to load the Wasm file from the server if not available, +because of that **it will only be slow for the first time**. + +## Examples in the Wild + +You may find it useful to see how the WASM bindings are being used in existing applications: + +- [Zebra IOTA Edge SDK](https://github.com/ZebraDevs/Zebra-Iota-Edge-SDK) (mobile apps using Capacitor.js + Svelte) + +## [API Reference](/identity.rs/references/api/wasm) + +## [Examples](https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/README.md) diff --git a/docs/build/identity.rs/1.1/docs/glossary.mdx b/docs/build/identity.rs/1.1/docs/glossary.mdx new file mode 100644 index 00000000000..a4595fdccf2 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/glossary.mdx @@ -0,0 +1,141 @@ +--- +description: Glossary for IOTA Identity, defines the terms used in this specification and throughout decentralized identifier infrastructure. +image: /img/Identity_icon.png +keywords: + - W3C + - terminology + - IOTA + - verification method + - verifiable data registry + - reference +--- + +# Glossary + +This section defines the terms used in this specification, [sourced from W3](https://www.w3.org/TR/did-core/#terminology), and throughout decentralized identifier infrastructure. A link to these terms is included whenever they appear in this specification. + +The first part of the glossary describes the terminology by the W3C. The [second describes](#iota-terminology) the terminology for IOTA-related topics. + +## W3C Terminology + +### Authentication + +A process (typically some type of protocol) by which an entity can prove it has a specific attribute or controls a specific secret using one or more verification methods. With DIDs, a common example would be proving control of the private key associated with a public key published in a DID document. + +### Decentralized Identifier (DID) + +A globally unique persistent identifier that does not require a centralized registration authority because it is generated or registered cryptographically. The generic format of a DID is defined in the DID Core specification. A specific DID scheme is defined in a DID method specification. Many, but not all, DID methods make use of distributed ledger technology (DLT) or some other form of decentralized network. + +### Decentralized Identity Management + +A type of identity management that is based on the use of decentralized identifiers. Decentralized identity management extends authority for identifier generation, registration, and assignment beyond traditional roots of trust, such as X.500 directory services, the Domain Name System, and most national ID systems. + +### DID Controller + +An entity that can make changes to a DID document. A DID may have more than one DID controller. The DID controller(s) can be denoted by the optional controller property at the top level of the DID document. Note that one DID controller may be the DID subject. + +### DID Delegate + +An entity to whom a DID controller has granted permission to use a verification method associated with a DID via a DID document. For example, a parent who controls a child's DID document might permit the child to use their personal device for authentication purposes. In this case, the child is the DID delegate. The child's personal device would contain the private cryptographic material enabling the child to authenticate using the DID. However, the child may not be permitted to add other personal devices without the parent's permission. + +### DID Document + +A set of data describing the DID subject, including mechanisms, such as public keys and pseudonymous biometrics, that the DID subject or a DID delegate can use to authenticate itself and prove its association with the DID. A DID document may also contain other attributes or claims describing the DID subject. A DID document may have one or more different representations as defined in [§ 6. Representations](https://www.w3.org/TR/did-core/#representations) or in the W3C DID Specification Registries [DID-SPEC-REGISTRIES](https://www.w3.org/TR/did-core/#bib-did-spec-registries). + +### DID Fragment + +The portion of a DID URL that follows the first hash sign character (#). DID fragment syntax is identical to URI fragment syntax. + +### DID Method + +A definition of how a specific DID scheme must be implemented to work with a specific verifiable data registry. A DID method is defined by a DID method specification, which must specify the precise operations by which DIDs are created, resolved, and deactivated, where DID documents are written and updated. [See W3's Methods](https://www.w3.org/TR/did-core/#methods). + +### DID Path + +The portion of a DID URL that begins with and includes the first forward-slash (/) character and ends with either a question mark (?) character or a fragment hash sign (#) character (or the end of the DID URL). DID path syntax is identical to URI path syntax. See [Path](https://www.w3.org/TR/did-core/#path). + +### DID Query + +The portion of a DID URL that follows and includes the first question mark character (?). DID query syntax is identical to URI query syntax. See [Query](https://www.w3.org/TR/did-core/#query). + +### DID Resolution + +The function that takes, as an input, a DID and a set of input metadata and returns a DID document in a conforming representation plus additional metadata. This function relies on the "Read" operation of the applicable DID method. The inputs and outputs of this function are defined in [Resolution](https://www.w3.org/TR/did-core/#resolution). + +### DID Resolver + +A DID resolver is a software or hardware component that performs the DID resolution function by taking a DID as input and producing a conforming DID document as output. + +### DID Scheme + +The formal syntax of a decentralized identifier. The generic DID scheme begins with the prefix "did:" as defined in the section of the DID Core specification. Each DID method specification must define a specific DID scheme that works with that particular DID method. In a specific DID method scheme, the DID method name must follow the first colon and terminate with the second colon, such as "did:example:". + +### DID Subject + +The entity identified by a DID and described by a DID document. A DID has exactly one DID subject. Anything can be a DID subject: a person, group, organization, physical thing, digital thing, logical thing, and so on. + +### DID URL + +A DID plus any additional syntactic component that conforms to the definition in § 3.2 DID URL Syntax. This includes an optional DID path, optional DID query (and its leading ? character), and optional DID fragment (and its leading # character). + +### DID URL Dereferencing + +The function that takes as its input a DID URL, a DID document, plus a set of dereferencing options, and returns a resource. This resource may be a DID document plus additional metadata, or it may be a secondary resource contained within the DID document, or it may be a resource entirely external to the DID document. If the function begins with a DID URL, it uses the DID resolution function to fetch a DID document indicated by the DID contained within the DID URL. The dereferencing function can then perform additional processing on the DID document to return the dereferenced resource indicated by the DID URL. The inputs and outputs of this function are defined in [DID URL Dereferencing](https://www.w3.org/TR/did-core/#did-url-dereferencing). + +## IOTA Terminology + +### Distributed Ledger (DLT) + +A distributed database in which the various nodes use a consensus protocol to maintain a shared ledger in which each transaction is cryptographically signed and chained to the previous transaction. + +### Public Key Description + +A data object contained inside a DID document that contains all the metadata necessary to use a public key or verification key. + +### Resource + +As defined by [RFC3986](https://www.rfc-editor.org/rfc/rfc3986): "...the term 'resource' is used in a general sense for whatever might be identified by a URI." Similarly, any resource may serve as a DID subject identified by a DID + +### Representation + +As defined for HTTP by [RFC7231](https://httpwg.org/specs/rfc7231.html): "information that is intended to reflect a past, current, or desired state of a given resource, in a format that can be readily communicated via the protocol, and that consists of a set of representation metadata and a potentially unbounded stream of representation data." A DID document is a representation of information describing a DID subject. The [Representations](https://www.w3.org/TR/did-core/#representations) section of the DID Core specification defines several representation formats for a DID document. + +### Service + +A means of communicating or interacting with the DID subject or associated entities via one or more service endpoints. Examples include discovery services, agent services, social networking services, file storage services, and verifiable credential repository services. + +### Service Endpoint + +A network address (such as an HTTP URL) at which a service operates on behalf of a DID subject. + +### Uniform Resource Identifier (URI) + +The standard identifier format for all resources on the World Wide Web as defined by [RFC3986](https://www.rfc-editor.org/rfc/rfc3986). A DID is a type of URI scheme. + +### Verifiable Credential + +A standard data model and representation format for cryptographically-verifiable digital credentials as defined by the W3C [VC-DATA-MODEL](https://www.w3.org/TR/vc-data-model/). + +### Verifiable Data Registry + +A system that facilitates the creation, verification, updating, or deactivation of decentralized identifiers and DID documents. A verifiable data registry may also be used for other cryptographically-verifiable data structures, such as verifiable credentials. For more information, see [VC-DATA-MODEL](https://www.w3.org/TR/vc-data-model/). + +### Verifiable Timestamp + +A verifiable timestamp enables a third-party to verify that a data object existed at a specific moment in time and that it has not been modified or corrupted since that moment in time. If the data integrity were to be reasonably modified or corrupted since that moment in time, the timestamp is not verifiable. + +### Verification Method + +A set of parameters that can be used together with a process or protocol to independently verify a proof. For example, a public key can be used as a verification method with respect to a digital signature; in such usage, it verifies that the signer possessed the associated private key. + +"Verification" and "proof" in this definition are intended to apply broadly. For example, a public key might be used during Diffie-Hellman key exchange to negotiate a shared symmetric key for encryption. This guarantees the integrity of the key agreement process. It is thus another type of verification method, even though descriptions of the process might not use the words "verification" or "proof." + +### Verification Relationship + +An expression of the relationship between the DID subject and a verification method. An example of a verification relationship is [authentication](https://www.w3.org/TR/did-core/#authentication). + +### Universally Unique Identifier (UUID) + +A type of globally unique identifier defined by [RFC4122](https://www.rfc-editor.org/rfc/rfc4122). UUIDs are similar to DIDs in that they do not require a centralized registration authority. UUIDs differ from DIDs in that they are not resolvable or cryptographically verifiable. +In addition to the terminology above, this specification also uses terminology from the [INFRA](https://infra.spec.whatwg.org/) specification to formally define the abstract data model. When [INFRA](https://infra.spec.whatwg.org/) terminology is used, such as string, ordered set, and map, it is linked directly to that specification. +In addition to the terminology above, this specification also uses terminology from the [INFRA] specification to formally define the abstract data model. When [INFRA] terminology is used, such as string, ordered set, and map, it is linked directly to that specification. diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx new file mode 100644 index 00000000000..c6130680c8a --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx @@ -0,0 +1,180 @@ +--- +title: Creating a Decentralized Identity +sidebar_label: Create and Publish +description: Create DID Documents and publish them to the Tangle +image: /img/Identity_icon.png +keywords: + - Documents + - DID + - Tangle + - Create + - Publish +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +If you want to benefit from Self-Sovereign Identity, +you need to create a [Decentralized Identity](../../explanations/decentralized-identifiers.mdx). +This identity consists of many parts that have different functions. + +:::note DID method Specification + +Note that the Iota Identity Framework follows [IOTA DID Method Specification](../../references/specifications/iota-did-method-spec.mdx). + +::: + +## Identity Generation Process + + +### 1. Get Funds to Cover the Storage Deposit + +The first thing you will need to generate an identity is an address with enough funds to cover +the [Storage Deposit](../../explanations/about-alias-outputs.mdx#storage-deposit). +In test networks, you can use a [faucet](https://faucet.testnet.shimmer.network/) to request funds. + +:::tip + +If you want to use the main Shimmer or IOTA networks, +you will need an output with actual Shimmer or IOTA funds to create a new Alias Output that represents a DID. + +::: + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/0_create_did.rs#L52 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L40-L51 +``` + + + +
+ +### 2. Create the Content for the DID Document + +As a bare minimum, a [DID document](../../explanations/decentralized-identifiers.mdx) needs at least one verification method. + +At this point, the DID itself is unknown since the Alias Output is not published yet and didn't get an `Alias ID` assigned. + +:::tip + +You can use a placeholder `did:iota:0x0000000000000000000000000000000000000000000000000000000000000000` to reference +the DID inside the document. + +::: + +
+ + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/0_create_did.rs#L59-L71 +``` + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L55C44-L65 +``` + + + +
+ +### 3. Construct a New Alias Output + +Next, you need to construct a new [Alias Output](../../explanations/about-alias-outputs.mdx) that includes the +DID Document in the [State Metadata](../../explanations/about-alias-outputs.mdx). +The created Alias Output contains an encoded version of the DID Document in its `State Metadata`, and has the state +controller and the governor set to the generated Ed25519 address. + +Note that controllers don't need to be Ed25519 addresses, they can be any type of output. +However, they must be unlocked in order perform a state or governance transition when the DID Document is updated or destroyed. + + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/0_create_did.rs#L75 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L70 +``` + + + +
+ +### 4. Publish the generated Alias Output. + +The byte cost for the document is automatically calculated and a new transaction is published that includes +the Basic Output as input and the newly generated Alias Output as output, as well as another Basic Output which contains +the remaining tokens. + +The DID is only known once the [Alias Output](../../explanations/about-alias-outputs.mdx) is successfully published, +since the DID's [Tag](../../references/specifications/iota-did-method-spec.mdx#iota-tag) contains the +[Alias ID](../../explanations/about-alias-outputs.mdx#alias-id). +Once the transaction is confirmed, the `Alias ID` is assigned, and the DID can be derived from it, +the DID Document is stored on the ledger and can be [resolved](resolve.mdx) using any node. + + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/0_create_did.rs#L78 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L74 +``` + + + +
+ +## Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/0_create_did.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/0_create_did.ts +``` + + + + +## Running Examples Locally + +In order to run the examples, you will need to run the [IOTA Sandbox](/iota-sandbox/welcome/) locally. + +If you want to use something different, you will need to modify the API and faucet endpoints in the examples to match your +setup. \ No newline at end of file diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx new file mode 100644 index 00000000000..aab81aa9bdd --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx @@ -0,0 +1,106 @@ +--- +title: Delete an IOTA Identity +sidebar_label: Delete +description: How to deactivate or destroy an IOTA Identity +image: /img/Identity_icon.png +keywords: + - Delete + - Deactivate + - Destroy +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +There are two approaches to delete an IOTA Identity, with different implications: + +- [Deactivate](#deactivate) +- [Destroy](#destroy) + +## Deactivate + +As detailed in the [IOTA DID Method Specification](../../references/specifications/iota-did-method-spec.mdx#deactivate), +the state controller of an IOTA Identity may [deactivate](https://www.w3.org/TR/did-core/#did-document-metadata) it by publishing an update that either: + +- deletes the contents of the DID Document entirely, leaving the state metadata empty, OR +- sets the `deactivated` field in the DID Document metadata to `true`. + +In both cases, the DID Document will be marked as `deactivated` when resolved. + +:::tip Reversible + +The identity can be reactivated at any time, by publishing an update restoring the DID Document's contents, +or unsetting the `deactivated` field in the metadata respectively, depending on how it was initially deactivated. + +Note that if the governor is different from the state controller, it cannot deactivate an identity directly because +it is disallowed from updating the DID Document, but it may [destroy](#destroy) it. + +::: + +### Example + +The following example demonstrates deactivating and reactivating an IOTA DID Document, +and optionally reclaiming the storage deposit. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/3_deactivate_did.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/3_deactivate_did.ts +``` + + + + +## Destroy + +Alternatively, you can [destroy](../../references/specifications/iota-did-method-spec.mdx#destroy) an IOTA Identity can be permanently. + +:::warning Irreversible + +Destroying an IOTA Identity is permanent and irreversible. + +::: + + +This is achieved by the governor of a DID publishing a transaction consuming the [Alias Output](../../references/specifications/iota-did-method-spec.mdx#alias-output) +containing the IOTA DID Document, without a corresponding Alias Output on the output side. + +Any coins and tokens in the Alias Output are reclaimed and can be sent to another address. + +:::warning + +Note that historical versions may still be stored off-ledger, or on a permanode, +so sensitive or Personal Identifiable Information (PII) should NEVER be stored in a DID Document. + +::: + +Even with a previous version available, a destroyed DID can never be restored. + +### Example + +The following example demonstrates how a governor destroys an IOTA Identity and sends the storage deposit back to itself. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/4_delete_did.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/4_delete_did.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx new file mode 100644 index 00000000000..7a9dbdb2066 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx @@ -0,0 +1,196 @@ +--- +title: Resolve an IOTA Identity +sidebar_label: Resolve +description: Explain how resolving works including arguments +image: /img/Identity_icon.png +keywords: + - Resolve +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +DID resolution is the process of fetching and decoding a [DID Document](https://www.w3.org/TR/did-core/#dfn-did-documents) corresponding to a given [DID](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers). +The [IOTA Identity framework](https://github.com/iotaledger/identity.rs) supports resolving DID Documents that are +stored on the IOTA and Shimmer networks and enables users to plug in handlers for additional methods. + +This is similar to, but not to be confused with, +the [W3C DID Resolution specification](https://w3c-ccg.github.io/did-resolution/), +which defines function signatures for resolution in the context of web or REST APIs, +whereas the IOTA Identity framework provides strongly-typed resolution for a better developer experience. + +This functionality is primarily provided by the `Resolver`, which can: + +- [Resolve IOTA DID Documents](#resolving-an-iota-did). +- [Resolve DID Documents from multiple DID methods](#resolving-multiple-did-methods). +- Resolve the DID Documents referenced in a verifiable presentation or credential. + +## Resolving an IOTA DID + +The following examples demonstrate how to resolve an IOTA DID Document from its DID. + +### Resolver + +Once you have configured a `Resolver` with a [`Client`](/iota-sdk/welcome), it will resolve +IOTA DID Documents according to the read procedure defined in the [IOTA DID Method Specification](../../references/specifications/iota-did-method-spec.mdx#read). +It fetches the latest [Alias Output](../../references/specifications/iota-did-method-spec.mdx#alias-output) from the network specified in the DID (see [DID Format](../../references/specifications/iota-did-method-spec.mdx#did-format)), +then extracts and validates the DID Document from it. + + + + +```rust +use identity_iota::iota::IotaDID; +use identity_iota::iota::IotaDocument; +use identity_iota::resolver::Resolver; +use iota_sdk::client::Client; + +#[tokio::main] +async fn main() -> anyhow::Result<()>{ + // Configure a client for the Shimmer testnet "rms". + let node_url = "https://api.testnet.shimmer.network/"; + let client = Client::builder() + .with_primary_node(node_url, None)? + .finish()?; + + // Construct a resolver using the client. + let mut resolver = Resolver::::new(); + resolver.attach_iota_handler(client); + + // Parse the DID and resolve its DID Document. + let did = IotaDID::parse("did:iota:rms:0x7b48b06232b8a1e7a31c314cab1ceedb84e2e9dd2b1fae79b67eaa4595f15e47")?; + let document: IotaDocument = resolver.resolve(&did).await?; + + Ok(()) +} +``` + + + + +```js +const { + Resolver, + IotaDID, + IotaIdentityClient, +} = require('@iota/identity-wasm/node'); +const { Client } = require('@iota/client-wasm/node'); + +// Configure a client for the Shimmer testnet "rms". +const nodeUrl = 'https://api.testnet.shimmer.network/'; +const client = new Client({ + primaryNode: nodeUrl, + localPow: true, +}); +const didClient = new IotaIdentityClient(client); + +// Construct a resolver using the client. +const resolver = new Resolver({ + client: didClient, +}); + +// Resolve the given did +const did = + 'did:iota:rms:0x7b48b06232b8a1e7a31c314cab1ceedb84e2e9dd2b1fae79b67eaa4595f15e47'; +const document = await resolver.resolve(did); +``` + + + + +### Client + +You can also use the [`Client`](/iota-sdk/welcome) directly to resolve individual DIDs from its configured network. + + + + +```rust +use identity_iota::iota::IotaDID; +use identity_iota::iota::IotaDocument; +use identity_iota::iota::IotaIdentityClientExt; +use iota_sdk::client::Client; + +#[tokio::main] +async fn main() -> anyhow::Result<()>{ + // Configure a client for the Shimmer testnet "rms". + let node_url = "https://api.testnet.shimmer.network/"; + let client = Client::builder() + .with_primary_node(node_url, None)? + .finish()?; + + // Parse the DID and resolve its DID Document. + let did = IotaDID::parse("did:iota:rms:0x7b48b06232b8a1e7a31c314cab1ceedb84e2e9dd2b1fae79b67eaa4595f15e47")?; + let document: IotaDocument = client.resolve_did(&did).await?; + Ok(()) +} +``` + + + + +```js +const { IotaDID, IotaIdentityClient } = require('@iota/identity-wasm/node'); +const { Client } = require('@iota/client-wasm/node'); + +// Configure a client for the Shimmer testnet "rms". +const nodeUrl = 'https://api.testnet.shimmer.network/'; +const client = new Client({ + primaryNode: nodeUrl, + localPow: true, +}); +const didClient = new IotaIdentityClient(client); + +// Parse the DID and resolve its DID Document. +const did = IotaDID.parse( + 'did:iota:rms:0x7b48b06232b8a1e7a31c314cab1ceedb84e2e9dd2b1fae79b67eaa4595f15e47', +); +const document = await didClient.resolveDid(did); +``` + + + + +## Advanced Resolver Configuration + +You can configure the `Resolver` to support many use cases by attaching custom resolution handlers. +This enables the `Resolver` to resolve multiple DID methods, as well as customizing how +a particular DID method (such as the IOTA method) gets resolved. + +This feature is mainly intended to be used together with the Resolver's convenience methods for +handling [verifiable presentations](../verifiable-presentations/create-and-validate.mdx) +and [credentials](./../../explanations/verifiable-credentials.mdx). + +### Resolving Multiple DID Methods + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/1_advanced/5_custom_resolution.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/1_advanced/4_custom_resolution.ts +``` + + + + +## Resolution for Verifiable Presentations + +When validating [verifiable presentations](./../verifiable-presentations/create-and-validate.mdx), you need to +resolve the DID Documents of the [verifiable credential](./../../explanations/verifiable-credentials.mdx) issuers +and presentation holder to verify their signatures. + +Resolving the necessary DID Documents is +[performed automatically when verifying presentations via the `Resolver`](../verifiable-presentations/create-and-validate.mdx#example) + +When direct access to these DID Documents is desired, the `Resolver` also provides standalone methods to: + +- Resolve a presentation holder's DID Document. +- Resolve the DID Documents of the issuers of the credentials in a verifiable presentation. +- Resolve the issuer's DID Document for a given verifiable credential. diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx new file mode 100644 index 00000000000..bfa317484d0 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx @@ -0,0 +1,534 @@ +--- +sidebar_label: Update +description: How DID Documents can be manipulated and how updates should be published +image: /img/Identity_icon.png +keywords: + - Documents + - DID + - Tangle + - Update + - Publish +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Update DID Documents + +You can extend DID Documents by adding [verification methods](#verification-methods), [services](#services) and custom properties. +A verification method adds public keys, which can be used to digitally sign things like a DID message or a verifiable credential, +while a service can provide metadata around the identity via URIs. + +## Verification Methods + +As demonstrated by the [example](#example) below, the IOTA Identity framework offers easy-to-use methods for adding +[verification methods](https://www.w3.org/TR/did-core/#verification-methods). + +### Properties + +You can specify the following properties for a verification method: + +- **id**: A [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) for the verification method. You can specify it by setting the [fragment](https://www.w3.org/TR/did-core/#fragment). +- **type**: Specifies the type of the verification method. The framework supports `Ed25519` and `X25519` key types. This property is automatically filled by the framework when specifying the verification material. +- **publicKeyMultibase**: A multi-base encoded public key which concludes the [verification material](https://www.w3.org/TR/did-core/#verification-material). This can be automatically generated by the framework or manually provided by users. + +## Verification Relationships + +[Verification relationships](https://www.w3.org/TR/did-core/#verification-relationships) express the relationship between the DID subject and the verification method. +You can use it to specify the purpose of the verification method. + +### Relationships + +The Identity Framework supports the following relationships: + +- **[Authentication](https://www.w3.org/TR/did-core/#authentication)**: Used to specify authentication methods for the DID subject. +- **[Assertion](https://www.w3.org/TR/did-core/#assertion)**: Used to verify verifiable credentials. +- **[Key Agreement](https://www.w3.org/TR/did-core/#assertion)**: Used for establishing secure communication channels. +- **[Capability Invocation](https://www.w3.org/TR/did-core/#capability-invocation)**: Can be used to authorize updates to the DID Document. +- **[Capability Delegation](https://www.w3.org/TR/did-core/#capability-delegation)**: A mechanism to delegate cryptographic capability to another party. + +Verification methods can be either [embedded or referenced](https://www.w3.org/TR/did-core/#referring-to-verification-methods). Referencing verification +methods allows them to be used by more than one verification relationship. +When you create a verification method using the Identity Framework, specifying the `MethodScope` option will result in an embedded verification method. +Leaving that option unset will create the verification method as a map entry of the `verificationMethod` property. +You can also add verification relationships afterward using references. + +:::note + +Updates to the DID Document are done through a state transition of the [Alias Output](../../references/specifications/iota-did-method-spec.mdx#alias-output) by its state controller. +The public key or address of the state controller does not need to be a verification method in the DID Document, +since it is defined in the containing Alias Output. + +::: + +## Services + +[Services](https://www.w3.org/TR/did-core/#services) allow you to add other ways of communicating with the DID subject. +An endpoint included in the DID Document can offer a way of reaching services for different purposes +like authentication, communicating, and discovery. + +### Properties + +You can specify the following properties for a service: + +- **id**: A [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) for referencing the service in the DID document. You can specify it by setting the [fragment](https://www.w3.org/TR/did-core/#fragment). +- **type**: A string used to maximize interoperability between services. The framework does not perform any checks on the content of this string. +- **serviceEndpoint**: A URL that points to the service endpoint. + +## Create Identity + +Before you can update anything, you will need to [create an Identity](./create.mdx). + + + + +```rust + // Create a new client to interact with the IOTA ledger. + let client: Client = Client::builder() + .with_primary_node(API_ENDPOINT, None)? + .finish() + .await?; + + // Create a new secret manager backed by a Stronghold. + let mut secret_manager: SecretManager = SecretManager::Stronghold( + StrongholdSecretManager::builder() + .password(Password::from("secure_password".to_owned())) + .build(random_stronghold_path())?, + ); + + // Create a new DID in an Alias Output for us to modify. + let storage: MemStorage = MemStorage::new(JwkMemStore::new(), KeyIdMemstore::new()); + let (_, document, fragment_1): (Address, IotaDocument, String) = + create_did(&client, &mut secret_manager, &storage).await?; + let did: IotaDID = document.id().clone(); + +``` + + + + +```js + const client = new Client({ + primaryNode: API_ENDPOINT, + localPow: true, + }); + const didClient = new IotaIdentityClient(client); + + // Generate a random mnemonic for our wallet. + const secretManager: MnemonicSecretManager = { + mnemonic: Utils.generateMnemonic(), + }; + + // Creates a new wallet and identity (see "0_create_did" example). + const storage: Storage = new Storage(new JwkMemStore(), new KeyIdMemStore()); + let { document, fragment } = await createDid( + client, + secretManager, + storage, + ); +``` + + + + +This creates and publishes an Alias Output containing a DID Document with one verification method. + +```json +{ + "doc": { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "verificationMethod": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } + } + ] + }, + "meta": { + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:03Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" + } +} +``` + +## Add a Verification Method + + + + +```rust + // Insert a new Ed25519 verification method in the DID document. + let fragment_2: String = document + .generate_method( + &storage, + JwkMemStore::ED25519_KEY_TYPE, + JwsAlgorithm::EdDSA, + None, + MethodScope::VerificationMethod, + ) + .await?; +``` + + + + +```js + // Insert a new Ed25519 verification method in the DID document. + await document.generateMethod( + storage, + JwkMemStore.ed25519KeyType(), + JwsAlgorithm.EdDSA, + "#key-2", + MethodScope.VerificationMethod(), + ); +``` + + + + +This creates a new verification method that includes a newly generated Ed25519 public key. + +```json +{ + "doc": { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "verificationMethod": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } + }, + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } + } + ] + }, + "meta": { + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:03Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" + } +} +``` + +Notice that these changes to the document are not [published](#publish-your-updates) yet. + +## Add Verification Relationships + +You can attach verification relationships to a verification method by referencing its fragment. + + + + +```rust +// Attach a new method relationship to the inserted method. +document.attach_method_relationship( + &document.id().to_url().join(format!("#{fragment_2}"))?, + MethodRelationship::Authentication, +)?; +``` + + + + +```js +// Attach a new method relationship to the inserted method. +document.attach_method_relationship( + &document.id().to_url().join(format!("#{fragment_2}"))?, + MethodRelationship::Authentication, +)?; +``` + + + + +This will add `Authentication` relationship to the verification method with the fragment `key-1`. +Note that `Authentication` references the already included `key-2` verification method: + +```json {12,19} +{ + "doc": { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "verificationMethod": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } + }, + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } + } + ], + "authentication": [ + "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE" + ] + }, + "meta": { + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:03Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" + } +} +``` + +## Add a Service + +You can also add custom properties can to a service by setting `properties`: + + + + +```rust + // Add a new Service. + let service: Service = Service::from_json_value(json!({ + "id": document.id().to_url().join("#linked-domain")?, + "type": "LinkedDomains", + "serviceEndpoint": "https://iota.org/" + }))?; + assert!(document.insert_service(service).is_ok()); + document.metadata.updated = Some(Timestamp::now_utc()); +``` + + + + +```js + // Add a new Service. + const service: Service = new Service({ + id: did.join("#linked-domain"), + type: "LinkedDomains", + serviceEndpoint: "https://iota.org/", + }); + document.insertService(service); + document.setMetadataUpdated(Timestamp.nowUTC()); +``` + + + + +The updated Document with the newly created service looks as follows. + +```json {21-27} +{ + "doc": { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "verificationMethod": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } + }, + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } + } + ], + "authentication": [ + "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE" + ], + "service": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#linked-domain", + "type": "LinkedDomains", + "serviceEndpoint": "https://iota.org/" + } + ] + }, + "meta": { + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:08Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" + } +} +``` + +## Remove a Verification Method + +You can also remove verification methods at any time using the following snippet: + + + + +```rust +// Remove a verification method. +let original_method: DIDUrl = document.resolve_method(fragment_1.as_str(), None).unwrap().id().clone(); +document.purge_method(&storage, &original_method).await.unwrap(); +``` + + + + +```js +// Remove a verification method. +let originalMethod = document.resolveMethod(fragment) as VerificationMethod; +await document.purgeMethod(storage, originalMethod?.id()); +``` + + + + +This removes the original verification method with the fragment `key-1`. + +```json +{ + "doc": { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "verificationMethod": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } + } + ], + "authentication": [ + "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE" + ], + "service": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#linked-domain", + "type": "LinkedDomains", + "serviceEndpoint": "https://iota.org/" + } + ] + }, + "meta": { + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:08Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" + } +} +``` + +## Publish Your Updates + +Publish the updated DID Document inside the Alias Output taking into account the increase in the storage deposit needed. + + + + +```rust + // Resolve the latest output and update it with the given document. + let alias_output: AliasOutput = client.update_did_output(document.clone()).await?; + + // Because the size of the DID document increased, we have to increase the allocated storage deposit. + // This increases the deposit amount to the new minimum. + let rent_structure: RentStructure = client.get_rent_structure().await?; + let alias_output: AliasOutput = AliasOutputBuilder::from(&alias_output) + .with_minimum_storage_deposit(rent_structure) + .finish()?; + + // Publish the updated Alias Output. + let updated: IotaDocument = client.publish_did_output(&secret_manager, alias_output).await?; +``` + + + + +```js + // Resolve the latest output and update it with the given document. + let aliasOutput: AliasOutput = await didClient.updateDidOutput(document); + + // Because the size of the DID document increased, we have to increase the allocated storage deposit. + // This increases the deposit amount to the new minimum. + const rentStructure: IRent = await didClient.getRentStructure(); + + aliasOutput = await client.buildAliasOutput({ + ...aliasOutput, + amount: Utils.computeStorageDeposit(aliasOutput, rentStructure), + aliasId: aliasOutput.getAliasId(), + unlockConditions: aliasOutput.getUnlockConditions(), + }); + + // Publish the output. + const updated: IotaDocument = await didClient.publishDidOutput(secretManager, aliasOutput); +``` + + + + +## Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/1_update_did.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/1_update_did.ts +``` + + + \ No newline at end of file diff --git a/docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx b/docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx new file mode 100644 index 00000000000..ba1cb85d4d5 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx @@ -0,0 +1,179 @@ +--- +description: How to link a domain and a DID +sidebar_label: Create and Verify +image: /img/Identity_icon.png +keywords: + - well-known + - domain linkage + - DID Configuration Resource + - Domain Linkage Credential +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Domain Linkage + +:::info +To use Domain Linkage in Rust you have to enable the `domain-linkage` feature. +::: + +## Overview + +Domain Linkage can provide proof for a connection between a DID and a domain being controlled by the same entity. +This linkage can transfer trust from a domain to a DID and vice versa. +For instance, if an entity trusts a domain, it can also trust the linked DID and all documents signed by +the verification methods included in the DID Document. + +A use case could be a verifier that trusts `www.example.com`, and receives a verifiable presentation issued by `did:foo:abc`. +If `did:foo:abc` is linked to `www.example.com`, the verifier can trust that the verifiable presentation is issued by +the same entity controlling `www.example.com`. +The DIF has approved a [Well Known DID Configuration](https://identity.foundation/.well-known/resources/did-configuration/) draft to standardize this connection by introducing +the [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource) and the [Linked Domain Service Endpoint](https://identity.foundation/.well-known/resources/did-configuration/#linked-domain-service-endpoint). + +![Identity getting started](/img/domain-linkage-diagram.png) + +### DID Configuration Resource + +Suppose that a DID `did:foo:example` with the following DID Document only contains one `verificationMethod`, `key-1`: + +```json {5} +{ + "id": "did:foo:abc", + "verificationMethod": [ + { + "id": "did:foo:abc#key-1", + "controller": "did:foo:abc", + "type": "Ed25519VerificationKey2018", + "publicKeyMultibase": "zDShpHKXkcHKHcF8CnGAA1UqyyuEPRNz1XFEuggbWJQSq" + } + ] + }, +``` + +The domain `https://www.example.com` represents the same entity and needs to be linked to increase trust in the DID. + +To establish this link, you must create a [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource), +and make it available on the [DID Configuration URL](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-uri). +In this case it's `https://example.com/.well-known/did-configuration.json`. + +The [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource) is a JSON-LD object containing verifiable credentials called `Domain Linkage Credentials`. +Each credential represents a linkage to a single DID. + +:::note + +Note that one `DID Configuration Resource` can include multiple `Domain Linkage Credentials`, +effectively linking the same domain to multiple DIDs. + +::: + +In this example, the domain `https://www.example.com` needs to be linked to the DID `did:foo:abc`. +This means that the `DID Configuration Resource` will have one `Domain Linkage Credential`. +This credential must have the following properties: + +- Its `type` includes `DomainLinkageCredential`. +- It includes the DID Configuration context. +- The `credentialSubject` must be the DID `did:foo:abc` and references the domain `https://www.example.com`. +- The issuer is the DID itself `did:foo:abc`. +- It is signed by a key material included in the DID Document, in this case `did:foo:abc#key-1`. + +```json +{ + "@context": "https://identity.foundation/.well-known/did-configuration/v1", + "linked_dids": [ + { + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://identity.foundation/.well-known/did-configuration/v1" + ], + "type": ["VerifiableCredential", "DomainLinkageCredential"], + "credentialSubject": { + "id": "did:foo:abc", + "origin": "https://www.example.com/" + }, + "issuer": "did:foo:abc", + "issuanceDate": "2023-02-09T22:14:15Z", + "expirationDate": "2024-02-09T22:14:15Z", + "proof": { + "type": "JcsEd25519Signature2020", + "verificationMethod": "did:foo:abc#key-1", + "signatureValue": "4SvYqo3YoArfW7r7qKfN7RUJdZnBteb166KE4UkX8MNdbp5UW6YbykneAzvjyRmf5EVQ9bnP9cS5sbEPUn2uaAcB" + } + } + ] +} +``` + +Now this `DID Configuration Resource` must be made available on `https://example.com/.well-known/did-configuration.json`, +which establishes the linkage. + +### Linked Domain Service Endpoint + +By having a domain, one can discover what DIDs are linked to it by fetching the `DID Configuration Resource` and +investigating the `Domain Linkage Credentials`. + +If you want to enable discovery from the other direction, that is, if you have a DID and want to discover which +domains are linked to it, you can add a [Linked Domain Service Endpoint](https://identity.foundation/.well-known/resources/did-configuration/#linked-domain-service-endpoint) to the DID Document. +The DID Document from this example will be extended as follows to enable discovery of `https://www.example.com`: + +```json {11-17} +{ + "id": "did:foo:abc", + "verificationMethod": [ + { + "id": "did:foo:abc#key-1", + "controller": "did:foo:abc", + "type": "Ed25519VerificationKey2018", + "publicKeyMultibase": "zDShpHKXkcHKHcF8CnGAA1UqyyuEPRNz1XFEuggbWJQSq" + } + ], + "service": [ + { + "id": "did:foo:abc#domain-linkage", + "type": "LinkedDomains", + "serviceEndpoint": "https://www.example.com/" + } + ] +} +``` + +:::note +Note that a DID Document can have multiple `Linked Domain Services` and each service can link to multiple domains. +::: + +### Verifying a DID and Domain Linkage + +As mentioned above, you can discover the Domain Linkage from either direction. +However, verifying the linkage in both cases involves only verifying the DID Configuration Resource. +The process is as follows: + +1. Fetch `DID Configuration Resource` from `https://www.example.com/.well-known/did-configuration.json`. +2. Resolve the DID Document of `did:foo:abc`. +3. Verify the `DID Configuration Resource` and its `Domain Linkage Credential` that references `did:foo:abc`. + + +:::tip About DID Configuration Resource Verification + +You can learn more +[about DID Configuration Resource Verification on the Identity Foundation website](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource-verification). + +::: + +## Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/1_advanced/6_domain_linkage.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/1_advanced/5_domain_linkage.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx b/docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx new file mode 100644 index 00000000000..c72630370cb --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx @@ -0,0 +1,152 @@ +--- +title: Key Storage +sidebar_label: Key Storage +description: Explain the use of the storage interfaces and how they can be implemented +image: /img/Identity_icon.png +keywords: + - key storage + - storage interfaces + - json web key + - json web algorithm + - signing +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Introduction + +The `JwkDocumentExt` API allows you to modify a DID document, for example, adding new verification methods. +It enables storing the secrets that verification methods represent securely. +It does so using the two storage interfaces, the `JwkStorage` and `KeyIdStorage`. +We refer to both of these as the **key storage**. + +The main idea behind the key storage is strongly inspired by the architecture of key management systems (KMS) +or secure enclaves: once private keys are entered into the system, they can never be retrieved again. +Instead, all operations using the key will have to go through that system. + +This approach allows the key storage to be architected more securely than simply storing and loading private keys from +a regular database. +Of course, security is directly dependent on the concrete implementation, +which is why we provide [Stronghold](https://github.com/iotaledger/stronghold.rs/), a best-effort in-software enclave, by default. + +However, there are cases where one cannot use `Stronghold`, +or may want to integrate key management of identities into their own KMS or similar, +which is why the key storage is an abstraction over such systems. +Any implementation of a key storage can be used by the `JwkDocumentExt` API. + +The two interfaces making up the key storage have two respective responsibilities. + +:::info + +Even though there are two separate interfaces, you can implement them using the same backing storage. + +::: + +## Function Overview + +A brief overview of those functions: + +- `JwkStorage`: CRUD and signing operations on [JSON Web Keys](https://www.rfc-editor.org/rfc/rfc7517). + - `generate`: Generate a new key represented as a JSON Web Key. + - `insert`: Insert an existing JSON Web Key into the storage. + - `sign`: Signs the provided data using the stored private key. + - `delete`: Permanently deletes a key. + - `exists`: Returns whether a key exists. +- `KeyIdStorage`: Stores the mappings from verification methods to their corresponding key identifier in the `JwkStorage`. + - `insert_key_id`: Inserts a mapping from a verification method identifier to a key identifier. + - `get_key_id`: Returns the key identifier for a given verification method identifier. + - `delete_key_id`: Deletes a mapping. + +## Key Identifier + +A `JwkStorage` stores and operates on keys, so they must be identified. +In general, Key Management Systems use some form of an identifier for their keys. +To abstract over those, the `JwkStorage` interface has a general-purpose `KeyId` type, +which is effectively a wrapper around a string. + +A `KeyIdStorage` is needed to store the key id that represents the private key for a given verification method. +To that end, a verification method itself must be identified. + +While within a document, each fragment must be unique, the same is not true given multiple documents, +so we cannot rely only on fragments if we don't want to partition the `KeyIdStorage` by DID. +The solution to this is using a `MethodDigest`, a hash over a verification method. + +When following best security practices, each verification method has its own associated key and, thus, a unique public key. +That, plus the fragment of a method, ensures the `MethodDigest` is unique. + +So, in essence, a `JwkStorage` stores a `KeyId -> JWK` mapping while a `KeyIdStorage` stores a `MethodDigest -> KeyId` mapping. + +:::caution + +Given the construction and limitations of the method digest, +no two documents should contain a method that shares both the same fragment and public key. +This should not happen under typical circumstances, but it is good to keep it in mind. + +::: + +## Key Types + +To express what key types a given `JwkStorage` implementation supports, you should use the `KeyType`, +which is another simple wrapper around a string. + +The reason for this design might seem odd in Rust, given the existence of associated types. +This more simplistic design is necessary to accommodate implementing the interface via the bindings to the library. + +Implementations are expected to export constants of the key types they support, +so users have an easy way to discover the supported types. +In general, storage implementations are free to support any [JSON Web Algorithm](https://www.rfc-editor.org/rfc/rfc7518.html)-compatible key. +However, the recommended default used by IOTA Identity is the `EdDSA` algorithm with curve `Ed25519`. + +## Implementation + +The IOTA Identity library ships two implementations of key storage. +The `JwkMemStore` and `KeyIdMemstore` are insecure in-memory implementations +intended as example implementations and for testing. + +The default key storage implementation is `Stronghold`, +which is an example of a storage that implements both storage interfaces simultaneously. +[`Stronghold`](https://github.com/iotaledger/stronghold.rs/) may be interesting for implementers to look at, +as it needs to deal with some challenges the in-memory version does not have to deal with. Note that the `Stronghold` implementation is only available in Rust. + +## Examples + +This section shows the Rust and TypeScript `Memstore` implementations. + +### `JwkMemStore` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/lib/jwk_storage.ts +``` + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/identity_storage/src/key_storage/memstore.rs +``` + + + + +### `KeyIdMemstore` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/lib/key_id_storage.ts +``` + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/identity_storage/src/key_id_storage/memstore.rs +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx new file mode 100644 index 00000000000..6f7103d1e20 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx @@ -0,0 +1,141 @@ +--- +title: Create a Verifiable Credential +sidebar_label: Create and Sign +description: Explain how a VC is created and verified +image: /img/Identity_icon.png +keywords: + - verifiable + - credentials + - Create + - sign +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +A [Verifiable Credential (VC)](./../../explanations/verifiable-credentials.mdx) can represent all +information that a physical credential represents, such as a passport or university +degree. However, by allowing other parties to cryptographically verify the authorship +and integrity of the claims, verifiable credentials can be seen as more tamper-evident +and more trustworthy than their physical counterparts. + +## Verifiable Credential Properties + +In the IOTA Identity Framework, you can create a Verifiable Credential with the following properties: + +- [**Context**](https://www.w3.org/TR/vc-data-model/#contexts): List of JSON-LD context URIs. Includes `"https://www.w3.org/2018/credentials/v1"` by default. +- [**Types**](https://www.w3.org/TR/vc-data-model/#types): List of types describing the credential. Includes `"VerifiableCredential"` by default. +- [**Subject**](https://www.w3.org/TR/vc-data-model/#credential-subject): The issuer's claims; a set of objects that contain one or more properties that are each related to a subject. +- [**Issuer**](https://www.w3.org/TR/vc-data-model/#issuer): The identifier of the issuer, typically their [DID](../../explanations/decentralized-identifiers.mdx). +- [**ID**](https://www.w3.org/TR/vc-data-model/#identifiers): Optional URI identifier for the credential. +- [**Issuance Date**](https://www.w3.org/TR/vc-data-model/#issuance-date): Timestamp for expressing the date and time when a credential becomes valid. +- [**Expiration Date**](https://www.w3.org/TR/vc-data-model/#expiration): Optional timestamp for expressing the date and time when a credential ceases to be valid. +- [**Status**](https://www.w3.org/TR/vc-data-model/#status): Optional information used to determine the current status of a credential, i.e. whether or not it has been [revoked](./revocation.mdx). +- [**Schema**](https://www.w3.org/TR/vc-data-model/#data-schemas): Optional list of objects specifying the schema that the data must conform to. +- [**Refresh Service**](https://www.w3.org/TR/vc-data-model/#refreshing): Optional link to a service where the recipient may refresh the included credentials. +- [**Terms of Use**](https://www.w3.org/TR/vc-data-model/#terms-of-use): Optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient. +- [**Evidence**](https://www.w3.org/TR/vc-data-model/#evidence): Optional list of objects that can be used by the issuer to provide the verifier with additional supporting information in a verifiable credential. +- [**Non-Transferable**](https://www.w3.org/TR/vc-data-model/#nontransferable-property): Optional flag that indicates that a verifiable credential must only be encapsulated in a [verifiable presentation](./../../explanations/verifiable-presentations.mdx) whose proof was issued by the credential subject. + + + + +## Signing {#signing} + +After preparing the verifiable credential, the issuer creates a signed JWT containing VC in the claims using one of their private keys. This is what allows verifiers to validate the credential independently using the corresponding public key from the issuer's DID Document. + +## Validation + +Verifiers should ensure certain credential properties are valid when receiving one or more in a [verifiable presentation](./../../explanations/verifiable-presentations.mdx). Both issuers and holders may also wish to validate their credentials, particularly directly after creating or receiving one. Validation may be performed at any point in time and can be a useful way of checking whether a credential has expired or been revoked. + +### Validation Checks + +The IOTA Identity Framework supports the following checks during credential validation: + +- **Semantic structure**: Ensures the credential adheres to the specification. +- **Signature**: Verifies the JWS against the issuer's DID Document. +- **Optional validations**: Additional checks on credential properties, and the signature can be configured by specifying [Validation Options](#validation-options). + +### Validation Options + +These options specify conditions that specific properties in a credential must satisfy. + +- **Expiration Date**: Check that the [`expirationDate`](https://www.w3.org/TR/vc-data-model/#expiration) property, if present, is not before a specific date-time. Defaults to the current datetime if unset. +- **Issuance Date**: Check that [`issuanceDate`](https://www.w3.org/TR/vc-data-model/#issuance-date) property, if present, is not after a specific date-time. Defaults to the current datetime if unset. +- **Verifier Options**: Validates aspects of the credential signature. + +## Sharing Verifiable Credentials + +A [verifiable presentation](./../../explanations/verifiable-presentations.mdx) is the recommended data format for sharing one or more verifiable credentials, +as it provides cryptographic means of proving the DID of the holder presenting them, +and for enforcing [subject-holder relationships](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships). + +## Example + +The following code showcases how an issuer can [create, sign](#create-and-sign-vc), +and [validate](#validate-a-vc) a verifiable credential. +In this example, the issuer signs a `UniversityDegreeCredential` with Alice's name and DID. + +### Create and Sign a VC + + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/5_create_vc.rs#L67-L98 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L51-L74 +``` + + + +
+ +### Validate a VC + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/5_create_vc.rs#L105-L113 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L83-L88 +``` + + + +
+ +This Verifiable Credential can be [verified by anyone](./../../explanations/verifiable-presentations.mdx), +allowing Alice to take control of it and share it with anyone. + +### Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/5_create_vc.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx new file mode 100644 index 00000000000..6d16eb5fdf3 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx @@ -0,0 +1,208 @@ +--- +sidebar_label: Revoke +description: Explain how a VC can be revoked +image: /img/Identity_icon.png +keywords: + - verifiable + - credentials + - revoke + - revocation +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Revoke a Verifiable Credential + +The [example](#example) below demonstrates two methods that an issuer can use to revoke a verifiable credential +using the IOTA Identity Framework: + +1. By using the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) field in a credential and linking +to a [revocation method](#revocation-methods). +2. By [removing the verification method](#removing-the-verification-method) that signed the credential. +This invalidates all credentials that were signed with that verification method. + +## Revocation methods +The IOTA Identity Framework supports two different revocation methods: `RevocationBitmap2022` and `StatusList2021`. +### Revocation Bitmap +[RevocationBitmap2022](/identity.rs/references/specifications/revocation-bitmap-2022/) is the default credential revocation method used in the IOTA Identity Framework. It allows +issuers to control whether a credential is _valid_ or _revoked_. To do so, a revocation list (represented +as a bitmap) is stored in the issuer's DID document. +When a credential is issued, a unique index from the issuer's revocation list +is chosen, linking the credential's status to the value of the list entry. To change the status of a credential, the issuer +simply updates the corresponding entry in its revocation list. + +With `RevocationBitmap2022` the `identity.rs` library completely handles the processes required to handle credentials revocation; +from creation and storage of the revocation list to its lookup. +This makes `RevocationBitmap2022` the preferred way for users to handle credential revocation, but it requires sufficient +funds to rent out the required on-tangle space. + +:::note + +DLT's size constraints limit the size of the revocation list. With the assumption of only one such revocation list +per the issuer's DID document, one may expect to be able to handle roughly 50k entries. + +::: + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/7_revoke_vc.rs#L167 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L156 +``` + + + + +If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, +if it is 0 (zero) it is not revoked. + +For example, with this approach the issuer adds an index to a credential in the `credentialStatus` field, such as `"5"`. +This part of the credential might then look like this: + +```json +"credentialStatus": { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", + "type": "RevocationBitmap2022", + "revocationBitmapIndex": "5" +}, +``` + +The verifier uses the `id` field (`did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation`) to look up the +service in the issuer's DID document: + +```json +{ + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", + "type": "RevocationBitmap2022", + "serviceEndpoint": "data:application/octet-stream;base64,ZUp5ek1tQmdZR1NBQUFFZ1ptVUFBQWZPQUlF" +} +``` + +During verification, the verifier decodes the revocation bitmap embedded in the `data` URL. +This bitmap written as a bitstring looks like this: `000001`. +Here, the 5th bit is set, which means the credential with that index is revoked, +while all other credentials aren't revoked. + +### StatusList2021 +[StatusList2021](https://www.w3.org/TR/2023/WD-vc-status-list-20230427) offers similar functionalities to `RevocationBitmap2022` +but in a more flexible and scalable way. +The main difference is that `StatusList2021` is completely agnostic in regards to how the issuer's status list +is stored and fetched, as long as its location can be encoded through a URL. For instance, the status list +can be made available over HTTP (e.g. `https://example.com/credentials/status`) or through the +Interplanetary File System (e.g. `ipfs://QmXDWGdVBhbDoXXzKNMhJk5ejnZgxpMBVzW4EhQaHPD3Mi`). + +This flexibility, although it requires the issuer to manually fetch and update its status list, allows for an arbitrary number of +entries in the status list, in contrast with `RevocationBitmap2022`, where the length of the list is limited by the DLT's constraints. + +Furthermore, `StatusList2021` introduces a new credential state: _suspended_. Suspended credentials are credentials that a validator will not accept as _valid_, but that might become valid again in the future. Instead, _revoked_ credentials **cannot** ever +be valid again, as the _revoked_ state is irreversible. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/1_advanced/8_status_list_2021.rs#L86-L90 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/1_advanced/7_status_list_2021.ts#L72-L76 +``` + + + + +First, an issuer creates a credential that encodes a certain status list, specifying its purpose (either `revocation` or `suspension`) +and the location at which it will be available (`https://example.com/credentials/status` in this case). After creation, the issuer +must make the credential available at the chosen URL so that verifiers can fetch it. + +Upon issuing a credential, to revoke it or suspend it later, the issuer sets the `credentialStatus` field, linking +to an entry in its status list. The snippet below shows what `credentialStatus` would look like when linking to the previously created +status list credential. + +```json +{ + "id": "https://example.com/credentials/status#94567", + "type": "StatusList2021Entry", + "statusPurpose": "revocation", + "statusListIndex": "94567", + "statusListCredential": "https://example.com/credentials/status" +} +``` + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/1_advanced/8_status_list_2021.rs#L173 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/1_advanced/7_status_list_2021.ts#L147 +``` + + + + +To set the status of a credential, the issuer retrieves the status list credential and sets the value of the chosen entry index. + +## Removing the Verification Method + +A less efficient alternative is to remove the verification method that signed the credential from the DID Document of +the issuer. +This means the VC can no longer be validated. + +However, this will also invalidate every VC signed with that verification method, +meaning that the issuer will have to sign every VC with a different key to retain +precise control over which credential is revoked. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/7_revoke_vc.rs#L197-L204 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L192C1-L195 +``` + + + + +## Full Example Code + +The following code exemplifies how you can revoke a [Verifiable Credential (VC)](../../explanations/verifiable-credentials.mdx). + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/7_revoke_vc.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx new file mode 100644 index 00000000000..514cbc58489 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx @@ -0,0 +1,141 @@ +--- +sidebar_label: Selective Disclosure +description: Explain VC with selective disclosure. +image: /img/Identity_icon.png +keywords: + - verifiable + - credentials + - SD-JWT + - Disclosure +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Selective Disclosure (SD-JWT) + + +Holders of verifiable credentials may prefer to keep all the information contained within the credential private from a verifier. Instead, they may opt only to share a specific subset of the properties included in the VC. The identity library implements the [IETF Specifications](https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html), which outlines a mechanism to enable the selective disclosure of individual properties within the JSON object of JWT claims. + +## Concept + +### Issuance + +During the issuance process, the issuer replaces a subset of the fields in a credential with digests of their salted values and creates a signed JWT. Next, JWT, alongside the plain text disclosures and the salt used for digest creation are sent to the holder. + +### Presentation + +At this stage, the holder can selectively choose which fields to disclose to the verifier. The disclosures are sent in plain text, with the JWT containing the digests to the verifier. + +:::note +Only values replaced by digests through the issuer can be selectively disclosed. The holder **can not** conceal values provided in plain text in the JWT claims. +::: + + +### Validation + +With these values and a valid signature, the verifier is able to reconstruct a Verified Credential (VC) that exclusively contains the information the holder intended to disclose. + +## How It Works + +A SD JWT can be constructed from the following JWT claim of an address credential in accordance with the [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token): + + +```json +{ + "iss": "did:iota:tst:0x899d07a766f93c2af1a19a3f4583ad338fc94c5d84b6afcadf49b197e1cb693e", + "jti": "https://example.com/credentials/3732", + "nbf": 1705925652, + "sub": "did:iota:tst:0x6c045e1f658197b432cfc7c66350b8781dca50f820e9de0fcdf0029b4b384355", + "vc": { + "@context": "https://www.w3.org/2018/credentials/v1", + "credentialSubject": { + "address": { + "country": "DE", + "locality": "Maxstadt", + "postal_code": "12344", + "street_address": "Weidenstraße 22" + }, + "name": "Alice" + }, + "type": [ + "VerifiableCredential", + "AddressCredential" + ] + } +} + +``` + +The issuer makes the values of "locality", "postal_code", and "street_address" selectively disclosable, giving the holder the freedom to select what details of the address to be disclosed and presented. + +```json +{ + "_sd_alg": "sha-256", + "iss": "did:iota:tst:0x899d07a766f93c2af1a19a3f4583ad338fc94c5d84b6afcadf49b197e1cb693e", + "jti": "https://example.com/credentials/3732", + "nbf": 1705925652, + "sub": "did:iota:tst:0x6c045e1f658197b432cfc7c66350b8781dca50f820e9de0fcdf0029b4b384355", + "vc": { + "@context": "https://www.w3.org/2018/credentials/v1", + "credentialSubject": { + "address": { + "_sd": [ + "8Dai0-GMZgkzmdryGzjYufUaRFkiNWzVsJJdWucwu84", + "jemTNaG_wiHauwmwWiWREsirAlr91qugPds4MA8e2xo", + "iakC9Dfe2r9fGnOaAr_pGg1b7CwITBjcwE7-O7WlMnY" + ], + "country": "DE" + }, + "name": "Alice" + }, + "type": [ + "VerifiableCredential", + "AddressCredential" + ] + } +} +``` + +:::note +The digests are contained in the `_sd` property in `address`. This allows both keys and values to be concealed. +::: + +For further details, see the [example](#full-example-code) below and the [sd-jwt-payload crate](https://github.com/iotaledger/sd-jwt-payload). + +## Presentation format + +The SD-JWT is presented in the following [format](https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html#section-5): + +> `~~~...~~` + +## Key Binding JWT + +When a verifier receives an SD-JWT, it may be desirable to verify that the presenter's identity matches the holder of the Credential. For that purpose, a [Key Binding JWT (KB-JWT)](https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html#section-4.3) can be used. + + +- The verifier sends a nonce to the holder. +- The holder creates a JWT containing the nonce and the digest of the issuer-signed JWT and the disclosures 1→N. +- The holder sends the KB-JWT to the verifier as a part of the presentation. +- By verifying the KB-JWT, the verifier ensures the identity of the holder, the integrity of the data, the freshness of the signature, and the intended audience. + + + +## Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/1_advanced/7_sd_jwt.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/1_advanced/6_sd_jwt.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx new file mode 100644 index 00000000000..9601726a9b3 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx @@ -0,0 +1,116 @@ +--- +sidebar_label: Create and Validate +description: Explain how a VP is created and verified +image: /img/Identity_icon.png +keywords: + - verifiable + - presentations +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Create and Validate Verifiable Presentations + +The IOTA Identity Framework enables holders to easily construct +[verifiable presentations](./../../explanations/verifiable-presentations.mdx). +As demonstrated in the [example](#example-code), +holders only need to pass in their credentials to create a JWT presentation. + +## Properties + +You can specify the following properties in a presentation: + +- [**ID**](https://www.w3.org/TR/vc-data-model/#identifiers): Optional URI identifier for the presentation. +- [**Context**](https://www.w3.org/TR/vc-data-model/#contexts): List of JSON-LD context URIs. Includes `"https://www.w3.org/2018/credentials/v1"` by default. +- [**Types**](https://www.w3.org/TR/vc-data-model/#types): List of types describing the presentation. Includes `"VerifiablePresentation"` by default. +- [**Credentials**](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-credentials): List of verifiable credentials to present. +- [**Holder**](https://www.w3.org/TR/vc-data-model/#dfn-holders): Optional URI, typically a DID, of the entity that generated the presentation. +- [**Refresh Service**](https://www.w3.org/TR/vc-data-model/#refreshing): Optional link to a service where the recipient may refresh the included credentials. +- [**Terms of Use**](https://www.w3.org/TR/vc-data-model/#terms-of-use): Optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient. + +Of the above, **only the list of credentials is required** when creating a presentation using the framework. +However, the holder property should be included to satisfy [subject-holder relationship](#subject-holder-relationship) checks during validation. + +After creation, the holder signs the verifiable presentation using a private key linked to one of the verification +methods in their DID Document and transmits it to a verifier for validation. + +## Creation and Validation + +A Verifiable Presentation can be issued as a JWT that provides data integrity, +and also proves the [DID](../../explanations/decentralized-identifiers.mdx) of the holder. + +:::note + +Verifiers should always send a challenge +to [mitigate replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations). +::: + + +The IOTA Identity Framework provides several options for verifiers to validate various sections of a verifiable presentation. +See the [example](#example-code) for a demonstration of how to validate a presentation. + +The framework checks: + +- **Semantic structure**: Ensures the presentation and its credentials adhere to the specification. +- **Presentation proof**: Verifies the presentation signature against the holder's DID document. +- **Credential proofs**: Verifies the credential signatures against the DID Documents of their respective issuers. + + +Currently, the following are **not** checked automatically: + +- **Data schemas**: Credentials that specify a [schema](https://www.w3.org/TR/vc-data-model/#data-schemas) property +should be examined to ensure conformance. +- **Fitness for purpose**: Whether the credentials in a presentation and the data within them are acceptable and +valid depends on the context in which they are used. Verifiers should ensure that the credential types, subjects, +and schemas sent by a holder match what was requested. +- **Issuer trustworthiness**: Verifiers must check that they trust the issuer on each individual credential in a +presentation. The framework only verifies that the issuer's signature on each credential is current and valid +against the given options. + +The default validation behavior may be modified by the following options. + +## Subject-Holder Relationship + +Specifies the expected relationship between the holder that signed the verifiable presentation and the subject +specified in each [verifiable credential](./../../explanations/verifiable-credentials.mdx). +This can be restricted by the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property, +which indicates that a verifiable credential must only be encapsulated into a verifiable presentation whose holder matches the credential subject. + +By default, the framework always enforces that the holder matches the subject. + +The following options are available to modify that behavior: + +- **`AlwaysSubject` (default)**: The holder DID that signed the presentation must match the [`credentialSubject` `id`](https://www.w3.org/TR/vc-data-model/#credential-subject) field in each of the attached credentials. This is the safest option which ensures holders may only present credentials that were directly issued to their DID. An error is thrown on a mismatch or if no subject `id` is present. +- **`SubjectOnNonTransferable`**: The holder DID must match the subject only for credentials where the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property is `true`. This is appropriate for accepting [bearer credentials](https://www.w3.org/TR/vc-data-model/#bearer-credentials) while still adhering to the specification. +- **`Any`**: The holder DID is not required to have any kind of relationship to any credential subject. This option performs no checks and ignores the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property. + +:::note + +See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships) +for further discussion on the different subject-holder relationships. + +::: + + +## Example Code + +The following code demonstrates how to use the IOTA Identity Framework end-to-end to create and sign a verifiable +presentation as a holder, serialize it to JSON for transmission, deserialize it on the receiving side as a verifier, +and finally validate it with various options. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/6_create_vp.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/6_create_vp.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/references/api/wasm.mdx b/docs/build/identity.rs/1.1/docs/references/api/wasm.mdx new file mode 100644 index 00000000000..8bab9303392 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/references/api/wasm.mdx @@ -0,0 +1,6260 @@ +--- +title: WASM API Reference +description: WASM API reference. +image: /img/Identity_icon.png +keywords: + - WASM + - API Reference +--- +# Wasm Api Reference + +## Classes + +
+
CoreDID
+

A method-agnostic Decentralized Identifier (DID).

+
+
CoreDocument
+

A method-agnostic DID Document.

+

Note: All methods that involve reading from this class may potentially raise an error +if the object is being concurrently modified.

+
+
Credential
+
+
DIDUrl
+

A method agnostic DID Url.

+
+
DecodedJws
+

A cryptographically verified decoded token from a JWS.

+

Contains the decoded headers and the raw claims.

+
+
DecodedJwtCredential
+

A cryptographically verified and decoded Credential.

+

Note that having an instance of this type only means the JWS it was constructed from was verified. +It does not imply anything about a potentially present proof property on the credential itself.

+
+
DecodedJwtPresentation
+

A cryptographically verified and decoded presentation.

+

Note that having an instance of this type only means the JWS it was constructed from was verified. +It does not imply anything about a potentially present proof property on the presentation itself.

+
+
Disclosure
+

Represents an elements constructing a disclosure. +Object properties and array elements disclosures are supported.

+

See: https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html#name-disclosures

+
+
DomainLinkageConfiguration
+

DID Configuration Resource which contains Domain Linkage Credentials. +It can be placed in an origin's .well-known directory to prove linkage between the origin and a DID. +See: https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource

+

Note:

+ +
+
Duration
+

A span of time.

+
+
EdDSAJwsVerifier
+

An implementor of IJwsVerifier that can handle the +EdDSA algorithm.

+
+
IotaDID
+

A DID conforming to the IOTA DID method specification.

+
+
IotaDocument
+

A DID Document adhering to the IOTA DID method specification.

+

Note: All methods that involve reading from this class may potentially raise an error +if the object is being concurrently modified.

+
+
IotaDocumentMetadata
+

Additional attributes related to an IOTA DID Document.

+
+
IotaIdentityClientExt
+

An extension interface that provides helper functions for publication +and resolution of DID documents in Alias Outputs.

+
+
Jwk
+
+
JwkGenOutput
+

The result of a key generation in JwkStorage.

+
+
Jws
+

A wrapper around a JSON Web Signature (JWS).

+
+
JwsHeader
+
+
JwsSignatureOptions
+
+
JwsVerificationOptions
+
+
Jwt
+

A wrapper around a JSON Web Token (JWK).

+
+
JwtCredentialValidationOptions
+

Options to declare validation criteria when validating credentials.

+
+
JwtCredentialValidator
+

A type for decoding and validating Credential.

+
+
JwtDomainLinkageValidator
+

A validator for a Domain Linkage Configuration and Credentials.

+
+
JwtPresentationOptions
+
+
JwtPresentationValidationOptions
+

Options to declare validation criteria when validating presentation.

+
+
JwtPresentationValidator
+
+
KeyBindingJWTValidationOptions
+

Options to declare validation criteria when validating credentials.

+
+
KeyBindingJwtClaims
+

Claims set for key binding JWT.

+
+
LinkedDomainService
+
+
MethodData
+

Supported verification method data formats.

+
+
MethodDigest
+

Unique identifier of a VerificationMethod.

+

NOTE: +This class does not have a JSON representation, +use the methods pack and unpack instead.

+
+
MethodScope
+

Supported verification method types.

+
+
MethodType
+

Supported verification method types.

+
+
Presentation
+
+
Proof
+

Represents a cryptographic proof that can be used to validate verifiable credentials and +presentations.

+

This representation does not inherently implement any standard; instead, it +can be utilized to implement standards or user-defined proofs. The presence of the +type field is necessary to accommodate different types of cryptographic proofs.

+

Note that this proof is not related to JWT and can be used in combination or as an alternative +to it.

+
+
Resolver
+

Convenience type for resolving DID documents from different DID methods.

+

Also provides methods for resolving DID Documents associated with +verifiable Credentials and Presentations.

+

Configuration

+

The resolver will only be able to resolve DID documents for methods it has been configured for in the constructor.

+
+
RevocationBitmap
+

A compressed bitmap for managing credential revocation.

+
+
SdJwt
+

Representation of an SD-JWT of the format +<Issuer-signed JWT>~<Disclosure 1>~<Disclosure 2>~...~<Disclosure N>~<optional KB-JWT>.

+
+
SdJwtCredentialValidator
+

A type for decoding and validating Credential.

+
+
SdObjectDecoder
+

Substitutes digests in an SD-JWT object by their corresponding plaintext values provided by disclosures.

+
+
SdObjectEncoder
+

Transforms a JSON object into an SD-JWT object by substituting selected values +with their corresponding disclosure digests.

+

Note: digests are created using the sha-256 algorithm.

+
+
Service
+

A DID Document Service used to enable trusted interactions associated with a DID subject.

+
+
StatusList2021
+

StatusList2021 data structure as described in W3C's VC status list 2021.

+
+
StatusList2021Credential
+

A parsed StatusList2021Credential.

+
+
StatusList2021CredentialBuilder
+

Builder type to construct valid StatusList2021Credential istances.

+
+
StatusList2021Entry
+

StatusList2021Entry implementation.

+
+
Storage
+

A type wrapping a JwkStorage and KeyIdStorage that should always be used together when +working with storage backed DID documents.

+
+
Timestamp
+
+
UnknownCredential
+
+
VerificationMethod
+

A DID Document Verification Method.

+
+
+ +## Members + +
+
CredentialStatus
+
+
StatusPurpose
+

Purpose of a StatusList2021.

+
+
StateMetadataEncoding
+
+
MethodRelationship
+
+
StatusCheck
+

Controls validation behaviour when checking whether or not a credential has been revoked by its +credentialStatus.

+
+
Strict
+

Validate the status if supported, reject any unsupported +credentialStatus types.

+

Only RevocationBitmap2022 is currently supported.

+

This is the default.

+
+
SkipUnsupported
+

Validate the status if supported, skip any unsupported +credentialStatus types.

+
+
SkipAll
+

Skip all status checks.

+
+
SubjectHolderRelationship
+

Declares how credential subjects must relate to the presentation holder.

+

See also the Subject-Holder Relationship section of the specification.

+
+
AlwaysSubject
+

The holder must always match the subject on all credentials, regardless of their nonTransferable property. +This variant is the default.

+
+
SubjectOnNonTransferable
+

The holder must match the subject only for credentials where the nonTransferable property is true.

+
+
Any
+

The holder is not required to have any kind of relationship to any credential subject.

+
+
FailFast
+

Declares when validation should return if an error occurs.

+
+
AllErrors
+

Return all errors that occur during validation.

+
+
FirstError
+

Return after the first error occurs.

+
+
+ +## Functions + +
+
verifyEd25519(alg, signingInput, decodedSignature, publicKey)
+

Verify a JWS signature secured with the EdDSA algorithm and curve Ed25519.

+

This function is useful when one is composing a IJwsVerifier that delegates +EdDSA verification with curve Ed25519 to this function.

+

Warning

+

This function does not check whether alg = EdDSA in the protected header. Callers are expected to assert this +prior to calling the function.

+
+
encodeB64(data) ⇒ string
+

Encode the given bytes in url-safe base64.

+
+
decodeB64(data) ⇒ Uint8Array
+

Decode the given url-safe base64-encoded slice into its raw bytes.

+
+
start()
+

Initializes the console error panic hook for better error messages

+
+
+ + + +## CoreDID +A method-agnostic Decentralized Identifier (DID). + +**Kind**: global class + +* [CoreDID](#CoreDID) + * _instance_ + * [.setMethodName(value)](#CoreDID+setMethodName) + * [.setMethodId(value)](#CoreDID+setMethodId) + * [.scheme()](#CoreDID+scheme) ⇒ string + * [.authority()](#CoreDID+authority) ⇒ string + * [.method()](#CoreDID+method) ⇒ string + * [.methodId()](#CoreDID+methodId) ⇒ string + * [.join(segment)](#CoreDID+join) ⇒ [DIDUrl](#DIDUrl) + * [.toUrl()](#CoreDID+toUrl) ⇒ [DIDUrl](#DIDUrl) + * [.intoUrl()](#CoreDID+intoUrl) ⇒ [DIDUrl](#DIDUrl) + * [.toString()](#CoreDID+toString) ⇒ string + * [.toCoreDid()](#CoreDID+toCoreDid) ⇒ [CoreDID](#CoreDID) + * [.toJSON()](#CoreDID+toJSON) ⇒ any + * [.clone()](#CoreDID+clone) ⇒ [CoreDID](#CoreDID) + * _static_ + * [.parse(input)](#CoreDID.parse) ⇒ [CoreDID](#CoreDID) + * [.validMethodName(value)](#CoreDID.validMethodName) ⇒ boolean + * [.validMethodId(value)](#CoreDID.validMethodId) ⇒ boolean + * [.fromJSON(json)](#CoreDID.fromJSON) ⇒ [CoreDID](#CoreDID) + + + +### coreDID.setMethodName(value) +Set the method name of the [CoreDID](#CoreDID). + +**Kind**: instance method of [CoreDID](#CoreDID) + +| Param | Type | +| --- | --- | +| value | string | + + + +### coreDID.setMethodId(value) +Set the method-specific-id of the `DID`. + +**Kind**: instance method of [CoreDID](#CoreDID) + +| Param | Type | +| --- | --- | +| value | string | + + + +### coreDID.scheme() ⇒ string +Returns the [CoreDID](#CoreDID) scheme. + +E.g. +- `"did:example:12345678" -> "did"` +- `"did:iota:smr:12345678" -> "did"` + +**Kind**: instance method of [CoreDID](#CoreDID) + + +### coreDID.authority() ⇒ string +Returns the [CoreDID](#CoreDID) authority: the method name and method-id. + +E.g. +- `"did:example:12345678" -> "example:12345678"` +- `"did:iota:smr:12345678" -> "iota:smr:12345678"` + +**Kind**: instance method of [CoreDID](#CoreDID) + + +### coreDID.method() ⇒ string +Returns the [CoreDID](#CoreDID) method name. + +E.g. +- `"did:example:12345678" -> "example"` +- `"did:iota:smr:12345678" -> "iota"` + +**Kind**: instance method of [CoreDID](#CoreDID) + + +### coreDID.methodId() ⇒ string +Returns the [CoreDID](#CoreDID) method-specific ID. + +E.g. +- `"did:example:12345678" -> "12345678"` +- `"did:iota:smr:12345678" -> "smr:12345678"` + +**Kind**: instance method of [CoreDID](#CoreDID) + + +### coreDID.join(segment) ⇒ [DIDUrl](#DIDUrl) +Construct a new [DIDUrl](#DIDUrl) by joining with a relative DID Url string. + +**Kind**: instance method of [CoreDID](#CoreDID) + +| Param | Type | +| --- | --- | +| segment | string | + + + +### coreDID.toUrl() ⇒ [DIDUrl](#DIDUrl) +Clones the [CoreDID](#CoreDID) into a [DIDUrl](#DIDUrl). + +**Kind**: instance method of [CoreDID](#CoreDID) + + +### coreDID.intoUrl() ⇒ [DIDUrl](#DIDUrl) +Converts the [CoreDID](#CoreDID) into a [DIDUrl](#DIDUrl), consuming it. + +**Kind**: instance method of [CoreDID](#CoreDID) + + +### coreDID.toString() ⇒ string +Returns the [CoreDID](#CoreDID) as a string. + +**Kind**: instance method of [CoreDID](#CoreDID) + + +### coreDID.toCoreDid() ⇒ [CoreDID](#CoreDID) +**Kind**: instance method of [CoreDID](#CoreDID) + + +### coreDID.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [CoreDID](#CoreDID) + + +### coreDID.clone() ⇒ [CoreDID](#CoreDID) +Deep clones the object. + +**Kind**: instance method of [CoreDID](#CoreDID) + + +### CoreDID.parse(input) ⇒ [CoreDID](#CoreDID) +Parses a [CoreDID](#CoreDID) from the given `input`. + +### Errors + +Throws an error if the input is not a valid [CoreDID](#CoreDID). + +**Kind**: static method of [CoreDID](#CoreDID) + +| Param | Type | +| --- | --- | +| input | string | + + + +### CoreDID.validMethodName(value) ⇒ boolean +Validates whether a string is a valid DID method name. + +**Kind**: static method of [CoreDID](#CoreDID) + +| Param | Type | +| --- | --- | +| value | string | + + + +### CoreDID.validMethodId(value) ⇒ boolean +Validates whether a string is a valid `DID` method-id. + +**Kind**: static method of [CoreDID](#CoreDID) + +| Param | Type | +| --- | --- | +| value | string | + + + +### CoreDID.fromJSON(json) ⇒ [CoreDID](#CoreDID) +Deserializes an instance from a JSON object. + +**Kind**: static method of [CoreDID](#CoreDID) + +| Param | Type | +| --- | --- | +| json | any | + + + +## CoreDocument +A method-agnostic DID Document. + +Note: All methods that involve reading from this class may potentially raise an error +if the object is being concurrently modified. + +**Kind**: global class + +* [CoreDocument](#CoreDocument) + * [new CoreDocument(values)](#new_CoreDocument_new) + * _instance_ + * [.id()](#CoreDocument+id) ⇒ [CoreDID](#CoreDID) + * [.setId(id)](#CoreDocument+setId) + * [.controller()](#CoreDocument+controller) ⇒ [Array.<CoreDID>](#CoreDID) + * [.setController(controllers)](#CoreDocument+setController) + * [.alsoKnownAs()](#CoreDocument+alsoKnownAs) ⇒ Array.<string> + * [.setAlsoKnownAs(urls)](#CoreDocument+setAlsoKnownAs) + * [.verificationMethod()](#CoreDocument+verificationMethod) ⇒ [Array.<VerificationMethod>](#VerificationMethod) + * [.authentication()](#CoreDocument+authentication) ⇒ Array.<(DIDUrl\|VerificationMethod)> + * [.assertionMethod()](#CoreDocument+assertionMethod) ⇒ Array.<(DIDUrl\|VerificationMethod)> + * [.keyAgreement()](#CoreDocument+keyAgreement) ⇒ Array.<(DIDUrl\|VerificationMethod)> + * [.capabilityDelegation()](#CoreDocument+capabilityDelegation) ⇒ Array.<(DIDUrl\|VerificationMethod)> + * [.capabilityInvocation()](#CoreDocument+capabilityInvocation) ⇒ Array.<(DIDUrl\|VerificationMethod)> + * [.properties()](#CoreDocument+properties) ⇒ Map.<string, any> + * [.setPropertyUnchecked(key, value)](#CoreDocument+setPropertyUnchecked) + * [.service()](#CoreDocument+service) ⇒ [Array.<Service>](#Service) + * [.insertService(service)](#CoreDocument+insertService) + * [.removeService(didUrl)](#CoreDocument+removeService) ⇒ [Service](#Service) \| undefined + * [.resolveService(query)](#CoreDocument+resolveService) ⇒ [Service](#Service) \| undefined + * [.methods(scope)](#CoreDocument+methods) ⇒ [Array.<VerificationMethod>](#VerificationMethod) + * [.verificationRelationships()](#CoreDocument+verificationRelationships) ⇒ Array.<(DIDUrl\|VerificationMethod)> + * [.insertMethod(method, scope)](#CoreDocument+insertMethod) + * [.removeMethod(did)](#CoreDocument+removeMethod) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + * [.resolveMethod(query, scope)](#CoreDocument+resolveMethod) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + * [.attachMethodRelationship(didUrl, relationship)](#CoreDocument+attachMethodRelationship) ⇒ boolean + * [.detachMethodRelationship(didUrl, relationship)](#CoreDocument+detachMethodRelationship) ⇒ boolean + * [.verifyJws(jws, options, signatureVerifier, detachedPayload)](#CoreDocument+verifyJws) ⇒ [DecodedJws](#DecodedJws) + * [.revokeCredentials(serviceQuery, indices)](#CoreDocument+revokeCredentials) + * [.unrevokeCredentials(serviceQuery, indices)](#CoreDocument+unrevokeCredentials) + * [.clone()](#CoreDocument+clone) ⇒ [CoreDocument](#CoreDocument) + * [._shallowCloneInternal()](#CoreDocument+_shallowCloneInternal) ⇒ [CoreDocument](#CoreDocument) + * [._strongCountInternal()](#CoreDocument+_strongCountInternal) ⇒ number + * [.toJSON()](#CoreDocument+toJSON) ⇒ any + * [.generateMethod(storage, keyType, alg, fragment, scope)](#CoreDocument+generateMethod) ⇒ Promise.<string> + * [.purgeMethod(storage, id)](#CoreDocument+purgeMethod) ⇒ Promise.<void> + * [.createJws(storage, fragment, payload, options)](#CoreDocument+createJws) ⇒ [Promise.<Jws>](#Jws) + * [.createCredentialJwt(storage, fragment, credential, options, custom_claims)](#CoreDocument+createCredentialJwt) ⇒ [Promise.<Jwt>](#Jwt) + * [.createPresentationJwt(storage, fragment, presentation, signature_options, presentation_options)](#CoreDocument+createPresentationJwt) ⇒ [Promise.<Jwt>](#Jwt) + * _static_ + * [.fromJSON(json)](#CoreDocument.fromJSON) ⇒ [CoreDocument](#CoreDocument) + + + +### new CoreDocument(values) +Creates a new [CoreDocument](#CoreDocument) with the given properties. + + +| Param | Type | +| --- | --- | +| values | ICoreDocument | + + + +### coreDocument.id() ⇒ [CoreDID](#CoreDID) +Returns a copy of the DID Document `id`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.setId(id) +Sets the DID of the document. + +### Warning + +Changing the identifier can drastically alter the results of +`resolve_method`, `resolve_service` and the related +[DID URL dereferencing](https://w3c-ccg.github.io/did-resolution/#dereferencing) algorithm. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| id | [CoreDID](#CoreDID) | + + + +### coreDocument.controller() ⇒ [Array.<CoreDID>](#CoreDID) +Returns a copy of the document controllers. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.setController(controllers) +Sets the controllers of the DID Document. + +Note: Duplicates will be ignored. +Use `null` to remove all controllers. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| controllers | [CoreDID](#CoreDID) \| [Array.<CoreDID>](#CoreDID) \| null | + + + +### coreDocument.alsoKnownAs() ⇒ Array.<string> +Returns a copy of the document's `alsoKnownAs` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.setAlsoKnownAs(urls) +Sets the `alsoKnownAs` property in the DID document. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| urls | string \| Array.<string> \| null | + + + +### coreDocument.verificationMethod() ⇒ [Array.<VerificationMethod>](#VerificationMethod) +Returns a copy of the document's `verificationMethod` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.authentication() ⇒ Array.<(DIDUrl\|VerificationMethod)> +Returns a copy of the document's `authentication` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.assertionMethod() ⇒ Array.<(DIDUrl\|VerificationMethod)> +Returns a copy of the document's `assertionMethod` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.keyAgreement() ⇒ Array.<(DIDUrl\|VerificationMethod)> +Returns a copy of the document's `keyAgreement` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.capabilityDelegation() ⇒ Array.<(DIDUrl\|VerificationMethod)> +Returns a copy of the document's `capabilityDelegation` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.capabilityInvocation() ⇒ Array.<(DIDUrl\|VerificationMethod)> +Returns a copy of the document's `capabilityInvocation` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.properties() ⇒ Map.<string, any> +Returns a copy of the custom DID Document properties. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.setPropertyUnchecked(key, value) +Sets a custom property in the DID Document. +If the value is set to `null`, the custom property will be removed. + +### WARNING + +This method can overwrite existing properties like `id` and result in an invalid document. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| key | string | +| value | any | + + + +### coreDocument.service() ⇒ [Array.<Service>](#Service) +Returns a set of all [Service](#Service) in the document. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.insertService(service) +Add a new [Service](#Service) to the document. + +Errors if there already exists a service or verification method with the same id. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| service | [Service](#Service) | + + + +### coreDocument.removeService(didUrl) ⇒ [Service](#Service) \| undefined +Remove a [Service](#Service) identified by the given [DIDUrl](#DIDUrl) from the document. + +Returns `true` if the service was removed. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| didUrl | [DIDUrl](#DIDUrl) | + + + +### coreDocument.resolveService(query) ⇒ [Service](#Service) \| undefined +Returns the first [Service](#Service) with an `id` property matching the provided `query`, +if present. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| query | [DIDUrl](#DIDUrl) \| string | + + + +### coreDocument.methods(scope) ⇒ [Array.<VerificationMethod>](#VerificationMethod) +Returns a list of all [VerificationMethod](#VerificationMethod) in the DID Document, +whose verification relationship matches `scope`. + +If `scope` is not set, a list over the **embedded** methods is returned. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| scope | [MethodScope](#MethodScope) \| undefined | + + + +### coreDocument.verificationRelationships() ⇒ Array.<(DIDUrl\|VerificationMethod)> +Returns an array of all verification relationships. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.insertMethod(method, scope) +Adds a new `method` to the document in the given `scope`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| method | [VerificationMethod](#VerificationMethod) | +| scope | [MethodScope](#MethodScope) | + + + +### coreDocument.removeMethod(did) ⇒ [VerificationMethod](#VerificationMethod) \| undefined +Removes all references to the specified Verification Method. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| did | [DIDUrl](#DIDUrl) | + + + +### coreDocument.resolveMethod(query, scope) ⇒ [VerificationMethod](#VerificationMethod) \| undefined +Returns a copy of the first verification method with an `id` property +matching the provided `query` and the verification relationship +specified by `scope`, if present. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| query | [DIDUrl](#DIDUrl) \| string | +| scope | [MethodScope](#MethodScope) \| undefined | + + + +### coreDocument.attachMethodRelationship(didUrl, relationship) ⇒ boolean +Attaches the relationship to the given method, if the method exists. + +Note: The method needs to be in the set of verification methods, +so it cannot be an embedded one. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| didUrl | [DIDUrl](#DIDUrl) | +| relationship | number | + + + +### coreDocument.detachMethodRelationship(didUrl, relationship) ⇒ boolean +Detaches the given relationship from the given method, if the method exists. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| didUrl | [DIDUrl](#DIDUrl) | +| relationship | number | + + + +### coreDocument.verifyJws(jws, options, signatureVerifier, detachedPayload) ⇒ [DecodedJws](#DecodedJws) +Decodes and verifies the provided JWS according to the passed `options` and `signatureVerifier`. + If no `signatureVerifier` argument is provided a default verifier will be used that is (only) capable of +verifying EdDSA signatures. + +Regardless of which options are passed the following conditions must be met in order for a verification attempt to +take place. +- The JWS must be encoded according to the JWS compact serialization. +- The `kid` value in the protected header must be an identifier of a verification method in this DID document, +or set explicitly in the `options`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| jws | [Jws](#Jws) | +| options | [JwsVerificationOptions](#JwsVerificationOptions) | +| signatureVerifier | IJwsVerifier | +| detachedPayload | string \| undefined | + + + +### coreDocument.revokeCredentials(serviceQuery, indices) +If the document has a [RevocationBitmap](#RevocationBitmap) service identified by `serviceQuery`, +revoke all specified `indices`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| serviceQuery | [DIDUrl](#DIDUrl) \| string | +| indices | number \| Array.<number> | + + + +### coreDocument.unrevokeCredentials(serviceQuery, indices) +If the document has a [RevocationBitmap](#RevocationBitmap) service identified by `serviceQuery`, +unrevoke all specified `indices`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| serviceQuery | [DIDUrl](#DIDUrl) \| string | +| indices | number \| Array.<number> | + + + +### coreDocument.clone() ⇒ [CoreDocument](#CoreDocument) +Deep clones the [CoreDocument](#CoreDocument). + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.\_shallowCloneInternal() ⇒ [CoreDocument](#CoreDocument) +### Warning +This is for internal use only. Do not rely on or call this method. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.\_strongCountInternal() ⇒ number +### Warning +This is for internal use only. Do not rely on or call this method. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.toJSON() ⇒ any +Serializes to a plain JS representation. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + +### coreDocument.generateMethod(storage, keyType, alg, fragment, scope) ⇒ Promise.<string> +Generate new key material in the given `storage` and insert a new verification method with the corresponding +public key material into the DID document. + +- If no fragment is given the `kid` of the generated JWK is used, if it is set, otherwise an error is returned. +- The `keyType` must be compatible with the given `storage`. `Storage`s are expected to export key type constants +for that use case. + +The fragment of the generated method is returned. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| keyType | string | +| alg | JwsAlgorithm | +| fragment | string \| undefined | +| scope | [MethodScope](#MethodScope) | + + + +### coreDocument.purgeMethod(storage, id) ⇒ Promise.<void> +Remove the method identified by the `fragment` from the document and delete the corresponding key material in +the `storage`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| id | [DIDUrl](#DIDUrl) | + + + +### coreDocument.createJws(storage, fragment, payload, options) ⇒ [Promise.<Jws>](#Jws) +Sign the `payload` according to `options` with the storage backed private key corresponding to the public key +material in the verification method identified by the given `fragment. + +Upon success a string representing a JWS encoded according to the Compact JWS Serialization format is returned. +See [RFC7515 section 3.1](https://www.rfc-editor.org/rfc/rfc7515#section-3.1). + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| fragment | string | +| payload | string | +| options | [JwsSignatureOptions](#JwsSignatureOptions) | + + + +### coreDocument.createCredentialJwt(storage, fragment, credential, options, custom_claims) ⇒ [Promise.<Jwt>](#Jwt) +Produces a JWT where the payload is produced from the given `credential` +in accordance with [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token). + +Unless the `kid` is explicitly set in the options, the `kid` in the protected header is the `id` +of the method identified by `fragment` and the JWS signature will be produced by the corresponding +private key backed by the `storage` in accordance with the passed `options`. + +The `custom_claims` can be used to set additional claims on the resulting JWT. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| fragment | string | +| credential | [Credential](#Credential) | +| options | [JwsSignatureOptions](#JwsSignatureOptions) | +| custom_claims | Record.<string, any> \| undefined | + + + +### coreDocument.createPresentationJwt(storage, fragment, presentation, signature_options, presentation_options) ⇒ [Promise.<Jwt>](#Jwt) +Produces a JWT where the payload is produced from the given presentation. +in accordance with [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token). + +Unless the `kid` is explicitly set in the options, the `kid` in the protected header is the `id` +of the method identified by `fragment` and the JWS signature will be produced by the corresponding +private key backed by the `storage` in accordance with the passed `options`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| fragment | string | +| presentation | [Presentation](#Presentation) | +| signature_options | [JwsSignatureOptions](#JwsSignatureOptions) | +| presentation_options | [JwtPresentationOptions](#JwtPresentationOptions) | + + + +### CoreDocument.fromJSON(json) ⇒ [CoreDocument](#CoreDocument) +Deserializes an instance from a plain JS representation. + +**Kind**: static method of [CoreDocument](#CoreDocument) + +| Param | Type | +| --- | --- | +| json | any | + + + +## Credential +**Kind**: global class + +* [Credential](#Credential) + * [new Credential(values)](#new_Credential_new) + * _instance_ + * [.context()](#Credential+context) ⇒ Array.<(string\|Record.<string, any>)> + * [.id()](#Credential+id) ⇒ string \| undefined + * [.type()](#Credential+type) ⇒ Array.<string> + * [.credentialSubject()](#Credential+credentialSubject) ⇒ Array.<Subject> + * [.issuer()](#Credential+issuer) ⇒ string \| Issuer + * [.issuanceDate()](#Credential+issuanceDate) ⇒ [Timestamp](#Timestamp) + * [.expirationDate()](#Credential+expirationDate) ⇒ [Timestamp](#Timestamp) \| undefined + * [.credentialStatus()](#Credential+credentialStatus) ⇒ Array.<Status> + * [.credentialSchema()](#Credential+credentialSchema) ⇒ Array.<Schema> + * [.refreshService()](#Credential+refreshService) ⇒ Array.<RefreshService> + * [.termsOfUse()](#Credential+termsOfUse) ⇒ Array.<Policy> + * [.evidence()](#Credential+evidence) ⇒ Array.<Evidence> + * [.nonTransferable()](#Credential+nonTransferable) ⇒ boolean \| undefined + * [.proof()](#Credential+proof) ⇒ [Proof](#Proof) \| undefined + * [.properties()](#Credential+properties) ⇒ Map.<string, any> + * [.setProof(proof)](#Credential+setProof) + * [.toJwtClaims(custom_claims)](#Credential+toJwtClaims) ⇒ Record.<string, any> + * [.toJSON()](#Credential+toJSON) ⇒ any + * [.clone()](#Credential+clone) ⇒ [Credential](#Credential) + * _static_ + * [.BaseContext()](#Credential.BaseContext) ⇒ string + * [.BaseType()](#Credential.BaseType) ⇒ string + * [.createDomainLinkageCredential(values)](#Credential.createDomainLinkageCredential) ⇒ [Credential](#Credential) + * [.fromJSON(json)](#Credential.fromJSON) ⇒ [Credential](#Credential) + + + +### new Credential(values) +Constructs a new [Credential](#Credential). + + +| Param | Type | +| --- | --- | +| values | ICredential | + + + +### credential.context() ⇒ Array.<(string\|Record.<string, any>)> +Returns a copy of the JSON-LD context(s) applicable to the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + +### credential.id() ⇒ string \| undefined +Returns a copy of the unique `URI` identifying the [Credential](#Credential) . + +**Kind**: instance method of [Credential](#Credential) + + +### credential.type() ⇒ Array.<string> +Returns a copy of the URIs defining the type of the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + +### credential.credentialSubject() ⇒ Array.<Subject> +Returns a copy of the [Credential](#Credential) subject(s). + +**Kind**: instance method of [Credential](#Credential) + + +### credential.issuer() ⇒ string \| Issuer +Returns a copy of the issuer of the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + +### credential.issuanceDate() ⇒ [Timestamp](#Timestamp) +Returns a copy of the timestamp of when the [Credential](#Credential) becomes valid. + +**Kind**: instance method of [Credential](#Credential) + + +### credential.expirationDate() ⇒ [Timestamp](#Timestamp) \| undefined +Returns a copy of the timestamp of when the [Credential](#Credential) should no longer be considered valid. + +**Kind**: instance method of [Credential](#Credential) + + +### credential.credentialStatus() ⇒ Array.<Status> +Returns a copy of the information used to determine the current status of the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + +### credential.credentialSchema() ⇒ Array.<Schema> +Returns a copy of the information used to assist in the enforcement of a specific [Credential](#Credential) structure. + +**Kind**: instance method of [Credential](#Credential) + + +### credential.refreshService() ⇒ Array.<RefreshService> +Returns a copy of the service(s) used to refresh an expired [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + +### credential.termsOfUse() ⇒ Array.<Policy> +Returns a copy of the terms-of-use specified by the [Credential](#Credential) issuer. + +**Kind**: instance method of [Credential](#Credential) + + +### credential.evidence() ⇒ Array.<Evidence> +Returns a copy of the human-readable evidence used to support the claims within the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + +### credential.nonTransferable() ⇒ boolean \| undefined +Returns whether or not the [Credential](#Credential) must only be contained within a [Presentation](#Presentation) +with a proof issued from the [Credential](#Credential) subject. + +**Kind**: instance method of [Credential](#Credential) + + +### credential.proof() ⇒ [Proof](#Proof) \| undefined +Optional cryptographic proof, unrelated to JWT. + +**Kind**: instance method of [Credential](#Credential) + + +### credential.properties() ⇒ Map.<string, any> +Returns a copy of the miscellaneous properties on the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + +### credential.setProof(proof) +Sets the `proof` property of the [Credential](#Credential). + +Note that this proof is not related to JWT. + +**Kind**: instance method of [Credential](#Credential) + +| Param | Type | +| --- | --- | +| proof | [Proof](#Proof) \| undefined | + + + +### credential.toJwtClaims(custom_claims) ⇒ Record.<string, any> +Serializes the `Credential` as a JWT claims set +in accordance with [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token). + +The resulting object can be used as the payload of a JWS when issuing the credential. + +**Kind**: instance method of [Credential](#Credential) + +| Param | Type | +| --- | --- | +| custom_claims | Record.<string, any> \| undefined | + + + +### credential.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [Credential](#Credential) + + +### credential.clone() ⇒ [Credential](#Credential) +Deep clones the object. + +**Kind**: instance method of [Credential](#Credential) + + +### Credential.BaseContext() ⇒ string +Returns the base JSON-LD context. + +**Kind**: static method of [Credential](#Credential) + + +### Credential.BaseType() ⇒ string +Returns the base type. + +**Kind**: static method of [Credential](#Credential) + + +### Credential.createDomainLinkageCredential(values) ⇒ [Credential](#Credential) +**Kind**: static method of [Credential](#Credential) + +| Param | Type | +| --- | --- | +| values | IDomainLinkageCredential | + + + +### Credential.fromJSON(json) ⇒ [Credential](#Credential) +Deserializes an instance from a JSON object. + +**Kind**: static method of [Credential](#Credential) + +| Param | Type | +| --- | --- | +| json | any | + + + +## DIDUrl +A method agnostic DID Url. + +**Kind**: global class + +* [DIDUrl](#DIDUrl) + * _instance_ + * [.did()](#DIDUrl+did) ⇒ [CoreDID](#CoreDID) + * [.urlStr()](#DIDUrl+urlStr) ⇒ string + * [.fragment()](#DIDUrl+fragment) ⇒ string \| undefined + * [.setFragment(value)](#DIDUrl+setFragment) + * [.path()](#DIDUrl+path) ⇒ string \| undefined + * [.setPath(value)](#DIDUrl+setPath) + * [.query()](#DIDUrl+query) ⇒ string \| undefined + * [.setQuery(value)](#DIDUrl+setQuery) + * [.join(segment)](#DIDUrl+join) ⇒ [DIDUrl](#DIDUrl) + * [.toString()](#DIDUrl+toString) ⇒ string + * [.toJSON()](#DIDUrl+toJSON) ⇒ any + * [.clone()](#DIDUrl+clone) ⇒ [DIDUrl](#DIDUrl) + * _static_ + * [.parse(input)](#DIDUrl.parse) ⇒ [DIDUrl](#DIDUrl) + * [.fromJSON(json)](#DIDUrl.fromJSON) ⇒ [DIDUrl](#DIDUrl) + + + +### didUrl.did() ⇒ [CoreDID](#CoreDID) +Return a copy of the [CoreDID](#CoreDID) section of the [DIDUrl](#DIDUrl). + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + +### didUrl.urlStr() ⇒ string +Return a copy of the relative DID Url as a string, including only the path, query, and fragment. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + +### didUrl.fragment() ⇒ string \| undefined +Returns a copy of the [DIDUrl](#DIDUrl) method fragment, if any. Excludes the leading '#'. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + +### didUrl.setFragment(value) +Sets the `fragment` component of the [DIDUrl](#DIDUrl). + +**Kind**: instance method of [DIDUrl](#DIDUrl) + +| Param | Type | +| --- | --- | +| value | string \| undefined | + + + +### didUrl.path() ⇒ string \| undefined +Returns a copy of the [DIDUrl](#DIDUrl) path. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + +### didUrl.setPath(value) +Sets the `path` component of the [DIDUrl](#DIDUrl). + +**Kind**: instance method of [DIDUrl](#DIDUrl) + +| Param | Type | +| --- | --- | +| value | string \| undefined | + + + +### didUrl.query() ⇒ string \| undefined +Returns a copy of the [DIDUrl](#DIDUrl) method query, if any. Excludes the leading '?'. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + +### didUrl.setQuery(value) +Sets the `query` component of the [DIDUrl](#DIDUrl). + +**Kind**: instance method of [DIDUrl](#DIDUrl) + +| Param | Type | +| --- | --- | +| value | string \| undefined | + + + +### didUrl.join(segment) ⇒ [DIDUrl](#DIDUrl) +Append a string representing a path, query, and/or fragment, returning a new [DIDUrl](#DIDUrl). + +Must begin with a valid delimiter character: '/', '?', '#'. Overwrites the existing URL +segment and any following segments in order of path, query, then fragment. + +I.e. +- joining a path will clear the query and fragment. +- joining a query will clear the fragment. +- joining a fragment will only overwrite the fragment. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + +| Param | Type | +| --- | --- | +| segment | string | + + + +### didUrl.toString() ⇒ string +Returns the [DIDUrl](#DIDUrl) as a string. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + +### didUrl.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + +### didUrl.clone() ⇒ [DIDUrl](#DIDUrl) +Deep clones the object. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + +### DIDUrl.parse(input) ⇒ [DIDUrl](#DIDUrl) +Parses a [DIDUrl](#DIDUrl) from the input string. + +**Kind**: static method of [DIDUrl](#DIDUrl) + +| Param | Type | +| --- | --- | +| input | string | + + + +### DIDUrl.fromJSON(json) ⇒ [DIDUrl](#DIDUrl) +Deserializes an instance from a JSON object. + +**Kind**: static method of [DIDUrl](#DIDUrl) + +| Param | Type | +| --- | --- | +| json | any | + + + +## DecodedJws +A cryptographically verified decoded token from a JWS. + +Contains the decoded headers and the raw claims. + +**Kind**: global class + +* [DecodedJws](#DecodedJws) + * [.claims()](#DecodedJws+claims) ⇒ string + * [.claimsBytes()](#DecodedJws+claimsBytes) ⇒ Uint8Array + * [.protectedHeader()](#DecodedJws+protectedHeader) ⇒ [JwsHeader](#JwsHeader) + * [.clone()](#DecodedJws+clone) ⇒ [DecodedJws](#DecodedJws) + * [.toJSON()](#DecodedJws+toJSON) ⇒ any + + + +### decodedJws.claims() ⇒ string +Returns a copy of the parsed claims represented as a string. + +# Errors +An error is thrown if the claims cannot be represented as a string. + +This error can only occur if the Token was decoded from a detached payload. + +**Kind**: instance method of [DecodedJws](#DecodedJws) + + +### decodedJws.claimsBytes() ⇒ Uint8Array +Return a copy of the parsed claims represented as an array of bytes. + +**Kind**: instance method of [DecodedJws](#DecodedJws) + + +### decodedJws.protectedHeader() ⇒ [JwsHeader](#JwsHeader) +Returns a copy of the protected header. + +**Kind**: instance method of [DecodedJws](#DecodedJws) + + +### decodedJws.clone() ⇒ [DecodedJws](#DecodedJws) +Deep clones the object. + +**Kind**: instance method of [DecodedJws](#DecodedJws) + + +### decodedJws.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [DecodedJws](#DecodedJws) + + +## DecodedJwtCredential +A cryptographically verified and decoded Credential. + +Note that having an instance of this type only means the JWS it was constructed from was verified. +It does not imply anything about a potentially present proof property on the credential itself. + +**Kind**: global class + +* [DecodedJwtCredential](#DecodedJwtCredential) + * [.credential()](#DecodedJwtCredential+credential) ⇒ [Credential](#Credential) + * [.protectedHeader()](#DecodedJwtCredential+protectedHeader) ⇒ [JwsHeader](#JwsHeader) + * [.customClaims()](#DecodedJwtCredential+customClaims) ⇒ Record.<string, any> \| undefined + * [.intoCredential()](#DecodedJwtCredential+intoCredential) ⇒ [Credential](#Credential) + + + +### decodedJwtCredential.credential() ⇒ [Credential](#Credential) +Returns a copy of the credential parsed to the [Verifiable Credentials Data model](https://www.w3.org/TR/vc-data-model/). + +**Kind**: instance method of [DecodedJwtCredential](#DecodedJwtCredential) + + +### decodedJwtCredential.protectedHeader() ⇒ [JwsHeader](#JwsHeader) +Returns a copy of the protected header parsed from the decoded JWS. + +**Kind**: instance method of [DecodedJwtCredential](#DecodedJwtCredential) + + +### decodedJwtCredential.customClaims() ⇒ Record.<string, any> \| undefined +The custom claims parsed from the JWT. + +**Kind**: instance method of [DecodedJwtCredential](#DecodedJwtCredential) + + +### decodedJwtCredential.intoCredential() ⇒ [Credential](#Credential) +Consumes the object and returns the decoded credential. + +### Warning + +This destroys the [DecodedJwtCredential](#DecodedJwtCredential) object. + +**Kind**: instance method of [DecodedJwtCredential](#DecodedJwtCredential) + + +## DecodedJwtPresentation +A cryptographically verified and decoded presentation. + +Note that having an instance of this type only means the JWS it was constructed from was verified. +It does not imply anything about a potentially present proof property on the presentation itself. + +**Kind**: global class + +* [DecodedJwtPresentation](#DecodedJwtPresentation) + * [.presentation()](#DecodedJwtPresentation+presentation) ⇒ [Presentation](#Presentation) + * [.protectedHeader()](#DecodedJwtPresentation+protectedHeader) ⇒ [JwsHeader](#JwsHeader) + * [.intoPresentation()](#DecodedJwtPresentation+intoPresentation) ⇒ [Presentation](#Presentation) + * [.expirationDate()](#DecodedJwtPresentation+expirationDate) ⇒ [Timestamp](#Timestamp) \| undefined + * [.issuanceDate()](#DecodedJwtPresentation+issuanceDate) ⇒ [Timestamp](#Timestamp) \| undefined + * [.audience()](#DecodedJwtPresentation+audience) ⇒ string \| undefined + * [.customClaims()](#DecodedJwtPresentation+customClaims) ⇒ Record.<string, any> \| undefined + + + +### decodedJwtPresentation.presentation() ⇒ [Presentation](#Presentation) +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + +### decodedJwtPresentation.protectedHeader() ⇒ [JwsHeader](#JwsHeader) +Returns a copy of the protected header parsed from the decoded JWS. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + +### decodedJwtPresentation.intoPresentation() ⇒ [Presentation](#Presentation) +Consumes the object and returns the decoded presentation. + +### Warning +This destroys the [DecodedJwtPresentation](#DecodedJwtPresentation) object. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + +### decodedJwtPresentation.expirationDate() ⇒ [Timestamp](#Timestamp) \| undefined +The expiration date parsed from the JWT claims. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + +### decodedJwtPresentation.issuanceDate() ⇒ [Timestamp](#Timestamp) \| undefined +The issuance date parsed from the JWT claims. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + +### decodedJwtPresentation.audience() ⇒ string \| undefined +The `aud` property parsed from JWT claims. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + +### decodedJwtPresentation.customClaims() ⇒ Record.<string, any> \| undefined +The custom claims parsed from the JWT. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + +## Disclosure +Represents an elements constructing a disclosure. +Object properties and array elements disclosures are supported. + +See: https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html#name-disclosures + +**Kind**: global class + +* [Disclosure](#Disclosure) + * [new Disclosure(salt, claim_name, claim_value)](#new_Disclosure_new) + * _instance_ + * [.disclosure()](#Disclosure+disclosure) ⇒ string + * [.toEncodedString()](#Disclosure+toEncodedString) ⇒ string + * [.toString()](#Disclosure+toString) ⇒ string + * [.salt()](#Disclosure+salt) ⇒ string + * [.claimName()](#Disclosure+claimName) ⇒ string \| undefined + * [.claimValue()](#Disclosure+claimValue) ⇒ any + * [.toJSON()](#Disclosure+toJSON) ⇒ any + * _static_ + * [.parse(disclosure)](#Disclosure.parse) ⇒ [Disclosure](#Disclosure) + * [.fromJSON(json)](#Disclosure.fromJSON) ⇒ [Disclosure](#Disclosure) + + + +### new Disclosure(salt, claim_name, claim_value) + +| Param | Type | +| --- | --- | +| salt | string | +| claim_name | string \| undefined | +| claim_value | any | + + + +### disclosure.disclosure() ⇒ string +Returns a copy of the base64url-encoded string. + +**Kind**: instance method of [Disclosure](#Disclosure) + + +### disclosure.toEncodedString() ⇒ string +Returns a copy of the base64url-encoded string. + +**Kind**: instance method of [Disclosure](#Disclosure) + + +### disclosure.toString() ⇒ string +Returns a copy of the base64url-encoded string. + +**Kind**: instance method of [Disclosure](#Disclosure) + + +### disclosure.salt() ⇒ string +Returns a copy of the salt value. + +**Kind**: instance method of [Disclosure](#Disclosure) + + +### disclosure.claimName() ⇒ string \| undefined +Returns a copy of the claim name, optional for array elements. + +**Kind**: instance method of [Disclosure](#Disclosure) + + +### disclosure.claimValue() ⇒ any +Returns a copy of the claim Value which can be of any type. + +**Kind**: instance method of [Disclosure](#Disclosure) + + +### disclosure.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [Disclosure](#Disclosure) + + +### Disclosure.parse(disclosure) ⇒ [Disclosure](#Disclosure) +Parses a Base64 encoded disclosure into a `Disclosure`. + +## Error + +Returns an `InvalidDisclosure` if input is not a valid disclosure. + +**Kind**: static method of [Disclosure](#Disclosure) + +| Param | Type | +| --- | --- | +| disclosure | string | + + + +### Disclosure.fromJSON(json) ⇒ [Disclosure](#Disclosure) +Deserializes an instance from a JSON object. + +**Kind**: static method of [Disclosure](#Disclosure) + +| Param | Type | +| --- | --- | +| json | any | + + + +## DomainLinkageConfiguration +DID Configuration Resource which contains Domain Linkage Credentials. +It can be placed in an origin's `.well-known` directory to prove linkage between the origin and a DID. +See: + +Note: +- Only the [JSON Web Token Proof Format](https://identity.foundation/.well-known/resources/did-configuration/#json-web-token-proof-format) + +**Kind**: global class + +* [DomainLinkageConfiguration](#DomainLinkageConfiguration) + * [new DomainLinkageConfiguration(linkedDids)](#new_DomainLinkageConfiguration_new) + * _instance_ + * [.linkedDids()](#DomainLinkageConfiguration+linkedDids) ⇒ [Array.<Jwt>](#Jwt) + * [.issuers()](#DomainLinkageConfiguration+issuers) ⇒ [Array.<CoreDID>](#CoreDID) + * [.toJSON()](#DomainLinkageConfiguration+toJSON) ⇒ any + * [.clone()](#DomainLinkageConfiguration+clone) ⇒ [DomainLinkageConfiguration](#DomainLinkageConfiguration) + * _static_ + * [.fromJSON(json)](#DomainLinkageConfiguration.fromJSON) ⇒ [DomainLinkageConfiguration](#DomainLinkageConfiguration) + + + +### new DomainLinkageConfiguration(linkedDids) +Constructs a new [DomainLinkageConfiguration](#DomainLinkageConfiguration). + + +| Param | Type | +| --- | --- | +| linkedDids | [Array.<Jwt>](#Jwt) | + + + +### domainLinkageConfiguration.linkedDids() ⇒ [Array.<Jwt>](#Jwt) +List of the Domain Linkage Credentials. + +**Kind**: instance method of [DomainLinkageConfiguration](#DomainLinkageConfiguration) + + +### domainLinkageConfiguration.issuers() ⇒ [Array.<CoreDID>](#CoreDID) +List of the issuers of the Domain Linkage Credentials. + +**Kind**: instance method of [DomainLinkageConfiguration](#DomainLinkageConfiguration) + + +### domainLinkageConfiguration.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [DomainLinkageConfiguration](#DomainLinkageConfiguration) + + +### domainLinkageConfiguration.clone() ⇒ [DomainLinkageConfiguration](#DomainLinkageConfiguration) +Deep clones the object. + +**Kind**: instance method of [DomainLinkageConfiguration](#DomainLinkageConfiguration) + + +### DomainLinkageConfiguration.fromJSON(json) ⇒ [DomainLinkageConfiguration](#DomainLinkageConfiguration) +Deserializes an instance from a JSON object. + +**Kind**: static method of [DomainLinkageConfiguration](#DomainLinkageConfiguration) + +| Param | Type | +| --- | --- | +| json | any | + + + +## Duration +A span of time. + +**Kind**: global class + +* [Duration](#Duration) + * _instance_ + * [.toJSON()](#Duration+toJSON) ⇒ any + * _static_ + * [.seconds(seconds)](#Duration.seconds) ⇒ [Duration](#Duration) + * [.minutes(minutes)](#Duration.minutes) ⇒ [Duration](#Duration) + * [.hours(hours)](#Duration.hours) ⇒ [Duration](#Duration) + * [.days(days)](#Duration.days) ⇒ [Duration](#Duration) + * [.weeks(weeks)](#Duration.weeks) ⇒ [Duration](#Duration) + * [.fromJSON(json)](#Duration.fromJSON) ⇒ [Duration](#Duration) + + + +### duration.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [Duration](#Duration) + + +### Duration.seconds(seconds) ⇒ [Duration](#Duration) +Create a new [Duration](#Duration) with the given number of seconds. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| --- | --- | +| seconds | number | + + + +### Duration.minutes(minutes) ⇒ [Duration](#Duration) +Create a new [Duration](#Duration) with the given number of minutes. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| --- | --- | +| minutes | number | + + + +### Duration.hours(hours) ⇒ [Duration](#Duration) +Create a new [Duration](#Duration) with the given number of hours. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| --- | --- | +| hours | number | + + + +### Duration.days(days) ⇒ [Duration](#Duration) +Create a new [Duration](#Duration) with the given number of days. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| --- | --- | +| days | number | + + + +### Duration.weeks(weeks) ⇒ [Duration](#Duration) +Create a new [Duration](#Duration) with the given number of weeks. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| --- | --- | +| weeks | number | + + + +### Duration.fromJSON(json) ⇒ [Duration](#Duration) +Deserializes an instance from a JSON object. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| --- | --- | +| json | any | + + + +## EdDSAJwsVerifier +An implementor of `IJwsVerifier` that can handle the +`EdDSA` algorithm. + +**Kind**: global class + +* [EdDSAJwsVerifier](#EdDSAJwsVerifier) + * [new EdDSAJwsVerifier()](#new_EdDSAJwsVerifier_new) + * [.verify(alg, signingInput, decodedSignature, publicKey)](#EdDSAJwsVerifier+verify) + + + +### new EdDSAJwsVerifier() +Constructs an EdDSAJwsVerifier. + + + +### edDSAJwsVerifier.verify(alg, signingInput, decodedSignature, publicKey) +Verify a JWS signature secured with the `EdDSA` algorithm. +Only the `Ed25519` curve is supported for now. + +This function is useful when one is building an `IJwsVerifier` that extends the default provided by +the IOTA Identity Framework. + +# Warning + +This function does not check whether `alg = EdDSA` in the protected header. Callers are expected to assert this +prior to calling the function. + +**Kind**: instance method of [EdDSAJwsVerifier](#EdDSAJwsVerifier) + +| Param | Type | +| --- | --- | +| alg | JwsAlgorithm | +| signingInput | Uint8Array | +| decodedSignature | Uint8Array | +| publicKey | [Jwk](#Jwk) | + + + +## IotaDID +A DID conforming to the IOTA DID method specification. + +**Kind**: global class + +* [IotaDID](#IotaDID) + * [new IotaDID(bytes, network)](#new_IotaDID_new) + * _instance_ + * [.network()](#IotaDID+network) ⇒ string + * [.tag()](#IotaDID+tag) ⇒ string + * [.toCoreDid()](#IotaDID+toCoreDid) ⇒ [CoreDID](#CoreDID) + * [.scheme()](#IotaDID+scheme) ⇒ string + * [.authority()](#IotaDID+authority) ⇒ string + * [.method()](#IotaDID+method) ⇒ string + * [.methodId()](#IotaDID+methodId) ⇒ string + * [.join(segment)](#IotaDID+join) ⇒ [DIDUrl](#DIDUrl) + * [.toUrl()](#IotaDID+toUrl) ⇒ [DIDUrl](#DIDUrl) + * [.toAliasId()](#IotaDID+toAliasId) ⇒ string + * [.intoUrl()](#IotaDID+intoUrl) ⇒ [DIDUrl](#DIDUrl) + * [.toString()](#IotaDID+toString) ⇒ string + * [.toJSON()](#IotaDID+toJSON) ⇒ any + * [.clone()](#IotaDID+clone) ⇒ [IotaDID](#IotaDID) + * _static_ + * [.METHOD](#IotaDID.METHOD) ⇒ string + * [.DEFAULT_NETWORK](#IotaDID.DEFAULT_NETWORK) ⇒ string + * [.fromAliasId(aliasId, network)](#IotaDID.fromAliasId) ⇒ [IotaDID](#IotaDID) + * [.placeholder(network)](#IotaDID.placeholder) ⇒ [IotaDID](#IotaDID) + * [.parse(input)](#IotaDID.parse) ⇒ [IotaDID](#IotaDID) + * [.fromJSON(json)](#IotaDID.fromJSON) ⇒ [IotaDID](#IotaDID) + + + +### new IotaDID(bytes, network) +Constructs a new [IotaDID](#IotaDID) from a byte representation of the tag and the given +network name. + +See also [placeholder](#IotaDID.placeholder). + + +| Param | Type | +| --- | --- | +| bytes | Uint8Array | +| network | string | + + + +### did.network() ⇒ string +Returns the Tangle network name of the [IotaDID](#IotaDID). + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.tag() ⇒ string +Returns a copy of the unique tag of the [IotaDID](#IotaDID). + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.toCoreDid() ⇒ [CoreDID](#CoreDID) +Returns the DID represented as a [CoreDID](#CoreDID). + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.scheme() ⇒ string +Returns the `DID` scheme. + +E.g. +- `"did:example:12345678" -> "did"` +- `"did:iota:main:12345678" -> "did"` + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.authority() ⇒ string +Returns the `DID` authority: the method name and method-id. + +E.g. +- `"did:example:12345678" -> "example:12345678"` +- `"did:iota:main:12345678" -> "iota:main:12345678"` + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.method() ⇒ string +Returns the `DID` method name. + +E.g. +- `"did:example:12345678" -> "example"` +- `"did:iota:main:12345678" -> "iota"` + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.methodId() ⇒ string +Returns the `DID` method-specific ID. + +E.g. +- `"did:example:12345678" -> "12345678"` +- `"did:iota:main:12345678" -> "main:12345678"` + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.join(segment) ⇒ [DIDUrl](#DIDUrl) +Construct a new [DIDUrl](#DIDUrl) by joining with a relative DID Url string. + +**Kind**: instance method of [IotaDID](#IotaDID) + +| Param | Type | +| --- | --- | +| segment | string | + + + +### did.toUrl() ⇒ [DIDUrl](#DIDUrl) +Clones the `DID` into a [DIDUrl](#DIDUrl). + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.toAliasId() ⇒ string +Returns the hex-encoded AliasId with a '0x' prefix, from the DID tag. + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.intoUrl() ⇒ [DIDUrl](#DIDUrl) +Converts the `DID` into a [DIDUrl](#DIDUrl), consuming it. + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.toString() ⇒ string +Returns the `DID` as a string. + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### did.clone() ⇒ [IotaDID](#IotaDID) +Deep clones the object. + +**Kind**: instance method of [IotaDID](#IotaDID) + + +### IotaDID.METHOD ⇒ string +The IOTA DID method name (`"iota"`). + +**Kind**: static property of [IotaDID](#IotaDID) + + +### IotaDID.DEFAULT\_NETWORK ⇒ string +The default Tangle network (`"iota"`). + +**Kind**: static property of [IotaDID](#IotaDID) + + +### IotaDID.fromAliasId(aliasId, network) ⇒ [IotaDID](#IotaDID) +Constructs a new [IotaDID](#IotaDID) from a hex representation of an Alias Id and the given +network name. + +**Kind**: static method of [IotaDID](#IotaDID) + +| Param | Type | +| --- | --- | +| aliasId | string | +| network | string | + + + +### IotaDID.placeholder(network) ⇒ [IotaDID](#IotaDID) +Creates a new placeholder [IotaDID](#IotaDID) with the given network name. + +E.g. `did:iota:smr:0x0000000000000000000000000000000000000000000000000000000000000000`. + +**Kind**: static method of [IotaDID](#IotaDID) + +| Param | Type | +| --- | --- | +| network | string | + + + +### IotaDID.parse(input) ⇒ [IotaDID](#IotaDID) +Parses a [IotaDID](#IotaDID) from the input string. + +**Kind**: static method of [IotaDID](#IotaDID) + +| Param | Type | +| --- | --- | +| input | string | + + + +### IotaDID.fromJSON(json) ⇒ [IotaDID](#IotaDID) +Deserializes an instance from a JSON object. + +**Kind**: static method of [IotaDID](#IotaDID) + +| Param | Type | +| --- | --- | +| json | any | + + + +## IotaDocument +A DID Document adhering to the IOTA DID method specification. + +Note: All methods that involve reading from this class may potentially raise an error +if the object is being concurrently modified. + +**Kind**: global class + +* [IotaDocument](#IotaDocument) + * [new IotaDocument(network)](#new_IotaDocument_new) + * _instance_ + * [.id()](#IotaDocument+id) ⇒ [IotaDID](#IotaDID) + * [.controller()](#IotaDocument+controller) ⇒ [Array.<IotaDID>](#IotaDID) + * [.alsoKnownAs()](#IotaDocument+alsoKnownAs) ⇒ Array.<string> + * [.setAlsoKnownAs(urls)](#IotaDocument+setAlsoKnownAs) + * [.properties()](#IotaDocument+properties) ⇒ Map.<string, any> + * [.setPropertyUnchecked(key, value)](#IotaDocument+setPropertyUnchecked) + * [.service()](#IotaDocument+service) ⇒ [Array.<Service>](#Service) + * [.insertService(service)](#IotaDocument+insertService) + * [.removeService(did)](#IotaDocument+removeService) ⇒ [Service](#Service) \| undefined + * [.resolveService(query)](#IotaDocument+resolveService) ⇒ [Service](#Service) \| undefined + * [.methods(scope)](#IotaDocument+methods) ⇒ [Array.<VerificationMethod>](#VerificationMethod) + * [.insertMethod(method, scope)](#IotaDocument+insertMethod) + * [.removeMethod(did)](#IotaDocument+removeMethod) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + * [.resolveMethod(query, scope)](#IotaDocument+resolveMethod) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + * [.attachMethodRelationship(didUrl, relationship)](#IotaDocument+attachMethodRelationship) ⇒ boolean + * [.detachMethodRelationship(didUrl, relationship)](#IotaDocument+detachMethodRelationship) ⇒ boolean + * [.verifyJws(jws, options, signatureVerifier, detachedPayload)](#IotaDocument+verifyJws) ⇒ [DecodedJws](#DecodedJws) + * [.pack()](#IotaDocument+pack) ⇒ Uint8Array + * [.packWithEncoding(encoding)](#IotaDocument+packWithEncoding) ⇒ Uint8Array + * [.metadata()](#IotaDocument+metadata) ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) + * [.metadataCreated()](#IotaDocument+metadataCreated) ⇒ [Timestamp](#Timestamp) \| undefined + * [.setMetadataCreated(timestamp)](#IotaDocument+setMetadataCreated) + * [.metadataUpdated()](#IotaDocument+metadataUpdated) ⇒ [Timestamp](#Timestamp) \| undefined + * [.setMetadataUpdated(timestamp)](#IotaDocument+setMetadataUpdated) + * [.metadataDeactivated()](#IotaDocument+metadataDeactivated) ⇒ boolean \| undefined + * [.setMetadataDeactivated(deactivated)](#IotaDocument+setMetadataDeactivated) + * [.metadataStateControllerAddress()](#IotaDocument+metadataStateControllerAddress) ⇒ string \| undefined + * [.metadataGovernorAddress()](#IotaDocument+metadataGovernorAddress) ⇒ string \| undefined + * [.setMetadataPropertyUnchecked(key, value)](#IotaDocument+setMetadataPropertyUnchecked) + * [.revokeCredentials(serviceQuery, indices)](#IotaDocument+revokeCredentials) + * [.unrevokeCredentials(serviceQuery, indices)](#IotaDocument+unrevokeCredentials) + * [.clone()](#IotaDocument+clone) ⇒ [IotaDocument](#IotaDocument) + * [._shallowCloneInternal()](#IotaDocument+_shallowCloneInternal) ⇒ [IotaDocument](#IotaDocument) + * [._strongCountInternal()](#IotaDocument+_strongCountInternal) ⇒ number + * [.toJSON()](#IotaDocument+toJSON) ⇒ any + * [.toCoreDocument()](#IotaDocument+toCoreDocument) ⇒ [CoreDocument](#CoreDocument) + * [.generateMethod(storage, keyType, alg, fragment, scope)](#IotaDocument+generateMethod) ⇒ Promise.<string> + * [.purgeMethod(storage, id)](#IotaDocument+purgeMethod) ⇒ Promise.<void> + * ~~[.createJwt(storage, fragment, payload, options)](#IotaDocument+createJwt) ⇒ [Promise.<Jws>](#Jws)~~ + * [.createJws(storage, fragment, payload, options)](#IotaDocument+createJws) ⇒ [Promise.<Jws>](#Jws) + * [.createCredentialJwt(storage, fragment, credential, options, custom_claims)](#IotaDocument+createCredentialJwt) ⇒ [Promise.<Jwt>](#Jwt) + * [.createPresentationJwt(storage, fragment, presentation, signature_options, presentation_options)](#IotaDocument+createPresentationJwt) ⇒ [Promise.<Jwt>](#Jwt) + * _static_ + * [.newWithId(id)](#IotaDocument.newWithId) ⇒ [IotaDocument](#IotaDocument) + * [.unpackFromOutput(did, aliasOutput, allowEmpty)](#IotaDocument.unpackFromOutput) ⇒ [IotaDocument](#IotaDocument) + * [.unpackFromBlock(network, block)](#IotaDocument.unpackFromBlock) ⇒ [Array.<IotaDocument>](#IotaDocument) + * [.fromJSON(json)](#IotaDocument.fromJSON) ⇒ [IotaDocument](#IotaDocument) + + + +### new IotaDocument(network) +Constructs an empty IOTA DID Document with a [placeholder](#IotaDID.placeholder) identifier +for the given `network`. + + +| Param | Type | +| --- | --- | +| network | string | + + + +### iotaDocument.id() ⇒ [IotaDID](#IotaDID) +Returns a copy of the DID Document `id`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.controller() ⇒ [Array.<IotaDID>](#IotaDID) +Returns a copy of the list of document controllers. + +NOTE: controllers are determined by the `state_controller` unlock condition of the output +during resolution and are omitted when publishing. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.alsoKnownAs() ⇒ Array.<string> +Returns a copy of the document's `alsoKnownAs` set. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.setAlsoKnownAs(urls) +Sets the `alsoKnownAs` property in the DID document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| urls | string \| Array.<string> \| null | + + + +### iotaDocument.properties() ⇒ Map.<string, any> +Returns a copy of the custom DID Document properties. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.setPropertyUnchecked(key, value) +Sets a custom property in the DID Document. +If the value is set to `null`, the custom property will be removed. + +### WARNING + +This method can overwrite existing properties like `id` and result in an invalid document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| key | string | +| value | any | + + + +### iotaDocument.service() ⇒ [Array.<Service>](#Service) +Return a set of all [Service](#Service) in the document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.insertService(service) +Add a new [Service](#Service) to the document. + +Returns `true` if the service was added. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| service | [Service](#Service) | + + + +### iotaDocument.removeService(did) ⇒ [Service](#Service) \| undefined +Remove a [Service](#Service) identified by the given [DIDUrl](#DIDUrl) from the document. + +Returns `true` if a service was removed. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| did | [DIDUrl](#DIDUrl) | + + + +### iotaDocument.resolveService(query) ⇒ [Service](#Service) \| undefined +Returns the first [Service](#Service) with an `id` property matching the provided `query`, +if present. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| query | [DIDUrl](#DIDUrl) \| string | + + + +### iotaDocument.methods(scope) ⇒ [Array.<VerificationMethod>](#VerificationMethod) +Returns a list of all [VerificationMethod](#VerificationMethod) in the DID Document, +whose verification relationship matches `scope`. + +If `scope` is not set, a list over the **embedded** methods is returned. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| scope | [MethodScope](#MethodScope) \| undefined | + + + +### iotaDocument.insertMethod(method, scope) +Adds a new `method` to the document in the given `scope`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| method | [VerificationMethod](#VerificationMethod) | +| scope | [MethodScope](#MethodScope) | + + + +### iotaDocument.removeMethod(did) ⇒ [VerificationMethod](#VerificationMethod) \| undefined +Removes all references to the specified Verification Method. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| did | [DIDUrl](#DIDUrl) | + + + +### iotaDocument.resolveMethod(query, scope) ⇒ [VerificationMethod](#VerificationMethod) \| undefined +Returns a copy of the first verification method with an `id` property +matching the provided `query` and the verification relationship +specified by `scope`, if present. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| query | [DIDUrl](#DIDUrl) \| string | +| scope | [MethodScope](#MethodScope) \| undefined | + + + +### iotaDocument.attachMethodRelationship(didUrl, relationship) ⇒ boolean +Attaches the relationship to the given method, if the method exists. + +Note: The method needs to be in the set of verification methods, +so it cannot be an embedded one. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| didUrl | [DIDUrl](#DIDUrl) | +| relationship | number | + + + +### iotaDocument.detachMethodRelationship(didUrl, relationship) ⇒ boolean +Detaches the given relationship from the given method, if the method exists. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| didUrl | [DIDUrl](#DIDUrl) | +| relationship | number | + + + +### iotaDocument.verifyJws(jws, options, signatureVerifier, detachedPayload) ⇒ [DecodedJws](#DecodedJws) +Decodes and verifies the provided JWS according to the passed `options` and `signatureVerifier`. + If no `signatureVerifier` argument is provided a default verifier will be used that is (only) capable of +verifying EdDSA signatures. + +Regardless of which options are passed the following conditions must be met in order for a verification attempt to +take place. +- The JWS must be encoded according to the JWS compact serialization. +- The `kid` value in the protected header must be an identifier of a verification method in this DID document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| jws | [Jws](#Jws) | +| options | [JwsVerificationOptions](#JwsVerificationOptions) | +| signatureVerifier | IJwsVerifier | +| detachedPayload | string \| undefined | + + + +### iotaDocument.pack() ⇒ Uint8Array +Serializes the document for inclusion in an Alias Output's state metadata +with the default [StateMetadataEncoding](#StateMetadataEncoding). + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.packWithEncoding(encoding) ⇒ Uint8Array +Serializes the document for inclusion in an Alias Output's state metadata. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| encoding | number | + + + +### iotaDocument.metadata() ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) +Returns a copy of the metadata associated with this document. + +NOTE: Copies all the metadata. See also `metadataCreated`, `metadataUpdated`, +`metadataPreviousMessageId`, `metadataProof` if only a subset of the metadata required. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.metadataCreated() ⇒ [Timestamp](#Timestamp) \| undefined +Returns a copy of the timestamp of when the DID document was created. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.setMetadataCreated(timestamp) +Sets the timestamp of when the DID document was created. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| timestamp | [Timestamp](#Timestamp) \| undefined | + + + +### iotaDocument.metadataUpdated() ⇒ [Timestamp](#Timestamp) \| undefined +Returns a copy of the timestamp of the last DID document update. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.setMetadataUpdated(timestamp) +Sets the timestamp of the last DID document update. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| timestamp | [Timestamp](#Timestamp) \| undefined | + + + +### iotaDocument.metadataDeactivated() ⇒ boolean \| undefined +Returns a copy of the deactivated status of the DID document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.setMetadataDeactivated(deactivated) +Sets the deactivated status of the DID document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| deactivated | boolean \| undefined | + + + +### iotaDocument.metadataStateControllerAddress() ⇒ string \| undefined +Returns a copy of the Bech32-encoded state controller address, if present. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.metadataGovernorAddress() ⇒ string \| undefined +Returns a copy of the Bech32-encoded governor address, if present. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.setMetadataPropertyUnchecked(key, value) +Sets a custom property in the document metadata. +If the value is set to `null`, the custom property will be removed. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| key | string | +| value | any | + + + +### iotaDocument.revokeCredentials(serviceQuery, indices) +If the document has a [RevocationBitmap](#RevocationBitmap) service identified by `serviceQuery`, +revoke all specified `indices`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| serviceQuery | [DIDUrl](#DIDUrl) \| string | +| indices | number \| Array.<number> | + + + +### iotaDocument.unrevokeCredentials(serviceQuery, indices) +If the document has a [RevocationBitmap](#RevocationBitmap) service identified by `serviceQuery`, +unrevoke all specified `indices`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| serviceQuery | [DIDUrl](#DIDUrl) \| string | +| indices | number \| Array.<number> | + + + +### iotaDocument.clone() ⇒ [IotaDocument](#IotaDocument) +Returns a deep clone of the [IotaDocument](#IotaDocument). + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.\_shallowCloneInternal() ⇒ [IotaDocument](#IotaDocument) +### Warning +This is for internal use only. Do not rely on or call this method. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.\_strongCountInternal() ⇒ number +### Warning +This is for internal use only. Do not rely on or call this method. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.toJSON() ⇒ any +Serializes to a plain JS representation. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.toCoreDocument() ⇒ [CoreDocument](#CoreDocument) +Transforms the [IotaDocument](#IotaDocument) to its [CoreDocument](#CoreDocument) representation. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + +### iotaDocument.generateMethod(storage, keyType, alg, fragment, scope) ⇒ Promise.<string> +Generate new key material in the given `storage` and insert a new verification method with the corresponding +public key material into the DID document. + +- If no fragment is given the `kid` of the generated JWK is used, if it is set, otherwise an error is returned. +- The `keyType` must be compatible with the given `storage`. `Storage`s are expected to export key type constants +for that use case. + +The fragment of the generated method is returned. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| keyType | string | +| alg | JwsAlgorithm | +| fragment | string \| undefined | +| scope | [MethodScope](#MethodScope) | + + + +### iotaDocument.purgeMethod(storage, id) ⇒ Promise.<void> +Remove the method identified by the given fragment from the document and delete the corresponding key material in +the given `storage`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| id | [DIDUrl](#DIDUrl) | + + + +### ~~iotaDocument.createJwt(storage, fragment, payload, options) ⇒ [Promise.<Jws>](#Jws)~~ +***Deprecated*** + +Sign the `payload` according to `options` with the storage backed private key corresponding to the public key +material in the verification method identified by the given `fragment. + +Upon success a string representing a JWS encoded according to the Compact JWS Serialization format is returned. +See [RFC7515 section 3.1](https://www.rfc-editor.org/rfc/rfc7515#section-3.1). + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| fragment | string | +| payload | string | +| options | [JwsSignatureOptions](#JwsSignatureOptions) | + + + +### iotaDocument.createJws(storage, fragment, payload, options) ⇒ [Promise.<Jws>](#Jws) +Sign the `payload` according to `options` with the storage backed private key corresponding to the public key +material in the verification method identified by the given `fragment. + +Upon success a string representing a JWS encoded according to the Compact JWS Serialization format is returned. +See [RFC7515 section 3.1](https://www.rfc-editor.org/rfc/rfc7515#section-3.1). + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| fragment | string | +| payload | string | +| options | [JwsSignatureOptions](#JwsSignatureOptions) | + + + +### iotaDocument.createCredentialJwt(storage, fragment, credential, options, custom_claims) ⇒ [Promise.<Jwt>](#Jwt) +Produces a JWS where the payload is produced from the given `credential` +in accordance with [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token). + +Unless the `kid` is explicitly set in the options, the `kid` in the protected header is the `id` +of the method identified by `fragment` and the JWS signature will be produced by the corresponding +private key backed by the `storage` in accordance with the passed `options`. + +The `custom_claims` can be used to set additional claims on the resulting JWT. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| fragment | string | +| credential | [Credential](#Credential) | +| options | [JwsSignatureOptions](#JwsSignatureOptions) | +| custom_claims | Record.<string, any> \| undefined | + + + +### iotaDocument.createPresentationJwt(storage, fragment, presentation, signature_options, presentation_options) ⇒ [Promise.<Jwt>](#Jwt) +Produces a JWT where the payload is produced from the given presentation. +in accordance with [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token). + +Unless the `kid` is explicitly set in the options, the `kid` in the protected header is the `id` +of the method identified by `fragment` and the JWS signature will be produced by the corresponding +private key backed by the `storage` in accordance with the passed `options`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| storage | [Storage](#Storage) | +| fragment | string | +| presentation | [Presentation](#Presentation) | +| signature_options | [JwsSignatureOptions](#JwsSignatureOptions) | +| presentation_options | [JwtPresentationOptions](#JwtPresentationOptions) | + + + +### IotaDocument.newWithId(id) ⇒ [IotaDocument](#IotaDocument) +Constructs an empty DID Document with the given identifier. + +**Kind**: static method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| id | [IotaDID](#IotaDID) | + + + +### IotaDocument.unpackFromOutput(did, aliasOutput, allowEmpty) ⇒ [IotaDocument](#IotaDocument) +Deserializes the document from an Alias Output. + +If `allowEmpty` is true, this will return an empty DID document marked as `deactivated` +if `stateMetadata` is empty. + +The `tokenSupply` must be equal to the token supply of the network the DID is associated with. + +NOTE: `did` is required since it is omitted from the serialized DID Document and +cannot be inferred from the state metadata. It also indicates the network, which is not +encoded in the `AliasId` alone. + +**Kind**: static method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| did | [IotaDID](#IotaDID) | +| aliasOutput | AliasOutputBuilderParams | +| allowEmpty | boolean | + + + +### IotaDocument.unpackFromBlock(network, block) ⇒ [Array.<IotaDocument>](#IotaDocument) +Returns all DID documents of the Alias Outputs contained in the block's transaction payload +outputs, if any. + +Errors if any Alias Output does not contain a valid or empty DID Document. + +**Kind**: static method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| network | string | +| block | Block | + + + +### IotaDocument.fromJSON(json) ⇒ [IotaDocument](#IotaDocument) +Deserializes an instance from a plain JS representation. + +**Kind**: static method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --- | --- | +| json | any | + + + +## IotaDocumentMetadata +Additional attributes related to an IOTA DID Document. + +**Kind**: global class + +* [IotaDocumentMetadata](#IotaDocumentMetadata) + * _instance_ + * [.created()](#IotaDocumentMetadata+created) ⇒ [Timestamp](#Timestamp) \| undefined + * [.updated()](#IotaDocumentMetadata+updated) ⇒ [Timestamp](#Timestamp) \| undefined + * [.deactivated()](#IotaDocumentMetadata+deactivated) ⇒ boolean \| undefined + * [.stateControllerAddress()](#IotaDocumentMetadata+stateControllerAddress) ⇒ string \| undefined + * [.governorAddress()](#IotaDocumentMetadata+governorAddress) ⇒ string \| undefined + * [.properties()](#IotaDocumentMetadata+properties) ⇒ Map.<string, any> + * [.toJSON()](#IotaDocumentMetadata+toJSON) ⇒ any + * [.clone()](#IotaDocumentMetadata+clone) ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) + * _static_ + * [.fromJSON(json)](#IotaDocumentMetadata.fromJSON) ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) + + + +### iotaDocumentMetadata.created() ⇒ [Timestamp](#Timestamp) \| undefined +Returns a copy of the timestamp of when the DID document was created. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + +### iotaDocumentMetadata.updated() ⇒ [Timestamp](#Timestamp) \| undefined +Returns a copy of the timestamp of the last DID document update. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + +### iotaDocumentMetadata.deactivated() ⇒ boolean \| undefined +Returns a copy of the deactivated status of the DID document. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + +### iotaDocumentMetadata.stateControllerAddress() ⇒ string \| undefined +Returns a copy of the Bech32-encoded state controller address, if present. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + +### iotaDocumentMetadata.governorAddress() ⇒ string \| undefined +Returns a copy of the Bech32-encoded governor address, if present. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + +### iotaDocumentMetadata.properties() ⇒ Map.<string, any> +Returns a copy of the custom metadata properties. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + +### iotaDocumentMetadata.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + +### iotaDocumentMetadata.clone() ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) +Deep clones the object. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + +### IotaDocumentMetadata.fromJSON(json) ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) +Deserializes an instance from a JSON object. + +**Kind**: static method of [IotaDocumentMetadata](#IotaDocumentMetadata) + +| Param | Type | +| --- | --- | +| json | any | + + + +## IotaIdentityClientExt +An extension interface that provides helper functions for publication +and resolution of DID documents in Alias Outputs. + +**Kind**: global class + +* [IotaIdentityClientExt](#IotaIdentityClientExt) + * [.newDidOutput(client, address, document, rentStructure)](#IotaIdentityClientExt.newDidOutput) ⇒ Promise.<AliasOutputBuilderParams> + * [.updateDidOutput(client, document)](#IotaIdentityClientExt.updateDidOutput) ⇒ Promise.<AliasOutputBuilderParams> + * [.deactivateDidOutput(client, did)](#IotaIdentityClientExt.deactivateDidOutput) ⇒ Promise.<AliasOutputBuilderParams> + * [.resolveDid(client, did)](#IotaIdentityClientExt.resolveDid) ⇒ [Promise.<IotaDocument>](#IotaDocument) + * [.resolveDidOutput(client, did)](#IotaIdentityClientExt.resolveDidOutput) ⇒ Promise.<AliasOutputBuilderParams> + + + +### IotaIdentityClientExt.newDidOutput(client, address, document, rentStructure) ⇒ Promise.<AliasOutputBuilderParams> +Create a DID with a new Alias Output containing the given `document`. + +The `address` will be set as the state controller and governor unlock conditions. +The minimum required token deposit amount will be set according to the given +`rent_structure`, which will be fetched from the node if not provided. +The returned Alias Output can be further customised before publication, if desired. + +NOTE: this does *not* publish the Alias Output. + +**Kind**: static method of [IotaIdentityClientExt](#IotaIdentityClientExt) + +| Param | Type | +| --- | --- | +| client | IIotaIdentityClient | +| address | Address | +| document | [IotaDocument](#IotaDocument) | +| rentStructure | IRent \| undefined | + + + +### IotaIdentityClientExt.updateDidOutput(client, document) ⇒ Promise.<AliasOutputBuilderParams> +Fetches the associated Alias Output and updates it with `document` in its state metadata. +The storage deposit on the output is left unchanged. If the size of the document increased, +the amount should be increased manually. + +NOTE: this does *not* publish the updated Alias Output. + +**Kind**: static method of [IotaIdentityClientExt](#IotaIdentityClientExt) + +| Param | Type | +| --- | --- | +| client | IIotaIdentityClient | +| document | [IotaDocument](#IotaDocument) | + + + +### IotaIdentityClientExt.deactivateDidOutput(client, did) ⇒ Promise.<AliasOutputBuilderParams> +Removes the DID document from the state metadata of its Alias Output, +effectively deactivating it. The storage deposit on the output is left unchanged, +and should be reallocated manually. + +Deactivating does not destroy the output. Hence, it can be re-activated by publishing +an update containing a DID document. + +NOTE: this does *not* publish the updated Alias Output. + +**Kind**: static method of [IotaIdentityClientExt](#IotaIdentityClientExt) + +| Param | Type | +| --- | --- | +| client | IIotaIdentityClient | +| did | [IotaDID](#IotaDID) | + + + +### IotaIdentityClientExt.resolveDid(client, did) ⇒ [Promise.<IotaDocument>](#IotaDocument) +Resolve a [IotaDocument](#IotaDocument). Returns an empty, deactivated document if the state metadata +of the Alias Output is empty. + +**Kind**: static method of [IotaIdentityClientExt](#IotaIdentityClientExt) + +| Param | Type | +| --- | --- | +| client | IIotaIdentityClient | +| did | [IotaDID](#IotaDID) | + + + +### IotaIdentityClientExt.resolveDidOutput(client, did) ⇒ Promise.<AliasOutputBuilderParams> +Fetches the `IAliasOutput` associated with the given DID. + +**Kind**: static method of [IotaIdentityClientExt](#IotaIdentityClientExt) + +| Param | Type | +| --- | --- | +| client | IIotaIdentityClient | +| did | [IotaDID](#IotaDID) | + + + +## Jwk +**Kind**: global class + +* [Jwk](#Jwk) + * [new Jwk(jwk)](#new_Jwk_new) + * _instance_ + * [.kty()](#Jwk+kty) ⇒ JwkType + * [.use()](#Jwk+use) ⇒ JwkUse \| undefined + * [.keyOps()](#Jwk+keyOps) ⇒ Array.<JwkOperation> + * [.alg()](#Jwk+alg) ⇒ JwsAlgorithm \| undefined + * [.kid()](#Jwk+kid) ⇒ string \| undefined + * [.x5u()](#Jwk+x5u) ⇒ string \| undefined + * [.x5c()](#Jwk+x5c) ⇒ Array.<string> + * [.x5t()](#Jwk+x5t) ⇒ string \| undefined + * [.x5t256()](#Jwk+x5t256) ⇒ string \| undefined + * [.paramsEc()](#Jwk+paramsEc) ⇒ JwkParamsEc \| undefined + * [.paramsOkp()](#Jwk+paramsOkp) ⇒ JwkParamsOkp \| undefined + * [.paramsOct()](#Jwk+paramsOct) ⇒ JwkParamsOct \| undefined + * [.paramsRsa()](#Jwk+paramsRsa) ⇒ JwkParamsRsa \| undefined + * [.toPublic()](#Jwk+toPublic) ⇒ [Jwk](#Jwk) \| undefined + * [.isPublic()](#Jwk+isPublic) ⇒ boolean + * [.isPrivate()](#Jwk+isPrivate) ⇒ boolean + * [.toJSON()](#Jwk+toJSON) ⇒ any + * [.clone()](#Jwk+clone) ⇒ [Jwk](#Jwk) + * _static_ + * [.fromJSON(json)](#Jwk.fromJSON) ⇒ [Jwk](#Jwk) + + + +### new Jwk(jwk) + +| Param | Type | +| --- | --- | +| jwk | IJwkParams | + + + +### jwk.kty() ⇒ JwkType +Returns the value for the key type parameter (kty). + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.use() ⇒ JwkUse \| undefined +Returns the value for the use property (use). + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.keyOps() ⇒ Array.<JwkOperation> +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.alg() ⇒ JwsAlgorithm \| undefined +Returns the value for the algorithm property (alg). + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.kid() ⇒ string \| undefined +Returns the value of the key ID property (kid). + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.x5u() ⇒ string \| undefined +Returns the value of the X.509 URL property (x5u). + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.x5c() ⇒ Array.<string> +Returns the value of the X.509 certificate chain property (x5c). + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.x5t() ⇒ string \| undefined +Returns the value of the X.509 certificate SHA-1 thumbprint property (x5t). + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.x5t256() ⇒ string \| undefined +Returns the value of the X.509 certificate SHA-256 thumbprint property (x5t#S256). + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.paramsEc() ⇒ JwkParamsEc \| undefined +If this JWK is of kty EC, returns those parameters. + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.paramsOkp() ⇒ JwkParamsOkp \| undefined +If this JWK is of kty OKP, returns those parameters. + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.paramsOct() ⇒ JwkParamsOct \| undefined +If this JWK is of kty OCT, returns those parameters. + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.paramsRsa() ⇒ JwkParamsRsa \| undefined +If this JWK is of kty RSA, returns those parameters. + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.toPublic() ⇒ [Jwk](#Jwk) \| undefined +Returns a clone of the [Jwk](#Jwk) with _all_ private key components unset. +Nothing is returned when `kty = oct` as this key type is not considered public by this library. + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.isPublic() ⇒ boolean +Returns `true` if _all_ private key components of the key are unset, `false` otherwise. + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.isPrivate() ⇒ boolean +Returns `true` if _all_ private key components of the key are set, `false` otherwise. + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [Jwk](#Jwk) + + +### jwk.clone() ⇒ [Jwk](#Jwk) +Deep clones the object. + +**Kind**: instance method of [Jwk](#Jwk) + + +### Jwk.fromJSON(json) ⇒ [Jwk](#Jwk) +Deserializes an instance from a JSON object. + +**Kind**: static method of [Jwk](#Jwk) + +| Param | Type | +| --- | --- | +| json | any | + + + +## JwkGenOutput +The result of a key generation in `JwkStorage`. + +**Kind**: global class + +* [JwkGenOutput](#JwkGenOutput) + * [new JwkGenOutput(key_id, jwk)](#new_JwkGenOutput_new) + * _instance_ + * [.jwk()](#JwkGenOutput+jwk) ⇒ [Jwk](#Jwk) + * [.keyId()](#JwkGenOutput+keyId) ⇒ string + * [.toJSON()](#JwkGenOutput+toJSON) ⇒ any + * [.clone()](#JwkGenOutput+clone) ⇒ [JwkGenOutput](#JwkGenOutput) + * _static_ + * [.fromJSON(json)](#JwkGenOutput.fromJSON) ⇒ [JwkGenOutput](#JwkGenOutput) + + + +### new JwkGenOutput(key_id, jwk) + +| Param | Type | +| --- | --- | +| key_id | string | +| jwk | [Jwk](#Jwk) | + + + +### jwkGenOutput.jwk() ⇒ [Jwk](#Jwk) +Returns the generated public [Jwk](#Jwk). + +**Kind**: instance method of [JwkGenOutput](#JwkGenOutput) + + +### jwkGenOutput.keyId() ⇒ string +Returns the key id of the generated [Jwk](#Jwk). + +**Kind**: instance method of [JwkGenOutput](#JwkGenOutput) + + +### jwkGenOutput.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [JwkGenOutput](#JwkGenOutput) + + +### jwkGenOutput.clone() ⇒ [JwkGenOutput](#JwkGenOutput) +Deep clones the object. + +**Kind**: instance method of [JwkGenOutput](#JwkGenOutput) + + +### JwkGenOutput.fromJSON(json) ⇒ [JwkGenOutput](#JwkGenOutput) +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwkGenOutput](#JwkGenOutput) + +| Param | Type | +| --- | --- | +| json | any | + + + +## Jws +A wrapper around a JSON Web Signature (JWS). + +**Kind**: global class + +* [Jws](#Jws) + * [new Jws(jws_string)](#new_Jws_new) + * [.toString()](#Jws+toString) ⇒ string + + + +### new Jws(jws_string) +Creates a new [Jws](#Jws) from the given string. + + +| Param | Type | +| --- | --- | +| jws_string | string | + + + +### jws.toString() ⇒ string +Returns a clone of the JWS string. + +**Kind**: instance method of [Jws](#Jws) + + +## JwsHeader +**Kind**: global class + +* [JwsHeader](#JwsHeader) + * [new JwsHeader()](#new_JwsHeader_new) + * _instance_ + * [.alg()](#JwsHeader+alg) ⇒ JwsAlgorithm \| undefined + * [.setAlg(value)](#JwsHeader+setAlg) + * [.b64()](#JwsHeader+b64) ⇒ boolean \| undefined + * [.setB64(value)](#JwsHeader+setB64) + * [.custom()](#JwsHeader+custom) ⇒ Record.<string, any> \| undefined + * [.has(claim)](#JwsHeader+has) ⇒ boolean + * [.isDisjoint(other)](#JwsHeader+isDisjoint) ⇒ boolean + * [.jku()](#JwsHeader+jku) ⇒ string \| undefined + * [.setJku(value)](#JwsHeader+setJku) + * [.jwk()](#JwsHeader+jwk) ⇒ [Jwk](#Jwk) \| undefined + * [.setJwk(value)](#JwsHeader+setJwk) + * [.kid()](#JwsHeader+kid) ⇒ string \| undefined + * [.setKid(value)](#JwsHeader+setKid) + * [.x5u()](#JwsHeader+x5u) ⇒ string \| undefined + * [.setX5u(value)](#JwsHeader+setX5u) + * [.x5c()](#JwsHeader+x5c) ⇒ Array.<string> + * [.setX5c(value)](#JwsHeader+setX5c) + * [.x5t()](#JwsHeader+x5t) ⇒ string \| undefined + * [.setX5t(value)](#JwsHeader+setX5t) + * [.x5tS256()](#JwsHeader+x5tS256) ⇒ string \| undefined + * [.setX5tS256(value)](#JwsHeader+setX5tS256) + * [.typ()](#JwsHeader+typ) ⇒ string \| undefined + * [.setTyp(value)](#JwsHeader+setTyp) + * [.cty()](#JwsHeader+cty) ⇒ string \| undefined + * [.setCty(value)](#JwsHeader+setCty) + * [.crit()](#JwsHeader+crit) ⇒ Array.<string> + * [.setCrit(value)](#JwsHeader+setCrit) + * [.url()](#JwsHeader+url) ⇒ string \| undefined + * [.setUrl(value)](#JwsHeader+setUrl) + * [.nonce()](#JwsHeader+nonce) ⇒ string \| undefined + * [.setNonce(value)](#JwsHeader+setNonce) + * [.toJSON()](#JwsHeader+toJSON) ⇒ any + * [.clone()](#JwsHeader+clone) ⇒ [JwsHeader](#JwsHeader) + * _static_ + * [.fromJSON(json)](#JwsHeader.fromJSON) ⇒ [JwsHeader](#JwsHeader) + + + +### new JwsHeader() +Create a new empty [JwsHeader](#JwsHeader). + + + +### jwsHeader.alg() ⇒ JwsAlgorithm \| undefined +Returns the value for the algorithm claim (alg). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setAlg(value) +Sets a value for the algorithm claim (alg). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | JwsAlgorithm | + + + +### jwsHeader.b64() ⇒ boolean \| undefined +Returns the value of the base64url-encode payload claim (b64). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setB64(value) +Sets a value for the base64url-encode payload claim (b64). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | boolean | + + + +### jwsHeader.custom() ⇒ Record.<string, any> \| undefined +Additional header parameters. + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.has(claim) ⇒ boolean +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| claim | string | + + + +### jwsHeader.isDisjoint(other) ⇒ boolean +Returns `true` if none of the fields are set in both `self` and `other`. + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| other | [JwsHeader](#JwsHeader) | + + + +### jwsHeader.jku() ⇒ string \| undefined +Returns the value of the JWK Set URL claim (jku). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setJku(value) +Sets a value for the JWK Set URL claim (jku). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsHeader.jwk() ⇒ [Jwk](#Jwk) \| undefined +Returns the value of the JWK claim (jwk). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setJwk(value) +Sets a value for the JWK claim (jwk). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | [Jwk](#Jwk) | + + + +### jwsHeader.kid() ⇒ string \| undefined +Returns the value of the key ID claim (kid). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setKid(value) +Sets a value for the key ID claim (kid). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsHeader.x5u() ⇒ string \| undefined +Returns the value of the X.509 URL claim (x5u). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setX5u(value) +Sets a value for the X.509 URL claim (x5u). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsHeader.x5c() ⇒ Array.<string> +Returns the value of the X.509 certificate chain claim (x5c). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setX5c(value) +Sets values for the X.509 certificate chain claim (x5c). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | Array.<string> | + + + +### jwsHeader.x5t() ⇒ string \| undefined +Returns the value of the X.509 certificate SHA-1 thumbprint claim (x5t). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setX5t(value) +Sets a value for the X.509 certificate SHA-1 thumbprint claim (x5t). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsHeader.x5tS256() ⇒ string \| undefined +Returns the value of the X.509 certificate SHA-256 thumbprint claim +(x5t#S256). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setX5tS256(value) +Sets a value for the X.509 certificate SHA-256 thumbprint claim +(x5t#S256). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsHeader.typ() ⇒ string \| undefined +Returns the value of the token type claim (typ). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setTyp(value) +Sets a value for the token type claim (typ). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsHeader.cty() ⇒ string \| undefined +Returns the value of the content type claim (cty). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setCty(value) +Sets a value for the content type claim (cty). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsHeader.crit() ⇒ Array.<string> +Returns the value of the critical claim (crit). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setCrit(value) +Sets values for the critical claim (crit). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | Array.<string> | + + + +### jwsHeader.url() ⇒ string \| undefined +Returns the value of the url claim (url). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setUrl(value) +Sets a value for the url claim (url). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsHeader.nonce() ⇒ string \| undefined +Returns the value of the nonce claim (nonce). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.setNonce(value) +Sets a value for the nonce claim (nonce). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsHeader.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### jwsHeader.clone() ⇒ [JwsHeader](#JwsHeader) +Deep clones the object. + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + +### JwsHeader.fromJSON(json) ⇒ [JwsHeader](#JwsHeader) +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwsHeader](#JwsHeader) + +| Param | Type | +| --- | --- | +| json | any | + + + +## JwsSignatureOptions +**Kind**: global class + +* [JwsSignatureOptions](#JwsSignatureOptions) + * [new JwsSignatureOptions(options)](#new_JwsSignatureOptions_new) + * _instance_ + * [.setAttachJwk(value)](#JwsSignatureOptions+setAttachJwk) + * [.setB64(value)](#JwsSignatureOptions+setB64) + * [.setTyp(value)](#JwsSignatureOptions+setTyp) + * [.setCty(value)](#JwsSignatureOptions+setCty) + * [.serUrl(value)](#JwsSignatureOptions+serUrl) + * [.setNonce(value)](#JwsSignatureOptions+setNonce) + * [.setKid(value)](#JwsSignatureOptions+setKid) + * [.setDetachedPayload(value)](#JwsSignatureOptions+setDetachedPayload) + * [.setCustomHeaderParameters(value)](#JwsSignatureOptions+setCustomHeaderParameters) + * [.toJSON()](#JwsSignatureOptions+toJSON) ⇒ any + * [.clone()](#JwsSignatureOptions+clone) ⇒ [JwsSignatureOptions](#JwsSignatureOptions) + * _static_ + * [.fromJSON(json)](#JwsSignatureOptions.fromJSON) ⇒ [JwsSignatureOptions](#JwsSignatureOptions) + + + +### new JwsSignatureOptions(options) + +| Param | Type | +| --- | --- | +| options | IJwsSignatureOptions \| undefined | + + + +### jwsSignatureOptions.setAttachJwk(value) +Replace the value of the `attachJwk` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| --- | --- | +| value | boolean | + + + +### jwsSignatureOptions.setB64(value) +Replace the value of the `b64` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| --- | --- | +| value | boolean | + + + +### jwsSignatureOptions.setTyp(value) +Replace the value of the `typ` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsSignatureOptions.setCty(value) +Replace the value of the `cty` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsSignatureOptions.serUrl(value) +Replace the value of the `url` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsSignatureOptions.setNonce(value) +Replace the value of the `nonce` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsSignatureOptions.setKid(value) +Replace the value of the `kid` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsSignatureOptions.setDetachedPayload(value) +Replace the value of the `detached_payload` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| --- | --- | +| value | boolean | + + + +### jwsSignatureOptions.setCustomHeaderParameters(value) +Add additional header parameters. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| --- | --- | +| value | Record.<string, any> | + + + +### jwsSignatureOptions.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + + +### jwsSignatureOptions.clone() ⇒ [JwsSignatureOptions](#JwsSignatureOptions) +Deep clones the object. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + + +### JwsSignatureOptions.fromJSON(json) ⇒ [JwsSignatureOptions](#JwsSignatureOptions) +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| --- | --- | +| json | any | + + + +## JwsVerificationOptions +**Kind**: global class + +* [JwsVerificationOptions](#JwsVerificationOptions) + * [new JwsVerificationOptions(options)](#new_JwsVerificationOptions_new) + * _instance_ + * [.setNonce(value)](#JwsVerificationOptions+setNonce) + * [.setMethodScope(value)](#JwsVerificationOptions+setMethodScope) + * [.setMethodId(value)](#JwsVerificationOptions+setMethodId) + * [.toJSON()](#JwsVerificationOptions+toJSON) ⇒ any + * [.clone()](#JwsVerificationOptions+clone) ⇒ [JwsVerificationOptions](#JwsVerificationOptions) + * _static_ + * [.fromJSON(json)](#JwsVerificationOptions.fromJSON) ⇒ [JwsVerificationOptions](#JwsVerificationOptions) + + + +### new JwsVerificationOptions(options) +Creates a new [JwsVerificationOptions](#JwsVerificationOptions) from the given fields. + + +| Param | Type | +| --- | --- | +| options | IJwsVerificationOptions \| undefined | + + + +### jwsVerificationOptions.setNonce(value) +Set the expected value for the `nonce` parameter of the protected header. + +**Kind**: instance method of [JwsVerificationOptions](#JwsVerificationOptions) + +| Param | Type | +| --- | --- | +| value | string | + + + +### jwsVerificationOptions.setMethodScope(value) +Set the scope of the verification methods that may be used to verify the given JWS. + +**Kind**: instance method of [JwsVerificationOptions](#JwsVerificationOptions) + +| Param | Type | +| --- | --- | +| value | [MethodScope](#MethodScope) | + + + +### jwsVerificationOptions.setMethodId(value) +Set the DID URl of the method, whose JWK should be used to verify the JWS. + +**Kind**: instance method of [JwsVerificationOptions](#JwsVerificationOptions) + +| Param | Type | +| --- | --- | +| value | [DIDUrl](#DIDUrl) | + + + +### jwsVerificationOptions.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [JwsVerificationOptions](#JwsVerificationOptions) + + +### jwsVerificationOptions.clone() ⇒ [JwsVerificationOptions](#JwsVerificationOptions) +Deep clones the object. + +**Kind**: instance method of [JwsVerificationOptions](#JwsVerificationOptions) + + +### JwsVerificationOptions.fromJSON(json) ⇒ [JwsVerificationOptions](#JwsVerificationOptions) +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwsVerificationOptions](#JwsVerificationOptions) + +| Param | Type | +| --- | --- | +| json | any | + + + +## Jwt +A wrapper around a JSON Web Token (JWK). + +**Kind**: global class + +* [Jwt](#Jwt) + * [new Jwt(jwt_string)](#new_Jwt_new) + * _instance_ + * [.toString()](#Jwt+toString) ⇒ string + * [.toJSON()](#Jwt+toJSON) ⇒ any + * [.clone()](#Jwt+clone) ⇒ [Jwt](#Jwt) + * _static_ + * [.fromJSON(json)](#Jwt.fromJSON) ⇒ [Jwt](#Jwt) + + + +### new Jwt(jwt_string) +Creates a new [Jwt](#Jwt) from the given string. + + +| Param | Type | +| --- | --- | +| jwt_string | string | + + + +### jwt.toString() ⇒ string +Returns a clone of the JWT string. + +**Kind**: instance method of [Jwt](#Jwt) + + +### jwt.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [Jwt](#Jwt) + + +### jwt.clone() ⇒ [Jwt](#Jwt) +Deep clones the object. + +**Kind**: instance method of [Jwt](#Jwt) + + +### Jwt.fromJSON(json) ⇒ [Jwt](#Jwt) +Deserializes an instance from a JSON object. + +**Kind**: static method of [Jwt](#Jwt) + +| Param | Type | +| --- | --- | +| json | any | + + + +## JwtCredentialValidationOptions +Options to declare validation criteria when validating credentials. + +**Kind**: global class + +* [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + * [new JwtCredentialValidationOptions(options)](#new_JwtCredentialValidationOptions_new) + * _instance_ + * [.toJSON()](#JwtCredentialValidationOptions+toJSON) ⇒ any + * [.clone()](#JwtCredentialValidationOptions+clone) ⇒ [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + * _static_ + * [.fromJSON(json)](#JwtCredentialValidationOptions.fromJSON) ⇒ [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + + + +### new JwtCredentialValidationOptions(options) + +| Param | Type | +| --- | --- | +| options | IJwtCredentialValidationOptions \| undefined | + + + +### jwtCredentialValidationOptions.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + + +### jwtCredentialValidationOptions.clone() ⇒ [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) +Deep clones the object. + +**Kind**: instance method of [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + + +### JwtCredentialValidationOptions.fromJSON(json) ⇒ [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + +| Param | Type | +| --- | --- | +| json | any | + + + +## JwtCredentialValidator +A type for decoding and validating [Credential](#Credential). + +**Kind**: global class + +* [JwtCredentialValidator](#JwtCredentialValidator) + * [new JwtCredentialValidator(signatureVerifier)](#new_JwtCredentialValidator_new) + * _instance_ + * [.validate(credential_jwt, issuer, options, fail_fast)](#JwtCredentialValidator+validate) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) + * [.verifySignature(credential, trustedIssuers, options)](#JwtCredentialValidator+verifySignature) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) + * _static_ + * [.checkExpiresOnOrAfter(credential, timestamp)](#JwtCredentialValidator.checkExpiresOnOrAfter) + * [.checkIssuedOnOrBefore(credential, timestamp)](#JwtCredentialValidator.checkIssuedOnOrBefore) + * [.checkSubjectHolderRelationship(credential, holder, relationship)](#JwtCredentialValidator.checkSubjectHolderRelationship) + * [.checkStatus(credential, trustedIssuers, statusCheck)](#JwtCredentialValidator.checkStatus) + * [.checkStatusWithStatusList2021(credential, status_list, status_check)](#JwtCredentialValidator.checkStatusWithStatusList2021) + * [.extractIssuer(credential)](#JwtCredentialValidator.extractIssuer) ⇒ [CoreDID](#CoreDID) + * [.extractIssuerFromJwt(credential)](#JwtCredentialValidator.extractIssuerFromJwt) ⇒ [CoreDID](#CoreDID) + + + +### new JwtCredentialValidator(signatureVerifier) +Creates a new [JwtCredentialValidator](#JwtCredentialValidator). If a `signatureVerifier` is provided it will be used when +verifying decoded JWS signatures, otherwise the default which is only capable of handling the `EdDSA` +algorithm will be used. + + +| Param | Type | +| --- | --- | +| signatureVerifier | IJwsVerifier | + + + +### jwtCredentialValidator.validate(credential_jwt, issuer, options, fail_fast) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) +Decodes and validates a [Credential](#Credential) issued as a JWS. A [DecodedJwtCredential](#DecodedJwtCredential) is returned upon +success. + +The following properties are validated according to `options`: +- the issuer's signature on the JWS, +- the expiration date, +- the issuance date, +- the semantic structure. + +# Warning +The lack of an error returned from this method is in of itself not enough to conclude that the credential can be +trusted. This section contains more information on additional checks that should be carried out before and after +calling this method. + +## The state of the issuer's DID Document +The caller must ensure that `issuer` represents an up-to-date DID Document. + +## Properties that are not validated + There are many properties defined in [The Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) that are **not** validated, such as: +`proof`, `credentialStatus`, `type`, `credentialSchema`, `refreshService` **and more**. +These should be manually checked after validation, according to your requirements. + +# Errors +An error is returned whenever a validated condition is not satisfied. + +**Kind**: instance method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| --- | --- | +| credential_jwt | [Jwt](#Jwt) | +| issuer | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| options | [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) | +| fail_fast | number | + + + +### jwtCredentialValidator.verifySignature(credential, trustedIssuers, options) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) +Decode and verify the JWS signature of a [Credential](#Credential) issued as a JWT using the DID Document of a trusted +issuer. + +A [DecodedJwtCredential](#DecodedJwtCredential) is returned upon success. + +# Warning +The caller must ensure that the DID Documents of the trusted issuers are up-to-date. + +## Proofs + Only the JWS signature is verified. If the [Credential](#Credential) contains a `proof` property this will not be +verified by this method. + +# Errors +This method immediately returns an error if +the credential issuer' url cannot be parsed to a DID belonging to one of the trusted issuers. Otherwise an attempt +to verify the credential's signature will be made and an error is returned upon failure. + +**Kind**: instance method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| --- | --- | +| credential | [Jwt](#Jwt) | +| trustedIssuers | Array.<(CoreDocument\|IToCoreDocument)> | +| options | [JwsVerificationOptions](#JwsVerificationOptions) | + + + +### JwtCredentialValidator.checkExpiresOnOrAfter(credential, timestamp) +Validate that the credential expires on or after the specified timestamp. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| --- | --- | +| credential | [Credential](#Credential) | +| timestamp | [Timestamp](#Timestamp) | + + + +### JwtCredentialValidator.checkIssuedOnOrBefore(credential, timestamp) +Validate that the credential is issued on or before the specified timestamp. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| --- | --- | +| credential | [Credential](#Credential) | +| timestamp | [Timestamp](#Timestamp) | + + + +### JwtCredentialValidator.checkSubjectHolderRelationship(credential, holder, relationship) +Validate that the relationship between the `holder` and the credential subjects is in accordance with +`relationship`. The `holder` parameter is expected to be the URL of the holder. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| --- | --- | +| credential | [Credential](#Credential) | +| holder | string | +| relationship | number | + + + +### JwtCredentialValidator.checkStatus(credential, trustedIssuers, statusCheck) +Checks whether the credential status has been revoked. + +Only supports `RevocationBitmap2022`. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| --- | --- | +| credential | [Credential](#Credential) | +| trustedIssuers | Array.<(CoreDocument\|IToCoreDocument)> | +| statusCheck | number | + + + +### JwtCredentialValidator.checkStatusWithStatusList2021(credential, status_list, status_check) +Checks wheter the credential status has been revoked using `StatusList2021`. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| --- | --- | +| credential | [Credential](#Credential) | +| status_list | [StatusList2021Credential](#StatusList2021Credential) | +| status_check | number | + + + +### JwtCredentialValidator.extractIssuer(credential) ⇒ [CoreDID](#CoreDID) +Utility for extracting the issuer field of a [Credential](#Credential) as a DID. + +### Errors + +Fails if the issuer field is not a valid DID. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| --- | --- | +| credential | [Credential](#Credential) | + + + +### JwtCredentialValidator.extractIssuerFromJwt(credential) ⇒ [CoreDID](#CoreDID) +Utility for extracting the issuer field of a credential in JWT representation as DID. + +# Errors + +If the JWT decoding fails or the issuer field is not a valid DID. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| --- | --- | +| credential | [Jwt](#Jwt) | + + + +## JwtDomainLinkageValidator +A validator for a Domain Linkage Configuration and Credentials. + +**Kind**: global class + +* [JwtDomainLinkageValidator](#JwtDomainLinkageValidator) + * [new JwtDomainLinkageValidator(signatureVerifier)](#new_JwtDomainLinkageValidator_new) + * [.validateLinkage(issuer, configuration, domain, options)](#JwtDomainLinkageValidator+validateLinkage) + * [.validateCredential(issuer, credentialJwt, domain, options)](#JwtDomainLinkageValidator+validateCredential) + + + +### new JwtDomainLinkageValidator(signatureVerifier) +Creates a new [JwtDomainLinkageValidator](#JwtDomainLinkageValidator). If a `signatureVerifier` is provided it will be used when +verifying decoded JWS signatures, otherwise the default which is only capable of handling the `EdDSA` +algorithm will be used. + + +| Param | Type | +| --- | --- | +| signatureVerifier | IJwsVerifier | + + + +### jwtDomainLinkageValidator.validateLinkage(issuer, configuration, domain, options) +Validates the linkage between a domain and a DID. +[DomainLinkageConfiguration](#DomainLinkageConfiguration) is validated according to [DID Configuration Resource Verification](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource-verification). + +Linkage is valid if no error is thrown. + +# Note: +- Only the [JSON Web Token Proof Format](https://identity.foundation/.well-known/resources/did-configuration/#json-web-token-proof-format) + is supported. +- Only the Credential issued by `issuer` is verified. + +# Errors + + - Semantic structure of `configuration` is invalid. + - `configuration` includes multiple credentials issued by `issuer`. + - Validation of the matched Domain Linkage Credential fails. + +**Kind**: instance method of [JwtDomainLinkageValidator](#JwtDomainLinkageValidator) + +| Param | Type | +| --- | --- | +| issuer | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| configuration | [DomainLinkageConfiguration](#DomainLinkageConfiguration) | +| domain | string | +| options | [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) | + + + +### jwtDomainLinkageValidator.validateCredential(issuer, credentialJwt, domain, options) +Validates a [Domain Linkage Credential](https://identity.foundation/.well-known/resources/did-configuration/#domain-linkage-credential). + +Error will be thrown in case the validation fails. + +**Kind**: instance method of [JwtDomainLinkageValidator](#JwtDomainLinkageValidator) + +| Param | Type | +| --- | --- | +| issuer | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| credentialJwt | [Jwt](#Jwt) | +| domain | string | +| options | [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) | + + + +## JwtPresentationOptions +**Kind**: global class + +* [JwtPresentationOptions](#JwtPresentationOptions) + * [new JwtPresentationOptions(options)](#new_JwtPresentationOptions_new) + * _instance_ + * [.toJSON()](#JwtPresentationOptions+toJSON) ⇒ any + * [.clone()](#JwtPresentationOptions+clone) ⇒ [JwtPresentationOptions](#JwtPresentationOptions) + * _static_ + * [.fromJSON(json)](#JwtPresentationOptions.fromJSON) ⇒ [JwtPresentationOptions](#JwtPresentationOptions) + + + +### new JwtPresentationOptions(options) +Creates a new [JwtPresentationOptions](#JwtPresentationOptions) from the given fields. + +Throws an error if any of the options are invalid. + + +| Param | Type | +| --- | --- | +| options | IJwtPresentationOptions \| undefined | + + + +### jwtPresentationOptions.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [JwtPresentationOptions](#JwtPresentationOptions) + + +### jwtPresentationOptions.clone() ⇒ [JwtPresentationOptions](#JwtPresentationOptions) +Deep clones the object. + +**Kind**: instance method of [JwtPresentationOptions](#JwtPresentationOptions) + + +### JwtPresentationOptions.fromJSON(json) ⇒ [JwtPresentationOptions](#JwtPresentationOptions) +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwtPresentationOptions](#JwtPresentationOptions) + +| Param | Type | +| --- | --- | +| json | any | + + + +## JwtPresentationValidationOptions +Options to declare validation criteria when validating presentation. + +**Kind**: global class + +* [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + * [new JwtPresentationValidationOptions(options)](#new_JwtPresentationValidationOptions_new) + * _instance_ + * [.toJSON()](#JwtPresentationValidationOptions+toJSON) ⇒ any + * [.clone()](#JwtPresentationValidationOptions+clone) ⇒ [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + * _static_ + * [.fromJSON(json)](#JwtPresentationValidationOptions.fromJSON) ⇒ [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + + + +### new JwtPresentationValidationOptions(options) +Creates a new [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) from the given fields. + +Throws an error if any of the options are invalid. + + +| Param | Type | +| --- | --- | +| options | IJwtPresentationValidationOptions \| undefined | + + + +### jwtPresentationValidationOptions.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + + +### jwtPresentationValidationOptions.clone() ⇒ [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) +Deep clones the object. + +**Kind**: instance method of [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + + +### JwtPresentationValidationOptions.fromJSON(json) ⇒ [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + +| Param | Type | +| --- | --- | +| json | any | + + + +## JwtPresentationValidator +**Kind**: global class + +* [JwtPresentationValidator](#JwtPresentationValidator) + * [new JwtPresentationValidator(signatureVerifier)](#new_JwtPresentationValidator_new) + * _instance_ + * [.validate(presentationJwt, holder, validation_options)](#JwtPresentationValidator+validate) ⇒ [DecodedJwtPresentation](#DecodedJwtPresentation) + * _static_ + * [.checkStructure(presentation)](#JwtPresentationValidator.checkStructure) + * [.extractHolder(presentation)](#JwtPresentationValidator.extractHolder) ⇒ [CoreDID](#CoreDID) + + + +### new JwtPresentationValidator(signatureVerifier) +Creates a new [JwtPresentationValidator](#JwtPresentationValidator). If a `signatureVerifier` is provided it will be used when +verifying decoded JWS signatures, otherwise the default which is only capable of handling the `EdDSA` +algorithm will be used. + + +| Param | Type | +| --- | --- | +| signatureVerifier | IJwsVerifier | + + + +### jwtPresentationValidator.validate(presentationJwt, holder, validation_options) ⇒ [DecodedJwtPresentation](#DecodedJwtPresentation) +Validates a [Presentation](#Presentation) encoded as a [Jwt](#Jwt). + +The following properties are validated according to `options`: +- the JWT can be decoded into a semantically valid presentation. +- the expiration and issuance date contained in the JWT claims. +- the holder's signature. + +Validation is done with respect to the properties set in `options`. + +# Warning + +* This method does NOT validate the constituent credentials and therefore also not the relationship between the +credentials' subjects and the presentation holder. This can be done with [JwtCredentialValidationOptions](#JwtCredentialValidationOptions). +* The lack of an error returned from this method is in of itself not enough to conclude that the presentation can +be trusted. This section contains more information on additional checks that should be carried out before and +after calling this method. + +## The state of the supplied DID Documents. + +The caller must ensure that the DID Documents in `holder` are up-to-date. + +# Errors + +An error is returned whenever a validated condition is not satisfied or when decoding fails. + +**Kind**: instance method of [JwtPresentationValidator](#JwtPresentationValidator) + +| Param | Type | +| --- | --- | +| presentationJwt | [Jwt](#Jwt) | +| holder | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| validation_options | [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) | + + + +### JwtPresentationValidator.checkStructure(presentation) +Validates the semantic structure of the [Presentation](#Presentation). + +**Kind**: static method of [JwtPresentationValidator](#JwtPresentationValidator) + +| Param | Type | +| --- | --- | +| presentation | [Presentation](#Presentation) | + + + +### JwtPresentationValidator.extractHolder(presentation) ⇒ [CoreDID](#CoreDID) +Attempt to extract the holder of the presentation. + +# Errors: +* If deserialization/decoding of the presentation fails. +* If the holder can't be parsed as DIDs. + +**Kind**: static method of [JwtPresentationValidator](#JwtPresentationValidator) + +| Param | Type | +| --- | --- | +| presentation | [Jwt](#Jwt) | + + + +## KeyBindingJWTValidationOptions +Options to declare validation criteria when validating credentials. + +**Kind**: global class + +* [KeyBindingJWTValidationOptions](#KeyBindingJWTValidationOptions) + * [new KeyBindingJWTValidationOptions(options)](#new_KeyBindingJWTValidationOptions_new) + * _instance_ + * [.toJSON()](#KeyBindingJWTValidationOptions+toJSON) ⇒ any + * [.clone()](#KeyBindingJWTValidationOptions+clone) ⇒ [KeyBindingJWTValidationOptions](#KeyBindingJWTValidationOptions) + * _static_ + * [.fromJSON(json)](#KeyBindingJWTValidationOptions.fromJSON) ⇒ [KeyBindingJWTValidationOptions](#KeyBindingJWTValidationOptions) + + + +### new KeyBindingJWTValidationOptions(options) + +| Param | Type | +| --- | --- | +| options | IKeyBindingJWTValidationOptions \| undefined | + + + +### keyBindingJWTValidationOptions.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [KeyBindingJWTValidationOptions](#KeyBindingJWTValidationOptions) + + +### keyBindingJWTValidationOptions.clone() ⇒ [KeyBindingJWTValidationOptions](#KeyBindingJWTValidationOptions) +Deep clones the object. + +**Kind**: instance method of [KeyBindingJWTValidationOptions](#KeyBindingJWTValidationOptions) + + +### KeyBindingJWTValidationOptions.fromJSON(json) ⇒ [KeyBindingJWTValidationOptions](#KeyBindingJWTValidationOptions) +Deserializes an instance from a JSON object. + +**Kind**: static method of [KeyBindingJWTValidationOptions](#KeyBindingJWTValidationOptions) + +| Param | Type | +| --- | --- | +| json | any | + + + +## KeyBindingJwtClaims +Claims set for key binding JWT. + +**Kind**: global class + +* [KeyBindingJwtClaims](#KeyBindingJwtClaims) + * [new KeyBindingJwtClaims(jwt, disclosures, nonce, aud, issued_at, custom_properties)](#new_KeyBindingJwtClaims_new) + * _instance_ + * [.toString()](#KeyBindingJwtClaims+toString) ⇒ string + * [.iat()](#KeyBindingJwtClaims+iat) ⇒ bigint + * [.aud()](#KeyBindingJwtClaims+aud) ⇒ string + * [.nonce()](#KeyBindingJwtClaims+nonce) ⇒ string + * [.sdHash()](#KeyBindingJwtClaims+sdHash) ⇒ string + * [.customProperties()](#KeyBindingJwtClaims+customProperties) ⇒ Record.<string, any> + * [.toJSON()](#KeyBindingJwtClaims+toJSON) ⇒ any + * [.clone()](#KeyBindingJwtClaims+clone) ⇒ [KeyBindingJwtClaims](#KeyBindingJwtClaims) + * _static_ + * [.keyBindingJwtHeaderTyp()](#KeyBindingJwtClaims.keyBindingJwtHeaderTyp) ⇒ string + * [.fromJSON(json)](#KeyBindingJwtClaims.fromJSON) ⇒ [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + + +### new KeyBindingJwtClaims(jwt, disclosures, nonce, aud, issued_at, custom_properties) +Creates a new [`KeyBindingJwtClaims`]. +When `issued_at` is left as None, it will automatically default to the current time. + +# Error +When `issued_at` is set to `None` and the system returns time earlier than `SystemTime::UNIX_EPOCH`. + + +| Param | Type | +| --- | --- | +| jwt | string | +| disclosures | Array.<string> | +| nonce | string | +| aud | string | +| issued_at | [Timestamp](#Timestamp) \| undefined | +| custom_properties | Record.<string, any> \| undefined | + + + +### keyBindingJwtClaims.toString() ⇒ string +Returns a string representation of the claims. + +**Kind**: instance method of [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + +### keyBindingJwtClaims.iat() ⇒ bigint +Returns a copy of the issued at `iat` property. + +**Kind**: instance method of [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + +### keyBindingJwtClaims.aud() ⇒ string +Returns a copy of the audience `aud` property. + +**Kind**: instance method of [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + +### keyBindingJwtClaims.nonce() ⇒ string +Returns a copy of the `nonce` property. + +**Kind**: instance method of [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + +### keyBindingJwtClaims.sdHash() ⇒ string +Returns a copy of the `sd_hash` property. + +**Kind**: instance method of [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + +### keyBindingJwtClaims.customProperties() ⇒ Record.<string, any> +Returns a copy of the custom properties. + +**Kind**: instance method of [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + +### keyBindingJwtClaims.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + +### keyBindingJwtClaims.clone() ⇒ [KeyBindingJwtClaims](#KeyBindingJwtClaims) +Deep clones the object. + +**Kind**: instance method of [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + +### KeyBindingJwtClaims.keyBindingJwtHeaderTyp() ⇒ string +Returns the value of the `typ` property of the JWT header according to +https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html#name-key-binding-jwt + +**Kind**: static method of [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + +### KeyBindingJwtClaims.fromJSON(json) ⇒ [KeyBindingJwtClaims](#KeyBindingJwtClaims) +Deserializes an instance from a JSON object. + +**Kind**: static method of [KeyBindingJwtClaims](#KeyBindingJwtClaims) + +| Param | Type | +| --- | --- | +| json | any | + + + +## LinkedDomainService +**Kind**: global class + +* [LinkedDomainService](#LinkedDomainService) + * [new LinkedDomainService(options)](#new_LinkedDomainService_new) + * _instance_ + * [.domains()](#LinkedDomainService+domains) ⇒ Array.<string> + * [.toService()](#LinkedDomainService+toService) ⇒ [Service](#Service) + * [.clone()](#LinkedDomainService+clone) ⇒ [LinkedDomainService](#LinkedDomainService) + * _static_ + * [.fromService(service)](#LinkedDomainService.fromService) ⇒ [LinkedDomainService](#LinkedDomainService) + * [.isValid(service)](#LinkedDomainService.isValid) ⇒ boolean + + + +### new LinkedDomainService(options) +Constructs a new [LinkedDomainService](#LinkedDomainService) that wraps a spec compliant [Linked Domain Service Endpoint](https://identity.foundation/.well-known/resources/did-configuration/#linked-domain-service-endpoint). + +Domain URLs must include the `https` scheme in order to pass the domain linkage validation. + + +| Param | Type | +| --- | --- | +| options | ILinkedDomainService | + + + +### linkedDomainService.domains() ⇒ Array.<string> +Returns the domains contained in the Linked Domain Service. + +**Kind**: instance method of [LinkedDomainService](#LinkedDomainService) + + +### linkedDomainService.toService() ⇒ [Service](#Service) +Returns the inner service which can be added to a DID Document. + +**Kind**: instance method of [LinkedDomainService](#LinkedDomainService) + + +### linkedDomainService.clone() ⇒ [LinkedDomainService](#LinkedDomainService) +Deep clones the object. + +**Kind**: instance method of [LinkedDomainService](#LinkedDomainService) + + +### LinkedDomainService.fromService(service) ⇒ [LinkedDomainService](#LinkedDomainService) +Creates a new [LinkedDomainService](#LinkedDomainService) from a [Service](#Service). + +# Error + +Errors if `service` is not a valid Linked Domain Service. + +**Kind**: static method of [LinkedDomainService](#LinkedDomainService) + +| Param | Type | +| --- | --- | +| service | [Service](#Service) | + + + +### LinkedDomainService.isValid(service) ⇒ boolean +Returns `true` if a [Service](#Service) is a valid Linked Domain Service. + +**Kind**: static method of [LinkedDomainService](#LinkedDomainService) + +| Param | Type | +| --- | --- | +| service | [Service](#Service) | + + + +## MethodData +Supported verification method data formats. + +**Kind**: global class + +* [MethodData](#MethodData) + * _instance_ + * [.tryDecode()](#MethodData+tryDecode) ⇒ Uint8Array + * [.tryPublicKeyJwk()](#MethodData+tryPublicKeyJwk) ⇒ [Jwk](#Jwk) + * [.toJSON()](#MethodData+toJSON) ⇒ any + * [.clone()](#MethodData+clone) ⇒ [MethodData](#MethodData) + * _static_ + * [.newBase58(data)](#MethodData.newBase58) ⇒ [MethodData](#MethodData) + * [.newMultibase(data)](#MethodData.newMultibase) ⇒ [MethodData](#MethodData) + * [.newJwk(key)](#MethodData.newJwk) ⇒ [MethodData](#MethodData) + * [.fromJSON(json)](#MethodData.fromJSON) ⇒ [MethodData](#MethodData) + + + +### methodData.tryDecode() ⇒ Uint8Array +Returns a `Uint8Array` containing the decoded bytes of the [MethodData](#MethodData). + +This is generally a public key identified by a [MethodData](#MethodData) value. + +### Errors +Decoding can fail if [MethodData](#MethodData) has invalid content or cannot be +represented as a vector of bytes. + +**Kind**: instance method of [MethodData](#MethodData) + + +### methodData.tryPublicKeyJwk() ⇒ [Jwk](#Jwk) +Returns the wrapped [Jwk](#Jwk) if the format is `PublicKeyJwk`. + +**Kind**: instance method of [MethodData](#MethodData) + + +### methodData.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [MethodData](#MethodData) + + +### methodData.clone() ⇒ [MethodData](#MethodData) +Deep clones the object. + +**Kind**: instance method of [MethodData](#MethodData) + + +### MethodData.newBase58(data) ⇒ [MethodData](#MethodData) +Creates a new [MethodData](#MethodData) variant with Base58-BTC encoded content. + +**Kind**: static method of [MethodData](#MethodData) + +| Param | Type | +| --- | --- | +| data | Uint8Array | + + + +### MethodData.newMultibase(data) ⇒ [MethodData](#MethodData) +Creates a new [MethodData](#MethodData) variant with Multibase-encoded content. + +**Kind**: static method of [MethodData](#MethodData) + +| Param | Type | +| --- | --- | +| data | Uint8Array | + + + +### MethodData.newJwk(key) ⇒ [MethodData](#MethodData) +Creates a new [MethodData](#MethodData) variant consisting of the given `key`. + +### Errors +An error is thrown if the given `key` contains any private components. + +**Kind**: static method of [MethodData](#MethodData) + +| Param | Type | +| --- | --- | +| key | [Jwk](#Jwk) | + + + +### MethodData.fromJSON(json) ⇒ [MethodData](#MethodData) +Deserializes an instance from a JSON object. + +**Kind**: static method of [MethodData](#MethodData) + +| Param | Type | +| --- | --- | +| json | any | + + + +## MethodDigest +Unique identifier of a [VerificationMethod](#VerificationMethod). + +NOTE: +This class does not have a JSON representation, +use the methods `pack` and `unpack` instead. + +**Kind**: global class + +* [MethodDigest](#MethodDigest) + * [new MethodDigest(verification_method)](#new_MethodDigest_new) + * _instance_ + * [.pack()](#MethodDigest+pack) ⇒ Uint8Array + * [.clone()](#MethodDigest+clone) ⇒ [MethodDigest](#MethodDigest) + * _static_ + * [.unpack(bytes)](#MethodDigest.unpack) ⇒ [MethodDigest](#MethodDigest) + + + +### new MethodDigest(verification_method) + +| Param | Type | +| --- | --- | +| verification_method | [VerificationMethod](#VerificationMethod) | + + + +### methodDigest.pack() ⇒ Uint8Array +Packs [MethodDigest](#MethodDigest) into bytes. + +**Kind**: instance method of [MethodDigest](#MethodDigest) + + +### methodDigest.clone() ⇒ [MethodDigest](#MethodDigest) +Deep clones the object. + +**Kind**: instance method of [MethodDigest](#MethodDigest) + + +### MethodDigest.unpack(bytes) ⇒ [MethodDigest](#MethodDigest) +Unpacks bytes into [MethodDigest](#MethodDigest). + +**Kind**: static method of [MethodDigest](#MethodDigest) + +| Param | Type | +| --- | --- | +| bytes | Uint8Array | + + + +## MethodScope +Supported verification method types. + +**Kind**: global class + +* [MethodScope](#MethodScope) + * _instance_ + * [.toString()](#MethodScope+toString) ⇒ string + * [.toJSON()](#MethodScope+toJSON) ⇒ any + * [.clone()](#MethodScope+clone) ⇒ [MethodScope](#MethodScope) + * _static_ + * [.VerificationMethod()](#MethodScope.VerificationMethod) ⇒ [MethodScope](#MethodScope) + * [.Authentication()](#MethodScope.Authentication) ⇒ [MethodScope](#MethodScope) + * [.AssertionMethod()](#MethodScope.AssertionMethod) ⇒ [MethodScope](#MethodScope) + * [.KeyAgreement()](#MethodScope.KeyAgreement) ⇒ [MethodScope](#MethodScope) + * [.CapabilityDelegation()](#MethodScope.CapabilityDelegation) ⇒ [MethodScope](#MethodScope) + * [.CapabilityInvocation()](#MethodScope.CapabilityInvocation) ⇒ [MethodScope](#MethodScope) + * [.fromJSON(json)](#MethodScope.fromJSON) ⇒ [MethodScope](#MethodScope) + + + +### methodScope.toString() ⇒ string +Returns the [MethodScope](#MethodScope) as a string. + +**Kind**: instance method of [MethodScope](#MethodScope) + + +### methodScope.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [MethodScope](#MethodScope) + + +### methodScope.clone() ⇒ [MethodScope](#MethodScope) +Deep clones the object. + +**Kind**: instance method of [MethodScope](#MethodScope) + + +### MethodScope.VerificationMethod() ⇒ [MethodScope](#MethodScope) +**Kind**: static method of [MethodScope](#MethodScope) + + +### MethodScope.Authentication() ⇒ [MethodScope](#MethodScope) +**Kind**: static method of [MethodScope](#MethodScope) + + +### MethodScope.AssertionMethod() ⇒ [MethodScope](#MethodScope) +**Kind**: static method of [MethodScope](#MethodScope) + + +### MethodScope.KeyAgreement() ⇒ [MethodScope](#MethodScope) +**Kind**: static method of [MethodScope](#MethodScope) + + +### MethodScope.CapabilityDelegation() ⇒ [MethodScope](#MethodScope) +**Kind**: static method of [MethodScope](#MethodScope) + + +### MethodScope.CapabilityInvocation() ⇒ [MethodScope](#MethodScope) +**Kind**: static method of [MethodScope](#MethodScope) + + +### MethodScope.fromJSON(json) ⇒ [MethodScope](#MethodScope) +Deserializes an instance from a JSON object. + +**Kind**: static method of [MethodScope](#MethodScope) + +| Param | Type | +| --- | --- | +| json | any | + + + +## MethodType +Supported verification method types. + +**Kind**: global class + +* [MethodType](#MethodType) + * _instance_ + * [.toString()](#MethodType+toString) ⇒ string + * [.toJSON()](#MethodType+toJSON) ⇒ any + * [.clone()](#MethodType+clone) ⇒ [MethodType](#MethodType) + * _static_ + * [.Ed25519VerificationKey2018()](#MethodType.Ed25519VerificationKey2018) ⇒ [MethodType](#MethodType) + * [.X25519KeyAgreementKey2019()](#MethodType.X25519KeyAgreementKey2019) ⇒ [MethodType](#MethodType) + * [.JsonWebKey()](#MethodType.JsonWebKey) ⇒ [MethodType](#MethodType) + * [.fromJSON(json)](#MethodType.fromJSON) ⇒ [MethodType](#MethodType) + + + +### methodType.toString() ⇒ string +Returns the [MethodType](#MethodType) as a string. + +**Kind**: instance method of [MethodType](#MethodType) + + +### methodType.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [MethodType](#MethodType) + + +### methodType.clone() ⇒ [MethodType](#MethodType) +Deep clones the object. + +**Kind**: instance method of [MethodType](#MethodType) + + +### MethodType.Ed25519VerificationKey2018() ⇒ [MethodType](#MethodType) +**Kind**: static method of [MethodType](#MethodType) + + +### MethodType.X25519KeyAgreementKey2019() ⇒ [MethodType](#MethodType) +**Kind**: static method of [MethodType](#MethodType) + + +### MethodType.JsonWebKey() ⇒ [MethodType](#MethodType) +A verification method for use with JWT verification as prescribed by the [Jwk](#Jwk) +in the `publicKeyJwk` entry. + +**Kind**: static method of [MethodType](#MethodType) + + +### MethodType.fromJSON(json) ⇒ [MethodType](#MethodType) +Deserializes an instance from a JSON object. + +**Kind**: static method of [MethodType](#MethodType) + +| Param | Type | +| --- | --- | +| json | any | + + + +## Presentation +**Kind**: global class + +* [Presentation](#Presentation) + * [new Presentation(values)](#new_Presentation_new) + * _instance_ + * [.context()](#Presentation+context) ⇒ Array.<(string\|Record.<string, any>)> + * [.id()](#Presentation+id) ⇒ string \| undefined + * [.type()](#Presentation+type) ⇒ Array.<string> + * [.verifiableCredential()](#Presentation+verifiableCredential) ⇒ [Array.<UnknownCredential>](#UnknownCredential) + * [.holder()](#Presentation+holder) ⇒ string + * [.refreshService()](#Presentation+refreshService) ⇒ Array.<RefreshService> + * [.termsOfUse()](#Presentation+termsOfUse) ⇒ Array.<Policy> + * [.proof()](#Presentation+proof) ⇒ [Proof](#Proof) \| undefined + * [.setProof(proof)](#Presentation+setProof) + * [.properties()](#Presentation+properties) ⇒ Map.<string, any> + * [.toJSON()](#Presentation+toJSON) ⇒ any + * [.clone()](#Presentation+clone) ⇒ [Presentation](#Presentation) + * _static_ + * [.BaseContext()](#Presentation.BaseContext) ⇒ string + * [.BaseType()](#Presentation.BaseType) ⇒ string + * [.fromJSON(json)](#Presentation.fromJSON) ⇒ [Presentation](#Presentation) + + + +### new Presentation(values) +Constructs a new presentation. + + +| Param | Type | +| --- | --- | +| values | IPresentation | + + + +### presentation.context() ⇒ Array.<(string\|Record.<string, any>)> +Returns a copy of the JSON-LD context(s) applicable to the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + +### presentation.id() ⇒ string \| undefined +Returns a copy of the unique `URI` identifying the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + +### presentation.type() ⇒ Array.<string> +Returns a copy of the URIs defining the type of the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + +### presentation.verifiableCredential() ⇒ [Array.<UnknownCredential>](#UnknownCredential) +Returns the JWT credentials expressing the claims of the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + +### presentation.holder() ⇒ string +Returns a copy of the URI of the entity that generated the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + +### presentation.refreshService() ⇒ Array.<RefreshService> +Returns a copy of the service(s) used to refresh an expired [Credential](#Credential) in the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + +### presentation.termsOfUse() ⇒ Array.<Policy> +Returns a copy of the terms-of-use specified by the presentation holder + +**Kind**: instance method of [Presentation](#Presentation) + + +### presentation.proof() ⇒ [Proof](#Proof) \| undefined +Optional cryptographic proof, unrelated to JWT. + +**Kind**: instance method of [Presentation](#Presentation) + + +### presentation.setProof(proof) +Sets the proof property of the [Presentation](#Presentation). + +Note that this proof is not related to JWT. + +**Kind**: instance method of [Presentation](#Presentation) + +| Param | Type | +| --- | --- | +| proof | [Proof](#Proof) \| undefined | + + + +### presentation.properties() ⇒ Map.<string, any> +Returns a copy of the miscellaneous properties on the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + +### presentation.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [Presentation](#Presentation) + + +### presentation.clone() ⇒ [Presentation](#Presentation) +Deep clones the object. + +**Kind**: instance method of [Presentation](#Presentation) + + +### Presentation.BaseContext() ⇒ string +Returns the base JSON-LD context. + +**Kind**: static method of [Presentation](#Presentation) + + +### Presentation.BaseType() ⇒ string +Returns the base type. + +**Kind**: static method of [Presentation](#Presentation) + + +### Presentation.fromJSON(json) ⇒ [Presentation](#Presentation) +Deserializes an instance from a JSON object. + +**Kind**: static method of [Presentation](#Presentation) + +| Param | Type | +| --- | --- | +| json | any | + + + +## Proof +Represents a cryptographic proof that can be used to validate verifiable credentials and +presentations. + +This representation does not inherently implement any standard; instead, it +can be utilized to implement standards or user-defined proofs. The presence of the +`type` field is necessary to accommodate different types of cryptographic proofs. + +Note that this proof is not related to JWT and can be used in combination or as an alternative +to it. + +**Kind**: global class + +* [Proof](#Proof) + * [new Proof(type_, properties)](#new_Proof_new) + * _instance_ + * [.type()](#Proof+type) ⇒ string + * [.properties()](#Proof+properties) ⇒ any + * [.toJSON()](#Proof+toJSON) ⇒ any + * [.clone()](#Proof+clone) ⇒ [Proof](#Proof) + * _static_ + * [.fromJSON(json)](#Proof.fromJSON) ⇒ [Proof](#Proof) + + + +### new Proof(type_, properties) + +| Param | Type | +| --- | --- | +| type_ | string | +| properties | any | + + + +### proof.type() ⇒ string +Returns the type of proof. + +**Kind**: instance method of [Proof](#Proof) + + +### proof.properties() ⇒ any +Returns the properties of the proof. + +**Kind**: instance method of [Proof](#Proof) + + +### proof.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [Proof](#Proof) + + +### proof.clone() ⇒ [Proof](#Proof) +Deep clones the object. + +**Kind**: instance method of [Proof](#Proof) + + +### Proof.fromJSON(json) ⇒ [Proof](#Proof) +Deserializes an instance from a JSON object. + +**Kind**: static method of [Proof](#Proof) + +| Param | Type | +| --- | --- | +| json | any | + + + +## Resolver +Convenience type for resolving DID documents from different DID methods. + +Also provides methods for resolving DID Documents associated with +verifiable [Credential](#Credential)s and [Presentation](#Presentation)s. + +# Configuration + +The resolver will only be able to resolve DID documents for methods it has been configured for in the constructor. + +**Kind**: global class + +* [Resolver](#Resolver) + * [new Resolver(config)](#new_Resolver_new) + * [.resolve(did)](#Resolver+resolve) ⇒ Promise.<(CoreDocument\|IToCoreDocument)> + * [.resolveMultiple(dids)](#Resolver+resolveMultiple) ⇒ Promise.<Array.<(CoreDocument\|IToCoreDocument)>> + + + +### new Resolver(config) +Constructs a new [Resolver](#Resolver). + +# Errors +If both a `client` is given and the `handlers` map contains the "iota" key the construction process +will throw an error because the handler for the "iota" method then becomes ambiguous. + + +| Param | Type | +| --- | --- | +| config | ResolverConfig | + + + +### resolver.resolve(did) ⇒ Promise.<(CoreDocument\|IToCoreDocument)> +Fetches the DID Document of the given DID. + +### Errors + +Errors if the resolver has not been configured to handle the method +corresponding to the given DID or the resolution process itself fails. + +**Kind**: instance method of [Resolver](#Resolver) + +| Param | Type | +| --- | --- | +| did | string | + + + +### resolver.resolveMultiple(dids) ⇒ Promise.<Array.<(CoreDocument\|IToCoreDocument)>> +Concurrently fetches the DID Documents of the multiple given DIDs. + +# Errors +* If the resolver has not been configured to handle the method of any of the given DIDs. +* If the resolution process of any DID fails. + +## Note +* The order of the documents in the returned array matches that in `dids`. +* If `dids` contains duplicates, these will be resolved only once and the resolved document +is copied into the returned array to match the order of `dids`. + +**Kind**: instance method of [Resolver](#Resolver) + +| Param | Type | +| --- | --- | +| dids | Array.<string> | + + + +## RevocationBitmap +A compressed bitmap for managing credential revocation. + +**Kind**: global class + +* [RevocationBitmap](#RevocationBitmap) + * [new RevocationBitmap()](#new_RevocationBitmap_new) + * _instance_ + * [.isRevoked(index)](#RevocationBitmap+isRevoked) ⇒ boolean + * [.revoke(index)](#RevocationBitmap+revoke) ⇒ boolean + * [.unrevoke(index)](#RevocationBitmap+unrevoke) ⇒ boolean + * [.len()](#RevocationBitmap+len) ⇒ number + * [.toService(serviceId)](#RevocationBitmap+toService) ⇒ [Service](#Service) + * _static_ + * [.type()](#RevocationBitmap.type) ⇒ string + * [.fromEndpoint(service)](#RevocationBitmap.fromEndpoint) ⇒ [RevocationBitmap](#RevocationBitmap) + + + +### new RevocationBitmap() +Creates a new [RevocationBitmap](#RevocationBitmap) instance. + + + +### revocationBitmap.isRevoked(index) ⇒ boolean +Returns `true` if the credential at the given `index` is revoked. + +**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) + +| Param | Type | +| --- | --- | +| index | number | + + + +### revocationBitmap.revoke(index) ⇒ boolean +Mark the given index as revoked. + +Returns true if the index was absent from the set. + +**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) + +| Param | Type | +| --- | --- | +| index | number | + + + +### revocationBitmap.unrevoke(index) ⇒ boolean +Mark the index as not revoked. + +Returns true if the index was present in the set. + +**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) + +| Param | Type | +| --- | --- | +| index | number | + + + +### revocationBitmap.len() ⇒ number +Returns the number of revoked credentials. + +**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) + + +### revocationBitmap.toService(serviceId) ⇒ [Service](#Service) +Return a `Service` with: +- the service's id set to `serviceId`, +- of type `RevocationBitmap2022`, +- and with the bitmap embedded in a data url in the service's endpoint. + +**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) + +| Param | Type | +| --- | --- | +| serviceId | [DIDUrl](#DIDUrl) | + + + +### RevocationBitmap.type() ⇒ string +The name of the service type. + +**Kind**: static method of [RevocationBitmap](#RevocationBitmap) + + +### RevocationBitmap.fromEndpoint(service) ⇒ [RevocationBitmap](#RevocationBitmap) +Try to construct a [RevocationBitmap](#RevocationBitmap) from a service +if it is a valid Revocation Bitmap Service. + +**Kind**: static method of [RevocationBitmap](#RevocationBitmap) + +| Param | Type | +| --- | --- | +| service | [Service](#Service) | + + + +## SdJwt +Representation of an SD-JWT of the format +`~~~...~~`. + +**Kind**: global class + +* [SdJwt](#SdJwt) + * [new SdJwt(jwt, disclosures, key_binding_jwt)](#new_SdJwt_new) + * _instance_ + * [.presentation()](#SdJwt+presentation) ⇒ string + * [.toString()](#SdJwt+toString) ⇒ string + * [.jwt()](#SdJwt+jwt) ⇒ string + * [.disclosures()](#SdJwt+disclosures) ⇒ Array.<string> + * [.keyBindingJwt()](#SdJwt+keyBindingJwt) ⇒ string \| undefined + * [.toJSON()](#SdJwt+toJSON) ⇒ any + * [.clone()](#SdJwt+clone) ⇒ [SdJwt](#SdJwt) + * _static_ + * [.parse(sd_jwt)](#SdJwt.parse) ⇒ [SdJwt](#SdJwt) + * [.fromJSON(json)](#SdJwt.fromJSON) ⇒ [SdJwt](#SdJwt) + + + +### new SdJwt(jwt, disclosures, key_binding_jwt) +Creates a new `SdJwt` from its components. + + +| Param | Type | +| --- | --- | +| jwt | string | +| disclosures | Array.<string> | +| key_binding_jwt | string \| undefined | + + + +### sdJwt.presentation() ⇒ string +Serializes the components into the final SD-JWT. + +**Kind**: instance method of [SdJwt](#SdJwt) + + +### sdJwt.toString() ⇒ string +Serializes the components into the final SD-JWT. + +**Kind**: instance method of [SdJwt](#SdJwt) + + +### sdJwt.jwt() ⇒ string +The JWT part. + +**Kind**: instance method of [SdJwt](#SdJwt) + + +### sdJwt.disclosures() ⇒ Array.<string> +The disclosures part. + +**Kind**: instance method of [SdJwt](#SdJwt) + + +### sdJwt.keyBindingJwt() ⇒ string \| undefined +The optional key binding JWT. + +**Kind**: instance method of [SdJwt](#SdJwt) + + +### sdJwt.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [SdJwt](#SdJwt) + + +### sdJwt.clone() ⇒ [SdJwt](#SdJwt) +Deep clones the object. + +**Kind**: instance method of [SdJwt](#SdJwt) + + +### SdJwt.parse(sd_jwt) ⇒ [SdJwt](#SdJwt) +Parses an SD-JWT into its components as [`SdJwt`]. + +## Error +Returns `DeserializationError` if parsing fails. + +**Kind**: static method of [SdJwt](#SdJwt) + +| Param | Type | +| --- | --- | +| sd_jwt | string | + + + +### SdJwt.fromJSON(json) ⇒ [SdJwt](#SdJwt) +Deserializes an instance from a JSON object. + +**Kind**: static method of [SdJwt](#SdJwt) + +| Param | Type | +| --- | --- | +| json | any | + + + +## SdJwtCredentialValidator +A type for decoding and validating [Credential](#Credential). + +**Kind**: global class + +* [SdJwtCredentialValidator](#SdJwtCredentialValidator) + * [new SdJwtCredentialValidator(signatureVerifier)](#new_SdJwtCredentialValidator_new) + * [.validateCredential(sd_jwt, issuer, options, fail_fast)](#SdJwtCredentialValidator+validateCredential) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) + * [.verifySignature(credential, trustedIssuers, options)](#SdJwtCredentialValidator+verifySignature) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) + * [.validateKeyBindingJwt(sdJwt, holder, options)](#SdJwtCredentialValidator+validateKeyBindingJwt) ⇒ [KeyBindingJwtClaims](#KeyBindingJwtClaims) + + + +### new SdJwtCredentialValidator(signatureVerifier) +Creates a new `SdJwtCredentialValidator`. If a `signatureVerifier` is provided it will be used when +verifying decoded JWS signatures, otherwise the default which is only capable of handling the `EdDSA` +algorithm will be used. + + +| Param | Type | +| --- | --- | +| signatureVerifier | IJwsVerifier | + + + +### sdJwtCredentialValidator.validateCredential(sd_jwt, issuer, options, fail_fast) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) +Decodes and validates a `Credential` issued as an SD-JWT. A `DecodedJwtCredential` is returned upon success. +The credential is constructed by replacing disclosures following the +[`Selective Disclosure for JWTs (SD-JWT)`](https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html) standard. + +The following properties are validated according to `options`: +- the issuer's signature on the JWS, +- the expiration date, +- the issuance date, +- the semantic structure. + +# Warning +* The key binding JWT is not validated. If needed, it must be validated separately using +`SdJwtValidator::validate_key_binding_jwt`. +* The lack of an error returned from this method is in of itself not enough to conclude that the credential can be +trusted. This section contains more information on additional checks that should be carried out before and after +calling this method. + +## The state of the issuer's DID Document +The caller must ensure that `issuer` represents an up-to-date DID Document. + +## Properties that are not validated + There are many properties defined in [The Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) that are **not** validated, such as: +`proof`, `credentialStatus`, `type`, `credentialSchema`, `refreshService` **and more**. +These should be manually checked after validation, according to your requirements. + +# Errors +An error is returned whenever a validated condition is not satisfied. + +**Kind**: instance method of [SdJwtCredentialValidator](#SdJwtCredentialValidator) + +| Param | Type | +| --- | --- | +| sd_jwt | [SdJwt](#SdJwt) | +| issuer | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| options | [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) | +| fail_fast | number | + + + +### sdJwtCredentialValidator.verifySignature(credential, trustedIssuers, options) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) +Decode and verify the JWS signature of a `Credential` issued as an SD-JWT using the DID Document of a trusted +issuer and replaces the disclosures. + +A `DecodedJwtCredential` is returned upon success. + +# Warning +The caller must ensure that the DID Documents of the trusted issuers are up-to-date. + +## Proofs + Only the JWS signature is verified. If the `Credential` contains a `proof` property this will not be verified +by this method. + +# Errors +* If the issuer' URL cannot be parsed. +* If Signature verification fails. +* If SD decoding fails. + +**Kind**: instance method of [SdJwtCredentialValidator](#SdJwtCredentialValidator) + +| Param | Type | +| --- | --- | +| credential | [SdJwt](#SdJwt) | +| trustedIssuers | Array.<(CoreDocument\|IToCoreDocument)> | +| options | [JwsVerificationOptions](#JwsVerificationOptions) | + + + +### sdJwtCredentialValidator.validateKeyBindingJwt(sdJwt, holder, options) ⇒ [KeyBindingJwtClaims](#KeyBindingJwtClaims) +Validates a Key Binding JWT (KB-JWT) according to `https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html#name-key-binding-jwt`. +The Validation process includes: + * Signature validation using public key materials defined in the `holder` document. + * `typ` value in KB-JWT header. + * `sd_hash` claim value in the KB-JWT claim. + * Optional `nonce`, `aud` and issuance date validation. + +**Kind**: instance method of [SdJwtCredentialValidator](#SdJwtCredentialValidator) + +| Param | Type | +| --- | --- | +| sdJwt | [SdJwt](#SdJwt) | +| holder | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| options | [KeyBindingJWTValidationOptions](#KeyBindingJWTValidationOptions) | + + + +## SdObjectDecoder +Substitutes digests in an SD-JWT object by their corresponding plaintext values provided by disclosures. + +**Kind**: global class + +* [SdObjectDecoder](#SdObjectDecoder) + * [new SdObjectDecoder()](#new_SdObjectDecoder_new) + * [.decode(object, disclosures)](#SdObjectDecoder+decode) ⇒ Record.<string, any> + + + +### new SdObjectDecoder() +Creates a new `SdObjectDecoder` with `sha-256` hasher. + + + +### sdObjectDecoder.decode(object, disclosures) ⇒ Record.<string, any> +Decodes an SD-JWT `object` containing by Substituting the digests with their corresponding +plaintext values provided by `disclosures`. + +## Notes +* Claims like `exp` or `iat` are not validated in the process of decoding. +* `_sd_alg` property will be removed if present. + +**Kind**: instance method of [SdObjectDecoder](#SdObjectDecoder) + +| Param | Type | +| --- | --- | +| object | Record.<string, any> | +| disclosures | Array.<string> | + + + +## SdObjectEncoder +Transforms a JSON object into an SD-JWT object by substituting selected values +with their corresponding disclosure digests. + +Note: digests are created using the sha-256 algorithm. + +**Kind**: global class + +* [SdObjectEncoder](#SdObjectEncoder) + * [new SdObjectEncoder(object)](#new_SdObjectEncoder_new) + * [.conceal(path, salt)](#SdObjectEncoder+conceal) ⇒ [Disclosure](#Disclosure) + * [.addSdAlgProperty()](#SdObjectEncoder+addSdAlgProperty) + * [.encodeToString()](#SdObjectEncoder+encodeToString) ⇒ string + * [.toString()](#SdObjectEncoder+toString) ⇒ string + * [.encodeToObject()](#SdObjectEncoder+encodeToObject) ⇒ Record.<string, any> + * [.toJSON()](#SdObjectEncoder+toJSON) ⇒ any + * [.addDecoys(path, number_of_decoys)](#SdObjectEncoder+addDecoys) + + + +### new SdObjectEncoder(object) +Creates a new `SdObjectEncoder` with `sha-256` hash function. + + +| Param | Type | +| --- | --- | +| object | any | + + + +### sdObjectEncoder.conceal(path, salt) ⇒ [Disclosure](#Disclosure) +Substitutes a value with the digest of its disclosure. +If no salt is provided, the disclosure will be created with a random salt value. + +`path` indicates the pointer to the value that will be concealed using the syntax of +[JSON pointer](https://datatracker.ietf.org/doc/html/rfc6901). + +For the following object: + + ``` +{ + "id": "did:value", + "claim1": { + "abc": true + }, + "claim2": ["val_1", "val_2"] +} +``` + +Path "/id" conceals `"id": "did:value"` +Path "/claim1/abc" conceals `"abc": true` +Path "/claim2/0" conceals `val_1` +``` + +## Errors +* `InvalidPath` if pointer is invalid. +* `DataTypeMismatch` if existing SD format is invalid. + +**Kind**: instance method of [SdObjectEncoder](#SdObjectEncoder) + +| Param | Type | +| --- | --- | +| path | string | +| salt | string \| undefined | + + + +### sdObjectEncoder.addSdAlgProperty() +Adds the `_sd_alg` property to the top level of the object, with +its value set to "sha-256". + +**Kind**: instance method of [SdObjectEncoder](#SdObjectEncoder) + + +### sdObjectEncoder.encodeToString() ⇒ string +Returns the modified object as a string. + +**Kind**: instance method of [SdObjectEncoder](#SdObjectEncoder) + + +### sdObjectEncoder.toString() ⇒ string +Returns the modified object as a string. + +**Kind**: instance method of [SdObjectEncoder](#SdObjectEncoder) + + +### sdObjectEncoder.encodeToObject() ⇒ Record.<string, any> +Returns the modified object. + +**Kind**: instance method of [SdObjectEncoder](#SdObjectEncoder) + + +### sdObjectEncoder.toJSON() ⇒ any +Returns the modified object. + +**Kind**: instance method of [SdObjectEncoder](#SdObjectEncoder) + + +### sdObjectEncoder.addDecoys(path, number_of_decoys) +Adds a decoy digest to the specified path. +If path is an empty slice, decoys will be added to the top level. + +**Kind**: instance method of [SdObjectEncoder](#SdObjectEncoder) + +| Param | Type | +| --- | --- | +| path | string | +| number_of_decoys | number | + + + +## Service +A DID Document Service used to enable trusted interactions associated with a DID subject. + +**Kind**: global class + +* [Service](#Service) + * [new Service(service)](#new_Service_new) + * _instance_ + * [.id()](#Service+id) ⇒ [DIDUrl](#DIDUrl) + * [.type()](#Service+type) ⇒ Array.<string> + * [.serviceEndpoint()](#Service+serviceEndpoint) ⇒ string \| Array.<string> \| Map.<string, Array.<string>> + * [.properties()](#Service+properties) ⇒ Map.<string, any> + * [.toJSON()](#Service+toJSON) ⇒ any + * [.clone()](#Service+clone) ⇒ [Service](#Service) + * _static_ + * [.fromJSON(json)](#Service.fromJSON) ⇒ [Service](#Service) + + + +### new Service(service) + +| Param | Type | +| --- | --- | +| service | IService | + + + +### service.id() ⇒ [DIDUrl](#DIDUrl) +Returns a copy of the [Service](#Service) id. + +**Kind**: instance method of [Service](#Service) + + +### service.type() ⇒ Array.<string> +Returns a copy of the [Service](#Service) type. + +**Kind**: instance method of [Service](#Service) + + +### service.serviceEndpoint() ⇒ string \| Array.<string> \| Map.<string, Array.<string>> +Returns a copy of the [Service](#Service) endpoint. + +**Kind**: instance method of [Service](#Service) + + +### service.properties() ⇒ Map.<string, any> +Returns a copy of the custom properties on the [Service](#Service). + +**Kind**: instance method of [Service](#Service) + + +### service.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [Service](#Service) + + +### service.clone() ⇒ [Service](#Service) +Deep clones the object. + +**Kind**: instance method of [Service](#Service) + + +### Service.fromJSON(json) ⇒ [Service](#Service) +Deserializes an instance from a JSON object. + +**Kind**: static method of [Service](#Service) + +| Param | Type | +| --- | --- | +| json | any | + + + +## StatusList2021 +StatusList2021 data structure as described in [W3C's VC status list 2021](https://www.w3.org/TR/2023/WD-vc-status-list-20230427/). + +**Kind**: global class + +* [StatusList2021](#StatusList2021) + * [new StatusList2021(size)](#new_StatusList2021_new) + * _instance_ + * [.clone()](#StatusList2021+clone) ⇒ [StatusList2021](#StatusList2021) + * [.len()](#StatusList2021+len) ⇒ number + * [.get(index)](#StatusList2021+get) ⇒ boolean + * [.set(index, value)](#StatusList2021+set) + * [.intoEncodedStr()](#StatusList2021+intoEncodedStr) ⇒ string + * _static_ + * [.fromEncodedStr(s)](#StatusList2021.fromEncodedStr) ⇒ [StatusList2021](#StatusList2021) + + + +### new StatusList2021(size) +Creates a new [StatusList2021](#StatusList2021) of `size` entries. + + +| Param | Type | +| --- | --- | +| size | number \| undefined | + + + +### statusList2021.clone() ⇒ [StatusList2021](#StatusList2021) +Deep clones the object. + +**Kind**: instance method of [StatusList2021](#StatusList2021) + + +### statusList2021.len() ⇒ number +Returns the number of entries in this [StatusList2021](#StatusList2021). + +**Kind**: instance method of [StatusList2021](#StatusList2021) + + +### statusList2021.get(index) ⇒ boolean +Returns whether the entry at `index` is set. + +**Kind**: instance method of [StatusList2021](#StatusList2021) + +| Param | Type | +| --- | --- | +| index | number | + + + +### statusList2021.set(index, value) +Sets the value of the `index`-th entry. + +**Kind**: instance method of [StatusList2021](#StatusList2021) + +| Param | Type | +| --- | --- | +| index | number | +| value | boolean | + + + +### statusList2021.intoEncodedStr() ⇒ string +Encodes this [StatusList2021](#StatusList2021) into its compressed +base64 string representation. + +**Kind**: instance method of [StatusList2021](#StatusList2021) + + +### StatusList2021.fromEncodedStr(s) ⇒ [StatusList2021](#StatusList2021) +Attempts to decode a [StatusList2021](#StatusList2021) from a string. + +**Kind**: static method of [StatusList2021](#StatusList2021) + +| Param | Type | +| --- | --- | +| s | string | + + + +## StatusList2021Credential +A parsed [StatusList2021Credential](https://www.w3.org/TR/2023/WD-vc-status-list-20230427/#statuslist2021credential). + +**Kind**: global class + +* [StatusList2021Credential](#StatusList2021Credential) + * [new StatusList2021Credential(credential)](#new_StatusList2021Credential_new) + * _instance_ + * [.id()](#StatusList2021Credential+id) ⇒ string + * [.setCredentialStatus(credential, index, revoked_or_suspended)](#StatusList2021Credential+setCredentialStatus) ⇒ [StatusList2021Entry](#StatusList2021Entry) + * [.purpose()](#StatusList2021Credential+purpose) ⇒ number + * [.entry(index)](#StatusList2021Credential+entry) ⇒ number + * [.clone()](#StatusList2021Credential+clone) ⇒ [StatusList2021Credential](#StatusList2021Credential) + * [.toJSON()](#StatusList2021Credential+toJSON) ⇒ any + * _static_ + * [.fromJSON(json)](#StatusList2021Credential.fromJSON) ⇒ [StatusList2021Credential](#StatusList2021Credential) + + + +### new StatusList2021Credential(credential) +Creates a new [StatusList2021Credential](#StatusList2021Credential). + + +| Param | Type | +| --- | --- | +| credential | [Credential](#Credential) | + + + +### statusList2021Credential.id() ⇒ string +**Kind**: instance method of [StatusList2021Credential](#StatusList2021Credential) + + +### statusList2021Credential.setCredentialStatus(credential, index, revoked_or_suspended) ⇒ [StatusList2021Entry](#StatusList2021Entry) +Sets the given credential's status using the `index`-th entry of this status list. +Returns the created `credentialStatus`. + +**Kind**: instance method of [StatusList2021Credential](#StatusList2021Credential) + +| Param | Type | +| --- | --- | +| credential | [Credential](#Credential) | +| index | number | +| revoked_or_suspended | boolean | + + + +### statusList2021Credential.purpose() ⇒ number +Returns the [StatusPurpose](#StatusPurpose) of this [StatusList2021Credential](#StatusList2021Credential). + +**Kind**: instance method of [StatusList2021Credential](#StatusList2021Credential) + + +### statusList2021Credential.entry(index) ⇒ number +Returns the state of the `index`-th entry, if any. + +**Kind**: instance method of [StatusList2021Credential](#StatusList2021Credential) + +| Param | Type | +| --- | --- | +| index | number | + + + +### statusList2021Credential.clone() ⇒ [StatusList2021Credential](#StatusList2021Credential) +**Kind**: instance method of [StatusList2021Credential](#StatusList2021Credential) + + +### statusList2021Credential.toJSON() ⇒ any +**Kind**: instance method of [StatusList2021Credential](#StatusList2021Credential) + + +### StatusList2021Credential.fromJSON(json) ⇒ [StatusList2021Credential](#StatusList2021Credential) +**Kind**: static method of [StatusList2021Credential](#StatusList2021Credential) + +| Param | Type | +| --- | --- | +| json | any | + + + +## StatusList2021CredentialBuilder +Builder type to construct valid [StatusList2021Credential](#StatusList2021Credential) istances. + +**Kind**: global class + +* [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + * [new StatusList2021CredentialBuilder(status_list)](#new_StatusList2021CredentialBuilder_new) + * [.purpose(purpose)](#StatusList2021CredentialBuilder+purpose) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + * [.subjectId(id)](#StatusList2021CredentialBuilder+subjectId) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + * [.expirationDate(time)](#StatusList2021CredentialBuilder+expirationDate) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + * [.issuer(issuer)](#StatusList2021CredentialBuilder+issuer) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + * [.context(context)](#StatusList2021CredentialBuilder+context) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + * [.type(t)](#StatusList2021CredentialBuilder+type) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + * [.proof(proof)](#StatusList2021CredentialBuilder+proof) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + * [.build()](#StatusList2021CredentialBuilder+build) ⇒ [StatusList2021Credential](#StatusList2021Credential) + + + +### new StatusList2021CredentialBuilder(status_list) +Creates a new [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder). + + +| Param | Type | +| --- | --- | +| status_list | [StatusList2021](#StatusList2021) \| undefined | + + + +### statusList2021CredentialBuilder.purpose(purpose) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) +Sets the purpose of the [StatusList2021Credential](#StatusList2021Credential) that is being created. + +**Kind**: instance method of [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + +| Param | Type | +| --- | --- | +| purpose | number | + + + +### statusList2021CredentialBuilder.subjectId(id) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) +Sets `credentialSubject.id`. + +**Kind**: instance method of [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + +| Param | Type | +| --- | --- | +| id | string | + + + +### statusList2021CredentialBuilder.expirationDate(time) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) +Sets the expiration date of the credential. + +**Kind**: instance method of [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + +| Param | Type | +| --- | --- | +| time | [Timestamp](#Timestamp) | + + + +### statusList2021CredentialBuilder.issuer(issuer) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) +Sets the issuer of the credential. + +**Kind**: instance method of [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + +| Param | Type | +| --- | --- | +| issuer | string | + + + +### statusList2021CredentialBuilder.context(context) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) +Sets the context of the credential. + +**Kind**: instance method of [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + +| Param | Type | +| --- | --- | +| context | string | + + + +### statusList2021CredentialBuilder.type(t) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) +Adds a credential type. + +**Kind**: instance method of [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + +| Param | Type | +| --- | --- | +| t | string | + + + +### statusList2021CredentialBuilder.proof(proof) ⇒ [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) +Adds a credential's proof. + +**Kind**: instance method of [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + +| Param | Type | +| --- | --- | +| proof | [Proof](#Proof) | + + + +### statusList2021CredentialBuilder.build() ⇒ [StatusList2021Credential](#StatusList2021Credential) +Attempts to build a valid [StatusList2021Credential](#StatusList2021Credential) with the previously provided data. + +**Kind**: instance method of [StatusList2021CredentialBuilder](#StatusList2021CredentialBuilder) + + +## StatusList2021Entry +[StatusList2021Entry](https://www.w3.org/TR/2023/WD-vc-status-list-20230427/#statuslist2021entry) implementation. + +**Kind**: global class + +* [StatusList2021Entry](#StatusList2021Entry) + * [new StatusList2021Entry(status_list, purpose, index, id)](#new_StatusList2021Entry_new) + * _instance_ + * [.id()](#StatusList2021Entry+id) ⇒ string + * [.purpose()](#StatusList2021Entry+purpose) ⇒ number + * [.index()](#StatusList2021Entry+index) ⇒ number + * [.statusListCredential()](#StatusList2021Entry+statusListCredential) ⇒ string + * [.toStatus()](#StatusList2021Entry+toStatus) ⇒ Status + * [.clone()](#StatusList2021Entry+clone) ⇒ [StatusList2021Entry](#StatusList2021Entry) + * [.toJSON()](#StatusList2021Entry+toJSON) ⇒ any + * _static_ + * [.fromJSON(json)](#StatusList2021Entry.fromJSON) ⇒ [StatusList2021Entry](#StatusList2021Entry) + + + +### new StatusList2021Entry(status_list, purpose, index, id) +Creates a new [StatusList2021Entry](#StatusList2021Entry). + + +| Param | Type | +| --- | --- | +| status_list | string | +| purpose | number | +| index | number | +| id | string \| undefined | + + + +### statusList2021Entry.id() ⇒ string +Returns this `credentialStatus`'s `id`. + +**Kind**: instance method of [StatusList2021Entry](#StatusList2021Entry) + + +### statusList2021Entry.purpose() ⇒ number +Returns the purpose of this entry. + +**Kind**: instance method of [StatusList2021Entry](#StatusList2021Entry) + + +### statusList2021Entry.index() ⇒ number +Returns the index of this entry. + +**Kind**: instance method of [StatusList2021Entry](#StatusList2021Entry) + + +### statusList2021Entry.statusListCredential() ⇒ string +Returns the referenced [StatusList2021Credential](#StatusList2021Credential)'s url. + +**Kind**: instance method of [StatusList2021Entry](#StatusList2021Entry) + + +### statusList2021Entry.toStatus() ⇒ Status +Downcasts [this](this) to [Status](Status) + +**Kind**: instance method of [StatusList2021Entry](#StatusList2021Entry) + + +### statusList2021Entry.clone() ⇒ [StatusList2021Entry](#StatusList2021Entry) +Deep clones the object. + +**Kind**: instance method of [StatusList2021Entry](#StatusList2021Entry) + + +### statusList2021Entry.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [StatusList2021Entry](#StatusList2021Entry) + + +### StatusList2021Entry.fromJSON(json) ⇒ [StatusList2021Entry](#StatusList2021Entry) +Deserializes an instance from a JSON object. + +**Kind**: static method of [StatusList2021Entry](#StatusList2021Entry) + +| Param | Type | +| --- | --- | +| json | any | + + + +## Storage +A type wrapping a `JwkStorage` and `KeyIdStorage` that should always be used together when +working with storage backed DID documents. + +**Kind**: global class + +* [Storage](#Storage) + * [new Storage(jwkStorage, keyIdStorage)](#new_Storage_new) + * [.keyIdStorage()](#Storage+keyIdStorage) ⇒ KeyIdStorage + * [.keyStorage()](#Storage+keyStorage) ⇒ JwkStorage + + + +### new Storage(jwkStorage, keyIdStorage) +Constructs a new `Storage`. + + +| Param | Type | +| --- | --- | +| jwkStorage | JwkStorage | +| keyIdStorage | KeyIdStorage | + + + +### storage.keyIdStorage() ⇒ KeyIdStorage +Obtain the wrapped `KeyIdStorage`. + +**Kind**: instance method of [Storage](#Storage) + + +### storage.keyStorage() ⇒ JwkStorage +Obtain the wrapped `JwkStorage`. + +**Kind**: instance method of [Storage](#Storage) + + +## Timestamp +**Kind**: global class + +* [Timestamp](#Timestamp) + * [new Timestamp()](#new_Timestamp_new) + * _instance_ + * [.toRFC3339()](#Timestamp+toRFC3339) ⇒ string + * [.checkedAdd(duration)](#Timestamp+checkedAdd) ⇒ [Timestamp](#Timestamp) \| undefined + * [.checkedSub(duration)](#Timestamp+checkedSub) ⇒ [Timestamp](#Timestamp) \| undefined + * [.toJSON()](#Timestamp+toJSON) ⇒ any + * _static_ + * [.parse(input)](#Timestamp.parse) ⇒ [Timestamp](#Timestamp) + * [.nowUTC()](#Timestamp.nowUTC) ⇒ [Timestamp](#Timestamp) + * [.fromJSON(json)](#Timestamp.fromJSON) ⇒ [Timestamp](#Timestamp) + + + +### new Timestamp() +Creates a new [Timestamp](#Timestamp) with the current date and time. + + + +### timestamp.toRFC3339() ⇒ string +Returns the [Timestamp](#Timestamp) as an RFC 3339 `String`. + +**Kind**: instance method of [Timestamp](#Timestamp) + + +### timestamp.checkedAdd(duration) ⇒ [Timestamp](#Timestamp) \| undefined +Computes `self + duration` + +Returns `null` if the operation leads to a timestamp not in the valid range for [RFC 3339](https://tools.ietf.org/html/rfc3339). + +**Kind**: instance method of [Timestamp](#Timestamp) + +| Param | Type | +| --- | --- | +| duration | [Duration](#Duration) | + + + +### timestamp.checkedSub(duration) ⇒ [Timestamp](#Timestamp) \| undefined +Computes `self - duration` + +Returns `null` if the operation leads to a timestamp not in the valid range for [RFC 3339](https://tools.ietf.org/html/rfc3339). + +**Kind**: instance method of [Timestamp](#Timestamp) + +| Param | Type | +| --- | --- | +| duration | [Duration](#Duration) | + + + +### timestamp.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [Timestamp](#Timestamp) + + +### Timestamp.parse(input) ⇒ [Timestamp](#Timestamp) +Parses a [Timestamp](#Timestamp) from the provided input string. + +**Kind**: static method of [Timestamp](#Timestamp) + +| Param | Type | +| --- | --- | +| input | string | + + + +### Timestamp.nowUTC() ⇒ [Timestamp](#Timestamp) +Creates a new [Timestamp](#Timestamp) with the current date and time. + +**Kind**: static method of [Timestamp](#Timestamp) + + +### Timestamp.fromJSON(json) ⇒ [Timestamp](#Timestamp) +Deserializes an instance from a JSON object. + +**Kind**: static method of [Timestamp](#Timestamp) + +| Param | Type | +| --- | --- | +| json | any | + + + +## UnknownCredential +**Kind**: global class + +* [UnknownCredential](#UnknownCredential) + * _instance_ + * [.tryIntoJwt()](#UnknownCredential+tryIntoJwt) ⇒ [Jwt](#Jwt) \| undefined + * [.tryIntoCredential()](#UnknownCredential+tryIntoCredential) ⇒ [Credential](#Credential) \| undefined + * [.tryIntoRaw()](#UnknownCredential+tryIntoRaw) ⇒ Record.<string, any> \| undefined + * [.toJSON()](#UnknownCredential+toJSON) ⇒ any + * [.clone()](#UnknownCredential+clone) ⇒ [UnknownCredential](#UnknownCredential) + * _static_ + * [.fromJSON(json)](#UnknownCredential.fromJSON) ⇒ [UnknownCredential](#UnknownCredential) + + + +### unknownCredential.tryIntoJwt() ⇒ [Jwt](#Jwt) \| undefined +Returns a [Jwt](#Jwt) if the credential is of type string, `undefined` otherwise. + +**Kind**: instance method of [UnknownCredential](#UnknownCredential) + + +### unknownCredential.tryIntoCredential() ⇒ [Credential](#Credential) \| undefined +Returns a [Credential](#Credential) if the credential is of said type, `undefined` otherwise. + +**Kind**: instance method of [UnknownCredential](#UnknownCredential) + + +### unknownCredential.tryIntoRaw() ⇒ Record.<string, any> \| undefined +Returns the contained value as an Object, if it can be converted, `undefined` otherwise. + +**Kind**: instance method of [UnknownCredential](#UnknownCredential) + + +### unknownCredential.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [UnknownCredential](#UnknownCredential) + + +### unknownCredential.clone() ⇒ [UnknownCredential](#UnknownCredential) +Deep clones the object. + +**Kind**: instance method of [UnknownCredential](#UnknownCredential) + + +### UnknownCredential.fromJSON(json) ⇒ [UnknownCredential](#UnknownCredential) +Deserializes an instance from a JSON object. + +**Kind**: static method of [UnknownCredential](#UnknownCredential) + +| Param | Type | +| --- | --- | +| json | any | + + + +## VerificationMethod +A DID Document Verification Method. + +**Kind**: global class + +* [VerificationMethod](#VerificationMethod) + * _instance_ + * [.id()](#VerificationMethod+id) ⇒ [DIDUrl](#DIDUrl) + * [.setId(id)](#VerificationMethod+setId) + * [.controller()](#VerificationMethod+controller) ⇒ [CoreDID](#CoreDID) + * [.setController(did)](#VerificationMethod+setController) + * [.type()](#VerificationMethod+type) ⇒ [MethodType](#MethodType) + * [.setType(type_)](#VerificationMethod+setType) + * [.data()](#VerificationMethod+data) ⇒ [MethodData](#MethodData) + * [.setData(data)](#VerificationMethod+setData) + * [.properties()](#VerificationMethod+properties) ⇒ Map.<string, any> + * [.setPropertyUnchecked(key, value)](#VerificationMethod+setPropertyUnchecked) + * [.toJSON()](#VerificationMethod+toJSON) ⇒ any + * [.clone()](#VerificationMethod+clone) ⇒ [VerificationMethod](#VerificationMethod) + * _static_ + * [.newFromJwk(did, key, fragment)](#VerificationMethod.newFromJwk) ⇒ [VerificationMethod](#VerificationMethod) + * [.fromJSON(json)](#VerificationMethod.fromJSON) ⇒ [VerificationMethod](#VerificationMethod) + + + +### verificationMethod.id() ⇒ [DIDUrl](#DIDUrl) +Returns a copy of the [DIDUrl](#DIDUrl) of the [VerificationMethod](#VerificationMethod)'s `id`. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + +### verificationMethod.setId(id) +Sets the id of the [VerificationMethod](#VerificationMethod). + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| --- | --- | +| id | [DIDUrl](#DIDUrl) | + + + +### verificationMethod.controller() ⇒ [CoreDID](#CoreDID) +Returns a copy of the `controller` `DID` of the [VerificationMethod](#VerificationMethod). + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + +### verificationMethod.setController(did) +Sets the `controller` `DID` of the [VerificationMethod](#VerificationMethod) object. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| --- | --- | +| did | [CoreDID](#CoreDID) | + + + +### verificationMethod.type() ⇒ [MethodType](#MethodType) +Returns a copy of the [VerificationMethod](#VerificationMethod) type. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + +### verificationMethod.setType(type_) +Sets the [VerificationMethod](#VerificationMethod) type. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| --- | --- | +| type_ | [MethodType](#MethodType) | + + + +### verificationMethod.data() ⇒ [MethodData](#MethodData) +Returns a copy of the [VerificationMethod](#VerificationMethod) public key data. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + +### verificationMethod.setData(data) +Sets [VerificationMethod](#VerificationMethod) public key data. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| --- | --- | +| data | [MethodData](#MethodData) | + + + +### verificationMethod.properties() ⇒ Map.<string, any> +Get custom properties of the Verification Method. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + +### verificationMethod.setPropertyUnchecked(key, value) +Adds a custom property to the Verification Method. +If the value is set to `null`, the custom property will be removed. + +### WARNING +This method can overwrite existing properties like `id` and result +in an invalid Verification Method. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| --- | --- | +| key | string | +| value | any | + + + +### verificationMethod.toJSON() ⇒ any +Serializes this to a JSON object. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + +### verificationMethod.clone() ⇒ [VerificationMethod](#VerificationMethod) +Deep clones the object. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + +### VerificationMethod.newFromJwk(did, key, fragment) ⇒ [VerificationMethod](#VerificationMethod) +Creates a new [VerificationMethod](#VerificationMethod) from the given `did` and [Jwk](#Jwk). If `fragment` is not given +the `kid` value of the given `key` will be used, if present, otherwise an error is returned. + +### Recommendations +The following recommendations are essentially taken from the `publicKeyJwk` description from the [DID specification](https://www.w3.org/TR/did-core/#dfn-publickeyjwk): +- It is recommended that verification methods that use `Jwks` to represent their public keys use the value of + `kid` as their fragment identifier. This is +done automatically if `None` is passed in as the fragment. +- It is recommended that [Jwk](#Jwk) kid values are set to the public key fingerprint. + +**Kind**: static method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| --- | --- | +| did | [CoreDID](#CoreDID) \| IToCoreDID | +| key | [Jwk](#Jwk) | +| fragment | string \| undefined | + + + +### VerificationMethod.fromJSON(json) ⇒ [VerificationMethod](#VerificationMethod) +Deserializes an instance from a JSON object. + +**Kind**: static method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| --- | --- | +| json | any | + + + +## CredentialStatus +**Kind**: global variable + + +## StatusPurpose +Purpose of a [StatusList2021](#StatusList2021). + +**Kind**: global variable + + +## StateMetadataEncoding +**Kind**: global variable + + +## MethodRelationship +**Kind**: global variable + + +## StatusCheck +Controls validation behaviour when checking whether or not a credential has been revoked by its +[`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status). + +**Kind**: global variable + + +## Strict +Validate the status if supported, reject any unsupported +[`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) types. + +Only `RevocationBitmap2022` is currently supported. + +This is the default. + +**Kind**: global variable + + +## SkipUnsupported +Validate the status if supported, skip any unsupported +[`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) types. + +**Kind**: global variable + + +## SkipAll +Skip all status checks. + +**Kind**: global variable + + +## SubjectHolderRelationship +Declares how credential subjects must relate to the presentation holder. + +See also the [Subject-Holder Relationship](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships) section of the specification. + +**Kind**: global variable + + +## AlwaysSubject +The holder must always match the subject on all credentials, regardless of their [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property. +This variant is the default. + +**Kind**: global variable + + +## SubjectOnNonTransferable +The holder must match the subject only for credentials where the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property is `true`. + +**Kind**: global variable + + +## Any +The holder is not required to have any kind of relationship to any credential subject. + +**Kind**: global variable + + +## FailFast +Declares when validation should return if an error occurs. + +**Kind**: global variable + + +## AllErrors +Return all errors that occur during validation. + +**Kind**: global variable + + +## FirstError +Return after the first error occurs. + +**Kind**: global variable + + +## verifyEd25519(alg, signingInput, decodedSignature, publicKey) +Verify a JWS signature secured with the `EdDSA` algorithm and curve `Ed25519`. + +This function is useful when one is composing a `IJwsVerifier` that delegates +`EdDSA` verification with curve `Ed25519` to this function. + +# Warning + +This function does not check whether `alg = EdDSA` in the protected header. Callers are expected to assert this +prior to calling the function. + +**Kind**: global function + +| Param | Type | +| --- | --- | +| alg | JwsAlgorithm | +| signingInput | Uint8Array | +| decodedSignature | Uint8Array | +| publicKey | [Jwk](#Jwk) | + + + +## encodeB64(data) ⇒ string +Encode the given bytes in url-safe base64. + +**Kind**: global function + +| Param | Type | +| --- | --- | +| data | Uint8Array | + + + +## decodeB64(data) ⇒ Uint8Array +Decode the given url-safe base64-encoded slice into its raw bytes. + +**Kind**: global function + +| Param | Type | +| --- | --- | +| data | Uint8Array | + + + +## start() +Initializes the console error panic hook for better error messages + +**Kind**: global function diff --git a/docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx b/docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx new file mode 100644 index 00000000000..684653b175f --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx @@ -0,0 +1,263 @@ +--- +title: IOTA DID Method Specification v1.0 +sidebar_label: DID Method +description: How IOTA Identity implements the Decentralized Identifiers Standard on the IOTA Tangle. +image: /img/Identity_icon.png +keywords: + - DID + - specs + - specifications + - Decentralized Identifiers + - Tangle + - format +--- + +# IOTA DID Method Specification v1.0 + +2023-08-23 + +## Abstract + +The IOTA DID Method Specification describes a method of implementing the [Decentralized Identifiers](https://www.w3.org/TR/did-core/) (DID) standard on [IOTA](https://iota.org), a Distributed Ledger Technology (DLT). It conforms to the [DID specification v1.0](https://www.w3.org/TR/did-core/) and describes how to perform Create, Read, Update and Delete (CRUD) operations for IOTA DID Documents using unspent transaction outputs (_UTXO_) on the IOTA and [Shimmer](https://shimmer.network/) networks, introduced with the [Stardust upgrade](https://blog.shimmer.network/stardust-upgrade-in-a-nutshell/). + +## Data Types & Subschema Notation + +Data types and subschemas used throughout this TIP are defined in [TIP-21](https://github.com/iotaledger/tips/blob/v1.1.0/tips/TIP-0021/tip-0021.md). + +## Introduction + +### UTXO Ledger + +The unspent transaction output ([UTXO](/tips/tips/TIP-0020/)) model defines a ledger state which is comprised of unspent outputs. Outputs are created by a transaction consuming outputs of previous transactions as inputs. The Stardust version of the protocol defines several output types, the relevant ones for the IOTA DID Method are: Basic Outputs for _value transactions_, and Alias Outputs for storage of DID Documents. + +All outputs must hold a minimum amount of tokens to be stored on the ledger. For output types that can hold arbitrary data, for instance the Alias Output, the amount of tokens held by the output must cover the byte cost of the data stored. This prevents the ledger size from growing uncontrollably while guaranteeing that the data is not pruned from the nodes, which is important for resolving DID Documents. This deposit is fully refundable and can be reclaimed when the output is destroyed. + +Data stored in an output and covered by the storage deposit will be stored in _all_ nodes on the network and can be retrieved from any node. This provides strong guarantees for any data stored in the ledger. + +### Alias Output + +The [Alias Output](https://github.com/iotaledger/tips/blob/v1.1.0/tips/TIP-0018/tip-0018.md#alias-output) is a specific implementation of the [UTXO state machine](https://github.com/iotaledger/tips/blob/v1.1.0/tips/TIP-0018/tip-0018.md#chain-constraint-in-utxo). Some of its relevant properties are: + +- **Amount**: the amount of IOTA coins held by the output. +- **Alias ID**: 32 byte array, a unique identifier of the alias, which is the BLAKE2b-256 hash + of the Output ID that created it. +- **State Index**: A counter that must increase by 1 every time the alias is state transitioned. +- **State Metadata**: Dynamically sized array of arbitrary bytes with a length up to `Max Metadata Length`, as defined in [TIP-22](https://github.com/iotaledger/tips/blob/v1.1.0/tips/TIP-0022/tip-0022.md). Can only be changed by the state controller. +- **Unlock Conditions**: + - State Controller Address Unlock Condition + - Governor Address Unlock Condition + +Consuming an Alias Output in a transaction may transition it into the next state. The current state is defined as the consumed Alias Output, while the next state is defined as the **Alias Output with the same explicit `Alias ID` on the output side**. There are two types of transitions: `state transition` and `governance transition`. + +All outputs include an `Unlock Conditions` property. This feature defines how the output can be unlocked and spent. The Alias Output supports two types of unlock conditions that can be set: the state controller and governor. Each of these can be either an Ed25519 Address, Alias Address or an NFT Address. An Alias Output can have at most one of each unlock condition. + +The state controller can unlock a state transition. It is identified by an incremented `State Index` and can change the fields `Amount`, `State Index`, `State Metadata` among other properties. + +The governor, on the other hand, can unlock a governance transition indicated by an unchanged `State Index`. A governance transition can change the addresses of the state controller and governor. It also allows destroying the Alias Output. + +### Ledger and DID + +Storing DID Documents in the ledger state means they inherently benefit from the guarantees the ledger provides. + +1. Conflicts among nodes are resolved and dealt with by the ledger. +2. Replay attacks are mitigated since transactions need to be confirmed by the ledger. +3. Through the `State Index` a linear history for updates of a DID Document is provided. + +## DID Method Name + +The `method-name` to identify this DID method is: `iota`. + +A DID that uses this method MUST begin with the following prefix: `did:iota`. Following the generic DID specification, this string MUST be lowercase. + +## DID Format + +The DIDs that follow this method have the following ABNF syntax. It uses the syntax in [RFC5234](https://www.rfc-editor.org/rfc/rfc5234) and the corresponding definition for `digit`. + +``` +iota-did = "did:iota:" iota-specific-idstring +iota-specific-idstring = [ iota-network ":" ] iota-tag +iota-network = 1*6network-char +iota-tag = "0x" 64lowercase-hex +lowercase-hex = digit / "a" / "b" / "c" / "d" / "e" / "f" +network-char = %x61-7A / digit ; corresponds to the character range from "a" to "z" and "0" to "9". +``` + +It starts with the string "did:iota:", followed by an optional network name (1 to 6 lowercase alpha characters) and a colon, then the tag. +The tag starts with "0x" followed by a hex-encoded `Alias ID` with lower case a-f. + +### IOTA-Network + +The iota-network is an identifier of the network where the DID is stored. This network must be an IOTA Ledger, but can either be a public or private network, permissionless or permissioned. + +The following values are reserved and cannot reference other networks: + +1. `iota` references the main network which refers to the ledger known to host the IOTA cryptocurrency. +2. `atoi` references the development network of IOTA. +3. `smr` references the shimmer network. +4. `rms` references the development network of Shimmer. + +When no IOTA network is specified, it is assumed that the DID is located on the `iota` network. This means that the following DIDs will resolve to the same DID Document: + +``` +did:iota:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe +did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe +``` + +### IOTA-Tag + +An IOTA-tag is a hex-encoded `Alias ID`. The `Alias ID` itself is a unique identifier of the alias, which is the BLAKE2b-256 hash of the Output ID that created it. +This tag identifies the Alias Output where the DID Document is stored, and it will not be known before the generation of the DID since it will be assigned when the Alias Output is created. + +### Anatomy of the State Metadata + +In the `State Metadata` of the Alias Output must be a byte packed payload with header fields as follows: + +| Name | Type | Description | +| ------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Document Type | ByteArray[3] | Set to value **DID** to denote a DID Document. | +| Version | uint8 | Set value **1** to denote the version number of this method | +| Encoding | uint8 | Set to value to **0** to denote JSON encoding without compression. | +| Payload | (uint16)ByteArray | A DID Document and its metadata, where every occurrence of the DID in the document is replaced by `did:0:0`. It must be encoded according to `Encoding`. | + +The types are defined in [TIP-21](/tips/tips/TIP-0021/#data-types). + +#### Payload + +The payload must contain the following fields: + +- `meta`: contains metadata about the DID Document. For example, `created` to indicate the time of + creation, and `updated` to indicate the time of the last update to the document. It may also include other properties. +- `doc`: contains the DID Document. In the example below, the document only contains one verification method. The `id` and `controller` is specified by `did:0:0` which references the DID of the document itself, since the DID is unknown at the time of publishing. It also deduplicates the DID of the document to reduce the size of the state metadata, in turn reducing the required storage deposit. + +Example State Metadata Document: + +```json +{ + "doc": { + "id": "did:0:0", + "verificationMethod": [ + { + "id": "did:0:0#jkGOGVO3Te7ADpvlplr47eP9ucLt41zm", + "controller": "did:0:0", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "jkGOGVO3Te7ADpvlplr47eP9ucLt41zm", + "crv": "Ed25519", + "x": "D5w8vG6tKEnpBAia5J4vNgLID8k0BspHz-cVMBCC3RQ" + } + } + ], + "authentication": ["did:0:0#jkGOGVO3Te7ADpvlplr47eP9ucLt41zm"] + }, + "meta": { + "created": "2023-08-28T14:49:37Z", + "updated": "2023-08-28T14:50:27Z" + } +} +``` + +## Controllers + +A state controller can directly update the DID Document and the amount of tokens held by the Alias Output, but it cannot destroy the output. A governor, on the other hand, can indirectly update the DID Document by updating the state controller. The governor can also destroy the output by performing a governance transition without producing an Alias Output with the same `Alias ID`. + +As of now, only one state controller and one governor can be set for an Alias Output. Support for multiple controllers may be possible depending on future updates of the protocol. + +## CRUD Operations + +Create, Read, Update and Delete (CRUD) operations that change the DID Documents are done through state or governance transitions of the Alias Output. + +**These operations require fund transfer to cover byte cost. Transactions must be carefully done in order to avoid fund loss.** For example, the amount of funds in the inputs should equal these in the outputs. Additionally, private keys of controllers must be stored securely. + +### Create + +In order to create a simple self controlled DID two things are required: + +1. An Ed25519 Address for which the private key is available, or control over an Alias or NFT Output. +2. A Basic, Alias or NFT Output with enough coins to cover the byte cost. + +Creation steps: + +1. Create the content of the DID Document like verification methods, services, etc. +2. Create the payload and the headers as described in the [Anatomy of the State Metadata](#anatomy-of-the-state-metadata). +3. Create a new Alias Output with the payload and the headers stored in its `State Metadata`. +4. Set the state controller and the governor unlock conditions to the addresses that should control state and governance transitions, respectively. +5. Set enough tokens in the output to cover the byte cost. +6. Publish a new transaction with an existing output that contains at least the storage deposit from step 6 as input, and the newly created Alias Output as output. + +Once the transaction is confirmed, the DID is published and can be formatted by using the `Alias ID` as the tag in [DID Format](#did-format). + +### Read + +The following steps can be used to read the latest DID Document associated with a DID. + +1. Obtain the `Alias ID` from the DID by extracting the `iota-tag` from the DID, see [DID Format](#did-format). +2. Obtain the network of the DID by extracting the `iota-network` from the DID, see [DID Format](#did-format). +3. Query the Alias Output corresponding to the `Alias ID` using a node running the [inx indexer](https://github.com/iotaledger/inx-indexer). Nodes usually include this indexer by default. +4. Assert that the extracted network matches the one returned from the node. Return an error otherwise. +5. Assert that the `Alias ID` of the returned output matches the `Alias ID` extracted from the DID. Return an error otherwise. +6. Retrieve the value of the `State Metadata` field from the returned output. +7. Validate the contents match the structure described in [Anatomy of the State Metadata](#anatomy-of-the-state-metadata). Return an error otherwise. +8. Decode the DID Document from the `State Metadata`. +9. Replace the placeholder `did:0:0` with the DID given as input. + +### Update + +Updating a DID Document can be achieved by the state controller performing a state transition of the Alias Output with the updated content: + +1. Create a copy of the Alias Output with the `Alias ID` set explicitly. +2. Pack the updated DID Document, as described in the [Anatomy of the State Metadata](#anatomy-of-the-state-metadata), into the `State Metadata` of the output. +3. Increment the `State Index`. +4. Set the `amount` of coins sufficient to cover the byte cost. +5. Publish a new transaction that includes the current Alias Output as input (along with any required Basic Outputs to consume to cover the `amount`, if increased) and the updated one as output. If the state controller unlock of the Alias Output references other Alias or NFT Outputs, those outputs must be unlocked in the same transaction, recursively. + +### Delete + +#### Deactivate + +Temporarily deactivating a DID can be done by deleting the contents of the `State Meadata` in the Alias Output, setting it to an empty byte array, and publishing an [update](#update). + +Another option is to [update](#update) the DID Document and set the `deactivated` property in its `metadata` to true. In both cases, the deactivated DID Document will be marked as `deactivated` when resolved. + +#### Destroy + +In order to permanently destroy a DID, a new transaction can be published by the governor that consumes the Alias Output without having a corresponding Alias Output on the output side with the same explicit `Alias ID`. This results in destroying the Alias Output and the DID. + +Note that this operation irreversibly and irrecoverably deletes the DID. This is because the `Alias ID` from which an IOTA DID is derived (see [IOTA-Tag](#iota-tag)) is generated from the hash of the input transaction that created it, which cannot generally be replicated. + +## IOTA Identity standards + +The `did:iota` method is implemented in the [IOTA Identity framework](https://github.com/iotaledger/identity.rs). This framework supports a number of operations that are standardized, some are standardized across the SSI community, and some are the invention of the IOTA Foundation. + +### Revocation + +Revocation of verifiable credentials and signatures can be achieved using the [Revocation Bitmap 2022](./revocation-bitmap-2022.mdx) where issuers store a bitmap of indices in the DID Document. These indices correspond to verifiable credentials they have issued. If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked. + +### Standardized Services + +The IOTA Identity framework also standardized certain `services` that are embedded in the DID Document. It is RECOMMENDED to implement these when implementing the `did:iota` method. + +Currently standardized `services`: + +- [Revocation Bitmap Service](./revocation-bitmap-2022.mdx#revocation-bitmap-service) + +## Security Considerations + +The `did:iota` method is implemented on the [IOTA](https://iota.org), a public permissionless and feeless Distributed Ledger Technology (DLT), making it resistant against almost all censorship attack vectors. Up until the `Coordicide` update for the IOTA network, a dependency on the coordinator exists for resolving ordering conflicts. This has a minor censorship possibility, that, in the worst case, can prevent transactions from getting confirmed. + +### Private Key Management + +All private keys or seeds used for the `did:iota` method should be equally well protected by the users. Private keys of the state controller and the governor are especially important as they control how keys are added or removed, providing full control over the identity. The IOTA Identity framework utilizes the [Stronghold project](https://github.com/iotaledger/stronghold.rs), a secure software implementation isolating digital secrets from exposure to hacks or leaks. Developers may choose to add other ways to manage the private keys in a different manner. + +## Privacy Considerations + +### Personal Identifiable Information + +The public IOTA and Shimmer networks are immutable. This means that once something is included, it can never be completely removed. For example, destroying an Alias Output will remove it from the ledger state, but it can still be stored in permanodes or by any party that records historical ledger states. + +That directly conflicts with certain privacy laws such as GDPR, which have a 'right-to-be-forgotten' for Personal Identifiable Information (PII). As such, users should NEVER upload any PII, including inside DID Documents. While verifiable credentials can be made public, this should only be utilized by Identity for Organisations and Identity for Things. + +### Correlation Risks + +As with any DID method, identities can be linked if they are used too often and their usage somehow becomes public. See [DID Correlation Risks](https://www.w3.org/TR/did-core/#did-correlation-risks). Additionally, a DID can be correlated with funds if the Alias Output used to store the DID Document or any of its controllers is used for holding, transferring or controlling coins or NFTs. diff --git a/docs/build/identity.rs/1.1/docs/references/specifications/overview.mdx b/docs/build/identity.rs/1.1/docs/references/specifications/overview.mdx new file mode 100644 index 00000000000..8ffb0951bd7 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/references/specifications/overview.mdx @@ -0,0 +1,15 @@ +--- +title: Specifications Overview +sidebar_label: Overview +description: Provide overview of the specifications +image: /img/Identity_icon.png +keywords: + - specifications +--- + +While IOTA Identity implements many existing standards, it also adds some additional features we would like to standardize ourselves. This section covers these features and how they work in great detail. These are not light reads and can be skipped. + +The current specifications are: + +- [IOTA DID](iota-did-method-spec.mdx): The specification for the IOTA DID Method implemented on the _Tangle_. +- [Revocation Bitmap 2022](revocation-bitmap-2022.mdx): The specification for an on-Tangle credential revocation mechanism. diff --git a/docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx b/docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx new file mode 100644 index 00000000000..f559ce5f12a --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx @@ -0,0 +1,201 @@ +--- +title: Revocation Bitmap +sidebar_label: Revocation Bitmap +description: The specification for the embedded revocation bitmap. +image: /img/Identity_icon.png +keywords: + - DID + - specs + - specifications + - revocation + - bitmap +--- + +# Revocation Bitmap 2022 + +## Abstract + +This specification describes a mechanism for publishing the revocation status of [verifiable credentials](../../explanations/verifiable-credentials.mdx) embedded in an issuer's DID document. + +## Introduction + +Revocation gives an issuer the capability to invalidate a credential they issued before its natural expiration date. To achieve this, issuers can embed an identifier in the `credentialStatus` field of a credential. Verifiers can then lookup that identifier in a separate list, to check whether the credential is still valid. This document specifies a mechanism of embedding such a list, in form of a bitmap, in the DID document of the issuer, where each bitmap index corresponds to a credential they have issued. This mechanism is space-efficient and enables a verifier to check a credential's status in a privacy-preserving manner and without requiring additional lookups or external resources. + +## Revocation Bitmap Concept + +The revocation status of a verifiable credential is expressed as a binary value. The issuer keeps a bitmap of indices corresponding to verifiable credentials they have issued. If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked. + +## Data Model + +### Revocation Bitmap Status + +For an issuer to enable verifiers to check the status of a verifiable credential, the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) property MUST be specified with the following properties: + +| Property | Description | +| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | The constraints on the `id` property are listed in the [Verifiable Credentials Data Model specification](https://www.w3.org/TR/vc-data-model/). The `id` MUST be a [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) that is the URL to a [Revocation Bitmap Service](#revocation-bitmap-service) in the DID Document of the issuer. It SHOULD include an `index` query set to the same value as `revocationBitmapIndex`, to uniquely identify the `credentialStatus`. If the `index` query is present, implementations SHOULD reject statuses where the `index` query's value does not match `revocationBitmapIndex`. | +| `type` | The `type` property MUST be `"RevocationBitmap2022"`. | +| `revocationBitmapIndex` | The `revocationBitmapIndex` property MUST be an unsigned, 32-bit integer expressed as a string. This is the index of the credential in the issuer's revocation bitmap. Each index SHOULD be unique among all credentials linking to the same [Revocation Bitmap Service](#revocation-bitmap-service). | + +#### Example + +An example of a verifiable credential with a `credentialStatus` of type `RevocationBitmap2022`. + +```json +{ + "@context": "https://www.w3.org/2018/credentials/v1", + "id": "https://example.edu/credentials/3732", + "type": ["VerifiableCredential", "UniversityDegreeCredential"], + "credentialSubject": { + "id": "did:iota:B8DucnzULJ9E8cmaReYoePU2b7UKE9WKxyEVov8tQA7H", + "GPA": "4.0", + "degree": "Bachelor of Science and Arts", + "name": "Alice" + }, + "issuer": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", + "issuanceDate": "2022-06-13T08:04:36Z", + "credentialStatus": { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw?index=5#revocation", + "type": "RevocationBitmap2022", + "revocationBitmapIndex": "5" + }, + "proof": { + "type": "JcsEd25519Signature2020", + "verificationMethod": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#key-1", + "signatureValue": "2eHdbDumMrer4pNVkaiYMqsVqVp2adq7bRcgTJZiw17Zeghk2ZT49YHwLwCCg35YKganBhxP6YSbzYoBK1AuCUv" + } +} +``` + +### Revocation Bitmap Service + +To allow verifiers to check the status of a [Revocation Bitmap Status](#revocation-bitmap-status), the DID document of the credential issuer MUST contain a [service](https://www.w3.org/TR/did-core/#services) with the following properties: + +| Property | Description | +| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | The constraints on the `id` property are listed in the [DID Core service specification](https://www.w3.org/TR/did-core/#services). The `id` property MUST be a DID URL uniquely identifying the revocation bitmap. | +| `type` | The `type` property MUST be `"RevocationBitmap2022"`. | +| `serviceEndpoint` | The `serviceEndpoint` MUST be generated according to the [service endpoint generation algorithm](#service-endpoint-generation-algorithm). | + +#### Example + +An example of an issuer's DID document where credential `"5"` in the `#revocation` service is revoked: + +```json +{ + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", + "verificationMethod": [ + { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#key-1", + "controller": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", + "type": "Ed25519VerificationKey2018", + "publicKeyMultibase": "z3hgM9fNkhwgT5mECbj1HdKoFNZgpffwQYEV8WBVHphXq" + } + ], + "capabilityInvocation": [ + { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#sign-0", + "controller": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", + "type": "Ed25519VerificationKey2018", + "publicKeyMultibase": "z83F6zbD3KqaxvQhqo25LvSXzoDdpZmp3EpPVonSVACwZ" + } + ], + "service": [ + { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", + "type": "RevocationBitmap2022", + "serviceEndpoint": "data:application/octet-stream;base64,ZUp5ek1tQmdZR1NBQUFFZ1ptVUFBQWZPQUlF" + } + ] +} +``` + +## Algorithms + +The following algorithms define how to generate, expand and validate revocation bitmaps. + +### Service Endpoint Generation Algorithm + +The following process MUST be followed when producing a `RevocationBitmap2022` to embed in a service endpoint: + +1. Let **bitmap** be a [_roaring bitmap_](https://roaringbitmap.org/) where each bit is initialized to 0. +2. For each revoked credential with an **index** not exceeding an unsigned, 32-bit integer, set the corresponding bit in **bitmap** at **index** to 1. +3. Generate the **bitmap serialization** according to the [roaring bitmap serialization format](https://github.com/RoaringBitmap/RoaringFormatSpec/) using the **bitmap** as input. +4. Generate a **compressed bitmap** by using the ZLIB compression algorithm [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)] on the **bitmap serialization** and base64-encoding [[RFC4648](https://datatracker.ietf.org/doc/html/rfc4648)] the result. +5. Create the **service endpoint** by embedding the **compressed bitmap** in a data URL [[RFC2397](https://datatracker.ietf.org/doc/html/rfc2397)]. On the data url, the `` MUST be `application/octet-stream` and the `base64` attribute MUST be set. +6. Return the **service endpoint**. + +### Service Endpoint Expansion Algorithm + +The following process MUST be followed when expanding the endpoint from a service of type `RevocationBitmap2022`: + +1. Let **service endpoint** be a data url generated using the [service endpoint generation algorithm](#service-endpoint-generation-algorithm). +2. The `` of the **service endpoint** MUST be `application/octet-stream` and the `base64` attribute MUST be set, return an error otherwise. Let **compressed bitmap** be the `` part of the data url. +3. Generate an **uncompressed bitmap** by base64-decoding [[RFC4648](https://datatracker.ietf.org/doc/html/rfc4648)] the **compressed bitmap** and then decompressing the result using ZLIB [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)]. +4. Generate the **bitmap** by deserializing the **uncompressed bitmap** according to the [roaring bitmap serialization format](https://github.com/RoaringBitmap/RoaringFormatSpec/). +5. Return the **bitmap**. + +### Validation Algorithm + +The following steps MUST be followed when checking whether a verifiable credential is revoked: + +1. Let **credential** be a verifiable credential containing a `credentialStatus` whose `type` is `RevocationBitmap2022`. +2. Let **revocation bitmap URL** be the `id` field of the **credential**'s `credentialStatus`. +3. Resolve the **revocation bitmap URL** to a **revocation bitmap service** in the issuer's DID document, and verify that the service `type` is `RevocationBitmap2022`. Return an error otherwise. +4. Expand the endpoint of the **revocation bitmap service** into a **revocation bitmap** according to the [service endpoint expansion algorithm](#service-endpoint-expansion-algorithm). +5. Let **revocation index** be the integer value of the `revocationBitmapIndex` property contained in the `credentialStatus` of the **credential**. +6. Let **revoked** be the value of the bit at index **revocation index** in the **revocation bitmap**. +7. Return `true` if **revoked** is 1, `false` otherwise. + +## Test Vectors + +This section provides test vectors to validate implementations against. + +### Test Vector 1 + +The following data URL decodes to a bitmap of length 0 where no index is revoked: + +`"data:application/octet-stream;base64,ZUp5ek1tQUFBd0FES0FCcg=="` + +### Test Vector 2 + +The following data URL decodes to a bitmap of length 3 where indices `5`, `398`, and `67000` are revoked: + +`"data:application/octet-stream;base64,ZUp5ek1tQmdZR0lBQVVZZ1pHQ1FBR0laSUdabDZHUGN3UW9BRXVvQjlB"`. + +### Test Vector 3 + +The following data URL decodes to a bitmap of length 16384 where all indices are revoked: + +`"data:application/octet-stream;base64,ZUp6dHhERVJBQ0FNQkxESEFWS1lXZkN2Q3E0MmFESmtyMlNrM0ROckFLQ2RBQUFBQUFBQTMzbGhHZm9q"` + +## Rationale + +This section describes the rationale behind some of the design decisions of this specification. + +### Compression and maximum size + +Considering that messages published to the Tangle cannot exceed [32 KiB](https://github.com/iotaledger/tips/blob/v1.1.0/tips/TIP-0006/tip-0006.md#message-validation) in size, and that larger messages have increased requirements, the use of compression was assessed. +The precise size of a serialized bitmap varies based on the number and distribution of revoked indices. When indices are revoked uniformly randomly, roughly 100,000 - 200,000 can be achieved in a DID Document with compression, and significantly more if consecutive indices are revoked. + +ZLIB [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)] was chosen for having a free and open source software licence and being one of the most widely used compression schemes, which enhances the accessibility of this specification. Some other assessed algorithms produced only marginally better compression ratios but had far fewer existing implementations across different programming languages. + +### Compressed Bitstring vs. Roaring Bitmap + +Because of its space efficiency, a roaring bitmap is preferred for representing a bitmap in-memory. To avoid the dependency on roaring bitmap, we considered using a compressed bitstring as the serialization format. However, serialization of such a bitstring was 2-3x slower compared to roaring's serialization format, which becomes an issue on resource-constrained devices (e.g. smartphones) or in web browsers. + +### Comparison to `RevocationList2020` and `StatusList2021` + +The [RevocationList2020 specification](https://w3c-ccg.github.io/vc-status-rl-2020/) and [StatusList2021 specification](https://w3c-ccg.github.io/vc-status-list-2021/) both describe a similar revocation mechanism using a verifiable credential that contains a bitmap, similar to the `RevocationBitmap2022` approach. The credential is hosted outside of the DID document and the verifier thus needs to fetch it from an external resource, likely one controlled by the issuer. This has privacy implications as the issuer can track where a fetch request for the credential came from and potentially infer who the credential was verified by and for what purpose. The issuer can also potentially infer which credential was checked. Because `RevocationBitmap2022` is embedded in the issuer's DID document, which can be obtained without the their knowledge, this approach does not suffer from these privacy shortcomings. See also the [privacy considerations](#privacy-considerations). + +A downside of embedding the revocation list in the DID document is that storage in a distributed ledger (DLT) is usually more expensive than other storage hosting solutions. The DLT might also impose message size limitations, capping the total number of revocations that can be done (see also [compression](#compression)). + +Another difference is that `RevocationList2020` specifies a minimum initial size of 131,072 for its bitstring, to mitigate the potential for correlating individuals when few credentials have been issued. `RevocationBitmap2022` uses a roaring bitmap instead of a bitstring, so the maximum size is not fixed (apart from the upper bound of an unsigned 32-bit integer). This means the bitmap cannot be used to correlate small populations without more information not present in the bitmap itself. However, both schemes still reveal publicly how many credentials have been revoked, which could be used to infer other information if more knowledge about how an issuer assigns credential revocation indexes is known. + +`StatusList2021` allows for explicitly stating the purpose of the list, currently either _revocation_ or _suspension_. This specification does not mandate that revoked credentials cannot be unrevoked, which means a `RevocationBitmap2022` can effectively also be used as a suspension list. + +### Privacy Considerations + +Because the revocation bitmap is embedded in the DID document, and thus available without contacting the issuer directly, the issuer cannot correlate how a holder uses their credential. + +An observer finding a service of type `RevocationBitmap2022` in a DID document can infer that this DID belongs to an issuer. However, DIDs of issuers tend to be publicly known, in contrast to DIDs of other entities, so this is unlikely to present an issue. External observers can monitor the frequency of revocations and potentially the total number of issued credentials, depending on how the issuer assigns credential indices (e.g. starting from 0 and incrementing the index for each issued credential). diff --git a/docs/build/identity.rs/1.1/docs/welcome.mdx b/docs/build/identity.rs/1.1/docs/welcome.mdx new file mode 100644 index 00000000000..d3290fdab86 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/welcome.mdx @@ -0,0 +1,91 @@ +--- +description: The most important concepts that developers will need to know to utilize IOTA Identity to its full potential. +image: /img/Identity_icon.png +keywords: + - Identity + - guide + - TOC + - overview + - reference +--- +# IOTA Identity Framework + +![IOTA Identity](/img/banner/banner_identity.svg) + +The IOTA Identity framework implements the most common standards and patterns for Decentralized Identity in both a DLT agnostic and `iota` method-specific manner. +It is designed to work for Identity for [People](#identity-for-people), [Organizations](#identity-for-organizations), +[Things, and Objects](#identity-for-things) acting as a unifying layer of trust between everyone and everything. + +## Introduction to Decentralized Identity + +Decentralized or Self-Sovereign Identity (SSI) gives individuals full control over their online identity, +offering a remedy for database breaches, lack of digital trust, and stringent privacy laws like GDPR. +Digital identity bridges the gap between online pseudonyms and real-world personas, enabling true verifiable identities. This gives individuals the power to choose which data to share and with whom. + + + +### Identity for People + +:::info Privacy + +IOTA Identity builds a new internet, without usernames, passwords, endless repeated forums, or uncontrolled data harvesting. + +::: + +Information about anyone's life is spread across many locations. Most people have numerous unorganized important documents at home, hundreds of online accounts, and many more online footprints. Through statistical predictive analysis, computer programs can harvest unverified online information sources and create a reasonably accurate profile about our lives. These profiles are accurate enough for targeted advertising and personalized content but lack the proof and trust for them to be used in business. This results in an antiquated customer experience where we have to submit our age and address for every purchase we make and every account we create. It also inhibits our ability to do many online tasks like requesting and extending licenses or taking out a mortgage. + +Self-Sovereign Identity is about returning autonomy and privacy to the individual, while also improving our online experience. Some movements focus on data privacy, preventing companies from using our information altogether, but with the IOTA Identity framework you control which part of the information you want to reveal. The user can create a single online profile containing all our personal information. They can decide who they share what information with, and a verifier checks if the information is correct, making the data trustworthy. This moves their online profile from a statistical estimation by corporate entities to an accurate and verifiable profile under their own control. + +IOTA Identity allows a new internet without usernames, passwords, endlessly repeated forms or data harvesting. Users have ultimate control and can choose to supply service providers with their personal data, who in return provide personalized experiences. Data will still flow, and perhaps even more than before, but it will always be in the individual's interest instead of a corporation's. People will gain additional benefits in sharing their data, either in monetary value or improved customer experience. This system is impossible in non-neutral environments such as permissioned or fee-based ledgers. + +Governmental mechanisms for building _digital identities_ are currently being established throughout Europe and Asia, with demand increasing around the globe. However, they are managed by single entities and restricted to the governments that created them. By decentralizing a framework for these standards to adapt to, we have a system for intergovernmental verification of individuals and devices. A person’s digital identification will be transferable across borders like a passport. However, it will no longer require the trust of the issuing government due to the digital trust established by the open and auditable system. + +### Identity for Organizations + +:::info GDPR + +IOTA Identity allows organizations to comply with GDPR in a cost-efficient and privacy-enabling manner + +::: + +Corporations are associated with greed and abuse of power. This reputation stems from the role some have chosen to take within society. Corporations are trusted with our data, but often do not act responsibly; vulnerability, fix, patch, repeat. In software and systems, we have seen this cycle repeat. Headlines on data leaks are now an ever-present feature in the news. + +IOTA Identity presents an opportunity for companies to embrace a new role in the ecosystem. Traditional approaches do not provide cost-efficient solutions to new legislation like GDPR. IOTA Identity enables organizations to change their processes to comply with the new regulations in a cost-efficient and privacy-enabling manner. Features of “Data Protection and Privacy by Design” shift responsibility over Personal Identifiable Information (PII) from organization to customer, and organizations no longer need to store that data. The relationship between customer and organization is also tightened as communication via a third-party Identity provider like Google or Facebook is no longer needed. + +Due to Know-Your-Customer (KYC) and Anti-Money Laundering (AML) obligations, companies can be certain who their customers are. These services also provide unique insight into their customers’ data. These insights can be combined and translated into verifiable credentials, providing a new “Trust Anchor” service with the potential for new business models. KYC and AML credentials would return the autonomy of personal data to the customer. Once companies accept other companies' KYC and AML credentials, the enrollment time for new customers is significantly reduced, as are the costs. With the personal data secured by the customer, companies can afford to store less data in their databases, reducing risk and responsibility and fulfilling the goals of legislation such as GDPR. + +Organizations that have their own decentralized identities can also combat fraud and increase control over their online brand. Companies can sign invoices and agreements using their decentralized identities. While interacting with the customers, they will also be able to reliably identify themselves. + +### Identity for Things + +:::info TRUST + +IOTA Identity adds the missing key ingredient for the "Economy of Things": Trust. + +::: + +With Identity of Things (IDoT), devices are provided with a unique global identity that are able to prove many attributes, including their capabilities, specifications, and authenticity. People, organizations, and other devices will only pay for devices that can prove their ability to fulfill the required task. This basis of trust prevents fraudulent activity. Additionally, using the IOTA ledger, the task's progress can be immutably logged. Combining the IOTA protocol and the IOTA Identity framework, we can automate the entire interaction between all parties without requiring predefined trust. The [Industry Marketplace](https://industry.iota.org/) provides a perfect example of how this framework and level of autonomy work. + +There is a growth in applications that generate Digital Twins for physical devices or objects, such as the Asset Administration Shell (AAS) developed for our Industry Marketplace. Digital twins are online profiles representing a device or object. They provide a virtual state that mirrors reality by emulating the device or object’s physical state through data input sources like sensors. A digital twin is often used to monitor states and execute actions based on the information. Digital twins are only rarely shared outside the associated application and organization due to the complexities in sharing and matching profiles. However, empowered with a digital identity, digital twin sharing would become possible. Once data is verifiable and trusted, digital twins can form the basis for the digital representation of physical devices and objects. This allows other identities to interact with them automatically and provide services such as predictive maintenance. + +Security is a major barrier to advancing technologies that use IoT. Whether it is the smart devices in our homes or at a larger scale, the critical infrastructure of organizations and cities, security must be at the core. It is central to any globally unifying identity solution. By integrating advanced research in cryptography and digital ledgers and combining it with a scalable access and management system, security will become a core functionality of the systems we build. By using scalable device DIDs, integrating verification and reputation schemes, and allowing for transparent tamper-proof accountability, we begin to understand how we can future-proof the security of our systems, allowing us to start trusting the process and not the patch. + +### One Framework. Any Identity + +The IOTA Identity framework serves as a ubiquitous layer of trust for the internet. Whether it's people, organizations, or things, the framework enables the creation of digital identities, fosters trust-building through verifiable credentials, and ensures seamless interaction among different entities. + +### Why IOTA? + +IOTA stands apart as a scalable, feeless Distributed Ledger Technology (DLT), suitable for a universal identity solution. Some features of IOTA include: + +* **Cost-effectiveness**: Usually, minting decentralized identities costs fees. IOTA Identity has redeemable and predictable deposits but no fees. +* **High availability**: Identities are always available on all network nodes - for holders, issuers, and verifiers. +* **Security**: Write access to identities is secured through multi-level control structures with key rotation capabilities, allowing for backup access and recoverability. +* **Integrity**: Updates go through the same mechanisms that secure the IOTA network, guaranteeing consistent state and history of all identities. diff --git a/docs/build/identity.rs/1.1/docs/workflow.mdx b/docs/build/identity.rs/1.1/docs/workflow.mdx new file mode 100644 index 00000000000..1952b19f7ad --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/workflow.mdx @@ -0,0 +1,179 @@ +--- +title: Identity.rs workflow +sidebar_label: Workflow +description: Learn about the software development process of the IOTA Identity repository. +image: /img/Identity_icon.png +keywords: + - Workflow + - Contribute + - GitHub + - explanation +--- + +# Identity Workflow + +In this article you will learn about the software development process for the IOTA Identity repository as well as key terms, functions, and the overall operability of the workflow components. + +## Issues + +Issues are opened when a certain task or problem is noted but cannot immediately be fixed. Issues may contain bug reports, requests, or larger topics. Please use the correct GitHub issue template for your issue type. Only IOTA Foundation members should use the task templates flagged for maintainers. You should make sure to [label](#issue-labels) the issue correctly. As a contributor, you may also add issues to a certain [project](https://github.com/iotaledger/identity.rs/projects/). + +## Git + +### Pull Requests + +New branches should be pushed to the GitHub repository as soon as possible, making them public to all contributors. In addition, a pull request (PR) should be opened in draft status, describing the goals and any requirements of the changes. To generate good [changelogs](#changelog), a PR title must be written in a way that is suitable as a changelog entry while the PR must be [labeled](#pr-labels) correctly. + +Any code written should frequently be committed and pushed back to the GitHub branch. This acts as both a back-up mechanism and provides transparency towards other contributors and the community. You should also pull from the origin branch of the PR regularly to prevent merge conflicts. + +Other contributors are encouraged to provide feedback on a PR during its development. A PR should be flagged as 'ready for review' once the PR has implemented all changes and no further commits are planned by the main contributors. The repository requires a review to be provided by at least one (other) developer in the team that works in the same language or has knowledge of the work before it can be merged. For larger PRs, the review of two maintainers is recommended. + +Once a PR is approved, the preferred method is "squash-and-merge" for non-epic branches to keep the destination branch clean and allow for many small commits while work is in-progress. Epic branches must instead be merged with the merge commits of included PRs intact, so the [changelog generator](#changelog) can detect included changes. Once merged in, the source branch may be deleted. + +### Branches + +IOTA Identity always has two permanent branches: `main` and `dev`. Both branches are protected and disallow direct commits; the only changes allowed are from pull requests approved and merged by maintainers. + +#### [Main](https://github.com/iotaledger/identity.rs/tree/main) (main) + +The `main` branch contains a stable version of the code that is released towards package managers such as `crates.io` and `npm`. This branch only accepts PRs that merge from `release` or `hotfix` branches. + +#### [Dev](https://github.com/iotaledger/identity.rs) (dev) + +The `dev` branch contains a frequently updated version of the code that is released towards package managers under a development flag. These releases may contain breaking changes without a strong notice towards developers using them. While the `dev` branch may get frequent updates, it may not contain unfinished features. Any large, multi-PR feature should be committed to a long-lived `epic` branch created specifically for that feature. + +### Work Branches + +These are branches that developers work on directly. Their names should be prefixed appropriately with one of the following categories. For example, a PR fixing a null pointer bug in the Wasm bindings might be created from a branch called `fix/client-non-null`. + +#### Feature (feat/, doc/, chore/, fix/) + +Singular PR contributions should create either a `feat`, `doc`, `chore`, or `fix` branch, depending on the type of changes. These may be branched from either the `dev` branch or an `epic` branch. If the number of lines of code are going to be relatively small and the work completed in a single PR, the branch should be created from `dev` and merged back into `dev` once completed. Otherwise, the branches should be created from their associated `epic` branch and be merged back into the same `epic` branch. + +- `feat` branches should contain changes to the code that expand or modify functionality. They should also include updates to the documentation and examples related to the feature, though `doc` branches may be used to catch up on documenting a feature. +- `doc` branches contain changes to code documentation or the wiki. These PRs should be kept relatively small to avoid burdening a reviewer with too many documentation updates at once. For example, during a documentation catch-up, we will have a branch or PR per documentation page. +- `chore` branches are short-lived branches that contain no significant features or functionality changes, but rather smaller fixes such as typos, code fixes, minor refactors, and CI changes. +- `fix` branches correct bugs such as compilation errors or where existing features do not behave as expected, generally without introducing any new functionality or breaking changes. + +We recommend integrating `dev` or `epic` regularly, depending on where the branch started, to reduce the possibility and potential size of merge conflicts. + +#### Epic (epic/) + +Long-lived `epic` branches should be created as soon as a feature is expected to require more than one PR. The `epic` branch should be branched from `dev` and should only accept merges that are related to the feature being developed. A PR should be opened as soon as the branch is created to publicly notify contributors about the development, the goals and requirements of the feature, and the existence of the branch. It is recommended you integrate `dev` often to reduce the possibility and potential size of merge conflicts. Epic branches must not be squash-merged, otherwise the [changelog generator](#changelog) will not detect its constituent PRs. + +### Semantic Versioning + +Semantic Versioning (SemVer) describes a methodology for versioning of software to convey meaning and guarantees through the version string. A typical version string looks like `2.3.1`, where `2` is called the major version, `3` the minor version and `1` the patch or bugfix version. + +The central idea is that every part of the version string conveys meaning. A major change introduces behavior that is incompatible with previous versions of the software, while a minor change adds backwards-compatible functionality and a patch simply fixes a problem. So just by looking at the version string, an implementer will understand the effort needed to integrate a new version. + +For more detailed information and an overview of advanced features, see [Semantic Versioning 2.0.0](https://semver.org/). Though this is not to be confused with [Sentimental Versioning](http://sentimentalversioning.org/). + +### Changelog + +A changelog is a file describing a software project for humans to grasp the type and content of changes from version to version. Changelogs are closely related to the versioning of software, since individual changes are grouped into versions that are, in our case, referenced by a [SemVer string](#semantic-versioning). We generally follow the recommendations from [keepachangelog](https://keepachangelog.com/en/1.0.0/). The changelog in this project is generated from the titles and [labels](#pr-labels) of [pull requests](#pull-requests). + +#### PR labels + +Labels are used to categorize changes in [pull requests](#pull-requests). Adding a label will include the labeled [PR](#pull-requests) title in the related section of the generated [changelog](#changelog). + +Changelogs are generated for the core Rust library and each binding separately. To attach a PR to a specific changelog, use the following labels: + +##### `Rust` + +This includes the PR in the core Rust library changelog. + +##### `Wasm` + +This includes the PR in the WASM bindings changelog. + +It is also necessary to add an appropriate label for the type of change in the PR. The following labels determine in which section a PR title will appear: + +##### Changed + +Maps to the major version of [Semantic Versioning](#semantic-versioning). +labels: `Breaking change` + +##### Added + +Maps to the minor version of [Semantic Versioning](#semantic-versioning). +labels: `Added` + +##### Patch + +Maps to the patch version of [Semantic Versioning](#semantic-versioning). +labels: `Patch` + +##### Deprecated + +Marks features that will be removed in the feature. No special version consideration should apply here, since the feature did not change yet. +labels: `Deprecated` + +##### Removed + +Marks features as being removed. Typically the features should have been deprecated in the previous version. This maps to the major version of [Semantic Versioning](#semantic-versioning). +labels: `Removed` + +##### Excluded tags + +Marks changes that should not be part of the changelog. This should only be used for documentation and rare exceptions. +labels: `Documentation`, `No changelog` + +Please note that a PR can only be listed in one section of a changelog. So attaching the labels `Rust` `Added` `Patch` to a PR, for example, is invalid because `Added` and `Patch` conflict. + +##### Release summary + +To attach a release summary to a version in the changelog, an issue with the label `release-summary` must be created. Create a GitHub milestone matching the version you want to describe and attach it to the issue. The issue can be closed immediately. The text of the issue will be included in the changelog as the release summary. + +### Issue Labels + +The following labels are used to categorize issues but do not have any effect on changelogs: `Request`, `Enhancement`, `Bug`, `Chore`, `Dependencies`, `Help wanted`, `Duplicate`, `Wontfix`. + +## Release + +With the release process, we can deliver versions of our software to the community. We use sensible automation where it helps to remove tedium. However, some steps that require active decision-making remain manual. + +The final list of changes from the [changelog](#changelog) informs the version of the release. If at least one change mapping to a major version is included, the major version needs to be incremented. In that case, the minor and patch versions are set to `0`. If there are no changes related to a major version, but changes related to a minor version are present, the minor version needs to be incremented while the patch version is set to `0`. Otherwise, only the patch version is incremented. Determining the version of the release is the responsibility of the person performing the release. + +The determined version of the release is used to create the [hotfix](#hotfix) or [release](#release) branch. For example, a major release from the previous version `v2.3.1` will create the `release/v3.0.0` branch. + +Notice the `v` in front of the version. We [tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) all release in git in the form of `vMAJOR.MINOR.PATCH`. For bindings, we prefix the tag with the binding name, so a tag for Wasm would look like `wasm-v1.2.3`. Bindings and the core Rust library are versioned and released independently. + +Additionally, we may release `dev` versions separately for both bindings and the core Rust library. These releases are meant as a preview of upcoming versions. For example, if the current version is `1.2.3` with the tag `v1.2.3`, we may release `v1.3.0-dev.1` which is then superseded by the actual `1.3.0` release. + +You should follow these steps to create a release: + +1. Ensure all the changes you want to release are on the `dev` branch. +2. Select the appropriate GitHub Actions workflow, e.g. `Rust Create Release PR`. + 2.1. Decide if you want to create a `dev` or `main` release. + 2.2. Determine the next version string. + 2.3. Run the workflow. The workflow will create a PR from `dev` targeting `dev` with release related changes. +3. Review the PR. + 3.1. The PR will update the changelog, check that it has all expected entries in the appropriate sections and the determined version matches the changelog according to [SemVer](#semantic-versioning). + 3.2. The PR will update project version strings, ensure these are correct and match the expected version. + 3.3. Refer to [Troubleshooting](#troubleshooting) if anything is incorrect. +4. Merge the PR. + 4.1. On merging to `dev`, an automatic workflow is triggered that builds and publishes artifacts to the appropriate package manager (`crates.io` for Rust, `npm` for the WASM bindings), and creates a GitHub Release (only for `main` version releases of the core Rust library). +5. For `main` version releases, merge the `dev` branch into the `main` branch. + +### Troubleshooting + +#### The changelog entries have the wrong description in the release PR + +Update the titles of the relevant PRs, then re-run the workflow with the same parameters. The release PR will be updated with the new changelog. + +#### The changelog in the release PR is missing entries, has unrelated entries, or entries in the wrong section + +Fix the [labels](#pr-labels) on the relevant PRs, then re-run the workflow with the same parameters. The release PR will be updated with the new changelog. + +#### The release description in the release PR is missing or wrong + +Fix the issue description, milestone, and label according to the [release summaries guide](#release-summary) and re-run the workflow with the same parameters. The release PR will be updated with the new changelog. + +#### Features or code are missing from the release + +Merge the code into the `dev` branch, then re-run the workflow with the same parameters. The release PR will be updated with the changes. + +#### I want to abort the release for any reason + +Close the PR. You can reopen it later. // TODO: can I just re-run the workflow? Maybe that needs an "I want to resume an aborted release" section? diff --git a/docs/build/identity.rs/1.1/sidebars.js b/docs/build/identity.rs/1.1/sidebars.js new file mode 100644 index 00000000000..30f4668b4d5 --- /dev/null +++ b/docs/build/identity.rs/1.1/sidebars.js @@ -0,0 +1,114 @@ +/** + * Creating a sidebar enables you to: + - create an ordered group of docs + - render a sidebar for each doc of that group + - provide next/previous navigation + + The sidebars can be generated from the filesystem, or explicitly defined here. + + Create as many sidebars as you want. + */ + +module.exports = { + // By default, Docusaurus generates a sidebar from the docs folder structure + // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], + + // But you can create a sidebar manually + + docs: [ + { + type: 'doc', + id: 'welcome', + label: 'Welcome', + }, + { + type: 'category', + label: 'Getting Started', + collapsed: false, + items: ['getting-started/rust', 'getting-started/wasm'], + }, + { + type: 'category', + label: 'Explanations', + items: [ + 'explanations/decentralized-identifiers', + 'explanations/verifiable-credentials', + 'explanations/verifiable-presentations', + 'explanations/about-alias-outputs', + ], + }, + { + type: 'category', + label: 'How To', + items: [ + { + type: 'category', + label: 'Decentralized Identifiers (DID)', + items: [ + 'how-tos/decentralized-identifiers/create', + 'how-tos/decentralized-identifiers/update', + 'how-tos/decentralized-identifiers/resolve', + 'how-tos/decentralized-identifiers/delete', + ], + }, + { + type: 'category', + label: 'Verifiable Credentials', + items: [ + 'how-tos/verifiable-credentials/create', + 'how-tos/verifiable-credentials/revocation', + 'how-tos/verifiable-credentials/selective-disclosure', + ], + }, + { + type: 'category', + label: 'Verifiable Presentations', + items: ['how-tos/verifiable-presentations/create-and-validate'], + }, + { + type: 'category', + label: 'Domain Linkage', + items: ['how-tos/domain-linkage/create-and-verify'], + }, + 'how-tos/key-storage', + ], + }, + { + type: 'category', + label: 'References', + collapsed: true, + items: [ + { + type: 'category', + label: 'API', + items: [ + { + type: 'doc', + id: 'references/api/wasm', + label: 'Wasm', + }, + { + type: 'link', + label: 'Rust', + href: 'https://docs.rs/identity_iota/latest/identity_iota/index.html', + }, + ], + }, + { + type: 'category', + label: 'Specifications', + items: [ + 'references/specifications/overview', + 'references/specifications/iota-did-method-spec', + 'references/specifications/revocation-bitmap-2022', + ], + }, + ], + }, + 'glossary', + 'contribute', + 'workflow', + 'contact', + 'faq', + ], +}; diff --git a/versionedConfig.js b/versionedConfig.js index 7e0c1c2ad27..8c7dc46cfea 100644 --- a/versionedConfig.js +++ b/versionedConfig.js @@ -66,6 +66,10 @@ exports.buildPluginsConfig = [ icon: 'Identity', subsection: 'build-layer-1', versions: [ + { + label: '1.1', + badges: ['IOTA', 'Shimmer'], + }, { label: '1.0', badges: ['IOTA', 'Shimmer'],