diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000000..a94640e695 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,25 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 2 + +[*.swift] +indent_size = 4 + +[*.{rs,go}] +indent_size = 4 + +[*.md] +trim_trailing_whitespace = false +indent_size = unset + +[LICENSE] +indent_size = unset + +[Makefile] +indent_style = tab diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs new file mode 100644 index 0000000000..fd58fbfc9e --- /dev/null +++ b/.git-blame-ignore-revs @@ -0,0 +1,3 @@ +# style: auto-fix and manually resolve all lint errors across the repo +# Mass formatting. No logic changes. +c9e982cdf2de93a3093f2e9c3dc4653811de1eac diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000000..2e2bb588d0 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,46 @@ +# Normalize all text files to LF +* text=auto eol=lf + +# Scripts -- must be LF (executed in Docker/Linux) +*.sh text eol=lf +*.bash text eol=lf + +# Data/config +*.sql text eol=lf +*.yaml text eol=lf +*.yml text eol=lf +*.json text eol=lf +*.toml text eol=lf +*.properties text eol=lf + +# Source code +*.scala text eol=lf +*.kt text eol=lf +*.kts text eol=lf +*.java text eol=lf +*.swift text eol=lf +*.ts text eol=lf +*.js text eol=lf +*.rs text eol=lf +*.go text eol=lf + +# Docs +*.md text eol=lf +*.txt text eol=lf + +# Docker +Dockerfile text eol=lf +docker-compose*.yml text eol=lf + +# Binary -- never touch +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.ico binary +*.jar binary +*.zip binary +*.tar.gz binary +*.woff binary +*.woff2 binary +*.ttf binary diff --git a/.github/workflows/file-hygiene.yml b/.github/workflows/file-hygiene.yml new file mode 100644 index 0000000000..edb8f9e9f3 --- /dev/null +++ b/.github/workflows/file-hygiene.yml @@ -0,0 +1,10 @@ +name: File Hygiene + +on: + pull_request: + push: + branches: [main] + +jobs: + lint: + uses: hyperledger-identus/.github/.github/workflows/lint-files.yml@f2c9e417fa46f69b015a9cdbaafdfb9e52e4ed60 # main diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml index 0505a951af..df48ece095 100644 --- a/.github/workflows/link-check.yml +++ b/.github/workflows/link-check.yml @@ -46,9 +46,9 @@ jobs: echo "| URL | Status | Parent Page |" >> link-report.md echo "|-----|--------|-------------|" >> link-report.md jq -r '.links[] | select(.state == "BROKEN") | "| \(.url) | \(.status) | \(.parent) |"' link-check-results.json >> link-report.md - + BROKEN_COUNT=$(jq '[.links[] | select(.state == "BROKEN")] | length' link-check-results.json) - + echo "### πŸ”— Broken Links Report( $BROKEN_COUNT found)" >> $GITHUB_STEP_SUMMARY cat link-report.md >> $GITHUB_STEP_SUMMARY @@ -64,4 +64,4 @@ jobs: if: env.LINKINATOR_EXIT_CODE != 0 run: | echo "Broken links detected. Check the artifact for details." - exit 1 \ No newline at end of file + exit 1 diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000000..aee3aa1b25 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,13 @@ +# markdownlint-cli2 configuration +# https://github.com/DavidAnson/markdownlint-cli2 + +# Ignore patterns +ignores: + - "**/target/**" + - "**/node_modules/**" + - ".claude/**" + - "**/build/**" + - "cloud-agent/**" + - "sdk-ts/**" + - "CHANGELOG.md" + - "megalinter-reports/**" diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000000..e063c2812b --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,52 @@ +# markdownlint configuration +# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md + +default: true + +# Allow long lines (common in tables, URLs, and generated content) +MD013: false + +# Allow multiple top-level headings (common in multi-section docs) +MD025: false + +# Allow inline HTML (needed for badges, details/summary, admonitions) +MD033: false + +# Allow duplicate headings in different sections +MD024: false + +# Allow emphasis as heading +MD036: false + +# Allow bare URLs +MD034: false + +# Allow non-sequential list numbering +MD029: false + +# Allow any strong style +MD050: false + +# Relaxed list indentation +MD007: false + +# Allow any list style +MD004: false + +# Allow heading increment jumps +MD001: false + +# Allow compact table style +MD060: false + +# Allow first line to not be heading +MD041: false + +# Allow dollar signs before commands +MD014: false + +# Allow non-descriptive link text +MD059: false + +# Allow code blocks without language +MD040: false diff --git a/.yamllint.yml b/.yamllint.yml new file mode 100644 index 0000000000..3937821213 --- /dev/null +++ b/.yamllint.yml @@ -0,0 +1,46 @@ +--- +extends: default + +rules: + # Allow long lines (common in CI workflows and docker-compose) + line-length: disable + + # Allow truthy values like 'on' (used in GitHub Actions triggers) + truthy: + allowed-values: ["true", "false", "yes", "no", "on"] + + # Relaxed comment indentation + comments-indentation: disable + + # Don't require document start marker + document-start: disable + + # Relaxed bracket/brace spacing + brackets: + min-spaces-inside: 0 + max-spaces-inside: 1 + braces: + min-spaces-inside: 0 + max-spaces-inside: 1 + + # Allow 1 space before comment + comments: + min-spaces-from-content: 1 + + # Relaxed indentation (semantic-release uses flow style) + indentation: + spaces: consistent + indent-sequences: whatever + + # Relaxed commas + commas: + min-spaces-after: 1 + max-spaces-after: -1 + max-spaces-before: -1 + +ignore: | + cloud-agent/ + sdk-ts/ + node_modules/ + .claude/ + .releaserc.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4c894c593e..4073fe4050 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,3 @@ -# Contributing - -Thank you for your interest in contributing to this project! Please refer to the Hyperledger Identus repository's [CONTRIBUTING.md](https://github.com/hyperledger-identus/identus/blob/main/CONTRIBUTING.md) file for guidelines on how to submit code or documentation contributions. \ No newline at end of file +# Contributing + +Thank you for your interest in contributing to this project! Please refer to the Hyperledger Identus repository's [CONTRIBUTING.md](https://github.com/hyperledger-identus/identus/blob/main/CONTRIBUTING.md) file for guidelines on how to submit code or documentation contributions. diff --git a/DCO.md b/DCO.md index dfcd8d5447..58d7d3644b 100644 --- a/DCO.md +++ b/DCO.md @@ -1,3 +1,3 @@ -# Developer Certificate of Origin (DCO) - -For information about sign-offs required for contributions to this repository, please refer to this Hyperledger Identus repository's [DCO.md](https://github.com/hyperledger-identus/identus/blob/main/DCO.md) file. \ No newline at end of file +# Developer Certificate of Origin (DCO) + +For information about sign-offs required for contributions to this repository, please refer to this Hyperledger Identus repository's [DCO.md](https://github.com/hyperledger-identus/identus/blob/main/DCO.md) file. diff --git a/LICENSE b/LICENSE index 55542ed5f0..522293639f 100644 --- a/LICENSE +++ b/LICENSE @@ -1,201 +1,201 @@ - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright 2024 Input Output Global - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2024 Input Output Global + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 2b37464505..364b4670b1 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,3 +1,3 @@ -# Mainteiners - -For information about the Maintainers of this repository, refer to the Hyperledger Identus repository’s [MAINTAINERS.md](https://github.com/hyperledger/identus/blob/main/MAINTAINERS.md) file. +# Mainteiners + +For information about the Maintainers of this repository, refer to the Hyperledger Identus repository’s [MAINTAINERS.md](https://github.com/hyperledger/identus/blob/main/MAINTAINERS.md) file. diff --git a/README.md b/README.md index a7d9bc3856..a018c7e1bf 100644 --- a/README.md +++ b/README.md @@ -3,28 +3,33 @@ This website is built using [Docusaurus 2](https://docusaurus.io/). # Structure + * docs * tutorials * sdk * api ## `docs`: general documentation + * Getting started guides * SSI and Identus concepts * Identus architecture and components description ## `tutorials`: general Identus tutorials + * Credential issuance * Verification * DIDs * etc. ## `sdk`: SDKs documentation + * sdk-ts * sdk-swift * sdk-kmp ## `api`: autogenerated docs from OpenAPI specs + `documentation/api` directory contains auto-generated documentation for RestAPI endpoints provided by Identus executables, it's auto-generated and should not be added manually. ## Installation diff --git a/SECURITY.md b/SECURITY.md index 366cb799fe..98d2fb6eb1 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,3 +1,3 @@ -# Security - -For information about reporting security vulnerabilities in this repository, please consult the Hyperledger Identus repository’s [SECURITY.md](https://github.com/hyperledger-identus/identus/blob/main/SECURITY.md) file. \ No newline at end of file +# Security + +For information about reporting security vulnerabilities in this repository, please consult the Hyperledger Identus repository’s [SECURITY.md](https://github.com/hyperledger-identus/identus/blob/main/SECURITY.md) file. diff --git a/documentation/adrs/decisions/2022-09-19-use-markdown-architectural-decision-records.md b/documentation/adrs/decisions/2022-09-19-use-markdown-architectural-decision-records.md index f16dbd0485..cfa428c03d 100644 --- a/documentation/adrs/decisions/2022-09-19-use-markdown-architectural-decision-records.md +++ b/documentation/adrs/decisions/2022-09-19-use-markdown-architectural-decision-records.md @@ -9,7 +9,7 @@ We want to record architectural decisions made in this project. Which format and structure should these records follow? -## Decision Drivers +## Decision Drivers - We want to improve the information and technical documentation of our software engineering projects - We want to create an immutable log of important architectural decisions we have made during the software development @@ -20,7 +20,7 @@ Which format and structure should these records follow? ## Considered Options -- [MADR](https://github.com/adr/madr/compare/3.0.0-beta...3.0.0-beta.2) 3.0.0-beta.2 +- [MADR](https://github.com/adr/madr/compare/3.0.0-beta...3.0.0-beta.2) 3.0.0-beta.2 - [MADR](https://adr.github.io/madr/) 2.1.2 with Log4brains patch - [MADR](https://adr.github.io/madr/) 2.1.2 – The original Markdown Architectural Decision Records - [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR" diff --git a/documentation/adrs/decisions/2022-10-05-using-tapir-library-as-a-dsl-for-openapi-specification.md b/documentation/adrs/decisions/2022-10-05-using-tapir-library-as-a-dsl-for-openapi-specification.md index 55be5ef964..5e4b67e45d 100644 --- a/documentation/adrs/decisions/2022-10-05-using-tapir-library-as-a-dsl-for-openapi-specification.md +++ b/documentation/adrs/decisions/2022-10-05-using-tapir-library-as-a-dsl-for-openapi-specification.md @@ -8,6 +8,7 @@ Related ADR/AIP: [Introduce REST HTTP for existing Node services](https://input-output.atlassian.net/wiki/spaces/AV2/pages/3454500948/AIP+-+001) ## Context and Problem Statement + Identus Platform will contain the REST API. The decision was made by team consensus during the first AOH meeting to follow "OpenAPI specification first" approach and generate stubs, server side and client side code based on OAS. Following this strategy we currently have 4-5 OAS files (Castor, Pollux, Mercury, Configuration). @@ -27,6 +28,7 @@ Mustache templates and code generation doesn't work out of the box, so the origi Current templates and generator contains constraints that were reported by [@Pat](https://docs.google.com/document/d/1WhUtflM_o-5uSx9LW76lycz2kbk071cVZiv6EtVwhAQ/edit#heading=h.ywcvgffenpz) and [@Shota](https://input-output-rnd.slack.com/archives/G018JE9NHAM/p1664563129397819), this requires engineering time to adopt the OAS for a code generation. @Ben says that we can live with these constraints Generally, OAS files are written by the engineers with different experience and different view on formatting, schemas, normalization, datatype. For instance, in current templates don't have + - a consistent way for paginating the entities - standard Responses for 4xx and 5xx errors - normalized data types (we use ```anyOf```, ```allOf```) @@ -40,11 +42,15 @@ To mitigate this issue @Pat proposed to use well-known tools: Quality and formatting of autogenerated code depend on the template (not all templates are good enough). Making the good code from existing templates require additional time of engineers. ### OpenAPI code generator constraints for Akka server + #### @Pat + - oneOf is not supported. It combines everything from the list if it’s an object, discard if it’s a primitive - allOf is not supported as stated in the documentation, but testing locally it worked - Have to handwrite the serialization layer + #### @Shota + - Undefined type ```AnyType```. You can have additionalProperties (```components/schemas//properties/additionalProperties```) in the schema, when you add it, it will generate a type for \ that has another type called `AnyType` inside, this type is not defined, it just does not exist in generated code so the compilation will fail, if you get a compilation error in your sources with some `AnyType` that is not defined, look for additionalProperties in your schema - Values of type object without properties don’t serialize with spray json. You can have ```componets/schemas//properties/``` and every property has a type, like string, int, etc.., you can have type as object, but if you do so, you must provide object properties as well like in example below, if you don’t add it, it will generate this object type with Any in scala, and then the Akka marshaller will fail, because we use SprayJson there, and it does not support Reader and Writer for type Any (basically it can’t serialize type Any into json), you could probably define Writer and Reader for type Any to be an empty object, but I personally don’t see a reason to have value of type object and not define what properties it is going to have anyway. - ```requestBody``` in every path must be explicitly ```required:true```. It is ```false``` by default, if not marked as ```true``` it will generate a service functions that accepts ```Option[Type]``` instead of ```Type``` but endpoints are always expecting ```Type``` even if required is ```false```, not ```Option[Type]```, then when you try to generate sources you will get compilation error ```expecting Type got Option[Type]``` @@ -104,11 +110,13 @@ graph TD - Better management of OAS spec and control over the documentation (Swagger UI, Redoc, Async API for WebSockets) ### Negative Consequences + - Not all engineers will be able to edit the endpoint definitions in Tapir DLS, so either only engineer with Scala knowledge will do this, or knowledge sharing and workshops "How to use Tapir" are required. - OAS is going to be generated from the model defined by DLS, so the granular/manual control over the spec will be replaced by Tapir generator - There is a risk that Tapir might have some hidden surprises and constraints ### Option 1 & 2: Feature Implementation Workflow +
 graph TD
     U[Start Feature] --> |Edit OAS| A
@@ -127,6 +135,7 @@ graph TD
 
### Option 3: Feature Implementation Workflow +
 graph TD
     U[Start Feature] --> |Edit Endpoint Specification| ED(Endpoint Definition)
@@ -169,6 +178,7 @@ graph TD
 ### Option 2: use OpenAPI tools and mustache templates for alternative Scala server libraries (Finch, Lagom, Play )
 
 [example | description | pointer to more information | …] 
+
 - All ```good``` and ```bad``` are the same as in Option 1
 - Bad, because we don't know if the mustache templates are good enough for Scala 3
 - Bad, because we need to evaluate if engineering team have the experience in Finch, Lagom or Play
@@ -190,8 +200,11 @@ graph TD
 - Bad, because we need to spend 3-5 day to transform OAS files into Tapir DSL
 
 ## How to migrate from the current state to Tapir?
+
 ### Current state: OpenAPI Tools + mustache templates for Akka server
+
 ### Desired state: Endpoint Definitions in Tapir + ZIO-HTTP
+
 Estimated migration time is 4-6 days which we don't really want to waste.
 
 So, engineering team can proceed with keeping the existing endpoints in the current state and even work on the new endpoints using generated server stubs for Akka.
diff --git a/documentation/adrs/decisions/2022-10-06-store-private-keys-of-issuers-inside-prism-agent.md b/documentation/adrs/decisions/2022-10-06-store-private-keys-of-issuers-inside-prism-agent.md
index 1adad8801f..9218b6ebbb 100644
--- a/documentation/adrs/decisions/2022-10-06-store-private-keys-of-issuers-inside-prism-agent.md
+++ b/documentation/adrs/decisions/2022-10-06-store-private-keys-of-issuers-inside-prism-agent.md
@@ -8,14 +8,12 @@
 
 While each holder has a wallet application on the phone (edge agent) to store private keys, contacts, and credentials, Identus Cloud Agent will provide a custodial solution to Issuers and Verifiers. Thus they won't have their wallets or store/manage keys. There needs to be storage for the private keys of Issuers and Verifiers on the Cloud Agent side.
 
-
 ## Considered Options
 
 - Having issuers store and manage their own keys on the edge wallet (Prism 1.4 approach)
 - Storing keys in a dedicated wallet application that is connected to the Cloud Agent
 - Having the Cloud Agent store and manage keys directly
 
