Controller Documents

[brentzundel]

There seems to be a need for a single definition of a controller document that can then be used by various VC securing specs (e.g., VC-DI and VC-JOSE-COSE).

This issue is for tracking the discussion and begins with the suggestion that the core data model makes the most sense as a "neutral" place for this definition that will require the least amount of additional effort.

[selfissued]

We need to create the common Controller Document specification before any of the securing specifications go to CR. This is tracked in the securing specifications at w3c/vc-jose-cose#160 and w3c/vc-data-integrity#216.

This needs to happen before CR because normative changes are needed to the Controller Document description in Data Integrity to enable it to be shared with VC-JOSE-COSE. We need to make these changes before CR so making them doesn't force us to inevitably have another round of CRs for both securing specifications.

[msporny]

We need to create the common Controller Document specification before any of the securing specifications go to CR.

-1, we need to demonstrate that the definitions of controller documents in both vc-jose-cose and vc-data-integrity are going to converge before we can have a common specification. What you say below...

@selfissued wrote:

This needs to happen before CR because normative changes are needed to the Controller Document description in Data Integrity

...indicates that you intend to suggest breaking changes to vc-data-integrity, which would be objected to, and hold up both specifications for an unknown period of time. This would be unacceptable given the timeline of the WG. DI is ready to go into CR now and has multiple independent implementations.

