gdc-common-utils-ts 1.24.3 → 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/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/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

@@ -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`
@@ -60,9 +68,12 @@ export declare function extractRepresentativeCredentialBinding(representativeCre
  * 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 such as
- * `sameAs` and `hasCredential`. Activation policy must therefore accept the
- * canonical person URN form and must not require a representative `did:web`.
+ * 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.
  */
@@ -148,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`
@@ -145,9 +153,12 @@ function extractCredentialBindingValue(value) {
  * 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 such as
- * `sameAs` and `hasCredential`. Activation policy must therefore accept the
- * canonical person URN form and must not require a representative `did:web`.
+ * 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.
  */
@@ -306,6 +317,14 @@ 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`.

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

@@ -1,4 +1,4 @@
-import { ControllerBindingInput, IdentityBootstrapValidationResult, OrganizationActivationRequest, OrganizationBindingInput } from '../models/identity-bootstrap';
+import { ControllerBindingInput, DidcommPlaintextTransportMetadata, IdentityBootstrapValidationResult, OrganizationActivationRequest, OrganizationBindingInput } from '../models/identity-bootstrap';
 import { JwkSet } from '../models/jwk';
 /**
  * Builder input for the canonical organization/service activation payload.
@@ -54,6 +54,23 @@ export interface BuildOrganizationBindingInputInput {
         keys: Array<Record<string, unknown>>;
     } | Array<Record<string, unknown>>;
 }
+export interface BuildDidcommPlaintextTransportMetadataInput {
+    /**
+     * Explicit controller/person binding used by `_activate`.
+     *
+     * In demo/plaintext flows this is the preferred source for mirroring the
+     * technical communication key metadata into `meta.jws.protected` /
+     * `meta.jwe.header`.
+     */
+    controller?: ControllerBindingInput;
+    /**
+     * Optional explicit content type copied into the mirrored technical JWS
+     * header.
+     *
+     * Defaults to `application/didcomm-plaintext+json`.
+     */
+    contentType?: string;
+}
 /**
  * Builds the canonical controller/person binding from semantic variables.
  *
@@ -79,12 +96,37 @@ export declare function buildControllerBindingInput(input: BuildControllerBindin
  * Builds the canonical organization/provider binding from semantic variables.
  */
 export declare function buildOrganizationBindingInput(input: BuildOrganizationBindingInputInput): OrganizationBindingInput;
+/**
+ * Builds the technical plaintext transport metadata expected by GW-compatible
+ * demo flows.
+ *
+ * Transport rule:
+ * - in secure JOSE transport, these values belong in the protected JWS/JWE
+ *   headers of the real envelope
+ * - in `application/didcomm-plaintext+json`, there is no signed outer
+ *   envelope on the wire, so high-level SDK/BFF helpers may mirror the same
+ *   technical key identifiers and public JWKs into `meta.jws.protected` and
+ *   `meta.jwe.header`
+ *
+ * This is technical compatibility fallback only. The canonical activation
+ * contract remains `controller.publicKeyJwk` / `controller.jwks`.
+ */
+export declare function buildDidcommPlaintextTransportMetadata(input: BuildDidcommPlaintextTransportMetadataInput): DidcommPlaintextTransportMetadata | undefined;
 /**
  * Builds the canonical `_activate` request payload shared by SDK and GW helpers.
  *
  * The resulting object intentionally preserves deprecated compatibility fields
  * when supplied, so callers can keep legacy flows alive while validators and
  * runtime layers flag that debt explicitly.
+ *
+ * Transport note:
+ * - secure JOSE submission should place technical signing/encryption metadata
+ *   in the protected headers of the real JWS/JWE envelope
+ * - demo `application/didcomm-plaintext+json` flows may mirror those same
+ *   values into plaintext `meta.jws.protected` / `meta.jwe.header` as a
+ *   technical fallback expected by GW-compatible backends
+ * - that plaintext transport metadata must not replace the canonical
+ *   `controller.publicKeyJwk` / `controller.jwks` activation contract
  */
 export declare function buildOrganizationActivationRequest(input: BuildOrganizationActivationRequestInput): OrganizationActivationRequest;
 /**

package/dist/utils/activation-request.js

@@ -1,5 +1,6 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { IssueSeverity } from '../models/issue.js';
+import { JoseContentEncryptionAlgorithms } from '../constants/cryptography.js';
 function pushIssue(issues, severity, code, message, path) {
     issues.push({ severity, code, message, ...(path ? { path } : {}) });
 }
@@ -12,6 +13,22 @@ function normalizeJwkSet(publicKeys) {
     }
     return publicKeys;
 }
+function normalizeJwk(input) {
+    return input && typeof input === 'object'
+        ? input
+        : undefined;
+}
+function isEncryptionJwk(key) {
+    if (!key) {
+        return false;
+    }
+    const purposes = Array.isArray(key.purposes) ? key.purposes.map((value) => String(value)) : [];
+    const keyOps = Array.isArray(key.key_ops) ? key.key_ops.map((value) => String(value)) : [];
+    return String(key.use || '').trim() === 'enc'
+        || purposes.includes('didcomm-enc')
+        || keyOps.includes('encrypt')
+        || keyOps.includes('deriveKey');
+}
 /**
  * Builds the canonical controller/person binding from semantic variables.
  *
@@ -53,12 +70,69 @@ export function buildOrganizationBindingInput(input) {
         ...(jwks ? { jwks } : {}),
     };
 }
+/**
+ * Builds the technical plaintext transport metadata expected by GW-compatible
+ * demo flows.
+ *
+ * Transport rule:
+ * - in secure JOSE transport, these values belong in the protected JWS/JWE
+ *   headers of the real envelope
+ * - in `application/didcomm-plaintext+json`, there is no signed outer
+ *   envelope on the wire, so high-level SDK/BFF helpers may mirror the same
+ *   technical key identifiers and public JWKs into `meta.jws.protected` and
+ *   `meta.jwe.header`
+ *
+ * This is technical compatibility fallback only. The canonical activation
+ * contract remains `controller.publicKeyJwk` / `controller.jwks`.
+ */
+export function buildDidcommPlaintextTransportMetadata(input) {
+    const signingKey = normalizeJwk(input.controller?.publicKeyJwk);
+    const encryptionKey = normalizeJwk(input.controller?.jwks?.keys?.find((candidate) => isEncryptionJwk(normalizeJwk(candidate))));
+    if (!signingKey && !encryptionKey) {
+        return undefined;
+    }
+    return {
+        ...(signingKey
+            ? {
+                jws: {
+                    protected: {
+                        alg: String(signingKey.alg || '').trim() || 'none',
+                        kid: String(signingKey.kid || '').trim() || 'none',
+                        cty: String(input.contentType || '').trim() || 'application/didcomm-plaintext+json',
+                        jwk: signingKey,
+                    },
+                },
+            }
+            : {}),
+        ...(encryptionKey
+            ? {
+                jwe: {
+                    header: {
+                        alg: String(encryptionKey.alg || encryptionKey.crv || '').trim() || 'none',
+                        enc: JoseContentEncryptionAlgorithms.Aes256Gcm,
+                        skid: String(encryptionKey.kid || '').trim() || 'none',
+                        jwk: encryptionKey,
+                    },
+                },
+            }
+            : {}),
+    };
+}
 /**
  * Builds the canonical `_activate` request payload shared by SDK and GW helpers.
  *
  * The resulting object intentionally preserves deprecated compatibility fields
  * when supplied, so callers can keep legacy flows alive while validators and
  * runtime layers flag that debt explicitly.
+ *
+ * Transport note:
+ * - secure JOSE submission should place technical signing/encryption metadata
+ *   in the protected headers of the real JWS/JWE envelope
+ * - demo `application/didcomm-plaintext+json` flows may mirror those same
+ *   values into plaintext `meta.jws.protected` / `meta.jwe.header` as a
+ *   technical fallback expected by GW-compatible backends
+ * - that plaintext transport metadata must not replace the canonical
+ *   `controller.publicKeyJwk` / `controller.jwks` activation contract
  */
 export function buildOrganizationActivationRequest(input) {
     return {

package/dist/utils/communication-search-editor.d.ts

@@ -6,7 +6,7 @@ export declare const CommunicationSearchEntryTypes: Readonly<{
 export declare const CommunicationSearchOperationTypes: Readonly<{
     readonly Search: "search";
 }>;
-export type CommunicationSearchDraft = Readonly<{
+export type CommunicationSearchState = Readonly<{
     searchParams: Readonly<Record<string, string | number | boolean | readonly (string | number | boolean)[] | undefined>>;
     periodStart?: string;
     periodEnd?: string;
@@ -24,7 +24,7 @@ export type CommunicationSearchDraft = Readonly<{
  */
 export declare class CommunicationSearchEditor {
     private draft;
-    constructor(initial?: Partial<CommunicationSearchDraft>);
+    constructor(initial?: Partial<CommunicationSearchState>);
     setSearchParams(value: Readonly<Record<string, string | number | boolean | readonly (string | number | boolean)[] | undefined>>): this;
     setSearchParam(claimKey: string, value: string | number | boolean | readonly (string | number | boolean)[] | undefined): this;
     setSearchParamSender(value: string | readonly string[]): this;
@@ -36,7 +36,7 @@ export declare class CommunicationSearchEditor {
     setPeriodEnd(value: string): this;
     setPaginationCount(value: number): this;
     setPageNumber(value: number): this;
-    getDraft(): CommunicationSearchDraft;
+    getState(): CommunicationSearchState;
     toSearchInput(): CommunicationParticipantSearchInput;
     buildRequest(): FhirParametersResource;
     buildEntry(): {

package/dist/utils/communication-search-editor.js

@@ -121,7 +121,7 @@ export class CommunicationSearchEditor {
         this.draft = cloneDraft({ ...this.draft, page: value });
         return this;
     }
-    getDraft() {
+    getState() {
         return cloneDraft(this.draft);
     }
     toSearchInput() {

package/dist/utils/index.d.ts

@@ -48,6 +48,7 @@ export * from './fhir-validator';
 export * from './family-registration-test-data';
 export * from './individual-form-pdf';
 export * from './individual-organization-claims';
+export * from './organization-lifecycle';
 export * from './individual-organization-lifecycle';
 export * from './individual-onboarding-editor';
 export * from './individual-onboarding-document-reference';
@@ -57,6 +58,8 @@ export * from './invoice-bundle';
 export * from './ips-bundle-claims';
 export * from './interoperable-resource-operation';
 export * from './jwt';
+export * from './jwk-thumbprint';
+export * from './legal-organization-onboarding';
 export * from './license';
 export * from './license-commercial-search';
 export * from './license-list-search';

package/dist/utils/index.js

@@ -48,6 +48,7 @@ export * from './fhir-validator.js';
 export * from './family-registration-test-data.js';
 export * from './individual-form-pdf.js';
 export * from './individual-organization-claims.js';
+export * from './organization-lifecycle.js';
 export * from './individual-organization-lifecycle.js';
 export * from './individual-onboarding-editor.js';
 export * from './individual-onboarding-document-reference.js';
@@ -57,6 +58,8 @@ export * from './invoice-bundle.js';
 export * from './ips-bundle-claims.js';
 export * from './interoperable-resource-operation.js';
 export * from './jwt.js';
+export * from './jwk-thumbprint.js';
+export * from './legal-organization-onboarding.js';
 export * from './license.js';
 export * from './license-commercial-search.js';
 export * from './license-list-search.js';