Enforce system-only SMART operation access

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 13c9cccc-8ec4-4b60-8da0-f36ee9ab8be5

Author: mikaelweave

docs/arch/adr-2607-async-operation-smart-scope-authorization.md

@@ -0,0 +1,34 @@
+# ADR-2607: SMART System Export Authorization
+
+**Status**: Proposed
+**Date**: 2026-07-14
+**Feature**: SMART export authorization
+
+## Context
+
+FHIR Bulk Data export is asynchronous: the initiating request creates a job, while separate operation URLs expose status, result metadata, and cancellation. Existing route-level authorization checks the export action but does not authorize those operation URLs against the resource set represented by the persisted job. Predictable job identifiers can therefore expose or mutate an export job unless authorization is repeated after loading its metadata.
+
+The [FHIR Bulk Data Access IG](https://hl7.org/fhir/uv/bulkdata/export.html) defines export as a backend-services operation using SMART system scopes. Patient and user SMART scopes describe interactive clinical access and cannot safely authorize an asynchronous bulk extraction. Existing RBAC export permission and non-SMART behavior must remain unchanged.
+
+## Options Considered
+
+1. **Rely on route-level export authorization** - Authorize only the export action on each route. *(rejected: status and cancellation would not be checked against persisted job resource types)*
+2. **Persist patient or user creator context** - Bind jobs to a SMART compartment and revalidate that identity on later requests. *(rejected: adds authorization identity to job metadata and treats Bulk Data export as interactive clinical access)*
+3. **Require SMART system scopes and authorize persisted resource types** - Limit SMART export to backend system scopes and revalidate each job's resource set. *(chosen)*
+
+## Decision
+
+Requests subject to SMART fine-grained access control may create, read, or cancel export jobs only through system scopes. Patient and user contexts are rejected. RBAC `Export` permission remains an independent prerequisite. A system wildcard export-read scope may create an export without `_type`; otherwise creation requires a nonempty explicit `_type`, and every requested type must be covered by an unconstrained system scope.
+
+SMART v1 coverage requires read plus export. SMART v2 coverage requires read-by-id, search, and export, equivalent to `rs` plus export. Search-parameter-constrained scopes do not authorize export. Status and cancellation derive requirements from persisted `_type` and defensively include completed output types. A job without explicit `_type` always requires wildcard access, even when current output contains only a subset. Unauthorized job access is returned as not found to avoid an existence oracle.
+
+## Consequences
+
+- SMART patient and user applications cannot use Bulk Data export.
+- Partial system access can export an explicit authorized type set without receiving wildcard access.
+- Legacy and new jobs without explicit `_type` remain visible only to wildcard system callers.
+- Export job records do not persist SMART authorization identity or compartment metadata.
+- Unauthorized job access is indistinguishable from an unknown job identifier.
+- Completed output types can tighten later authorization but cannot weaken the no-`_type` wildcard rule.
+- RBAC and non-SMART export behavior are unchanged.
+- Other asynchronous operation types are outside this decision and retain their existing behavior.

src/Microsoft.Health.Fhir.Core.UnitTests/Features/Operations/Export/CancelExportRequestHandlerTests.cs

@@ -17,6 +17,7 @@
 using Microsoft.Health.Fhir.Core.Features.Operations;
 using Microsoft.Health.Fhir.Core.Features.Operations.Export;
 using Microsoft.Health.Fhir.Core.Features.Operations.Export.Models;
+using Microsoft.Health.Fhir.Core.Features.Operations.Security;
 using Microsoft.Health.Fhir.Core.Features.Persistence;
 using Microsoft.Health.Fhir.Core.Features.Security;
 using Microsoft.Health.Fhir.Core.Features.Security.Authorization;
@@ -35,6 +36,7 @@ public class CancelExportRequestHandlerTests
         private const string JobId = "jobId";
 
         private readonly IFhirOperationDataStore _fhirOperationDataStore = Substitute.For<IFhirOperationDataStore>();
+        private readonly IExportSmartScopeValidator _exportSmartScopeValidator = Substitute.For<IExportSmartScopeValidator>();
         private readonly IMediator _mediator;
 
         private readonly CancellationToken _cancellationToken = new CancellationTokenSource().Token;
@@ -49,6 +51,7 @@ public CancelExportRequestHandlerTests()
                 .Add(sp => new CancelExportRequestHandler(
                     _fhirOperationDataStore,
                     DisabledFhirAuthorizationService.Instance,
+                    _exportSmartScopeValidator,
                     _retryCount,
                     _sleepDurationProvider,
                     NullLogger<CancelExportRequestHandler>.Instance))
@@ -74,6 +77,7 @@ public async Task GivenAFhirMediator_WhenUserIsNotAuthorized_ThenUnauthorizedFhi
             var handler = new CancelExportRequestHandler(
                 _fhirOperationDataStore,
                 authorizationService,
+                _exportSmartScopeValidator,
                 _retryCount,
                 _sleepDurationProvider,
                 NullLogger<CancelExportRequestHandler>.Instance);
@@ -304,6 +308,33 @@ public async Task GivenAFhirMediator_WhenRetryEncountersJobNotFoundOnRefetch_The
             await _fhirOperationDataStore.Received(1).UpdateExportJobAsync(Arg.Any<ExportJobRecord>(), weakETag, Arg.Any<bool>(), Arg.Any<CancellationToken>());
         }
 
