Add 'id' to auth suites

[dmitrizagidulin]

It would be very helpful (in terms of key add/remove/rotate operations), if we added ids to the authentication/authorization suites in the spec. (That way, they can be addressed individually, as opposed to their index in the array of suites.)

So, currently:

{
  "@context": "https://w3id.org/veres-one/v1",
  "id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
  ...
  "grantCapability": [{
    "type": "Ed25519SignatureCapabilityAuthorization2018",
    "publicKey": {
      "id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#ocap-grant-key-1",
      "type": "Ed25519VerificationKey2018",
      "owner": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
      "publicKeyBase58": "HURvcFiZbmtaQQMhkVVoq1JpxxRe8UrBS5wBQMJhXkfM"
    }
  }],
  "invokeCapability": [{
    "type": "Ed25519SignatureCapabilityAuthorization2018",
    "publicKey": {
      "id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#ocap-invoke-key-1",
      "type": "Ed25519VerificationKey2018",
      "owner": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
      "publicKeyBase58": "Gu5yfYsbYvmSeSsAbBBNafy9i6G3o5kiX5PxUGPg1iFJ"
    }
  }]
}

Proposed:

{
  "@context": "https://w3id.org/veres-one/v1",
  "id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
  ...
  "grantCapability": [{
    "id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#grant-suite-1",
    "type": "Ed25519SignatureCapabilityAuthorization2018",
    "publicKey": {
      "id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#ocap-grant-key-1",
      "type": "Ed25519VerificationKey2018",
      "owner": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
      "publicKeyBase58": "HURvcFiZbmtaQQMhkVVoq1JpxxRe8UrBS5wBQMJhXkfM"
    }
  }],
  "invokeCapability": [{
    "id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#invoke-suite-1",
    "type": "Ed25519SignatureCapabilityAuthorization2018",
    "publicKey": {
      "id": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ#ocap-invoke-key-1",
      "type": "Ed25519VerificationKey2018",
      "owner": "did:v1:nym:4jWHwNdrG9-6jd9I7K1si3kTRneNwftZV9m6rkrAfWQ",
      "publicKeyBase58": "Gu5yfYsbYvmSeSsAbBBNafy9i6G3o5kiX5PxUGPg1iFJ"
    }
  }]
}

[msporny]

It would be very helpful (in terms of key add/remove/rotate operations)

I'm going to annoyingly question the hypothesis... why does having an ID help for this specific use case (I get why it helps in other use cases). For example, when one part of the system needs to refer to another part of the system, and id helps. We have such a requirement for keys... but we don't have such a requirement for suites and capabilities, do we?

For UIs, I expect that they'll track via index in the array. For non-UIs, I expect they'll match on other things (not the id, because not everything is required to have an id).

[dmitrizagidulin]

@msporny an excellent question.

Ok, so, say one is (hypothetically) implementing an addKey() method on a DID Document. How would you, as a developer, expect to invoke that method to add a key to that first grantCapability suite? Because there's nothing really to match that suite on (assuming there can be more than one grantCapability suite of type Ed25519SignatureCapabilityAuthorization2018).

If array index is preferred, so you'd be invoking it via addKey({key, suiteType: 'grantCapability', suiteIndex: 0}), since presumably a user is looking at UI somewhere, that's fine. (In which case, this issue can be resolved.)

But for non-UI cases, if there's like some key rotation cron job, how would it refer to a particular suite?

[dmitrizagidulin]

Yeah, I think part of what I'm unclear on is the intended use case for multiple suites (within the same category and having the same type). (So I can't quite picture the UI)

[msporny]

How would you, as a developer, expect to invoke that method to add a key to that first grantCapability suite?

By index, I think that works for now.

The larger issue when trying to "name" suites is what name to use. Remember, the names you use not only have to be unique in the document, but unique through time (if you want to avoid weird temporal naming issues -- did you mean #suite-1 that was used in 2018, or #suite-1 that was used in the year 2024), which means that you end up picking UUIDs for the fragment identifiers (or something to that effect). This problem is common to every fragment identifier, so it's no reason NOT to do what you're saying. Also, we can't prevent people from creating ids... but insisting that they're always there is also an issue. ids have always been optional on suites. We could change that, but only if we absolutely must do so.

I'm unclear on is the intended use case for multiple suites (within the same category and having the same type)

You may want to be able to grant capabilities from two different machines. So, instead of sharing one key between two machines, you add two suites that only differ by their key.

But for non-UI cases, if there's like some key rotation cron job, how would it refer to a particular suite?

Since we can't say that suites MUST have an id (or, rather, I'm concerned about mandating that)... then you have to be able to use another mechanism. More than likely, a key rotation cronjob would have some other logic (like knowing what key needs to be rotated and when)... and in that case, it can use the key fingerprint, or the key id, or the publicKeyBase58, etc.

[dmitrizagidulin]

which means that you end up picking UUIDs for the fragment identifiers

Yeah, that's what I was picturing doing.

Anyways, I can go with referencing by suite array index, no prob. Feel free to close the issue.

[msporny]

Anyways, I can go with referencing by suite array index, no prob. Feel free to close the issue.

To be clear, I'm fine w/ creating ids if we need to. Just doesn't feel like we need to just yet. Closing, re-open if you feel there is no other way to do it.

[msporny]

Oh, also - keep in mind that array position doesn't mean anything. Those things are mathematical sets (not lists)... the array ordering is not preserved (or at least, you can't count on it).

[dmitrizagidulin]

I was thinking about that too, re array position not meaning anything. Which would be an argument for suite IDs, right? :) But I figured that you meant that if a user is looking at some UI and needs to add a key to it, the app behind the UI will have an actual order-preserving array which it can use to manipulate via array index.