As we discussed on the last telecon, we can do this work in parallel and converge if there is a definite path to convergence. If there is true convergence, DI implementations will not need to change (and we won't need to go through a 2nd CR). If normative changes are necessary, they should be minor, and a 2nd CR is not a huge lift.

[iherman]

The issue was discussed in a meeting on 2023-10-24

List of resolutions:

• Resolution No. 1: The working group will create a Controller Document specification, with the intent that it become a recommendation, containing functionality and definitions that are common to both securing specifications (VC JOSE COSE and Data Integrity).
• Resolution No. 2: Once the Controller Document specification is in the Candidate Recommendation phase, the corresponding Controller Document functionality will be removed from both securing specifications and replaced by normative references to the Controller Document specifications.
• Resolution No. 3: The securing specifications will profile the shared document as needed.

View the transcript

1. Controller Documents.

See github issue vc-data-model#1307.

See github issue vc-data-integrity#216.

See github pull request vc-data-integrity#219.

Brent Zundel: Just for tracking purposes. Where we're at: DI and vc-jose-cose specify some sort of controller document.
… The differences have led to the current proposal to have a separate document that is a controller document spec, which we're expecting to be minimal.
… selfissued reached out to the chairs with a set of proposals. Suggestion is to go over them in this call.

Orie Steele: You can put the resolution on the issue as well.

Orie Steele: or rather the proposals.

Michael Jones: Proposed Resolution 1: The working group will create a Controller Document specification containing functionality and definitions that are common to both securing specifications (VC JOSE COSE and Data Integrity).

Michael Jones: The goal here is to have a path forward for securing specs and controller docs.

Michael Jones: Proposed Resolution 2: The corresponding Controller Document functionality will be removed from both securing specifications and replaced by use of the new shared document.

Michael Jones: Proposed Resolution 3: The securing specifications will profile the shared document as needed.

Michael Jones: Proposed Resolution 4: The shared document shall not include the use of multibase or multihash. This functionality will instead be included in the Data Integrity-specific profile.

Michael Jones: Proposed Resolution 5: The shared document does not have to include key discovery using .well-known URLs. If it is not included, it will instead be included in the VC JOSE COSE-specific profile. (The working group can choose to include it as a separate decision, if desired).

Michael Jones: Proposed Resolution 6: We will create the new shared document and use it from the securing specifications before either goes to CR.

Michael Jones: And if we have time, we should pass one of:.

Michael Jones: Proposed Resolution 7: The shared document will include key discovery using .well-known URLs.

Michael Jones: Proposed Resolution 8: The shared document will not include key discovery using .well-known URLs.

Brent Zundel: Proposals build on one another. Let's get started.

Manu Sporny: Looking at the proposals I can see controversy in 4, 5, 6, 7 and 8. Concerned with this being reopened before DI going into CR.
… There's a clear preference in 4-8 for vc-jose-cose.
… Feels like it's going to put the work on hold for securing.

Michael Jones: No intent to have preferences for a single securing spec.
… Intended to be even handed, and give us a clear path forward as a WG.
… I'd like WG to be on record on whether we'll do the split, regardless of whether we'll go to CR or not.

Orie Steele: Process question, is CR a thing the WG decides?

Brent Zundel: The WG resolves to go to CR (which we've done for vc-json-schema, and others).
… Then the editors move those specs by clicking the correct buttons and drafting docs.

Michael Jones: +1.

Andres Uribe: +1.

Gabe Cohen: +1.

Manu Sporny: I'd change to "will attempt to". It might not be successful.

Brent Zundel: I'll wordsmith this.

Michael Jones: Feels like it's watered down. I would rather be on record on what we plan to do. Ok if we fail.

Proposed resolution: The working group will create a Controller Document specification, with the intent that it become a recommendation, containing functionality and definitions that are common to both securing specifications (VC JOSE COSE and Data Integrity). (Brent Zundel)

Brent Zundel: +1.

Michael Jones: +1.

Orie Steele: +1.

Manu Sporny: +1.

Gabe Cohen: +1.

Shigeya Suzuki: +1.

Andres Uribe: +1.

Dave Longley: +1.

Core5069: +1.

Ted Thibodeau Jr.: +1.

Resolution #1: The working group will create a Controller Document specification, with the intent that it become a recommendation, containing functionality and definitions that are common to both securing specifications (VC JOSE COSE and Data Integrity).

Manu Sporny: Needs to say something about timing on when the functionality will be removed.

Ted Thibodeau Jr.: +1 manu.

Michael Jones: I've intentionally worded this so they're independent.
… Prop 6 talks about timing. I don't want to talk about it now.

Ted Thibodeau Jr.: Batch resolutions need to be handled as batch proposals. Doing it in the proposed order leaves significant holes.
… In the proposed order it's possible to create a doc that doesn't go into CR, after moving functionality. If that comes to pass, we'll need to reinsert it.
… Don't think this piecemeal proposal is viable.

Brent Zundel: Wordsmithing all at once seems difficult, but we can attempt.
… Open to concrete suggestions on how we can move forward.

Dave Longley: Thinking we need to include intent. Re: path forward - a sticking point is whether this delays CR.
… Will this enable us to move forward without delaying CR?

Manu Sporny: I made the concrete suggestion that we specify when the functionality will be removed (after controller document enters CR).
… That should be a fine time to remove.
… Trying to get the proposal to pass.

Core5069: +1 to TallTed's proposal.

Michael Jones: Couldn't make last week call. Issue says it's a pre-CR issue. We should deal with it. Timing should be a separate proposal.

Orie Steele: Seems like what we're saying is don't have anything delay DI getting into CR.
… Maybe we do the other proposals before we address this one?

Brent Zundel: Are you proposing we tackel #6?

Manu Sporny: I think this is a bad idea. We've already went through the logic of not delaying CR in multiple calls.

Dave Longley: agree with Manu that this is a bad idea, i will not vote to delay CR.

Manu Sporny: All publications are aiming to be published on nov 7.
… Was initially a +1 to moving the controller document outside, because it looked like we would get to some common ground.
… That doesn't look to be the case. We originally proposed moving it outside of DI as-is, into the outside doc.

Orie Steele: We have time for 2 CRs afaik.

Manu Sporny: What we're seeing is that multiple changes are being asked (removing some pieces).

Brent Zundel: chair hat off, I would -1 this. I believe we should go into CR with Data Integrity and change it should we succeed with a common controller document.

Manu Sporny: I think we shouldn't have that affect the DI timeline. If we succeed getting the controller document into CR, then we have created something common.
… If we are successful moving out, and we come to consensus that normative changes need to happen in the controller document, then DI has to go into CR review again. That is a 28 day turn around.

Ted Thibodeau Jr.: Is "either" in prop6 meant to refer to the two securing specs (VC JOSE COSE and Data Integrity) plus the new Controller Document? I think that "either" should be "any", if so. If not, please explain what this "either" is meant to refer to.

Manu Sporny: I'm not convinced we'll get the consensus. Blocking DI would delay publication even more.

Shigeya Suzuki: I read through data integrity last weeks and feels that placement of the controller document in DI looks odd and difficult to understand.

Michael Jones: I think we should run the proposals. The editors of vc-jose-cose will appreciate understanding the intent.

Dave Longley: we already passed proposal 1, that indicates an intent to have one.

Brent Zundel: The intent is to have 1.
… We can run the proposals and then see where people are at.
… Let's all take some deep breadths.
… Any proposal that calls for a delay of DI going into CR is clearly not going to pass.

Core5069: that shared document goes to cr?

Phillip Long: +1 for that proposal.

Brent Zundel: Would anyone -1 this? If so, what changes would you like to see?

Michael Jones: preaent+.

Brent Zundel: I think this would still possibly force a second CR.

Ted Thibodeau Jr.: Not a -1. Concerned this doesn't say anything about when it's going to happen.

Manu Sporny: The belief is that this modification would not cause a second CR for DI, because implementations would not have to change the way they're implemented.
… If it doesn't, it's because the group has come to consensus that we're ok going through a second CR. It's quick as it's only 30 days turnaround.

Paul Dietrich: Is this a merge, or just copying text?

Ted Thibodeau Jr.: Have of my concern is that there might already be differences between docs. I don't know.
… The second piece is that as a stand alone document, it will get issues. There is no guarantee that implementations will not need to change.

Brent Zundel: The paths before us: 1) We copy paste (with slight modifications) from DI/vc-jose-cose to this doc. No changes to implementation in DI, not blocking.
… 2) We cannot get this document into CR. So DI will still profile, and vc-jose-cose will profile. No common ground, we failed.
… There are paths in the middle, which include going into a second CR phase.
… Believe it's possible to get to 1), which is the happy path.