+        /// <summary>
+        /// Verifies that cancelling an export invokes the SMART export job validator
+        /// and that a denial from the validator propagates without mutating the job.
+        /// </summary>
+        [Fact]
+        public async Task GivenAFhirMediator_WhenCancelingExportJob_ThenSmartExportJobValidatorIsInvoked()
+        {
+            SetupExportJob(OperationStatus.Running);
+
+            await _mediator.CancelExportAsync(JobId, _cancellationToken);
+
+            _exportSmartScopeValidator.Received(1).ValidateJobAccess(Arg.Any<ExportJobRecord>());
+        }
+
+        [Fact]
+        public async Task GivenAFhirMediator_WhenSmartScopeValidatorDeniesCancelAccess_ThenJobNotFoundExceptionShouldBeThrownAndJobNotUpdated()
+        {
+            SetupExportJob(OperationStatus.Running);
+            _exportSmartScopeValidator
+                .When(x => x.ValidateJobAccess(Arg.Any<ExportJobRecord>()))
+                .Do(_ => throw new UnauthorizedFhirActionException());
+
+            await Assert.ThrowsAsync<JobNotFoundException>(() => _mediator.CancelExportAsync(JobId, _cancellationToken));
+
+            await _fhirOperationDataStore.DidNotReceive().UpdateExportJobAsync(Arg.Any<ExportJobRecord>(), Arg.Any<WeakETag>(), Arg.Any<bool>(), Arg.Any<CancellationToken>());
+        }
+
         private ExportJobOutcome SetupExportJob(OperationStatus operationStatus, WeakETag weakETag = null)
         {
             var outcome = CreateExportJobOutcome(

src/Microsoft.Health.Fhir.Core.UnitTests/Features/Operations/Export/GetExportRequestHandlerTests.cs

@@ -17,6 +17,7 @@
 using Microsoft.Health.Fhir.Core.Features.Operations;
 using Microsoft.Health.Fhir.Core.Features.Operations.Export;
 using Microsoft.Health.Fhir.Core.Features.Operations.Export.Models;
+using Microsoft.Health.Fhir.Core.Features.Operations.Security;
 using Microsoft.Health.Fhir.Core.Features.Persistence;
 using Microsoft.Health.Fhir.Core.Features.Security;
 using Microsoft.Health.Fhir.Core.Features.Security.Authorization;
@@ -36,6 +37,7 @@ public class GetExportRequestHandlerTests
         private const string JobId = "jobId";
 
         private readonly IFhirOperationDataStore _fhirOperationDataStore = Substitute.For<IFhirOperationDataStore>();
+        private readonly IExportSmartScopeValidator _exportSmartScopeValidator = Substitute.For<IExportSmartScopeValidator>();
         private readonly IMediator _mediator;
 
         private readonly CancellationToken _cancellationToken = new CancellationTokenSource().Token;
@@ -48,7 +50,8 @@ public GetExportRequestHandlerTests()
             collection
                 .Add(sp => new GetExportRequestHandler(
                     _fhirOperationDataStore,
-                    DisabledFhirAuthorizationService.Instance))
+                    DisabledFhirAuthorizationService.Instance,
+                    _exportSmartScopeValidator))
                 .Singleton()
                 .AsSelf()
                 .AsImplementedInterfaces();
@@ -70,7 +73,8 @@ public async Task GivenAFhirMediator_WhenUserIsNotAuthorized_ThenUnauthorizedFhi
 
             var handler = new GetExportRequestHandler(
                 _fhirOperationDataStore,
-                authorizationService);
+                authorizationService,
+                _exportSmartScopeValidator);
 
             await Assert.ThrowsAsync<UnauthorizedFhirActionException>(() =>
                 handler.Handle(new GetExportRequest(new Uri("http://localhost"), JobId), _cancellationToken));
@@ -349,6 +353,38 @@ public async Task GivenAFhirMediator_WhenGettingCanceledJobWithPartialResults_Th
             Assert.Single(response.JobResult.Error);
         }
 
+        /// <summary>
+        /// Verifies that the SMART export scope validator is invoked with the fetched job record
+        /// and that a denial from the validator propagates to the caller.
+        /// </summary>
+        [Fact]
+        public async Task GivenAFhirMediator_WhenGettingCompletedExportJob_ThenSmartScopeValidatorIsInvoked()
+        {
+            var jobRecord = CreateExportJobRecord(OperationStatus.Completed);
+            var outcome = CreateExportJobOutcome(jobRecord);
+
+            _fhirOperationDataStore.GetExportJobByIdAsync(JobId, _cancellationToken).Returns(outcome);
+
+            await _mediator.Send(new GetExportRequest(new Uri("http://localhost"), JobId), _cancellationToken);
+
+            _exportSmartScopeValidator.Received(1).ValidateJobAccess(jobRecord);
+        }
+
+        [Fact]
+        public async Task GivenAFhirMediator_WhenSmartScopeValidatorDeniesExportAccess_ThenJobNotFoundExceptionShouldBeThrown()
+        {
+            var jobRecord = CreateExportJobRecord(OperationStatus.Completed);
+            var outcome = CreateExportJobOutcome(jobRecord);
+
+            _fhirOperationDataStore.GetExportJobByIdAsync(JobId, _cancellationToken).Returns(outcome);
+            _exportSmartScopeValidator
+                .When(x => x.ValidateJobAccess(Arg.Any<ExportJobRecord>()))
+                .Do(_ => throw new UnauthorizedFhirActionException());
+
+            await Assert.ThrowsAsync<JobNotFoundException>(() =>
+                _mediator.Send(new GetExportRequest(new Uri("http://localhost"), JobId), _cancellationToken));
+        }
+
         private ExportJobRecord CreateExportJobRecord(OperationStatus operationStatus)
         {
             return new ExportJobRecord(