gdc-common-utils-ts 1.4.22 → 1.5.1

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

@@ -0,0 +1,138 @@
+export declare const EXAMPLE_CONSENT_ACCESS_SUBJECT: "did:web:api.acme.org:individual:123";
+export declare const EXAMPLE_CONSENT_ACCESS_PROVIDER_DID: "did:web:hospital.acme.org";
+export declare const EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL: "doctor.oncall@example.org";
+export declare const EXAMPLE_CONSENT_ACCESS_RELATED_PERSON_EMAIL: "parent.guardian@example.org";
+export declare const EXAMPLE_CONSENT_ACCESS_JURISDICTION: "ES";
+export declare const EXAMPLE_CONSENT_ACCESS_RULES: Readonly<{
+    physicianByEmailContinuousCare: {
+        readonly 'Consent.date': "2026-05-20";
+        readonly 'Consent.period-end'?: string | undefined;
+        readonly 'Consent.period-start'?: string | undefined;
+        readonly 'Consent.resourceType'?: string | undefined;
+        readonly '@context': "org.hl7.fhir.api";
+        readonly 'Consent.identifier': string;
+        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
+        readonly 'Consent.actor-identifier': string;
+        readonly 'Consent.actor-role': string;
+        readonly 'Consent.decision': "permit" | "deny";
+        readonly 'Consent.purpose': string;
+        readonly 'Consent.action': string;
+    };
+    physicianByEmailEmergency: {
+        readonly 'Consent.date': "2026-05-20";
+        readonly 'Consent.period-end'?: string | undefined;
+        readonly 'Consent.period-start'?: string | undefined;
+        readonly 'Consent.resourceType'?: string | undefined;
+        readonly '@context': "org.hl7.fhir.api";
+        readonly 'Consent.identifier': string;
+        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
+        readonly 'Consent.actor-identifier': string;
+        readonly 'Consent.actor-role': string;
+        readonly 'Consent.decision': "permit" | "deny";
+        readonly 'Consent.purpose': string;
+        readonly 'Consent.action': string;
+    };
+    physicianByOrganizationContinuousCare: {
+        readonly 'Consent.date': "2026-05-20";
+        readonly 'Consent.period-end'?: string | undefined;
+        readonly 'Consent.period-start'?: string | undefined;
+        readonly 'Consent.resourceType'?: string | undefined;
+        readonly '@context': "org.hl7.fhir.api";
+        readonly 'Consent.identifier': string;
+        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
+        readonly 'Consent.actor-identifier': string;
+        readonly 'Consent.actor-role': string;
+        readonly 'Consent.decision': "permit" | "deny";
+        readonly 'Consent.purpose': string;
+        readonly 'Consent.action': string;
+    };
+    physicianByJurisdictionEmergency: {
+        readonly 'Consent.date': "2026-05-20";
+        readonly 'Consent.period-end'?: string | undefined;
+        readonly 'Consent.period-start'?: string | undefined;
+        readonly 'Consent.resourceType'?: string | undefined;
+        readonly '@context': "org.hl7.fhir.api";
+        readonly 'Consent.identifier': string;
+        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
+        readonly 'Consent.actor-identifier': string;
+        readonly 'Consent.actor-role': string;
+        readonly 'Consent.decision': "permit" | "deny";
+        readonly 'Consent.purpose': string;
+        readonly 'Consent.action': string;
+    };
+    nurseByOrganization: {
+        readonly 'Consent.date': "2026-05-20";
+        readonly 'Consent.period-end'?: string | undefined;
+        readonly 'Consent.period-start'?: string | undefined;
+        readonly 'Consent.resourceType'?: string | undefined;
+        readonly '@context': "org.hl7.fhir.api";
+        readonly 'Consent.identifier': string;
+        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
+        readonly 'Consent.actor-identifier': string;
+        readonly 'Consent.actor-role': string;
+        readonly 'Consent.decision': "permit" | "deny";
+        readonly 'Consent.purpose': string;
+        readonly 'Consent.action': string;
+    };
+    paramedicByJurisdiction: {
+        readonly 'Consent.date': "2026-05-20";
+        readonly 'Consent.period-end'?: string | undefined;
+        readonly 'Consent.period-start'?: string | undefined;
+        readonly 'Consent.resourceType'?: string | undefined;
+        readonly '@context': "org.hl7.fhir.api";
+        readonly 'Consent.identifier': string;
+        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
+        readonly 'Consent.actor-identifier': string;
+        readonly 'Consent.actor-role': string;
+        readonly 'Consent.decision': "permit" | "deny";
+        readonly 'Consent.purpose': string;
+        readonly 'Consent.action': string;
+    };
+    directPhysicianDenyInsideAllowedOrganization: {
+        readonly 'Consent.date': "2026-05-20";
+        readonly 'Consent.period-end'?: string | undefined;
+        readonly 'Consent.period-start'?: string | undefined;
+        readonly 'Consent.resourceType'?: string | undefined;
+        readonly '@context': "org.hl7.fhir.api";
+        readonly 'Consent.identifier': string;
+        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
+        readonly 'Consent.actor-identifier': string;
+        readonly 'Consent.actor-role': string;
+        readonly 'Consent.decision': "permit" | "deny";
+        readonly 'Consent.purpose': string;
+        readonly 'Consent.action': string;
+    };
+    relatedPersonByEmail: {
+        readonly 'Consent.date': "2026-05-20";
+        readonly 'Consent.period-end'?: string | undefined;
+        readonly 'Consent.period-start'?: string | undefined;
+        readonly 'Consent.resourceType'?: string | undefined;
+        readonly '@context': "org.hl7.fhir.api";
+        readonly 'Consent.identifier': string;
+        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
+        readonly 'Consent.actor-identifier': string;
+        readonly 'Consent.actor-role': string;
+        readonly 'Consent.decision': "permit" | "deny";
+        readonly 'Consent.purpose': string;
+        readonly 'Consent.action': string;
+    };
+    revokedPhysicianEmailConsent: {
+        readonly 'Consent.date': "2026-05-20";
+        readonly 'Consent.period-end'?: string | undefined;
+        readonly 'Consent.period-start'?: string | undefined;
+        readonly 'Consent.resourceType'?: string | undefined;
+        readonly '@context': "org.hl7.fhir.api";
+        readonly 'Consent.identifier': string;
+        readonly 'Consent.subject': "did:web:api.acme.org:individual:123";
+        readonly 'Consent.actor-identifier': string;
+        readonly 'Consent.actor-role': string;
+        readonly 'Consent.decision': "permit" | "deny";
+        readonly 'Consent.purpose': string;
+        readonly 'Consent.action': string;
+    };
+}>;
+export declare const EXAMPLE_CONSENT_PHONE_EXTENSION_PENDING: Readonly<{
+    target: "tel:+34600111222";
+    status: "pending-extension";
+    reason: "telephone actor targeting remains an extension concern unless the sector/runtime explicitly enables it";
+}>;

