added new architectural overview

[jandrieu]

A proposed new architectural overview, based on discussions with both CHAPI and supply chain use cases.

---

Preview | Diff

[jandrieu]

To preview this with the diagrams, try https://legreq.github.io/vc-api/

[David-Chadwick]

On 26/10/2021 21:41, Joe Andrieu wrote: To preview this with the diagrams, try https://legreq.github.io/vc-api/ Bingo. You hit the jackpot this time :-) David — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android. [ { ***@***.***": "http://schema.org", ***@***.***": "EmailMessage", "potentialAction": { ***@***.***": "ViewAction", "target": "#237 (comment)", "url": "#237 (comment)", "name": "View Pull Request" }, "description": "View this Pull Request on GitHub", "publisher": { ***@***.***": "Organization", "name": "GitHub", "url": "https://github.com" } } ]

[OR13]

@jandrieu thanks so much for taking to time to discuss these flows with @mprorock and myself, its a helpful reminder of how important visualization is to our work.

[agropper]

Figure 2 and the description of the Holder App put human subjects at an unnecessary disadvantage relative to Issuers by linking control to possession.

It is also likely to increase the overall implementation costs of multi-tenant services by fragmenting the market between service providers to Issuers and to Holders. For example, multi-tenant storage services are valuable to both Issuers and Subjects even as the delegated control aspects for these storage services might be provided by other multi-tenant fiduciaries to both Issuers and Subjects where the fiduciary never has possession of the credentials themselves. This, for example, is how a money manager firm as delegate provides cost-effective services even as the banks are providing multi-tenant asset storage to both institutions and individuals. European PSD-2 regulations are a modern example of this.

Third, the linkage of credential control to credential possession damages both security and privacy by ignoring the principle of separation of concerns. This is particularly evident as systems move to implement zero-trust architecture.

Many real-world use-cases for verifiable digital credentials recognize the need for delegation by both Issuers and Subjects. Figure 2 does not adequately reflect real-world trust boundaries and the major privacy engineering differences between long-lived credentials like a driver's license and a short-lived credential like a boarding pass. In the example of a Cruise Ship Boarding Pass the Verifier (cruise operator) uses multi-tenant services to issue a short-lived policy-based boarding credential based on delegation of services to a verifier of a long-lived (vaccination) credential. The Subject's role in this case is purely as controller and their trust relationship is only with the cruise ship operator and not with any of their delegates. In US healthcare HIPAA law, these key multi-tenant Issuer and Verifier delegates are called HIPAA Business Associates.

I suggest that VC API and the architectural overview begin by acknowledging the business importance of delegation to multi-tenant services and the importance of separation of concerns to security and privacy.

[agropper]

I object to this merge of the architectural overview and will propose new text.

[agropper]

I was asked to provide text pertaining to this PR and I'm not sure the best way to do that. Here's proposed text for Section 1. Related issues include #58, #181, #234, #189, #100.

1. Introduction

Verifiable Credentials (VC) are a standard data model designed to mitigate risks of misuse and fraud. As a data model, VCs are protocol-neutral and consider only two roles: issuer and subject. When the subject of a VC is a natural person or linked to a natural person, privacy and human rights can be impacted by the vastly more efficient processing of standardized VCs as compared to their analog ancestors.

Technology, in the form of standardized APIs and protocols for issuing VCs, further enhances the efficiency of processing VCs and adds to the risks of unforeseen privacy and human rights consequences.

VC issue has a request phase and a delivery phase. The request may be made by the subject or another role and delivery can be to a client that may or may not be controlled by the subject. Delegation is highly relevant for both phases. The issuer may delegate processing of the request to a separate entity. The subject, for their part, may also delegate the ability to request a VC to a separate entity. The ability to delegate is a third dimension in the enhanced efficiency of processing VCs and has impact on privacy and human rights.

VC API architecture is designed for market acceptance through a combination of efficiency and respect for privacy and human rights. APIs and protocols for VC processing do not favor delegation by the issuer role over delegation by the subject role.

[brianorwhatever]

@agropper how does this relate to this PR? Is your proposed text meant as an introduction to the architectural overview, or the entire VC API? If it is the latter it should be in a separate pull request and not prevent the architectural overview from moving forward.

[jandrieu]

@agropper Unfortunately, this language is inconsistent with the VC Data model as published.

I have tried to understand your points of concern about holders, but frankly, I don't get it. Holders are the person who literally holds the VC. They may or may not be the subject.

That's simply how it works. It's as foundational as physics is to biology and biology is to health. Denying the physical reality of the situation is not going to improve our outcomes.

It might be that someone inappropriate got ahold of the VC and are presenting it.

Or, it might be that someone appropriate got ahold of the VC and are presenting it, such as an administrative assistant helping an executive make travel arrangements or a mother handling her child's medical records.

Both of these cases illustrate the fundamental role that Verifiable Presentations have in establishing the relationship of the presenter to the subject, whether or not they are the subject. If you remove the distinction between holder and subject, it is literally impossible to have a conversation about situations where the holder is not the subject: both the appropriate uses we want to support and the inappropriate uses we want to defend against.

