# Email Ownership Governance Framework

This Governance Framework is community managed.

When making connections from one person to another over DIDComm, it is useful to be able to gain proof of something to verify that the connection is with the right person and has not been subject to a MITM attack. We expect this Governance Framework to be one of many used for the purpose of helping to verify identity attributes in the creation of trusted channels.

This is an early attempt at the creation and use of of a practical governance framework. As Governance Framework technology improves, we expect this particular framework to be replaced.

## Purpose
To facilitate the verification of email ownership between two parties over DIDComm and related technologies.

## Details

### Issue Requirements
Issuers must validate email ownership by sending an email to the email address in question. The email MUST contain a link for the user to click, or a code to be entered in a verification step. After verifying that the clicked link or entered code matches, the credential may be issued.

Issued credentials should indicate an expiration date no longer than 6 months from the date of verification.

### Schemas

### Valid Issuers
BGov: `<did>`

### Revocation
This framework does not currently use revocation, relying upon the expiration date to prevent widespread issues.

### Allowable Verification Purposes
Email addresses revealed in this manner may be used for the following purposes:
- Displaying to recipient.
- Checking against address book.

## Machine Readable Document
_This document will be hosted at a stable URI, and will be updated as requried._

{
    "@context": ["https://github.com/hyperledger/aries-rfcs/blob/master/0430-machine-readable-governance-frameworks/context.jsonld"],
    "name": "Email Ownership"
    "version": "0.1",
    "description": "Proof of email ownership."
    "last_updated": "",
    "docs_uri": "<uri to human portion of this example",
    "data_uri": "<uri to machine readable portion of this example>",
    "schemas": [],
    "issuers":["<bcgov did>"]
}

### EDIT FROM DANIEL
I said I didn't care about which syntax we use. That's true, but I DO care about the **expressiveness** of the syntax we design. So I'm making this counterproposal because I think the first cut above isn't expressive enough. If we want to say more things, we have to add additional fields in a way that doesn't follow any predefined pattern, and that may become cumbersome. What we have here isn't just a flat data structure; there are interrelationships among fields. Those interrelationships have to model complex business and legal logic as defined in the human side of gov frameworks. Just adding fields to a data structure won't be enough to extend this in the future, because we'll have to add logic about how the fields relate to one another. So while I don't care about which syntax we use, I want us to design (not necessarily implement!) that syntax out now, satisfying ourselves that it will be capable of saying (almost) everything we eventually expect to want. This will prevent us from imposing an upgrade burden on everybody when the syntax has to change (possibly several times).

What I originally proposed in Aries 0430 is an example of such a syntax. There could be other examples that satisfy the same criteria, and I'd be happy to explore them. But before we discard my proposal, I feel like maybe we overestimated its complexity. Here's what the same doc would look like if we wanted to use that syntax to tolerate a more flexible model where issuers isn't a hard-coded role. It only diverges on line 10, and is only 1 line longer. Is this a lot harder to explain?

{
    "@context": ["https://github.com/hyperledger/aries-rfcs/blob/master/0430-machine-readable-governance-frameworks/context.jsonld"],
    "name": "Email Ownership"
    "version": "0.1",
    "description": "Proof of email ownership."
    "last_updated": "",
    "docs_uri": "<uri to human portion of this example",
    "data_uri": "<uri to machine readable portion of this example>",
    "schemas": [],
    "roles": ["issuer"], 
    "rules": [ {"when": {"id": "did:example:abc123"}, "thus": "issuer"} ]
}    

Comments:

* Line 10: Roles will be defined in human docs. We have to be able to map what's said there to what's known in code. We don't want to hardcode "issuer" because some frameworks might need multiple types of issuers.
* Line 11: When we see a party controlling this DID, impute the "issuer" role to them.

I feel like this is ultra simple. It imposes almost no extra parsing burden. But it is compatible with a future evolution that is far more powerful and rich:

{
    "@context": ["https://github.com/hyperledger/aries-rfcs/blob/master/0430-machine-readable-governance-frameworks/context.jsonld"],
    "name": "Email Ownership"
    "version": "0.1",
    "description": "Proof of email ownership."
    "last_updated": "",
    "docs_uri": "<uri to human portion of this example",
    "data_uri": "<uri to machine readable portion of this example>",
    "schemas": [],
    "roles": ["issuer"], 
    "privileges": [{"name": "issue-email-proof", "uri": "https://foo.org/aries/gf/issue-email"} ],
    "duties": [ {"name": "GDPR-dat-control", "uri": "https://foo.org/gdpr/safeguard-pii"} ],
    "define": [ {"name": "BCGov": "id": "did:example:abc123"} ], 
    "rules": [ {"grant": ["issue-email-proof"], "when": {"name": "BCGov"},
        "duties": ["GDPR-dat-control"], "thus": "issuer"} ]
}    

This version has more indirections in it, but they follow a predictable pattern that the syntax already contemplated by avoiding hardcoding. More comments:

* Line 11: Like arbitrary roles, we can also define arbitrary privileges and what they mean.
* Line 12: And you can define arbitrary duties.
* Line 13: Declare that the name "BCGov" belongs to anyone controlling this particular DID. This lets an issuer use more than one DID, among other things. You can define as many things as you want.
* Line 14: Let anybody have the arbitrary 'issue-email-proof' privilege if they are named BCGov, as defined immediately above. Conferring this priv also confers an arbitrary GDPR duty, and gives that entity the arbitrary 'issuer' role.

This contains a handful of indirections, but it is still not drastically more verbose or harder to parse. It allows for things like granting issuance rights for certain types of credentials only, and only to entities that can prove their qualifications with other credentials. It supports hierarchical accreditation. It provides a pattern to express qualifications and duties for verifiers and holders, not just issuers.

Again, I would be happy to explore alternative syntaxes. What I'd want to see in them is equivalent expressiveness. No matter which syntax we choose, we don't have to implement all its complexity now; I just advocate that we allow for future expressiveness without changing the syntax design.

## Notes
- Right now this is a direct list of issuers. In the future, moving to a credential held by issuers is more scalable.
- This example doesn't quite align with [RFC 340](https://github.com/hyperledger/aries-rfcs/tree/master/concepts/0430-machine-readable-governance-frameworks). We should explore the differences and find the right alignment.

## Questions
- RFC 430 doesn't include a reference to schemas. How should this be done?
- Ownership is probably the wrong word for the title, as is control. What is the right word here?
- Multiple Schemas in the same framework?
- Are there subsets of Governance Frameworks that allow portions to be referenced, or only the framework as a whole?
- Code for the indy email verification service: https://github.com/bcgov/indy-email-verification