# Authorization Needs and Grants

## Patient Health Application

### TODO

- Application Profile
- Access Need Groups
- Associated Access Needs

- Application SKOS
- Index
- Version

- Access Grant(s)

### Patient Health Application Profile

The XFH Patient Health Application will have the following Application Profile, which will be used by an authorization agent (in our case embedded into the same) to identify the kinds of access it needs to function.

**https://xformativ.pub/xfh-patient/id#agent**

@prefix eco: <http://www.w3.org/ns/solid/ecosystem#> .
@prefix acl: <http://www.w3.org/ns/auth/acl#> .
@prefix st: <http://www.w3.org/ns/shapetree#> .
@prefix med: <http://shapetrees.pub/ts/medical-record/shapetree#> .
@prefix xfhp: <http://xformativ.pub/xfh-patient/ts/shapetree#> .

<#agent>
    a eco:Application ;
    eco:applicationName "XFORM Health PHR"
    eco:applicationDescription "Web based application that patients can use to manage data in their health record, stored in a Solid pod." ;
    eco:applicationAuthor <https://xformativ.pub/org/id#agent> ;
    eco:authorizationCallback <https://xformativ.pub/xfh-patient/authz-callback> ;
    eco:hasAccessNeedGroup <#medrecord-group> .

<#medrecord-group> 
    a eco:AccessNeedGroup ;
    eco:hasAccessNeed <#medicalRecord>, <#dashboard> ;
    eco:hasAccessNeedOverride <#condition> , 
                              <#encounter> , 
                              <#prescription> ,
                              <#allergy> ,
                              <#observation> ,
                              <#diagnosticReport> ,
                              <#practitioner> ;                        
    eco:authenticatesAs eco:Pilot ;
    eco:hasAccessNeedDecoratorIndex <xfh-patient-decorator-index.ttl> .
    
<#medicalRecord>
    a eco:AccessNeed ;
    eco:inAccessNeedGroup <#medrecord-group> ;
    eco:registeredShapeTree <med:medicalRecord> ;
    eco:recursivelyAuthorize true;
    eco:accessMode acl:Read, acl:Write, acl:Control;
    eco:accessNecessity eco:AccessRequired .

# Patient, Appointment, activity, document, have same perms and necessities
# Overrides are for read + control

<#condition>
    a eco:AccessNeed ;
    eco:inAccessNeedGroup <#medrecord-group> ;
    eco:registeredShapeTree <med:condition> ;
    eco:recursivelyAuthorize true;
    eco:accessMode acl:Read, acl:Control;
    eco:accessNecessity eco:AccessRequired .

<#encounter>
    a eco:AccessNeed ;
    eco:inAccessNeedGroup <#medrecord-group> ;
    eco:registeredShapeTree <med:encounter> ;
    eco:recursivelyAuthorize true;
    eco:accessMode acl:Read, acl:Control;
    eco:accessNecessity eco:AccessRequired .

<#prescription>
    a eco:AccessNeed ;
    eco:inAccessNeedGroup <#medrecord-group> ;
    eco:registeredShapeTree <med:prescription> ;
    eco:recursivelyAuthorize true;
    eco:accessMode acl:Read, acl:Control;
    eco:accessNecessity eco:AccessRequired .

<#allergy>
    a eco:AccessNeed ;
    eco:inAccessNeedGroup <#medrecord-group> ;
    eco:registeredShapeTree <med:allergy> ;
    eco:recursivelyAuthorize true;
    eco:accessMode acl:Read, acl:Control;
    eco:accessNecessity eco:AccessRequired .

<#observation>
    a eco:AccessNeed ;
    eco:inAccessNeedGroup <#medrecord-group> ;
    eco:registeredShapeTree <med:observation> ;
    eco:recursivelyAuthorize true;
    eco:accessMode acl:Read, acl:Control;
    eco:accessNecessity eco:AccessRequired .