package/dist/examples/consent-access.js

@@ -0,0 +1,104 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentPurposes, } from '../constants/healthcare.js';
+import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+export const EXAMPLE_CONSENT_ACCESS_SUBJECT = 'did:web:api.acme.org:individual:123';
+export const EXAMPLE_CONSENT_ACCESS_PROVIDER_DID = 'did:web:hospital.acme.org';
+export const EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL = 'doctor.oncall@example.org';
+export const EXAMPLE_CONSENT_ACCESS_RELATED_PERSON_EMAIL = 'parent.guardian@example.org';
+export const EXAMPLE_CONSENT_ACCESS_JURISDICTION = 'ES';
+function buildRule(input) {
+    return {
+        '@context': 'org.hl7.fhir.api',
+        'Consent.identifier': input.identifier,
+        'Consent.subject': EXAMPLE_CONSENT_ACCESS_SUBJECT,
+        'Consent.actor-identifier': input.actorIdentifier,
+        'Consent.actor-role': input.actorRole,
+        'Consent.decision': input.decision || 'permit',
+        'Consent.purpose': input.purpose,
+        'Consent.action': input.actions.join(','),
+        ...(input.resourceTypes?.length ? { 'Consent.resourceType': input.resourceTypes.join(',') } : {}),
+        ...(input.periodStart ? { 'Consent.period-start': input.periodStart } : {}),
+        ...(input.periodEnd ? { 'Consent.period-end': input.periodEnd } : {}),
+        'Consent.date': '2026-05-20',
+    };
+}
+export const EXAMPLE_CONSENT_ACCESS_RULES = Object.freeze({
+    physicianByEmailContinuousCare: buildRule({
+        identifier: 'urn:uuid:consent-physician-email-treatment',
+        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL,
+        actorRole: HealthcareActorRoles.Physician,
+        purpose: HealthcareConsentPurposes.Treatment,
+        actions: [HealthcareBasicSections.AllergiesAndIntolerances.claim],
+        resourceTypes: [ResourceTypesFhirR4.Composition, ResourceTypesFhirR4.AllergyIntolerance],
+    }),
+    physicianByEmailEmergency: buildRule({
+        identifier: 'urn:uuid:consent-physician-email-emergency',
+        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL,
+        actorRole: HealthcareActorRoles.Physician,
+        purpose: HealthcareConsentPurposes.EmergencyTreatment,
+        actions: [HealthcareBasicSections.PatientSummaryDocument.claim],
+        resourceTypes: [ResourceTypesFhirR4.Composition, ResourceTypesFhirR4.DocumentReference],
+    }),
+    physicianByOrganizationContinuousCare: buildRule({
+        identifier: 'urn:uuid:consent-physician-org-treatment',
+        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_DID,
+        actorRole: HealthcareActorRoles.Physician,
+        purpose: HealthcareConsentPurposes.Treatment,
+        actions: [HealthcareBasicSections.Results.claim],
+        resourceTypes: [ResourceTypesFhirR4.Composition, ResourceTypesFhirR4.DiagnosticReport],
+    }),
+    physicianByJurisdictionEmergency: buildRule({
+        identifier: 'urn:uuid:consent-physician-jurisdiction-emergency',
+        actorIdentifier: EXAMPLE_CONSENT_ACCESS_JURISDICTION,
+        actorRole: HealthcareActorRoles.Physician,
+        purpose: HealthcareConsentPurposes.EmergencyTreatment,
+        actions: [HealthcareBasicSections.PatientSummaryDocument.claim],
+        resourceTypes: [ResourceTypesFhirR4.Composition, ResourceTypesFhirR4.DocumentReference],
+    }),
+    nurseByOrganization: buildRule({
+        identifier: 'urn:uuid:consent-nurse-org-treatment',
+        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_DID,
+        actorRole: HealthcareActorRoles.NursingProfessional,
+        purpose: HealthcareConsentPurposes.Treatment,
+        actions: [HealthcareBasicSections.HistoryOfMedicationUse.claim],
+        resourceTypes: [ResourceTypesFhirR4.Composition, ResourceTypesFhirR4.MedicationStatement],
+    }),
+    paramedicByJurisdiction: buildRule({
+        identifier: 'urn:uuid:consent-paramedic-jurisdiction-emergency',
+        actorIdentifier: EXAMPLE_CONSENT_ACCESS_JURISDICTION,
+        actorRole: HealthcareActorRoles.Paramedic,
+        purpose: HealthcareConsentPurposes.EmergencyTreatment,
+        actions: [HealthcareBasicSections.PatientSummaryDocument.claim],
+        resourceTypes: [ResourceTypesFhirR4.Composition, ResourceTypesFhirR4.Observation],
+    }),
+    directPhysicianDenyInsideAllowedOrganization: buildRule({
+        identifier: 'urn:uuid:consent-physician-direct-deny',
+        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL,
+        actorRole: HealthcareActorRoles.Physician,
+        decision: 'deny',
+        purpose: HealthcareConsentPurposes.Treatment,
+        actions: [HealthcareBasicSections.Results.claim],
+        resourceTypes: [ResourceTypesFhirR4.DiagnosticReport],
+    }),
+    relatedPersonByEmail: buildRule({
+        identifier: 'urn:uuid:consent-related-person-email',
+        actorIdentifier: EXAMPLE_CONSENT_ACCESS_RELATED_PERSON_EMAIL,
+        actorRole: 'v3-RoleCode|RESPRSN',
+        purpose: HealthcareConsentPurposes.Treatment,
+        actions: [HealthcareBasicSections.PatientSummaryDocument.claim],
+        resourceTypes: [ResourceTypesFhirR4.Composition, ResourceTypesFhirR4.DocumentReference],
+    }),
+    revokedPhysicianEmailConsent: buildRule({
+        identifier: 'urn:uuid:consent-physician-email-revoked',
+        actorIdentifier: EXAMPLE_CONSENT_ACCESS_PROVIDER_EMAIL,
+        actorRole: HealthcareActorRoles.Physician,
+        purpose: HealthcareConsentPurposes.EmergencyTreatment,
+        actions: [HealthcareBasicSections.PatientSummaryDocument.claim],
+        periodEnd: '2026-05-01T00:00:00Z',
+    }),
+});
+export const EXAMPLE_CONSENT_PHONE_EXTENSION_PENDING = Object.freeze({
+    target: 'tel:+34600111222',
+    status: 'pending-extension',
+    reason: 'telephone actor targeting remains an extension concern unless the sector/runtime explicitly enables it',
+});

