gdc-sdk-node-ts 2.9.10 → 2.9.12

package/dist/individual-onboarding.d.ts

@@ -28,8 +28,15 @@ export type IndividualOrganizationConfirmOrderInput = {
 export type IndividualOrganizationOrderResult = SubmitAndPollResult & Readonly<{
     activationCode: string;
     /**
-     * Governed RelatedPerson identifier automatically materialized by GW for
-     * the principal Organization owner/controller.
+     * Governed `RelatedPerson.identifier` automatically materialized by GW for
+     * the principal Organization owner/controller. GW reuses the bare UUID from
+     * `Organization.owner.identifier.value`; document helpers expose it as an
+     * `urn:uuid:<UUID>` FHIR reference only when a reference is required.
+     */
+    controllerRelatedPersonIdentifier: string;
+    /**
+     * @deprecated Use `controllerRelatedPersonIdentifier`, which states the
+     * resource represented by this identifier.
      */
     controllerAssignmentIdentifier: string;
 }>;

package/dist/individual-onboarding.js

@@ -44,7 +44,12 @@ export async function confirmIndividualOrganizationOrderWithDeps(deps) {
     if (!controllerAssignmentIdentifier) {
         throw new Error('confirmIndividualOrganizationOrder failed: missing automatic controller RESPRSN assignment in GW Order response.');
     }
-    return { ...order, activationCode, controllerAssignmentIdentifier };
+    return {
+        ...order,
+        activationCode,
+        controllerRelatedPersonIdentifier: controllerAssignmentIdentifier,
+        controllerAssignmentIdentifier,
+    };
 }
 /**
  * Reads the opaque controller activation code from a completed individual

package/dist/individual-start.d.ts

@@ -53,6 +53,12 @@ export type IndividualOrganizationRegistrationInput = {
      * a product gateway extension.
      */
     controllerTelephone?: string;
+    /**
+     * Stable UUID of the principal controller/RESPRSN assignment. In a self
+     * registration this may be the same UUID already assigned to the person.
+     * Omit only for a brand-new assignment so the SDK creates it once.
+     */
+    controllerIdentifier?: string;
     controllerRole?: string;
     additionalClaims?: Record<string, unknown>;
     timeoutSeconds?: number;

package/dist/individual-start.js

@@ -1,6 +1,7 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { randomUUID } from 'node:crypto';
 import { ClaimsOfferSchemaorg, ClaimsOrganizationSchemaorg, ClaimsPersonSchemaorg, ClaimsServiceSchemaorg, } from 'gdc-common-utils-ts/constants';
-import { buildIndividualDidWeb, buildSecureIdValueIndividual, extractPrimaryClaims, readFamilyOrganizationSummaryFromResponseBody, SecureIdTypesIndividual, } from 'gdc-common-utils-ts';
+import { buildIndividualDidWeb, buildSecureIdValueIndividual, extractPrimaryClaims, normalizeUuid, readFamilyOrganizationSummaryFromResponseBody, SecureIdTypesIndividual, } from 'gdc-common-utils-ts';
 export { buildIndividualMemberDidWebFromPrivateIdentifiers } from 'gdc-common-utils-ts';
 import { GwCoreLifecycleRequestType } from './constants/lifecycle.js';
 import { resolvePollOptionsFromSeconds } from './poll-options.js';
@@ -32,10 +33,14 @@ export async function registerIndividualOrganizationWithDeps(deps) {
         throw new Error('registerIndividualOrganization requires controllerEmail, or controllerTelephone only for compatibility/extension flows.');
     }
     const controllerRole = String(deps.input.controllerRole || 'RESPRSN').trim();
+    const controllerIdentifier = canonicalControllerUuid(deps.input.controllerIdentifier
+        || deps.input.additionalClaims?.[ClaimsOrganizationSchemaorg.ownerIdentifierValue]
+        || randomUUID());
     const claims = {
         '@context': 'org.schema',
         ...(deps.input.additionalClaims || {}),
         [ClaimsOrganizationSchemaorg.alternateName]: alternateName,
+        [ClaimsOrganizationSchemaorg.ownerIdentifierValue]: controllerIdentifier,
         [ClaimsServiceSchemaorg.category]: deps.routeCtx.sector,
         [ClaimsPersonSchemaorg.hasOccupationalRoleValue]: controllerRole,
         ...(controllerEmail
@@ -93,6 +98,19 @@ export async function registerIndividualOrganizationWithDeps(deps) {
         identity: readIndividualOrganizationBootstrapIdentity(registration.poll.body),
     };
 }
+function canonicalControllerUuid(value) {
+    const hexadecimal = normalizeUuid(String(value || '').trim());
+    if (!hexadecimal) {
+        throw new TypeError('controllerIdentifier must be a UUID or urn:uuid identifier.');
+    }
+    return [
+        hexadecimal.slice(0, 8),
+        hexadecimal.slice(8, 12),
+        hexadecimal.slice(12, 16),
+        hexadecimal.slice(16, 20),
+        hexadecimal.slice(20),
+    ].join('-');
+}
 /** @deprecated Use `registerIndividualOrganizationWithDeps`. */
 export async function startIndividualOrganizationWithDeps(deps) {
     return registerIndividualOrganizationWithDeps(deps);

package/dist/orchestration/individual-controller-sdk.d.ts

@@ -9,6 +9,15 @@ import type { NodeCapability } from '../session.js';
 import type { IndividualOrganizationLifecycleInput } from 'gdc-sdk-core-ts';
 import type { BlockchainArtifactRegistrationInput, ClinicalBundleSearchInput, ClinicalSectionUpdateInput, SubjectSectionUpdateInput, ClinicalSummaryReadResult, ClinicalSummaryRequestInput, ClinicalSummaryUpdateInput, CommunicationIngestionInput, CommunicationParticipantRuntimeSearchInput, DigitalTwinGenerationInput, DigitalTwinSecondaryUseConsentInput, DigitalTwinSecondaryUseConsentResult, DigitalTwinSubjectLinkPurgeInput, DigitalTwinSubjectLinkPurgeResult, GrantProfessionalAccessInput, GrantProfessionalAccessResult, IndividualMemberLifecycleInput, IndividualMemberLicenseAddInput, IndividualMemberLicenseInvitationInput, IndividualMemberLicenseTransitionInput, IpsOrFhirImportInput, LicenseListRuntimeSearchInput, LicenseOfferRuntimeSearchInput, LicenseOrderRuntimeSearchInput, RevokeProfessionalAccessInput, RevokeProfessionalAccessResult, ProfessionalAccessRequestDecisionInput, ProfessionalAccessRequestSearchInput, RelatedPersonUpsertInput } from '../resource-operations.js';
 import type { SmartTokenExchangeResult, SmartTokenRequestInput } from '../smart-token.js';
+/** Profile-owned defaults applied to subject-section mutations after unlock. */
+export type IndividualControllerProfileDefaults = Readonly<{
+    attester: SubjectSectionUpdateInput['attester'];
+}>;
+/**
+ * High-level section input. An opened controller profile supplies its own
+ * protected RESPRSN attester; standalone facades must still provide one.
+ */
+export type IndividualControllerSubjectSectionUpdateInput = Omit<SubjectSectionUpdateInput, 'attester'> & Partial<Pick<SubjectSectionUpdateInput, 'attester'>>;
 /**
  * Individual-controller oriented facade over a `NodeRuntimeClient`.
  *
@@ -18,10 +27,11 @@ import type { SmartTokenExchangeResult, SmartTokenRequestInput } from '../smart-
 export declare class IndividualControllerSdk {
     private readonly client;
     private readonly capabilities?;
+    private readonly profileDefaults?;
     /**
      * @param client Runtime client implementation used to submit and poll GW flows.
      */
-    constructor(client: NodeRuntimeClient, capabilities?: readonly NodeCapability[] | undefined);
+    constructor(client: NodeRuntimeClient, capabilities?: readonly NodeCapability[] | undefined, profileDefaults?: IndividualControllerProfileDefaults | undefined);
     /**
      * Registers the personal organization/subject index and returns its Offer.
      * Wallet creation, activation exchange, DCR, and session opening are later
@@ -118,7 +128,7 @@ export declare class IndividualControllerSdk {
      * appointments or contracts, while preserving the indexed Composition
      * author/attester compatibility contract.
      */
-    updateSubjectSection(ctx: RouteContext, input: SubjectSectionUpdateInput): Promise<SubmitAndPollResult>;
+    updateSubjectSection(ctx: RouteContext, input: IndividualControllerSubjectSectionUpdateInput): Promise<SubmitAndPollResult>;
     /**
      * Updates the multi-section summary through a Composition-first document.
      * On a direct call, use the authenticated profile `actorDid` as `sender` and

package/dist/orchestration/individual-controller-sdk.js

@@ -18,9 +18,10 @@ export class IndividualControllerSdk {
     /**
      * @param client Runtime client implementation used to submit and poll GW flows.
      */
-    constructor(client, capabilities) {
+    constructor(client, capabilities, profileDefaults) {
         this.client = client;
         this.capabilities = capabilities;
+        this.profileDefaults = profileDefaults;
     }
     /**
      * Registers the personal organization/subject index and returns its Offer.
@@ -173,7 +174,11 @@ export class IndividualControllerSdk {
      */
     updateSubjectSection(ctx, input) {
         assertFacadeCapability(this.capabilities, ActorCapabilities.IndividualIngestCommunication, ActorKinds.IndividualController, 'updateSubjectSection');
-        return requireClientMethod(this.client, 'updateSubjectSection')(ctx, input);
+        const attester = input.attester || this.profileDefaults?.attester;
+        if (!attester) {
+            throw new Error('updateSubjectSection requires an explicit attester unless the facade comes from an opened controller profile.');
+        }
+        return requireClientMethod(this.client, 'updateSubjectSection')(ctx, { ...input, attester });
     }
     /**
      * Updates the multi-section summary through a Composition-first document.

package/dist/organization-registration-authorization.d.ts

@@ -0,0 +1,16 @@
+import type { VerifiableCredentialV2 } from 'gdc-common-utils-ts/models/verifiable-credential';
+import type { IWallet, WalletExecutionContext, WalletKeySelection } from 'gdc-sdk-core-ts';
+/** Input required to add one human-authorizer proof to the out-of-band VC. */
+export type SignOrganizationRegistrationAuthorizationInput = Readonly<{
+    credential: VerifiableCredentialV2;
+    wallet: IWallet;
+    context: WalletExecutionContext;
+    key: WalletKeySelection;
+    verificationMethod: string;
+    createdAt?: string;
+}>;
+/**
+ * Adds one detached JWS proof made by the already-unlocked professional
+ * profile. The browser never receives the private key or clear wallet seed.
+ */
+export declare function signOrganizationRegistrationAuthorizationCredential(input: SignOrganizationRegistrationAuthorizationInput): Promise<VerifiableCredentialV2>;

package/dist/organization-registration-authorization.js

@@ -0,0 +1,34 @@
+import { canonicalizeOrganizationRegistrationAuthorizationCredential, } from 'gdc-common-utils-ts/utils/organization-registration-authorization';
+/**
+ * Adds one detached JWS proof made by the already-unlocked professional
+ * profile. The browser never receives the private key or clear wallet seed.
+ */
+export async function signOrganizationRegistrationAuthorizationCredential(input) {
+    if (!input.wallet.signDetachedJws) {
+        throw new Error('Wallet does not support detached organization authorization proofs.');
+    }
+    const verificationMethod = String(input.verificationMethod || '').trim();
+    if (!verificationMethod)
+        throw new Error('Organization authorization proof requires verificationMethod.');
+    const payload = canonicalizeOrganizationRegistrationAuthorizationCredential(input.credential);
+    const jws = await input.wallet.signDetachedJws(input.context, {
+        payload,
+        header: { typ: 'application/vc+ld+json' },
+        key: input.key,
+    });
+    const existingProofs = Array.isArray(input.credential.proof)
+        ? input.credential.proof
+        : input.credential.proof
+            ? [input.credential.proof]
+            : [];
+    return {
+        ...input.credential,
+        proof: [...existingProofs, {
+                type: 'JsonWebSignature2020',
+                created: input.createdAt || new Date().toISOString(),
+                proofPurpose: 'contractAgreement',
+                verificationMethod,
+                jws,
+            }],
+    };
+}

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

@@ -11,7 +11,8 @@ import { ProfessionalSdk } from './orchestration/professional-sdk.js';
 import { DigitalTwinSdk } from './orchestration/digital-twin-sdk.js';
 import type { SmartTokenExchangeResult } from './smart-token.js';
 import type { DigitalTwinSearchInput, DigitalTwinSearchResult } from './digital-twin.js';
-import type { RouteContext } from './individual-onboarding.js';
+import type { IndividualOrganizationOrderResult, RouteContext } from './individual-onboarding.js';
+import type { IndividualOrganizationRegistrationResult } from './individual-start.js';
 import type { HostRouteContext } from './host-onboarding.js';
 import type { SecureDidcommTransportAdapter } from 'gdc-sdk-core-ts';
 import { type PinProtectedProfileSecret, type ProfileProtectionOptions, type ServerProfileSealer } from './server-profile-protection.js';
@@ -145,6 +146,13 @@ export type ServerProfileEnrollmentInput = Readonly<{
     idToken: string;
     /** One-time code returned by the completed organization flow or employee `License/_issue`. */
     activationCode: string;
+    /**
+     * Principal controller identifier projected by the SDK from
+     * `Organization.owner.identifier.value` and the matching automatic
+     * `RelatedPerson.identifier`. Individual-controller callers pass this
+     * identifier; the SDK constructs protected document-attester metadata.
+     */
+    controllerRelatedPersonIdentifier?: string;
     /**
      * Optional explicit installation identity. Normally omit it so the SDK
      * derives the identity from the wallet key it creates for this profile.
@@ -292,6 +300,20 @@ export type OpenedServerIndividualController = Readonly<{
     session: ResolvedServerProfileSession;
     profile: ServerProfileRecord;
     sdk: IndividualControllerSdk;
+    /** Returns the protected RelatedPerson URI for FHIR document attestation. */
+    getAttesterUriForDocs(): string;
+}>;
+/** One-time self-controller enrollment. It never opens a working session. */
+export type ServerSelfIndividualControllerEnrollmentInput = Readonly<{
+    ownerId: string;
+    profileId: string;
+    registration: Pick<IndividualOrganizationRegistrationResult, 'identity'>;
+    order: Pick<IndividualOrganizationOrderResult, 'activationCode' | 'controllerRelatedPersonIdentifier'>;
+    routeContext: RouteContext;
+    pin: string;
+    idToken: string;
+    redirectUris: string[];
+    clientName: string;
 }>;
 /** Server-owned role evidence used to sign a fresh professional VP. */
 export type ServerProfessionalProofInput = Readonly<{
@@ -383,6 +405,13 @@ export declare class ServerProfileSessionManager {
          */
         sourceAuthor?: ClinicalSourceAuthorSelection;
     }>): Promise<ClinicalCreatorIpsExport>;
+    /**
+     * Enrolls the controller of a self-managed individual from SDK-owned
+     * registration and Order projections. The caller never parses claims or
+     * constructs FHIR attester metadata, and this operation does not open the
+     * resulting profile.
+     */
+    enrollSelfIndividualController(input: ServerSelfIndividualControllerEnrollmentInput): Promise<ServerProfileRecord>;
     enroll(input: ServerProfileEnrollmentInput): Promise<ServerProfileRecord>;
     /**
      * Rotates an employee wallet after a fresh OTP-authenticated GW recovery.

package/dist/server-profile-session.js

@@ -24,20 +24,23 @@ import { ProfilePinRejectedError, openServerProfileSecret, protectServerProfileS
  * RelatedPerson/PractitionerRole assignment returned by GW.
  */
 export function buildProfileAttester(input) {
-    const hexadecimal = normalizeUuid(String(input.assignmentIdentifier || '').trim());
-    if (!hexadecimal) {
-        throw new TypeError('Profile attester assignmentIdentifier must be a UUID returned by RelatedPerson or PractitionerRole data.');
-    }
-    const uuid = [
-        hexadecimal.slice(0, 8),
-        hexadecimal.slice(8, 12),
-        hexadecimal.slice(12, 16),
-        hexadecimal.slice(16, 20),
-        hexadecimal.slice(20),
-    ].join('-');
+    const assignmentIdentifier = String(input.assignmentIdentifier || '').trim();
+    const hexadecimal = normalizeUuid(assignmentIdentifier);
+    const reference = hexadecimal
+        ? `${UrnPrefixes.Uuid}${[
+            hexadecimal.slice(0, 8),
+            hexadecimal.slice(8, 12),
+            hexadecimal.slice(12, 16),
+            hexadecimal.slice(16, 20),
+            hexadecimal.slice(20),
+        ].join('-')}`
+        : assignmentIdentifier;
+    if (!/^(?:urn:|https?:\/\/)/i.test(reference)) {
+        throw new TypeError('Profile attester assignmentIdentifier must be a governed RelatedPerson or PractitionerRole URI.');
+    }
     return Object.freeze({
         mode: input.mode,
-        party: Object.freeze({ reference: `${UrnPrefixes.Uuid}${uuid}` }),
+        party: Object.freeze({ reference }),
     });
 }
 /**
@@ -76,11 +79,46 @@ export class ServerProfileSessionManager {
     async exportClinicalCreatorIps(input) {
         return exportServerProfileClinicalCreatorIps(await this.requireOwnedProfile(input.ownerId, input.profileId), { sourceAuthor: input.sourceAuthor });
     }
+    /**
+     * Enrolls the controller of a self-managed individual from SDK-owned
+     * registration and Order projections. The caller never parses claims or
+     * constructs FHIR attester metadata, and this operation does not open the
+     * resulting profile.
+     */
+    async enrollSelfIndividualController(input) {
+        const identity = input.registration.identity;
+        if (!identity) {
+            throw new Error('Self individual-controller enrollment requires the registered individual identity.');
+        }
+        return this.enroll({
+            ownerId: input.ownerId,
+            profileId: input.profileId,
+            actorKind: ActorKinds.IndividualController,
+            actorMode: 'self',
+            actorDid: identity.subjectDid,
+            profileDid: identity.subjectDid,
+            providerDid: identity.providerDidWeb,
+            routeContext: input.routeContext,
+            allowedSubjectDids: [identity.subjectDid],
+            pin: input.pin,
+            idToken: input.idToken,
+            activationCode: input.order.activationCode,
+            controllerRelatedPersonIdentifier: input.order.controllerRelatedPersonIdentifier,
+            redirectUris: input.redirectUris,
+            clientName: input.clientName,
+        });
+    }
     async enroll(input) {
         const normalizedClinicalCreatorBinding = input.clinicalCreatorBinding
             ? normalizeClinicalCreatorBinding(input.clinicalCreatorBinding)
             : undefined;
-        const attester = input.attester || (normalizedClinicalCreatorBinding
+        const controllerAttester = input.controllerRelatedPersonIdentifier
+            ? buildProfileAttester({
+                assignmentIdentifier: input.controllerRelatedPersonIdentifier,
+                mode: CompositionAttesterModes.Personal,
+            })
+            : undefined;
+        const attester = controllerAttester || input.attester || (normalizedClinicalCreatorBinding
             ? buildProfileAttester({
                 assignmentIdentifier: normalizedClinicalCreatorBinding.authorIdentifier,
                 mode: normalizedClinicalCreatorBinding.kind === FhirIpsCreatorKinds.Professional
@@ -562,6 +600,10 @@ export class ServerProfileSessionManager {
             || (profile.actorMode !== 'self' && profile.actorMode !== 'controller')) {
             throw new Error('Profile is not an individual controller.');
         }
+        const profileAttester = profile.attester;
+        if (!profileAttester) {
+            throw new Error('The opened individual-controller profile has no RelatedPerson attester.');
+        }
         const client = new NodeHttpClient({
             baseUrl: this.options.gatewayBaseUrl,
             ctx: profile.routeContext,
@@ -571,7 +613,20 @@ export class ServerProfileSessionManager {
             transportProfile: TransportProfiles.DidcommEncryptedForm,
             secureTransportAdapter: session.secureTransportAdapter,
         });
-        return { session, profile, sdk: new IndividualControllerSdk(client) };
+        return {
+            session,
+            profile,
+            sdk: new IndividualControllerSdk(client, undefined, {
+                attester: profileAttester,
+            }),
+            getAttesterUriForDocs: () => {
+                const reference = String(profileAttester.party.reference || '').trim();
+                if (!reference) {
+                    throw new Error('The opened individual-controller profile has no RelatedPerson attester URI.');
+                }
+                return reference;
+            },
+        };
     }
     /**
      * Opens the high-level organization-controller API without exposing wallet,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-sdk-node-ts",
-  "version": "2.9.10",
+  "version": "2.9.12",
   "description": "Next-generation Node runtime package for the GDC SDK family",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",