<#diagnosticReport>
    a eco:AccessNeed ;
    eco:inAccessNeedGroup <#medrecord-group> ;
    eco:registeredShapeTree <med:diagnosticReport> ;
    eco:recursivelyAuthorize true;
    eco:accessMode acl:Read, acl:Control;
    eco:accessNecessity eco:AccessRequired .

<#practitioner>
    a eco:AccessNeed ;
    eco:inAccessNeedGroup <#medrecord-group> ;
    eco:registeredShapeTree <med:practitioner> ;
    eco:recursivelyAuthorize true;
    eco:accessMode acl:Read, acl:Control;
    eco:accessNecessity eco:AccessRequired .

<#dashboard>
    a eco:AccessNeed ;
    eco:inAccessNeedGroup <#medrecord-group> ;
    eco:registeredShapeTree <xfhp:dashboard> ;
    eco:recursivelyAuthorize true;
    eco:accessMode acl:Read, acl:Control ;
    eco:accessNecessity eco:AccessRequired .

### Prepared Access Needs ###

@prefix eco: <http://www.w3.org/ns/solid/ecosystem#> .
@prefix acl: <http://www.w3.org/ns/auth/acl#> .
@prefix st: <http://www.w3.org/ns/shapetree#> .
@prefix med: <http://shapetrees.pub/ts/medical-record/shapetree#> .
@prefix medd: <http://shapetrees.pub/ts/medical-record/decorator#> .
@prefix xfhp: <http://xformativ.pub/xfh-patient/ts/shapetree#> .
@prefix xfhpd: <http://xformativ.pub/xfh-patient/ts/decorator#> .

<#pag-medrecordgroup> 
    a eco:PreparedAccessNeedGroup ;
    eco:hasAccessNeedGroupDecorator xfhpd:medrecord-group ;
    eco:accessNecessity eco:AccessRequired ;
    eco:authenticatesAs eco:Pilot ;
    eco:hasPreparedAccessNeed <#pan-medicalrecord>, <#pan-dashboard> .
        
<#pan-medicalrecord>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:medicalRecord ;
    eco:accessMode acl:Read, acl:Write, acl:Control ;
    eco:accessNecessity eco:AccessRequired ;
    eco:hasAccessNeedDecorator xfhpd:medicalRecord ;
    eco:hasShapeTreeDecorator medd:medicalRecord ;
    eco:referencesPreparedAccessNeed <#pan-patient> , 
                                     <#pan-appointment> , 
                                     <#pan-condition> , 
                                     <#pan-encounter> , 
                                     <#pan-prescription> , 
                                     <#pan-allergy> , 
                                     <#pan-observation> , 
                                     <#pan-diagnosticReport> , 
                                     <#pan-activity> , 
                                     <#pan-practitioner> , 
                                     <#pan-document> . 
    
<#pan-patient>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:patient ;
    st:shapeTreeDecorator medd:patient ;
    eco:accessNeedDecorator xfhpd:patient ;
    eco:supportedBy <#pan-patient-active-index> ;
    eco:accessMode acl:Read, acl:Write, acl:Control;
    eco:accessNecessity eco:AccessRequired . 

<#pan-appointment>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:appointment ;
    eco:hasShapeTreeDecorator medd:appointment ;
    eco:hasAccessNeedDecorator xfhpd:appointment ;
    eco:supportedBy <#pan-patient-timeline-appointment> ;
    eco:accessMode acl:Read, acl:Write, acl:Control;
    eco:accessNecessity eco:AccessRequired .

<#pan-condition>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:condition ;
    eco:hasShapeTreeDecorator medd:condition ;
    eco:hasAccessNeedDecorator xfhpd:condition ;
    eco:supportedBy <#pan-condition-active-index> ;
    eco:accessMode acl:Read, acl:Write, acl:Control ;
    eco:accessNecessity eco:AccessRequired .  

