gdc-common-utils-ts 2.8.5 → 2.8.7

package/README.md

@@ -522,6 +522,12 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - The base token examples are read-only; richer scenario fixtures intentionally add `organization/Consent.cruds`.
 - [`src/examples/related-person.ts`](src/examples/related-person.ts)
   - RelatedPerson/family-member examples.
+- [`buildFhirIpsCreatorProvenance(...)`](src/utils/fhir-ips-creator-identity.ts)
+  and [`docs/101-DIDCOMM-IDENTITY-BOUNDARY.md`](docs/101-DIDCOMM-IDENTITY-BOUNDARY.md)
+  - Keep `Composition.author`, `Composition.attester`, DIDComm sender and
+    signing key separate. A member-created fact may use the registered
+    RelatedPerson as both author and personal attester; a dictated
+    individual-created fact keeps the individual as author.
 - [`src/examples/frontend-session.ts`](src/examples/frontend-session.ts)
   - Frontend profile/session bootstrap examples.
 - [`src/examples/lifecycle.ts`](src/examples/lifecycle.ts)

package/dist/models/confidential-storage.d.ts

@@ -50,6 +50,18 @@ export interface AuditInfo {
     txId?: string;
     /** Transaction timestamp (ISO 8601). */
     txTime?: string;
+    /** Stable semantic creator resolved from authenticated clinical identity. */
+    creatorDid?: string;
+    /** Authenticated transport actor when different from the source author. */
+    submitterDid?: string;
+    /** Verified DCR/JWS signing key used by the submitting channel. */
+    signingKeyId?: string;
+    /** Organization or subject that owns the source author's role/relationship. */
+    authorOwnerIdentifier?: string;
+    /** Source Composition.date used for strictly-later successor decisions. */
+    documentDate?: string;
+    /** Source record linked to a derived confidential projection. */
+    sourceRecordId?: string;
 }
 /**
  * Public runtime projection kept outside encrypted `content`.

package/dist/models/interoperable-claims/composition-claims.d.ts

@@ -16,4 +16,12 @@ export declare const CompositionClaim: {
     readonly Identifier: "Composition.identifier";
     readonly Title: "Composition.title";
 };
+/** Canonical FHIR R4 Composition.attester.mode codes. */
+export declare const CompositionAttesterModes: Readonly<{
+    readonly Personal: "personal";
+    readonly Professional: "professional";
+    readonly Legal: "legal";
+    readonly Official: "official";
+}>;
+export type CompositionAttesterMode = typeof CompositionAttesterModes[keyof typeof CompositionAttesterModes];
 export type CompositionClaimKey = typeof CompositionClaim[keyof typeof CompositionClaim];

package/dist/models/interoperable-claims/composition-claims.js

@@ -18,3 +18,10 @@ export const CompositionClaim = {
     Identifier: 'Composition.identifier',
     Title: 'Composition.title',
 };
+/** Canonical FHIR R4 Composition.attester.mode codes. */
+export const CompositionAttesterModes = Object.freeze({
+    Personal: 'personal',
+    Professional: 'professional',
+    Legal: 'legal',
+    Official: 'official',
+});

package/dist/utils/confidential-document-provenance.d.ts

@@ -0,0 +1,26 @@
+import type { AuditInfo, IndexedAttribute } from '../models/confidential-storage.js';
+export declare const ConfidentialDocumentIndex: Readonly<{
+    readonly Sector: "sector";
+    readonly CreatorDid: "audit.creatorDid";
+    readonly SubmitterDid: "audit.submitterDid";
+    readonly SigningKeyId: "audit.signingKeyId";
+}>;
+/** Flat Composition claims whose string value is a positional or set-like CSV projection. */
+export declare const CompositionCsvClaimKeys: readonly ["Composition.author", "Composition.attester", "Composition.attester-mode", "Composition.attester-time", "Composition.section", "Composition.entry"];
+export type ConfidentialDocumentProvenanceAudit = Pick<AuditInfo, 'creatorDid' | 'submitterDid' | 'signingKeyId'>;
+export type ConfidentialDocumentIndexedAttributesInput = Readonly<{
+    claims: Readonly<Record<string, unknown>>;
+    sector?: string;
+    audit?: ConfidentialDocumentProvenanceAudit;
+    /**
+     * Temporarily retain the former whole-CSV attribute so exact legacy queries
+     * continue to match while consumers move to one attribute per value.
+     */
+    includeDeprecatedCsvAggregate?: boolean;
+}>;
+/**
+ * Projects searchable metadata without changing the protected canonical
+ * claims. CSV multiplicity is governed by `CompositionCsvClaimKeys`; arbitrary
+ * text containing commas is never split.
+ */
+export declare function buildConfidentialDocumentIndexedAttributes(input: ConfidentialDocumentIndexedAttributesInput): IndexedAttribute[];

