gdc-common-utils-ts 2.3.13 → 2.3.14

package/README.md

@@ -44,6 +44,13 @@ It is intentionally not a full backend orchestration layer.
 
 - FHIR SearchParameter names must use canonical FHIR naming (lowercase, with `-` when defined by FHIR).
 - Never use invented camelCase parameter names for FHIR claims/search keys (example: `Communication.part-of` is valid, `Communication.partOf` is not).
+- FHIR claims use exactly `<ResourceType>.<concrete-parameter>` and never add
+  pseudo-path segments. For example, the section/topic claim is
+  `Communication.topic`; the native projection may contain
+  `Communication.topic.coding`, but `Communication.topic.coding` is not a
+  claims key.
+- Schema.org claims are a different vocabulary and preserve the canonical
+  Schema.org camelCase property name.
 - Only define custom names when no canonical FHIR SearchParameter exists.
 - `resource.meta.claims` is the canonical project-specific claims container and must be preserved across conversions/transports.
 - `resource.meta.claims` is not part of base FHIR; it is a claims-first extension carried by FHIR-like resources in GDC contracts.
@@ -52,6 +59,12 @@ It is intentionally not a full backend orchestration layer.
   boundary before indexed storage. Existing `resource.meta.claims` take
   precedence so SDK-authored semantics survive transport conversion.
 
+For a `Communication` whose attached Bundle is `batch` or `collection`, the
+application section code belongs in `Communication.topic`. A LOINC section code
+is serialized as native FHIR `topic.coding`; it is not inferred from
+`payload.contentCodeableConcept`. A document Bundle instead remains organized
+by its attached `Composition.section` graph.
+
 ## Identity Continuity
 
 For ICA-backed organization activation, the representative/controller proof is
@@ -134,6 +147,7 @@ read first:
 - [`docs/101-CLINICAL-IPS.md`](docs/101-CLINICAL-IPS.md)
 - [`docs/REFERENCE-CLINICAL-IPS-API.md`](docs/REFERENCE-CLINICAL-IPS-API.md)
 - [`docs/101-CONSENT_PERMISSION_TEMPLATES.md`](docs/101-CONSENT_PERMISSION_TEMPLATES.md)
+- [`docs/101-INDIVIDUAL-MEMBER-SMART.md`](docs/101-INDIVIDUAL-MEMBER-SMART.md)
 
 Shared batch model for high-frequency clinical measurements:
 

package/dist/examples/consent-access.d.ts

