Skip to content

Commit

Permalink
Include support for VC 2.0 credentials.
Browse files Browse the repository at this point in the history 
Other updates, fixes, and clarifications.
  • Loading branch information
Wes Biggs committed Aug 29, 2024
1 parent 64dab1c commit 5faa5c2
Show file tree
Hide file tree
Showing 10 changed files with 90 additions and 180 deletions.
2 changes: 1 addition & 1 deletion book.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ preferred-dark-theme = "coal"
[output.linkcheck]
follow-web-links = true
traverse-parent-directories = false
exclude = ['en\.bitcoin\.it', 'github\.com/LibertyDSNP/spec']
exclude = ['en\.bitcoin\.it', 'github\.com/LibertyDSNP/spec', 'w3\.org']

[output.html.fold]
enable = true
120 changes: 16 additions & 104 deletions pages/ActivityContent/Associated/Attachments.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -209,35 +209,30 @@
}
```

## Attestations and Interactions
## Attestations

Attestation and Interaction attachments are DSNP extensions to the Activity Content model that allow Verifiable Credentials to be attached to content with clear semantics.
Attestation attachments are DSNP extensions to the Activity Content model that allow users to attach Verifiable Credentials corresponding to an Attribute Set Type with their DSNP profile or a social media post.

The Verifiable Credential found at the indicated URL must include the user's [DSNP User URI](../../DSNP/Identifiers.md#dsnp-user-uri) in its `credentialSubject.id` field.

| Property | Base Spec | Required | Description | Restrictions |
| --- | --- | --- | --- | --- |
| `type` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-type) | YES | Identifies the type of the object | MUST be set to `Attestation` |
| `url` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-url) | YES | An array of links for the given credential | MUST be a [Verifiable Credential Link](#verifiable-credential-link) |
| `name` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name) | no | The display name for the attestation | |

### Verifiable Credential Link

Both Attestation and Interaction attachments must contain a link to Verifiable Credential document.
Attestation attachments must contain a link to a Verifiable Credential document.
The link must contain a relationship identifier in the form of a DSNP Attribute Set Type (the `rel` field), to allow applications to determine the type of credential expected.

| Property | Base Spec | Required | Description | Restrictions |
| --- | --- | --- | --- | --- |
| `type` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-type) | YES | Identifies the type of the object | MUST be set to `Link` |
| `rel` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-id) | YES | The attestation's attribute set type | MUST be a DSNP [Attribute Set Type](../../DSNP/AttributeSets.md#attribute-set-type) corresponding to the referenced credential document |
| `href` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-href) | YES | The URL for the associated Verifiable Credential | MUST be a [Supported URL Schema](../Overview.md#supported-url-schema) |
| `mediaType` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-mediatype) | YES | MIME type of `href` content | MUST be set to [`application/vc+ld+json`](https://w3c.github.io/vc-data-model/#vc-ld-media-type) |
| `hash` | [DSNP 1.0](Hash.md) | YES | Array of hashes for linked content validation | MUST include at least one [supported hash](Hash.md#supported-algorithms) |

### Attestation

Attestations about a DSNP User may be included as attachments in an Activity object.
This format allows users to include relevant data corresponding to an Attribute Set Type with their DSNP profile or a social media content item.

The Verifiable Credential found at the indicated URL must include the [DSNP DID](../../VerifiableCredentials/Types/DID.md) of the user in its `credentialSubject.id` field.

| Property | Base Spec | Required | Description | Restrictions |
| --- | --- | --- | --- | --- |
| `type` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-type) | YES | Identifies the type of the object | MUST be set to `Attestation` |
| `url` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-url) | YES | An array of links for the given credential | MUST be a [Verifiable Credential Link](#verifiable-credential-link) |
| `name` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name) | no | The display name for the attestation | |
| `mediaType` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-mediatype) | YES | MIME type of `href` content | MUST be set to [`application/vc`](https://www.w3.org/TR/vc-data-model-2.0/#vc-ld-media-type) |
| `hash` | [DSNP extension](Hash.md) | YES | Array of hashes for linked content validation | MUST include at least one [supported hash](Hash.md#supported-algorithms) |

#### Example

Expand All @@ -254,84 +249,11 @@ The Verifiable Credential found at the indicated URL must include the [DSNP DID]
"url": [
{
"type": "Link",
"rel": "did:dsnp:123456$AcmeMedicalAssociation",
"rel": "did:dsnp:123456$AcmeMedicalAssociationPhysician",
"href": "https://acmemedicalassn.org/credentials/degree-123.json",
"mediaType": "application/vc+ld+json",
"hash": [
"QmQrGdv6Ky5sJhaVdw27y4aod5pdfihDkBTxiBkRaSGJJ7"
]
}
]
}
],
"published": "1970-01-01T00:00:00+00:00"
}
```

### Interaction

The `Interaction` attachment type enables simple discovery of pseudonymously issued credentials that may be relevant for a user to relate to a specific content item.

In contrast to `Attestation` attachments, Interactions reference a Verifiable Credential that does not address a specific DSNP User as its subject, but instead relies on a user-provided interaction identifier that can later be provably associated with a DSNP identity.
This allows for the issuance of Interaction credentials outside of an authenticated DSNP application context, and in scenarios where users wish to remain anonymous to the issuer.