package/dist/utils/confidential-document-provenance.js

@@ -0,0 +1,68 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { CompositionClaim } from '../models/interoperable-claims/composition-claims.js';
+export const ConfidentialDocumentIndex = Object.freeze({
+    Sector: 'sector',
+    CreatorDid: 'audit.creatorDid',
+    SubmitterDid: 'audit.submitterDid',
+    SigningKeyId: 'audit.signingKeyId',
+});
+/** Flat Composition claims whose string value is a positional or set-like CSV projection. */
+export const CompositionCsvClaimKeys = Object.freeze([
+    CompositionClaim.Author,
+    CompositionClaim.Attester,
+    CompositionClaim.AttesterMode,
+    CompositionClaim.AttesterTime,
+    CompositionClaim.Section,
+    CompositionClaim.Entry,
+]);
+const CSV_CLAIMS = new Set(CompositionCsvClaimKeys);
+const COMPOSITION_CLAIMS = new Set(Object.values(CompositionClaim));
+function canonicalCompositionClaimName(name) {
+    return [...COMPOSITION_CLAIMS].find((claimName) => name === claimName || name.endsWith(`.${claimName}`));
+}
+/**
+ * Projects searchable metadata without changing the protected canonical
+ * claims. CSV multiplicity is governed by `CompositionCsvClaimKeys`; arbitrary
+ * text containing commas is never split.
+ */
+export function buildConfidentialDocumentIndexedAttributes(input) {
+    const attributes = [];
+    const includeDeprecatedAggregate = input.includeDeprecatedCsvAggregate !== false;
+    const append = (name, value, unique) => {
+        const normalized = String(value ?? '').trim();
+        if (!normalized)
+            return;
+        if (attributes.some((attribute) => attribute.name === name && attribute.value === normalized))
+            return;
+        attributes.push({ name, value: normalized, ...(unique ? { unique: true } : {}) });
+    };
+    append(ConfidentialDocumentIndex.Sector, input.sector);
+    append(ConfidentialDocumentIndex.CreatorDid, input.audit?.creatorDid);
+    append(ConfidentialDocumentIndex.SubmitterDid, input.audit?.submitterDid);
+    append(ConfidentialDocumentIndex.SigningKeyId, input.audit?.signingKeyId);
+    for (const [name, rawValue] of Object.entries(input.claims)) {
+        if (name === '@context' || name === '@type' || rawValue === undefined || rawValue === null || Array.isArray(rawValue)) {
+            continue;
+        }
+        const value = String(rawValue).trim();
+        if (!value)
+            continue;
+        const canonicalCompositionName = canonicalCompositionClaimName(name);
+        const indexedName = canonicalCompositionName || name;
+        if (CSV_CLAIMS.has(indexedName)) {
+            const values = value.split(',').map((item) => item.trim()).filter(Boolean);
+            values.forEach((item) => append(indexedName, item));
+            if (includeDeprecatedAggregate && values.length > 1)
+                append(indexedName, value);
+            if (name !== indexedName)
+                append(name, value);
+            continue;
+        }
+        const isUniqueResourceIdentifier = !canonicalCompositionName
+            && (name.endsWith('.identifier') || name.endsWith('.identifier.value'));
+        append(indexedName, value, isUniqueResourceIdentifier);
+        if (name !== indexedName)
+            append(name, value);
+    }
+    return attributes;
+}

package/dist/utils/did.d.ts

