gdc-common-utils-ts 1.24.1 → 2.0.1

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.
@@ -22,7 +22,18 @@ export interface BuildOrganizationActivationRequestInput {
 export interface BuildControllerBindingInputInput {
     /** Public DID to publish or bind for the controller/person. */
     did?: string;
-    /** Additional public alias such as `mailto:`. */
+    /**
+     * Additional public alias for the controller/person.
+     *
+     * Canonical examples:
+     * - `urn:multibase:z...` for an email-derived ICA/GW binding
+     * - `tel:+34600111222` for a phone identifier
+     * - `did:web:...` or another stable public identifier
+     *
+     * Do not use `mailto:` when the source value is an email for ICA/GW
+     * interoperability. Start from the plain email and normalize it first with
+     * `normalizeSameAsHash(...)`.
+     */
     sameAs?: string;
     /** Primary controller signing key. */
     publicSignKey?: Record<string, unknown>;
@@ -43,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.
  *
@@ -54,18 +82,51 @@ export interface BuildOrganizationBindingInputInput {
  *
  * so the caller does not have to manually shape `controller.publicKeyJwk` and
  * `controller.jwks`.
+ *
+ * ICA/GW interoperability note:
+ * - callers that start from a raw email should first normalize it with
+ *   `normalizeSameAsHash(...)` before assigning `sameAs`
+ * - keep the raw email separately in activation claims when GW still needs it
+ *   for internal admin/bootstrap records
+ * - do not send `mailto:` as the canonical controller alias when the binding
+ *   source is an email address
  */
 export declare function buildControllerBindingInput(input: BuildControllerBindingInputInput): ControllerBindingInput;
 /**
  * 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.
  *
@@ -23,6 +40,14 @@ function normalizeJwkSet(publicKeys) {
  *
  * so the caller does not have to manually shape `controller.publicKeyJwk` and
  * `controller.jwks`.
+ *
+ * ICA/GW interoperability note:
+ * - callers that start from a raw email should first normalize it with
+ *   `normalizeSameAsHash(...)` before assigning `sameAs`
+ * - keep the raw email separately in activation claims when GW still needs it
+ *   for internal admin/bootstrap records
+ * - do not send `mailto:` as the canonical controller alias when the binding
+ *   source is an email address
  */
 export function buildControllerBindingInput(input) {
     const jwks = normalizeJwkSet(input.publicKeys);
@@ -45,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-participant-search-test-data.d.ts

@@ -0,0 +1,17 @@
+import type { CommunicationParticipantProjection, CommunicationParticipantSearchInput } from './communication-participant-search';
+/**
+ * Shared communication-participant search input fixture reused across GW/SDK
+ * tests.
+ */
+export declare function buildExampleCommunicationParticipantSearchInput(overrides?: Partial<CommunicationParticipantSearchInput>): CommunicationParticipantSearchInput;
+/**
+ * Shared stored projection fixture that mirrors the shape persisted by GW
+ * communication-channel projections.
+ */
+export declare function buildExampleCommunicationParticipantProjection(overrides?: Partial<CommunicationParticipantProjection & {
+    id?: string;
+    thid?: string;
+}>): CommunicationParticipantProjection & {
+    id: string;
+    thid: string;
+};

package/dist/utils/communication-participant-search-test-data.js

@@ -0,0 +1,39 @@
+import { EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_RECIPIENT, EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_USER, EXAMPLE_COMMUNICATION_SEARCH_CATEGORY, EXAMPLE_COMMUNICATION_SEARCH_TOPIC, EXAMPLE_COMMUNICATION_PARTICIPANT_SEARCH_SUBJECT_DID, EXAMPLE_COMMUNICATION_PARTICIPANT_SENDER_DID, EXAMPLE_COMMUNICATION_PARTICIPANT_TEL_RECIPIENT, EXAMPLE_COMMUNICATION_PARTICIPANT_USER_DID, EXAMPLE_COMMUNICATION_THREAD_ID, } from '../examples/shared.js';
+import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
+/**
+ * Shared communication-participant search input fixture reused across GW/SDK
+ * tests.
+ */
+export function buildExampleCommunicationParticipantSearchInput(overrides = {}) {
+    return {
+        subject: EXAMPLE_COMMUNICATION_PARTICIPANT_SEARCH_SUBJECT_DID,
+        userActorId: [EXAMPLE_COMMUNICATION_PARTICIPANT_USER_DID, EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_USER],
+        targetActorId: [EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_RECIPIENT, EXAMPLE_COMMUNICATION_PARTICIPANT_TEL_RECIPIENT],
+        searchParams: {
+            [CommunicationClaim.Category]: EXAMPLE_COMMUNICATION_SEARCH_CATEGORY,
+            [CommunicationClaim.Topic]: EXAMPLE_COMMUNICATION_SEARCH_TOPIC,
+        },
+        ...overrides,
+    };
+}
+/**
+ * Shared stored projection fixture that mirrors the shape persisted by GW
+ * communication-channel projections.
+ */
+export function buildExampleCommunicationParticipantProjection(overrides = {}) {
+    return {
+        id: 'communication-participant-record-001',
+        thid: EXAMPLE_COMMUNICATION_THREAD_ID,
+        subject: EXAMPLE_COMMUNICATION_PARTICIPANT_SEARCH_SUBJECT_DID,
+        sender: EXAMPLE_COMMUNICATION_PARTICIPANT_SENDER_DID,
+        sent: '2026-06-15T10:00:00Z',
+        category: EXAMPLE_COMMUNICATION_SEARCH_CATEGORY,
+        topic: EXAMPLE_COMMUNICATION_SEARCH_TOPIC,
+        recipients: [
+            EXAMPLE_COMMUNICATION_PARTICIPANT_USER_DID,
+            EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_RECIPIENT,
+            EXAMPLE_COMMUNICATION_PARTICIPANT_TEL_RECIPIENT,
+        ],
+        ...overrides,
+    };
+}

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

@@ -0,0 +1,108 @@
+import { buildSearchBundle, type FhirParametersResource, type SearchParameterPrimitive } from './fhir-search.js';
+/**
+ * Canonical participant-token prefixes used by communication search helpers.
+ */
+export declare const CommunicationParticipantPrefixes: Readonly<{
+    readonly Did: "did:";
+    readonly Email: "email:";
+    readonly Mailto: "mailto:";
+    readonly Tel: "tel:";
+    readonly Phone: "phone:";
+    readonly Wildcard: "*";
+}>;
+/**
+ * Canonical parameter names supported by `Communication/_search`.
+ */
+export declare const CommunicationParticipantSearchParameterNames: Readonly<{
+    readonly Subject: "subject";
+    readonly Actor: "actor";
+    readonly Sender: "sender";
+    readonly Recipient: "recipient";
+    readonly User: "user";
+    readonly Target: "target";
+    readonly PeriodStart: "period-start";
+    readonly PeriodEnd: "period-end";
+    readonly Page: "page";
+    readonly Count: "count";
+}>;
+/**
+ * Backward-compatible aliases still accepted while callers migrate to the
+ * canonical control names.
+ */
+export declare const CommunicationParticipantSearchParameterAliases: Readonly<{
+    readonly SentFrom: "sent-from";
+    readonly SentTo: "sent-to";
+}>;
+/**
+ * Indexed-attribute names used by communication projections.
+ */
+export declare const CommunicationParticipantIndexNames: Readonly<{
+    readonly Subject: "Communication.subject";
+    readonly Participant: "Communication.participant-token";
+    readonly Sender: "Communication.sender-token";
+    readonly Recipient: "Communication.recipient-token";
+}>;
+export type CommunicationParticipantTokenInput = string | readonly string[] | undefined | null;
+export type CommunicationParticipantSearchInput = {
+    /**
+     * Canonical claims-like search parameters keyed by reusable claim constants
+     * such as `CommunicationClaim.Sender`, `CommunicationClaim.Recipient`,
+     * `CommunicationClaim.Category`, or `CommunicationClaim.Topic`.
+     */
+    searchParams?: Readonly<Record<string, SearchParameterPrimitive | undefined>>;
+    subject?: CommunicationParticipantTokenInput;
+    actorId?: CommunicationParticipantTokenInput;
+    senderActorId?: CommunicationParticipantTokenInput;
+    recipientActorId?: CommunicationParticipantTokenInput;
+    userActorId?: CommunicationParticipantTokenInput;
+    targetActorId?: CommunicationParticipantTokenInput;
+    periodStart?: string;
+    periodEnd?: string;
+    sentFrom?: string;
+    sentTo?: string;
+    page?: number;
+    count?: number;
+};
+export type CommunicationParticipantSearchCriteria = {
+    subjectActorIds: string[];
+    anySubject: boolean;
+    actorIds: string[];
+    anyActor: boolean;
+    senderActorIds: string[];
+    anySender: boolean;
+    recipientActorIds: string[];
+    anyRecipient: boolean;
+    userActorIds: string[];
+    anyUser: boolean;
+    targetActorIds: string[];
+    anyTarget: boolean;
+    claimSearchParams: Readonly<Record<string, string[]>>;
+    periodStart?: string;
+    periodEnd?: string;
+    page: number;
+    count?: number;
+};
+export type CommunicationParticipantProjection = {
+    subject?: unknown;
+    sender?: unknown;
+    recipients?: unknown;
+    from?: unknown;
+    to?: unknown;
+    sent?: unknown;
+    category?: unknown;
+    topic?: unknown;
+};
+export type CommunicationParticipantIndexedAttribute = {
+    name: string;
+    value: string;
+    unique?: boolean;
+};
+export declare function normalizeCommunicationParticipantToken(value: unknown): string;
+export declare function normalizeCommunicationParticipantTokenList(value: unknown): string[];
+export declare function isCommunicationParticipantWildcardToken(value: unknown): boolean;
+export declare function buildCommunicationParticipantSearchParameters(input: CommunicationParticipantSearchInput): FhirParametersResource;
+export declare function buildCommunicationParticipantSearchBundle(input: CommunicationParticipantSearchInput): ReturnType<typeof buildSearchBundle>;
+export declare function parseCommunicationParticipantSearchCriteria(input: Record<string, unknown> | FhirParametersResource | undefined): CommunicationParticipantSearchCriteria;
+export declare function buildCommunicationParticipantIndexAttributes(projection: CommunicationParticipantProjection): CommunicationParticipantIndexedAttribute[];
+export declare function matchesCommunicationParticipantSearch(projection: CommunicationParticipantProjection, criteria: CommunicationParticipantSearchCriteria): boolean;
+export declare function paginateCommunicationParticipantMatches<T>(records: readonly T[], criteria: Pick<CommunicationParticipantSearchCriteria, 'page' | 'count'>): T[];