Ted Thibodeau Jr.: +1 manu's new draft.

Proposed resolution: Once the Controller Document specification is in the Candidate Recommendation phase, the corresponding Controller Document functionality will be removed from both securing specifications and replaced by normative references to the Controller Document specifications. (Brent Zundel)

Manu Sporny: +1.

Dave Longley: +1.

Andres Uribe: +1.

Ted Thibodeau Jr.: +1.

Gabe Cohen: +1.

Phillip Long: +1.

Orie Steele: +1.

Brent Zundel: +1.

Core5069: +!

Shigeya Suzuki: +1.

Paul Dietrich: +1.

Core5069: +1.

Michael Jones: Or we rip controller document support out of vc-jose-cose if we fail to reach consensus on a controller document spec.

Michael Jones: +1.

Resolution #2: Once the Controller Document specification is in the Candidate Recommendation phase, the corresponding Controller Document functionality will be removed from both securing specifications and replaced by normative references to the Controller Document specifications.

Brent Zundel: Proposed resolution #3 is straigthforward. Let's do it.

Manu Sporny: Question for selfissued, can we downscope them? I saw a proposal to remove content from them. That says we would be removing existing content.
… That raises the question, does publicKeyJwk stay there?

Michael Jones: The intent isn't to profile to remove stuff. The controller document is meant to have stuff in common.
… You would profile it to add things that aren't in common.

Manu Sporny: Controller documents are meant to have verification material. That's my concern, we're talking about gutting what controller documents are about.
… It's going to take effort from the group to get there. We can try it, but it's not what I was expecting when people said profile. Profile usually involves a subset.
… The other thing they have in common is that DI doesn't shove publicKeyJwk out.

Dave Longley: i did not vote for an "end around" way to make VC-JOSE-COSE preferences the default.

Dave Longley: there is no common "preference" for JWKs.

Orie Steele: I am concerned about giving bad security advice... regardless of which document the advice is in.

Ted Thibodeau Jr.: Struggling not to feel ambushed by the proposals. Clearly there was thought put into it, but not all ramifications were thought through.

Dave Longley: Orie: We're all concerned about giving bad advice -- for anything :).

Brent Zundel: I believe in the positive intentions of both sides of this conversation. I don't think either side is trying to manipulate into some place of superiority. The intention is always to write the best spec.

Michael Jones: If manu's primary concern is about the amount of work, i'll do it.
… We think always using publicKeyJwk in vc-jose-cose is the best decision for interop.

Dave Longley: i am totally fine with VC-JOSE-COSE having a preference for key formats in that specification.

