gdc-common-utils-ts 1.7.0 → 1.9.0

package/README.md

@@ -131,6 +131,8 @@ The canonical API contract should live in JSDoc on exported code. The README act
 ### Communication / document utilities
 
 - [`initializeCommunicationIdentity(...)`](src/utils/communication-identity.ts)
+  - bootstraps the technical communication profile identity for a device/app/channel runtime
+  - do not teach its `entityId` as if it were the legal organization id
   - Derives the technical ML-DSA/ML-KEM communication identity for a device, portal, or app profile and returns JOSE header templates for `meta.jws.protected` and `meta.jwe.header`.
   - Uses explicit `seedMaterial` for deterministic derivation. Without `seedMaterial`, it defaults to random generation. `mode = deterministic` requires `seedMaterial`.
 - [`buildOrganizationDidWeb(...)`, `buildProfessionalDidWeb(...)`, `buildIndividualDidWeb(...)`](src/utils/did.ts)
@@ -208,7 +210,7 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - Shared route contexts, controller binding fragments, and reusable helper builders.
   - `tenantId` is modeled as an identifier-like route token (`acme-id`), not as a friendly alternate name.
 - [`docs/LIFECYCLE_101.md`](docs/LIFECYCLE_101.md)
-  - Copy/paste lifecycle guide "for torpes" with semantic rules and reusable placeholders.
+  - Copy/paste lifecycle `101` guide with semantic rules and reusable placeholders.
 
 ## Documentation Naming Rules
 

package/dist/constants/actor-session.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Canonical actor-kind vocabulary shared across SDK packages.
+ */
+export declare const ActorKinds: Readonly<{
+    readonly HostOnboarding: "host_onboarding";
+    readonly OrganizationController: "organization_controller";
+    readonly OrganizationEmployee: "organization_employee";
+    readonly IndividualController: "individual_controller";
+    readonly IndividualMember: "individual_member";
+    readonly Professional: "professional";
+}>;
+/**
+ * Canonical capability vocabulary shared across SDK packages.
+ */
+export declare const ActorCapabilities: Readonly<{
+    readonly HostActivateOrganization: "host.activate_organization";
+    readonly HostConfirmOrder: "host.confirm_order";
+    readonly OrganizationCreateEmployee: "organization.create_employee";
+    readonly OrganizationDisableEmployee: "organization.disable_employee";
+    readonly OrganizationPurgeEmployee: "organization.purge_employee";
+    readonly OrganizationActivateDevice: "organization.activate_device";
+    readonly OrganizationIssueActivationCode: "organization.issue_activation_code";
+    readonly OrganizationRequestSmartToken: "organization.request_smart_token";
+    readonly IndividualBootstrap: "individual.bootstrap";
+    readonly IndividualDisable: "individual.disable";
+    readonly IndividualPurge: "individual.purge";
+    readonly IndividualImportIps: "individual.import_ips";
+    readonly IndividualGenerateDigitalTwin: "individual.generate_digital_twin";
+    readonly IndividualIngestCommunication: "individual.ingest_communication";
+    readonly IndividualUpsertRelatedPerson: "individual.upsert_related_person";
+    readonly IndividualMemberDisable: "individual_member.disable";
+    readonly IndividualMemberPurge: "individual_member.purge";
+    readonly ConsentGrantProfessionalAccess: "consent.grant_professional_access";
+    readonly ProfessionalMedication: "professional.medication";
+    readonly ProfessionalAppointment: "professional.appointment";
+    readonly ProfessionalRequestSmartToken: "professional.request_smart_token";
+    readonly TokenRequestSmart: "token.request_smart";
+}>;
+export type ActorKindsValue = typeof ActorKinds[keyof typeof ActorKinds];
+export type ActorCapabilitiesValue = typeof ActorCapabilities[keyof typeof ActorCapabilities];

package/dist/constants/actor-session.js

