gdc-sdk-node-ts 2.2.2 → 2.3.0

package/dist/resource-operations.d.ts

@@ -1,6 +1,7 @@
+import type { DeviceAppType } from 'gdc-common-utils-ts/constants/device';
 import type { LicenseOfferSearchState, LicenseOrderSearchState } from 'gdc-common-utils-ts/utils/license-commercial-search';
 import type { LicenseListSearchState } from 'gdc-common-utils-ts/utils/license-list-search';
-import type { BundleSearchQuery, CommunicationInput, DateRange, EmployeeSearchValue, IndividualOrganizationLifecycleInput } from 'gdc-sdk-core-ts';
+import type { BundleSearchQuery, CommMsgExtendedCommunicationOutboxJob, CommunicationOutboxJob, CommunicationInput, DateRange, EmployeeSearchValue, IndividualOrganizationLifecycleInput, TransportProfile } from 'gdc-sdk-core-ts';
 import type { BundleEntry, BundleJsonApi } from 'gdc-common-utils-ts/models/bundle';
 import type { SubmitAndPollResult } from './orchestration/client-port.js';
 import type { RouteContext } from './individual-onboarding.js';
@@ -85,6 +86,52 @@ export type LicenseListRuntimeSearchInput = {
         intervalMs?: number;
     };
 };
+/**
+ * Reserves one individual-organization seat for an existing RelatedPerson.
+ *
+ * Only FHIR v3 RoleCode members belong here. ISCO professionals receive
+ * Consent/Communication access but keep using the license paid by their
+ * professional organization.
+ */
+export type IndividualMemberLicenseInvitationInput = {
+    ownerOrganizationId: string;
+    /** Exact card/subject DID granted after the invitation is accepted. */
+    subjectDid: string;
+    relatedPersonId: string;
+    invitationId: string;
+    role: string;
+    email?: string;
+    telephone?: string;
+    type?: DeviceAppType;
+    requestThid?: string;
+    pollOptions?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    };
+};
+/** Adds zero-cost member seats to one individual organization. */
+export type IndividualMemberLicenseAddInput = {
+    ownerOrganizationId: string;
+    quantity: number;
+    requestThid?: string;
+    pollOptions?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    };
+};
+/** Input shared by invitation acceptance, deactivation and release. */
+export type IndividualMemberLicenseTransitionInput = {
+    /** Required for controller deactivation/release; acceptance resolves by code. */
+    ownerOrganizationId?: string;
+    activationCode: string;
+    subjectId?: string;
+    verifiedActorIdentifier?: string;
+    requestThid?: string;
+    pollOptions?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    };
+};
 /**
  * Runtime search/list input for commercial offer read-models exposed through
  * actor facades.
@@ -144,6 +191,13 @@ export type IpsOrFhirImportInput = {
     };
 };
 export type RelatedPersonUpsertInput = {
+    /**
+     * Canonical RelatedPerson bundle. Keep kinship/legal relationship in
+     * `RelatedPerson.relationship`; the optional GDC `RelatedPerson.role`
+     * extension may carry comma-separated functions such as
+     * `CAREGIVER,ECON,DEPEN,BILL`.
+     * Access decisions such as PERMITTED do not belong in either claim.
+     */
     relatedPersonPayload: {
         thid?: string;
     } & Record<string, unknown>;
