SMART 2.2 granular scopes: parse, enforce, and test vectors

[cursor]

Summary

Implement SMART App Launch 2.2 granular scopes in pkg/smart and enforce them across FHIR data paths. Today HAIStack supports SMART 1.x-style scopes (patient/*.read, user/Patient.write) and documents 2.2 granular scopes as deferred in smart.SMARTVersion.

Background

SMART 2.0+ replaces coarse .read/.write suffixes with CRUDS letters (r, s, c, u, d). SMART 2.2 adds optional FHIR search-parameter filters on scopes:

patient/Observation.rs?category=laboratory

Servers must enforce filters on read, search, create, update, delete, and must not leak out-of-scope resources via _include, _revinclude, bundles, or $everything.

HAIStack already enforces patient compartment via TenantContext.PatientScope and ApplyPatientSearchScopeToParams — granular scopes are the next layer of search-parameter narrowing within that compartment.

Proposed scope

Phase 1 — Parsing and metadata

• Extend pkg/smart/scope.go to parse CRUDS suffixes (patient/Observation.rs, user/*.cruds)
• Parse optional ?param=value filter suffix (2.2)
• Map v1 scopes to v2 semantics per spec (.read → .rs, .write → .cud, .* → .cruds)
• Advertise permission-v2 and permission-v2.2 in smart.Configuration / reference host
• Document compatibility matrix in pkg/smart/README.md

Phase 2 — Enforcement

• ScopeSet matching per operation letter (read vs search vs write)
• Intersect scope filters with search params in pkg/search / HTTP search path
• Enforce filters on loaded resources (read/history) via envelope checks
• Filter _include / _revinclude / bundle results (extend filterSearchBundlePatientScope pattern)
• Policy may still narrow scopes (extend authztest scenarios)

Phase 3 — Tests

• Unit test vectors for 2.2 scope strings (valid/invalid)
• Integration scenarios in pkg/testkit/authztest for filter enforcement
• Inferno STU2.2 discovery/launch tests when reference OAuth matures

Acceptance criteria

• Parse and match CRUDS scopes and at least one 2.2 filter pattern
• Patient-scoped search with patient/Observation.rs?category=X cannot return out-of-filter resources
• Policy deny still overrides scope allow (existing authztest pattern)
• smart.SMARTVersion updated to reflect 2.2 support level
• README documents v1 → v2 migration and host responsibilities

Out of scope

• Full OAuth2/OIDC authorization server
• Dynamic client registration server
• EHR launch UI orchestration

Related

• API security: SMART 2.2 readiness and authorization semantics test suite #8 API security: authorization semantics test suite (Phase 1–4)
• Inferno CI discovery job (reference host)
• examples/smart-authz policy-narrowing demo

References

• SMART App Launch 2.2 — Scopes and Launch Context
• US Core granular scopes