<#pan-encounter>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:encounter ;
    eco:hasShapeTreeDecorator medd:encounter ;
    eco:hasAccessNeedDecorator xfhpd:encounter ;
    eco:accessMode acl:Read, acl:Write, acl:Control ;
    eco:accessNecessity eco:AccessRequired . 

<#pan-prescription>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:prescription ;
    eco:hasShapeTreeDecorator medd:prescription ;
    eco:hasAccessNeedDecorator xfhpd:prescription ;
    eco:supportedBy <#pan-patient-timeline-prescription>,
                    <#pan-prescription-active-index> ;
    eco:accessMode acl:Read, acl:Write, acl:Control ;
    eco:accessNecessity eco:AccessRequired . 

<#pan-allergy>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:allergy ;
    eco:hasShapeTreeDecorator medd:allergy ;
    eco:hasAccessNeedDecorator xfhpd:allergy ;
    eco:supportedBy <#pan-allergy-active-index> ;
    eco:accessMode acl:Read, acl:Write, acl:Control ;
    eco:accessNecessity eco:AccessRequired . 

<#pan-observation>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:observation ;
    eco:hasShapeTreeDecorator medd:observation ;
    eco:hasAccessNeedDecorator xfhpd:observation ;
    eco:supportedBy <#pan-patient-timeline-observation> ;
    eco:accessMode acl:Read, acl:Write, acl:Control ;
    eco:accessNecessity eco:AccessRequired .
    
<#pan-diagnosticReport>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:diagnosticReport ;
    eco:hasShapeTreeDecorator medd:diagnosticReport ;
    eco:hasAccessNeedDecorator xfhpd:diagnosticReport ;
    eco:supportedBy <#pan-patient-timeline-diagnostic-report> ;
    eco:accessMode acl:Read, acl:Write, acl:Control;
    eco:accessNecessity eco:AccessRequired .
    
<#pan-activity>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:activity ;
    eco:hasShapeTreeDecorator medd:activity ;
    eco:hasAccessNeedDecorator xfhpd:activity ;
    eco:accessMode acl:Read, acl:Write, acl:Control;
    eco:accessNecessity eco:AccessRequired .
    
<#pan-practitioner>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:practitioner ;
    eco:hasShapeTreeDecorator medd:practitioner ;
    eco:hasAccessNeedDecorator xfhpd:practitioner ;
    eco:accessMode acl:Read, acl:Write, acl:Control;
    eco:accessNecessity eco:AccessRequired .
    
<#pan-document>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree med:document ;
    eco:hasShapeTreeDecorator medd:document ;
    eco:hasAccessNeedDecorator xfhpd:document ;
    eco:accessMode acl:Read, acl:Write, acl:Control;
    eco:accessNecessity eco:AccessRequired .
    

###########################################################
# Dashboard Needs
###########################################################

# Note that <#pan-dashboard> is not a supporting need, so 
# it will show up to the user when authorizing
<#pan-dashboard>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree xfhp:dashboard ;
    eco:hasShapeTreeDecorator xfhpd:decorateDashboard ;
    eco:hasAccessNeedDecorator xfhpd:decorateDashboardNeed ;
    eco:accessMode acl:Read, acl:Control;
    eco:accessNecessity eco:AccessRequired ; 
    eco:referencesPreparedAccessNeed <#pan-patient-timeline-appointment> ,
                                     <#pan-patient-timeline-diagnostic-report> ,
                                     <#pan-patient-timeline-prescription> ,
                                     <#pan-patient-timeline-observation> ,
                                     <#pan-patient-active-index> ,
                                     <#pan-condition-active-index> ,
                                     <#pan-prescription-active-index> ,
                                     <#pan-allergy-active-index> .

<#pan-patient-timeline-appointment>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree xfhp:patient-timeline-appointment ;
    eco:hasShapeTreeDecorator xfhpd:decorate-patient-timeline-appointment ;
    eco:hasAccessNeedDecorator xfhpd:decorate-patient-timeline-appointment-need ;
    eco:supports <#pan-appointment> ;
    eco:accessMode acl:Read, acl:Control ;
    eco:accessNecessity eco:AccessRequired .
    
