001package ca.uhn.fhir.rest.server.interceptor.consent; 002 003/*- 004 * #%L 005 * HAPI FHIR - Server Framework 006 * %% 007 * Copyright (C) 2014 - 2022 Smile CDR, Inc. 008 * %% 009 * Licensed under the Apache License, Version 2.0 (the "License"); 010 * you may not use this file except in compliance with the License. 011 * You may obtain a copy of the License at 012 * 013 * http://www.apache.org/licenses/LICENSE-2.0 014 * 015 * Unless required by applicable law or agreed to in writing, software 016 * distributed under the License is distributed on an "AS IS" BASIS, 017 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 018 * See the License for the specific language governing permissions and 019 * limitations under the License. 020 * #L% 021 */ 022 023import ca.uhn.fhir.rest.api.server.RequestDetails; 024import ca.uhn.fhir.rest.server.exceptions.BaseServerResponseException; 025import org.hl7.fhir.instance.model.api.IBaseResource; 026 027/** 028 * Note: Since HAPI FHIR 5.1.0, methods in this interface have default methods that return {@link ConsentOutcome#PROCEED} 029 */ 030public interface IConsentService { 031 032 /** 033 * This method is called when an operation is initially beginning, before any 034 * significant processing occurs. The service may use this method to decide 035 * whether the request needs to be reviewed further or not. 036 * 037 * @param theRequestDetails Contains details about the operation that is 038 * beginning, including details about the request type, 039 * URL, etc. Note that the RequestDetails has a generic 040 * Map (see {@link RequestDetails#getUserData()}) that 041 * can be used to store information and state to be 042 * passed between methods in the consent service. 043 * @param theContextServices An object passed in by the consent framework that 044 * provides utility functions relevant to acting on 045 * consent directives. 046 * @return An outcome object. See {@link ConsentOutcome} 047 */ 048 default ConsentOutcome startOperation(RequestDetails theRequestDetails, IConsentContextServices theContextServices) { 049 return ConsentOutcome.PROCEED; 050 } 051 052 /** 053 * This method is called if a user may potentially see a resource via READ 054 * operations, SEARCH operations, etc. This method may make decisions about 055 * whether or not the user should be permitted to see the resource. 056 * <p> 057 * Implementations should make no attempt to modify the returned result within 058 * this method. For modification use cases (e.g. masking for consent rules) the 059 * user should use the {@link #willSeeResource(RequestDetails, IBaseResource, IConsentContextServices)} 060 * method to actually make changes. This method is intended to only 061 * to make decisions. 062 * </p> 063 * <b>Performance note:</b> Note that this method should be efficient, since it will be called once 064 * for every resource potentially returned (e.g. by searches). If this method 065 * takes a significant amount of time to execute, performance on the server 066 * will suffer. 067 * </p> 068 * 069 * @param theRequestDetails Contains details about the operation that is 070 * beginning, including details about the request type, 071 * URL, etc. Note that the RequestDetails has a generic 072 * Map (see {@link RequestDetails#getUserData()}) that 073 * can be used to store information and state to be 074 * passed between methods in the consent service. 075 * @param theResource The resource that will be exposed 076 * @param theContextServices An object passed in by the consent framework that 077 * provides utility functions relevant to acting on 078 * consent directives. 079 * @return An outcome object. See {@link ConsentOutcome} 080 */ 081 default ConsentOutcome canSeeResource(RequestDetails theRequestDetails, IBaseResource theResource, IConsentContextServices theContextServices) { 082 return ConsentOutcome.PROCEED; 083 } 084 085 /** 086 * This method is called if a user is about to see a resource, either completely 087 * or partially. In other words, if the user is going to see any part of this resource 088 * via READ operations, SEARCH operations, etc., this method is 089 * called. This method may modify the resource in order to filter/mask aspects of 090 * the contents, or even to enrich it. 091 * <p> 092 * The returning {@link ConsentOutcome} may optionally replace the resource 093 * with a different resource (including an OperationOutcome) by calling the 094 * resource property on the {@link ConsentOutcome}. 095 * </p> 096 * <p> 097 * In addition, the {@link ConsentOutcome} must return one of the following 098 * statuses: 099 * </p> 100 * <ul> 101 * <li>{@link ConsentOperationStatusEnum#AUTHORIZED}: The resource will be returned to the client.</li> 102 * <li>{@link ConsentOperationStatusEnum#PROCEED}: The resource will be returned to the client. Any embedded resources contained within the resource will also be checked by {@link #willSeeResource(RequestDetails, IBaseResource, IConsentContextServices)}.</li> 103 * <li>{@link ConsentOperationStatusEnum#REJECT}: The resource will not be returned to the client. If the resource supplied to the </li> 104 * </ul> 105 * 106 * @param theRequestDetails Contains details about the operation that is 107 * beginning, including details about the request type, 108 * URL, etc. Note that the RequestDetails has a generic 109 * Map (see {@link RequestDetails#getUserData()}) that 110 * can be used to store information and state to be 111 * passed between methods in the consent service. 112 * @param theResource The resource that will be exposed 113 * @param theContextServices An object passed in by the consent framework that 114 * provides utility functions relevant to acting on 115 * consent directives. 116 * @return An outcome object. See method documentation for a description. 117 */ 118 default ConsentOutcome willSeeResource(RequestDetails theRequestDetails, IBaseResource theResource, IConsentContextServices theContextServices) { 119 return ConsentOutcome.PROCEED; 120 } 121 122 /** 123 * This method is called when an operation is complete. It can be used to perform 124 * any necessary cleanup, flush audit events, etc. 125 * <p> 126 * This method is not called if the request failed. {@link #completeOperationFailure(RequestDetails, BaseServerResponseException, IConsentContextServices)} 127 * will be called instead in that case. 128 * </p> 129 * 130 * @param theRequestDetails Contains details about the operation that is 131 * beginning, including details about the request type, 132 * URL, etc. Note that the RequestDetails has a generic 133 * Map (see {@link RequestDetails#getUserData()}) that 134 * can be used to store information and state to be 135 * passed between methods in the consent service. 136 * @param theContextServices An object passed in by the consent framework that 137 * provides utility functions relevant to acting on 138 * consent directives. 139 * @see #completeOperationFailure(RequestDetails, BaseServerResponseException, IConsentContextServices) 140 */ 141 default void completeOperationSuccess(RequestDetails theRequestDetails, IConsentContextServices theContextServices) { 142 } 143 144 /** 145 * This method is called when an operation is complete. It can be used to perform 146 * any necessary cleanup, flush audit events, etc. 147 * <p> 148 * This method will be called if the request did not complete successfully, instead of 149 * {@link #completeOperationSuccess(RequestDetails, IConsentContextServices)}. Typically this means that 150 * the operation failed and a failure is being returned to the client. 151 * </p> 152 * 153 * @param theRequestDetails Contains details about the operation that is 154 * beginning, including details about the request type, 155 * URL, etc. Note that the RequestDetails has a generic 156 * Map (see {@link RequestDetails#getUserData()}) that 157 * can be used to store information and state to be 158 * passed between methods in the consent service. 159 * @param theContextServices An object passed in by the consent framework that 160 * provides utility functions relevant to acting on 161 * consent directives. 162 * @see #completeOperationSuccess(RequestDetails, IConsentContextServices) 163 */ 164 default void completeOperationFailure(RequestDetails theRequestDetails, BaseServerResponseException theException, IConsentContextServices theContextServices) { 165 } 166}