@@ -21,6 +21,7 @@ export declare const EXAMPLE_CONSENT_ACCESS_RULES: Readonly<{
     paramedicByJurisdiction: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
     directPhysicianDenyInsideAllowedOrganization: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
     relatedPersonByEmail: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
+    relatedPersonClinicalSections: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
     revokedPhysicianEmailConsent: ConsentRule & Partial<Record<ClaimConsent.resourceType, string>>;
 }>;
 export declare const EXAMPLE_CONSENT_PHONE_EXTENSION_PENDING: Readonly<{

package/dist/examples/consent-access.js

@@ -106,6 +106,21 @@ export const EXAMPLE_CONSENT_ACCESS_RULES = Object.freeze({
         actions: [HealthcareBasicSections.PatientSummaryDocument.claim],
         resourceTypes: [ResourceTypesFhirR4.Composition, ResourceTypesFhirR4.DocumentReference],
     }),
+    relatedPersonClinicalSections: buildRule({
+        identifier: 'urn:uuid:consent-related-person-clinical-sections',
+        actorIdentifier: EXAMPLE_EMAIL_RELATED_PERSON,
+        actorRole: EXAMPLE_RELATED_PERSON_ROLE,
+        purpose: HealthcareConsentPurposes.Treatment,
+        actions: [
+            HealthcareBasicSections.AllergiesAndIntolerances.attributeValue,
+            HealthcareBasicSections.HistoryOfMedicationUse.attributeValue,
+        ],
+        resourceTypes: [
+            ResourceTypesFhirR4.Composition,
+            ResourceTypesFhirR4.AllergyIntolerance,
+            ResourceTypesFhirR4.MedicationStatement,
+        ],
+    }),
     revokedPhysicianEmailConsent: buildRule({
         identifier: 'urn:uuid:consent-physician-email-revoked',
         actorIdentifier: EXAMPLE_EMAIL_PROFESSIONAL,

package/dist/models/consent-access.d.ts

@@ -15,6 +15,8 @@ export type ConsentActorDescriptor = Readonly<{
     actorKind?: ConsentActorKind;
     email?: string;
     did?: string;
+    /** Additional verified identifiers bound to the same actor. */
+    aliases?: readonly string[];
     phone?: string;
     organizationDid?: string;
     organizationUrl?: string;

package/dist/utils/communication-fhir-r4.js

@@ -1,5 +1,6 @@
 // Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
+import { LOINC_SYSTEM_URL } from '../models/clinical-sections.js';
 import { validateFhirResource } from './fhir-validator.js';
 /**
  * Validates a FHIR R4 `Communication` resource through the configured validator pipeline.
@@ -85,6 +86,9 @@ export function transformCommunicationClaimsToResourceFhirR4(communicationClaims
         const category = toStringOrUndefined(claims[CommunicationClaim.Category]);
         if (category)
             resource['category'] = [{ coding: [parseSystemCode(category)] }];
+        const topic = toStringOrUndefined(claims[CommunicationClaim.Topic]);
+        if (topic)
+            resource['topic'] = { coding: [parseTopicCoding(topic)] };
         const subject = toStringOrUndefined(claims[CommunicationClaim.Subject]);
         if (subject)
             resource['subject'] = { reference: subject };
@@ -127,6 +131,7 @@ export function extractCommunicationClaimsFromResourceFhirR4(resource, options =
     const partOfRef = resource?.partOf?.[0]?.reference;
     const noteText = resource?.note?.[0]?.text;
     const categoryCoding = resource?.category?.[0]?.coding?.[0];
+    const topicCoding = resource?.topic?.coding?.[0];
     const payloads = resource?.payload || [];
     const referencePayload = payloads.find((payload) => payload.contentReference !== undefined);
     const attachmentPayload = payloads.find((payload) => payload.contentAttachment !== undefined);
@@ -151,6 +156,14 @@ export function extractCommunicationClaimsFromResourceFhirR4(resource, options =
         else if (code)
             claims[CommunicationClaim.Category] = code;
     }
+    if (topicCoding) {
+        const system = toStringOrUndefined(topicCoding.system);
+        const code = toStringOrUndefined(topicCoding.code);
+        if (system && code)
+            claims[CommunicationClaim.Topic] = formatTopicClaim(system, code);
+        else if (code)
+            claims[CommunicationClaim.Topic] = code;
+    }
     setIf(claims, CommunicationClaim.ContentReference, contentReference);
     if (contentAttachment) {
         setIf(claims, CommunicationClaim.ContentAttachmentData, contentAttachment.data);
@@ -214,6 +227,22 @@ function parseSystemCode(value) {
     }
     return { code: trimmed };
 }
+function parseTopicCoding(value) {
+    const coding = parseSystemCode(value);
+    if (coding.system?.toUpperCase() === 'LOINC') {
+        return { ...coding, system: LOINC_SYSTEM_URL };
+    }
+    return coding;
+}
+function formatTopicClaim(system, code) {
+    const normalizedSystem = system.trim().toLowerCase();
+    if (normalizedSystem === LOINC_SYSTEM_URL
+        || normalizedSystem === 'https://loinc.org'
+        || normalizedSystem === 'urn:oid:2.16.840.1.113883.6.1') {
+        return `LOINC|${code.trim()}`;
+    }
+    return `${system.trim()}|${code.trim()}`;
+}
 function toStringOrUndefined(value) {
     if (value === undefined || value === null)
         return undefined;

package/dist/utils/consent.js

@@ -245,9 +245,30 @@ function splitCsv(value) {
         .map((item) => item.trim())
         .filter(Boolean);
 }
+/**
+ * Reads one concrete Consent search-parameter claim from either the internal
+ * rule shape (`Consent.action`) or a contextualized FHIR claim
+ * (`org.hl7.fhir.api.Consent.action`). Persisted rule sets from both forms are
+ * therefore evaluated identically.
+ */
+function readConsentRuleClaim(rule, claim) {
+    const source = rule;
+    if (source[claim] !== undefined)
+        return source[claim];
+    const context = String(source['@context'] || '').trim().replace(/\.$/, '');
+    if (context && source[`${context}.${claim}`] !== undefined) {
+        return source[`${context}.${claim}`];
+    }
+    return source[`org.hl7.fhir.api.${claim}`];
+}
 function normalizeSectionToken(value) {
     const trimmed = String(value || '').trim();
-    if (!trimmed || !trimmed.includes('|'))
+    if (!trimmed)
+        return trimmed;
+    const loincPrefixed = trimmed.match(/^loinc:([^|:\s]+)$/i);
+    if (loincPrefixed)
+        return `loinc|${loincPrefixed[1]}`;
+    if (!trimmed.includes('|'))
         return trimmed;
     const [system, code] = trimmed.split('|', 2);
     const normalizedSystem = system
@@ -405,6 +426,12 @@ export function resolveConsentActor(actor) {
             }));
         }
     }
+    for (const alias of actor.aliases || []) {
+        const normalizedAlias = String(alias || '').trim();
+        if (normalizedAlias) {
+            directTargets.push(normalizeConsentTarget(normalizedAlias, { actorKind }));
+        }
+    }
     const phone = normalizePhone(String(actor.phone || ''));
     if (phone) {
         const phoneTarget = normalizeConsentTarget(`tel:${phone}`, { actorKind });
@@ -453,7 +480,7 @@ export function resolveConsentActor(actor) {
  * @param options.now Optional evaluation timestamp.
  */
 export function isConsentRuleActive(rule, options = {}) {
-    if (options.subject && String(rule[ClaimConsent.subject] || '').trim() !== String(options.subject || '').trim()) {
+    if (options.subject && String(readConsentRuleClaim(rule, ClaimConsent.subject) || '').trim() !== String(options.subject || '').trim()) {
         return false;
     }
     const now = options.now instanceof Date
@@ -461,8 +488,8 @@ export function isConsentRuleActive(rule, options = {}) {
         : options.now
             ? new Date(options.now).getTime()
             : Date.now();
-    const periodStart = String(rule[ClaimConsent.periodStart] || '').trim();
-    const periodEnd = String(rule[ClaimConsent.periodEnd] || '').trim();
+    const periodStart = String(readConsentRuleClaim(rule, ClaimConsent.periodStart) || '').trim();
+    const periodEnd = String(readConsentRuleClaim(rule, ClaimConsent.periodEnd) || '').trim();
     if (periodStart && !Number.isNaN(Date.parse(periodStart)) && Date.parse(periodStart) > now)
         return false;
     if (periodEnd && !Number.isNaN(Date.parse(periodEnd)) && Date.parse(periodEnd) < now)
@@ -472,7 +499,7 @@ export function isConsentRuleActive(rule, options = {}) {
 function groupRulesBy(rules, predicate) {
     const groups = {};
     for (const rule of rules) {
-        for (const token of splitCsv(rule[ClaimConsent.actorIdentifier])) {
+        for (const token of splitCsv(readConsentRuleClaim(rule, ClaimConsent.actorIdentifier))) {
             const normalized = normalizeConsentTarget(token, { preferOrganizationDid: true });
             if (!predicate(normalized))
                 continue;
@@ -505,7 +532,7 @@ function normalizeRequestedList(values, wildcard = '*') {
 }
 function extractRuleResourceTypes(rule) {
     const candidates = [
-        rule[ClaimConsent.resourceType],
+        readConsentRuleClaim(rule, ClaimConsent.resourceType),
         rule['Consent.resource-type'],
         rule['Consent.resource'],
         rule['Consent.data-type'],
@@ -518,7 +545,7 @@ function extractRuleResourceTypes(rule) {
     return [];
 }
 function ruleMatchesRole(rule, actorRole) {
-    const ruleRoles = splitCsv(rule[ClaimConsent.actorRole]).map(normalizeConsentRoleValue).filter(Boolean);
+    const ruleRoles = splitCsv(readConsentRuleClaim(rule, ClaimConsent.actorRole)).map(normalizeConsentRoleValue).filter(Boolean);
     if (ruleRoles.length === 0 || ruleRoles.includes('*'))
         return true;
     const requestedRole = normalizeConsentRoleValue(String(actorRole || ''));
@@ -542,7 +569,7 @@ function ruleMatchesRole(rule, actorRole) {
     });
 }
 function ruleMatchesPurpose(rule, purpose) {
-    const rulePurpose = String(rule[ClaimConsent.purpose] || '').trim();
+    const rulePurpose = String(readConsentRuleClaim(rule, ClaimConsent.purpose) || '').trim();
     if (!purpose || !rulePurpose)
         return true;
     return rulePurpose === purpose;
@@ -551,11 +578,29 @@ function ruleMatchesSection(rule, section) {
     if (!section || section === '*')
         return true;
     const requestedSection = normalizeSectionToken(section);
-    const actions = splitCsv(rule[ClaimConsent.action]).map(normalizeSectionToken);
+    const rawAction = String(readConsentRuleClaim(rule, ClaimConsent.action) || '').trim();
+    const actions = extractRuleSectionTokens(rawAction).map(normalizeSectionToken);
     if (actions.length === 0)
         return false;
     return actions.includes(requestedSection) || actions.includes('*');
 }
+function extractRuleSectionTokens(rawAction) {
+    if (!rawAction)
+        return [];
+    const canonicalExpressions = rawAction
+        .split(/\s+/)
+        .map((value) => value.trim())
+        .filter((value) => /^(?:organization\/|patient\/)?Composition\.[A-Za-z]+(?:\?|$)/i.test(value));
+    if (canonicalExpressions.length === 0)
+        return splitCsv(rawAction);
+    return canonicalExpressions.flatMap((expression) => {
+        const [, queryString = ''] = expression.split('?', 2);
+        const section = new URLSearchParams(queryString).get('section');
+        return section
+            ? section.split(',').map((value) => value.trim()).filter(Boolean)
+            : ['*'];
+    });
+}
 function ruleMatchesResourceType(rule, resourceType) {
     if (!resourceType || resourceType === '*')
         return true;
@@ -565,7 +610,7 @@ function ruleMatchesResourceType(rule, resourceType) {
     return resourceTypes.includes(resourceType) || resourceTypes.includes('*');
 }
 function resolveRuleMatch(rule, actor) {
-    for (const token of splitCsv(rule[ClaimConsent.actorIdentifier])) {
+    for (const token of splitCsv(readConsentRuleClaim(rule, ClaimConsent.actorIdentifier))) {
         const normalized = normalizeConsentTarget(token, { preferOrganizationDid: true });
         if (actor.directTargets.some((target) => target.canonicalValue === normalized.canonicalValue)) {
             return { matchKind: 'direct', target: normalized, precedenceBase: 10 };
@@ -583,7 +628,7 @@ function toRuleMatch(rule, actor, section, resourceType) {
     const resolved = resolveRuleMatch(rule, actor);
     if (!resolved.target || resolved.matchKind === 'none' || resolved.precedenceBase === undefined)
         return undefined;
-    const decision = rule[ClaimConsent.decision];
+    const decision = readConsentRuleClaim(rule, ClaimConsent.decision);
     const precedence = resolved.precedenceBase + (decision === 'deny' ? 0 : 1);
     return {
         rule,

package/dist/utils/individual-smart.d.ts

@@ -38,6 +38,15 @@ export type IndividualControllerCredentialInput = IndividualActorIdentityCredent
 export type IndividualControllerVpPayloadInput = IndividualActorIdentityVpPayloadInput;
 export type IndividualMemberCredentialInput = IndividualActorIdentityCredentialInput;
 export type IndividualMemberVpPayloadInput = IndividualActorIdentityVpPayloadInput;
+export type IndividualMemberCredentialSummary = Readonly<{
+    actorDid: string;
+    subjectDid: string;
+    relationship: string;
+    issuerDid?: string;
+    email?: string;
+    telephone?: string;
+    sameAs: string[];
+}>;
 export declare function getIndividualControllerIdentitySameAs(input: Readonly<Pick<IndividualControllerCredentialInput, 'sameAs' | 'email'>>): string[];
 export declare function getIndividualControllerIdentityTelephone(input: Readonly<Pick<IndividualControllerCredentialInput, 'telephone'>>): string | undefined;
 export declare function getIndividualControllerIdentityVC(input: IndividualControllerCredentialInput): Record<string, unknown>;
@@ -51,6 +60,17 @@ export declare function getIndividualSubjectVC(input: IndividualSubjectCredentia
 export declare function getIndividualMemberIdentitySameAs(input: Readonly<Pick<IndividualMemberCredentialInput, 'sameAs' | 'email'>>): string[];
 export declare function getIndividualMemberIdentityTelephone(input: Readonly<Pick<IndividualMemberCredentialInput, 'telephone'>>): string | undefined;
 export declare function getIndividualMemberIdentityVC(input: IndividualMemberCredentialInput): Record<string, unknown>;
+/**
+ * Reads the relationship identity asserted by one already-verified member VC.
+ * Signature/proof verification belongs to the enclosing VP verifier.
+ */
+export declare function summarizeIndividualMemberIdentityCredential(credential: unknown): IndividualMemberCredentialSummary | undefined;
+/** Finds an exact actor/subject member relationship in an already-verified VP. */
+export declare function getMatchingIndividualMemberCredentialFromVpToken(vpToken: string, criteria: Readonly<{
+    actorDid: string;
+    subjectDid: string;
+    relationship?: string;
+}>): IndividualMemberCredentialSummary | undefined;
 export declare function buildIndividualMemberIdentityVpPayload(input: IndividualMemberVpPayloadInput): Record<string, unknown>;
 export declare function buildUnsignedIndividualMemberIdentityVpJwt(input: IndividualMemberVpPayloadInput, options?: Readonly<{
     nowSeconds?: number;

package/dist/utils/individual-smart.js

@@ -2,6 +2,7 @@ import { ClaimsPersonSchemaorg } from '../constants/schemaorg.js';
 import { IndividualCredentialTypes, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
 import { normalizeSameAsHashCsv, normalizeSameAsHashList, normalizeTelephoneHash } from './same-as.js';
 import { buildUnsignedVpJwt } from './jwt.js';
+import { getVpCredentials } from './vp-token.js';
 function getIndividualIdentitySameAs(input) {
     const sameAsCandidates = [];
     if (input.sameAs) {
@@ -127,6 +128,50 @@ export function getIndividualMemberIdentityTelephone(input) {
 export function getIndividualMemberIdentityVC(input) {
     return buildIndividualIdentityVC(input, IndividualCredentialTypes.IndividualMemberCredential);
 }
+/**
+ * Reads the relationship identity asserted by one already-verified member VC.
+ * Signature/proof verification belongs to the enclosing VP verifier.
+ */
+export function summarizeIndividualMemberIdentityCredential(credential) {
+    const source = credential;
+    const types = Array.isArray(source?.type) ? source.type.map(String) : [String(source?.type || '')];
+    if (!types.includes(IndividualCredentialTypes.IndividualMemberCredential))
+        return undefined;
+    const subject = source?.credentialSubject || {};
+    const actorDid = String(subject.id || '').trim();
+    const subjectDid = String(subject.subject || '').trim();
+    const relationship = String(subject.relationship || '').trim();
+    if (!actorDid || !subjectDid || !relationship)
+        return undefined;
+    return {
+        actorDid,
+        subjectDid,
+        relationship,
+        ...(String(source?.issuer?.id || source?.issuer || '').trim()
+            ? { issuerDid: String(source.issuer?.id || source.issuer).trim() }
+            : {}),
+        ...(String(subject[ClaimsPersonSchemaorg.email] || '').trim()
+            ? { email: String(subject[ClaimsPersonSchemaorg.email]).trim().toLowerCase() }
+            : {}),
+        ...(String(subject[ClaimsPersonSchemaorg.telephone] || '').trim()
+            ? { telephone: String(subject[ClaimsPersonSchemaorg.telephone]).trim() }
+            : {}),
+        sameAs: normalizeSameAsHashList(subject.sameAs),
+    };
+}
+/** Finds an exact actor/subject member relationship in an already-verified VP. */
+export function getMatchingIndividualMemberCredentialFromVpToken(vpToken, criteria) {
+    return getVpCredentials(vpToken)
+        .map(summarizeIndividualMemberIdentityCredential)
+        .find((summary) => {
+        if (!summary)
+            return false;
+        return summary.actorDid === String(criteria.actorDid || '').trim()
+            && summary.subjectDid === String(criteria.subjectDid || '').trim()
+            && (!criteria.relationship
+                || summary.relationship.toLowerCase() === String(criteria.relationship).trim().toLowerCase());
+    });
+}
 export function buildIndividualMemberIdentityVpPayload(input) {
     return buildIndividualIdentityVpPayload(input, IndividualCredentialTypes.IndividualMemberCredential);
 }

package/dist/utils/smart-scope.d.ts

@@ -1,3 +1,5 @@
+import type { ConsentActorDescriptor, EffectiveAccessEvaluation } from '../models/consent-access';
+import type { ConsentRule } from '../models/consent-rule';
 export type SmartCompositionReadScopeOptions = {
     /**
      * Subject DID pinned by the current CORE GW root scope contract.
@@ -26,3 +28,59 @@ export type SmartCompositionReadScopeOptions = {
  * scope builder.
  */
 export declare function buildSmartCompositionReadScope(options: SmartCompositionReadScopeOptions): string;
+export type DeriveGrantedSmartScopesInput = Readonly<{
+    /** Requested SMART root scopes. Every scope must pin the same subject. */
+    requestedScopes: string | readonly string[];
+    /** Authenticated actor descriptors resolved by a trusted runtime. */
+    actor: ConsentActorDescriptor;
+    /** Canonical relationship or professional role claim. */
+    actorRole?: string;
+    /** Consent purpose required for the access. */
+    purpose?: string;
+    /** Deterministic clock used by tests and policy evaluation. */
+    now?: string | Date;
+    /**
+     * Known sections used to expand `section=*` or an omitted section filter.
+     *
+     * Defaults to the shared IPS summary-section registry. Supplying an explicit
+     * list is useful for a sector-specific profile while keeping the evaluator
+     * product-neutral.
+     */
+    availableSections?: readonly string[];
+}>;
+export type GrantedSmartScopesDecision = 'granted' | 'partial' | 'denied';
+export type GrantedSmartScopesResult = Readonly<{
+    /** One subject shared by every accepted request scope. */
+    subject: string;
+    /** Overall projection decision. Empty grants are always `denied`. */
+    decision: GrantedSmartScopesDecision;
+    /** Exact scopes that GW may place in the signed token. */
+    grantedScopes: string[];
+    /** Original scopes or scope fragments that received no grant. */
+    deniedScopes: string[];
+    /** Exact clinical sections retained in `grantedScopes`. */
+    grantedSections: string[];
+    /** Requested clinical sections omitted from `grantedScopes`. */
+    deniedSections: string[];
+    /** Per-scope shared consent evaluations retained for audit/tests. */
+    evaluations: EffectiveAccessEvaluation[];
+}>;
+/**
+ * Derives the exact read-only SMART scopes covered by active Consent rules.
+ *
+ * This pure helper deliberately does not create or sign a JWT. A trusted GW
+ * supplies authoritative rules and actor identity, calls this projection, and
+ * signs only `grantedScopes`. Browser applications may use the same function
+ * with fixtures to predict UI capabilities, but that prediction grants no
+ * authority.
+ *
+ * Security properties:
+ * - all root scopes must target one subject
+ * - `patient/*`, non-Composition and write-bearing scopes fail closed
+ * - wildcard/omitted section requests are expanded to explicit known sections
+ * - the returned scopes contain only `requested ∩ actively consented`
+ *
+ * @param rules Authoritative or test Consent rules.
+ * @param input Requested scopes plus trusted actor/purpose context.
+ */
+export declare function deriveGrantedSmartScopes(rules: readonly ConsentRule[], input: DeriveGrantedSmartScopesInput): GrantedSmartScopesResult;

package/dist/utils/smart-scope.js

@@ -1,4 +1,5 @@
-import { HealthcareBasicSections } from '../constants/healthcare.js';
+import { HealthcareBasicSections, HealthcareSummarySections, } from '../constants/healthcare.js';
+import { evaluateConsentCoverage } from './consent.js';
 /**
  * Builds the gateway-pinned SMART root scope required by the current CORE GW
  * token contract:
@@ -27,3 +28,130 @@ export function buildSmartCompositionReadScope(options) {
     }
     return `organization/Composition.${options.accessVerb || 'rs'}?${query.toString()}`;
 }
+/**
+ * Derives the exact read-only SMART scopes covered by active Consent rules.
+ *
+ * This pure helper deliberately does not create or sign a JWT. A trusted GW
+ * supplies authoritative rules and actor identity, calls this projection, and
+ * signs only `grantedScopes`. Browser applications may use the same function
+ * with fixtures to predict UI capabilities, but that prediction grants no
+ * authority.
+ *
+ * Security properties:
+ * - all root scopes must target one subject
+ * - `patient/*`, non-Composition and write-bearing scopes fail closed
+ * - wildcard/omitted section requests are expanded to explicit known sections
+ * - the returned scopes contain only `requested ∩ actively consented`
+ *
+ * @param rules Authoritative or test Consent rules.
+ * @param input Requested scopes plus trusted actor/purpose context.
+ */
+export function deriveGrantedSmartScopes(rules, input) {
+    const rawScopes = (Array.isArray(input.requestedScopes)
+        ? input.requestedScopes
+        : [input.requestedScopes])
+        .map((scope) => String(scope || '').trim())
+        .filter(Boolean);
+    if (rawScopes.length === 0) {
+        throw new Error('deriveGrantedSmartScopes requires at least one requested scope.');
+    }
+    const availableSections = Array.from(new Set((input.availableSections?.length
+        ? input.availableSections
+        : Object.values(HealthcareSummarySections).map((section) => section.attributeValue))
+        .map((section) => String(section || '').trim())
+        .filter(Boolean)));
+    const parsedScopes = rawScopes.map((scope) => parseClinicalScope(scope, availableSections));
+    const subjects = Array.from(new Set(parsedScopes.map((scope) => scope.subject).filter(Boolean)));
+    if (subjects.length !== 1) {
+        throw new Error('deriveGrantedSmartScopes requires every requested scope to pin one single subject.');
+    }
+    const subject = subjects[0];
+    const grantedScopes = [];
+    const deniedScopes = [];
+    const grantedSections = [];
+    const deniedSections = [];
+    const evaluations = [];
+    for (const parsed of parsedScopes) {
+        if (!parsed.supported) {
+            deniedScopes.push(parsed.raw);
+            deniedSections.push(...parsed.requestedSections);
+            continue;
+        }
+        const scopeGrantedSections = [];
+        for (const section of parsed.requestedSections) {
+            const evaluation = evaluateConsentCoverage([...rules], {
+                subject,
+                actor: input.actor,
+                actorRole: input.actorRole,
+                purpose: input.purpose,
+                sections: [section],
+                resourceTypes: ['Composition'],
+                now: input.now,
+            });
+            evaluations.push(evaluation);
+            if (evaluation.allowed) {
+                scopeGrantedSections.push(section);
+                grantedSections.push(section);
+            }
+            else {
+                deniedSections.push(section);
+            }
+        }
+        if (scopeGrantedSections.length === 0) {
+            deniedScopes.push(parsed.raw);
+            continue;
+        }
+        grantedScopes.push(buildSmartCompositionReadScope({
+            subjectDid: subject,
+            sections: scopeGrantedSections,
+            accessVerb: parsed.accessVerb,
+        }));
+        if (scopeGrantedSections.length !== parsed.requestedSections.length) {
+            deniedScopes.push(parsed.raw);
+        }
+    }
+    const uniqueGrantedScopes = Array.from(new Set(grantedScopes));
+    const uniqueDeniedScopes = Array.from(new Set(deniedScopes));
+    const uniqueGrantedSections = Array.from(new Set(grantedSections));
+    const uniqueDeniedSections = Array.from(new Set(deniedSections))
+        .filter((section) => !uniqueGrantedSections.includes(section));
+    const decision = uniqueGrantedScopes.length === 0
+        ? 'denied'
+        : uniqueDeniedScopes.length > 0 || uniqueDeniedSections.length > 0
+            ? 'partial'
+            : 'granted';
+    return {
+        subject,
+        decision,
+        grantedScopes: uniqueGrantedScopes,
+        deniedScopes: uniqueDeniedScopes,
+        grantedSections: uniqueGrantedSections,
+        deniedSections: uniqueDeniedSections,
+        evaluations,
+    };
+}
+function parseClinicalScope(rawScope, availableSections) {
+    const [head, queryString = ''] = rawScope.split('?', 2);
+    const match = head.match(/^organization\/Composition\.(r|rs)$/);
+    const params = new URLSearchParams(queryString);
+    const subject = String(params.get('subject') || '').trim();
+    if (!subject) {
+        throw new Error(`SMART scope must pin a subject: ${rawScope}`);
+    }
+    const unsupportedFilter = Array.from(params.keys())
+        .some((key) => key !== 'subject' && key !== 'section');
+    const requested = String(params.get('section') || '').trim();
+    const requestedSections = !requested || requested.split(',').includes('*')
+        ? [...availableSections]
+        : requested
+            .split(',')
+            .map((section) => section.trim())
+            .filter(Boolean);
+    return {
+        raw: rawScope,
+        subject,
+        accessVerb: match?.[1],
+        requestedSections: Array.from(new Set(requestedSections)),
+        supported: Boolean(match) && !unsupportedFilter && requestedSections.length > 0,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.3.13",
+  "version": "2.3.14",
   "publishConfig": {
     "access": "public"
   },