An Interaction attachment resembles an Attestation, with the addition of an interaction nonce as described below (the `nonce` field), a Verifiable Credential Link in the `url` field, and an identifier of the object of the interaction in the `href` field.
The linked Verifiable Credential must have a credential subject that minimally includes an `interactionId` and repeats the `href` field, but may contain other data as defined by a [Verifiable Credential Schema](../../VerifiableCredentials/Types/VerifiableCredentialSchema.md)).

Proof that the credential was issued to the user responsible for posting the content is produced and verified using a cryptographic hash.
To acquire an anonymous Interaction credential, a DSNP User generates and records a random nonce of any length (192 bits or more is recommended).
The user then concatenates their DSNP User Id (in little-endian 64-bit format) with the nonce and generates a message digest using a [supported hashing algorithm](Hash.md#supported-algorithms).
The multibase-encoded hash output is then sent to the credential issuer to be included as an `interactionId` key in the `credentialSubject` field of the generated document.
It is intentionally opaque to the issuer.
The issuer may include any other fields relevant to the document schema in the `credentialSubject`, and then generate a signature proof.
The URL of the signed credential is then included in the interaction attachment (see example).

When posting content including the Interaction attachment, the user must include the nonce (as the `nonce` key) in order for consuming applications to verify that the originator of the content is responsible for generating the interaction.
A verifier MUST inspect the DSNP User Id of the sender of the content (via the relevant announcement) and the nonce, and repeat the hashing process to verify that it matches the value from `interactionId`.

Issuers of interaction credentials are encouraged to use the `display` extension described in the DSNP [Verifiable Credential Schema](../../VerifiableCredentials/Types/VerifiableCredentialSchema.md#display-extension) documentation to provide applications with hints as to how a verified interaction may be displayed, for example as a badge on a profile or content post.

| Property | Base Spec | Required | Description | Restrictions |
| --- | --- | --- | --- | --- |
| `type` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-type) | YES | Identifies the tag as type `Interaction` | MUST be `Interaction` |
| `url` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-url) | YES | An array of links for the given credential | MUST be a [Verifiable Credential Link](#verifiable-credential-link) |
| `name` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-name) | no | The display name for the interaction | |
| `reference` | [Activity Vocabulary 2.0](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-id) | YES | URI of object of the interaction | MUST be the same as the corresponding field within the linked document's `credentialSubject` |
| `nonce` | DSNP extension | YES | Multibase-encoded random byte string (a minimum deserialized size of 24 bytes is recommended) | |

#### Provenance of Interaction Credentials (Non-Normative)

Part of the provenance of a credential relies upon having a DSNP User Id and nonce that are hashed by the requester of the credential.
Ideally, the requester could prove that they were the user indicated by the DSNP User Id.
Similar assertions are often done by providing signatures: the user could sign a message including their User Id with the private key associated with a public key they manage as user data, in much the same way that the issuer of a Verifiable Credential creates a signature proof.

However, because DSNP does not prevent multiple users from associating the same public key with their accounts, it would be possible, for example, for Alice to obtain a credential in Bob's name and give it to Bob to post, as long as Bob represents that the corresponding public key is his own by listing it as one of his DSNP public keys.
Therefore, the provenance guarantee offered by the hashing approach on an otherwise anonymous credential is ultimately equivalent.
Because of this, applications should _not_ infer that the credential requester and sender are necessarily the same entity, only that, if different, they have collaborated to obtain a credential associated with the sender.

If it is important to be able to prove definitively that the credential requester is the same user as represented in the hash (for example, in a proof of personhood claim), the credential issuer should ask the user to authenticate by signing a challenge with their control key, and include the user's unhashed DSNP DID as the `credentialSubject`.

#### Example

```json
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Note",
"content": "This rug really ties the room together.",
"mediaType": "text/plain",
"attachments": [
{
"type": "Interaction",
"reference": "https://thebiglebowski.fandom.com/wiki/The_Rug",
"nonce": "zYAjKoNbau5KiqmHPmSxYCvn66dA1vLmwbt",
"url": [
{
"type": "Link",
"rel": "did:dsnp:898998$ProofOfPurchase",
"href": "https://therugstore.com/proof/txn-2929123.json",
"mediaType": "application/vc+ld+json",
"mediaType": "application/vc",
"hash": [
"QmQrGdv6Ky5sJhaVdw27y4aod5pdfihDkBTxiBkRaSGJJ7"
"bciqdnu347gcfmxzbkhgoubiobphm6readngitfywktdtbdocgogop2q"
]
}
]
Expand All @@ -340,13 +262,3 @@ If it is important to be able to prove definitively that the credential requeste
"published": "1970-01-01T00:00:00+00:00"
}
```

The referenced credential document would include within its `credentialSubject` a matching `reference` value, as well as an `interactionId` generated by hashing the sender's 64-bit little-endian DSNP User Id and the (deserialized) `nonce`:

```
"credentialSubject": {
"interactionId": "...",
"reference": "https://thebiglebowski.fandom.com/wiki/The_Rug",
"transactionId": "ABC123"
}
```
Loading

0 comments on commit 5faa5c2

Please sign in to comment.