package/dist/examples/index.d.ts

@@ -3,6 +3,7 @@ export * from './organization-controller';
 export * from './individual-controller';
 export * from './professional';
 export * from './related-person';
+export * from './consent-access';
 export * from './frontend-session';
 export * from './api-flow-examples';
 export * from './contract-examples';

package/dist/examples/index.js

@@ -3,6 +3,7 @@ export * from './organization-controller.js';
 export * from './individual-controller.js';
 export * from './professional.js';
 export * from './related-person.js';
+export * from './consent-access.js';
 export * from './frontend-session.js';
 export * from './api-flow-examples.js';
 export * from './contract-examples.js';

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

@@ -0,0 +1,79 @@
+import type { ConsentRule } from './consent-rule.js';
+export type ConsentActorKind = 'professional' | 'related-person';
+export type ConsentMatchKind = 'direct' | 'organization' | 'jurisdiction' | 'none';
+export type ConsentTargetKind = 'email' | 'did' | 'organization' | 'jurisdiction' | 'phone' | 'unknown';
+export type NormalizedConsentTarget = Readonly<{
+    raw: string;
+    kind: ConsentTargetKind;
+    canonicalValue: string;
+    isDirectTarget: boolean;
+    isOrganizationTarget: boolean;
+    isJurisdictionTarget: boolean;
+    isPhoneExtension: boolean;
+}>;
+export type ConsentActorDescriptor = Readonly<{
+    actorKind?: ConsentActorKind;
+    email?: string;
+    did?: string;
+    phone?: string;
+    organizationDid?: string;
+    organizationUrl?: string;
+    jurisdiction?: string;
+}>;
+export type ResolvedConsentActor = Readonly<{
+    actorKind: ConsentActorKind;
+    directTargets: NormalizedConsentTarget[];
+    organizationTargets: NormalizedConsentTarget[];
+    jurisdictionTargets: NormalizedConsentTarget[];
+    phoneTargets: NormalizedConsentTarget[];
+}>;
+export type ConsentCoverageRequest = Readonly<{
+    subject?: string;
+    actor: ConsentActorDescriptor;
+    actorRole?: string;
+    purpose?: string;
+    sections?: string[];
+    resourceTypes?: string[];
+    now?: string | Date;
+}>;
+export type ConsentRuleMatch = Readonly<{
+    rule: ConsentRule;
+    ruleId?: string;
+    decision: 'permit' | 'deny';
+    matchKind: ConsentMatchKind;
+    target: NormalizedConsentTarget;
+    precedence: number;
+    section?: string;
+    resourceType?: string;
+}>;
+export type MissingPermissionSet = Readonly<{
+    sections: string[];
+    resourceTypes: string[];
+    pairs: Array<{
+        section?: string;
+        resourceType?: string;
+        reason: string;
+    }>;
+}>;
+export type EffectiveAccessEvaluation = Readonly<{
+    allowed: boolean;
+    denied: boolean;
+    partial: boolean;
+    subject?: string;
+    actor: ResolvedConsentActor;
+    matchedRules: ConsentRuleMatch[];
+    winningRules: ConsentRuleMatch[];
+    explicitDenials: ConsentRuleMatch[];
+    allowedSections: string[];
+    deniedSections: string[];
+    allowedResourceTypes: string[];
+    deniedResourceTypes: string[];
+    missing: MissingPermissionSet;
+}>;
+export type ActiveConsentView = Readonly<{
+    activeRules: ConsentRule[];
+    byDirectTarget: Record<string, ConsentRule[]>;
+    byOrganizationTarget: Record<string, ConsentRule[]>;
+    byJurisdictionTarget: Record<string, ConsentRule[]>;
+    byPhoneTarget: Record<string, ConsentRule[]>;
+}>;