Continuing to disregard the vocabulary already published in the VC Data Model specification--which the VC API is based upon--doesn't help us incorporate or otherwise respond to your concerns except by attempting to clarify the language error you continue to make.

Please note that you had every opportunity to advocate for your position in the recent update to the VC Data Model, which can be viewed here: https://www.w3.org/TR/2021/REC-vc-data-model-20211109/ This version 1.1 has just been released for public review and a W3C Advisory Committee vote. You'll note that the foundational role of the holder continues to be defined in that specification.

You can't just wave your hand and make holders disappear. They are a real thing in the real world and they are formally recognized in the VD Data Model.

I recommend closing this issue here and opening it in the VC Data Model, where it can at least be considered. The VC-API specification is not the right place to redefine terms in the VC Data Model. https://github.com/w3c/vc-data-model/

[agropper]

@jandrieu We're both talking about delegation and the context is (VC-API) protocols, not VC Data Models. As far as I know, holder is not an attribute in a VC.

In this context, your proposal talks about issuers delegating to service providers and you also effectively describe the role of delegation to an executive assistant or a mother by a subject.

In my proposed introduction text, I am careful to refer to VCs where the subject is a human or directly relates to a human. The VC Data Model and VC-API do not distinguish among subject species and both you and I argued for "herd privacy" in other contexts in order to protect the privacy of humans.

VC API is absolutely the best place to be discussing delegation in support of VCs. The record for this group shows my concerns with bundling VC Issuer with Holder and Verifier in the same specification. The group decided to move in spite of my concerns and I have tried to respect that decision.

The privacy and human rights issue I have been raising does not depend on the definition of holder vs. controller. According to Christopher Allen and maybe others, the VC Data Model chose to use holder in order to avoid using owner. As I recall the subject-holder discussions went on for many months and still come up on occasion.

Christopher Allen and I both believe that support for the Law of Agency is critical to adoption of VCs. At the VC API protocol levels, that translates into support for delegation by both the Issuer and the Subject.

In summary, the VC Data Model group can decide to reduce downstream confusion and potential privacy and human rights objections at any time but that is not a protocol issue. Please let's try to resolve the delegation protocol issue here in the VC API group.

[mprorock]

You can't just wave your hand and make holders disappear. They are a real thing in the real world and they are formally recognized in the VD Data Model.

I recommend closing this issue here and opening it in the VC Data Model, where it can at least be considered. The VC-API specification is not the right place to redefine terms in the VC Data Model. https://github.com/w3c/vc-data-model/

Implementer hat on:
+1 This is a work item that is focused on defining an API for performing operations related to VCs. That means that it will accept the standard as it is, otherwise, honestly, what value would it have to those who want a spec to conform to for API interactions around VCs. As an implementer of tech that utilizes VCs per the VC Data Model, I have no value from an API or specification that does not conform to that data model.

Chair hat on:
This is pre-standards work. A lot of effort by @jandrieu and others went in to diagramming and documenting the existing, as implemented in the wild processes as they relate to the VC Data Model as published as a W3C standard. This work is not final, and should be viewed as evolutionary in nature.

Attempting to deviate from the VC Data Model would be inappropriate for this work item (In my opinion as a Chair).

If there are areas outside of the scope of this PR, please issue a new PR with suggested changes. If there are suggestions for adjustments to a PR please make those concrete suggestions to the PR via the documented github process for suggestions so that they can be diffed, compared, and reviewed.

The job of the editors of a Work Item is to determine the consensus of the group, and in this case, if drafting a possible specification that relates to an already published and accepted standard, to ensure that work done conforms with that standard. It is the editors decision how to proceed or escalate as desired.

[dmitrizagidulin]

Though I do not formally object, I do want to bring up some concerns, on the record.

1. I disagree with including the Admin boxes (Issuer Admin, Verifier Admin, Holder Admin) as separate from the Service. I don't think that accurately reflects most (all?) VC API deployments out there -- in most cases, the Issuer/Verifier App contains the business rules in its code (not even in the config, in code specifically), and there's no meaningful way to separate the rules from the app.
2. It would be great to add a key to the diagram - what do ovals, squares and rhomboids mean, in the diagram?
3. I'm not sure the person icon for Issuer and Verifier is useful.
4. I strongly disagree about the inclusion of the Storage service component for the Issuer and Verifier. Many issuers and verifiers do not in any way store the VCs they're dealing with. At very least, those components should be marked as optional.

[jandrieu]

@dmitrizagidulin I think you're missing the point of the diagram.

It is NOT to say what components are in spec. It isn't even to say which endpoints are in spec.

It is precisely to enable you to make the points you are making.

Without the distinction of storage and admin, we lack a shared language to explain what is in or out of scope. IMO, every flow in that architecture diagram, and indeed, every message in the sequence diagrams, should be evaluated for standardization.

This diagram gives us a foundation for that conversation. Nothing more.

[msporny]

@dmitrizagidulin would like a key to the diagram in a separate PR.

[msporny]

Editorial, multiple reviews, changes requested and made, no remaining objections, merging.