@@ -153,7 +207,22 @@ export type RelatedPersonUpsertInput = {
     };
 };
 export type CommunicationIngestionInput = {
-    communicationPayload: CommunicationInput & Record<string, unknown>;
+    /**
+     * Preferred claims-first job created by
+     * `createCommunicationOutboxJobFromCommMsgExtendedDraft(...)`. Legacy
+     * `createOutboxJobFromDraft(...)` jobs remain accepted temporarily.
+     */
+    communicationJob?: CommunicationOutboxJob | CommMsgExtendedCommunicationOutboxJob;
+    /**
+     * Compatibility input for callers that already own one GW envelope.
+     * New application code should pass `communicationJob` instead.
+     */
+    communicationPayload?: CommunicationInput & Record<string, unknown>;
+    /** Overrides the client default only for this clinical submission. */
+    transportProfile?: TransportProfile;
+    /** Clinical representation rendered from canonical claims: built-in `api`/`r4` or an extension format. */
+    clinicalFormat?: string;
+    /** @deprecated Use `clinicalFormat`. This value selects representation and route, not transport. */
     pathFormatSegment?: 'org.hl7.fhir.api' | 'org.hl7.fhir.r4' | 'api' | 'r4' | 'fhir.r4';
     autoConvertClaimsToFhirR4?: boolean;
     pollOptions?: {
@@ -250,6 +319,8 @@ export type ClinicalBundleSearchInput = Omit<BundleSearchQuery, 'section' | 'sea
         timeoutMs?: number;
         intervalMs?: number;
     };
+    /** Overrides the client default for this subject-scoped clinical read. */
+    transportProfile?: TransportProfile;
 };
 export type ConsentActorTargetInput = string | string[] | {
     identifier?: string;
@@ -481,6 +552,40 @@ export declare function searchIndividualLicensesWithDeps(routeCtx: RouteContext,
  * search route without mandatory filters.
  */
 export declare function listIndividualLicensesWithDeps(routeCtx: RouteContext, input: LicenseListRuntimeSearchInput | undefined, deps: Parameters<typeof searchIndividualLicensesWithDeps>[2]): Promise<SubmitAndPollResult>;
+type IndividualLicenseMutationDeps = {
+    individualLicenseActionPath: (ctx: RouteContext, action: string) => string;
+    individualLicenseActionPollPath: (ctx: RouteContext, action: string) => string;
+    submitAndPoll: (submitPath: string, pollPath: string, payload: {
+        thid?: string;
+    } & Record<string, unknown>, pollOptions?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }) => Promise<SubmitAndPollResult>;
+};
+/**
+ * Reserves one available household/member seat for a selected contact.
+ *
+ * Ordered application flow:
+ * 1. Create/select RelatedPerson.
+ * 2. Author Consent rules.
+ * 3. Call this operation only for a FHIR v3 RoleCode member.
+ * 4. Put the returned activation code in the invitation Communication.
+ */
+export declare function issueIndividualMemberLicenseWithDeps(routeCtx: RouteContext, input: IndividualMemberLicenseInvitationInput, deps: IndividualLicenseMutationDeps): Promise<SubmitAndPollResult>;
+/**
+ * Adds free seats without creating contacts, permissions or invitations.
+ * Price zero is explicit so GW never routes this MVP operation through a
+ * payment-proof branch.
+ */
+export declare function addFreeIndividualMemberLicensesWithDeps(routeCtx: RouteContext, input: IndividualMemberLicenseAddInput, deps: IndividualLicenseMutationDeps): Promise<SubmitAndPollResult>;
+/**
+ * Accepts, deactivates or releases one member seat.
+ *
+ * `_accept` needs the Firebase/BFF verified recipient plus the authenticated
+ * subject id. `_release` remains backend-guarded and cannot free an active
+ * member directly.
+ */
+export declare function transitionIndividualMemberLicenseWithDeps(routeCtx: RouteContext, action: '_accept' | '_deactivate' | '_release', input: IndividualMemberLicenseTransitionInput, deps: IndividualLicenseMutationDeps): Promise<SubmitAndPollResult>;
 export declare function searchIndividualLicenseOffersWithDeps(routeCtx: RouteContext, input: LicenseOfferRuntimeSearchInput, deps: {
     individualLicenseOfferSearchPath: (ctx: RouteContext) => string;
     individualLicenseOfferSearchPollPath: (ctx: RouteContext) => string;
@@ -550,8 +655,8 @@ export declare function upsertRelatedPersonAndPollWithDeps(routeCtx: RouteContex
     }) => Promise<SubmitAndPollResult>;
 }): Promise<SubmitAndPollResult>;
 export declare function ingestCommunicationAndUpdateIndexWithDeps(routeCtx: RouteContext, input: CommunicationIngestionInput, deps: {
-    individualCommunicationBatchPath: (ctx: RouteContext, pathFormatSegment: 'org.hl7.fhir.api' | 'org.hl7.fhir.r4') => string;
-    individualCommunicationPollPath: (ctx: RouteContext, pathFormatSegment: 'org.hl7.fhir.api' | 'org.hl7.fhir.r4') => string;
+    individualCommunicationBatchPath: (ctx: RouteContext, pathFormatSegment: string) => string;
+    individualCommunicationPollPath: (ctx: RouteContext, pathFormatSegment: string) => string;
     transformPayloadForFhirR4?: (payload: Record<string, unknown>, enabled: boolean) => Record<string, unknown>;
     submitAndPoll: (submitPath: string, pollPath: string, payload: {
         thid?: string;
@@ -651,3 +756,5 @@ export declare function generateDigitalTwinFromSubjectDataWithDeps(routeCtx: Rou
         intervalMs?: number;
     }) => Promise<SubmitAndPollResult>;
 }): Promise<SubmitAndPollResult>;
+export declare function normalizeCommunicationPathFormatSegment(raw?: string): string;
+export {};

package/dist/resource-operations.js

@@ -2,7 +2,7 @@
 import { HealthcareBasicSections, ResourceTypesFhirR4 } from 'gdc-common-utils-ts/constants';
 import { Format } from 'gdc-common-utils-ts/constants/Schemas';
 import { RelatedPersonClaim } from 'gdc-common-utils-ts/models/interoperable-claims/related-person-claims';
-import { buildCommunicationParticipantSearchBundle, buildBlockchainArtifactDocumentReference, BundleQuery, createInteroperableResourceOperationEditor, IndividualOrganizationLifecycleEditor, LicenseOfferSearchEditor, LicenseOrderSearchEditor, InteroperableLifecycleStatuses, LicenseListSearchEditor, } from 'gdc-common-utils-ts';
+import { buildCommunicationParticipantSearchBundle, buildBlockchainArtifactDocumentReference, BundleQuery, createInteroperableResourceOperationEditor, IndividualOrganizationLifecycleEditor, LicenseOfferSearchEditor, LicenseOrderSearchEditor, InteroperableLifecycleStatuses, LicenseListSearchEditor, buildLicenseIssueEntry, buildLicensePurchaseEntry, } from 'gdc-common-utils-ts';
 import { addFhirResourceToCommunication, createCommunicationResource, } from 'gdc-sdk-core-ts';
 import { GwCoreLifecycleRequestMethod, GwCoreLifecycleRequestType, GwCoreLifecycleTodo, } from './constants/lifecycle.js';
 import { buildEmployeeBatchEntry, buildEmployeeSearchBundle, ConsentClaims, } from 'gdc-sdk-core-ts';
@@ -169,6 +169,81 @@ export async function searchIndividualLicensesWithDeps(routeCtx, input, deps) {
 export async function listIndividualLicensesWithDeps(routeCtx, input, deps) {
     return searchIndividualLicensesWithDeps(routeCtx, input || {}, deps);
 }
+/**
+ * Reserves one available household/member seat for a selected contact.
+ *
+ * Ordered application flow:
+ * 1. Create/select RelatedPerson.
+ * 2. Author Consent rules.
+ * 3. Call this operation only for a FHIR v3 RoleCode member.
+ * 4. Put the returned activation code in the invitation Communication.
+ */
+export async function issueIndividualMemberLicenseWithDeps(routeCtx, input, deps) {
+    const entry = buildLicenseIssueEntry({
+        email: input.email,
+        telephone: input.telephone,
+        role: input.role,
+        userClass: 'individual',
+        type: input.type || 'web',
+        ownerOrganizationId: input.ownerOrganizationId,
+        relatedPersonId: input.relatedPersonId,
+        invitationId: input.invitationId,
+    });
+    entry.meta.subjectDid = input.subjectDid;
+    return deps.submitAndPoll(deps.individualLicenseActionPath(routeCtx, '_issue'), deps.individualLicenseActionPollPath(routeCtx, '_issue'), {
+        thid: input.requestThid || `individual-license-issue-${createRuntimeUuid()}`,
+        body: { resourceType: 'Bundle', type: 'batch', data: [entry] },
+    }, input.pollOptions);
+}
+/**
+ * Adds free seats without creating contacts, permissions or invitations.
+ * Price zero is explicit so GW never routes this MVP operation through a
+ * payment-proof branch.
+ */
+export async function addFreeIndividualMemberLicensesWithDeps(routeCtx, input, deps) {
+    const entry = buildLicensePurchaseEntry({
+        quantity: input.quantity,
+        userClass: 'individual',
+        type: 'web',
+        price: 0,
+        priceCurrency: 'EUR',
+        ownerOrganizationId: input.ownerOrganizationId,
+    });
+    return deps.submitAndPoll(deps.individualLicenseActionPath(routeCtx, '_add'), deps.individualLicenseActionPollPath(routeCtx, '_add'), {
+        thid: input.requestThid || `individual-license-add-${createRuntimeUuid()}`,
+        body: { resourceType: 'Bundle', type: 'batch', data: [entry] },
+    }, input.pollOptions);
+}
+/**
+ * Accepts, deactivates or releases one member seat.
+ *
+ * `_accept` needs the Firebase/BFF verified recipient plus the authenticated
+ * subject id. `_release` remains backend-guarded and cannot free an active
+ * member directly.
+ */
+export async function transitionIndividualMemberLicenseWithDeps(routeCtx, action, input, deps) {
+    return deps.submitAndPoll(deps.individualLicenseActionPath(routeCtx, action), deps.individualLicenseActionPollPath(routeCtx, action), {
+        thid: input.requestThid || `individual-license-${action.slice(1)}-${createRuntimeUuid()}`,
+        body: {
+            resourceType: 'Bundle',
+            type: 'batch',
+            data: [{
+                    id: input.activationCode,
+                    type: `IndividualMemberLicense${action}`,
+                    meta: {
+                        ...(input.ownerOrganizationId ? { ownerOrganizationId: input.ownerOrganizationId } : {}),
+                        ...(input.subjectId ? { subjectId: input.subjectId } : {}),
+                        ...(input.verifiedActorIdentifier ? { verifiedActorIdentifier: input.verifiedActorIdentifier } : {}),
+                        claims: {
+                            '@context': 'org.schema',
+                            'org.schema.IndividualProduct.serialNumber': input.activationCode,
+                        },
+                    },
+                    request: { method: 'POST' },
+                }],
+        },
+    }, input.pollOptions);
+}
 export async function searchIndividualLicenseOffersWithDeps(routeCtx, input, deps) {
     return deps.submitAndPoll(deps.individualLicenseOfferSearchPath(routeCtx), deps.individualLicenseOfferSearchPollPath(routeCtx), {
         thid: input.requestThid || `individual-license-offer-search-${createRuntimeUuid()}`,
@@ -281,6 +356,9 @@ export async function upsertRelatedPersonAndPollWithDeps(routeCtx, input, deps)
     return deps.submitAndPoll(deps.individualRelatedPersonBatchPath(routeCtx), deps.individualRelatedPersonPollPath(routeCtx), payload, input.pollOptions);
 }
 export async function ingestCommunicationAndUpdateIndexWithDeps(routeCtx, input, deps) {
+    if (!input.communicationPayload) {
+        throw new Error('Legacy communication ingestion requires communicationPayload.');
+    }
     const payload = {
         thid: input.communicationPayload.thid || `communication-${createRuntimeUuid()}`,
         ...input.communicationPayload,
@@ -588,13 +666,15 @@ export async function generateDigitalTwinFromSubjectDataWithDeps(routeCtx, input
         : deps.digitalTwinCompositionR4PollPath(routeCtx);
     return deps.submitAndPoll(submitPath, pollPath, payload, input.pollOptions);
 }
-function normalizeCommunicationPathFormatSegment(raw) {
+export function normalizeCommunicationPathFormatSegment(raw) {
     const value = String(raw || '').trim().toLowerCase();
     if (!value || value === 'api' || value === 'org.hl7.fhir.api')
         return 'org.hl7.fhir.api';
     if (value === 'r4' || value === 'fhir.r4' || value === 'org.hl7.fhir.r4')
         return 'org.hl7.fhir.r4';
-    return 'org.hl7.fhir.api';
+    if (/^org\.hl7\.fhir\.[a-z0-9.-]+$/.test(value))
+        return value;
+    throw new Error(`Unsupported Communication clinical format '${String(raw || '')}'.`);
 }
 function createRuntimeUuid() {
     const fromCrypto = globalThis.crypto?.randomUUID?.();

package/dist/runtime-client-paths.d.ts

@@ -52,6 +52,10 @@ export declare class RuntimeClientPaths {
     individualFamilyOrganizationPurgePollPath(ctx?: RouteContext): string;
     individualLicenseSearchPath(ctx?: RouteContext): string;
     individualLicenseSearchPollPath(ctx?: RouteContext): string;
+    /** Builds one individual-member license mutation path. */
+    individualLicenseActionPath(ctx: RouteContext | undefined, action: string): string;
+    /** Builds the poll path paired with one individual-member license mutation. */
+    individualLicenseActionPollPath(ctx: RouteContext | undefined, action: string): string;
     individualLicenseOfferSearchPath(ctx?: RouteContext): string;
     individualLicenseOfferSearchPollPath(ctx?: RouteContext): string;
     individualLicenseOrderSearchPath(ctx?: RouteContext): string;
@@ -64,8 +68,8 @@ export declare class RuntimeClientPaths {
     individualRelatedPersonPurgePollPath(ctx?: RouteContext): string;
     individualConsentR4BatchPath(ctx: RouteContext): string;
     individualConsentR4PollPath(ctx: RouteContext): string;
-    individualCommunicationBatchPath(ctx: RouteContext, format: 'org.hl7.fhir.api' | 'org.hl7.fhir.r4'): string;
-    individualCommunicationPollPath(ctx: RouteContext, format: 'org.hl7.fhir.api' | 'org.hl7.fhir.r4'): string;
+    individualCommunicationBatchPath(ctx: RouteContext, format: string): string;
+    individualCommunicationPollPath(ctx: RouteContext, format: string): string;
     individualCommunicationSearchPath(ctx: RouteContext): string;
     individualCommunicationSearchPollPath(ctx: RouteContext): string;
     individualDocumentReferenceBatchPath(ctx: RouteContext): string;

package/dist/runtime-client-paths.js

@@ -66,6 +66,10 @@ export class RuntimeClientPaths {
     individualFamilyOrganizationPurgePollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'Organization', `${GwCoreLifecycleAction.Purge}-response`); }
     individualLicenseSearchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'License', '_search'); }
     individualLicenseSearchPollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'License', '_search-response'); }
+    /** Builds one individual-member license mutation path. */
+    individualLicenseActionPath(ctx, action) { return this.v1Path(ctx, 'individual', 'org.schema', 'License', action); }
+    /** Builds the poll path paired with one individual-member license mutation. */
+    individualLicenseActionPollPath(ctx, action) { return this.v1Path(ctx, 'individual', 'org.schema', 'License', `${action}-response`); }
     individualLicenseOfferSearchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'Offer', '_search'); }
     individualLicenseOfferSearchPollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'Offer', '_search-response'); }
     individualLicenseOrderSearchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'Order', '_search'); }