Orie Steele: +1 to selfissued comment.

Core5069: I think the controller document must avoid key representations, but that is a significant portion of DI.

Manu Sporny: Not worried about doing the work, more about taking time off of other things.
… I believe the WG can do it.

Dave Longley: if there is no common preference for key formats -- then that has no place in a common controller document.

Brent Zundel: Seems straighforward that we can make this work happen.

Dave Longley: +1 to Joe, totally agree -- we must not endorse something that isn't commonly endorsed.

Dave Longley: (in the shared document).

Orie Steele: I don't think these proposed resolutions imply any specific changes to the specs, they offer the ability to reflect WG consensus.

Joe Andrieu: Wanted to underscore what manu just said. Not about games. The way the proposal is structured would prefer publicKeyJwk.

Brent Zundel: We're nitpicking about the potential detail of a spec that hasn't been written.
… It's a fact that common things will be only the consensus agreed upon things.
… We aren't talking about specifics yet. No one is suggesting that. We are assuming ill-intent. Please assume good intent. The work in this group will fail if you don't have an open mind.

Dave Longley: +1 to brent's articulation of "common".

Core5069: of you respect my opinion, I ask you not to call it nitpicking.

Dave Longley: i think the trouble was in what "common" meant, so +1 to brent.

Orie Steele: +1 Brent, we might end up saying less, if we have to agree... but isn't it worth trying to agree?

Shigeya Suzuki: +1 to Brent.

Core5069: it's the algorithm of common.

Orie Steele: +1 Brent : ).

Ted Thibodeau Jr.: ftr, I am not assuming ill intent. I am asserting inability to sufficiently consider these proposals within this meeting.

Proposed resolution: The securing specifications will profile the shared document as needed. (Brent Zundel)

Orie Steele: +1.

Shigeya Suzuki: +1.

Michael Jones: +1.

Gabe Cohen: +1.

Brent Zundel: +1.

Andres Uribe: +1.

Core5069: -1.

Paul Dietrich: 0 I think the group has different opinions on "as needed" and that makes it impossible for me to decide.

Dave Longley: +1 for securing specs to indicate their specific preferences from the shared doc.

Ted Thibodeau Jr.: +0.

Paul Dietrich: can we replace as needed with more specific language.

Phillip Long: +0.

Joe Andrieu: My concern is more about all the proposals together. I reserve the right to object depending on what happens with the specs.

Manu Sporny: -0 we need to understand "profile" and "as needed" -- I could support a proposal that was more clear about those things.

Resolution #3: The securing specifications will profile the shared document as needed.

Orie Steele: +1 to assuming good intent, and finding common ground.

---

[iherman]

The issue was discussed in a meeting on 2023-10-25

List of resolutions:

• Resolution No. 1: The shared Controller Document specification will include all Controller Document features that are used by the securing specifications today, and each individual securing specification can profile the Controller Document spec down to make specific choices as desirable.

View the transcript