@@ -70,6 +70,21 @@ export declare function createHostedDidWeb(hostDidWeb: string, tenantId: string,
  * used by the hosted organization form.
  */
 export declare function extractTenantIdFromHostedDidWeb(did: string): string | undefined;
+/**
+ * Builds the canonical hosted organization DID from the official identifier
+ * vocabulary governed by the selected data space.
+ *
+ * The identifier type is a path token such as `taxID`, `VAT`, or `BN`; this
+ * helper normalizes only that token and never guesses a type by parsing the
+ * identifier value. The corresponding FHIR Organization must retain the same
+ * type and value in `Organization.identifier`.
+ */
+export declare function buildHostedOrganizationDidWeb(input: {
+    hostDomain: string;
+    sector: string;
+    officialIdentifierType: string;
+    officialIdentifierValue: string;
+}): string;
 /**
  * Builds the canonical hosted provider DID root used by hosted tenant services.
  *

package/dist/utils/did.js

@@ -150,6 +150,32 @@ export function extractTenantIdFromHostedDidWeb(did) {
     }
     return decodeURIComponent(tenantId);
 }
+/**
+ * Builds the canonical hosted organization DID from the official identifier
+ * vocabulary governed by the selected data space.
+ *
+ * The identifier type is a path token such as `taxID`, `VAT`, or `BN`; this
+ * helper normalizes only that token and never guesses a type by parsing the
+ * identifier value. The corresponding FHIR Organization must retain the same
+ * type and value in `Organization.identifier`.
+ */
+export function buildHostedOrganizationDidWeb(input) {
+    const hostDomain = String(input.hostDomain || '').trim().toLowerCase();
+    const sector = String(input.sector || '').trim().toLowerCase();
+    const identifierType = String(input.officialIdentifierType || '').trim().toLowerCase();
+    const identifierValue = String(input.officialIdentifierValue || '').trim();
+    if (!hostDomain)
+        throw new Error('buildHostedOrganizationDidWeb requires hostDomain.');
+    if (!sector)
+        throw new Error('buildHostedOrganizationDidWeb requires sector.');
+    if (!/^[a-z][a-z0-9._-]*$/.test(identifierType)) {
+        throw new Error('buildHostedOrganizationDidWeb requires a canonical officialIdentifierType path token.');
+    }
+    if (!identifierValue || /[:/\s]/.test(identifierValue)) {
+        throw new Error('buildHostedOrganizationDidWeb requires one DID-path-safe officialIdentifierValue.');
+    }
+    return `did:web:${hostDomain}:${sector}:organization:${identifierType}:${identifierValue}`;
+}
 /**
  * Builds the canonical hosted provider DID root used by hosted tenant services.
  *
@@ -170,7 +196,12 @@ export function buildHostedProviderDidWeb(input) {
         throw new Error('buildHostedProviderDidWeb requires sector.');
     if (!providerTaxId)
         throw new Error('buildHostedProviderDidWeb requires providerTaxId.');
-    return `did:web:${hostDomain}:${sector}:organization:taxid:${providerTaxId}`;
+    return buildHostedOrganizationDidWeb({
+        hostDomain,
+        sector,
+        officialIdentifierType: 'taxid',
+        officialIdentifierValue: providerTaxId,
+    });
 }
 /**
  * Builds the canonical public provider DID root used by an external provider domain.

package/dist/utils/fhir-ips-creator-identity.d.ts

@@ -1,3 +1,4 @@
+import { type CompositionAttesterMode } from '../models/interoperable-claims/composition-claims.js';
 export declare const FhirIpsCreatorKinds: Readonly<{
     readonly IndividualSubject: "individual-subject";
     readonly IndividualMember: "individual-member";
@@ -30,6 +31,42 @@ export type FhirIpsCreatorAuthor = Readonly<{
     authorReference: string;
     entries: readonly FhirIpsCreatorBundleEntry[];
 }>;
+export type FhirIpsCreatorProvenanceInput = FhirIpsCreatorAuthorInput & Readonly<{
+    /**
+     * Explicit source originator. Defaults to the owning organization or
+     * individual. When the authenticated member/professional actually authored
+     * the content, pass its registered RelatedPerson/PractitionerRole assignment
+     * reference; that same assignment may also remain the attester.
+     */
+    compositionAuthorReference?: string;
+    /** Defaults to professional for employees and personal for individual members. */
+    attesterMode?: CompositionAttesterMode;
+    /** Optional FHIR instant copied to Composition.attester.time. */
+    attestedAt?: string;
+}>;
+export type FhirIpsCreatorProvenance = Readonly<{
+    authorReference: string;
+    attesters: readonly Readonly<{
+        mode: CompositionAttesterMode;
+        party: Readonly<{
+            reference: string;
+        }>;
+        time?: string;
+    }>[];
+    entries: readonly FhirIpsCreatorBundleEntry[];
+}>;
+/**
+ * Builds source authorship separately from the person or role that attests it.
+ *
+ * Defaults model delegated flows: an organization's professional attests an
+ * organization-authored record, while a member/caregiver attests a
+ * subject-authored record. For content actually created by that authenticated
+ * member or professional, set `compositionAuthorReference` to its registered
+ * RelatedPerson or PractitionerRole assignment. Author and attester may then
+ * intentionally reference the same assignment; neither is the transport
+ * sender or signing key.
+ */
+export declare function buildFhirIpsCreatorProvenance(input: FhirIpsCreatorProvenanceInput): FhirIpsCreatorProvenance;
 /**
  * Builds the ordinary FHIR R4 resources referenced by an IPS
  * `Composition.author`.
@@ -39,6 +76,10 @@ export type FhirIpsCreatorAuthor = Readonly<{
  * ONESELF references the existing Patient/subject entry. A professional
  * references PractitionerRole while retaining the underlying Practitioner.
  * An individual member references RelatedPerson.
+ *
+ * @deprecated Use `buildFhirIpsCreatorProvenance` so Composition.author and
+ * Composition.attester remain separate. This compatibility helper preserves
+ * its historical role-as-author result.
  */
 export declare function buildFhirIpsCreatorAuthor(input: FhirIpsCreatorAuthorInput): FhirIpsCreatorAuthor;
 type ClinicalCreatorChannelAliases = Readonly<{

package/dist/utils/fhir-ips-creator-identity.js

@@ -2,11 +2,48 @@
 import { getHealthcareRoleByClaim } from '../constants/healthcare.js';
 import { isStableActorIdentifier } from './actor-identifier.js';
 import { normalizeUuid } from './normalize-uuid.js';
+import { CompositionAttesterModes, } from '../models/interoperable-claims/composition-claims.js';
 export const FhirIpsCreatorKinds = Object.freeze({
     IndividualSubject: 'individual-subject',
     IndividualMember: 'individual-member',
     Professional: 'professional',
 });
+/**
+ * Builds source authorship separately from the person or role that attests it.
+ *
+ * Defaults model delegated flows: an organization's professional attests an
+ * organization-authored record, while a member/caregiver attests a
+ * subject-authored record. For content actually created by that authenticated
+ * member or professional, set `compositionAuthorReference` to its registered
+ * RelatedPerson or PractitionerRole assignment. Author and attester may then
+ * intentionally reference the same assignment; neither is the transport
+ * sender or signing key.
+ */
+export function buildFhirIpsCreatorProvenance(input) {
+    if (input.kind === FhirIpsCreatorKinds.IndividualSubject) {
+        return {
+            authorReference: requireReference(input.compositionAuthorReference || input.subjectReference, 'compositionAuthorReference'),
+            attesters: [],
+            entries: [],
+        };
+    }
+    const creator = buildFhirIpsCreatorAuthor(input);
+    const defaultAuthor = input.kind === FhirIpsCreatorKinds.Professional
+        ? input.organizationReference
+        : input.subjectReference;
+    const mode = input.attesterMode || (input.kind === FhirIpsCreatorKinds.Professional
+        ? CompositionAttesterModes.Professional
+        : CompositionAttesterModes.Personal);
+    return {
+        authorReference: requireReference(input.compositionAuthorReference || defaultAuthor, 'compositionAuthorReference'),
+        attesters: [{
+                mode,
+                party: { reference: creator.authorReference },
+                ...(input.attestedAt ? { time: input.attestedAt } : {}),
+            }],
+        entries: creator.entries,
+    };
+}
 /**
  * Builds the ordinary FHIR R4 resources referenced by an IPS
  * `Composition.author`.
@@ -16,6 +53,10 @@ export const FhirIpsCreatorKinds = Object.freeze({
  * ONESELF references the existing Patient/subject entry. A professional
  * references PractitionerRole while retaining the underlying Practitioner.
  * An individual member references RelatedPerson.
+ *
+ * @deprecated Use `buildFhirIpsCreatorProvenance` so Composition.author and
+ * Composition.attester remain separate. This compatibility helper preserves
+ * its historical role-as-author result.
  */
 export function buildFhirIpsCreatorAuthor(input) {
     const actorIdentifier = requireUuidUrn(input.actorIdentifier, 'actorIdentifier');
@@ -29,7 +70,7 @@ export function buildFhirIpsCreatorAuthor(input) {
     }
     const role = requireRoleCoding(input.role);
     if (input.kind === FhirIpsCreatorKinds.IndividualMember) {
-        const subjectReference = requireUuidUrn(input.subjectReference, 'subjectReference');
+        const subjectReference = requireReference(input.subjectReference, 'subjectReference');
         return {
             authorReference: authorIdentifier,
             entries: [{

package/dist/utils/index.d.ts

@@ -52,6 +52,7 @@ export * from './bundle-didcomm-payload';
 export * from './communication-didcomm-payload';
 export * from './confidential-storage-persistence';
 export * from './confidential-storage-test-data';
+export * from './confidential-document-provenance';
 export * from './permission-templates';
 export * from './client-assertion';
 export * from './professional-smart';

package/dist/utils/index.js

@@ -52,6 +52,7 @@ export * from './bundle-didcomm-payload.js';
 export * from './communication-didcomm-payload.js';
 export * from './confidential-storage-persistence.js';
 export * from './confidential-storage-test-data.js';
+export * from './confidential-document-provenance.js';
 export * from './permission-templates.js';
 export * from './client-assertion.js';
 export * from './professional-smart.js';

package/package.json

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