<#pan-patient-timeline-diagnostic-report> 
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree xfhp:patient-timeline-diagnostic-report ;
    eco:hasShapeTreeDecorator xfhpd:decorate-patient-timeline-diagnostic-report ;
    eco:supports <#pan-diagnosticReport> ;
    eco:accessMode acl:Read, acl:Control ;
    eco:accessNecessity eco:AccessRequired .

<#pan-patient-timeline-prescription> 
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree xfhp:patient-timeline-prescription ;
    eco:hasShapeTreeDecorator xfhpd:decorate-patient-timeline-prescription ;
    eco:hasAccessNeedDecorator xfhpd:decorate-patient-timeline-prescription-need ;
    eco:supports <#pan-prescription> ;
    eco:accessMode acl:Read, acl:Control ;
    eco:accessNecessity eco:AccessRequired .

<#pan-patient-timeline-observation> 
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree xfhp:patient-timeline-observation ;
    eco:hasShapeTreeDecorator xfhpd:decorate-patient-timeline-observation ;
    eco:supports <#pan-observation> ;
    eco:accessMode acl:Read, acl:Control ;
    eco:accessNecessity eco:AccessRequired .

<#pan-patient-active-index> 
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree xfhp:patient-active-index ;
    eco:hasShapeTreeDecorator xfhpd:decorate-patient-active-index ;
    eco:supports <#pan-patient> ;
    eco:accessMode acl:Read, acl:Control ;
    eco:accessNecessity eco:AccessRequired .

<#pan-condition-active-index> 
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree xfhp:condition-active-index ;
    eco:hasShapeTreeDecorator xfhpd:decorate-condition-active-index ;
    eco:supports <#pan-condition> ;
    eco:accessMode acl:Read, acl:Control ;
    eco:accessNecessity eco:AccessRequired .

<#pan-prescription-active-index> 
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree xfhp:prescription-active-index ;
    eco:hasShapeTreeDecorator xfhpd:decorate-prescription-active-index ;
    eco:supports <#pan-prescription> ;
    eco:accessMode acl:Read, acl:Control ;
    eco:accessNecessity eco:AccessRequired .

<#pan-allergy-active-index>
    a eco:PreparedAccessNeed ;
    eco:registeredShapeTree xfhp:allergy-active-index ;
    eco:hasShapeTreeDecorator xfhpd:decorate-allergy-active-index ;
    eco:hasAccessNeedDecorator xfhpd:decorate-allergy-active-index-need ;
    eco:supports <#pan-allergy> ;
    eco:accessMode acl:Read, acl:Control ;
    eco:accessNecessity eco:AccessRequired .

### Access Grant ###

- Takes a prepared access group and needs, and ties them to specific data registrations and instances
- There are three types of instance selection
- All instances of a type now and forever
- Focused instance selection (i.e. medical-record-1)
- Inherited / recursive instance selection (i.e. prescription1,2,3+future that are linked to medical-record-1)
- Each access grant must be scoped to a specific subject that is requesting access. This could be a single agent, or a group.
- Each access grant must be able to pick up where it leaves off for a given subject. Specifically, when an access grant is made for Bob by Alice to some set of prepared needs, Bob should be able to bring up access for Alice at any time, and see those accurately reflected.
- If a given subject has requested access through various avenues (e.g. Alice and Bob collaborate together on a lot of different things), we must consolidate these together so that Alice sees one rational superset of what she has granted Bob access to)
- Going to need to determine how we want to deal with cases where there is an existing grant and a new set of needs, especially when there are overlaps...
- When evaluating a new request - It might be that we just call out the overlaps during presentation but otherwise act normally...
- You only arrive here either because a subject is asking for access, you want to review the access a subject has, or you want to remove some amount of access.
- Keep in mind that removal must take into account the original necessities, otherwise you end up with broken functionality. So, whether the UI renders it that way or not, removal of optional stuff is fine, but required stuff would require removing the entire capability from the group.
- An operation is needed that can take the overarching grant for a given subject, and apply it by iterating over associated data registrations / instances, and setting the permissions appropriately. This also means that we canot add redundant authorization statements, or break existing authorization statements.