@@ -0,0 +1,40 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+/**
+ * Canonical actor-kind vocabulary shared across SDK packages.
+ */
+export const ActorKinds = Object.freeze({
+    HostOnboarding: 'host_onboarding',
+    OrganizationController: 'organization_controller',
+    OrganizationEmployee: 'organization_employee',
+    IndividualController: 'individual_controller',
+    IndividualMember: 'individual_member',
+    Professional: 'professional',
+});
+/**
+ * Canonical capability vocabulary shared across SDK packages.
+ */
+export const ActorCapabilities = Object.freeze({
+    HostActivateOrganization: 'host.activate_organization',
+    HostConfirmOrder: 'host.confirm_order',
+    OrganizationCreateEmployee: 'organization.create_employee',
+    OrganizationDisableEmployee: 'organization.disable_employee',
+    OrganizationPurgeEmployee: 'organization.purge_employee',
+    OrganizationActivateDevice: 'organization.activate_device',
+    OrganizationIssueActivationCode: 'organization.issue_activation_code',
+    OrganizationRequestSmartToken: 'organization.request_smart_token',
+    IndividualBootstrap: 'individual.bootstrap',
+    IndividualDisable: 'individual.disable',
+    IndividualPurge: 'individual.purge',
+    IndividualImportIps: 'individual.import_ips',
+    IndividualGenerateDigitalTwin: 'individual.generate_digital_twin',
+    IndividualIngestCommunication: 'individual.ingest_communication',
+    IndividualUpsertRelatedPerson: 'individual.upsert_related_person',
+    IndividualMemberDisable: 'individual_member.disable',
+    IndividualMemberPurge: 'individual_member.purge',
+    ConsentGrantProfessionalAccess: 'consent.grant_professional_access',
+    ProfessionalMedication: 'professional.medication',
+    ProfessionalAppointment: 'professional.appointment',
+    ProfessionalRequestSmartToken: 'professional.request_smart_token',
+    TokenRequestSmart: 'token.request_smart',
+});

package/dist/constants/index.d.ts

@@ -1,3 +1,4 @@
+export * from './actor-session';
 export * from './communication';
 export * from './cryptography';
 export * from './device';

package/dist/constants/index.js

@@ -1,3 +1,4 @@
+export * from './actor-session.js';
 export * from './communication.js';
 export * from './cryptography.js';
 export * from './device.js';

package/dist/constants/schemaorg.d.ts

@@ -139,3 +139,8 @@ export declare enum ICAOIdentityParams {
 }
 export declare const indexedPersonAttributeList: string[];
 export declare const fullPersonParamsSchemaorg: ParameterData[];
+/**
+ * Canonical schema.org `Service` flat claims commonly used by GW tenant and
+ * individual onboarding flows.
+ */
+export declare const fullServiceParamsSchemaorg: ParameterData[];

package/dist/constants/schemaorg.js

@@ -224,3 +224,35 @@ export const fullPersonParamsSchemaorg = [
     },
     */
 ];
+/**
+ * Canonical schema.org `Service` flat claims commonly used by GW tenant and
+ * individual onboarding flows.
+ */
+export const fullServiceParamsSchemaorg = [
+    {
+        name: ClaimsServiceSchemaorg.category,
+        type: 'token',
+        value: undefined,
+    },
+    {
+        name: ClaimsServiceSchemaorg.identifier,
+        type: 'uri',
+        value: undefined,
+        unique: true,
+    },
+    {
+        name: ClaimsServiceSchemaorg.serviceType,
+        type: 'token',
+        value: undefined,
+    },
+    {
+        name: ClaimsServiceSchemaorg.termsOfService,
+        type: 'uri',
+        value: undefined,
+    },
+    {
+        name: ClaimsServiceSchemaorg.url,
+        type: 'uri',
+        value: undefined,
+    },
+];

package/dist/models/actor-session.d.ts

@@ -0,0 +1,9 @@
+import type { ActorCapabilitiesValue, ActorKindsValue } from '../constants/actor-session';
+/**
+ * Canonical actor kind shared across SDK packages.
+ */
+export type ActorKind = ActorKindsValue;
+/**
+ * Canonical capability token shared across SDK packages.
+ */
+export type Capability = ActorCapabilitiesValue;

package/dist/models/actor-session.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+export {};

package/dist/models/did.d.ts

@@ -1,6 +1,8 @@
 import { PublicJwk } from "../interfaces/Cryptography.types";
 import { RecipientPublicKey } from "./crypto";
 import { JwkSet } from "./jwk";