package/dist/runtime-transport.d.ts

@@ -4,8 +4,9 @@ export type RuntimeTransportConfig = Readonly<{
     defaultHeaders: Record<string, string>;
     requestTimeoutMs: number;
     httpTraceFile?: string;
+    fetchImpl?: typeof fetch;
 }>;
-export declare function buildRuntimeHeaders(config: RuntimeTransportConfig, contentType: string): Record<string, string>;
+export declare function buildRuntimeHeaders(config: RuntimeTransportConfig, contentType: string, accept?: string): Record<string, string>;
 export declare function pollBatchResponseWithRuntimeConfig(config: RuntimeTransportConfig, path: string, request: {
     thid: string;
 }): Promise<{
@@ -18,5 +19,16 @@ export declare function postJsonWithRuntimeConfig(config: RuntimeTransportConfig
     location?: string;
     body: unknown;
 }>;
+/** Submits an already-rendered JSON, FHIR, DIDComm or secure-form request. */
+export declare function postRenderedWithRuntimeConfig(config: RuntimeTransportConfig, path: string, request: {
+    contentType: string;
+    accept: string;
+    body: Record<string, unknown> | string;
+}): Promise<{
+    status: number;
+    location?: string;
+    body: unknown;
+    retryAfterMs?: number;
+}>;
 export declare function fetchWithTimeout(config: RuntimeTransportConfig, path: string, init: RequestInit): Promise<Response>;
 export declare function parseResponseBody(response: Response): Promise<unknown>;

package/dist/runtime-transport.js

@@ -1,11 +1,11 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { DIDCOMM_DEFAULT_ACCEPT_HEADER } from 'gdc-common-utils-ts/utils/didcomm-submit';
 import { appendHttpTrace, parseTraceBody, parseTraceRawText, redactTraceValue, } from './runtime-http-trace.js';
-export function buildRuntimeHeaders(config, contentType) {
+export function buildRuntimeHeaders(config, contentType, accept = DIDCOMM_DEFAULT_ACCEPT_HEADER) {
     const headers = {
         ...config.defaultHeaders,
         'Content-Type': contentType,
-        Accept: DIDCOMM_DEFAULT_ACCEPT_HEADER,
+        Accept: accept,
     };
     if (config.bearerToken)
         headers.Authorization = `Bearer ${config.bearerToken}`;
@@ -36,6 +36,21 @@ export async function postJsonWithRuntimeConfig(config, path, payload, contentTy
         body: await parseResponseBody(response),
     };
 }
+/** Submits an already-rendered JSON, FHIR, DIDComm or secure-form request. */
+export async function postRenderedWithRuntimeConfig(config, path, request) {
+    const response = await fetchWithTimeout(config, path, {
+        method: 'POST',
+        headers: buildRuntimeHeaders(config, request.contentType, request.accept),
+        body: typeof request.body === 'string' ? request.body : JSON.stringify(request.body),
+    });
+    const retryAfter = Number(response.headers.get('retry-after'));
+    return {
+        status: response.status,
+        location: response.headers.get('location') || undefined,
+        body: await parseResponseBody(response),
+        retryAfterMs: Number.isFinite(retryAfter) ? retryAfter * 1000 : undefined,
+    };
+}
 export async function fetchWithTimeout(config, path, init) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), config.requestTimeoutMs);