-
 ## Decision Outcome
 
 Chosen option: Option 3, because it is the simplest approach that satisfies the needs of providing the Issuer and Verifier with key storage while also not requiring them to manage their own keys. Option 3 was chosen instead of Option 2 because it achieves the same goal but does not require work on integrating another wallet application, so in short, it is simpler and faster to implement.
@@ -24,7 +22,6 @@ Chosen option: Option 3, because it is the simplest approach that satisfies the
 
 While Option 3 is simpler to implement then Option 2 and provides basic functionality required to solve the problem emphasized in [Context and Problem Statement](#context-and-problem-statement), it does not provide full functionality and security of widely used and well tested wallet application. Therefore this decision is considered to be temporary and made only in the interest of solving the problem as fast as possible.
 
-
 ## Links
 
 - [Recording of the meeting where decision was made](https://drive.google.com/file/d/120YyW2IEpl-F-6kF0V0Fau4bM7BbQ6mT/view?usp=sharing)
diff --git a/documentation/adrs/decisions/2023-01-18-quill-library-for-sql-statement-generation.md b/documentation/adrs/decisions/2023-01-18-quill-library-for-sql-statement-generation.md
index 772d397c5c..d4fd506bdf 100644
--- a/documentation/adrs/decisions/2023-01-18-quill-library-for-sql-statement-generation.md
+++ b/documentation/adrs/decisions/2023-01-18-quill-library-for-sql-statement-generation.md
@@ -19,6 +19,7 @@ it simply provides a functional way to construct programs (and higher-level libr
 doobie is a Typelevel project. 
 This means we embrace pure, typeful, functional programming, and provide a safe and friendly environment for teaching, learning, and contributing as described in the Scala Code of Conduct.
 ```
+
 Doobie is a good choice for DAL, and this ADR is about something other than replacing it.
 
 Writing the SQL statement and mapping the row to the case class is a boilerplate and error-prone activity that the Quill library can optimize.
diff --git a/documentation/adrs/decisions/2023-04-05-did-linked-resources.md b/documentation/adrs/decisions/2023-04-05-did-linked-resources.md
index b6f0256ccb..3aa01ae4c1 100644
--- a/documentation/adrs/decisions/2023-04-05-did-linked-resources.md
+++ b/documentation/adrs/decisions/2023-04-05-did-linked-resources.md
@@ -58,6 +58,7 @@ The following aspect must be taken into account for storing the resources in DLT
 Based on the nature of the resource the size limitations must be considered.
 
 For the following resource types and the common use cases 16KB should be enough, so it's possible to store these on DLT:
+
 - credential schema
 - credential definition
 - logo in SVG format
@@ -65,6 +66,7 @@ For the following resource types and the common use cases 16KB should be enough,
 - documentation in the markdown format
 
 For larger resource types IPFS or another option should be considered. Large resource examples:
+
 - media files
 - large documents
 - large revocation status lists
@@ -219,14 +221,12 @@ Looks like the ToIP specification is inspired by Cheqd's ADR.
 - discoverability: URI is replaced with DID URL that allows discovering the resource using Internal and/or Universal resolver
 - trust: the `checksum` is provided, so it is possible to verify that the resource was not modified by 3rd party
 
-
 #### Negative Consequences
 
 - scalability: the DID document should be updated when the new resource is created
 - interoperability: using the Universal Resolver is optional, so either SDK or internal application API must be used to fetch the resource
 - standard: the `linkedResourceMetadata` field is not a standard part of the DID specification, so the application should be aware of how to deal with it
 
-
 ### DID URL dereferencing (W3C specification)
 
 The current solution is based on the dereferencing algorithm described in the [DID-Resolution#dereferencing](https://w3c-ccg.github.io/did-resolution/#dereferencing) specification and describes how the DID resolver can dereference the resource linked to the DID. It does not describe where the resource is stored.
@@ -291,6 +291,7 @@ In this case, the DID Method may describe how the path should be resolved and th
 - scalability: the algorithm contains 2 or 3 steps and the DID Document is always must be resolved in the first step
 
 #### Out of the Scope
+
 - trust, longevity, and technology stack are not specified in this solution
 
 ### DID URL Dereferencing (Trust over IP specification - outdated)
@@ -366,8 +367,8 @@ This specification describes many important aspects:
 
 - longevity, and technology stack are not specified in this solution but must be guaranteed by the underlying DLT
 
-
 ### RootsID - Cardano AnonCreds (Implementation of ToIP at the Cardano stack)
+
 RootsID adopted the AnonCreds specification to store the credential schema and credential definition on the Cardano blockchain.
 
 Links to the implementation and the method description are in the #Links section for this ADR
@@ -389,15 +390,14 @@ As the solution is based on the latest ToIP specification, it derives all positi
 - technology stack: the solution is stateless and is much cheaper in terms of the infrastructure cost
 - technology stack: the solution is implemented in Python and TypeScript (mobile platforms can use the same approach as well)
 
-
 #### Negative Consequences
+
 - scalability: the specification is inspired by the Cheqd approach to store the linkedResourceMetadata inside of the DID Document
 - the convention for references and the logic must be carefully reviewed:
   - `schemaId` in this solution is `{didRef}/resources/{cardano_transaction_id}`, so it doesn't refer to the `id` but to the Tx where everything else is stored (it's an interesting idea for a stateless design)
   - resource metadata is built according to the ToIP specification but for AnonCreds entities only: credential schema and credential definition.
 - technology stack: it doesn't fit to current platform, but can be used for inspiration.
 
-
 ### Hyperledger AnonCreds
 
 According to the AnonCreds specification, such kinds of resources as credential schema and credential definition are stored on-chain. Indy blockchain is used by the Hyperledger technology stack.
@@ -450,6 +450,7 @@ Example of the credential schema transaction:
 ```
 
 The resource (credential schema) in the current example can be discovered using Indy SDK by the following id:
+
 ```
 Y6LRXGU3ZCpm7yzjVRSaGu:2:BasicIdentity:1.0.0
 ```
@@ -482,7 +483,6 @@ Are similar to the Hyperledger AnonCreds solution
 
 The main benefit of the Trinsic approach to storing resources is a good abstraction layer, documentation, REST API and a variety of supported programming languages in SDKs for dealing with underlying resources.
 
-
 ### Solution #1 (W3C with dynamic resource resolution)
 
 The solution for storing the resources linked to the DID depends on two decisions that are described in the Context and Problem Statement:
@@ -493,6 +493,7 @@ The solution for storing the resources linked to the DID depends on two decision
 Taking into account the advantages and disadvantages of the existing solutions the decision about the solution for the Identus platform might be the following:
 
 -the resource is linked to the DID by convention specified in the W3C specification, so specifying the resource in the DID URL and defining the service endpoint that exposes the resource allows to discover and fetch the resource using the Universal Resolver
+
 - as an option, the same resource can be discovered and fetched by the Identus platform backend and SDK without loading the Universal resolver
 - the resource integrity must be guaranteed by one of the following options:
   - by signing the payload with one of the DID's keys or
@@ -597,7 +598,6 @@ The version is skipped as for resolving the single resource we don't need a `ver
 
 So, having the following service endpoint definition in the DID Document:
 
-
 ```
 {  
   "service": [
@@ -717,7 +717,6 @@ The main benefits of option #1 for the Identus platform are the following:
 - this solution is scalable and decentralized (anyone can deploy the Identus stack)
 - level of trust can be guaranteed by the underlying VDR and enforced by hashes or signatures of the resource
 
-
 ## Links
 
 - [Our Approach to DID-Linked Resources](https://blog.cheqd.io/our-approach-to-resources-on-ledger-25bf5690c975)
@@ -730,4 +729,3 @@ The main benefits of option #1 for the Identus platform are the following:
 - [DID-Resolution#dereferencing](https://w3c-ccg.github.io/did-resolution/#dereferencing)
 - [RootsID AnonCreds Methods](https://github.com/roots-id/cardano-anoncreds/blob/main/cardano-anoncred-methods.md)
 - [RootsID Cardano AnonCreds repo](https://github.com/roots-id/cardano-anoncreds)
-
diff --git a/documentation/adrs/decisions/2023-05-09-message-routing-for-multi-tenant.md b/documentation/adrs/decisions/2023-05-09-message-routing-for-multi-tenant.md
index c5f67194c4..a501a9c1f8 100644
--- a/documentation/adrs/decisions/2023-05-09-message-routing-for-multi-tenant.md
+++ b/documentation/adrs/decisions/2023-05-09-message-routing-for-multi-tenant.md
@@ -6,6 +6,7 @@
 - Tags: multi-tenant, routing, message
 
 ## Context and Problem Statement
+
 The Cloud Agent in multi-tenancy is still a single agent running, however, some of the resources are now shared between the tenants of the agent.
 Each tenant has their own keys, with their own DIDs, connections. Transports and most of the settings are still shared between agents.
 All the API endpoints are same from outside
@@ -55,4 +56,4 @@ Backend services: Cloud Agent use PostgreSQL. Authentication and authorization
 
--->
\ No newline at end of file
+-->
diff --git a/documentation/adrs/decisions/2023-05-15-mediator-message-storage.md b/documentation/adrs/decisions/2023-05-15-mediator-message-storage.md
index aacd9f58c8..da83f2d2ed 100644
--- a/documentation/adrs/decisions/2023-05-15-mediator-message-storage.md
+++ b/documentation/adrs/decisions/2023-05-15-mediator-message-storage.md
@@ -6,6 +6,7 @@
 - Tags: storage, db, message, mongo, postgres, sql
 
 ## Context and Problem Statement
+
 Mediator storage
 Relational databases like PostgreSQL store data in structured tables, with rows and columns that help establish relationships between various tables and entities.
 SQL is used in PostgreSQL to save, retrieve, access, and manipulate the database data.
@@ -28,6 +29,7 @@ MongoDB Atlas. Fully managed MongoDB in the cloud which can reduce the infrastru
 Amazon DocumentDB (with MongoDB compatibility)  [https://aws.amazon.com/documentdb/]
 
 ## Decision Drivers
+
 - DIDCOMM messages are json based
 - flexibility to store the data
 - Reduce serialisation deserilisation of the data
@@ -36,6 +38,7 @@ Amazon DocumentDB (with MongoDB compatibility)  [https://aws.amazon.com/document
 - low maintainance
 
 ## Considered Options
+
 - PostgresSQL (Storing unstructured data (JSON) and quering data (JSON), scalability)
 - MongoDB (Storing unstructured data (JSON) and quering data (JSON), scalability)
 - Kafka Stream (Storing unstructured data (JSON) and quering data (JSON), scalability and streaming)
@@ -70,7 +73,6 @@ MongoDB provides flexibility with json storage and queries
 - Bad, Is not full ACID compliance
 - Bad, Doesn't natively support complex joins like a relational database
 
-
 ## Refrences used
 
 - [https://www.plesk.com/blog/various/mongodb-vs-postgresql/]
diff --git a/documentation/adrs/decisions/2023-05-16-hierarchical-deterministic-key-generation-algorithm.md b/documentation/adrs/decisions/2023-05-16-hierarchical-deterministic-key-generation-algorithm.md
index 44c0375d67..359bb3f767 100644
--- a/documentation/adrs/decisions/2023-05-16-hierarchical-deterministic-key-generation-algorithm.md
+++ b/documentation/adrs/decisions/2023-05-16-hierarchical-deterministic-key-generation-algorithm.md
@@ -16,6 +16,7 @@ Current ADR is based on the Research Spike [Evaluation of Using a Single Mnemoni
 - Tony Rose (Atala Head of Product)
 
 Reviewed in 2024 by Atala engineers:
+
 - Jesus Diaz Vico
 - Ezequiel Postan
 - Pat Losoponkul
@@ -58,7 +59,6 @@ Secure store implementation is a matter of another ADR. By now, the Hashicorp Va
 
 The current decision doesn't have backward compatibility with the PRISM v1.4, but it can be mitigated by switching to the `unmanaged` way of key management for the DIDs created in v1.4 or by implementing the backward compatibility module in the Identus Platform
 
-
 ## Decision Drivers
 
 - Deterministic key derivation for the Identus Platform and in all components: Cloud Agent (JVM), Identity Wallets (Android, iOS, Web)
@@ -96,6 +96,7 @@ m/wallet-purpose'/did-method'/did-index'/key-purpose'/key-index'
 `key-index` - the index of the key pair
 
 In order to generate key material (private and public keys):
+
 - Secp256k1 ellipstic curve will be used with standard bip32 derivation
 - Curve25519 (Ed25519) will be used with the standard bip32 implementation for [ed25519](https://ieeexplore.ieee.org/document/7966967)
 - Future implementations will require their own implementations of the derive function, and very potentially at some point we may want to rework bip32 implementation to make it more agnostic, because a high percentage of the code is going to be the same.
diff --git a/documentation/adrs/decisions/2023-05-18-data-isolation-for-multitenancy.md b/documentation/adrs/decisions/2023-05-18-data-isolation-for-multitenancy.md
index 923f432771..873f227cef 100644
--- a/documentation/adrs/decisions/2023-05-18-data-isolation-for-multitenancy.md
+++ b/documentation/adrs/decisions/2023-05-18-data-isolation-for-multitenancy.md
@@ -118,7 +118,6 @@ Moreover, for the SaaS application to manage thousands of organizations and mill
 - Logical Separation - PostgreSQL RSP allows to separate of the tenant data at the database level end and enforces the ACL using the policies
 - The Complexity of the Implementation - this option can be implemented on top of the current codebase without significant refactoring of the codebase and additional work for infrastructure engineers.
 
-
 ### Negative Consequences
 
 - Physical Separation - is not covered by this option
@@ -153,7 +152,6 @@ For each Wallet abstraction, the tenant must have the table or the schema with t
 - Bad, because the migration time and maintenance complexity is going to grow with the number of tenants
 - Bad, because `noisy neighbors` issue might occur when some tenant is actively using the Wallet and occupies the resources
 
-
 ### Database per Tenant and Instance per Tenant
 
 In this option, the data are physically isolated by using the database or the server instance per tenant.
@@ -172,6 +170,7 @@ Current options must be applied for SaaS solutions with a high number of tenants
 Both options serve the same goal - horizontal scaling of the instances of PostgreSQL
 
 The main advantages of Citus:
+
 - fits for on-premise deployments
 - provides additional monitoring and statistics to manage the tenants
 - routing to the shard is managed by Citus using the `hash` of the table index (compared to AWS sharding option, the routing is done at the application layer and the system table contains the information about the mapping of the tenant to the instance of the database)
diff --git a/documentation/adrs/decisions/2023-05-27-use-keycloak-and-jwt-tokens-for-authentication-and-authorisation-to-facilitate-multitenancy-in-cloud-agent.md b/documentation/adrs/decisions/2023-05-27-use-keycloak-and-jwt-tokens-for-authentication-and-authorisation-to-facilitate-multitenancy-in-cloud-agent.md
index 050aa57353..aa94c62927 100644
--- a/documentation/adrs/decisions/2023-05-27-use-keycloak-and-jwt-tokens-for-authentication-and-authorisation-to-facilitate-multitenancy-in-cloud-agent.md
+++ b/documentation/adrs/decisions/2023-05-27-use-keycloak-and-jwt-tokens-for-authentication-and-authorisation-to-facilitate-multitenancy-in-cloud-agent.md
@@ -135,4 +135,3 @@ Chosen option: "Keycloak with JWT tokens (without digital signatures)", because
 - [Information on OAuth 2.0 Token Binding - DPoP](https://tools.ietf.org/id/draft-ietf-oauth-dpop-03.html)
 - [Decentralized Identifiers (DIDs) documentation](https://www.w3.org/TR/did-core/)
 - [JWT vs Opaque Tokens](https://zitadel.com/blog/jwt-vs-opaque-tokens)
-
diff --git a/documentation/adrs/decisions/2023-06-28-apollo-as-centralised-and-secure-cryptography-management-module.md b/documentation/adrs/decisions/2023-06-28-apollo-as-centralised-and-secure-cryptography-management-module.md
index 9e23734678..dff868ee7a 100644
--- a/documentation/adrs/decisions/2023-06-28-apollo-as-centralised-and-secure-cryptography-management-module.md
+++ b/documentation/adrs/decisions/2023-06-28-apollo-as-centralised-and-secure-cryptography-management-module.md
@@ -12,6 +12,7 @@ Technical Story: [Apollo Cryptographic Module KMM | https://input-output.atlassi
 
### 1. Summary + This proposal sets out to crystallize a long-term plan for Identus' cryptographic functionality. Rather than constructing an entirely new cryptographic functionality, our focus is on integrating robust, secure and tested libraries, meeting several key requirements in the process. By leveraging the flexibility of Kotlin Multiplatform, this library will ensure strong, provable security, centralized management of all cryptography, easy upgrades, and efficient code reuse across multiple platforms. @@ -21,33 +22,41 @@ A significant additional advantage of our chosen framework, particularly for the
### 2. Introduction + This proposal outlines a comprehensive plan to develop a cryptographic library using Kotlin Multiplatform. This library will meet our defined requirements and strategically position us for future technological advancements. #### 2.1 Provable Security + Our cryptographic library will provide engineers with high assurances of security. This will be accomplished by using cryptographic primitives that are secure, with this security being provable through rigorous mathematical proofs. Documentation will accompany these proofs to offer transparency and enable a deeper understanding of the underlying logic and assurances. #### 2.2 Centralized Cryptography Management + We propose the creation of a cryptographic library that serves as the central management hub for all cryptographic operations within the Identus platform. By preventing "DIY" implementations, we decrease potential vulnerabilities and establish a standard, thus enhancing overall security across our organization. #### 2.3 Easy Upgrade Path + In light of emerging cryptographic needs such as the introduction of quantum-resistant cryptography, our library will be designed with easy upgrades in mind. Its modular design will allow for the seamless introduction of new cryptographic primitives as they become necessary or advisable. This adaptability will ensure that cryptographic upgrades across all of Identus' components are consistent and efficient. #### 2.4 Code Reusability + Our library will make the most of Kotlin Multiplatform's capabilities for code reuse across different platforms. We aim to design cryptographic functions that promote this potential, thus minimizing the development effort required for adding new functionality or adapting to different platforms.
### 3. Advantages of Kotlin Multiplatform + Choosing Kotlin Multiplatform for this project affords us several advantages, notably its potential to export to WASM. Not only this stack, but it significantly enhances the utility and versatility of our library, especially for our JavaScript version. While other languages like Rust offer similar capabilities, the use of Kotlin Multiplatform aligns more closely with our resource allocation and current technological strategy.
### 4. Trade Offs + The trade-off gap analysis does not come from the debate between having 1 single language (agnostic) or multiple native platform implementations as this discussion could end super quickly by just reading the 4 points in the Introduction section (Easy upgrade path, code reusability). The real debate is between choosing the right language that suits us best. We have been analyzing the potential use of Rust or KMM to build the Apollo module. #### 4.1 Advantages of KMM + Easier to have same interface for the cryptographic functionalities in all platforms Single Unit test suit to verify platform compatibility between platforms Version lock for supported library versions @@ -55,10 +64,12 @@ Less pron to compatibility errors between platforms When a new Platform is added to KMM we can easily test and verify with our code quality standards, if it passes we can add a new platform support #### 4.2 Disadvantages of KMM + KMM is very powerful but still has some issues the more complex the project is, in Apollo it should be quite straightforward High dependency on a single point of failure (This can be advantage and disadvantage) #### 4.3 Advantage of KMM against rust + KMM in this situation has great advantageous against Rust It might be more difficult to find libraries in Rust that can do all we require for all the platforms. Testing would not be so straightforward and By platform. It would instead run only on the platform that is building the code. @@ -67,6 +78,7 @@ Uniffi doesnt work for all platforms we provide, so some wrappers would have to
### 5. Implementation Details + We have established several key requirements for our team: 1. Ownership of Apollo and its roadmap is clearly defined. If any issues, doubts, or concerns arise or if any decisions need to be made about the roadmap, tech debt, or any other related aspects, stakeholders know who to contact. @@ -84,6 +96,7 @@ We have established several key requirements for our team:
### 6. Definition of Done + In order to consider this completed or done the existing SDK's must have integrated with this new Module.
@@ -99,6 +112,7 @@ In order to consider this completed or done the existing SDK's must have integra
#### Implementation resources + | Engineer | Role | Availability | |---------------------------------------|---------------------------------------------|--------------| | Francisco Javier RibΓ³ | Engineering Lead + Developer | Part time | @@ -112,11 +126,11 @@ In order to consider this completed or done the existing SDK's must have integra
### 8. Triage & future roadmap + The main goal of this section is to describe the process where we choose what comes next in Apollo and how we take those decisions. **Comments** - 1. There is a risk of starting to add to Apollo "anything that looks like cryptography". For instance, the Anoncreds part that takes care of formatting the credentials (which is what anoncreds-rs does) should not go into Apollo. 2. But the underlying cryptographic functionality (for which anoncreds-rs calls libursa) should go into Apollo. 3. Maybe something similar applies to HD wallets. diff --git a/documentation/adrs/decisions/2023-07-14-performance-framework-for-atala-prism.md b/documentation/adrs/decisions/2023-07-14-performance-framework-for-atala-prism.md index 383f73a30d..04deec0008 100644 --- a/documentation/adrs/decisions/2023-07-14-performance-framework-for-atala-prism.md +++ b/documentation/adrs/decisions/2023-07-14-performance-framework-for-atala-prism.md @@ -103,7 +103,6 @@ Cons: * Quite an expensive Cloud solution * New for us, some learning curve is expected - ### Gatling Strengths: @@ -136,7 +135,6 @@ Cons: * Supports a lot less of output formats than K6 * Distributed load generation is very complex, not natively integrated - ### Locust Strengths: diff --git a/documentation/adrs/decisions/2023-09-28-revocation-status-list-expansion-strategy.md b/documentation/adrs/decisions/2023-09-28-revocation-status-list-expansion-strategy.md index b65ea07606..fab8fb6a51 100644 --- a/documentation/adrs/decisions/2023-09-28-revocation-status-list-expansion-strategy.md +++ b/documentation/adrs/decisions/2023-09-28-revocation-status-list-expansion-strategy.md @@ -15,7 +15,6 @@ The specification recommends a minimum size of 16 KB for the status list include However, it does not delineate a maximum size, nor does it provide guidance on how to proceed if the selected status list surpasses its capacity to store information about revoked credentials. Put differently, if more credentials are issued than can be accommodated by a 16 KB status list, no specific instructions are provided. - ## Decision Drivers We must determine a strategy for expanding the revocation status list to accommodate the increasing number of revoked credentials in the future. @@ -28,10 +27,8 @@ In the future, there might be a need to reorganize the state and possibly move s Absolutely, it's crucial to avoid overengineering the solution. This ensures that the code remains manageable and easy to maintain in the long run. - ## Considered Options - Option 1: Increment status list size as we approach its limit: We'll enhance the status list by simply doubling its size. @@ -45,11 +42,10 @@ With this approach, we'll generate and store multiple status list credentials. It will be crucial to ensure that each credential is linked to a specific status list, allowing us to track where the revocation information is stored. If we stick with the smallest recommended status list size, one revocation status list can hold information about 131,072 revocable credentials. - ## Pros and Cons of the Options - #### Option 1 + Option 1 offers the primary advantage of being straightforward to implement. It is also important to note that Option 2 isn't significantly more challenging to implement, so we shouldn't overly prioritize this consideration. @@ -68,16 +64,13 @@ Initially, both options face the same issue with a small anonymity set due to th As the number of VCs increases, Option 1 maintains a continuously growing anonymity set. However, in Option 2, when the issuer reaches the 16KB limit and creates a new list, there will be a period where the new list has only a few VCs, resulting in a smaller anonymity set for VCs in the second list. - Option 2 however, has a big advantage considering upcoming need for AnonCreds revocation. AnonCreds doesn't allow for expanding the status list size once defined during revocation registry creation. Pushing back Option 2 for AnonCreds and starting with an initial capacity of 1 million credentials may not be efficient. The size of the attached TAILS FILE grows rapidly with capacity (e.g., 8.4MB for 32,768 VCs!). This file needs to be resolved/downloaded by the holder during the issuance process. - ## Decision Outcome Given that the implementation of Option 2 is not significantly more complicated than Option 1, and considering that JWT credentials, specifically statusList2021, are not inherently private, we have decided to proceed with Option 2. This choice is more future-proof, especially in light of the anticipated need to implement AnonCreds revocation in the future. - diff --git a/documentation/adrs/decisions/2024-01-03-use-jwt-claims-for-agent-admin-auth.md b/documentation/adrs/decisions/2024-01-03-use-jwt-claims-for-agent-admin-auth.md index e1d012d9c7..efe8079450 100644 --- a/documentation/adrs/decisions/2024-01-03-use-jwt-claims-for-agent-admin-auth.md +++ b/documentation/adrs/decisions/2024-01-03-use-jwt-claims-for-agent-admin-auth.md @@ -88,6 +88,7 @@ Example JWT payload containing `ClientRole`. (Some claims are omitted for readab } } ``` + The claim is available at `resource_access..roles` by default. The path to the claim should be configurable by the agent to avoid vendor lock and remain agnostic to the IAM configuration. @@ -132,6 +133,7 @@ For the agent, it needs to support 2 roles: - Bad, because roles are at the realm level, making it hard to support some topology *Note: This option is equally applicable as Option 1, depending on the required topology.* + ### Option 3: Use custom user attribute for defining roles in Keycloak - Bad, because role abstraction is already provided by Keycloak. Engineering effort is spent to reinvent the same concept diff --git a/documentation/adrs/decisions/2024-01-15-Error-handling-report-problem-agent.md b/documentation/adrs/decisions/2024-01-15-Error-handling-report-problem-agent.md index d446a29c3f..2a68735aea 100644 --- a/documentation/adrs/decisions/2024-01-15-Error-handling-report-problem-agent.md +++ b/documentation/adrs/decisions/2024-01-15-Error-handling-report-problem-agent.md @@ -30,7 +30,6 @@ If an error occurs in this background job over DIDComm in Agent A, it is recorde What are our needs? Let’s try to sum up the required capabilities based on [Report Problem 2.0](https://identity.foundation/didcomm-messaging/spec/#problem-reports), we need: - The Cloud Agent is designed to perform three distinct roles: `Issuer`, `Holder`, and `Verifier`. Within these roles, it operates across three protocol flows, namely `Connection`, `Issuance`, and `Verification`. @@ -96,7 +95,6 @@ it operates across three protocol flows, namely `Connection`, `Issuance`, and `V - **C4** - Max retries (Cascading Problems): Connection state cannot be moved after max retries - **C5** - See G3 - ## Issuance Flow Scenarios [https://github.com/decentralized-identity/waci-didcomm/tree/main/issue_credential] @@ -117,7 +115,6 @@ it operates across three protocol flows, namely `Connection`, `Issuance`, and `V - **I5** - Max retries (Cascading Problems): Issuance state cannot be moved after max retries - **I6** - See G3 - ## Verification(Present proof) Flow Scenarios [https://github.com/decentralized-identity/waci-didcomm/blob/main/present_proof/present-proof-v3.md] @@ -164,5 +161,3 @@ In the event of an issue in the Cloud Agent, the following actions are taken: 2. [Replying to Warnings](https://identity.foundation/didcomm-messaging/spec/#replying-to-warnings) 3. [ACKs](https://identity.foundation/didcomm-messaging/spec/#acks) - - diff --git a/documentation/adrs/decisions/2024-03-07-handle-errors-in-bg-jobs-by-storing-on-state-records-and-sending-via-webhooks.md b/documentation/adrs/decisions/2024-03-07-handle-errors-in-bg-jobs-by-storing-on-state-records-and-sending-via-webhooks.md index 7cf6e1e6a1..5c9ab4ad44 100644 --- a/documentation/adrs/decisions/2024-03-07-handle-errors-in-bg-jobs-by-storing-on-state-records-and-sending-via-webhooks.md +++ b/documentation/adrs/decisions/2024-03-07-handle-errors-in-bg-jobs-by-storing-on-state-records-and-sending-via-webhooks.md @@ -22,10 +22,12 @@ While the DIDComm Error Reporting protocol effectively handles errors in peer-to ## Considered Options 1. Storing error information in database records + - Storing in RFC 9457 Problem Details for HTTP APIs format - Storing in proprietary format - Storing as ZIO.Failure string (as is) - Enhancing the API to return this attribute of the record when checking the status of an operation + 2. Creating a central registry of errors 3. Using existing webhook system to send errors to clients 4. Implementing event-driven error notifications @@ -80,4 +82,4 @@ We have opted for enhanced error handling by storing error details on background ## Links -- [DIDComm Messaging Specification](https://identity.foundation/didcomm-messaging/spec/) \ No newline at end of file +- [DIDComm Messaging Specification](https://identity.foundation/didcomm-messaging/spec/) diff --git a/documentation/adrs/decisions/2024-05-20-use-did-urls-to-reference-resources.md b/documentation/adrs/decisions/2024-05-20-use-did-urls-to-reference-resources.md index 62fb3d61d2..a2b611ba29 100644 --- a/documentation/adrs/decisions/2024-05-20-use-did-urls-to-reference-resources.md +++ b/documentation/adrs/decisions/2024-05-20-use-did-urls-to-reference-resources.md @@ -1,11 +1,10 @@ -# Storage for SSI related resources +# Storage for SSI related resources -- Status: accepted -- Deciders: Javi, Ben, Yurii +- Status: accepted +- Deciders: Javi, Ben, Yurii - Date: 2024-05-20 - Tags: Verifiable Data Registry (VDR), decentralized storage - ## Context and Problem Statement The main question to answer is: What is the most practical way to store resources related to VC verification and revocation? @@ -28,18 +27,19 @@ A desired solution should balance We considered the following alternatives, which contemplate the approaches currently discussed by the broad SSI ecosystem at the time of this writing. - URLs and traditional HTTP servers: with no surprises, in this approach, each resource is identified with a URL and stored in traditional servers. The URLs will encode hashes as query parameters to enforce integrity for static resources. Dynamic resources will be signed by the resource creator's key. -- DID URLs and traditional HTTP servers: in this variation, resources are still stored in servers. Resources are identified by DID URLs that dereference services of the associated DID document. The services will contain the final URL to retrieve the corresponding resources. Once again, hashes will be associated to static resources as DID URL query parameters, while dynamic resources will be signed adequately. +- DID URLs and traditional HTTP servers: in this variation, resources are still stored in servers. Resources are identified by DID URLs that dereference services of the associated DID document. The services will contain the final URL to retrieve the corresponding resources. Once again, hashes will be associated to static resources as DID URL query parameters, while dynamic resources will be signed adequately. - IPFS: An IPFS approach would be useful for storing static resources using IPFS identifiers for them. Dynamic resources however become more challenges. Even though we recognize the existence of constructions like IPNS or other layers to manage dynamic resources, we find them less secure in terms of availability and consistency guarantees. -- Ledger based storage (Cardano in particular): In this approach, resources would be stored in transactions' metadata posted on-chain. The data availability and integrity can be inherited from the underlying ledger. +- Ledger based storage (Cardano in particular): In this approach, resources would be stored in transactions' metadata posted on-chain. The data availability and integrity can be inherited from the underlying ledger. - A combination of previous methods and the use of a ledger: Similar as above, data references are posted on-chain, but the actual resources are stores in servers. The servers could be traditional HTTP servers or IPFS nodes. ## Decision Outcome After a careful analysis we concluded the following points: + - There is an architectural need to develop a "proxy" component, a.k.a. VDR proxy, that would work as a first phase for resource resolution. Behind the VDR proxy, different storage implementations could be added as extensions - With respect to specific implementations - + ledger based storage at this stage introduces latency, throughput bottlenecks, costs and other issues not suitable for most use cases. - + Hybrid solutions that make use of a ledger share similar drawbacks. + + ledger based storage at this stage introduces latency, throughput bottlenecks, costs and other issues not suitable for most use cases. + + Hybrid solutions that make use of a ledger share similar drawbacks. + Decentralized Hash Tables (such as IPFS) do not provide efficient handling for dynamic resources (such as revocation lists). + We concluded that a reasonable first iteration could be delivered using DID URLs to identify resources while they would be, a priori, stored in traditional HTTP servers. @@ -52,11 +52,10 @@ After a careful analysis we concluded the following points: - There is a level of under-specification at W3C specifications with respect to DID URL dereferencing. This forces us to define the under-specificied behaviour or simply creata-our-own solution. -## Links +## Links We leave a list of useful links for context - [AnonCreds Methods Registry](https://hyperledger.github.io/anoncreds-methods-registry/) - [AnonCreds Specification](https://hyperledger.github.io/anoncreds-spec/) - [W3C DID resolution algorithm](https://w3c-ccg.github.io/did-resolution/) - diff --git a/documentation/develop/README.md b/documentation/develop/README.md index 312c955831..2c94104395 100644 --- a/documentation/develop/README.md +++ b/documentation/develop/README.md @@ -35,6 +35,7 @@ Build wallet applications for web and mobile platforms using our comprehensive S #### [TypeScript SDK](../../sdk-ts/docs/sdk/README.md) Build browser and Node.js applications with full support for: + - DIDComm messaging - Credential issuance and presentation - AnonCreds, SD-JWT, and JWT credentials @@ -42,6 +43,7 @@ Build browser and Node.js applications with full support for: - Backup and recovery **Tutorials available:** + - [Storage with Pluto](../../sdk-ts/docs/pluto/README.md) - [PRISM DID Management](../../sdk-ts/docs/prism/what-is-did-prism.md) - [Connectionless & Out-of-Band](../../sdk-ts/docs/develop/sdk/tutorials/connectionless/ConnectionlessOffer.md) @@ -133,6 +135,7 @@ This modular architecture provides flexibility to customize solutions for specif ### Connection Establishment Agents establish secure DIDComm connections using: + - **Direct invitations** - For known parties with existing connections - **Out-of-Band (OOB) invitations** - QR codes or deep links for new connections - **Mediator routing** - Message delivery for offline/mobile wallets diff --git a/documentation/develop/cloud-agent/authentication.md b/documentation/develop/cloud-agent/authentication.md index cafe54869f..027945ab20 100644 --- a/documentation/develop/cloud-agent/authentication.md +++ b/documentation/develop/cloud-agent/authentication.md @@ -19,20 +19,18 @@ entity is verified and authenticated during interactions with the platform: The Cloud Agent uses the Default Entity and the Default Wallet for all interactions with the Agent over the REST API and DIDComm in the single-tenant mode. A Default Entity is an entity with the id `00000000-0000-0000-0000-000000000000`, and a Default Wallet is a wallet with the id `00000000-0000-0000-0000-000000000000`. - ## API Key Authentication ### Introduction API Key Authentication is a straightforward method used to authenticate entities by utilizing a secret key. This method requires the inclusion of an `apikey` header in HTTP requests, with the value corresponding to the issued secret key. The configuration of API Key Authentication for an entity is managed by the Administrator using the Entity API methods. - ### Security and Restrictions + - **API Key Length**: To maintain robust security, the length of the API Key value must exceed 16 bytes (128 bits). This length requirement is essential for enhancing the security of your API Key against potential attacks. The max length of the API Key value is limited to 128 bytes. Unique API Keys: Each API Key is unique to a specific entity. It cannot be shared or reused by other entities. If an attempt to assign the same API Key value to another entity, the API Key is considered compromised and must be considered unusable. - **Unique API Keys:** Each API Key is unique to a specific entity. It cannot be shared or reused by other entities. If an attempt to assign the same APIKey value to another entity, the APIKey is considered compromised and must be considered unusable. - **Revocation:** In case of a tenant's API Key revocation, it becomes invalid for authentication. - ### Agent Responsibilities The Agent manages API Keys for each tenant and maintains the security of the system: @@ -40,8 +38,6 @@ The Agent manages API Keys for each tenant and maintains the security of the sys - **API Key Storage:** The Agent maintains each tenant's APIKeys list. However, it is essential to note that the original value of the APIKey is not stored in the Agent, ensuring additional security. - **Hashing and Authentication:** The Agent securely stores the hash of the APIKey in the database and uses it to authenticate the entity. The hashing process employs the `SHA-256` algorithm and a `salt` value to compute the hash value, ensuring data integrity and security during authentication. The length of the `salt` value must exceed 16 bytes (128 bits) - - Based on the configuration API Key authentication, the Cloud Agent can support the following interaction models: ### Single Tenant without apikey authentication @@ -52,11 +48,9 @@ Disable API key authentication and use the Default Wallet for all interactions w |----------------------|-------| | API_KEY_ENABLED | false | - - ### Single Tenant with apikey authentication -Enable API key authentication and use the Default Wallet for all interactions with the Cloud Agent over the REST API and DIDComm. +Enable API key authentication and use the Default Wallet for all interactions with the Cloud Agent over the REST API and DIDComm. | Environment Variable | Value | |--------------------------------------|-------| @@ -72,7 +66,6 @@ Enable APIKey authentication and use the Entity and the Wallet associated with t | API_KEY_ENABLED | true | | API_KEY_AUTHENTICATE_AS_DEFAULT_USER | false | - ### Multi-Tenant with apikey authentication and auto-provisioning Enable APIKey authentication and use the Wallet associated with the APIKey for all interactions with the Cloud Agent. Automatically register the tenant's Entity, Wallet, and API key during the first interaction with the Cloud Agent over the REST API. @@ -96,7 +89,6 @@ The following REST APIs get protected by the Admin-Api-Key authentication method - Wallet Management REST API - Entity Management REST API - ## JWT Token Authentication and Authorisation with the Keycloak ### Introduction @@ -201,8 +193,8 @@ and the `KEYCLOAK_ROLES_CLAIM_PATH` should be set to `resource_access./dids/peer//keys/ value= ``` -## Links: +## Links - [HashiCorm Vault](https://www.vaultproject.io/) - [Vault KV Secrets Engine](https://www.vaultproject.io/docs/secrets/kv/kv-v2) diff --git a/documentation/develop/cloud-agent/troubleshooting&considerations.md b/documentation/develop/cloud-agent/troubleshooting&considerations.md index 6cfc8faf06..705e021e7d 100644 --- a/documentation/develop/cloud-agent/troubleshooting&considerations.md +++ b/documentation/develop/cloud-agent/troubleshooting&considerations.md @@ -1,9 +1,11 @@ # 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 @@ -52,6 +54,7 @@ We should consider configuring the logging Options in the **Docker Daemon**. For } } ``` + 3. Restart the Docker daemon to apply the new settings: ```shell diff --git a/documentation/develop/cloud-agent/vdr.md b/documentation/develop/cloud-agent/vdr.md index add1dc5f41..56e8633e8d 100644 --- a/documentation/develop/cloud-agent/vdr.md +++ b/documentation/develop/cloud-agent/vdr.md @@ -86,6 +86,7 @@ The Cloud Agent supports multiple VDR drivers for different use cases: For all VDR environment variables, see the [Environment Variables](./environment-variables.md) documentation. **Choosing a driver**: + - **Development/Testing**: Use `memory` or `database` drivers for fast iteration without blockchain overhead - **Blockchain-backed storage (recommended)**: Use `neoprism` driver with NeoPRISM for modern REST-based integration - **Blockchain-backed storage (legacy)**: Use `prism-node` driver for existing PRISM Node deployments @@ -98,6 +99,7 @@ For all VDR environment variables, see the [Environment Variables](./environment The NeoPrism driver stores VDR entries on the Cardano blockchain through a [NeoPRISM](/documentation/learn/advanced-explainers/neoprism/) instance. This is the **recommended** blockchain-backed VDR driver for new deployments, offering a modern REST API, lightweight resource usage, and full VDR lifecycle management. The Cloud Agent communicates with NeoPRISM via HTTP to: + - Submit signed VDR operations (create, update, deactivate) to the Cardano blockchain - Resolve VDR entry data and metadata - Query operation status @@ -192,12 +194,14 @@ VDR_DEFAULT_KEY_ID=vdr-1 The PRISM driver stores data on the Cardano blockchain, providing decentralized, permanent, and verifiable storage. Unlike the in-memory and database drivers which store data locally for testing, the PRISM driver offers blockchain-backed guarantees suitable for deployments requiring blockchain permanence. **Key capabilities**: + - Data stored on Cardano blockchain, not controlled by any single entity - Permanent, immutable storage that persists beyond agent lifecycle - Publicly verifiable by anyone with blockchain access - Designed for scenarios requiring blockchain auditability **Best suited for**: + - Deployments requiring public, decentralized verification - Credential status lists that must remain accessible indefinitely - Use cases with regulatory requirements for tamper-proof storage @@ -239,6 +243,7 @@ Configure the PRISM driver using these environment variables: | `VDR_PRISM_DRIVER_PRIVATE_NETWORK_PROTOCOL_MAGIC` | Option B | Protocol magic number for private network | `42` | **⚠️ Network Configuration**: You MUST configure exactly ONE network option: + - **Option A** (Public Blockfrost): Set `VDR_PRISM_DRIVER_BLOCKFROST_API_KEY` only - **Option B** (Private Network): Set both `VDR_PRISM_DRIVER_PRIVATE_NETWORK_URL` and `VDR_PRISM_DRIVER_PRIVATE_NETWORK_PROTOCOL_MAGIC` @@ -319,6 +324,7 @@ The underlying [PRISM VDR driver library](https://github.com/hyperledger-identus | PRISMDriverMongoDBWithIndexer | MongoDB + indexing | ❌ Not available | βœ… Available | All implementations share the same protocol parameters: + - **Driver Family**: `PRISM` - **Driver Version**: `1.0` diff --git a/documentation/develop/quick-start.md b/documentation/develop/quick-start.md index 94f262e976..49c8890bf3 100644 --- a/documentation/develop/quick-start.md +++ b/documentation/develop/quick-start.md @@ -9,13 +9,14 @@ import TabItem from '@theme/TabItem'; ## Pre-Requisites - ### Agent Deployment + This guide will demonstrate a single-tenant deployment with API Key authentication disabled and an in-memory ledger for published DID storage, which is the simplest configuration to get started as a developer. More advanced configuration options can be found in [Multi-Tenancy Management](/tutorials/multitenancy/tenant-onboarding) and associated [Environment Variables](/home/identus/cloud-agent/environment-variables) configuration options. We develop on modern machines equipped with either Intel based x64 processors or Apple ARM processors with a minimum of four cores, 16 GB of memory and 128GB+ of SSD-type storage. 1. To spin up an Cloud Agent you must: + * Have Git installed. * Have Docker installed. * Clone the [Identus Cloud Agent repository](https://github.com/hyperledger/identus-cloud-agent). @@ -24,10 +25,8 @@ We develop on modern machines equipped with either Intel based x64 processors or git clone https://github.com/hyperledger/identus-cloud-agent ``` - 2. Once cloned, create a new file named __./identus-cloud-agent/infrastructure/local/.env-issuer__ to define the Issuer Agent environment variable configuration with the following content: - ``` API_KEY_ENABLED=false AGENT_VERSION=2.0.0 @@ -40,8 +39,6 @@ PG_PORT=5432 3. Create a new file named __./identus-cloud-agent/infrastructure/local/.env-verifier__ to define the Verifier Agent environment variable configuration with the following content: - - ``` API_KEY_ENABLED=false AGENT_VERSION=2.0.0 @@ -62,41 +59,42 @@ API_KEY_ENABLED disables API Key authentication. This should **not** be used bey 5. Start the `issuer` and `verifier` Cloud Agents by running the below commands in the terminal. + * Issuer Cloud Agent: - - * Issuer Cloud Agent: - Mac OSX terminal shell + ```bash ./infrastructure/local/run.sh -n issuer -b -e ./infrastructure/local/.env-issuer -p 8000 -d "$(ipconfig getifaddr $(route get default | grep interface | awk '{print $2}'))" ``` + Linux terminal shell + ```bash ./infrastructure/local/run.sh -n issuer -b -e ./infrastructure/local/.env-issuer -p 8000 -d "$(ip addr show $(ip route show default | awk '/default/ {print $5}') | grep 'inet ' | awk '{print $2}' | cut -d/ -f1)" ``` * The Issuer [API endpoint](http://localhost:8000/cloud-agent/) will be accessible on port 8000 `http://localhost:8000/cloud-agent/` with a [Swagger Interface](http://localhost:8000/cloud-agent/redoc) available at `http://localhost:8000/cloud-agent/redoc`. - * Verifier Cloud Agent: For Mac OSX terminal shell + ```bash ./infrastructure/local/run.sh -n verifier -b -e ./infrastructure/local/.env-verifier -p 9000 -d "$(ipconfig getifaddr $(route get default | grep interface | awk '{print $2}'))" ``` + For Linux terminal shell + ```bash ./infrastructure/local/run.sh -n verifier -b -e ./infrastructure/local/.env-verifier -p 9000 -d "$(ip addr show $(ip route show default | awk '/default/ {print $5}') | grep 'inet ' | awk '{print $2}' | cut -d/ -f1)" ``` - * The Verifier [API endpoint](http://localhost:9000/cloud-agent/) will be accessible on port 9000 `http://localhost:9000/cloud-agent/` with a [Swagger Interface](http://localhost:9000/cloud-agent/redoc) available at `http://localhost:9000/cloud-agent/redoc`. - - ### Agent configuration #### Creating LongForm PrismDID + 1. Run the following API request against your Issuer API to create a PRISM DID: :::note @@ -142,7 +140,6 @@ curl --location \ ::: - #### Create a credential schema (JWT W3C Credential) 1. To create a [credential schema](/documentation/learn/glossary/#credential-schema) on the Issuer API instance, run the following request: @@ -209,8 +206,8 @@ curl -X 'POST' \ }' ``` - ### Starting Sample App + All wallet SDK's come bundled with a sample application, that cover all the Identus flows, including establishing connections, issuance, and verification flows. @@ -234,6 +231,7 @@ curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh ``` 3. Run the following: + * Build the source SDK: ```bash @@ -244,6 +242,7 @@ npm run build ``` * Start the React demo: + ```bash cd demos/next npm i @@ -266,6 +265,7 @@ git clone https://github.com/hyperledger/identus-edge-agent-sdk-swift 3. On the top left of the XCode window you will see a Play/Run button, click it. 4. The app will start. 5. Click Wallet Demo 2.0 + * You will be able to run the rest of the guide here. @@ -281,15 +281,18 @@ git clone https://github.com/hyperledger/identus-edge-agent-sdk-kmm 3. In the `Run configuration` dropdown, select SampleApp. 4. Select the device or emulator you want to use. 5. Click "Run". + * The SampleApp will launch on the applicable device or emulator. ### Deploy & Establish Mediation + Mediation is the process that ensures messages get routed and stored correctly between Issuers, Verifiers and Holders, even if they are offline. The mediator offers a service that is always running and can securely store messages and deliver them to the associated DIDs using DIDComm. This enables use-cases where connectivity to a (mobile) wallet cannot be guaranteed. #### Preparation + 1. To get the mediator deployed locally for the demo, clone the [Mediator repository](https://github.com/hyperledger/identus-mediator). ```bash @@ -305,10 +308,13 @@ The latest mediator version can be found at [Mediator releases](https://github.c ::: Mac OSX terminal shell + ```bash MEDIATOR_VERSION=1.1.0 SERVICE_ENDPOINTS="http://$(ipconfig getifaddr $(route get default | grep interface | awk '{print $2}')):8080;ws://$(ipconfig getifaddr $(route get default | grep interface | awk '{print $2}')):8080/ws" docker compose up ``` + Linux terminal shell + ```bash MEDIATOR_VERSION=1.1.0 SERVICE_ENDPOINTS="http://$(ip addr show $(ip route show default | awk '/default/ {print $5}') | grep 'inet ' | awk '{print $2}' | cut -d/ -f1):8080;ws://$(ip addr show $(ip route show default | awk '/default/ {print $5}') | grep 'inet ' | awk '{print $2}' | cut -d/ -f1):8080/ws" docker compose up ``` @@ -317,8 +323,6 @@ MEDIATOR_VERSION=1.1.0 SERVICE_ENDPOINTS="http://$(ip addr show $(ip route show 3. More advanced documentation and configuration options can be found [here](https://github.com/hyperledger/identus-mediator). - - 4. Now you need to capture the Mediator's [Peer DID](/documentation/learn/glossary/#peer-did) in order to start DIDCOMM V2 Mediation protocol, you can do so by opening you browser at the mediators [endpoint](/documentation/learn/glossary/#endpoints). #### Demo application @@ -340,7 +344,7 @@ Follow the steps in your desired platform as stated below: -1. Open http://localhost:3000/debug in your browser, +1. Open http://localhost:3000/debug in your browser, 1. paste the mediator peer DID (obtained from the `from` attribute after fetching from the mediator's invitation endpoint), 1. click **Edge Agent** tab in the bottom left, 1. click **Connect** button, @@ -360,8 +364,6 @@ Follow the steps in your desired platform as stated below: - - 2. If you are running the SampleApp, click the **Start Agent** button. The below code examples show how to establish mediation when building your own application. @@ -372,7 +374,6 @@ The below code examples show how to establish mediation when building your own a - ```typescript const mediatorDID = SDK.Domain.DID.fromString( [[MEDIATOR DID PEER]] @@ -408,7 +409,6 @@ The below code examples show how to establish mediation when building your own a - ```swift let agent = CloudAgent(mediatorDID: did) try await agent.start() @@ -418,7 +418,6 @@ The below code examples show how to establish mediation when building your own a - ```kotlin val apollo = ApolloImpl() val castor = CastorImpl(apollo) @@ -454,12 +453,15 @@ agent.startFetchingMessages() ## Establish Holder connections + To connect the Holder to both Cloud Agent instances, you must run this in both Issuer and Verifier endpoints. ### Establish a connection - Agent side + A connection must be established between the Holder and Cloud Agents to correctly deliver the Issuance + Verification Messages to the Holder. #### Establish connection on the Issuer Cloud Agent + ```bash curl --location \ --request POST 'http://localhost:8000/cloud-agent/connections' \ @@ -474,6 +476,7 @@ curl --location \ * Copy the `invitationUrl` and the `connectionId`. #### Establish connection on the Verifier Cloud Agent + ```bash curl --location \ --request POST 'http://localhost:9000/cloud-agent/connections' \ @@ -488,22 +491,25 @@ curl --location \ * Copy the `invitationUrl` and the `connectionId`. ### Establish a connection - Holder side + 3. Now that you have the invitation, it's time for the Holder to accept it. #### Demo application + 4. Open a browser at localhost:3000. 5. Start the Edge Agent by clicking the button. 6. Paste the invitation URL generated in the previous step into the `CloudAgent` connection section and click on Create Connection. - * The application will react when the connection gets established correctly and show a new connection. + * The application will react when the connection gets established correctly and show a new connection. 4. On the Out of Bounds (OOB) dialog, paste the invitation URL we generated into the `CloudAgent` connection section and click **Validate**. + * The application will respond once the connection gets established correctly and show a message under messages. @@ -512,8 +518,8 @@ curl --location \ 4. Go back to the Application: 5. Click the floating button at the bottom right corner of the Contacts tab. 6. On the dialog, paste the invitation URL we generated into the `CloudAgent` connection section and click **Validate**. - * The application will react once the connection gets established correctly and show a message under messages. + * The application will react once the connection gets established correctly and show a message under messages. @@ -551,6 +557,7 @@ agent.acceptOutOfBandInvitation(invitation) The credential issuance flow consists of multiple steps, detailed in this section. It starts with the Issuer sending a [Credential Offer](/documentation/learn/glossary/#credential-offer) to the Holder, which would accept or reject this invitation and create a `credentialRequest` from it. The [credential request](/documentation/learn/glossary/#credential-request) gets sent through DIDComm to the Issuer, issuing and sending the credential back to the Holder. 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 @@ -592,6 +599,7 @@ curl --location --request POST 'http://localhost:8000/cloud-agent/issue-credenti "automaticIssuance": true }' ``` + ### Create a Credential Offer as Invitation for connectionless issuance **Issuer Agent** @@ -630,11 +638,12 @@ curl --location --request POST 'http://localhost:8000/cloud-agent/issue-credenti }' ``` - ### 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 + @@ -699,8 +708,8 @@ automaticIssuance is optional. It can also be manually triggered and confirmed b ::: - #### Demo application + 3. The holder will at some point receive a `CredentialOffer`, which the holder must accept, and then, a `CredentialRequest` is created and sent back to the Issuer through DIDComm V2 protocols. @@ -718,7 +727,6 @@ automaticIssuance is optional. It can also be manually triggered and confirmed b - Code examples 5. The exchange between CredentialOffer and CredentialRequest is demonstrated through more advanced code samples below, showcasing how different platforms handle it. @@ -803,6 +811,7 @@ agent.handleReceivedMessagesEvents().collect { list -> ### Store the Issued Credential [Holder] + :::caution The sample application are using an insecure storage solution which should only be used for testing purposes and not production environments! @@ -815,8 +824,6 @@ The sample application are using an insecure storage solution which should only - - ```typescript props.agent.addListener(ListenerKey.MESSAGE,async (newMessages:SDK.Domain.Message[]) => { //newMessages can contain any didcomm message that is received, including @@ -859,7 +866,6 @@ agent - ```kotlin agent.handleReceivedMessagesEvents().collect { list -> list.forEach { message -> @@ -878,6 +884,7 @@ agent.handleReceivedMessagesEvents().collect { list -> ## Request a verification from the Verifier Cloud Agent to the Holder (JWT W3C Credential) + Now that the Holder has received a credential, it can be used in a verification workflow between a Holder and a Verifier. This requires the following steps: 1. Verifier creates a proof request @@ -891,10 +898,11 @@ 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 + @@ -924,7 +932,7 @@ curl --location \ * This API request will return a `presentationRequestId,` which the verifier can use later to check the current status of the request. - + 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. @@ -956,7 +964,9 @@ curl --location \ ### Accept Request Presentation invitation for connectionless verification **Holder** For connectionless verification, the Holder needs to accept the invitation containing the Request Presentation. + #### Demo application + @@ -1012,8 +1022,6 @@ agent.acceptOutOfBandInvitation(invitation) - - ### Holder: Receives the Presentation proof request 6. The Holder needs an Edge Agent running with the message listener active. It will receive the presentation proof request from the Verifier Cloud Agent for the correct type of messages as detailed below: @@ -1107,7 +1115,7 @@ agent.handleReceivedMessagesEvents().collect { list -> -### Verifier: Will then check on the API if the Presentation Request has been completed or not. +### Verifier: Will then check on the API if the Presentation Request has been completed or not ```bash curl --location \ diff --git a/documentation/develop/sidebar.ts b/documentation/develop/sidebar.ts index 073dc87434..98ff616788 100644 --- a/documentation/develop/sidebar.ts +++ b/documentation/develop/sidebar.ts @@ -46,4 +46,4 @@ const sidebar: SidebarsConfig[keyof SidebarsConfig] = [ ] -export default sidebar \ No newline at end of file +export default sidebar diff --git a/documentation/learn/README.md b/documentation/learn/README.md index c6343c7095..275ca6c841 100644 --- a/documentation/learn/README.md +++ b/documentation/learn/README.md @@ -3,17 +3,19 @@ sidebar_position: 1 --- # About Hyperledger Identus -Identity is about access. It is the key that unlocks doors we wish to enter. To stream movies, we need access to get into the virtual theater. Today, we do that by having an account with a streaming service, which authenticates us into the lobby. + +Identity is about access. It is the key that unlocks doors we wish to enter. To stream movies, we need access to get into the virtual theater. Today, we do that by having an account with a streaming service, which authenticates us into the lobby. We need authorization to enter the theater to watch the movie, which requires a service plan. Which selection will determine whether we can watch in standard, high definition, or 4k. -This example is repeatable across all interactions: banking, insurance, online services, shopping, investing, education, traveling, driving, etc. Identity may be the most essential thing we undervalue in our lives. We use it to physically and digitally access goods and services locally and globally. +This example is repeatable across all interactions: banking, insurance, online services, shopping, investing, education, traveling, driving, etc. Identity may be the most essential thing we undervalue in our lives. We use it to physically and digitally access goods and services locally and globally. ## Self-Sovereign Identity (SSI) -[Self-sovereign identity](/documentation/learn/glossary/#self-sovereign-identity) introduces new concepts that flip the existing identity models. The control shifts from the central authorities to the edges, with individuals. SSI is a set of principles that leverage decentralized identity technology. Sovrin compiled a list of the principles in an easy-to-digest format, available [here](https://sovrin.org/principles-of-ssi/). + +[Self-sovereign identity](/documentation/learn/glossary/#self-sovereign-identity) introduces new concepts that flip the existing identity models. The control shifts from the central authorities to the edges, with individuals. SSI is a set of principles that leverage decentralized identity technology. Sovrin compiled a list of the principles in an easy-to-digest format, available [here](https://sovrin.org/principles-of-ssi/). The World Wide Web Consortium (W3C) organization has been setting the standards for the Internet as we know it. Similarly, they are also working on next-generation technologies such as decentralized identity. In July 2022, the W3C approved the DID specification to become a [recommendation](https://www.w3.org/press-releases/2022/did-rec/). The W3C has compiled a list in addition to the specifications for all DID methods available [here](https://www.w3.org/TR/did-spec-registries/). -For a deep dive into the DID specification itself, the W3C standard is [here](https://www.w3.org/TR/did-core/). +For a deep dive into the DID specification itself, the W3C standard is [here](https://www.w3.org/TR/did-core/). diff --git a/documentation/learn/advanced-explainers/_category_.json b/documentation/learn/advanced-explainers/_category_.json index b971d70ccd..589a0f8db9 100644 --- a/documentation/learn/advanced-explainers/_category_.json +++ b/documentation/learn/advanced-explainers/_category_.json @@ -8,4 +8,4 @@ "title": "Advanced explainers", "description": "Technical reference documentation including ADRs, specifications, and API details." } -} \ No newline at end of file +} diff --git a/documentation/learn/advanced-explainers/cloud-agent/README.md b/documentation/learn/advanced-explainers/cloud-agent/README.md index 33c6131f1c..4d59d57820 100644 --- a/documentation/learn/advanced-explainers/cloud-agent/README.md +++ b/documentation/learn/advanced-explainers/cloud-agent/README.md @@ -1,6 +1,6 @@ # Overview -The [Cloud Agent](/home/concepts/glossary#cloud-agent) is a scaleable, easy-to-use, robust, and W3C standards-based agent that provides [self-sovereign identity (SSI)](/home/concepts/glossary#self-sovereign-identity) services to build products and solutions based on it. +The [Cloud Agent](/home/concepts/glossary#cloud-agent) is a scaleable, easy-to-use, robust, and W3C standards-based agent that provides [self-sovereign identity (SSI)](/home/concepts/glossary#self-sovereign-identity) services to build products and solutions based on it. The Cloud Agent exposes REST API for integration with any programming language. The Cloud Agent provides all the required capabilities to leverage the power of decentralized identity through the support of W3C standards, [DIDComm](/home/concepts/glossary#didcomm), and the Hyperledger Aries protocols, solutions based on the Cloud Agent are interoperable with the SSI ecosystem. @@ -15,7 +15,7 @@ The Cloud Agent includes the following high-level features: ## Cloud Agent Features -This document provides an overview of the Cloud Agent feature set. +This document provides an overview of the Cloud Agent feature set. This document is manually updated; as such, it may not be up to date with the most recent release of Cloud Agent. ## Platform Support diff --git a/documentation/learn/advanced-explainers/cloud-agent/multi-tenancy.md b/documentation/learn/advanced-explainers/cloud-agent/multi-tenancy.md index 0835b1504a..6a9c928227 100644 --- a/documentation/learn/advanced-explainers/cloud-agent/multi-tenancy.md +++ b/documentation/learn/advanced-explainers/cloud-agent/multi-tenancy.md @@ -41,19 +41,25 @@ An entity represents a user or any other identity within the Identus platform. E Each entity is associated with an Authentication Method, which serves as a secure means of verifying the identity and access rights of the entity. This method ensures the entity's identity is authenticated during interactions with the platform, enhancing security. ### Logical Isolation + Logical Isolation is a core principle of Identus' multi-tenancy model. It ensures that one entity's digital assets, transactions, and data are logically separated from others, maintaining the highest data privacy and security level. ### Shared Wallets + Identus' multi-tenancy capabilities allow for the sharing of wallets among multiple entities. This feature facilitates collaborative work and resource sharing while preserving data isolation within the shared wallet. The entity can own only one wallet. Sharing it with other entities is possible, but multiple entities cannot own it. ### Tenant Management + Tenant Management is the process of onboarding, provisioning, and managing entities and wallets within the Identus platform. Administrators can configure each entity's permissions, resources, and access control, ensuring efficient and secure multi-tenancy operations. ### DIDComm Connections + DIDComm Connections are the secure communication channels between peers within the SSI ecosystem. Identus' multi-tenancy model ensures that the connections of one entity are logically isolated from those of other entities, preserving data privacy and security. Based on the DID-Peer of the message recipient, the corresponding wallet processes the message. ### Webhook Notifications + Webhook notifications enable users to receive alerts for specific events in the system. There are two types of webhook notifications: + - Global webhooks: monitor all events across all wallets at the Cloud Agent level - Wallet webhooks: isolated to individual wallets and do not have visibility into assets in other wallets. @@ -61,7 +67,6 @@ Webhook notifications enable users to receive alerts for specific events in the The following diagram illustrates the relationship between the key components of Identus' multi-tenancy model. - ```mermaid graph TB; Tenant(Tenant) --> |Represented by| Entity diff --git a/documentation/learn/advanced-explainers/did-prism/README.md b/documentation/learn/advanced-explainers/did-prism/README.md index 2dd8cada51..4c50d921a4 100644 --- a/documentation/learn/advanced-explainers/did-prism/README.md +++ b/documentation/learn/advanced-explainers/did-prism/README.md @@ -6,11 +6,13 @@ Officially according to the specs the `did:prism` method only existed in the Car But for testing purposes, many of the users are using the Cardano `preprod` network. ## Cloud Agent and Prism Node + The Cloud Agent together with the Prism Node provides a comprehensive solution for managing and resolving DIDs. The Prism Node is a microservice that exposes gRPC endpoints and implements `did:prism` events, allowing users to create, update, deactivate, and resolve DIDs in a secure and privacy-preserving manner. This solution is designed for the enterprise use case and requires setting up the full Cardano stack together with the Prism Node. ## Universal Resolver -The Universal Resolver is a service that provides a unified interface for resolving DIDs across different DID methods. + +The Universal Resolver is a service that provides a unified interface for resolving DIDs across different DID methods. It allows users to resolve DIDs from various DID methods, including PRISM, and retrieve their associated DID Documents. The `did:prism` has been integrated into the Universal Resolver, enabling users to resolve PRISM DIDs using the same interface as other DID methods. @@ -20,12 +22,14 @@ The Universal Resolver endpoint for PRISM DIDs is: https://dev.uniresolver.io/ ## SDKs + Each SDK provides a way to resolve DIDs and retrieve their associated DID Documents. The SDKs are designed to be easy to use and integrate into existing applications, allowing developers to quickly add DID resolution capabilities to their projects. Each SDK implements the `DIDResolver` interface via a URL. In order to configure the DIDResolver the corresponding endpoint should be set in the SDK configuration. ## Alternative Implementations ### Blocktrust Node + The Blocktrust Node is a community alternative to the Prism Node, providing similar functionality for resolving DIDs and managing DID Documents. The publicly available Blocktrust Node can be used to resolve PRISM DIDs and retrieve their associated DID Documents. @@ -33,6 +37,7 @@ The list of the Blocktrust endpoints for the PRISM DIDs is: [https://statistics.blocktrust.dev/resolve](https://statistics.blocktrust.dev/resolve) ### NeoPRISM + [NeoPRISM](https://github.com/hyperledger-identus/neoprism) is an alternative to the Prism Node, providing similar functionality for resolving DIDs and managing DID Documents. Written in Rust, NeoPRISM offers a lightweight, resource-efficient solution that can also be configured as a DID node backend for the Cloud Agent. The publicly available NeoPRISM can be used to resolve PRISM DIDs and retrieve their associated DID Documents. @@ -56,14 +61,17 @@ This image store the status off all DIDs in the file system. But the image is li The code is also distributed as a library in [Maven Central repository](https://mvnrepository.com/repos/central) and it's capable to run on the JVM and JS Environments. #### Prism-VDR + The [prism-vdr](https://github.com/FabioPinheiro/prism-vdr) is alternative PRISM DID indexer that stores all the PRISM DIDs events and their associated DID Documents in the GitHub repository. The PRISM-VDR supports the following Cardano networks: + - [`mainnet` network](https://github.com/FabioPinheiro/prism-vdr/tree/main/mainnet/diddoc) - [`preprod` network](https://github.com/FabioPinheiro/prism-vdr/tree/main/preprod/diddoc) -#### Blockfrost & PRISM +#### Blockfrost & PRISM Blockfrost is also constantly running the PRISM Indexer for all the Cardano networks and uploading the status to a [Blockfrost's GitHub repository](https://github.com/blockfrost/prism-vdr): + - [`mainnet` network](https://github.com/blockfrost/prism-vdr/tree/main/mainnet/diddoc) - [`preprod` network](https://github.com/blockfrost/prism-vdr/tree/main/preprod/diddoc) - [`preview` network](https://github.com/blockfrost/prism-vdr/tree/main/preview/diddoc) diff --git a/documentation/learn/advanced-explainers/did-prism/_category_.json b/documentation/learn/advanced-explainers/did-prism/_category_.json index 7e061d2192..514055d611 100644 --- a/documentation/learn/advanced-explainers/did-prism/_category_.json +++ b/documentation/learn/advanced-explainers/did-prism/_category_.json @@ -5,4 +5,4 @@ "type": "doc", "id": "README" } - } \ No newline at end of file + } diff --git a/documentation/learn/advanced-explainers/did-prism/did-prism-resolver-sdk.md b/documentation/learn/advanced-explainers/did-prism/did-prism-resolver-sdk.md index d5913e1329..5805b32d07 100644 --- a/documentation/learn/advanced-explainers/did-prism/did-prism-resolver-sdk.md +++ b/documentation/learn/advanced-explainers/did-prism/did-prism-resolver-sdk.md @@ -8,13 +8,14 @@ The DID resolver URL should be set in the SDK configuration to point to the appr ## SDK-TS -The SDK-TS provides a way to resolve PRISM DIDs and retrieve their associated DID Documents. +The SDK-TS provides a way to resolve PRISM DIDs and retrieve their associated DID Documents. The resolver that can be configured with the corresponding URL is the [PrismShortFormDIDResolver](https://github.com/hyperledger-identus/sdk-ts/blob/main/integration-tests/e2e-tests/src/resolvers/PrismShortFormDIDResolver.ts). ## SDK-Swift + The SDK-Swift provides a way to resolve PRISM DIDs and retrieve their associated DID Documents. The resolver that can be configured with the corresponding URL is the [PrismShortFormResolver](https://github.com/hyperledger-identus/sdk-swift/blob/main/E2E/Tests/Source/Resolvers/PrismShortFormResolver.swift) ## SDK-KMP -SDK-KMP cannot resolve the short form DIDs, but it can resolve the long form DIDs. \ No newline at end of file +SDK-KMP cannot resolve the short form DIDs, but it can resolve the long form DIDs. diff --git a/documentation/learn/advanced-explainers/mediator.md b/documentation/learn/advanced-explainers/mediator.md index 675e1a6d58..d32e0af2b7 100644 --- a/documentation/learn/advanced-explainers/mediator.md +++ b/documentation/learn/advanced-explainers/mediator.md @@ -19,9 +19,11 @@ The Mediator is an open-source initiative. For more details, you can refer to th ## DIDComm V2 Mediator Test Suite ### Overview + We have rigorously evaluated our Mediator protocols using the [DIDComm V2 Mediator Test Suite](https://github.com/input-output-hk/didcomm-v2-mediator-test-suite/). This test suite scrutinizes the compatibility of mediators with DIDComm V2 protocols, serving as a benchmark for quality and reliability. ### Protocols Tested + The suite tests a variety of vital protocols, including: - [Trust Ping 2.0](https://didcomm.org/trust-ping/2.0/) diff --git a/documentation/learn/advanced-explainers/neoprism/running-neoprism.md b/documentation/learn/advanced-explainers/neoprism/running-neoprism.md index 802118e890..dc857ad267 100644 --- a/documentation/learn/advanced-explainers/neoprism/running-neoprism.md +++ b/documentation/learn/advanced-explainers/neoprism/running-neoprism.md @@ -38,6 +38,7 @@ docker pull hyperledgeridentus/identus-neoprism:$NEOPRISM_VERSION NeoPRISM supports two database backends configured via the `NPRISM_DB_URL` environment variable: #### SQLite + ```bash # In-memory database (development/testing) NPRISM_DB_URL='sqlite::memory:' @@ -47,6 +48,7 @@ NPRISM_DB_URL='sqlite:/path/to/database.db' ``` #### PostgreSQL + ```bash # PostgreSQL connection string NPRISM_DB_URL='postgresql://username:password@hostname:5432/database_name' @@ -63,7 +65,6 @@ Set the `NPRISM_CARDANO_NETWORK` environment variable to specify which Cardano n Ensure that the selected network matches your blockchain data source configuration and the Cloud Agent's intended deployment environment. - ### Examples #### Development Mode @@ -142,4 +143,3 @@ docker run -p 8080:8080 \ ``` Replace the placeholder values with your actual Cardano wallet configuration. This mode requires a separately running indexer instance to provide DID resolution capabilities. - diff --git a/documentation/learn/advanced-explainers/prism-node/README.md b/documentation/learn/advanced-explainers/prism-node/README.md index 621cc9ddb3..3437b77dda 100644 --- a/documentation/learn/advanced-explainers/prism-node/README.md +++ b/documentation/learn/advanced-explainers/prism-node/README.md @@ -4,6 +4,7 @@ sidebar_position: 1 --- # PRISM Node + The PRISM Node acts as a second-layer node for the Distributed Ledger. It functions as a [verifiable data registry](/home/concepts/glossary#verifiable-data-registry), providing a secure and reliable way to store and manage data. PRISM Node's primary purpose is to provide a secure and trustworthy platform for storing and managing data on the Distributed Ledger. By leveraging the blockchain's security and decentralization, the PRISM Node stores and retrieves data in a secure and immutable manner. All operations are independently verified and authenticated using cryptographic signatures and other security measures, so all data is accurate and trustworthy. @@ -27,5 +28,4 @@ At its core, PRISM depends on protocols defining how to manage decentralized ide - DID resolvers can take the output of PRISM Nodes and construct the current DID document associated with a DID. - An additional consideration is that operations can be posted on-chain in blocks, helping on the scalability side and general reduction of fees. - Additionally, the node provides an interface to track the status of operations submitted to a PRISM Node. diff --git a/documentation/learn/advanced-explainers/prism-node/_category_.json b/documentation/learn/advanced-explainers/prism-node/_category_.json index 8b1728e9f7..0feb8edc19 100644 --- a/documentation/learn/advanced-explainers/prism-node/_category_.json +++ b/documentation/learn/advanced-explainers/prism-node/_category_.json @@ -5,4 +5,4 @@ "type": "doc", "id": "README" } - } \ No newline at end of file + } diff --git a/documentation/learn/advanced-explainers/prism-node/running-node.md b/documentation/learn/advanced-explainers/prism-node/running-node.md index a435951669..8f9bcaab3b 100644 --- a/documentation/learn/advanced-explainers/prism-node/running-node.md +++ b/documentation/learn/advanced-explainers/prism-node/running-node.md @@ -2,7 +2,7 @@ ## Overview -The Node is a level 2 proxy on top of the Cardano blockchain responsible for publishing, resolving, updating, and deactivating DIDs. It exposes a gRPC API to perform all the operations above. +The Node is a level 2 proxy on top of the Cardano blockchain responsible for publishing, resolving, updating, and deactivating DIDs. It exposes a gRPC API to perform all the operations above. The Identus cloud Agent communicates with the Node, with all operations conducted through it. The following documentation will provide a high-level overview of how the Node functions and explain its usage, including the environment variables required and how to deploy it to the Cardano mainnet and testnet. @@ -19,21 +19,18 @@ The Node consists of four separate executables: The Node gRPC is a service responsible for submitting transactions to the Cardano network with a configurable frequency, retrieving blocks, and processing the data for storage in a database. - #### Node PosgresQL database The database used by the Node to store processed data, namely DID documents and their respective states. - #### Cardano wallet backend An interface enables the Node to submit transactions to the Cardano node. -#### DB sync. +#### DB sync The Node uses an indexed version of the Cardano blockchain to access and parse minted blocks. - ```mermaid graph TB GRPC["Node gRPC Server"] @@ -52,11 +49,10 @@ graph TB ### Node enviroment variables - | Environment Variable | Description | Default Value | Data Type | |-----------------------------------------|---------------------------------------------------------------------------------------|-----------------|----------------------------------| | NODE_PSQL_HOST | Host and port of Node PosgresQL database | localhost:5432 | String | -| NODE_PSQL_DATABASE | Name of the database to connect to | node_db | String | +| NODE_PSQL_DATABASE | Name of the database to connect to | node_db | String | | NODE_PSQL_USERNAME | Username for database authentication | postgres | String | | NODE_PSQL_PASSWORD | Password for database authentication | postgres | String | | NODE_PSQL_AWAIT_CONNECTION_THREADS | Maximum amount of database connections | 8 | Int | @@ -72,7 +68,7 @@ graph TB | NODE_ID_CHAR_LIMIT | Maximum number of characters id field of pk and service can have | 50 | Int | | NODE_CARDANO_NETWORK | Cardano network node should operate on | testnet | Enum(testnet, mainnet) | | NODE_CARDANO_WALLET_ID | ID (hex encoded) of the wallet to use for payments | | String | -| NODE_CARDANO_WALLET_PASSPHRASE | Spending passphrase of NODE_CARDANO_WALLET_ID | | String | +| NODE_CARDANO_WALLET_PASSPHRASE | Spending passphrase of NODE_CARDANO_WALLET_ID | | String | | NODE_CARDANO_PAYMENT_ADDRESS | Address (hex encoded) to make payments to, can be NODE_CARDANO_WALLET_ID itself | | String | | NODE_CARDANO_WALLET_API_HOST | Cardano wallet backend API host | localhost | String | | NODE_CARDANO_WALLET_API_PORT | Cardano wallet backend API port | 8090 | Int | @@ -84,7 +80,6 @@ graph TB | NODE_CARDANO_DB_SYNC_USERNAME | Username for db sync database authentication | postgres | String | | NODE_CARDANO_DB_SYNC_PASSWORD | Password for db sync database authentication | password | String | - #### Running node Node docker image is available on GitHub, accessible here: @@ -109,14 +104,14 @@ Once you have these services up and running, specify their respective URLs in th * DB-sync - `NODE_CARDANO_DB_SYNC_HOST` for DB-sync host and port in a format `host:port` - `NODE_CARDANO_DB_SYNC_DATABASE` the databse name in DB-sync postgres database - - `NODE_CARDANO_DB_SYNC_USERNAME` DB-sync Database username + - `NODE_CARDANO_DB_SYNC_USERNAME` DB-sync Database username - `NODE_CARDANO_DB_SYNC_PASSWORD` DB-sync Database password When running the Node with Cardano ledger, you must specify which network to use, either `mainnet` or `testnet`, using the `NODE_CARDANO_NETWORK` environment variable. While this environment variable is essential for the correct operation of the Node, it does not define the usable network. As mentioned earlier, the interface communicates with the Cardano node; subsequently, the network is DB-sync and Cardano wallet backend. Therefore, when configuring those services, you must specify the network used in their respective configurations. It is possible to run DB-sync on testnet, and Cardano wallet backend on mainnet, and select either one via `NODE_CARDANO_NETWORK`. The Node won't report any errors, but this configuration would be incorrect and won't work correctly. You are responsible for syncing these three components. If you intend to use the testnet, set `NODE_CARDANO_NETWORK` to the testnet, but also run Cardano wallet backend connected to the testnet and start DB-sync to sync from the Node that is also running on the testnet as well. The same goes with mainnet. Apart from that, you must also provide the Wallet ID and its spending password as environment variables as well: -* `NODE_CARDANO_WALLET_ID` - The wallet ID must be in hex-encoded format, and the wallet must belong to the network you are running the Node on, which can be either testnet or mainnet +* `NODE_CARDANO_WALLET_ID` - The wallet ID must be in hex-encoded format, and the wallet must belong to the network you are running the Node on, which can be either testnet or mainnet * `NODE_CARDANO_WALLET_PASSPHRAS` - Spending password or wallet above The Node utilizes Cardano as a decentralized open database, and its implementation is similar to the DIF Sidetree Protocol. In short, the Node stores all relevant information in a Cardano transaction metadata and sends 1 ADA (minimum allowed amount) to another address, which you must provide via the `NODE_CARDANO_PAYMENT_ADDRESS` environment variable, which will store arbitrary information on the blockchain. In most cases, you don't need to specify a particular address for sending transactions as long as the transaction gets recorded. In this case, you should set NODE_CARDANO_PAYMENT_ADDRESS to the same address you are sending transactions from, `NODE_CARDANO_WALLET_ID`. In this configuration, you are not spending any ADA other than the transaction fee for every transaction. Suppose your wallet does not have enough ADA to cover the transaction fee (plus 1 ADA to send to yourself). In that case, the transaction won't get recorded, and your operation, which includes any DID-related action, won't be submitted. @@ -130,10 +125,9 @@ When running the Node, you must specify the host, database name, username, and p * `NODE_PSQL_USERNAME` - username * `NODE_PSQL_PASSWORD` - password - The Node gRPC server has three dependencies: Node DB, Cardano wallet, and DB-sync. You need to run these three services before starting the Node. -Node DB is a simple PostgreSQL database. +Node DB is a simple PostgreSQL database. Cardano wallet is an application that communicates with the Cardano network; it functions as a server that you can start and connect to either the mainnet or testnet. You must provide the Node runnable's host and port as environment variables. diff --git a/documentation/learn/basic-concepts.md b/documentation/learn/basic-concepts.md index f898ed8e30..2537c5eb6e 100644 --- a/documentation/learn/basic-concepts.md +++ b/documentation/learn/basic-concepts.md @@ -95,7 +95,7 @@ Identus comprises core libraries that facilitate typical SSI interactions among ![Identus component diagram](/img/component-diagram.png) -**Identus component capabilities** +**Identus component capabilities** The Identus ecosystem consists of three core components, each serving distinct functions in the decentralized identity infrastructure: @@ -103,10 +103,9 @@ The Identus ecosystem consists of three core components, each serving distinct f * **Wallet SDKs** deliver client-side credential management capabilities for mobile and web applications, allowing users to securely store their VCs, create presentations for verification requests, manage cryptographic keys, and handle encrypted DIDComm messaging with other parties. - * **The mediator** acts as a message routing proxy, ensuring reliable communication in the decentralized ecosystem. It routes and stores messages between parties, enables offline message delivery for mobile devices, and provides privacy-preserving message forwarding without exposing communication patterns. -For more information, refer to the [Advanced explainers](/category/advanced-explainers). +For more information, refer to the [Advanced explainers](/category/advanced-explainers). **Typical interaction flow** @@ -202,7 +201,7 @@ Tenant management is the process of onboarding, provisioning, and managing entit Multi-tenancy requires implementation planning to configure the Cloud agent with multi-tenancy enabled. The system supports various authentication methods, including API keys, JWT tokens, and third-party identity providers. -For detailed implementation guidance, refer to the [multi-tenancy tutorials](/cloud-agent/docs/docusaurus/multitenancy/tenant-onboarding). +For detailed implementation guidance, refer to the [multi-tenancy tutorials](/cloud-agent/docs/docusaurus/multitenancy/tenant-onboarding). ## 5. Common use cases {#5-common-use-cases} @@ -382,7 +381,6 @@ IoT devices can hold VCs that prove their identity, security compliance, and ope * Trusted communication between devices * Compliance with security and safety standards. - **Software and API credentials** Software applications and APIs can use VCs for authentication and access control. @@ -411,7 +409,6 @@ When planning a use case implementation, consider: * Governance and policy frameworks * Interoperability with other systems. - **Business model** * Cost distribution among participants diff --git a/documentation/learn/community-initiatives/project-catalyst-vdr.md b/documentation/learn/community-initiatives/project-catalyst-vdr.md index 248c7fc3cc..38a1552220 100644 --- a/documentation/learn/community-initiatives/project-catalyst-vdr.md +++ b/documentation/learn/community-initiatives/project-catalyst-vdr.md @@ -5,6 +5,7 @@ description: Completion overview of the Project Catalyst–funded Verifiable Dat --- # Verifiable Data Registry (VDR) for Identus on Cardano + **Project Catalyst – Project Completion Overview** This document summarizes the completion of the **Project Catalyst initiative** to design and deliver a **Verifiable Data Registry (VDR)** framework for **Identus on Cardano**. @@ -24,6 +25,7 @@ It enables data to be: - Stored across different backends (blockchain, database, files) In Identus, VDRs are used for: + - DID documents and operations - Credential schemas and definitions - Trust and identity metadata anchored on Cardano @@ -37,6 +39,7 @@ This project establishes VDRs as a **generic, reusable abstraction**, not tied t ### 1. Generic VDR Specification A technology-agnostic specification defining: + - VDR interfaces and responsibilities - Driver families and versions - URL-based resolution model @@ -46,6 +49,7 @@ A technology-agnostic specification defining: This specification allows **any storage backend** to implement a VDR consistently. **Links** + - Repository & specification: https://github.com/hyperledger-identus/vdr @@ -54,11 +58,13 @@ This specification allows **any storage backend** to implement a VDR consistentl ### 2. Cardano / PRISM VDR Specification A Cardano-specific VDR protocol describing: + - How verifiable data is anchored in Cardano transactions - Metadata encoding and verification rules - Compatibility with DID PRISM and Identus architecture **Links** + - Specification: https://github.com/hyperledger-identus/prism-vdr-driver/blob/main/prism-vdr-specification.md - Repository: @@ -69,11 +75,13 @@ A Cardano-specific VDR protocol describing: ### 3. Generic VDR Driver (Kotlin) A reference implementation of the generic VDR specification: + - Implemented in Kotlin - Demonstrates how to build VDR drivers - Used for validation, testing, and non-ledger backends **Links** + - Implementation: https://github.com/hyperledger-identus/vdr/tree/main/src @@ -84,22 +92,26 @@ A reference implementation of the generic VDR specification: To prove real-world applicability, multiple independent PRISM VDR drivers were implemented. #### Scala PRISM VDR Driver + - Uses the Blockfrost API - Supports file-based and MongoDB indexing - Published as reusable artifacts **Links** + - https://github.com/hyperledger-identus/prism-vdr-driver --- #### NeoPrism VDR Driver (Rust) + - Rust-based Cardano indexing and resolution service - Pluggable input feeds (Blockfrost, DBSync, custom) - REST API for VDR resolution - W3C-compliant DID resolution **Links** + - https://github.com/hyperledger-identus/neoprism --- @@ -107,11 +119,13 @@ To prove real-world applicability, multiple independent PRISM VDR drivers were i #### Prism-Node + Cloud-Agent Integration The production Identus stack: + - `prism-node` performs Cardano ledger operations - `cloud-agent` exposes REST and DIDComm APIs - Together they provide a complete Cardano-backed VDR service **Links** + - Prism Node: https://github.com/hyperledger-identus/prism-node - Cloud Agent: @@ -122,6 +136,7 @@ The production Identus stack: ## Public Demonstration A full end-to-end demonstration was recorded and published, showing: + - VDR architecture in practice - Multiple driver implementations - Cardano-anchored publishing and resolution flows diff --git a/documentation/learn/glossary.md b/documentation/learn/glossary.md index de6bbbba80..90a266fa26 100644 --- a/documentation/learn/glossary.md +++ b/documentation/learn/glossary.md @@ -1,279 +1,352 @@ # Glossary ## A + ### Access control -Access control mechanisms define how tenants/entities can access and interact with their data and resources and control who can access them. + +Access control mechanisms define how tenants/entities can access and interact with their data and resources and control who can access them. It helps enforce security and privacy policies in a multi-tenant environment. ### Anchoring + The act of anchoring is tying to something that is trusted by assumption. Usually some sort of an entity with authority. ### Administrator -An administrator is a role who oversees the agent and releated resources, including tenant, Edge Agent management, or external services. Admistrator typically does not participate in day-to-day SSI interactions. +An administrator is a role who oversees the agent and releated resources, including tenant, Edge Agent management, or external services. Admistrator typically does not participate in day-to-day SSI interactions. ## C + ### Claim {#claim} + An assertion made about a [subject](#did-subject). ### Claims {#claims} -Synonym of [claim](#claim) in the plural form. + +Synonym of [claim](#claim) in the plural form. ### Cloud Agent {#cloud-agent} + The Cloud Agent is a scaleable, easy-to-use, robust, and W3C standards-based agent that provides self-sovereign identity (SSI) services to build products and solutions based on it. The Cloud Agent exposes REST API for integration with any programming language. ### Controller + See [DID Controller](#did-controller). ### Connection Protocol + The protocol provides endpoints for creating and managing connections, as well as for accepting invitations. ### connection invitation + An invitation from one entity to another to establish a connection. ### Connection request + A request to establish a connection. ### Credential Definition {#credential-definition} -The term [refers](https://hyperledger.github.io/anoncreds-spec/#term:credential-definition) to the AnonCreds v1 implementation. -Credential Definition contains public and private part. + +The term [refers](https://hyperledger.github.io/anoncreds-spec/#term:credential-definition) to the AnonCreds v1 implementation. +Credential Definition contains public and private part. The public part is published and available for anyone to use to verify the credential. The private part is used to issue credentials. ### Credential schema + A data template for verifiable credentials (VCs). It contains claims of the VCs, credential schema author, type, name, version, and proof of authorship. ### Credential offer + An Issuer sends a request to the Holder to accept a verifiable credential. ### Credential request -When the Holder accepts or rejects a credential offer, a credential request is created from it. - +When the Holder accepts or rejects a credential offer, a credential request is created from it. ## D + ### Decentralized Identifier {#decentralized-identifier} + A globally unique persistent identifier that does not require a centralized registration authority and is often cryptographically generated. All DIDs use distributed ledger technology (DLT) or some other decentralized network. ### DID {#did} + See [decentralized identifier](#decentralized-identifier) ### DIDs {#dids} + See [decentralized identifiers](#decentralized-identifier) ### DIDComm {#didcomm} + A set of secure, standards-based communications protocols to establish and manage trusted, peer-to-peer connections and interactions between DIDs in a transport-agnostic and interoperable manner. ### DID controller + The entity that has control of the DID ### DID document {#did-document} + A set of data that describes the DID subject, including mechanisms such as cryptographic public keys. The entire W3C DID specification is [here](https://www.w3.org/TR/did-spec-registries/). ### DID method + The DID method defines how to implement a specific DID method schema. The specification defines the DID method, including precise operations to create DIDs and [DID documents](#did-document) and how to resolve, update, and deactivate them. ### DID resolution + The process for retrieving a [DID document](#did-document). ### DID subject {#did-subject} + The entity is identified by a [DID](#decentralized-identifier) and described by a [DID documents](#did-document). Anything can be a DID subject: person, group, organization, physical thing, digital thing, etc. ### DID Url -A DID itself is a type of a URL, while `did` is a registered schema type, like `http` and `https`. With Identus, we refer DID URLs to a DID that includes path and query parameters and can resolve a resource via one of the service endpoints in the DID document. For example: + +A DID itself is a type of a URL, while `did` is a registered schema type, like `http` and `https`. With Identus, we refer DID URLs to a DID that includes path and query parameters and can resolve a resource via one of the service endpoints in the DID document. For example: + ``` did:prism:9f847f8bbb66c112f71d08ab39930d468ccbfe1e0e1d002be53d46c431212c26?resourceService=agent-base-url&resourcePath=schema-registry/schemas/did-url&resourceHash=4074bb1a8e0ea45437ad86763cd7e12de3fe8349ef19113df773b0d65c8a9c46 ``` ### Distributed Ledger Technology (DLT) {#dlt} -A distributed database or ledger establishes confidence for the participants to rely on the data recorded. Typically these databases use nodes and a consensus protocol to confirm the order of cryptographically signed transactions. Linking the transactions over time creates a historical ledger that is effectively immutable. - +A distributed database or ledger establishes confidence for the participants to rely on the data recorded. Typically these databases use nodes and a consensus protocol to confirm the order of cryptographically signed transactions. Linking the transactions over time creates a historical ledger that is effectively immutable. ## E + ### Endpoints + A network address at which services operate on behalf of a [DID subject](#did-subject). ### Entity -An `entity,` in the context of the Identus platform, is an identity representing a user or system. -Each entity possesses an Edge Agent and is associated with an authentication method. + +An `entity,` in the context of the Identus platform, is an identity representing a user or system. +Each entity possesses an Edge Agent and is associated with an authentication method. Entities are crucial for secure and verifiable transactions within the SSI ecosystem. ### Edge Agent SDK {#edge-agent-sdk} + For use with web and mobile (iOS, Android, TypeScript) enable identity holders to store credentials and respond to proof requests. ### Edge Agent + A Edge Agent can perform DID operations, like create, update, and deactivate. It also enables management of verifiable credentials, and communications. ## G -### Governance framework -See [Trust Framework](#trust-framework) +### Governance framework +See [Trust Framework](#trust-framework) ## H -### Holder {#holder} -An entity will take on this role by possessing one or more [verifiable credentials](#verifiable-credential) and generating [verifiable presentations](#verifiable-presentation). Also takes the role of a prover when presenting verifiable credentials for verification. +### Holder {#holder} +An entity will take on this role by possessing one or more [verifiable credentials](#verifiable-credential) and generating [verifiable presentations](#verifiable-presentation). Also takes the role of a prover when presenting verifiable credentials for verification. ## I + ### IAM + IAM (Identity and Access Management), is a framework that controls and manages user access to computing resources. It ensures secure authentication, appropriate authorization, and effective auditing to protect against unauthorized access in a computing environment. ### Identus + A suite of products that provides infrastructure for decentralized identity. ### IDP {#idp} + An Identity Provider (IDP) is a centralized service that manages and authenticates user identities, allowing individuals to access multiple applications and services with a single set of credentials. IDPs play a crucial role in Single Sign-On (SSO) systems, simplifying user access management across various platforms and services. ### Invitation + Sent by the [inviter](#inviter) to the [invitee](#invitee) to request and establish a connection. ### Invitee + A subject that receives a connection invitation and accepts it by sending a connection request. ### Inviter + A subject that initiates a connection request by sending a connection invitation. ### Issuer {#issuer} + An entity that asserts claim(s) about one or more [subjects](#did-subject) then creates a [verifiable credential](#verifiable-credential) from these claims and transmits the VC to a holder. ### Issue Credential Protocol + Allows you to create, retrieve, and manage issued [verifiable credentials (VCs)](#verifiable-credential) between a VC issuer and a VC holder. ## K + ### Keycloak Service -Keycloak is an open-source [IAM](#iam) solution that provides authentication, authorization, and single sign-on capabilities for applications and services. It allows organizations to secure their applications by managing user identities, enforcing security policies, and facilitating seamless and secure user authentication. +Keycloak is an open-source [IAM](#iam) solution that provides authentication, authorization, and single sign-on capabilities for applications and services. It allows organizations to secure their applications by managing user identities, enforcing security policies, and facilitating seamless and secure user authentication. ## M + ### Mediator {#mediator} + A mediator participates in agent-to-agent message delivery that the sender must model. It has its keys and will deliver messages only after decrypting an outer envelope to reveal a forward request. Many types of mediators may exist, but two important ones should be widely understood, as they commonly manifest in DID Docs: + - A service that hosts many cloud agents at a single endpoint to provide herd privacy (an "agency") is a mediator. - A cloud-based agent that routes between/among the edges of a sovereign domain is a mediator. For a detailed overview of mediators refer to the [RFC0046: Mediators and Relays](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0046-mediators-and-relays). ### Mutli-tenancy -Multi-tenancy is a core capability of the Identus platform, allowing it to serve numerous users/identities while logically isolating their Edge Agent assets. -This segregation maintains data privacy and security, enhancing scalability and resource sharing within the SSI ecosystem. +Multi-tenancy is a core capability of the Identus platform, allowing it to serve numerous users/identities while logically isolating their Edge Agent assets. +This segregation maintains data privacy and security, enhancing scalability and resource sharing within the SSI ecosystem. ## O + ### OIDC + OIDC (OpenID Connect), is an authentication protocol built on top of OAuth 2.0. It enables secure user authentication and allows applications to obtain information about users, facilitating single sign-on (SSO) and identity verification in web and mobile applications. ### OID4VCI + [OID4VCI](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html) (OpenID for Verifiable Credential Issuance) defines an authorization mechanism for issuing credentials using the OAuth2 protocol. It grants the holder access to credentials protected by the issuer's authorization server. ## P + ### Peer DID + They are specialized DIDs for peer-to-peer relationships. ### Peer DID Method + A rich DID method that has no blockchain dependencies. The verifiable data registry is a synchronization protocol between peers. See the [Peer DID Method specification](https://github.com/decentralized-identity/peer-did-method-spec). ### Present Proof Protocol + The protocol provides endpoints for a Verifier to request new proof presentations from Holder/Provers and for a Holder/Prover to respond to the presentation request using a specific verifiable credential they own. ### Proof + A cryptographic mechanism that proves the information in a [verifiable credential](#verifiable-credential) or [verifiable presentation](#verifiable-presentation) has not been tampered with. Many types of cryptographic proofs include but are not limited to digital signatures, zero-knowledge proofs, Proofs of Work, and Proofs of Stake. ### Proof presentation + See [verifiable presentation](#verifiable-presentation). Also see [Present Proof Protocol](#present-proof-protocol). ### Protection API + The Protection API in User-Managed Access ([UMA](#uma)) is a set of endpoints that enables resource servers to enforce access policies and protect resources. It provides a mechanism for resource servers to interact with the authorization server to obtain necessary information and permissions, ensuring that access to user-managed resources aligns with the user's specified policies. ### Protection API + The Protection API in User-Managed Access ([UMA](#uma)) is a set of endpoints that enables resource servers to enforce access policies and protect resources. It provides a mechanism for resource servers to interact with the authorization server to obtain necessary information and permissions, ensuring that access to user-managed resources aligns with the user's specified policies. ### Protocol buffer + Also known as protobuf. ### Prism envelope + A response type for endpoints that implement prism anoncred method + ```json {"resource": , url: } ``` - - ## R + ### Relay + A relay is an entity that passes along agent-to-agent messages depending on the sender's encryption choices. It does not decrypt anything. Relays can change the transport for a message (e.g., accept an HTTP POST, then turn around and emit an email, or accept a Bluetooth transmission, then turn around and transmit something in a message queue). Mix networks like TOR are a type of relay. For a detailed overview of relays refer to the [RFC0046: Mediators and Relays](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0046-mediators-and-relays). ### Relying party + A party that depends on the authenticity of digital signatures. ### RPT -Requesting Party Token (RPT) is a concept within the [UMA](#uma) framework. It represents a token obtained by a client application from an authorization server, allowing the client to access protected resources on behalf of the requesting party (user), based on the user's policies and consent. +Requesting Party Token (RPT) is a concept within the [UMA](#uma) framework. It represents a token obtained by a client application from an authorization server, allowing the client to access protected resources on behalf of the requesting party (user), based on the user's policies and consent. ## S + ### Secrets storage {#secrets-storage} + This component securely stores sensitive information, such as private keys associated with an individual's digital identity, Edge Agent seed, etc. Secrets storage plays a crucial role in SSI implementations because it ensures that sensitive information is securely stored and protected against unauthorized access or disclosure ### Subject {#subject} + See [DID Subject](#did-subject) ### SSI {#ssi} + See [Self-Sovereign Identity](#self-sovereign-identity) ### Self-Sovereign Identity (SSI) {#self-sovereign-identity} -An identity model that shifts control to the edges, focused on security, privacy using public/private key encryption. - +An identity model that shifts control to the edges, focused on security, privacy using public/private key encryption. ## T + ### Tenant -A tenant is an individual user, organization, or entity that utilizes the SSI platform. + +A tenant is an individual user, organization, or entity that utilizes the SSI platform. Each tenant has its isolated area within the system, maintaining the separation of assets. ### Tenant Isolation + Tenant isolation is a core capability of the Identus platform, allowing it to serve numerous users/identities while logically isolating their Edge Agent assets. ### Tenant Management + Tenant management encompasses the processes and tools used to onboard, provision, and manage tenants within the SSI platform, including user registration, role assignment, authentication method configuring, and access permissions. ### Trust Framework + A governing body that establishes rules, requirements, establishes operating procedures, and a [trust registry](#trust-registry) for specific ecosystems. ### Trust Registry -A document that lists authorized issuers and verifiers established by the [Trust framework](#trust-framework). +A document that lists authorized issuers and verifiers established by the [Trust framework](#trust-framework). ## U + ### UMA -User-Managed Access (UMA) is an authorization framework that allows users to control and manage access to their online resources. UMA enables individuals to share their digital assets with others while maintaining control over who can access the information and for what purposes. +User-Managed Access (UMA) is an authorization framework that allows users to control and manage access to their online resources. UMA enables individuals to share their digital assets with others while maintaining control over who can access the information and for what purposes. ## V + ### Vault Service {#vault-service} + HashiCorp Vault is a widely used open-source and enterprise-grade solution designed for securely storing, accessing, and managing secrets and sensitive data in modern computing environments. It offers a centralized platform for managing cryptographic keys, passwords, API keys, tokens, and other secrets. ### Verifiable Credential (VC) {#verifiable-credential} + A verifiable credential is a tamper-evident credential that contains one or more claims made by an issuer whose authorship can be cryptographically verified. It is possible to use VCs to create a [verifiable presentation](#verifiable-presentation). Also, the claims in a VC can be about different subjects. ### Verifiable Credentials (VCs) {#verifiable-credentials} + Synonym of the [Verifiable Credential (VC)](#verifiable-credential). ### Verifiable Data Registry {#verifiable-data-registry} + A system that mediates the creation and verification of identifiers, keys, and other relevant data. ### Verifiable Presentation {#verifiable-presentation} -Data is derived from one or more [verifiable credentials](#verifiable-credential), issued by issuers, and shared (presented) to a specific verifier. The verifiable presentation is tamper-evident and encoded in a way to trust the authorship of the data after a cryptographic verification. -### Verifier -An entity that receives one or more [verifiable credentials](#verifiable-credential) optionally, inside a [verifiable presentation](#verifiable-presentation). Also known as a relying party. +Data is derived from one or more [verifiable credentials](#verifiable-credential), issued by issuers, and shared (presented) to a specific verifier. The verifiable presentation is tamper-evident and encoded in a way to trust the authorship of the data after a cryptographic verification. +### Verifier +An entity that receives one or more [verifiable credentials](#verifiable-credential) optionally, inside a [verifiable presentation](#verifiable-presentation). Also known as a relying party. ## W + ### Wallet SDK {#wallet-sdk} -A software development kit (SDK) that enables developers to build applications that interact with the Identus platform. + +A software development kit (SDK) that enables developers to build applications that interact with the Identus platform. The Wallet SDK provides a set of tools, libraries, and APIs that simplify the integration of SSI features, such as DID operations, verifiable credentials, and secure communications, into web and mobile applications. -Wallet SDK is much wider term than [Edge Agent SDK](#edge-agent-sdk), as it includes all the features of Edge Agent SDK and more. \ No newline at end of file +Wallet SDK is much wider term than [Edge Agent SDK](#edge-agent-sdk), as it includes all the features of Edge Agent SDK and more. diff --git a/documentation/learn/what-is-hyperledger-identus.md b/documentation/learn/what-is-hyperledger-identus.md index 2f5b00d35b..cc9c0cc511 100644 --- a/documentation/learn/what-is-hyperledger-identus.md +++ b/documentation/learn/what-is-hyperledger-identus.md @@ -20,11 +20,11 @@ Identus is built on industry-standard protocols and specifications to ensure int ## What you'll learn {#what-you'll-learn} -This Learn section will guide you through understanding Identus, from fundamental concepts to advanced implementations. +This Learn section will guide you through understanding Identus, from fundamental concepts to advanced implementations. **Learning path overview** -Begin with the **Basic concepts** section to understand the fundamental principles of decentralized identity. Then explore the **Advanced explainers** for a deeper exploration of the ecosystem components. +Begin with the **Basic concepts** section to understand the fundamental principles of decentralized identity. Then explore the **Advanced explainers** for a deeper exploration of the ecosystem components. The content assumes basic familiarity with digital identity concepts but explains all SSI-specific terminology. Follow the links to the glossary for detailed definitions throughout the documentation. diff --git a/documentation/reference/_category_.json b/documentation/reference/_category_.json index c448ec41dd..ff5ee6d6dc 100644 --- a/documentation/reference/_category_.json +++ b/documentation/reference/_category_.json @@ -6,4 +6,4 @@ "type": "generated-index", "title": "Reference" } - } \ No newline at end of file + } diff --git a/documentation/reference/adrs/README.md b/documentation/reference/adrs/README.md index 9f2560bd5c..81a8b2f2dc 100644 --- a/documentation/reference/adrs/README.md +++ b/documentation/reference/adrs/README.md @@ -40,4 +40,3 @@ You can browse the ADRs by using the left menu or the search bar. - [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme) - [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them) - [ADR GitHub organization](https://adr.github.io/) - diff --git a/documentation/reference/adrs/_category_.json b/documentation/reference/adrs/_category_.json index b48a9e64be..8a9ac242e5 100644 --- a/documentation/reference/adrs/_category_.json +++ b/documentation/reference/adrs/_category_.json @@ -6,4 +6,4 @@ "type": "doc", "id": "README" } - } \ No newline at end of file + } diff --git a/documentation/reference/sidebar.ts b/documentation/reference/sidebar.ts index d4e8901dae..4021c72531 100644 --- a/documentation/reference/sidebar.ts +++ b/documentation/reference/sidebar.ts @@ -54,4 +54,4 @@ const sidebar: SidebarsConfig[keyof SidebarsConfig] = [ } ] -export default sidebar \ No newline at end of file +export default sidebar diff --git a/documentation/reference/specifications.md b/documentation/reference/specifications.md index c23ffdcad8..0571a36274 100644 --- a/documentation/reference/specifications.md +++ b/documentation/reference/specifications.md @@ -29,7 +29,7 @@ | βœ… | βœ… | βœ… | βœ… | [Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-1.0/) | Core specification for DIDs | | βœ… | βœ… | βœ… | βœ… | [PRISM DID Method Specification - did:prism](https://github.com/input-output-hk/prism-did-method-spec/blob/main/w3c-spec/PRISM-method.md) | PRISM DID Method specification | | βœ… | βœ… | βœ… | βœ… | [Peer DID 1.0](https://identity.foundation/peer-did-method-spec/) | Peer DID specification. Partually suported (did:peer:2 is fully supported) | -| βœ… | βœ… | βœ… | βœ… | [Verifiable Credentials JSON Schema Specification](https://www.w3.org/TR/vc-json-schema/) | JSON Schemas for Verifiable Credentials | +| βœ… | βœ… | βœ… | βœ… | [Verifiable Credentials JSON Schema Specification](https://www.w3.org/TR/vc-json-schema/) | JSON Schemas for Verifiable Credentials | | βœ… | βœ… | βœ… | βœ… | [Securing Verifiable Credentials using JOSE and COSE](https://www.w3.org/TR/vc-jose-cose/) | Core specification for VC-JWT | | βœ… | βœ… | βœ… | βœ… | [JSON Object Signing and Encryption (JOSE)](https://www.iana.org/assignments/jose/jose.xhtml) | JOSE registry of headers, curves, keys, signature and encryption algorithms | | βœ… | ❌ | ❌ | ❌ | [Selective Disclosure for JWTs (SD-JWT)](https://datatracker.ietf.org/doc/draft-ietf-oauth-selective-disclosure-jwt/07/) | Core specification for SD-JWT (not SD-JWT-VC). Outdated, the latest is v14 | @@ -39,7 +39,7 @@ | βœ… | βœ… | βœ… | βœ… | [HTTP AnonCreds Method](https://hyperledger.github.io/anoncreds-methods-registry/#http-anoncreds-method) | HTTP AnonCreds Method for Schema and Credential Definition | | βœ… | βœ… | βœ… | βœ… | [Bitstring Status List v1.0](https://www.w3.org/TR/vc-bitstring-status-list/) | Core specification for VC-JWT | | ❌ | ❌ | ❌ | ❌ | [DIF Presentation Exchange 2.x.x](https://identity.foundation/presentation-exchange) | DIF Presentation Exchange protocol | -| βœ… | βœ…οΈ | βœ…οΈ | βœ…οΈ | [Out of Band Protocol 2.0](https://identity.foundation/didcomm-messaging/spec/#out-of-band-messages) | Out of Band messages for DIDComm (part of DIDCommV2 specification) | | +| βœ… | βœ…οΈ | βœ…οΈ | βœ…οΈ | [Out of Band Protocol 2.0](https://identity.foundation/didcomm-messaging/spec/#out-of-band-messages) | Out of Band messages for DIDComm (part of DIDCommV2 specification) | | 🚫 | βœ… | βœ… | βœ… | [Coordinate Mediation Protocol 2.0](https://didcomm.org/coordinate-mediation/2.0/) | Coordinate Mediation Protocol for DIDCommV2 | | βœ… | βœ…οΈ | βœ…οΈ | βœ…οΈ | [Connection Protocol 1.0](https://github.com/hyperledger-identus/cloud-agent/blob/main/mercury/protocol-connection/Connection-Protocol.md) | The protocol is used when you wish to create a connection with another agent | | βœ… | ❓️ | ❓️ | ❓️ | [Aries RFC 0023: DID Exchange v1](https://github.com/hyperledger/aries-rfcs/tree/main/features/0023-did-exchange) | The protocol to exchange DIDs between agents when establishing a DID based relationship | @@ -52,5 +52,3 @@ | βœ… | βœ… | βœ… | βœ… | [Aries RFC 0035: Report Problem Protocol 1.0](https://github.com/hyperledger/aries-rfcs/blob/main/features/0035-report-problem/README.md) | Report Problem Protocol for DIDCommV2 | | πŸ”„ | πŸ”„ | πŸ”„ | πŸ”„ | [OpenID for Verifiable Credential Issuance - draft 15](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html) | OpenID Connect for VC Issuance (VC-JWT is supported only). Client side. | | πŸ”„ | πŸ”„ | πŸ”„ | 🚧 | [OpenID for Verifiable Credential Presentation - draft 15](https://openid.net/specs/openid-4-verifiable-credential-presentation-1_0.html) | OpenID Connect for VC Presentation (VC-JWT is supported only). Client side. | - - diff --git a/infra/README.md b/infra/README.md index ed494b44cc..27169d3e34 100644 --- a/infra/README.md +++ b/infra/README.md @@ -25,5 +25,6 @@ Docker image is built each time new changes are merged to `main` branch of the r ## Misc The docs are protected by http basic authentication, `demo:iohk4ever`, if you ever need to update this password: + - Run `htpasswd -n demo` to define the new password (install `apache2-utils` if the command wasn't found). - Paste the output line to [htpasswd](nginx/htpasswd). diff --git a/prepare.sh b/prepare.sh index 108a12f22f..d7ab7c5de9 100644 --- a/prepare.sh +++ b/prepare.sh @@ -1,3 +1,3 @@ #!/bin/bash npx docusaurus clean-api-docs all -npx docusaurus gen-api-docs all \ No newline at end of file +npx docusaurus gen-api-docs all diff --git a/src/components/atala-graphic/index.js b/src/components/atala-graphic/index.js index 129ad494b4..9057eb08c7 100644 --- a/src/components/atala-graphic/index.js +++ b/src/components/atala-graphic/index.js @@ -27,4 +27,4 @@ export default function AtalaGraphic() { ) -} \ No newline at end of file +} diff --git a/src/components/atala-graphic/index.module.css b/src/components/atala-graphic/index.module.css index ed4fa2a6c2..f924286b3c 100644 --- a/src/components/atala-graphic/index.module.css +++ b/src/components/atala-graphic/index.module.css @@ -36,4 +36,4 @@ .hero__graphic__wrapper { transform: translateX(25%); } -} \ No newline at end of file +} diff --git a/src/components/blob/index.js b/src/components/blob/index.js index b7ebc371f7..5debaec08d 100644 --- a/src/components/blob/index.js +++ b/src/components/blob/index.js @@ -33,4 +33,4 @@ export default function Blob() {
) -} \ No newline at end of file +} diff --git a/src/components/blob/index.module.css b/src/components/blob/index.module.css index f907aa2981..2937798eed 100644 --- a/src/components/blob/index.module.css +++ b/src/components/blob/index.module.css @@ -37,4 +37,4 @@ to { transform: rotate(360deg); } -} \ No newline at end of file +} diff --git a/src/components/features/styles.module.css b/src/components/features/styles.module.css index 3b4c98d78d..a251cff29c 100644 --- a/src/components/features/styles.module.css +++ b/src/components/features/styles.module.css @@ -16,4 +16,4 @@ .featureSvg { height: 97.5px; width: 100px; -} \ No newline at end of file +} diff --git a/src/components/resources/index.module.css b/src/components/resources/index.module.css index 4805452ce5..91cca6c031 100644 --- a/src/components/resources/index.module.css +++ b/src/components/resources/index.module.css @@ -164,4 +164,4 @@ p { background: var(--ifm-color-primary); padding: .625rem 1.75rem; text-decoration: none; -} \ No newline at end of file +} diff --git a/src/config/multiDocPreset.ts b/src/config/multiDocPreset.ts index cc920ae4b9..33c2e8ba3c 100644 --- a/src/config/multiDocPreset.ts +++ b/src/config/multiDocPreset.ts @@ -29,4 +29,4 @@ export default function preset(_context: any, opts: Opts) { ...docs.map(contentConfig => ['docsPluginId' in contentConfig ? CONTENT_OPENAPI_PLUGIN : CONTENT_DOCS_PLUGIN, contentConfig]), ], }; -} \ No newline at end of file +} diff --git a/src/config/presets.ts b/src/config/presets.ts index 29263d2e34..b4891e1e7c 100644 --- a/src/config/presets.ts +++ b/src/config/presets.ts @@ -33,15 +33,15 @@ export const presets: PresetConfig[] = [ ], /** * TODO: REMOVE THIS AFTER MIGRATION TO NEW DOCS - * + * * Each Repository will distribute the documentation in the same way we are implementing now. * docs/learning * docs/develop * docs/reference - * + * * Each folder can have a sidebar.ts to define the sidebar items, but its not required. - * One sidebar will be automatically generated from the content of the folder and the order of the documents - * can be set using mdx comments + * One sidebar will be automatically generated from the content of the folder and the order of the documents + * can be set using mdx comments */ remarkPlugins: [ [ diff --git a/src/css/custom.css b/src/css/custom.css index 33c677d54b..82c09da9ae 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -305,4 +305,4 @@ button[aria-expanded] { /* Hide specific sidebar items */ .hidden-sidebar-item { display: none !important; -} \ No newline at end of file +} diff --git a/src/pages/index.module.css b/src/pages/index.module.css index af84004aed..72b2b1966e 100644 --- a/src/pages/index.module.css +++ b/src/pages/index.module.css @@ -76,4 +76,4 @@ .hero__content { top: clamp(5.125rem, 100vw, 9.125rem); } -} \ No newline at end of file +} diff --git a/src/utils/index.ts b/src/utils/index.ts index 58a1903fc3..7759f85fa2 100644 --- a/src/utils/index.ts +++ b/src/utils/index.ts @@ -17,7 +17,7 @@ export function extractMarkdownTitleInfo(content: string): { title?: string, sid const customTitleMatch = content.match(//i); const customSidebarLabelMatch = content.match(//i); const customSidebarPositionMatch = content.match(//i); - + let title = customTitleMatch?.[1]?.trim(); if (!title) { @@ -26,7 +26,7 @@ export function extractMarkdownTitleInfo(content: string): { title?: string, sid title = h1Match[1].trim(); } } - + if (title) { title = title.replace(/^(?:Class|Interface|Type\s+alias|Variable|Function|Namespace|Enum|Enumeration):\s+/i, ''); title = title.replace(/\\([^a-zA-Z0-9])/g, '$1'); @@ -49,7 +49,7 @@ function getTitleFromMd(filePath: string, fallback: string): string { const info = extractMarkdownTitleInfo(content); if (info.sidebar_label) return info.sidebar_label; if (info.title) return info.title; - + return fallback; } catch { return fallback; @@ -95,7 +95,7 @@ export function getSidebarItemsForDir(dirPath: string): SidebarItemConfig[] { try { catProps = JSON.parse(fs.readFileSync(categoryJsonPath, 'utf8')); } catch (e) { - console.warn(`Warning: Failed to parse ${categoryJsonPath}:`, e); + console.warn(`Warning: Failed to parse ${categoryJsonPath}:`, e); } } @@ -142,7 +142,7 @@ export function getSidebarItemsForDir(dirPath: string): SidebarItemConfig[] { if (categoryLink && categoryLink.type === 'doc' && categoryLink.id !== `${childPath}/${indexName}`) { const customDocMd = `${dirPath}/${dirent.name}/${categoryLink.id.split('/').pop()}.md`; const customDocMdx = `${customDocMd}x`; - fallbackLabel = fs.existsSync(customDocMdx) ? getTitleFromMd(customDocMdx, baseLabel) : + fallbackLabel = fs.existsSync(customDocMdx) ? getTitleFromMd(customDocMdx, baseLabel) : (fs.existsSync(customDocMd) ? getTitleFromMd(customDocMd, baseLabel) : baseLabel); } else { const actualIndexPath = fs.existsSync(indexPathMdx) ? indexPathMdx : indexPath; @@ -173,8 +173,8 @@ export function getSidebarItemsForDir(dirPath: string): SidebarItemConfig[] { ...(catProps.collapsible !== undefined && { collapsible: catProps.collapsible }), ...(catProps.className && { className: catProps.className }), customProps: { - ...catProps.customProps, - ...(typeof catProps.position === 'number' && { position: catProps.position }) + ...catProps.customProps, + ...(typeof catProps.position === 'number' && { position: catProps.position }) }, ...(categoryLink && { link: categoryLink }), items: finalChildItems @@ -241,4 +241,4 @@ export function buildTypeDocCategorySidebar(pathStr: string, label: string): Sid items } ] -} \ No newline at end of file +}