package/dist/models/consent-access.js

@@ -0,0 +1,2 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+export {};

package/dist/models/index.d.ts

@@ -9,6 +9,7 @@ export * from './confidential-job';
 export * from './confidential-message';
 export * from './confidential-storage';
 export * from './consent-rule';
+export * from './consent-access';
 export * from './crypto';
 export * from './device-license';
 export * from './did';

package/dist/models/index.js

@@ -9,6 +9,7 @@ export * from './confidential-job.js';
 export * from './confidential-message.js';
 export * from './confidential-storage.js';
 export * from './consent-rule.js';
+export * from './consent-access.js';
 export * from './crypto.js';
 export * from './device-license.js';
 export * from './did.js';

package/dist/utils/consent.d.ts

@@ -1,3 +1,5 @@
+import type { ActiveConsentView, ConsentActorDescriptor, ConsentActorKind, ConsentCoverageRequest, EffectiveAccessEvaluation, NormalizedConsentTarget, ResolvedConsentActor } from '../models/consent-access.js';
+import type { ConsentRule } from '../models/consent-rule.js';
 /**
  * Legacy structured actor selector kept for backwards compatibility while the
  * SDK converges on the canonical flat consent actor identifier contract.
@@ -142,3 +144,75 @@ export declare function buildConsentClaimsSimple(input: BuildConsentClaimsSimple
  * @param options.consentIdentifierFactory Optional fallback identifier factory.
  */
 export declare function buildConsentClaimsSimpleWithCid(input: BuildConsentClaimsSimpleInput, options?: BuildConsentClaimsSimpleOptions): ConsentClaimsWithCidResult;
+/**
+ * Normalizes a consent target token into a reusable matching descriptor.
+ *
+ * The helper keeps the current GW contract:
+ * - the first precedence tier is intended for concrete professional email matches
+ * - direct runtime selectors may still include email / `did:web` / phone
+ * - organization targets are normalized to `did:web:<host>`
+ * - jurisdictions resolve to ISO-like uppercase codes
+ * - phone targets stay marked as extension-specific
+ *
+ * @param input Raw target input from a rule or runtime request.
+ * @param options.actorKind Optional actor family hint.
+ * @param options.preferOrganizationDid When true, base `did:web:<host>` values are treated as organization targets.
+ */
+export declare function normalizeConsentTarget(input: string, options?: {
+    actorKind?: ConsentActorKind;
+    preferOrganizationDid?: boolean;
+}): NormalizedConsentTarget;
+/**
+ * Resolves all actor match targets used by consent evaluation.
+ *
+ * Organization matching prefers explicit `organizationDid` / `organizationUrl`.
+ * When those are absent but an email exists, the email domain is exposed as a
+ * fallback organization target through `did:web:<domain>`.
+ *
+ * @param actor Runtime actor descriptor.
+ */
+export declare function resolveConsentActor(actor: ConsentActorDescriptor): ResolvedConsentActor;
+/**
+ * Returns `true` when a consent rule is currently active.
+ *
+ * A rule is active when:
+ * - it matches the requested subject when one is provided
+ * - `Consent.period-start` is absent or already effective
+ * - `Consent.period-end` is absent or still in the future
+ *
+ * @param rule Consent rule to inspect.
+ * @param options.subject Optional subject filter.
+ * @param options.now Optional evaluation timestamp.
+ */
+export declare function isConsentRuleActive(rule: ConsentRule, options?: {
+    subject?: string;
+    now?: string | Date;
+}): boolean;
+/**
+ * Builds an aggregated active-consent view grouped by target kind.
+ *
+ * @param rules Full consent-rule set available for the subject.
+ * @param options.subject Optional subject filter.
+ * @param options.now Optional evaluation timestamp.
+ */
+export declare function groupActiveConsentsByTarget(rules: ConsentRule[], options?: {
+    subject?: string;
+    now?: string | Date;
+}): ActiveConsentView;
+/**
+ * Evaluates effective consent coverage for a runtime access request.
+ *
+ * Precedence implemented by the shared evaluator:
+ * 1. explicit deny for a concrete email
+ * 2. explicit permit for a concrete email
+ * 3. organization-scoped decisions
+ * 4. jurisdiction-scoped decisions
+ * 5. default deny
+ *
+ * Resource-type evaluation is optional: when a rule does not carry an explicit
+ * resource-type filter, it is treated as section-scoped wildcard coverage.
+ *
+ * @param rules Full consent-rule set available to the caller.
+ * @param request Runtime request to evaluate.
+ */
+export declare function evaluateConsentCoverage(rules: ConsentRule[], request: ConsentCoverageRequest): EffectiveAccessEvaluation;