@@ -51,7 +66,7 @@ export async function fetchWithTimeout(config, path, init) {
         },
     };
     try {
-        const response = await fetch(url, { ...init, signal: controller.signal });
+        const response = await (config.fetchImpl || fetch)(url, { ...init, signal: controller.signal });
         const responseClone = response.clone();
         const responseRaw = await responseClone.text();
         appendHttpTrace(config.httpTraceFile, {

package/dist/server-profile-protection.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Host-controlled KEK boundary.
+ *
+ * A BFF normally implements this with Cloud KMS. A native confidential app
+ * implements the same boundary with a non-exportable Keychain/Keystore key.
+ * The adapter never receives the user's PIN.
+ */
+export type ServerProfileSealer = Readonly<{
+    seal(cleartext: string, aad: string): Promise<string>;
+    unseal(ciphertext: string, aad: string): Promise<string>;
+}>;
+/** Persisted scrypt work factor. The salt and parameters are public metadata. */
+export type ProfileScryptParameters = Readonly<{
+    name: 'scrypt';
+    saltBase64Url: string;
+    cost: number;
+    blockSize: number;
+    parallelization: number;
+    keyLength: 32;
+}>;
+/**
+ * Portable v1 envelope for a profile secret.
+ *
+ * `ciphertext` contains the secret encrypted by a random DEK. The host first
+ * wraps that DEK; the PIN-derived key then encrypts the host-wrapped value.
+ * Opening therefore requires both factors without exposing either factor to
+ * the other adapter.
+ */
+export type PinProtectedProfileSecret = Readonly<{
+    version: 'gdc-pin-host-envelope-v1';
+    kdf: ProfileScryptParameters;
+    payload: AesGcmCiphertext;
+    pinWrappedHostDek: AesGcmCiphertext;
+}>;
+export type AesGcmCiphertext = Readonly<{
+    ivBase64Url: string;
+    ciphertextBase64Url: string;
+    tagBase64Url: string;
+}>;
+export type ProfileProtectionOptions = Readonly<{
+    cost?: number;
+    blockSize?: number;
+    parallelization?: number;
+}>;
+/** Distinguishes a wrong PIN from a host KMS outage or corrupted payload. */
+export declare class ProfilePinRejectedError extends Error {
+    constructor();
+}
+/**
+ * Encrypt one seed, private-key export or credential using a fresh DEK.
+ *
+ * The returned salt is intentionally stored in clear. Security comes from the
+ * PIN work factor, the independent host KEK and authenticated encryption, not
+ * from hiding the salt or algorithm parameters.
+ */
+export declare function protectServerProfileSecret(cleartext: string, pin: string, aad: string, hostSealer: ServerProfileSealer, options?: ProfileProtectionOptions): Promise<PinProtectedProfileSecret>;
+/**
+ * Open one protected profile secret using both PIN and host protection.
+ *
+ * The PIN layer is authenticated before the host adapter is called. A wrong
+ * PIN therefore neither reaches KMS nor becomes indistinguishable from a KMS
+ * availability failure in audit logs.
+ */
+export declare function openServerProfileSecret(envelope: PinProtectedProfileSecret, pin: string, aad: string, hostSealer: ServerProfileSealer): Promise<string>;

package/dist/server-profile-protection.js

@@ -0,0 +1,110 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto';
+/** Distinguishes a wrong PIN from a host KMS outage or corrupted payload. */
+export class ProfilePinRejectedError extends Error {
+    constructor() {
+        super('Profile PIN rejected.');
+        this.name = 'ProfilePinRejectedError';
+    }
+}
+/**
+ * Encrypt one seed, private-key export or credential using a fresh DEK.
+ *
+ * The returned salt is intentionally stored in clear. Security comes from the
+ * PIN work factor, the independent host KEK and authenticated encryption, not
+ * from hiding the salt or algorithm parameters.
+ */
+export async function protectServerProfileSecret(cleartext, pin, aad, hostSealer, options = {}) {
+    requirePin(pin);
+    const kdf = {
+        name: 'scrypt',
+        saltBase64Url: randomBytes(16).toString('base64url'),
+        cost: options.cost ?? 16384,
+        blockSize: options.blockSize ?? 8,
+        parallelization: options.parallelization ?? 1,
+        keyLength: 32,
+    };
+    const pinKey = derivePinKey(pin, kdf);
+    const dek = randomBytes(32);
+    const hostWrappedDek = await hostSealer.seal(dek.toString('base64url'), `${aad}:dek`);
+    try {
+        return {
+            version: 'gdc-pin-host-envelope-v1',
+            kdf,
+            payload: encryptAesGcm(Buffer.from(cleartext), dek, `${aad}:payload`),
+            pinWrappedHostDek: encryptAesGcm(Buffer.from(hostWrappedDek), pinKey, `${aad}:host-wrapped-dek`),
+        };
+    }
+    finally {
+        pinKey.fill(0);
+        dek.fill(0);
+    }
+}
+/**
+ * Open one protected profile secret using both PIN and host protection.
+ *
+ * The PIN layer is authenticated before the host adapter is called. A wrong
+ * PIN therefore neither reaches KMS nor becomes indistinguishable from a KMS
+ * availability failure in audit logs.
+ */
+export async function openServerProfileSecret(envelope, pin, aad, hostSealer) {
+    validateEnvelope(envelope);
+    const pinKey = derivePinKey(pin, envelope.kdf);
+    let hostWrappedDek;
+    try {
+        hostWrappedDek = decryptAesGcm(envelope.pinWrappedHostDek, pinKey, `${aad}:host-wrapped-dek`).toString('utf8');
+    }
+    catch {
+        throw new ProfilePinRejectedError();
+    }
+    finally {
+        pinKey.fill(0);
+    }
+    const dek = Buffer.from(await hostSealer.unseal(hostWrappedDek, `${aad}:dek`), 'base64url');
+    try {
+        if (dek.length !== 32)
+            throw new Error('Profile host returned an invalid DEK.');
+        return decryptAesGcm(envelope.payload, dek, `${aad}:payload`).toString('utf8');
+    }
+    finally {
+        dek.fill(0);
+    }
+}
+function derivePinKey(pin, parameters) {
+    requirePin(pin);
+    return scryptSync(pin, Buffer.from(parameters.saltBase64Url, 'base64url'), parameters.keyLength, {
+        N: parameters.cost,
+        r: parameters.blockSize,
+        p: parameters.parallelization,
+        maxmem: Math.max(64 * 1024 * 1024, 256 * parameters.cost * parameters.blockSize),
+    });
+}
+function encryptAesGcm(cleartext, key, aad) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    cipher.setAAD(Buffer.from(aad));
+    const ciphertext = Buffer.concat([cipher.update(cleartext), cipher.final()]);
+    return {
+        ivBase64Url: iv.toString('base64url'),
+        ciphertextBase64Url: ciphertext.toString('base64url'),
+        tagBase64Url: cipher.getAuthTag().toString('base64url'),
+    };
+}
+function decryptAesGcm(value, key, aad) {
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(value.ivBase64Url, 'base64url'));
+    decipher.setAAD(Buffer.from(aad));
+    decipher.setAuthTag(Buffer.from(value.tagBase64Url, 'base64url'));
+    return Buffer.concat([
+        decipher.update(Buffer.from(value.ciphertextBase64Url, 'base64url')),
+        decipher.final(),
+    ]);
+}
+function requirePin(pin) {
+    if (String(pin).length < 6)
+        throw new Error('Production profile PIN must contain at least 6 characters.');
+}
+function validateEnvelope(value) {
+    if (value?.version !== 'gdc-pin-host-envelope-v1' || value.kdf?.name !== 'scrypt') {
+        throw new Error('Unsupported protected profile envelope.');
+    }
+}