Merge branch 'main' into fix/dco-yshyn-iohk

CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.109.0](https://github.com/hyperledger/identus-docs/compare/v1.108.0...v1.109.0) (2024-09-11)
+
+### :rocket: New Content
+
+* Docker Logging Considerations ([#162](https://github.com/hyperledger/identus-docs/issues/162)) ([cea862b](https://github.com/hyperledger/identus-docs/commit/cea862b4f7b111d84461597dd192de2a0f09ee96))
+
 ## [1.108.0](https://github.com/hyperledger/identus-docs/compare/v1.107.0...v1.108.0) (2024-09-09)
 
 ### :rocket: New Content

documentation/docs/identus/cloud-agent/environment-variables.md

@@ -64,3 +64,5 @@ The following enviroment variables can be used to configure Cloud Agent:
 | KEYCLOAK_CLIENT_SECRET                     | The Keycloak client secret.                                                                                                                                        | String                | `prism-agent-demo-secret`                    |
 | KEYCLOAK_UMA_AUTO_UPGRADE_RPT              | Whether or not to enable automatic upgrade of RPT tokens. If disabled, `accessToken` must be RPT and include the permission claims.                                | Boolean               | true                                         |
 | KEYKLOAK_ROLES_CLAIM_PATH                  | The json path to the `roles` claim in the JWT payload . Used for role-based authorization (e.g. admin or tenant).                                                  | String                | `resource_access.<KEYCLOAK_CLIENT_ID>.roles` |
+| PRESENTATION_INVITATION_EXPIRY             | The presentation invitation expiry duration e.g 300 seconds. After which the OOB Request Presentation will expire                                                  | String                | 300 seconds                                  |
+| ISSUANCE_INVITATION_EXPIRY                 | The presentation invitation expiry duration e.g 300 seconds. After which the OOB Credential Offer will expire                                                      | String                | 300 seconds                                  |     

documentation/docs/identus/troubleshooting&considerations.md

@@ -0,0 +1,63 @@
+# Troubleshooting & Considerations
+
+## Docker Logging Management Considerations
+When setting up a long-running environment using Docker Compose, it’s important to consider several factors to avoid issues such as excessive log file sizes leading to out-of-memory errors.
+
+### Configuring Docker Compose for Effective Log Management
+To ensure your Docker containers run smoothly and avoid problems related to excessive log file growth, configure log rotation in your docker-compose.yml file. This will help manage log file sizes and prevent out-of-memory errors caused by uncontrolled log growth.
+
+### Log Rotation Example
+
+Here’s a example in the mediator how to set up log rotation in your Docker Compose configuration:
+
+1. Open your docker-compose.yml file.
+2. Add or update the logging configuration under your service definition. For example:
+
+```yaml
+version: '3.8'
+
+services:
+  identus-mediator:
+    image: ghcr.io/input-output-hk/atala-prism-mediator:0.14.2
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+```
+
+- `driver`: Specifies the logging driver to use. The json-file driver is the default and supports log rotation options.
+- `max-size`: Sets the maximum size of the log file before it gets rotated. In the example above, the log file will be rotated when it reaches 10 MB.
+- `max-file`: Determines the number of rotated log files to keep. In this example, up to 3 log files will be kept before old files are deleted.
+
+```shell
+docker-compose up -d
+```
+
+3. Save the changes to your `docker-compose.yml` file and **Restart** your Docker containers to apply the new logging configuration.
+
+### Configuring Docker Daemon for Effective Log Management
+
+We should consider configuring the logging Options in the **Docker Daemon**. For a global logging configuration applicable to all Docker containers. We can modify the Docker daemon settings. This approach ensures consistent log management across all containers.
+
+1. Edit the Docker daemon configuration file (usually located at /etc/docker/daemon.json). If the file doesn’t exist, you can create it.
+2. Add or update the logging options in the `daemon.json` file:
+
+```json
+{
+  "log-driver": "json-file",
+  "log-opts": {
+    "max-size": "10m",
+    "max-file": "3"
+  }
+}
+```
+3. Restart the Docker daemon to apply the new settings:
+
+```shell
+sudo systemctl restart docker
+```
+
+#### Docker logging drivers
+
+For more information see https://docs.docker.com/engine/logging/configure/#supported-logging-drivers

documentation/docs/quick-start.md

@@ -601,7 +601,13 @@ agent.acceptOutOfBandInvitation(invitation)
 
 The credential issuance flow consists of multiple steps, detailed in this section. It starts with the Issuer sending a [Credential Offer](/docs/concepts/glossary/#credential-offer) to the Holder, which would accept or reject this invitation and create a `credentialRequest` from it. The [credential request](/docs/concepts/glossary/#credential-request) gets sent through DIDComm to the Issuer, issuing and sending the credential back to the Holder.
 
-### Create a Credential Offer **Issuer Agent**
+The Issuer can create a credential offer in two ways:
+1. As a direct credential offer DIDComm message for a holder with an existing connection
+2. As an credential offer as attachment in an OOB invitation message for connectionless issuance
+
+<Tabs>
+<TabItem value="existing" label="With Existing Connection">
+### Create a Credential Offer with an existing connection **Issuer Agent**
 
 1. To trigger the creation of a credential-offer, we call the credential-offers-endpoint, as follows:
 
@@ -630,7 +636,98 @@ curl --location --request POST 'http://localhost:8000/cloud-agent/issue-credenti
     "automaticIssuance": true
 }'
 ```
+</TabItem>
+<TabItem value="connectionless" label="Connectionless Issuance">
+### Create a Credential Offer as Invitation for connectionless issuance **Issuer Agent**
+
+1. To trigger the creation of a credential-offer, we call the credential-offers-invitation-endpoint, as follows:
+
+:::info
+
+Please replace the following variables in the example request before sending:
+
+- `goalCode`: OPTIONAL A self-attested code the receiver may want to display to the user or use in automatically deciding what to do with the out-of-band message,
+- `goal`: OPTIONAL. A self-attested string that the receiver may want to display to the user about the context-specific goal of the out-of-band message.
+- `publishedPrismDID`: The short form of the PRISM DID created when setting up the Issuer agent
 
+The Issuing DID is the published PRISM DID in its short version which was also used to create and publish the credential schema.
+
+- ``
+
+:::
+
+```bash
+curl --location --request POST 'http://localhost:8000/cloud-agent/issue-credentials/credential-offers/invitation' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "claims": {"emailAddress":"sampleEmail", "familyName":"", "dateOfIssuance":"2023-01-01T02:02:02Z", "drivingLicenseID":"", "drivingClass":1},
+    "goalCode": [[goalCode]],
+    "goal": [[goal]],
+    "credentialFormat": "JWT",
+    "issuingDID": [[publishedPrismDID]],
+    "automaticIssuance": true
+}'
+```
+
+
+### Accept Credential Offer Invitation for connectionless issuance **Holder**
+
+For connectionless issuance, the Holder needs to accept the invitation containing the credential offer. This step is necessary before creating the Credential Request.
+#### Demo application
+<Tabs>
+<TabItem value="js" label="Typescript Sample APP">
+
+1. In the browser at localhost:3000, navigate to the "Credential Offer" section.
+2. Paste the invitation URL received from the Issuer into the provided input field.
+3. Click on "Accept Invitation" to process the credential offer.
+
+</TabItem>
+<TabItem value="swift" label="Swift Sample APP">
+
+1. In the Swift mobile app, go to the "Credential Offer" section.
+2. Enter the invitation URL received from the Issuer.
+3. Tap on "Accept Invitation" to process the credential offer.
+
+</TabItem>
+<TabItem value="android" label="Android Sample APP">
+
+1. In the Android mobile app, navigate to the "Credential Offer" section.
+2. Input the invitation URL provided by the Issuer.
+3. Tap "Accept Invitation" to process the credential offer.
+
+</TabItem>
+</Tabs>
+
+<summary>Code examples</summary>
+<Tabs>
+<TabItem value="js" label="Typescript">
+
+```js
+const parsed = await props.agent.parseOOBInvitation(new URL([[OOB URL]]));
+await props.agent.acceptDIDCommInvitation(parsed);
+```
+
+</TabItem>
+<TabItem value="swift" label="Swift">
+
+```swift
+  let message = try agent.parseOOBInvitation(url: oobUrl)
+  try await agent.acceptDIDCommInvitation(invitation: message)
+```
+
+</TabItem>
+<TabItem value="android" label="Android">
+
+```kotlin
+val invitation = agent.parseInvitation(oobUrl)
+agent.acceptOutOfBandInvitation(invitation)
+```
+
+</TabItem>
+</Tabs>
+
+</TabItem>
+</Tabs>
 ### Create CredentialRequest from CredentialOffer **Holder**
 
 2. Because this credential Offer was created with the `automaticIssuance` true, as soon as the `CloudAgent` receives this `credentialRequest` it will respond with the `IssuedCredential` message and send this back to the holder.
@@ -829,12 +926,16 @@ Now that the Holder has received a credential, it can be used in a verification
 
 :::info
 
-In the example, we show a verification flow that assumes a connection between Holder and Verifier. In the future, we will also support connectionless verification.
+In the example, we demonstrate two verification flows:
 
+1. Verification with an established connection between the Holder and the Verifier.
+2. Connectionless verification in which the Holder and Verifier do not have a pre-established connection.
 :::
 
 
 ### Verifier Agent
+<Tabs>
+<TabItem value="existing" label="With Existing Connection">
 
 5. To run this section, we will use [the connection](/docs/quick-start#establish-connection-on-the-verifier-cloud-agent) we created between the Holder and the Verifier.
 
@@ -861,6 +962,95 @@ curl --location \
 
   * This API request will return a `presentationRequestId,` which the verifier can use later to check the current status  of the request.
 
+</TabItem>
+<TabItem value="connectionless" label="Connectionless Request Presentation"> 
+
+5. To run this section, we'll use the presentation invitation endpoint to create a request presentation invitation, which the holder can scan to receive the invitation or the verifier can share directly.
+
+```bash
+curl --location \
+--request POST 'http://localhost:9000/cloud-agent/present-proof/presentations/invitation' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "goalCode": [[goalCode]],
+    "goal": [[goal]],
+    "credentialFormat": "JWT",
+    "proofs": [
+        {
+            "schemaId": [[schemaId]],
+            "trustIssuers": [
+                [[PUBLISHED PRISM DID FROM THE ISSUER]]
+            ]
+        }
+    ],
+    "options": {
+        "challenge": "A challenge for the holder to sign",
+        "domain": "domain.com"
+    }
+}'
+```
+
+  * This API request will return an `invitationId` along with an Out-Of-Band (OOB) message. The OOB message includes a Request Presentation in JSON format as an attachment and is encoded as a base64 URL-encoded string, which can be shared with the holder.
+
+### Accept Request Presentation invitation for connectionless verification **Holder**
+
+For connectionless verification, the Holder needs to accept the invitation containing the Request Presentation.
+#### Demo application
+<Tabs>
+<TabItem value="js" label="Typescript Sample APP">
+
+1. In the browser at localhost:3000, navigate to the "Request Presentation" section.
+2. Paste the invitation URL received from the Issuer into the provided input field.
+3. Click on "Accept Invitation" to process the request presentation.
+
+</TabItem>
+<TabItem value="swift" label="Swift Sample APP">
+
+1. In the Swift mobile app, go to the "Request Presentation" section.
+2. Enter the invitation URL received from the Issuer.
+3. Tap on "Accept Invitation" to process the request presentation.
+
+</TabItem>
+<TabItem value="android" label="Android Sample APP">
+
+1. In the Android mobile app, navigate to the "Request Presentation" section.
+2. Input the invitation URL provided by the Issuer.
+3. Tap "Accept Invitation" to process the request presentation.
+
+</TabItem>
+</Tabs>
+
+<summary>Code examples</summary>
+<Tabs>
+<TabItem value="js" label="Typescript">
+
+```js
+const parsed = await props.agent.parseOOBInvitation(new URL([[OOB URL]]));
+await props.agent.acceptDIDCommInvitation(parsed);
+```
+
+</TabItem>
+<TabItem value="swift" label="Swift">
+
+```swift
+  let message = try agent.parseOOBInvitation(url: oobUrl)
+  try await agent.acceptDIDCommInvitation(invitation: message)
+```
+
+</TabItem>
+<TabItem value="android" label="Android">
+
+```kotlin
+val invitation = agent.parseInvitation(oobUrl)
+agent.acceptOutOfBandInvitation(invitation)
+```
+
+</TabItem>
+</Tabs>
+
+</TabItem>
+</Tabs>
+
 
 
 ### Holder: Receives the Presentation proof request

documentation/docs/sidebars.js

@@ -79,6 +79,7 @@ const sidebars = {
           ],
         },
         "identus/mediator",
+        "identus/troubleshooting&considerations",
         "identus/getting-help",
       ],
     },

package.json

@@ -1,6 +1,6 @@
 {
   "name": "identus-documentation-portal",
-  "version": "1.108.0",
+  "version": "1.109.0",
   "private": true,
   "license": "Apache-2.0",
   "scripts": {