package/dist/utils/consent.js

@@ -190,3 +190,488 @@ export function buildConsentClaimsSimpleWithCid(input, options = {}) {
         claimsCid: assigned.cid,
     };
 }
+function normalizeJurisdiction(value) {
+    const trimmed = String(value || '').trim();
+    if (!trimmed)
+        return '';
+    if (/^[A-Z]{2}$/i.test(trimmed))
+        return trimmed.toUpperCase();
+    const isoStd = trimmed.match(/^urn:iso:std:iso:3166\|([a-z]{2})$/i);
+    if (isoStd)
+        return isoStd[1].toUpperCase();
+    const iso = trimmed.match(/^urn:iso:3166(?:-2)?:([a-z]{2})(?:[-:].*)?$/i);
+    if (iso)
+        return iso[1].toUpperCase();
+    return trimmed.toUpperCase();
+}
+function normalizeDidWebFromUrl(value) {
+    const raw = String(value || '').trim();
+    if (!raw)
+        return undefined;
+    if (raw.startsWith('did:web:'))
+        return raw.toLowerCase();
+    try {
+        const parsed = raw.includes('://') ? new URL(raw) : new URL(`https://${raw}`);
+        return parsed.hostname ? `did:web:${parsed.hostname.toLowerCase()}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeConsentRoleValue(value) {
+    const trimmed = String(value || '').trim();
+    if (!trimmed || trimmed === '*')
+        return trimmed;
+    const [system, code] = trimmed.includes('|') ? trimmed.split('|', 2) : ['', trimmed];
+    return system
+        ? `${system.trim().toLowerCase()}|${code.trim()}`
+        : trimmed.toLowerCase();
+}
+function splitCsv(value) {
+    return String(value || '')
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function normalizeSectionToken(value) {
+    const trimmed = String(value || '').trim();
+    if (!trimmed || !trimmed.includes('|'))
+        return trimmed;
+    const [system, code] = trimmed.split('|', 2);
+    const normalizedSystem = system
+        .trim()
+        .toLowerCase()
+        .replace(/^https?:\/\/loinc\.org$/i, 'loinc')
+        .replace(/^urn:oid:2\.16\.840\.1\.113883\.6\.1$/i, 'loinc');
+    return `${normalizedSystem}|${code.trim()}`;
+}
+function uniqueTargets(targets) {
+    const seen = new Set();
+    const result = [];
+    for (const target of targets) {
+        const key = `${target.kind}:${target.canonicalValue}:${target.isDirectTarget ? 'd' : ''}${target.isOrganizationTarget ? 'o' : ''}${target.isJurisdictionTarget ? 'j' : ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(target);
+    }
+    return result;
+}
+/**
+ * Normalizes a consent target token into a reusable matching descriptor.
+ *
+ * The helper keeps the current GW contract:
+ * - the first precedence tier is intended for concrete professional email matches
+ * - direct runtime selectors may still include email / `did:web` / phone
+ * - organization targets are normalized to `did:web:<host>`
+ * - jurisdictions resolve to ISO-like uppercase codes
+ * - phone targets stay marked as extension-specific
+ *
+ * @param input Raw target input from a rule or runtime request.
+ * @param options.actorKind Optional actor family hint.
+ * @param options.preferOrganizationDid When true, base `did:web:<host>` values are treated as organization targets.
+ */
+export function normalizeConsentTarget(input, options = {}) {
+    const raw = String(input || '').trim();
+    const parsed = parseConsentActorToken(raw);
+    if (parsed?.kind === 'email') {
+        return {
+            raw,
+            kind: 'email',
+            canonicalValue: parsed.value,
+            isDirectTarget: true,
+            isOrganizationTarget: false,
+            isJurisdictionTarget: false,
+            isPhoneExtension: false,
+        };
+    }
+    if (parsed?.kind === 'phone') {
+        return {
+            raw,
+            kind: 'phone',
+            canonicalValue: parsed.value,
+            isDirectTarget: true,
+            isOrganizationTarget: false,
+            isJurisdictionTarget: false,
+            isPhoneExtension: true,
+        };
+    }
+    if (parsed?.kind === 'country') {
+        return {
+            raw,
+            kind: 'jurisdiction',
+            canonicalValue: parsed.value,
+            isDirectTarget: false,
+            isOrganizationTarget: false,
+            isJurisdictionTarget: true,
+            isPhoneExtension: false,
+        };
+    }
+    const organizationDid = normalizeDidWebFromUrl(raw);
+    const isEmployeeLikeDid = /^did:web:[^:\s]+:(employee|family|relatedperson|related-person):/i.test(raw);
+    if (raw.startsWith('did:')) {
+        const preferOrganizationDid = Boolean(options.preferOrganizationDid && !isEmployeeLikeDid);
+        return {
+            raw,
+            kind: preferOrganizationDid ? 'organization' : 'did',
+            canonicalValue: raw.toLowerCase(),
+            isDirectTarget: !preferOrganizationDid,
+            isOrganizationTarget: preferOrganizationDid,
+            isJurisdictionTarget: false,
+            isPhoneExtension: false,
+        };
+    }
+    if (organizationDid) {
+        return {
+            raw,
+            kind: 'organization',
+            canonicalValue: organizationDid,
+            isDirectTarget: false,
+            isOrganizationTarget: true,
+            isJurisdictionTarget: false,
+            isPhoneExtension: false,
+        };
+    }
+    const jurisdiction = normalizeJurisdiction(raw);
+    if (/^[A-Z]{2}$/.test(jurisdiction)) {
+        return {
+            raw,
+            kind: 'jurisdiction',
+            canonicalValue: jurisdiction,
+            isDirectTarget: false,
+            isOrganizationTarget: false,
+            isJurisdictionTarget: true,
+            isPhoneExtension: false,
+        };
+    }
+    return {
+        raw,
+        kind: 'unknown',
+        canonicalValue: raw,
+        isDirectTarget: false,
+        isOrganizationTarget: false,
+        isJurisdictionTarget: false,
+        isPhoneExtension: false,
+    };
+}
+/**
+ * Resolves all actor match targets used by consent evaluation.
+ *
+ * Organization matching prefers explicit `organizationDid` / `organizationUrl`.
+ * When those are absent but an email exists, the email domain is exposed as a
+ * fallback organization target through `did:web:<domain>`.
+ *
+ * @param actor Runtime actor descriptor.
+ */
+export function resolveConsentActor(actor) {
+    const actorKind = actor.actorKind || 'professional';
+    const directTargets = [];
+    const organizationTargets = [];
+    const jurisdictionTargets = [];
+    const phoneTargets = [];
+    const email = String(actor.email || '').trim();
+    if (email) {
+        const direct = normalizeConsentTarget(email, { actorKind });
+        directTargets.push(direct);
+        const domain = email.includes('@') ? email.split('@')[1] : '';
+        const fallbackOrganizationDid = normalizeDidWebFromUrl(domain);
+        if (fallbackOrganizationDid) {
+            organizationTargets.push(normalizeConsentTarget(fallbackOrganizationDid, {
+                actorKind,
+                preferOrganizationDid: true,
+            }));
+        }
+    }
+    const did = String(actor.did || '').trim();
+    if (did) {
+        directTargets.push(normalizeConsentTarget(did, { actorKind }));
+        const baseOrgDid = did.startsWith('did:web:') ? `did:web:${did.slice('did:web:'.length).split(':')[0]}` : '';
+        if (baseOrgDid) {
+            organizationTargets.push(normalizeConsentTarget(baseOrgDid, {
+                actorKind,
+                preferOrganizationDid: true,
+            }));
+        }
+    }
+    const phone = normalizePhone(String(actor.phone || ''));
+    if (phone) {
+        const phoneTarget = normalizeConsentTarget(`tel:${phone}`, { actorKind });
+        directTargets.push(phoneTarget);
+        phoneTargets.push(phoneTarget);
+    }
+    const orgDid = String(actor.organizationDid || '').trim();
+    if (orgDid) {
+        organizationTargets.push(normalizeConsentTarget(orgDid, {
+            actorKind,
+            preferOrganizationDid: true,
+        }));
+    }
+    const orgUrl = String(actor.organizationUrl || '').trim();
+    if (orgUrl) {
+        const normalized = normalizeDidWebFromUrl(orgUrl);
+        if (normalized) {
+            organizationTargets.push(normalizeConsentTarget(normalized, {
+                actorKind,
+                preferOrganizationDid: true,
+            }));
+        }
+    }
+    const jurisdiction = normalizeJurisdiction(String(actor.jurisdiction || ''));
+    if (jurisdiction) {
+        jurisdictionTargets.push(normalizeConsentTarget(jurisdiction, { actorKind }));
+    }
+    return {
+        actorKind,
+        directTargets: uniqueTargets(directTargets),
+        organizationTargets: uniqueTargets(organizationTargets),
+        jurisdictionTargets: uniqueTargets(jurisdictionTargets),
+        phoneTargets: uniqueTargets(phoneTargets),
+    };
+}
+/**
+ * Returns `true` when a consent rule is currently active.
+ *
+ * A rule is active when:
+ * - it matches the requested subject when one is provided
+ * - `Consent.period-start` is absent or already effective
+ * - `Consent.period-end` is absent or still in the future
+ *
+ * @param rule Consent rule to inspect.
+ * @param options.subject Optional subject filter.
+ * @param options.now Optional evaluation timestamp.
+ */
+export function isConsentRuleActive(rule, options = {}) {
+    if (options.subject && String(rule['Consent.subject'] || '').trim() !== String(options.subject || '').trim()) {
+        return false;
+    }
+    const now = options.now instanceof Date
+        ? options.now.getTime()
+        : options.now
+            ? new Date(options.now).getTime()
+            : Date.now();
+    const periodStart = String(rule['Consent.period-start'] || '').trim();
+    const periodEnd = String(rule['Consent.period-end'] || '').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)
+        return false;
+    return true;
+}
+function groupRulesBy(rules, predicate) {
+    const groups = {};
+    for (const rule of rules) {
+        for (const token of splitCsv(rule['Consent.actor-identifier'])) {
+            const normalized = normalizeConsentTarget(token, { preferOrganizationDid: true });
+            if (!predicate(normalized))
+                continue;
+            groups[normalized.canonicalValue] ||= [];
+            groups[normalized.canonicalValue].push(rule);
+        }
+    }
+    return groups;
+}
+/**
+ * Builds an aggregated active-consent view grouped by target kind.
+ *
+ * @param rules Full consent-rule set available for the subject.
+ * @param options.subject Optional subject filter.
+ * @param options.now Optional evaluation timestamp.
+ */
+export function groupActiveConsentsByTarget(rules, options = {}) {
+    const activeRules = rules.filter((rule) => isConsentRuleActive(rule, options));
+    return {
+        activeRules,
+        byDirectTarget: groupRulesBy(activeRules, (target) => target.isDirectTarget && !target.isPhoneExtension),
+        byOrganizationTarget: groupRulesBy(activeRules, (target) => target.isOrganizationTarget),
+        byJurisdictionTarget: groupRulesBy(activeRules, (target) => target.isJurisdictionTarget),
+        byPhoneTarget: groupRulesBy(activeRules, (target) => target.isPhoneExtension),
+    };
+}
+function normalizeRequestedList(values, wildcard = '*') {
+    const normalized = (values || []).map((value) => String(value || '').trim()).filter(Boolean);
+    return normalized.length ? Array.from(new Set(normalized)) : [wildcard];
+}
+function extractRuleResourceTypes(rule) {
+    const candidates = [
+        rule['Consent.resourceType'],
+        rule['Consent.resource-type'],
+        rule['Consent.resource'],
+        rule['Consent.data-type'],
+    ];
+    for (const candidate of candidates) {
+        const values = splitCsv(candidate);
+        if (values.length > 0)
+            return values;
+    }
+    return [];
+}
+function ruleMatchesRole(rule, actorRole) {
+    const ruleRoles = splitCsv(rule['Consent.actor-role']).map(normalizeConsentRoleValue).filter(Boolean);
+    if (ruleRoles.length === 0 || ruleRoles.includes('*'))
+        return true;
+    const requestedRole = normalizeConsentRoleValue(String(actorRole || ''));
+    return !!requestedRole && ruleRoles.includes(requestedRole);
+}
+function ruleMatchesPurpose(rule, purpose) {
+    const rulePurpose = String(rule['Consent.purpose'] || '').trim();
+    if (!purpose || !rulePurpose)
+        return true;
+    return rulePurpose === purpose;
+}
+function ruleMatchesSection(rule, section) {
+    if (!section || section === '*')
+        return true;
+    const requestedSection = normalizeSectionToken(section);
+    const actions = splitCsv(rule['Consent.action']).map(normalizeSectionToken);
+    if (actions.length === 0)
+        return false;
+    return actions.includes(requestedSection) || actions.includes('*');
+}
+function ruleMatchesResourceType(rule, resourceType) {
+    if (!resourceType || resourceType === '*')
+        return true;
+    const resourceTypes = extractRuleResourceTypes(rule);
+    if (resourceTypes.length === 0)
+        return true;
+    return resourceTypes.includes(resourceType) || resourceTypes.includes('*');
+}
+function resolveRuleMatch(rule, actor) {
+    for (const token of splitCsv(rule['Consent.actor-identifier'])) {
+        const normalized = normalizeConsentTarget(token, { preferOrganizationDid: true });
+        if (actor.directTargets.some((target) => target.canonicalValue === normalized.canonicalValue)) {
+            return { matchKind: 'direct', target: normalized, precedenceBase: 10 };
+        }
+        if (actor.organizationTargets.some((target) => target.canonicalValue === normalized.canonicalValue)) {
+            return { matchKind: 'organization', target: normalized, precedenceBase: 20 };
+        }
+        if (actor.jurisdictionTargets.some((target) => target.canonicalValue === normalized.canonicalValue)) {
+            return { matchKind: 'jurisdiction', target: normalized, precedenceBase: 30 };
+        }
+    }
+    return { matchKind: 'none' };
+}
+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['Consent.decision'];
+    const precedence = resolved.precedenceBase + (decision === 'deny' ? 0 : 1);
+    return {
+        rule,
+        ruleId: String((rule.id) || '').trim() || undefined,
+        decision,
+        matchKind: resolved.matchKind,
+        target: resolved.target,
+        precedence,
+        section: section === '*' ? undefined : section,
+        resourceType: resourceType === '*' ? undefined : resourceType,
+    };
+}
+function emptyMissing() {
+    return { sections: [], resourceTypes: [], pairs: [] };
+}
+/**
+ * Evaluates effective consent coverage for a runtime access request.
+ *
+ * Precedence implemented by the shared evaluator:
+ * 1. explicit deny for a concrete email
+ * 2. explicit permit for a concrete email
+ * 3. organization-scoped decisions
+ * 4. jurisdiction-scoped decisions
+ * 5. default deny
+ *
+ * Resource-type evaluation is optional: when a rule does not carry an explicit
+ * resource-type filter, it is treated as section-scoped wildcard coverage.
+ *
+ * @param rules Full consent-rule set available to the caller.
+ * @param request Runtime request to evaluate.
+ */
+export function evaluateConsentCoverage(rules, request) {
+    const actor = resolveConsentActor(request.actor);
+    const sections = normalizeRequestedList(request.sections);
+    const resourceTypes = normalizeRequestedList(request.resourceTypes);
+    const activeRules = rules.filter((rule) => isConsentRuleActive(rule, {
+        subject: request.subject,
+        now: request.now,
+    }));
+    const matchedRules = [];
+    const winningRules = [];
+    const explicitDenials = [];
+    const allowedSections = new Set();
+    const deniedSections = new Set();
+    const allowedResourceTypes = new Set();
+    const deniedResourceTypes = new Set();
+    const missing = emptyMissing();
+    for (const section of sections) {
+        for (const resourceType of resourceTypes) {
+            const candidates = activeRules
+                .filter((rule) => ruleMatchesRole(rule, request.actorRole)
+                && ruleMatchesPurpose(rule, request.purpose)
+                && ruleMatchesSection(rule, section)
+                && ruleMatchesResourceType(rule, resourceType))
+                .map((rule) => toRuleMatch(rule, actor, section, resourceType))
+                .filter((match) => Boolean(match))
+                .sort((a, b) => a.precedence - b.precedence);
+            matchedRules.push(...candidates);
+            const winner = candidates[0];
+            if (!winner) {
+                missing.pairs.push({
+                    section: section === '*' ? undefined : section,
+                    resourceType: resourceType === '*' ? undefined : resourceType,
+                    reason: 'default-deny-no-active-consent',
+                });
+                if (section !== '*')
+                    missing.sections.push(section);
+                if (resourceType !== '*')
+                    missing.resourceTypes.push(resourceType);
+                if (section !== '*')
+                    deniedSections.add(section);
+                if (resourceType !== '*')
+                    deniedResourceTypes.add(resourceType);
+                continue;
+            }
+            winningRules.push(winner);
+            if (winner.decision === 'deny') {
+                explicitDenials.push(winner);
+                if (section !== '*')
+                    deniedSections.add(section);
+                if (resourceType !== '*')
+                    deniedResourceTypes.add(resourceType);
+                missing.pairs.push({
+                    section: section === '*' ? undefined : section,
+                    resourceType: resourceType === '*' ? undefined : resourceType,
+                    reason: `explicit-${winner.matchKind}-deny`,
+                });
+                if (section !== '*')
+                    missing.sections.push(section);
+                if (resourceType !== '*')
+                    missing.resourceTypes.push(resourceType);
+            }
+            else {
+                if (section !== '*')
+                    allowedSections.add(section);
+                if (resourceType !== '*')
+                    allowedResourceTypes.add(resourceType);
+            }
+        }
+    }
+    return {
+        allowed: missing.pairs.length === 0,
+        denied: missing.pairs.length > 0 && allowedSections.size === 0 && allowedResourceTypes.size === 0,
+        partial: missing.pairs.length > 0 && (allowedSections.size > 0 || allowedResourceTypes.size > 0),
+        subject: request.subject,
+        actor,
+        matchedRules,
+        winningRules,
+        explicitDenials,
+        allowedSections: Array.from(allowedSections),
+        deniedSections: Array.from(deniedSections),
+        allowedResourceTypes: Array.from(allowedResourceTypes),
+        deniedResourceTypes: Array.from(deniedResourceTypes),
+        missing: {
+            sections: Array.from(new Set(missing.sections)),
+            resourceTypes: Array.from(new Set(missing.resourceTypes)),
+            pairs: missing.pairs,
+        },
+    };
+}

package/package.json

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