gdc-common-utils-ts 1.24.1 → 2.0.1

package/README.md

@@ -1,5 +1,15 @@
 # gdc-common-utils-ts
 
+See [ARCHITECTURE.md](./ARCHITECTURE.md) and
+[CONTRIBUTING.md](./CONTRIBUTING.md) before adding new shared helpers,
+fixtures, or high-level tests.
+
+Short rule:
+
+- if a test/example can reuse a shared type or fixture, it must do so
+- do not add ad hoc literals in `101` tests when `gdc-common-utils-ts` can own
+  the reusable value instead
+
 Employee shared examples live in `src/examples/employee.ts`.
 Employee pure helper functions live in `src/utils/employee.ts`.
 
@@ -30,6 +40,35 @@ boundaries used in `gdc-common-utils-ts`.
 - `resource.meta.claims` is the canonical project-specific claims container and must be preserved across conversions/transports.
 - `resource.meta.claims` is not part of base FHIR; it is a claims-first extension carried by FHIR-like resources in GDC contracts.
 
+## Identity Continuity
+
+For ICA-backed organization activation, the representative/controller proof is
+intentionally split into two complementary dimensions:
+
+- `credentialSubject.sameAs`
+  public identity continuity, typically an email-derived
+  `urn:multibase:z...`
+- `credentialSubject.hasCredential.material`
+  signing-key continuity, ideally an RFC 9278 JWK-thumbprint URN bound to the
+  controller key that signs the VP or was captured during ICA verification
+
+They are not interchangeable:
+
+- `sameAs` does not prove possession of the signing key
+- `hasCredential.material` does not by itself prove the expected public alias
+  or email continuity
+
+Production-grade flows should prefer ICA-issued representative VCs that carry
+both dimensions.
+
+Step by step:
+
+1. ICA verifies the signed PDF and emits the representative VC.
+2. ICA projects `credentialSubject.sameAs` from signed email evidence when available.
+3. ICA projects `credentialSubject.hasCredential.material` from the captured controller binding key.
+4. GW/common-utils enforce key-binding continuity as the hard activation requirement.
+5. Higher layers may additionally compare `sameAs` for stronger identity/audit continuity.
+
 ## 101 Test Convention
 
 Every `101` test in this repo is expected to be a didactic executable tutorial,

package/dist/constants/index.d.ts

@@ -14,6 +14,7 @@ export * from './schemaorg';
 export * from './hl7-roles';
 export * from './healthcare';
 export * from './permission-templates';
+export * from './profile-runtime';
 export * from './vital-signs';
 export * from './network';
 export * from './observation-category';

package/dist/constants/index.js

@@ -14,6 +14,7 @@ export * from './schemaorg.js';
 export * from './hl7-roles.js';
 export * from './healthcare.js';
 export * from './permission-templates.js';
+export * from './profile-runtime.js';
 export * from './vital-signs.js';
 export * from './network.js';
 export * from './observation-category.js';

package/dist/constants/profile-runtime.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Canonical logical application families used by shared SDK profile/session
+ * contracts.
+ */
+export declare const ProfileAppTypes: Readonly<{
+    readonly Organization: "Organization";
+    readonly Family: "Family";
+}>;
+export type ProfileAppType = typeof ProfileAppTypes[keyof typeof ProfileAppTypes];
+/**
+ * Canonical runtime classes for actor-aware profile loading.
+ */
+export declare const ActorRuntimeClasses: Readonly<{
+    readonly Frontend: "frontend";
+    readonly Server: "server";
+}>;
+export type ActorRuntimeClass = typeof ActorRuntimeClasses[keyof typeof ActorRuntimeClasses];
+/**
+ * Canonical key access strategies for profile loading/unlocking.
+ */
+export declare const KeyAccessModes: Readonly<{
+    readonly DeriveFromSeed: "derive-from-seed";
+    readonly UnlockEncryptedKeys: "unlock-encrypted-keys";
+}>;
+export type KeyAccessMode = typeof KeyAccessModes[keyof typeof KeyAccessModes];
+/**
+ * Canonical secret kinds for subject/index relationship connection.
+ */
+export declare const ConnectionSecretKinds: Readonly<{
+    readonly PinPassword: "pin-password";
+    readonly OtpCode: "otp-code";
+}>;
+export type ConnectionSecretKind = typeof ConnectionSecretKinds[keyof typeof ConnectionSecretKinds];

package/dist/constants/profile-runtime.js