Access Grant Structure:

- Prepared Access Need Groups
- Prepared Access Needs
- Associated Data Registrations
- Must be tied to one or more access needs / groups
- Type of association
- All registered instances always
- Focused instance selection(s)
- Inherited instance selection(s)
- Associated Registered Data Instances (when applicable)

@prefix eco: <http://www.w3.org/ns/solid/ecosystem#> .
@prefix acl: <http://www.w3.org/ns/auth/acl#> .
@prefix st: <http://www.w3.org/ns/shapetree#> .
@prefix med: <http://shapetrees.pub/ts/medical-record/shapetree#> .
@prefix medd: <http://shapetrees.pub/ts/medical-record/decorator#> .
@prefix xfhp: <http://xformativ.pub/xfh-patient/ts/shapetree#> .
@prefix xfhpd: <http://xformativ.pub/xfh-patient/ts/decorator#> .
@prefix data: <https://alice.example/data/ .


<#grant>
    a eco:AccessGrant
    eco:AccessGrantSubject https://bob.example/profile/id#me ;  # individual agent or group
    eco:hasPreparedAccessNeedGroup <#pan-medrecord-group> ;
    eco:hasDataRegistrationGrant <#medical-record-grant> .

# Data registration grants are 1:1 with data registrations
# Types of accessScope: eco:SelectInstances, eco:EveryInstance, eco:InheritInstances

<#medical-record-grant>
    a eco:DataRegistrationGrant ;
    eco:hasRegistration data:medical-record ;
    eco:registeredShapeTree med:medicalRecord ;
    eco:satisfiesPreparedAccessNeed <#pan-medicalrecord> ;
    eco:accessScope eco:SelectInstances ;  
    eco:hasRegisteredDataInstances data:medical-record/medical-record-1 .
    
<#patient-grant>
    a eco:DataRegistrationGrant ;
    eco:hasRegistration data:patient ;
    eco:registeredShapeTree med:patient ;
    eco:satisfiesPreparedAccessNeed <#pan-patient> ;
    eco:accessScope eco:InheritInstances ;  
    eco:inheritsFrom <#medical-record-grant> .

<#appointment-grant>
    a eco:DataRegistrationGrant ;
    eco:hasRegistration data:appointment ;
    eco:registeredShapeTree med:appointment ;
    eco:satisfiesPreparedAccessNeed <#pan-appointment> ;
    eco:accessScope eco:InheritInstances, eco:SelectInstances ;  
    eco:inheritsFrom <#medical-record-grant> ;
    eco:hasRegisteredDataInstances data:appointment/appointment-2 ,
                                   data:appointment/appointment-4 .

Note: We'll need to create some specific AccessNeedGroup and AccessNeed types for general data sharing between individuals, but will not allow that to be used from Applications.

Access Change Event: (this is probably lower priority for today)

- Enumerate the actual access changes to data in the registry
- Use the output from the permission algorithm to detail what's being applied, and ideally what the delta was.

## Person to person sharing (Patient to Carer)

- Agent Public Profile

- Access Need Request
- Access Need Groups
- Access Needs

- Prepared Access Group
- Prepared Access Needs

- Access Grant(s)

SESSION WITH JOSH AND ERIC:

- Conventions Needed
- Where does Agent ID for xformativ go
- Fix access need decorator index
- Fix carats on shape trees in medical record
- Add some typing for access need groups so that we can represent some default
person to person data sharing scenarios
- Change skos:narrower to a references property instead
- Add a bi-directional link from preparedAccessNeed to DataRegistrationGrant
- Do we need to point the ACL back to the authorization grant
- What is the default type of access need group for person to person? Best way to define / invoke?