2.1. Controller Documents (issue vc-data-model#1307)

See github issue vc-data-model#1307.

See github issue vc-data-integrity#216.

See github pull request vc-data-integrity#219.

Brent Zundel: We'll begin with the continuation of the topic of our special topic call, which was Controller Doc.
… there were a number of proposals that were brought before the group.
… 3 of them were resolved.
… check email / notes.
… there are 4 more proposals that have been brought up, 3 of them concerning the same thing, and one I'm very confident won't pass even after long discussion.
… the focus will be around Key Discovery.
… specifically, discovery using '.well-known/'.
… one of the proposals says 'Shared doc will NOT use key discovery'.
… the other one says, maybe we should do key discovery using .well-known.
… would it be amenable to the group for the primary doc to do .well-known as primary mechanism.
… if there's consensus, we'll run a proposal.

Michael Jones: it makes sense to include that, it's a standards based key representation used in practice.
… so it makes sense to make it available to both securing specs.

Dave Longley: so, thinking about our call yesterday and the resolutions,.
… and was thinking forward to how some securing specs might want to profile down.
… as we agreed in the last resolution, and other specs might want to keep those options open.
… given that, it only makes sense for the shared doc to provide multiple options.
… I think that's were some of us were thinking when we were talking about things in common.
… we might get more consensus on things like '.well-known', if we agree that shared doc has things in it that may or may not be referenced by secured implementations.
… if we're ONLY going to put things into the shared doc that current specs reference, that'll show preference for options where it's not needed.
… I'm concerned we'll end up making different decisions on that basis, stripping down the shared document.
… as a result, we might need to have multiple shared documents.
… might be better for us that the shared doc has things that securing specs MAY reference.
… that way, we can more likely get to a consensus on something like .well-known (given concerns of preference).

Orie Steele: Seems like showing preference for things that both specs use, would be good for implementers.

Manu Sporny: ^ not when that preference doesn't exist, Orie.

Manu Sporny: To say that the Data Integrity specs "prefer JWK" is not correct, it's provided as an option.

Brent Zundel: just to repeat, we have one suggestion from Mike that .well-known be included.
… Dave is suggesting additionally that the core Controller Doc spec be inclusive of not just .well-known but other securing mechanisms / discovery mechanisms.
… so that specs like VC J/C and DI can choose among the options there as a profile.

Dave Longley: yes, that's great.
… if we do that generally, across all of our options, we'll have a much easier time to come to consensus.

Dmitri Zagidulin: As a data point, about the .well-known mechanism, based on some recent VC implementations, there are a number of institutions like universities that are not allowed to create folders with dots in them. There are education institutions that can't put their keys in .well-known due to their web control panels and whatnot. It's useful, but not everyone can use it.

Michael Jones: two responses.
… first to Dmitri - I certainly believe you, but if they can't use .well-known, they can't produce OAuth metadata, just a bunch of things they can't do.
… I feel for the people in those environments, but that may be not our problem to solve.
… I appreciate Dave's thoughtful remarks.
… my intent is to only have things in the shared controller doc that will be used for /both/ securing specs.
… if it lets us move forward, I'd hold my nose and accept some things that were not used by both, as long as the securing specs could profile it to say "don't use this part".

Orie Steele: Good thing did:web allows you to but controller documents at arbitrary locations...

Dave Longley: +1 to Mike, document everything in the shared spec and then profile down, that can get us to consensus.

Joe Andrieu: I'm not a fan of .well-known because it's anchored in a centralized resource/url.
… and I don't think that it applies to all our situations. I don't see VCs as a subset of the modern web, I see them as larger.

Brent Zundel: just to clarify, are you opposed to .well-known included at all, or to it being the /only/ mechanism.

Joe Andrieu: at all.

Dave Longley: i can hold my nose if everything (key formats, etc.) is in the shared doc and securing specs can profile down.

Manu Sporny: I wanted to agree with what Dave was saying, and what Mike Jones just said. it would be fine to include a number of things in the controller doc, put them in a single document.

Dave Longley: +1 to Manu.

Manu Sporny: and when you go to profile, you can say "Do not use X or Y, we don't want you doing that" -- that's perfectly fine.
… we'd provide all the options in the controller doc spec, and then securing specs will profile them.
… that feels like a good compromise, people who don't want to use features can call them out.

Kristina Yasuda: This is what SD-JWT VC spec does. It mentions multiple mechanisms: .well-known, DID, x.509, etc. see spec on datatracker.

Dave Longley: +1 to a resolution that says we provide all the "controller-document-related options" in the shared controller doc spec and then each securing spec profiles that down to what they accept.

Orie Steele: +1 Manu, although i still hope we can limit the controller document options to "good ones", if we can't agree on what good is, its ok to just split the difference.

Kristina Yasuda: And I think we should do the same here.

Manu Sporny: so, +1 to that. What that would mean is that we'd include 'publicKeyJWK', 'publicKeyMultibase', we'd include .well-known discovery mechanism.
… we'd include multiple algos in there.
… which means that the entirety of the contents of the DI spec could be lifted & placed into the new spec (minus DI-specific language).
… and we can add everything related in the JOSE/COSE spec. and add the language "Do not use X feature" etc.

Dave Longley: +1 to Manu, very supportive of that approach -- and its sounds like others in IRC would support as well.

Manu Sporny: so, +1 to that if it helps us move forward.
… I also don't like .well-known, but I'd hold my nose to it being added to the shared spec.

Brent Zundel: I believe we have roughly a path forward.
… we had one person comment that an aspect would not be acceptable; everyone else seems to be willing to move forward with this (the profiling approach).
… so I think we're to the point of trying to craft proposal language.
… I'm happy to do that unless someone else wants to craft resolutions.

Shigeya Suzuki: For a data point, for some usecases we will use .well-known.

Brent Zundel: here is draft proposal, anyone opposed? (and if yes, how should we change it).

Joe Andrieu: I have some concerns re temporality. the controller document 'will include', which seems in the future?
… or is it possible for securing specs to adjust what goes into it?
… so, causality needs clarifying.

Brent Zundel: my understanding is - both DI and Jose/Cose would be written in the controller doc, as they're written today.
… and then they could be modified as profiles etc.

Dave Longley: +1 to brent's interpretation.

Proposed resolution: The shared Controller Document specification will include all Controller Document features that are used by the securing specifications today, and each individual securing specification can profile the Controller Document spec down to make specific choices as desirable. (Ted Thibodeau Jr.)

Brent Zundel: does that help with causality, Joe?

Joe Andrieu: yes.

Kristina Yasuda: it seems that this resolution does not apply to just key discovery, but other aspects as well. is the intent to just mix all the features from the securing specs?

Manu Sporny: yes, my understanding as well. just to be crystal clear,.
… I'm looking at the VC DI controller doc section right now. it defines effectively what's found in DID Core, says you can use 'publicKeyJwk' and 'publicKeyMultibase', and the secretKey properties too.
… defines multibase bytes normatively.
… I don't know what's in VC JOSE/COSE, maybe Orie and Mike could speak to it.
… I'm hearing the .well-known stuff would move in there.
… also believe that we have a 'Retrieve Verification Method' algorithm that'd move into the shared doc.
… that also has a set of processing errors (table).
… things like, throwing an error about invalid controller doc, id, etc.

Dave Longley: +1 to Manu.

Manu Sporny: the errors would move too.

Orie Steele: the vc data integrity controller document defines capability system and encryption related terminology, which is not used in vc data model today.

Dave Longley: and VC-JOSE-COSE talks about .well-known (or would) and that would be put into the shared doc too.

Orie Steele: accurate. just in terms of current VC JOSE/COSE spec - it has already a profiled-down version, just needs to be able to refer to correct term definitions.
… current version in latest draft just expresses preference for common JOSE/COSE key representations. Does not contain elaboration on capabilityDelegation, capabilityInvocation or keyAgreement, as they're not used in VCs currently, to my knowledge.
… so when we constructed it, we took the DI definition, removed 'proof', multibase, the delegation and key agreement keys.

Kristina Yasuda: Clear, thank you.

Dave Longley: +1 for VC-JOSE-COSE to continue to profile down in the way Orie says.

Brent Zundel: with that, we are ready to run the proposal.

Proposed resolution: The shared Controller Document specification will include all Controller Document features that are used by the securing specifications today, and each individual securing specification can profile the Controller Document spec down to make specific choices as desirable. (Brent Zundel)

Manu Sporny: +1.

Dave Longley: +1.

Brent Zundel: +1.

Ted Thibodeau Jr.: +1.

Dmitri Zagidulin: +1.

Michael Jones: +1.

Shigeya Suzuki: +1.

Andres Uribe: +1.

Joe Andrieu: +1.

Paul Dietrich: +1.

Orie Steele: +1.

Benjamin Young: +1.

Resolution #1: The shared Controller Document specification will include all Controller Document features that are used by the securing specifications today, and each individual securing specification can profile the Controller Document spec down to make specific choices as desirable.

Brent Zundel: if I'm understanding correctly, this single proposal captures all of the stuff from the remaining resolutions & proposals from yesterday.
… I think we can move to other issues.

Dave Longley: +1 to Brent, this captures the rest in one way or another.

Manu Sporny: agreed.

Michael Jones: question to chairs (I'm open to many different answers) -- is it time to request volunteers to work on this new shared doc?

Brent Zundel: If there are folks on the call who want to volunteer, I'd love to hear it.

Michael Jones: I'll volunteer.

Manu Sporny: I'll volunteer.

Brent Zundel: solid editorial team. others are also welcome to volunteer now, or reach out to chairs.

[msporny]

A Controller Document specification exists now: https://github.com/w3c/vc-controller-document

Closing.