+import type { ActorKind } from "./actor-session";
+export type { ActorKind } from "./actor-session";
 /**
  * The parameters required to construct a service endpoint selector.
  * This is the contract for a specific API method to define its endpoint.
@@ -71,7 +73,6 @@ export interface VerificationMethod extends RecipientPublicKey {
     controller: string;
     publicKeyJwk: PublicJwk;
 }
-export type ActorKind = 'host_onboarding' | 'organization_controller' | 'organization_employee' | 'individual_controller' | 'individual_member' | 'professional';
 export interface ResolvedServiceEndpoint {
     id: string;
     type: string;

package/dist/models/fhir-related-person.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Canonical flat-claim constants for FHIR `RelatedPerson`.
+ *
+ * @architecture 101
+ * - Use exported constants instead of inline claim-name literals.
+ * - `ClaimsContextFhirRelatedPerson` models the stable business/search contract.
+ * - `RelatedPerson.patient` is kept as a transport/storage compatibility alias for
+ *   existing R4 payloads, while `RelatedPerson.subject` remains the shared SDK name.
+ */
+import type { SearchParameterCatalog } from './params';
+/**
+ * Canonical interoperable claims for `RelatedPerson`.
+ *
+ * The enum follows the established `ResourceType.parameter` shape used by the
+ * rest of the flat FHIR claims model.
+ */
+export declare enum ClaimsContextFhirRelatedPerson {
+    Identifier = "RelatedPerson.identifier",
+    Subject = "RelatedPerson.subject",
+    Relationship = "RelatedPerson.relationship",
+    Name = "RelatedPerson.name",
+    Email = "RelatedPerson.email",
+    Phone = "RelatedPerson.phone"
+}
+/**
+ * Legacy FHIR R4 field name still present in examples and existing stored data.
+ *
+ * New shared code should normalize from this alias into
+ * `ClaimsContextFhirRelatedPerson.Subject` when projecting business DTOs.
+ */
+export declare const FHIR_RELATED_PERSON_PATIENT_CLAIM: "RelatedPerson.patient";
+/**
+ * Legacy telecom alias preserved for older ingestion payloads.
+ */
+export declare const FHIR_RELATED_PERSON_TELECOM_CLAIM: "RelatedPerson.telecom";
+/**
+ * Optional lifecycle/status claim used by projections when present.
+ */
+export declare const FHIR_RELATED_PERSON_STATUS_CLAIM: "RelatedPerson.status";
+/**
+ * Public search parameter names exposed for `RelatedPerson`.
+ *
+ * These names are independent from the underlying flat claim keys and are the
+ * right source for client-side search UIs and future `CapabilityStatement`
+ * generation.
+ */
+export declare enum RelatedPersonSearchParameterName {
+    Identifier = "identifier",
+    Subject = "subject",
+    Relationship = "relationship",
+    Name = "name",
+    Email = "email",
+    Phone = "phone"
+}
+/**
+ * Shared searchable/indexable parameter catalog for `RelatedPerson`.
+ *
+ * `name` is the canonical flat claim key to index/query. The record key is the
+ * public search-attribute name.
+ */
+export declare const relatedPersonSearchParameterCatalog: SearchParameterCatalog<RelatedPersonSearchParameterName>;

package/dist/models/fhir-related-person.js

@@ -0,0 +1,108 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * @fileoverview Canonical flat-claim constants for FHIR `RelatedPerson`.
+ *
+ * @architecture 101
+ * - Use exported constants instead of inline claim-name literals.
+ * - `ClaimsContextFhirRelatedPerson` models the stable business/search contract.
+ * - `RelatedPerson.patient` is kept as a transport/storage compatibility alias for
+ *   existing R4 payloads, while `RelatedPerson.subject` remains the shared SDK name.
+ */
+/**
+ * Canonical interoperable claims for `RelatedPerson`.
+ *
+ * The enum follows the established `ResourceType.parameter` shape used by the
+ * rest of the flat FHIR claims model.
+ */
+export var ClaimsContextFhirRelatedPerson;
+(function (ClaimsContextFhirRelatedPerson) {
+    ClaimsContextFhirRelatedPerson["Identifier"] = "RelatedPerson.identifier";
+    ClaimsContextFhirRelatedPerson["Subject"] = "RelatedPerson.subject";
+    ClaimsContextFhirRelatedPerson["Relationship"] = "RelatedPerson.relationship";
+    ClaimsContextFhirRelatedPerson["Name"] = "RelatedPerson.name";
+    ClaimsContextFhirRelatedPerson["Email"] = "RelatedPerson.email";
+    ClaimsContextFhirRelatedPerson["Phone"] = "RelatedPerson.phone";
+})(ClaimsContextFhirRelatedPerson || (ClaimsContextFhirRelatedPerson = {}));
+/**
+ * Legacy FHIR R4 field name still present in examples and existing stored data.
+ *
+ * New shared code should normalize from this alias into
+ * `ClaimsContextFhirRelatedPerson.Subject` when projecting business DTOs.
+ */
+export const FHIR_RELATED_PERSON_PATIENT_CLAIM = 'RelatedPerson.patient';
+/**
+ * Legacy telecom alias preserved for older ingestion payloads.
+ */
+export const FHIR_RELATED_PERSON_TELECOM_CLAIM = 'RelatedPerson.telecom';
+/**
+ * Optional lifecycle/status claim used by projections when present.
+ */
+export const FHIR_RELATED_PERSON_STATUS_CLAIM = 'RelatedPerson.status';
+/**
+ * Public search parameter names exposed for `RelatedPerson`.
+ *
+ * These names are independent from the underlying flat claim keys and are the
+ * right source for client-side search UIs and future `CapabilityStatement`
+ * generation.
+ */
+export var RelatedPersonSearchParameterName;
+(function (RelatedPersonSearchParameterName) {
+    RelatedPersonSearchParameterName["Identifier"] = "identifier";
+    RelatedPersonSearchParameterName["Subject"] = "subject";
+    RelatedPersonSearchParameterName["Relationship"] = "relationship";
+    RelatedPersonSearchParameterName["Name"] = "name";
+    RelatedPersonSearchParameterName["Email"] = "email";
+    RelatedPersonSearchParameterName["Phone"] = "phone";
+})(RelatedPersonSearchParameterName || (RelatedPersonSearchParameterName = {}));
+/**
+ * Shared searchable/indexable parameter catalog for `RelatedPerson`.
+ *
+ * `name` is the canonical flat claim key to index/query. The record key is the
+ * public search-attribute name.
+ */
+export const relatedPersonSearchParameterCatalog = {
+    [RelatedPersonSearchParameterName.Identifier]: {
+        name: ClaimsContextFhirRelatedPerson.Identifier,
+        type: 'token',
+        value: undefined,
+        indexed: true,
+        appliesTo: ['RelatedPerson'],
+    },
+    [RelatedPersonSearchParameterName.Subject]: {
+        name: ClaimsContextFhirRelatedPerson.Subject,
+        type: 'reference',
+        value: undefined,
+        indexed: true,
+        claimAliases: [FHIR_RELATED_PERSON_PATIENT_CLAIM],
+        appliesTo: ['RelatedPerson'],
+    },
+    [RelatedPersonSearchParameterName.Relationship]: {
+        name: ClaimsContextFhirRelatedPerson.Relationship,
+        type: 'token',
+        value: undefined,
+        indexed: true,
+        appliesTo: ['RelatedPerson'],
+    },
+    [RelatedPersonSearchParameterName.Name]: {
+        name: ClaimsContextFhirRelatedPerson.Name,
+        type: 'string',
+        value: undefined,
+        indexed: true,
+        appliesTo: ['RelatedPerson'],
+    },
+    [RelatedPersonSearchParameterName.Email]: {
+        name: ClaimsContextFhirRelatedPerson.Email,
+        type: 'token',
+        value: undefined,
+        indexed: true,
+        appliesTo: ['RelatedPerson'],
+    },
+    [RelatedPersonSearchParameterName.Phone]: {
+        name: ClaimsContextFhirRelatedPerson.Phone,
+        type: 'token',
+        value: undefined,
+        indexed: true,
+        claimAliases: [FHIR_RELATED_PERSON_TELECOM_CLAIM],
+        appliesTo: ['RelatedPerson'],
+    },
+};

