From 669198b60b278ea85e93ea68d446a56a3281f6f5 Mon Sep 17 00:00:00 2001 From: Andor Kesselman Date: Wed, 28 Feb 2024 14:31:15 -0800 Subject: [PATCH] added service profile section and TODO cleanup --- package.json | 13 +++++------- spec/foreword.md | 24 +++++++++++++++++++++-- spec/header.md | 9 ++++----- spec/introduction.md | 14 +++++++++++++ spec/normative_references.md | 6 +++--- spec/requirements.md | 37 +++++++++++++++++++++++++---------- spec/revision_history.md | 2 ++ spec/terms_and_definitions.md | 6 ------ 8 files changed, 77 insertions(+), 34 deletions(-) create mode 100644 spec/introduction.md diff --git a/package.json b/package.json index 103f4f6..400478d 100644 --- a/package.json +++ b/package.json @@ -12,15 +12,9 @@ "render": "node -e \"require('spec-up')({ nowatch: true })\"", "dev": "node -e \"require('spec-up')({ dev: true })\"" }, - "keywords": [ - "spec", - "specs", - "markdown", - "editor", - "standards" - ], + "keywords": ["spec", "specs", "markdown", "editor", "standards"], "author": "Daniel Buchner", - "license": "Apache 2.0", + "license": "apache-2.0", "bugs": { "url": "https://github.com/decentralized-identity/spec-up/issues" }, @@ -60,5 +54,8 @@ }, "overrides": { "graceful-fs": "^4.2.11" + }, + "resolutions": { + "graceful-fs": "^4.2.11" } } diff --git a/spec/foreword.md b/spec/foreword.md index a889e28..db103ed 100644 --- a/spec/foreword.md +++ b/spec/foreword.md @@ -10,10 +10,27 @@ ## Foreword -::: todo -Create Foreword content in advance of Public Review Draft (i.e. no content expected for Implementers Review Draft) +ToIP (Trust Over IP Foundation) create a _____ + +::: todo +Preamble along the lines of an ISO Foreword. ::: +List significant changes (non-normative): + +* Shift away from a pure Issuer/Holder/Verifier approach to support non-credential use cases. +* Addition of namespacing concep to begin normalization of trust registries naming conventions. +* Enrichment of registry-of-registry concept to allow for registries that focus primarily on providing a list of registries. + +### On Trust, Trustworthy, and Trustworthiness + +The term [[ref:trust]] is loaded with varied meanings that often conflict. In the context of [[ref:trust registries]] we need to establish the scope of what we are talking about when we apply the term "trust" to trust registires. There are baseline definitions that follow this limiting scope. + +A trust registry does not create trust. The decision for one entity to "trust" another is their decision. A trust registry may provide information that helps the *consuming party* in deciding that an entity is [[ref: trustworthy]]. + +::: todo + define term "*consuming party*" - OR find better term and capture definition. + ### Copyright Notice @@ -46,3 +63,6 @@ We need answers to a simple question: > Does `Entity X` have `Authorization Y`, in the context of `Ecosystem Governance Framework Z`? +[[def: trustworthiness]] +~ An attribute of a person or organization that provides confidence to others of the qualifications, capabilities, and reliability of that entity to perform specific tasks and fulfill assigned responsibilities. Trustworthiness is also a characteristic of information technology products and systems (see Section 2.6.2 on trustworthiness of information systems). The attribute of trustworthiness, whether applied to people, processes, or technologies, can be measured, at least in relative terms if not quantitatively.48 The determination of trustworthiness plays a key role in establishing trust relationships among persons and organizations. The trust relationships are key factors in risk decisions made by senior leaders/executives. NOTE: Current state-of-the-practice for measuring trustworthiness can reliably differentiate between widely different levels of trustworthiness and is capable of producing a trustworthiness scale that is hierarchical between similar instances of measuring activities (e.g., the results from ISO/IEC 15408 [Common Criteria] evaluations). +- source: [NIST Special Publication 800-39](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-39.pdf) p.24 diff --git a/spec/header.md b/spec/header.md index 347cfe8..a4f83f9 100644 --- a/spec/header.md +++ b/spec/header.md @@ -17,8 +17,6 @@ Shift `Document Purpose` to Implementer Review Draft before going to Implementer Review. ::: - - **Note to Implementers and Reviewers** The intent of this Implementers Review Draft Deliverable is to drive input for the specification. Comments are appreciated and encouraged. During the Implementers Review period (TODO: list dates) feedback may be dispositioned rapidly. @@ -54,9 +52,10 @@ To comply with the intellectual property rights protections in[ the charter of t * Jacques Latour, CIRA * Christine Martin, Continuum Loop Inc. -- - -**Participate ** +### Participate +::: warning +SECTION will be removed before going to Review] +::: Participation is welcomed and encouraged. diff --git a/spec/introduction.md b/spec/introduction.md new file mode 100644 index 0000000..eded113 --- /dev/null +++ b/spec/introduction.md @@ -0,0 +1,14 @@ + +[//]: # (Pandoc Formatting Macros) + +[//]: # (::: introtitle) + +[//]: # (Introduction) + +[//]: # (:::) + +## Introduction + +::: todo +create introduction +::: diff --git a/spec/normative_references.md b/spec/normative_references.md index db96e08..1b9f522 100644 --- a/spec/normative_references.md +++ b/spec/normative_references.md @@ -11,10 +11,10 @@ [//]: # (:::) * [ToIP Governance Architecture Specification](https://wiki.trustoverip.org/pages/viewpage.action?pageId=71241) -* -* -TODO: Finish up alignging with `spec-up` spec linkging +::: todo +Finish up alignging with `spec-up` spec linkging +::: [[spec-norm]] diff --git a/spec/requirements.md b/spec/requirements.md index 5534a36..2489224 100644 --- a/spec/requirements.md +++ b/spec/requirements.md @@ -18,14 +18,11 @@ The following queries relate to receiving answers related to entities and other The following queries relate to configuration of systems that will interact with the trust registry. - * [CQ-1] MUST provide a list of [[ref: authorization]] namespaces that are supported by the responding system. * [CQ-2] MUST provide list of additional [[xref: TOIP, EGFs]] that the trust registry operates under. * [CQ-2] MUST provide a list of [[ref: VID Type]] (i.e. VID Types) that are supported by the responding system. * [CQ-3] MUST provide a list of [[xref: TOIP, assurance levels]] that are supported by the responding system. - - ### Metadata Queries [MQ-*] * [MQ-1] MUST provide a list of [[xref: TOIP, ecosystem governance frameworks]] (EGFs) that the system is operating under. This data will be comprised of the following elements: @@ -35,8 +32,6 @@ The following queries relate to configuration of systems that will interact with 2. [MQ-3] SHOULD provide the legal name and jurisdiction of the [[xref: TOIP, administering authority]] for the [[xref:TOIP, trust registry]] operator (if different from [[xref: TOIP, governing body]]). 3. [MQ-4] SHOULD provide a textual description of the trust registry mandate. - - ### Governing Authorities [GA-*] **Governing authorities** compliant with this specification: @@ -50,7 +45,9 @@ The following queries relate to configuration of systems that will interact with * [GA-3-1] This specification. * [GA-3-2] The [ToIP Governance Architecture Specification](https://wiki.trustoverip.org/pages/viewpage.action?pageId=71241). Note that this includes the requirement that the [[xref: TOIP, EGF]] and all [[xref: TOIP, governed parties]] must be identified with a [[xref: TOIP, DID]]. -TODO: Add normative ref to [ToIP Governance Architecture Specification](https://wiki.trustoverip.org/pages/viewpage.action?pageId=71241) +::: todo +Add normative ref to [ToIP Governance Architecture Specification](https://wiki.trustoverip.org/pages/viewpage.action?pageId=71241) +::: * [GA-4] MUST publish, in the [[xref: TOIP, DID document]] associated with the **DID** identifying its **EGF**, a [[ref: service property]] specifying the [[ref: service endpoint]] for its [[ref: primary trust registry]] that meets the requirements in the _[Trust Registry Service Property](#trust-registry-service-property)_ section. [GA-5] MUST publish in its EGF a list of any other EGFs governing [[ref: secondary trust registries]]. @@ -84,15 +81,35 @@ The [[xref: TOIP, DID document]] for the **DID** that identifies an **EGF** comp * [TRSP-2] The value of the `serviceEndpoint` property MUST be exactly one HTTPS URI. -::: issue -https://github.com/trustoverip/tswg-trust-registry-protocol/issues/5 -- Should align with Service Profiles/[Service Discovery] efforts +::: todo +FIX ::: [[ref: Registered entities]] MUST indicate which registries they are part of. * [TRSP-3] Registered entities MUST indicate the [[ref: primary trust registry]]] for a particular [[ref: authorization]]. + +#### Service Profile Recommendation + +_the following recommendation is non-normative_ + + +It is recommended that the service leverage the [Service Profile +Specification](https://github.com/trustoverip/tswg-trust-registry-service-profile/blob/main/spec.md). +Trust Over IP hosts a [Service Profile]() with the following pointer: + +```json +{ + "integrity": "<>", + "profile": "<>" + "uri": "" +} +``` + +By implementing service profiles, it enables easier interoperability and +discovery of service capabilities for the trust registry being implemented. + ### Trust Registry Protocol [TRP-*] The authoritative technical specifications for the API calls in the ToIP Trust Registry Protocol V1 are specified in Appendix A (OpenAPI YAML file). This section contains a textual description of the **requirements**. @@ -117,7 +134,7 @@ The authoritative technical specifications for the API calls in the ToIP Trust R - ii. [TRP-3-2] **Recognized Registry:** Given the entityDID the system SHOULD return the list of [[def:trust registries]] that the entity has indicated it is registered in. - [TRP-3-2-1] The system MUST NOT return more than one trust registry in the array designated as a [[def: primary registry]]. -::: TODO: +::: todo CREATE TrustRegistryType and TrustRegistryListType in OAS. ::: diff --git a/spec/revision_history.md b/spec/revision_history.md index 021638c..a845266 100644 --- a/spec/revision_history.md +++ b/spec/revision_history.md @@ -1,4 +1,6 @@ **Revision History** +::: note [[This section applies after the specification has been released for a Public Review, including Implementers Public Review]]. +::: diff --git a/spec/terms_and_definitions.md b/spec/terms_and_definitions.md index 13c6ce5..a1f5ed2 100644 --- a/spec/terms_and_definitions.md +++ b/spec/terms_and_definitions.md @@ -7,11 +7,8 @@ [//]: # (: file format defined by ISO 32000-2) - - ## Terms & Definitions - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [[spec-inform:RFC2119]] when, and only when, they appear in all capitals, as shown here. [[def: authorization, authorizations]]: @@ -40,7 +37,6 @@ https://github.com/trustoverip/tswg-trust-registry-protocol/issues/6 * Source: [NIST](https://csrc.nist.gov/glossary/term/permission) - [[def: primary trust registry]]: ~ The single [[xref: TOIP, trust registry]] that is considered the primary source for information of a particular type in an ecosystem. @@ -53,8 +49,6 @@ https://github.com/trustoverip/tswg-trust-registry-protocol/issues/6 ~ Source: [[spec-norm:DID-CORE]] [[def: service property]]: -~ TODO: - * in context of: [TRP-1] ...MUST publish, in the [[xref: TOIP, DID document]] associated with the **DID** identifying its **EGF**, a [[ref: service property]] specifying the [[ref: service endpoint]]