@@ -0,0 +1,30 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Canonical logical application families used by shared SDK profile/session
+ * contracts.
+ */
+export const ProfileAppTypes = Object.freeze({
+    Organization: 'Organization',
+    Family: 'Family',
+});
+/**
+ * Canonical runtime classes for actor-aware profile loading.
+ */
+export const ActorRuntimeClasses = Object.freeze({
+    Frontend: 'frontend',
+    Server: 'server',
+});
+/**
+ * Canonical key access strategies for profile loading/unlocking.
+ */
+export const KeyAccessModes = Object.freeze({
+    DeriveFromSeed: 'derive-from-seed',
+    UnlockEncryptedKeys: 'unlock-encrypted-keys',
+});
+/**
+ * Canonical secret kinds for subject/index relationship connection.
+ */
+export const ConnectionSecretKinds = Object.freeze({
+    PinPassword: 'pin-password',
+    OtpCode: 'otp-code',
+});

package/dist/examples/frontend-session.js

@@ -9,12 +9,13 @@
  * - do not inline DID/email/profile literals directly in frontend examples
  */
 import { EXAMPLE_PROFILE_EMAIL, EXAMPLE_PROFILE_ID, EXAMPLE_PROFILE_ORGANIZATION_DID, } from './shared.js';
+import { EXAMPLE_PROFILE_APP_TYPE_FAMILY } from './profile-runtime.js';
 export const EXAMPLE_PROFILE_SESSION_INPUT = {
     profileId: ` ${EXAMPLE_PROFILE_ID} `,
     email: ` ${EXAMPLE_PROFILE_EMAIL} `,
     role: ' controller ',
     providerDid: ` ${EXAMPLE_PROFILE_ORGANIZATION_DID} `,
-    appType: 'Family',
+    appType: EXAMPLE_PROFILE_APP_TYPE_FAMILY,
 };
 export const EXAMPLE_PROFILE_REGISTRY_ENTRY = {
     id: EXAMPLE_PROFILE_ID,

package/dist/examples/ica-activation-proof.d.ts

@@ -24,6 +24,13 @@ export declare const EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID: "urn:ietf:params:oau
 export declare const EXAMPLE_PRESENTATION_AUDIENCE_HOST_ID: "host:node-operator-es";
 export declare const EXAMPLE_ORGANIZATION_TAX_ID: "ESB00112233";
 export declare const EXAMPLE_REPRESENTATIVE_ROLE_CODE: "RESPRSN";
+export declare const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_CODE: "1120";
+export declare const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_IDENTIFIER: "urn:ilo:ilostat:isco-08:1120";
+export declare const EXAMPLE_REPRESENTATIVE_IDENTIFIER: "IDCES-99999999R";
+export declare const EXAMPLE_REPRESENTATIVE_EMAIL: "legal.rep@example.org";
+export declare const EXAMPLE_REPRESENTATIVE_SUBJECT_URN: "urn:person:identifier:IDCES-99999999R";
+export declare const EXAMPLE_REPRESENTATIVE_SAME_AS: "urn:multibase:zControllerHash";
+export declare const EXAMPLE_ORG_ACTIVATION_ORGANIZATION_DID: "did:web:provider.example:health-care:organization:taxid:VATES-ESB00112233";
 export declare const EXAMPLE_ORGANIZATION_ID: "ESB00112233";
 export declare const EXAMPLE_ACTIVATION_AUTHORIZED_CATEGORY: "health-care";
 export declare const EXAMPLE_ACTIVATION_AUTHORIZED_SERVICE_TYPE: "organization/Composition.cruds";
@@ -45,18 +52,18 @@ export declare const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL: Rea
     '@context': string[];
     type: ("VerifiableCredential" | "LegalRepresentativeCredential")[];
     credentialSubject: {
-        id: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
+        id: "urn:person:identifier:IDCES-99999999R";
         memberOf: {
             taxID: "ESB00112233";
         };
         hasOccupation: {
-            identifier: {
-                value: "RESPRSN";
-            };
+            identifier: "urn:ilo:ilostat:isco-08:1120";
         };
         hasCredential: {
             material: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
         };
+        identifier: "IDCES-99999999R";
+        sameAs: "urn:multibase:zControllerHash";
     };
 }>;
 export declare const EXAMPLE_ORG_ACTIVATION_PROOF_VP_PAYLOAD: Readonly<{

package/dist/examples/ica-activation-proof.js

@@ -30,6 +30,13 @@ export const EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID = `${UrnPrefixes.JwkThumbprin
 export const EXAMPLE_PRESENTATION_AUDIENCE_HOST_ID = 'host:node-operator-es';
 export const EXAMPLE_ORGANIZATION_TAX_ID = 'ESB00112233';
 export const EXAMPLE_REPRESENTATIVE_ROLE_CODE = 'RESPRSN';
+export const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_CODE = '1120';
+export const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_IDENTIFIER = 'urn:ilo:ilostat:isco-08:1120';
+export const EXAMPLE_REPRESENTATIVE_IDENTIFIER = 'IDCES-99999999R';
+export const EXAMPLE_REPRESENTATIVE_EMAIL = 'legal.rep@example.org';
+export const EXAMPLE_REPRESENTATIVE_SUBJECT_URN = `urn:person:identifier:${EXAMPLE_REPRESENTATIVE_IDENTIFIER}`;
+export const EXAMPLE_REPRESENTATIVE_SAME_AS = 'urn:multibase:zControllerHash';
+export const EXAMPLE_ORG_ACTIVATION_ORGANIZATION_DID = 'did:web:provider.example:health-care:organization:taxid:VATES-ESB00112233';
 export const EXAMPLE_ORGANIZATION_ID = EXAMPLE_ORGANIZATION_TAX_ID;
 export const EXAMPLE_ACTIVATION_AUTHORIZED_CATEGORY = DataspaceSectors.HealthCare;
 export const EXAMPLE_ACTIVATION_AUTHORIZED_SERVICE_TYPE = ServiceCapability.IndexProvider;
@@ -57,18 +64,18 @@ export const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL = Object.fre
         ActivationCredentialTypes.LegalRepresentativeCredential,
     ],
     credentialSubject: {
-        id: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
+        id: EXAMPLE_REPRESENTATIVE_SUBJECT_URN,
         memberOf: {
             taxID: EXAMPLE_ORGANIZATION_TAX_ID,
         },
         hasOccupation: {
-            identifier: {
-                value: EXAMPLE_REPRESENTATIVE_ROLE_CODE,
-            },
+            identifier: EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_IDENTIFIER,
         },
         hasCredential: {
             material: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
         },
+        identifier: EXAMPLE_REPRESENTATIVE_IDENTIFIER,
+        sameAs: EXAMPLE_REPRESENTATIVE_SAME_AS,
     },
 });
 export const EXAMPLE_ORG_ACTIVATION_PROOF_VP_PAYLOAD = Object.freeze({

package/dist/examples/index.d.ts

@@ -11,6 +11,7 @@ export * from './related-person';
 export * from './consent-access';
 export * from './relationship-access';
 export * from './frontend-session';
+export * from './profile-runtime';
 export * from './lifecycle';
 export * from './api-flow-examples';
 export * from './contract-examples';

package/dist/examples/index.js

@@ -11,6 +11,7 @@ export * from './related-person.js';
 export * from './consent-access.js';
 export * from './relationship-access.js';
 export * from './frontend-session.js';
+export * from './profile-runtime.js';
 export * from './lifecycle.js';
 export * from './api-flow-examples.js';
 export * from './contract-examples.js';

package/dist/examples/lifecycle.js

@@ -2,7 +2,7 @@
 import { ClaimsOrganizationSchemaorg, ClaimsPersonSchemaorg, } from '../constants/schemaorg.js';
 import { LifecycleRequestType } from '../constants/lifecycle.js';
 import { ClaimConsent } from '../models/consent-rule.js';
-import { IndividualOrganizationLifecycleDraft, IndividualOrganizationLifecycleOperations, } from '../utils/individual-organization-lifecycle.js';
+import { IndividualOrganizationLifecycleEditor, IndividualOrganizationLifecycleOperations, } from '../utils/individual-organization-lifecycle.js';
 import { EXAMPLE_EMAIL_CONTROLLER_INDIVIDUAL, EXAMPLE_EMAIL_CONTROLLER_ORG, EXAMPLE_CLINICAL_SECTION_ALLERGIES, EXAMPLE_CONSENT_PURPOSE_TREATMENT, EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN, EXAMPLE_JURISDICTION, EXAMPLE_SECTOR, EXAMPLE_TENANT_IDENTIFIER, } from './shared.js';
 /**
  * Canonical lifecycle naming for `v1`.
@@ -190,12 +190,12 @@ export const EXAMPLE_INDIVIDUAL_DISABLE_MESSAGE = {
         erasesPersonalDataImmediately: false,
     },
 };
-export const EXAMPLE_INDIVIDUAL_ORGANIZATION_DISABLE_ENTRY = new IndividualOrganizationLifecycleDraft()
+export const EXAMPLE_INDIVIDUAL_ORGANIZATION_DISABLE_ENTRY = new IndividualOrganizationLifecycleEditor()
     .setClaims(EXAMPLE_INDIVIDUAL_DISABLE_MESSAGE.claims)
     .setOperation(IndividualOrganizationLifecycleOperations.Disable)
     .setRequestType(EXAMPLE_INDIVIDUAL_ORGANIZATION_DISABLE_REQUEST_TYPE)
     .buildCurrentGwDataEntry();
-export const EXAMPLE_INDIVIDUAL_ORGANIZATION_DISABLE_PAYLOAD = new IndividualOrganizationLifecycleDraft()
+export const EXAMPLE_INDIVIDUAL_ORGANIZATION_DISABLE_PAYLOAD = new IndividualOrganizationLifecycleEditor()
     .setClaims(EXAMPLE_INDIVIDUAL_DISABLE_MESSAGE.claims)
     .setOperation(IndividualOrganizationLifecycleOperations.Disable)
     .setRequestType(EXAMPLE_INDIVIDUAL_ORGANIZATION_DISABLE_REQUEST_TYPE)
@@ -221,12 +221,12 @@ export const EXAMPLE_INDIVIDUAL_DELETE_MESSAGE = {
         keepsMinimumAuditTrailRequiredByLaw: true,
     },
 };
-export const EXAMPLE_INDIVIDUAL_ORGANIZATION_PURGE_ENTRY = new IndividualOrganizationLifecycleDraft()
+export const EXAMPLE_INDIVIDUAL_ORGANIZATION_PURGE_ENTRY = new IndividualOrganizationLifecycleEditor()
     .setClaims(EXAMPLE_INDIVIDUAL_DISABLE_MESSAGE.claims)
     .setOperation(IndividualOrganizationLifecycleOperations.Purge)
     .setRequestType(EXAMPLE_INDIVIDUAL_ORGANIZATION_PURGE_REQUEST_TYPE)
     .buildCurrentGwDataEntry();
-export const EXAMPLE_INDIVIDUAL_ORGANIZATION_PURGE_PAYLOAD = new IndividualOrganizationLifecycleDraft()
+export const EXAMPLE_INDIVIDUAL_ORGANIZATION_PURGE_PAYLOAD = new IndividualOrganizationLifecycleEditor()
     .setClaims(EXAMPLE_INDIVIDUAL_DISABLE_MESSAGE.claims)
     .setOperation(IndividualOrganizationLifecycleOperations.Purge)
     .setRequestType(EXAMPLE_INDIVIDUAL_ORGANIZATION_PURGE_REQUEST_TYPE)

package/dist/examples/organization-controller.d.ts

@@ -32,7 +32,6 @@ export declare const EXAMPLE_ACTIVATE_ORGANIZATION_FROM_ICA_PROOF_INPUT: {
         };
     };
     readonly additionalClaims: {
-        readonly "org.schema.Organization.alternateName": "acme";
         readonly "org.schema.Organization.legalName": "ACME HEALTH SL";
         readonly "org.schema.Organization.identifier.additionalType": "taxID";
         readonly "org.schema.Organization.identifier.value": "VATES-B00112233";

package/dist/examples/organization-controller.js

@@ -14,7 +14,6 @@ export const EXAMPLE_ACTIVATE_ORGANIZATION_FROM_ICA_PROOF_INPUT = {
     vpToken: '<ica-proof-token>',
     controller: EXAMPLE_CONTROLLER_BINDING,
     additionalClaims: {
-        [ClaimsOrganizationSchemaorg.alternateName]: 'acme',
         [ClaimsOrganizationSchemaorg.legalName]: 'ACME HEALTH SL',
         [ClaimsOrganizationSchemaorg.identifierType]: 'taxID',
         [ClaimsOrganizationSchemaorg.identifierValue]: 'VATES-B00112233',

package/dist/examples/profile-runtime.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared fixtures for profile-runtime tests and 101 examples.
+ *
+ * Keep runtime-class, key-access, secret-kind, app-type, and local secret
+ * placeholders here so SDK packages do not re-inline them in their own tests.
+ */
+export declare const EXAMPLE_PROFILE_APP_TYPE_FAMILY: "Family";
+export declare const EXAMPLE_PROFILE_RUNTIME_CLASS_SERVER: "server";
+export declare const EXAMPLE_PROFILE_RUNTIME_CLASS_FRONTEND: "frontend";
+export declare const EXAMPLE_PROFILE_KEY_ACCESS_MODE_SERVER: "unlock-encrypted-keys";
+export declare const EXAMPLE_PROFILE_KEY_ACCESS_MODE_FRONTEND: "derive-from-seed";
+export declare const EXAMPLE_PROFILE_CONNECTION_SECRET_KIND_PIN_PASSWORD: "pin-password";
+export declare const EXAMPLE_PROFILE_LOCAL_PIN_PASSWORD_BACKEND: "local-backend-pin";
+export declare const EXAMPLE_PROFILE_LOCAL_PIN_PASSWORD_FRONTEND: "local-frontend-pin";
+export declare const EXAMPLE_PROFILE_CONNECTION_PIN_PASSWORD: "subject-channel-pin";
+export declare const EXAMPLE_PROFILE_RUNTIME_JOB_ID: "job-id";

package/dist/examples/profile-runtime.js

@@ -0,0 +1,18 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { ActorRuntimeClasses, ConnectionSecretKinds, KeyAccessModes, ProfileAppTypes, } from '../constants/profile-runtime.js';
+/**
+ * Shared fixtures for profile-runtime tests and 101 examples.
+ *
+ * Keep runtime-class, key-access, secret-kind, app-type, and local secret
+ * placeholders here so SDK packages do not re-inline them in their own tests.
+ */
+export const EXAMPLE_PROFILE_APP_TYPE_FAMILY = ProfileAppTypes.Family;
+export const EXAMPLE_PROFILE_RUNTIME_CLASS_SERVER = ActorRuntimeClasses.Server;
+export const EXAMPLE_PROFILE_RUNTIME_CLASS_FRONTEND = ActorRuntimeClasses.Frontend;
+export const EXAMPLE_PROFILE_KEY_ACCESS_MODE_SERVER = KeyAccessModes.UnlockEncryptedKeys;
+export const EXAMPLE_PROFILE_KEY_ACCESS_MODE_FRONTEND = KeyAccessModes.DeriveFromSeed;
+export const EXAMPLE_PROFILE_CONNECTION_SECRET_KIND_PIN_PASSWORD = ConnectionSecretKinds.PinPassword;
+export const EXAMPLE_PROFILE_LOCAL_PIN_PASSWORD_BACKEND = 'local-backend-pin';
+export const EXAMPLE_PROFILE_LOCAL_PIN_PASSWORD_FRONTEND = 'local-frontend-pin';
+export const EXAMPLE_PROFILE_CONNECTION_PIN_PASSWORD = 'subject-channel-pin';
+export const EXAMPLE_PROFILE_RUNTIME_JOB_ID = 'job-id';

package/dist/examples/shared.d.ts

@@ -187,6 +187,15 @@ export declare const EXAMPLE_CONSENT_OPERATION_THREAD_ID: "thread-consent-exampl
 export declare const EXAMPLE_CONSENT_PERIOD_START: "2026-05-20T00:00:00Z";
 export declare const EXAMPLE_COMMUNICATION_UUID: "urn:uuid:communication-example-001";
 export declare const EXAMPLE_COMMUNICATION_IDENTIFIER: "urn:uuid:communication-example-001";
+export declare const EXAMPLE_COMMUNICATION_THREAD_ID: "thread-communication-example-001";
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_SEARCH_SUBJECT_DID: string;
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_SENDER_DID: "did:web:provider.example.org";
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_USER_DID: string;
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_USER: "family.owner@example.org";
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_RECIPIENT: "nurse.oncall@example.org";
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_TEL_RECIPIENT: "+34600111222";
+export declare const EXAMPLE_COMMUNICATION_SEARCH_CATEGORY: string;
+export declare const EXAMPLE_COMMUNICATION_SEARCH_TOPIC: "care-plan-follow-up";
 export declare const EXAMPLE_IPS_BUNDLE_NOTE_TEXT: "IPS ingestion request";
 export declare const EXAMPLE_CONTENT_TYPE_APPLICATION_JSON: "application/json";
 export declare const EXAMPLE_CONTENT_TYPE_FHIR_JSON: "application/fhir+json";

package/dist/examples/shared.js

@@ -226,6 +226,15 @@ export const EXAMPLE_CONSENT_OPERATION_THREAD_ID = 'thread-consent-example-001';
 export const EXAMPLE_CONSENT_PERIOD_START = '2026-05-20T00:00:00Z';
 export const EXAMPLE_COMMUNICATION_UUID = 'urn:uuid:communication-example-001';
 export const EXAMPLE_COMMUNICATION_IDENTIFIER = EXAMPLE_COMMUNICATION_UUID;
+export const EXAMPLE_COMMUNICATION_THREAD_ID = 'thread-communication-example-001';
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_SEARCH_SUBJECT_DID = EXAMPLE_SUBJECT_DID;
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_SENDER_DID = EXAMPLE_TENANT_SERVICE_DID;
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_USER_DID = EXAMPLE_RELATED_PERSON_MEMBER_DID;
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_USER = 'family.owner@example.org';
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_RECIPIENT = 'nurse.oncall@example.org';
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_TEL_RECIPIENT = '+34600111222';
+export const EXAMPLE_COMMUNICATION_SEARCH_CATEGORY = CommunicationCategoryCodes.Notification.attributeValue;
+export const EXAMPLE_COMMUNICATION_SEARCH_TOPIC = 'care-plan-follow-up';
 export const EXAMPLE_IPS_BUNDLE_NOTE_TEXT = 'IPS ingestion request';
 export const EXAMPLE_CONTENT_TYPE_APPLICATION_JSON = 'application/json';
 export const EXAMPLE_CONTENT_TYPE_FHIR_JSON = 'application/fhir+json';

package/dist/interfaces/Cryptography.types.d.ts

@@ -27,6 +27,17 @@ export type AlgMlDsa2 = "ML-DSA-44";
 export type AlgMlDsa3 = "ML-DSA-65";
 export type AlgMlDsa5 = "ML-DSA-87";
 export type MldsaAlg = AlgMlDsa2 | AlgMlDsa3 | AlgMlDsa5;
+/**
+ * Base JWKs used for RFC 7638 thumbprint calculation.
+ *
+ * Mapping used by this codebase:
+ * - ML-KEM uses `OKP` with `crv`
+ * - ML-DSA uses `AKP` with `alg` and `pub`
+ * - classical EC uses `EC` with `crv`, `x`, `y`
+ *
+ * Note that ML-DSA does not use `crv` here. The algorithm family/strength is
+ * captured by `alg` instead, for example `ML-DSA-44`.
+ */
 export type MlkemBaseJwk = {
     kty: "OKP";
     crv: MlkemCurve;
@@ -52,6 +63,10 @@ export interface MldsaPublicJwk extends MldsaBaseJwk {
 }
 /**
  * Represents a public key for classic cryptography algorithms like Elliptic Curve.
+ *
+ * The RFC 7638 thumbprint for these keys is derived from `kty`, `crv`, `x`,
+ * and `y`. This means curves such as `P-256`, `P-384`, and `secp256k1` are
+ * covered through the `crv` field.
  */
 export interface ClassicPublicJwk {
     kty: "EC";

package/dist/models/identity-bootstrap.d.ts

@@ -1,6 +1,7 @@
 import { PublicJwk } from '../interfaces/Cryptography.types';
 import { type IssueSeverityAttentionCode } from './issue';
 import { JwkSet } from './jwk';
+import { DidCommDecodedMetadata } from './confidential-message';
 /**
  * Public key binding for a human actor/controller identity.
  *
@@ -79,6 +80,14 @@ export interface OrganizationActivationRequest extends ActivationProofInput {
      */
     representativeCredential?: unknown;
 }
+/**
+ * Technical metadata mirrored into plaintext DIDComm payloads when no real
+ * outer JWS/JWE envelope is present on the wire.
+ *
+ * This must be treated as transport compatibility metadata only. It does not
+ * replace canonical activation fields such as `vp_token` or `controller.*`.
+ */
+export type DidcommPlaintextTransportMetadata = DidCommDecodedMetadata;
 /**
  * Structured validation issue emitted by bootstrap validators.
  */

package/dist/utils/activation-policy.d.ts

@@ -1,4 +1,4 @@
-export type ActivationRepresentativePolicyErrorCode = 'MISSING_REPRESENTATIVE_DID_WEB' | 'MISSING_REPRESENTATIVE_ROLE_RESPRSN' | 'MISSING_REPRESENTATIVE_CREDENTIAL_BINDING' | 'REPRESENTATIVE_TAXID_MISMATCH';
+export type ActivationRepresentativePolicyErrorCode = 'MISSING_REPRESENTATIVE_SUBJECT_ID' | 'MISSING_REPRESENTATIVE_ROLE_RESPRSN' | 'MISSING_REPRESENTATIVE_CREDENTIAL_BINDING' | 'REPRESENTATIVE_TAXID_MISMATCH';
 export type ActivationServiceAuthorizationPolicyErrorCode = 'MISSING_ORGANIZATION_SERVICE_CATEGORY' | 'MISSING_ORGANIZATION_SERVICE_TYPE' | 'UNAUTHORIZED_ORGANIZATION_SERVICE_CATEGORY' | 'UNAUTHORIZED_ORGANIZATION_SERVICE_TYPE';
 export type ActivationRepresentativePolicyError = {
     code: ActivationRepresentativePolicyErrorCode;
@@ -48,6 +48,14 @@ export declare function hasRoleCode(roleCode: string | undefined, requiredCode?:
 /**
  * Extracts representative signing/binding continuity data from `credentialSubject.hasCredential`.
  *
+ * Security note:
+ * - this field proves continuity of the controller signing/binding key
+ * - it is intentionally different from `credentialSubject.sameAs`, which
+ *   proves continuity of the representative public identity alias (for example
+ *   email-derived `urn:multibase:z...`)
+ * - production-grade activation flows are strongest when both dimensions are
+ *   present in the ICA-issued representative VC
+ *
  * Compatibility rules:
  * - legacy VC payloads may still carry `hasCredential.material`
  * - newer payloads may carry the same semantic value in `hasCredential.value`
@@ -56,12 +64,40 @@ export declare function hasRoleCode(roleCode: string | undefined, requiredCode?:
  * @param representativeCredential Candidate representative credential.
  */
 export declare function extractRepresentativeCredentialBinding(representativeCredential: unknown): string | undefined;
+/**
+ * Extracts the representative subject identifier from `credentialSubject.id`.
+ *
+ * ICA currently models the natural person with a stable person URN while the
+ * controller/bootstrap continuity is carried in sibling claims:
+ * - `sameAs` for public identity continuity
+ * - `hasCredential` for key-binding continuity
+ *
+ * Activation policy must therefore accept the canonical person URN form and
+ * must not require a representative `did:web`.
+ *
+ * @param representativeCredential Candidate representative credential.
+ */
+export declare function extractRepresentativeSubjectId(representativeCredential: unknown): string | undefined;
 /**
  * Extracts a `did:web:` identifier from a VC-like credential.
  *
  * @param credential Candidate credential.
  */
 export declare function extractDidWebFromCredential(credential: unknown): string | undefined;
+/**
+ * Checks whether the representative role expresses the activation-controller
+ * semantics accepted by GW.
+ *
+ * Compatibility rules:
+ * - historical GW payloads may still use HL7/FHIR `RESPRSN`
+ * - current ICA person credentials may encode the legal representative role as
+ *   ISCO-08 `1120`, either tokenized (`ISCO-08|1120`) or as the canonical
+ *   ILO URN (`urn:ilo:ilostat:isco-08:1120`)
+ *
+ * @param roleCode Candidate role token extracted from the credential.
+ * @param requiredCode Required GW compatibility code, defaults to `RESPRSN`.
+ */
+export declare function hasActivationRepresentativeRole(roleCode: string | undefined, requiredCode?: string): boolean;
 /**
  * Extracts the categories authorized by an ICA-issued organization credential.
  *
@@ -123,6 +159,14 @@ export declare function isMemberDidWebUnderOwner(memberDidWeb: string, ownerDidW
 /**
  * Validates the activation representative policy against organization and representative credentials.
  *
+ * The representative proof model is intentionally two-dimensional:
+ * - `credentialSubject.sameAs` expresses public identity continuity
+ * - `credentialSubject.hasCredential.material` expresses signing-key continuity
+ *
+ * For GW activation, the key-binding dimension is the hard requirement
+ * enforced here. The public-identity dimension may still be used by higher
+ * layers for stronger demo/production matching and auditability.
+ *
  * @param input.organizationCredential Candidate organization credential.
  * @param input.representativeCredential Candidate representative credential.
  * @param input.requiredRoleCode Required representative role, defaults to `RESPRSN`.

package/dist/utils/activation-policy.js

@@ -106,6 +106,14 @@ export function hasRoleCode(roleCode, requiredCode = 'RESPRSN') {
 /**
  * Extracts representative signing/binding continuity data from `credentialSubject.hasCredential`.
  *
+ * Security note:
+ * - this field proves continuity of the controller signing/binding key
+ * - it is intentionally different from `credentialSubject.sameAs`, which
+ *   proves continuity of the representative public identity alias (for example
+ *   email-derived `urn:multibase:z...`)
+ * - production-grade activation flows are strongest when both dimensions are
+ *   present in the ICA-issued representative VC
+ *
  * Compatibility rules:
  * - legacy VC payloads may still carry `hasCredential.material`
  * - newer payloads may carry the same semantic value in `hasCredential.value`
@@ -141,6 +149,27 @@ function extractCredentialBindingValue(value) {
         || '').trim();
     return candidate || undefined;
 }
+/**
+ * Extracts the representative subject identifier from `credentialSubject.id`.
+ *
+ * ICA currently models the natural person with a stable person URN while the
+ * controller/bootstrap continuity is carried in sibling claims:
+ * - `sameAs` for public identity continuity
+ * - `hasCredential` for key-binding continuity
+ *
+ * Activation policy must therefore accept the canonical person URN form and
+ * must not require a representative `did:web`.
+ *
+ * @param representativeCredential Candidate representative credential.
+ */
+export function extractRepresentativeSubjectId(representativeCredential) {
+    const obj = asObject(representativeCredential);
+    if (!obj)
+        return undefined;
+    const subject = extractCredentialSubject(obj);
+    const subjectId = String(subject?.id || '').trim();
+    return subjectId || undefined;
+}
 /**
  * Extracts a `did:web:` identifier from a VC-like credential.
  *
@@ -154,6 +183,27 @@ export function extractDidWebFromCredential(credential) {
     const didCandidate = String(subject?.id || obj.id || '').trim();
     return didCandidate.startsWith('did:web:') ? didCandidate : undefined;
 }
+/**
+ * Checks whether the representative role expresses the activation-controller
+ * semantics accepted by GW.
+ *
+ * Compatibility rules:
+ * - historical GW payloads may still use HL7/FHIR `RESPRSN`
+ * - current ICA person credentials may encode the legal representative role as
+ *   ISCO-08 `1120`, either tokenized (`ISCO-08|1120`) or as the canonical
+ *   ILO URN (`urn:ilo:ilostat:isco-08:1120`)
+ *
+ * @param roleCode Candidate role token extracted from the credential.
+ * @param requiredCode Required GW compatibility code, defaults to `RESPRSN`.
+ */
+export function hasActivationRepresentativeRole(roleCode, requiredCode = 'RESPRSN') {
+    if (hasRoleCode(roleCode, requiredCode))
+        return true;
+    const normalized = String(roleCode || '').trim().toUpperCase();
+    if (!normalized)
+        return false;
+    return /(?:^|[|:])1120$/.test(normalized);
+}
 /**
  * Extracts the categories authorized by an ICA-issued organization credential.
  *
@@ -267,19 +317,27 @@ export function isMemberDidWebUnderOwner(memberDidWeb, ownerDidWeb) {
 /**
  * Validates the activation representative policy against organization and representative credentials.
  *
+ * The representative proof model is intentionally two-dimensional:
+ * - `credentialSubject.sameAs` expresses public identity continuity
+ * - `credentialSubject.hasCredential.material` expresses signing-key continuity
+ *
+ * For GW activation, the key-binding dimension is the hard requirement
+ * enforced here. The public-identity dimension may still be used by higher
+ * layers for stronger demo/production matching and auditability.
+ *
  * @param input.organizationCredential Candidate organization credential.
  * @param input.representativeCredential Candidate representative credential.
  * @param input.requiredRoleCode Required representative role, defaults to `RESPRSN`.
  */
 export function validateActivationRepresentativePolicy(input) {
     const errors = [];
-    const representativeDid = input.representativeCredential
-        ? extractDidWebFromCredential(input.representativeCredential)
+    const representativeSubjectId = input.representativeCredential
+        ? extractRepresentativeSubjectId(input.representativeCredential)
         : undefined;
-    if (input.representativeCredential && !representativeDid) {
+    if (input.representativeCredential && !representativeSubjectId) {
         errors.push({
-            code: 'MISSING_REPRESENTATIVE_DID_WEB',
-            message: 'ICA-issued representative credential is missing credentialSubject.id did:web.',
+            code: 'MISSING_REPRESENTATIVE_SUBJECT_ID',
+            message: 'ICA-issued representative credential is missing credentialSubject.id.',
         });
     }
     if (!input.representativeCredential)
@@ -293,10 +351,10 @@ export function validateActivationRepresentativePolicy(input) {
         });
     }
     const roleCode = extractRepresentativeRoleCode(input.representativeCredential);
-    if (!hasRoleCode(roleCode, input.requiredRoleCode || 'RESPRSN')) {
+    if (!hasActivationRepresentativeRole(roleCode, input.requiredRoleCode || 'RESPRSN')) {
         errors.push({
             code: 'MISSING_REPRESENTATIVE_ROLE_RESPRSN',
-            message: 'ICA-issued representative credential must include Responsible Party role (RESPRSN) in credentialSubject.hasOccupation.',
+            message: 'ICA-issued representative credential must include legal representative role semantics (RESPRSN or ISCO-08 1120) in credentialSubject.hasOccupation.',
         });
     }
     const binding = extractRepresentativeCredentialBinding(input.representativeCredential);