package/dist/models/index.d.ts

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview Barrel export for shared model contracts.
+ *
+ * @architecture 101
+ * Keep this file export-only; shared business logic belongs in dedicated modules.
+ */
+export * from './actor-session';
 export * from './aes';
 export * from './auth';
 export * from './bundle';
@@ -14,6 +21,7 @@ export * from './crypto';
 export * from './device-license';
 export * from './did';
 export * from './fhir-documents';
+export * from './fhir-related-person';
 export * from './interoperable-claims';
 export * from './indexing';
 export * from './identity-bootstrap';
@@ -33,6 +41,7 @@ export * from './operation-outcome';
 export * from './params';
 export * from './resource-document';
 export * from './relationship-access';
+export * from './related-profile';
 export * from './response';
 export * from './urlPath';
 export * from './verifiable-credential';

package/dist/models/index.js

@@ -1,3 +1,11 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * @fileoverview Barrel export for shared model contracts.
+ *
+ * @architecture 101
+ * Keep this file export-only; shared business logic belongs in dedicated modules.
+ */
+export * from './actor-session.js';
 export * from './aes.js';
 export * from './auth.js';
 export * from './bundle.js';
@@ -14,6 +22,7 @@ export * from './crypto.js';
 export * from './device-license.js';
 export * from './did.js';
 export * from './fhir-documents.js';
+export * from './fhir-related-person.js';
 export * from './interoperable-claims.js';
 export * from './indexing.js';
 export * from './identity-bootstrap.js';
@@ -33,6 +42,7 @@ export * from './operation-outcome.js';
 export * from './params.js';
 export * from './resource-document.js';
 export * from './relationship-access.js';
+export * from './related-profile.js';
 export * from './response.js';
 export * from './urlPath.js';
 export * from './verifiable-credential.js';

package/dist/models/params.d.ts

@@ -95,6 +95,31 @@ export interface ParameterData extends ParamAttribute {
      */
     appliesTo?: string[];
 }
+/**
+ * Shared definition for a search parameter that can also be used as an
+ * indexable attribute contract.
+ *
+ * `name` remains the canonical flat claim key that will be stored and queried.
+ * The record key in a `SearchParameterCatalog` is the public search-attribute
+ * name to expose in APIs or capability statements.
+ */
+export interface SearchParameterDefinition extends ParameterData {
+    /**
+     * Optional compatibility aliases accepted on read/normalization before the
+     * canonical `name` is used for indexing.
+     */
+    claimAliases?: readonly string[];
+    /**
+     * Whether this parameter is intended to be indexed for blind queries.
+     * Defaults to `true` when omitted by catalog consumers.
+     */
+    indexed?: boolean;
+}
+/**
+ * Per-resource search parameter catalog keyed by the public search attribute
+ * name (e.g. `identifier`, `subject`, `status`).
+ */
+export type SearchParameterCatalog<TSearchName extends string = string> = Record<TSearchName, SearchParameterDefinition>;
 export interface StringSearchParameter extends ParameterData {
     type: 'string';
     value: string;

package/dist/models/params.js

@@ -1,3 +1,2 @@
 // Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
-// File: crypto-ts/models/params.ts
 export {};

package/dist/models/related-profile.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Shared DTOs for portal/BFF `related profiles` projections.
+ *
+ * @architecture 101
+ * - These DTOs are frontend-facing projections, not raw FHIR payloads.
+ * - Raw search/index semantics stay in `ClaimsContextFhirRelatedPerson`.
+ * - Use exported constants for repeated source and parameter names.
+ */
+export type RelatedProfileStatus = 'active' | 'pending' | 'inactive' | 'revoked';
+export type RelatedProfileRole = 'controller' | 'caregiver' | 'related-person' | 'professional' | 'member' | 'unknown';
+export type RelatedProfileSource = 'relatedperson';
+export declare const RELATED_PROFILE_SOURCE_RELATED_PERSON: "relatedperson";
+export declare const RELATED_PROFILE_SEARCH_PARAM_ACTOR_IDENTIFIER: "actorIdentifier";
+export declare const RELATED_PROFILE_SEARCH_PARAM_SUBJECT_ID: "subjectId";
+export declare const RELATED_PROFILE_SEARCH_PARAM_RELATIONSHIP: "relationship";
+export declare const RELATED_PROFILE_SEARCH_PARAM_INCLUDE_INACTIVE: "includeInactive";
+export type RelatedProfileSearchInput = Readonly<{
+    actorIdentifier: string;
+    subjectId?: string;
+    relationship?: string;
+    includeInactive?: boolean;
+}>;
+export type RelatedProfileSummary = Readonly<{
+    relationshipId: string;
+    source: RelatedProfileSource;
+    subjectId: string;
+    actorIdentifier?: string;
+    actorDisplayName?: string;
+    actorTelecom?: string;
+    relationship?: string;
+    role: RelatedProfileRole;
+    isController: boolean;
+    status: RelatedProfileStatus;
+    claims: Record<string, unknown>;
+}>;
+export type RelatedProfileSearchResult = Readonly<{
+    actorIdentifier: string;
+    total: number;
+    data: RelatedProfileSummary[];
+}>;
+export declare const DEFAULT_INDIVIDUAL_MEMBER_BASELINE_SEATS = 2;
+export declare const DEFAULT_INDIVIDUAL_MEMBER_BASELINE_PRICE_EUR = "0.00";

package/dist/models/related-profile.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * @fileoverview Shared DTOs for portal/BFF `related profiles` projections.
+ *
+ * @architecture 101
+ * - These DTOs are frontend-facing projections, not raw FHIR payloads.
+ * - Raw search/index semantics stay in `ClaimsContextFhirRelatedPerson`.
+ * - Use exported constants for repeated source and parameter names.
+ */
+export const RELATED_PROFILE_SOURCE_RELATED_PERSON = 'relatedperson';
+export const RELATED_PROFILE_SEARCH_PARAM_ACTOR_IDENTIFIER = 'actorIdentifier';
+export const RELATED_PROFILE_SEARCH_PARAM_SUBJECT_ID = 'subjectId';
+export const RELATED_PROFILE_SEARCH_PARAM_RELATIONSHIP = 'relationship';
+export const RELATED_PROFILE_SEARCH_PARAM_INCLUDE_INACTIVE = 'includeInactive';
+export const DEFAULT_INDIVIDUAL_MEMBER_BASELINE_SEATS = 2;
+export const DEFAULT_INDIVIDUAL_MEMBER_BASELINE_PRICE_EUR = '0.00';

package/dist/utils/communication-identity.d.ts

@@ -6,9 +6,21 @@ import { JwkKeyUses } from '../constants/cryptography';
 export type CommunicationIdentityBootstrapMode = 'deterministic' | 'random';
 export interface CommunicationIdentityBootstrapOptions {
     /**
-     * Stable logical identifier of the device/profile/app bootstrap context.
+     * Stable logical identifier of the technical communication profile.
      *
-     * This is metadata for the caller. It is not used as implicit seed material.
+     * This is not the legal organization id, not the tenant id, and not the
+     * human controller identity.
+     *
+     * Treat it as the id of the technical channel/runtime/device profile that
+     * owns the communication keys for this app/service.
+     *
+     * Good examples:
+     * - `portal.acme.org:acme-id:web-channel`
+     * - `portal.acme.org:acme-id:backend-runtime`
+     * - `mobile.acme.app:user-42:device-primary`
+     *
+     * This value is metadata for the caller. It is not used as implicit seed
+     * material.
      */
     entityId: string;
     /**
@@ -114,10 +126,17 @@ export interface CommunicationIdentityBootstrapResult {
  * human/person signing identity used for controller/professional/individual
  * authorization decisions.
  *
+ * Conceptual split:
+ * - `appId` identifies the application towards GW CORE headers/policy
+ * - `entityId` identifies the local technical communication profile that owns
+ *   transport keys
+ * - controller/professional/subject DIDs identify domain actors
+ *
  * The returned JOSE header templates match the current DIDComm metadata contract:
  * `meta.jws.protected` and `meta.jwe.header`.
  *
- * @param options.entityId Stable logical identity of the bootstrap context.
+ * @param options.entityId Stable logical identity of the technical
+ * communication profile or channel runtime.
  * @param options.seedMaterial Explicit seed material for deterministic derivation.
  * @param options.cryptography Stateless crypto engine implementation.
  * @param options.mode Deterministic or random seed derivation mode.

package/dist/utils/communication-identity.js

@@ -11,10 +11,17 @@ import { CommunicationKeyPurposes, DefaultEncryptionCurves, DefaultSigningAlgori
  * human/person signing identity used for controller/professional/individual
  * authorization decisions.
  *
+ * Conceptual split:
+ * - `appId` identifies the application towards GW CORE headers/policy
+ * - `entityId` identifies the local technical communication profile that owns
+ *   transport keys
+ * - controller/professional/subject DIDs identify domain actors
+ *
  * The returned JOSE header templates match the current DIDComm metadata contract:
  * `meta.jws.protected` and `meta.jwe.header`.
  *
- * @param options.entityId Stable logical identity of the bootstrap context.
+ * @param options.entityId Stable logical identity of the technical
+ * communication profile or channel runtime.
  * @param options.seedMaterial Explicit seed material for deterministic derivation.
  * @param options.cryptography Stateless crypto engine implementation.
  * @param options.mode Deterministic or random seed derivation mode.

package/dist/utils/did-resolution.d.ts

@@ -1,4 +1,5 @@
-import { ActorKind, DidDocument, DidResolutionResult, ResolvedServiceEndpoint } from '../models/did';
+import type { ActorKind } from '../models/actor-session';
+import { DidDocument, DidResolutionResult, ResolvedServiceEndpoint } from '../models/did';
 /**
  * Service selection criteria used when resolving operational endpoints from a DID Document.
  */

package/dist/utils/did-resolution.js

@@ -1,4 +1,5 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { ActorKinds } from '../constants/actor-session.js';
 import { DiscoveryCapabilities, DidServiceIds } from '../constants/did-services.js';
 function normalizeServiceEndpoint(service) {
     const capability = inferCapabilityFromServiceId(service.id)
@@ -147,16 +148,16 @@ export function getActorKindFromDid(did) {
         return 'unknown';
     if (normalized.includes(':employee:')) {
         return normalized.includes('resprsn') || normalized.includes('controller')
-            ? 'organization_controller'
-            : 'professional';
+            ? ActorKinds.OrganizationController
+            : ActorKinds.Professional;
     }
     if (normalized.includes(':family:') || normalized.includes(':member:')) {
         return normalized.includes('oneself') || normalized.includes('controller')
-            ? 'individual_controller'
-            : 'individual_member';
+            ? ActorKinds.IndividualController
+            : ActorKinds.IndividualMember;
     }
     if (normalized.includes('host'))
-        return 'host_onboarding';
+        return ActorKinds.HostOnboarding;
     return 'unknown';
 }
 /**

package/dist/utils/gateway-index-params.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Shared internal index-parameter builders used by GW managers.
+ *
+ * @architecture 101
+ * These helpers are not public FHIR search catalogs. They encapsulate internal
+ * blind-query index shapes already shared across multiple GW managers.
+ */
+import type { ParameterData } from '../models/params';
+import type { ClaimsRecord } from '../models/resource-document';
+/**
+ * Internal blind-query attribute names shared by employee/controller records.
+ */
+export declare enum GatewayEmployeeIndexAttributeName {
+    Email = "email",
+    Role = "role",
+    Kid = "kid"
+}
+type EmployeeIdentityIndexInput = Readonly<{
+    email?: string;
+    roleCode?: string;
+    kidValues?: readonly string[];
+}>;
+/**
+ * Builds the canonical blind-query index set for employee/controller records.
+ *
+ * `roleCode` is expected to be already normalized by the caller.
+ *
+ * @param input - Concrete employee/controller identity values.
+ * @returns Concrete `ParameterData[]` entries ready for HMAC protection.
+ */
+export declare function buildEmployeeIdentityIndexParameters(input: EmployeeIdentityIndexInput): ParameterData[];
+/**
+ * Materializes concrete index parameters from a shared flat-claim definition list.
+ *
+ * The returned entries keep the original definition metadata (`type`, `unique`)
+ * and only replace `value` with the concrete scalar from the claims object when
+ * present.
+ *
+ * @param claims - Flat claims object to read from.
+ * @param definitions - Shared parameter definitions.
+ * @returns Concrete entries with populated values only.
+ */
+export declare function buildClaimIndexParametersFromDefinitionList(claims: ClaimsRecord, definitions: readonly ParameterData[]): ParameterData[];
+export {};

package/dist/utils/gateway-index-params.js

@@ -0,0 +1,80 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * @fileoverview Shared internal index-parameter builders used by GW managers.
+ *
+ * @architecture 101
+ * These helpers are not public FHIR search catalogs. They encapsulate internal
+ * blind-query index shapes already shared across multiple GW managers.
+ */
+/**
+ * Internal blind-query attribute names shared by employee/controller records.
+ */
+export var GatewayEmployeeIndexAttributeName;
+(function (GatewayEmployeeIndexAttributeName) {
+    GatewayEmployeeIndexAttributeName["Email"] = "email";
+    GatewayEmployeeIndexAttributeName["Role"] = "role";
+    GatewayEmployeeIndexAttributeName["Kid"] = "kid";
+})(GatewayEmployeeIndexAttributeName || (GatewayEmployeeIndexAttributeName = {}));
+/**
+ * Builds the canonical blind-query index set for employee/controller records.
+ *
+ * `roleCode` is expected to be already normalized by the caller.
+ *
+ * @param input - Concrete employee/controller identity values.
+ * @returns Concrete `ParameterData[]` entries ready for HMAC protection.
+ */
+export function buildEmployeeIdentityIndexParameters(input) {
+    const parameters = [];
+    if (typeof input.email === 'string' && input.email.trim().length > 0) {
+        parameters.push({
+            name: GatewayEmployeeIndexAttributeName.Email,
+            value: input.email.trim(),
+            unique: true,
+            type: 'string',
+        });
+    }
+    if (typeof input.roleCode === 'string' && input.roleCode.trim().length > 0) {
+        parameters.push({
+            name: GatewayEmployeeIndexAttributeName.Role,
+            value: input.roleCode.trim(),
+            unique: false,
+            type: 'token',
+        });
+    }
+    for (const kid of input.kidValues || []) {
+        if (typeof kid !== 'string' || kid.trim().length === 0)
+            continue;
+        parameters.push({
+            name: GatewayEmployeeIndexAttributeName.Kid,
+            value: kid.trim(),
+            unique: false,
+            type: 'string',
+        });
+    }
+    return parameters;
+}
+/**
+ * Materializes concrete index parameters from a shared flat-claim definition list.
+ *
+ * The returned entries keep the original definition metadata (`type`, `unique`)
+ * and only replace `value` with the concrete scalar from the claims object when
+ * present.
+ *
+ * @param claims - Flat claims object to read from.
+ * @param definitions - Shared parameter definitions.
+ * @returns Concrete entries with populated values only.
+ */
+export function buildClaimIndexParametersFromDefinitionList(claims, definitions) {
+    const parameters = [];
+    for (const definition of definitions) {
+        const rawValue = claims[definition.name];
+        if (typeof rawValue !== 'string' && typeof rawValue !== 'number') {
+            continue;
+        }
+        parameters.push({
+            ...definition,
+            value: rawValue,
+        });
+    }
+    return parameters;
+}

package/dist/utils/index.d.ts

@@ -13,6 +13,7 @@ export * from './didcomm-submit-policy';
 export * from './discovery-normalization';
 export * from './format-converter';
 export * from './fhir-cid';
+export * from './gateway-index-params';
 export * from './communication-fhir-r4';
 export * from './communication-document-reference';
 export * from './communication-identity';
@@ -27,5 +28,6 @@ export * from './normalize';
 export * from './object-convert';
 export * from './normalize-uuid';
 export * from './smart-scope';
+export * from './search-parameter-catalog';
 export * from './activation-request';
 export * from './vp-token';

package/dist/utils/index.js

@@ -13,6 +13,7 @@ export * from './didcomm-submit-policy.js';
 export * from './discovery-normalization.js';
 export * from './format-converter.js';
 export * from './fhir-cid.js';
+export * from './gateway-index-params.js';
 export * from './communication-fhir-r4.js';
 export * from './communication-document-reference.js';
 export * from './communication-identity.js';
@@ -27,5 +28,6 @@ export * from './normalize.js';
 export * from './object-convert.js';
 export * from './normalize-uuid.js';
 export * from './smart-scope.js';
+export * from './search-parameter-catalog.js';
 export * from './activation-request.js';
 export * from './vp-token.js';

package/dist/utils/search-parameter-catalog.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Helpers for shared search-parameter catalogs.
+ *
+ * @architecture 101
+ * - Search catalogs define the public search surface by resource type.
+ * - These helpers resolve canonical contextualized claim names plus aliases.
+ * - GW managers can use the same catalog both for indexing and for future
+ *   `CapabilityStatement.searchParam` generation.
+ */
+import type { ClaimsRecord } from '../models/resource-document';
+import type { ParameterData, SearchParameterCatalog, SearchParameterDefinition } from '../models/params';
+/**
+ * Resolves the first populated value for a search parameter definition using its
+ * canonical claim name followed by any configured aliases.
+ *
+ * @param claims - Flat claims object.
+ * @param definition - Search parameter definition.
+ * @returns First populated scalar value, if any.
+ */
+export declare function resolveSearchParameterValueFromClaims(claims: ClaimsRecord, definition: SearchParameterDefinition): string | undefined;
+/**
+ * Builds index/query-ready `ParameterData` entries from a shared search catalog.
+ *
+ * Only catalog entries marked as indexable, and with a populated value in the
+ * claims object, are returned.
+ *
+ * @param claims - Flat claims object.
+ * @param catalog - Shared search parameter catalog for a resource type.
+ * @returns Concrete parameter entries with resolved values.
+ */
+export declare function buildIndexParametersFromSearchCatalog<TSearchName extends string>(claims: ClaimsRecord, catalog: SearchParameterCatalog<TSearchName>): ParameterData[];

package/dist/utils/search-parameter-catalog.js

@@ -0,0 +1,81 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * @fileoverview Helpers for shared search-parameter catalogs.
+ *
+ * @architecture 101
+ * - Search catalogs define the public search surface by resource type.
+ * - These helpers resolve canonical contextualized claim names plus aliases.
+ * - GW managers can use the same catalog both for indexing and for future
+ *   `CapabilityStatement.searchParam` generation.
+ */
+/**
+ * Trims a scalar value into a canonical optional string.
+ *
+ * @param value - Raw claim value.
+ * @returns Trimmed text or `undefined` when empty.
+ */
+function normalizeOptionalText(value) {
+    const normalized = String(value ?? '').trim();
+    return normalized || undefined;
+}
+/**
+ * Resolves a flat claim using exact match first and `@context`-prefixed lookup
+ * as compatibility fallback for contextualized storage mode.
+ *
+ * @param claims - Flat claims object.
+ * @param claimName - Canonical or alias claim key.
+ * @returns Scalar value when present.
+ */
+function getContextualizedClaimValue(claims, claimName) {
+    const directValue = normalizeOptionalText(claims[claimName]);
+    if (directValue)
+        return directValue;
+    const context = normalizeOptionalText(claims['@context']);
+    if (!context)
+        return undefined;
+    const prefixedName = context.endsWith('.') ? `${context}${claimName}` : `${context}.${claimName}`;
+    return normalizeOptionalText(claims[prefixedName]);
+}
+/**
+ * Resolves the first populated value for a search parameter definition using its
+ * canonical claim name followed by any configured aliases.
+ *
+ * @param claims - Flat claims object.
+ * @param definition - Search parameter definition.
+ * @returns First populated scalar value, if any.
+ */
+export function resolveSearchParameterValueFromClaims(claims, definition) {
+    const claimNames = [definition.name, ...(definition.claimAliases || [])];
+    for (const claimName of claimNames) {
+        const normalized = getContextualizedClaimValue(claims, claimName);
+        if (normalized)
+            return normalized;
+    }
+    return undefined;
+}
+/**
+ * Builds index/query-ready `ParameterData` entries from a shared search catalog.
+ *
+ * Only catalog entries marked as indexable, and with a populated value in the
+ * claims object, are returned.
+ *
+ * @param claims - Flat claims object.
+ * @param catalog - Shared search parameter catalog for a resource type.
+ * @returns Concrete parameter entries with resolved values.
+ */
+export function buildIndexParametersFromSearchCatalog(claims, catalog) {
+    const parameters = [];
+    for (const definition of Object.values(catalog)) {
+        if (definition.indexed === false)
+            continue;
+        const value = resolveSearchParameterValueFromClaims(claims, definition);
+        if (!value)
+            continue;
+        parameters.push({
+            ...definition,
+            name: definition.name,
+            value,
+        });
+    }
+    return parameters;
+}

package/package.json

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