gdc-common-utils-ts 1.24.3 → 2.0.1

package/dist/utils/individual-organization-lifecycle.d.ts

@@ -47,7 +47,7 @@ export type IndividualOrganizationLifecyclePayload = Readonly<{
         data: IndividualOrganizationLifecycleDataEntry[];
     };
 }>;
-export type IndividualOrganizationLifecycleDraftState = Readonly<{
+export type IndividualOrganizationLifecycleEditorState = Readonly<{
     operation: IndividualOrganizationLifecycleOperation;
     claims: IndividualOrganizationLifecycleClaims;
     resourceId?: string;
@@ -76,7 +76,7 @@ export declare function buildCurrentIndividualOrganizationLifecycleDataEntry(inp
  */
 export declare function buildCurrentIndividualOrganizationLifecyclePayload(input: IndividualOrganizationLifecyclePayloadInput): IndividualOrganizationLifecyclePayload;
 /**
- * High-level chainable draft for hosted individual/family lifecycle work.
+ * High-level chainable editor for hosted individual/family lifecycle work.
  *
  * Teaching goal:
  * - authors one canonical flat `org.schema.Organization.*` claim set
@@ -84,11 +84,12 @@ export declare function buildCurrentIndividualOrganizationLifecyclePayload(input
  * - can emit either a semantic lifecycle message or the current GW CORE
  *   payload shape used by `sdk-node`
  */
-export declare class IndividualOrganizationLifecycleDraft {
+export declare class IndividualOrganizationLifecycleEditor {
     private draft;
-    constructor(initial?: Partial<IndividualOrganizationLifecycleDraftState>);
+    constructor(initial?: Partial<IndividualOrganizationLifecycleEditorState>);
     mergeClaims(claims: IndividualOrganizationLifecycleClaims): this;
     setClaims(claims: IndividualOrganizationLifecycleClaims): this;
+    setContext(context: string): this;
     setIdentifier(identifier: string): this;
     setAlternateName(alternateName: string): this;
     setOwnerEmail(email: string): this;
@@ -96,8 +97,17 @@ export declare class IndividualOrganizationLifecycleDraft {
     setResourceId(resourceId?: string): this;
     setRequestType(requestType: string): this;
     setThreadId(thid: string): this;
+    getIdentifier(): string | undefined;
+    getContext(): string | undefined;
+    getAlternateName(): string | undefined;
+    getOwnerEmail(): string | undefined;
+    getOperation(): IndividualOrganizationLifecycleOperation;
+    getResourceId(): string | undefined;
+    getRequestType(): string | undefined;
+    getThreadId(): string | undefined;
     getClaims(): IndividualOrganizationLifecycleClaims;
-    getDraft(): IndividualOrganizationLifecycleDraftState;
+    getState(): IndividualOrganizationLifecycleEditorState;
+    getEditorState(): IndividualOrganizationLifecycleEditorState;
     toSemanticMessage(): IndividualOrganizationLifecycleSemanticMessage;
     buildCurrentGwDataEntry(): IndividualOrganizationLifecycleDataEntry;
     buildCurrentGwPayload(): IndividualOrganizationLifecyclePayload;

package/dist/utils/individual-organization-lifecycle.js

@@ -17,7 +17,10 @@ function normalizeText(value) {
 function normalizeDraft(draft) {
     return {
         operation: draft?.operation || IndividualOrganizationLifecycleOperations.Disable,
-        claims: cloneClaims(draft?.claims),
+        claims: {
+            '@context': 'org.schema',
+            ...cloneClaims(draft?.claims),
+        },
         resourceId: normalizeText(draft?.resourceId),
         requestType: normalizeText(draft?.requestType),
         thid: normalizeText(draft?.thid),
@@ -75,7 +78,7 @@ export function buildCurrentIndividualOrganizationLifecyclePayload(input) {
     };
 }
 /**
- * High-level chainable draft for hosted individual/family lifecycle work.
+ * High-level chainable editor for hosted individual/family lifecycle work.
  *
  * Teaching goal:
  * - authors one canonical flat `org.schema.Organization.*` claim set
@@ -83,7 +86,7 @@ export function buildCurrentIndividualOrganizationLifecyclePayload(input) {
  * - can emit either a semantic lifecycle message or the current GW CORE
  *   payload shape used by `sdk-node`
  */
-export class IndividualOrganizationLifecycleDraft {
+export class IndividualOrganizationLifecycleEditor {
     draft;
     constructor(initial) {
         this.draft = normalizeDraft(initial);
@@ -96,6 +99,15 @@ export class IndividualOrganizationLifecycleDraft {
         this.draft = patchDraft(this.draft, { claims });
         return this;
     }
+    setContext(context) {
+        this.draft = patchDraft(this.draft, {
+            claims: {
+                ...this.draft.claims,
+                '@context': String(context).trim(),
+            },
+        });
+        return this;
+    }
     setIdentifier(identifier) {
         this.draft = patchDraft(this.draft, {
             claims: {
@@ -139,12 +151,47 @@ export class IndividualOrganizationLifecycleDraft {
         this.draft = patchDraft(this.draft, { thid });
         return this;
     }
+    getIdentifier() {
+        const value = this.draft.claims[ClaimsOrganizationSchemaorg.identifier];
+        const normalized = normalizeText(value);
+        return normalized || undefined;
+    }
+    getContext() {
+        const value = this.draft.claims['@context'];
+        const normalized = normalizeText(value);
+        return normalized || undefined;
+    }
+    getAlternateName() {
+        const value = this.draft.claims[ClaimsOrganizationSchemaorg.alternateName];
+        const normalized = normalizeText(value);
+        return normalized || undefined;
+    }
+    getOwnerEmail() {
+        const value = this.draft.claims[ClaimsOrganizationSchemaorg.ownerEmail];
+        const normalized = normalizeText(value);
+        return normalized || undefined;
+    }
+    getOperation() {
+        return this.draft.operation;
+    }
+    getResourceId() {
+        return normalizeText(this.draft.resourceId) || undefined;
+    }
+    getRequestType() {
+        return normalizeText(this.draft.requestType) || undefined;
+    }
+    getThreadId() {
+        return normalizeText(this.draft.thid) || undefined;
+    }
     getClaims() {
         return cloneClaims(this.draft.claims);
     }
-    getDraft() {
+    getState() {
         return normalizeDraft(this.draft);
     }
+    getEditorState() {
+        return this.getState();
+    }
     toSemanticMessage() {
         return {
             operation: this.draft.operation,
@@ -156,7 +203,7 @@ export class IndividualOrganizationLifecycleDraft {
     buildCurrentGwDataEntry() {
         const requestType = normalizeText(this.draft.requestType);
         if (!requestType) {
-            throw new Error('IndividualOrganizationLifecycleDraft.buildCurrentGwDataEntry requires requestType.');
+            throw new Error('IndividualOrganizationLifecycleEditor.buildCurrentGwDataEntry requires requestType.');
         }
         return buildCurrentIndividualOrganizationLifecycleDataEntry({
             claims: this.getClaims(),
@@ -167,7 +214,7 @@ export class IndividualOrganizationLifecycleDraft {
     buildCurrentGwPayload() {
         const requestType = normalizeText(this.draft.requestType);
         if (!requestType) {
-            throw new Error('IndividualOrganizationLifecycleDraft.buildCurrentGwPayload requires requestType.');
+            throw new Error('IndividualOrganizationLifecycleEditor.buildCurrentGwPayload requires requestType.');
         }
         return {
             thid: this.draft.thid || createLifecycleThreadId(this.draft.operation),

package/dist/utils/interoperable-resource-operation.d.ts

@@ -16,7 +16,7 @@ export declare const InteroperableLifecycleStatuses: Readonly<{
 }>;
 export type InteroperableLifecycleStatus = typeof InteroperableLifecycleStatuses[keyof typeof InteroperableLifecycleStatuses];
 export type InteroperableSearchParams = Readonly<Record<string, SearchParameterPrimitive | undefined>>;
-export type InteroperableResourceOperationDraft = Readonly<{
+export type InteroperableResourceOperationState = Readonly<{
     resourceType: string;
     identifierClaimKey: string;
     identifierValue?: string;
@@ -45,7 +45,7 @@ export interface InteroperableResourceOperationEditor {
     mergeClaims(claims: Record<string, unknown>): InteroperableResourceOperationEditor;
     setLifecycleStatus(value: InteroperableLifecycleStatus): InteroperableResourceOperationEditor;
     importFhirResource(resource: FhirResource): InteroperableResourceOperationEditor;
-    getDraft(): InteroperableResourceOperationDraft;
+    getState(): InteroperableResourceOperationState;
     getBusinessIdentifier(): string | undefined;
     getClaims(): Record<string, unknown>;
     buildLifecycleResource(): {
@@ -140,7 +140,7 @@ export declare function buildInteroperableSearchPath(resourceType: string): stri
  * - `resource.meta.status` carries lifecycle state without overloading
  *   resource-specific FHIR fields such as `status` or `active`
  */
-export declare function buildLifecycleOperationResource(draft: InteroperableResourceOperationDraft): {
+export declare function buildLifecycleOperationResource(state: InteroperableResourceOperationState): {
     resourceType: string;
     id?: string;
     identifier?: Array<{
@@ -155,4 +155,4 @@ export declare function buildLifecycleOperationResource(draft: InteroperableReso
 /**
  * Creates the shared chainable editor for search/disable/purge request shapes.
  */
-export declare function createInteroperableResourceOperationEditor(initial?: Partial<InteroperableResourceOperationDraft>): InteroperableResourceOperationEditor;
+export declare function createInteroperableResourceOperationEditor(initial?: Partial<InteroperableResourceOperationState>): InteroperableResourceOperationEditor;

package/dist/utils/interoperable-resource-operation.js

@@ -24,23 +24,23 @@ function cloneClaims(claims) {
 function resolveDefaultIdentifierClaimKey(resourceType) {
     return `${String(resourceType || '').trim()}.identifier`;
 }
-function normalizeDraft(draft) {
-    const resourceType = normalizeText(draft?.resourceType) || 'Resource';
+function normalizeDraft(state) {
+    const resourceType = normalizeText(state?.resourceType) || 'Resource';
     return {
         resourceType,
-        identifierClaimKey: normalizeText(draft?.identifierClaimKey) || resolveDefaultIdentifierClaimKey(resourceType),
-        identifierValue: normalizeText(draft?.identifierValue),
-        identifierSystem: normalizeText(draft?.identifierSystem),
-        resourceId: normalizeText(draft?.resourceId),
-        claims: cloneClaims(draft?.claims),
-        lifecycleStatus: draft?.lifecycleStatus,
+        identifierClaimKey: normalizeText(state?.identifierClaimKey) || resolveDefaultIdentifierClaimKey(resourceType),
+        identifierValue: normalizeText(state?.identifierValue),
+        identifierSystem: normalizeText(state?.identifierSystem),
+        resourceId: normalizeText(state?.resourceId),
+        claims: cloneClaims(state?.claims),
+        lifecycleStatus: state?.lifecycleStatus,
     };
 }
-function patchDraft(draft, patch) {
+function patchDraft(state, patch) {
     return normalizeDraft({
-        ...draft,
+        ...state,
         ...patch,
-        claims: patch.claims ? cloneClaims(patch.claims) : cloneClaims(draft.claims),
+        claims: patch.claims ? cloneClaims(patch.claims) : cloneClaims(state.claims),
     });
 }
 /**
@@ -118,23 +118,23 @@ export function buildInteroperableSearchPath(resourceType) {
  * - `resource.meta.status` carries lifecycle state without overloading
  *   resource-specific FHIR fields such as `status` or `active`
  */
-export function buildLifecycleOperationResource(draft) {
-    const claims = cloneClaims(draft.claims);
-    if (draft.identifierValue && !normalizeText(claims[draft.identifierClaimKey])) {
-        claims[draft.identifierClaimKey] = draft.identifierValue;
+export function buildLifecycleOperationResource(state) {
+    const claims = cloneClaims(state.claims);
+    if (state.identifierValue && !normalizeText(claims[state.identifierClaimKey])) {
+        claims[state.identifierClaimKey] = state.identifierValue;
     }
     return {
-        resourceType: draft.resourceType,
-        ...(draft.resourceId ? { id: draft.resourceId } : {}),
-        ...(draft.identifierValue ? {
+        resourceType: state.resourceType,
+        ...(state.resourceId ? { id: state.resourceId } : {}),
+        ...(state.identifierValue ? {
             identifier: [{
-                    value: draft.identifierValue,
-                    ...(draft.identifierSystem ? { system: draft.identifierSystem } : {}),
+                    value: state.identifierValue,
+                    ...(state.identifierSystem ? { system: state.identifierSystem } : {}),
                 }],
         } : {}),
         meta: {
             claims,
-            ...(draft.lifecycleStatus ? { status: draft.lifecycleStatus } : {}),
+            ...(state.lifecycleStatus ? { status: state.lifecycleStatus } : {}),
         },
     };
 }
@@ -192,7 +192,7 @@ export function createInteroperableResourceOperationEditor(initial) {
             });
             return editor;
         },
-        getDraft() {
+        getState() {
             return normalizeDraft(draft);
         },
         getBusinessIdentifier() {

package/dist/utils/jwk-thumbprint.d.ts

@@ -0,0 +1,40 @@
+import { PublicJwk } from '../interfaces/Cryptography.types';
+/**
+ * Minimal RSA public JWK shape needed for RFC 7638 thumbprint derivation.
+ */
+export type RsaPublicJwk = {
+    kty: 'RSA';
+    e: string;
+    n: string;
+    kid?: string;
+    alg?: string;
+    use?: string;
+};
+/**
+ * Public JWK shapes supported by the RFC 7638 thumbprint helpers.
+ *
+ * Notes:
+ * - classic EC keys are identified by `kty: 'EC'` and use `crv`, `x`, `y`
+ * - this includes `secp256k1`, represented as `crv: 'secp256k1'`
+ * - ML-DSA keys are represented in this codebase as `kty: 'AKP'` and use
+ *   `alg` plus `pub`; they do not use `crv`
+ */
+export type ThumbprintableJwk = PublicJwk | RsaPublicJwk;
+/**
+ * Computes the RFC 7638 JWK thumbprint as a bare base64url string.
+ *
+ * Canonical fields per supported key family:
+ * - `EC`: `kty`, `crv`, `x`, `y`
+ * - `RSA`: `kty`, `e`, `n`
+ * - `OKP`: `kty`, `crv`, `x`
+ * - `AKP` / ML-DSA: `kty`, `alg`, `pub`
+ *
+ * For classical EC keys, the curve is taken from `crv`, so keys such as
+ * `secp256k1` are handled naturally through `crv: 'secp256k1'`.
+ */
+export declare function computeRfc7638JwkThumbprint(jwk: ThumbprintableJwk): string;
+/**
+ * Returns the RFC 9278 thumbprint URI form:
+ * `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
+ */
+export declare function toJwkThumbprintSha256Urn(jwk: ThumbprintableJwk): string;

package/dist/utils/jwk-thumbprint.js

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+import { UrnPrefixes } from '../constants/urn.js';
+function canonicalizeForThumbprint(jwk) {
+    const keys = Object.keys(jwk).sort();
+    const parts = keys.map((key) => `"${key}":${JSON.stringify(jwk[key])}`);
+    return `{${parts.join(',')}}`;
+}
+function toBaseThumbprintJwk(jwk) {
+    if (jwk.kty === 'EC') {
+        const { crv, x, y } = jwk;
+        if (!crv || !x || !y)
+            throw new Error('EC JWK thumbprint requires crv, x and y.');
+        return { kty: 'EC', crv, x, y };
+    }
+    if (jwk.kty === 'RSA') {
+        const { e, n } = jwk;
+        if (!e || !n)
+            throw new Error('RSA JWK thumbprint requires e and n.');
+        return { kty: 'RSA', e, n };
+    }
+    if (jwk.kty === 'OKP') {
+        const { crv, x } = jwk;
+        if (!crv || !x)
+            throw new Error('OKP JWK thumbprint requires crv and x.');
+        return { kty: 'OKP', crv, x };
+    }
+    if (jwk.kty === 'AKP') {
+        const { alg, pub } = jwk;
+        if (!alg || !pub)
+            throw new Error('AKP JWK thumbprint requires alg and pub.');
+        return { kty: 'AKP', alg, pub };
+    }
+    throw new Error(`Unsupported JWK kty for RFC7638 thumbprint: ${jwk.kty || 'unknown'}`);
+}
+/**
+ * Computes the RFC 7638 JWK thumbprint as a bare base64url string.
+ *
+ * Canonical fields per supported key family:
+ * - `EC`: `kty`, `crv`, `x`, `y`
+ * - `RSA`: `kty`, `e`, `n`
+ * - `OKP`: `kty`, `crv`, `x`
+ * - `AKP` / ML-DSA: `kty`, `alg`, `pub`
+ *
+ * For classical EC keys, the curve is taken from `crv`, so keys such as
+ * `secp256k1` are handled naturally through `crv: 'secp256k1'`.
+ */
+export function computeRfc7638JwkThumbprint(jwk) {
+    const canonical = canonicalizeForThumbprint(toBaseThumbprintJwk(jwk));
+    return createHash('sha256').update(canonical).digest('base64url');
+}
+/**
+ * Returns the RFC 9278 thumbprint URI form:
+ * `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
+ */
+export function toJwkThumbprintSha256Urn(jwk) {
+    return `${UrnPrefixes.JwkThumbprintSha256KeyId}${computeRfc7638JwkThumbprint(jwk)}`;
+}

package/dist/utils/legal-organization-onboarding.d.ts

@@ -0,0 +1,97 @@
+import { ClaimsOrganizationSchemaorg } from '../constants/schemaorg';
+import { ClaimsRecord } from '../models/resource-document';
+export type LegalOrganizationOnboardingErrorCode = 'MISSING_IDENTIFIER_OR_TAX_ID' | 'EXPLICIT_ALTERNATE_NAME_NOT_ALLOWED';
+export type LegalOrganizationOnboardingValidationError = {
+    code: LegalOrganizationOnboardingErrorCode;
+    message: string;
+    claimPaths: string[];
+};
+export type ValidateLegalOrganizationOnboardingClaimsOptions = {
+    /**
+     * When `false` (default), `alternateName` is treated as a compatibility alias
+     * derived from the canonical legal identifier. Callers may still send an
+     * explicit value, but it must match the final normalized
+     * `Organization.identifier.value`.
+     *
+     * When `true`, callers may keep an explicit `alternateName` that differs from
+     * `Organization.identifier.value`.
+     */
+    allowExplicitAlternateNameForTenantId?: boolean;
+};
+export type ValidateLegalOrganizationOnboardingClaimsResult = {
+    ok: boolean;
+    errors: LegalOrganizationOnboardingValidationError[];
+    missingClaims: string[];
+    normalizedClaims: ClaimsRecord;
+    derived: {
+        identifierValueFromTaxId: boolean;
+        alternateNameFromIdentifierValue: boolean;
+    };
+};
+/**
+ * JSON Schema for legal-organization onboarding claims used by high-level SDK
+ * forms and assistants before they submit anything to GW CORE.
+ *
+ * Contract:
+ * - one of `Organization.identifier.value` or `Organization.taxID` must be
+ *   provided
+ * - `alternateName` is optional at input time because current GW compatibility
+ *   may derive it from the canonical legal identifier
+ * - callers that want stricter tenant-alias behavior must still run the
+ *   validator below because JSON Schema alone cannot express the
+ *   runtime option `allowExplicitAlternateNameForTenantId`
+ */
+export declare const LEGAL_ORGANIZATION_ONBOARDING_JSON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://gdc/common-utils/legal-organization-onboarding.schema.json";
+    readonly title: "Legal Organization Onboarding Claims";
+    readonly type: "object";
+    readonly properties: {
+        readonly '@context': {
+            readonly type: "string";
+            readonly enum: readonly ["org.schema"];
+        };
+        readonly "org.schema.Organization.identifier.value": {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Canonical legal identifier used by onboarding and tenant normalization.";
+        };
+        readonly "org.schema.Organization.taxID": {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Compatibility tax identifier that may backfill Organization.identifier.value.";
+        };
+        readonly "org.schema.Organization.alternateName": {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly description: "Optional compatibility alias. If omitted, callers may derive it from Organization.identifier.value.";
+        };
+    };
+    readonly oneOf: readonly [{
+        readonly required: readonly [ClaimsOrganizationSchemaorg.identifierValue];
+    }, {
+        readonly required: readonly [ClaimsOrganizationSchemaorg.taxId];
+    }];
+    readonly additionalProperties: true;
+};
+/**
+ * Validates and normalizes legal-organization onboarding claims for SDKs,
+ * forms, and assistant-style data collection flows.
+ *
+ * Main behavior:
+ * - requires at least one of `Organization.identifier.value` or
+ *   `Organization.taxID`
+ * - if `identifier.value` is missing and `taxID` exists, copies
+ *   `taxID -> identifier.value`
+ * - if `alternateName` is missing and a canonical identifier exists, copies
+ *   `identifier.value -> alternateName`
+ * - when `allowExplicitAlternateNameForTenantId` is `false` (default),
+ *   rejects explicit `alternateName` values that differ from the final
+ *   canonical `identifier.value`
+ *
+ * The result shape is intentionally assistant-friendly:
+ * - `missingClaims` tells UI/voice flows what is still required
+ * - `normalizedClaims` shows the post-derivation claim set
+ * - `derived` explains which values were filled automatically
+ */
+export declare function validateLegalOrganizationOnboardingClaims(claims: ClaimsRecord, options?: ValidateLegalOrganizationOnboardingClaimsOptions): ValidateLegalOrganizationOnboardingClaimsResult;

package/dist/utils/legal-organization-onboarding.js

@@ -0,0 +1,128 @@
+import { ClaimsOrganizationSchemaorg } from '../constants/schemaorg.js';
+/**
+ * JSON Schema for legal-organization onboarding claims used by high-level SDK
+ * forms and assistants before they submit anything to GW CORE.
+ *
+ * Contract:
+ * - one of `Organization.identifier.value` or `Organization.taxID` must be
+ *   provided
+ * - `alternateName` is optional at input time because current GW compatibility
+ *   may derive it from the canonical legal identifier
+ * - callers that want stricter tenant-alias behavior must still run the
+ *   validator below because JSON Schema alone cannot express the
+ *   runtime option `allowExplicitAlternateNameForTenantId`
+ */
+export const LEGAL_ORGANIZATION_ONBOARDING_JSON_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://gdc/common-utils/legal-organization-onboarding.schema.json',
+    title: 'Legal Organization Onboarding Claims',
+    type: 'object',
+    properties: {
+        '@context': {
+            type: 'string',
+            enum: ['org.schema'],
+        },
+        [ClaimsOrganizationSchemaorg.identifierValue]: {
+            type: 'string',
+            minLength: 1,
+            description: 'Canonical legal identifier used by onboarding and tenant normalization.',
+        },
+        [ClaimsOrganizationSchemaorg.taxId]: {
+            type: 'string',
+            minLength: 1,
+            description: 'Compatibility tax identifier that may backfill Organization.identifier.value.',
+        },
+        [ClaimsOrganizationSchemaorg.alternateName]: {
+            type: 'string',
+            minLength: 1,
+            description: 'Optional compatibility alias. If omitted, callers may derive it from Organization.identifier.value.',
+        },
+    },
+    oneOf: [
+        { required: [ClaimsOrganizationSchemaorg.identifierValue] },
+        { required: [ClaimsOrganizationSchemaorg.taxId] },
+    ],
+    additionalProperties: true,
+};
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length ? trimmed : undefined;
+}
+/**
+ * Validates and normalizes legal-organization onboarding claims for SDKs,
+ * forms, and assistant-style data collection flows.
+ *
+ * Main behavior:
+ * - requires at least one of `Organization.identifier.value` or
+ *   `Organization.taxID`
+ * - if `identifier.value` is missing and `taxID` exists, copies
+ *   `taxID -> identifier.value`
+ * - if `alternateName` is missing and a canonical identifier exists, copies
+ *   `identifier.value -> alternateName`
+ * - when `allowExplicitAlternateNameForTenantId` is `false` (default),
+ *   rejects explicit `alternateName` values that differ from the final
+ *   canonical `identifier.value`
+ *
+ * The result shape is intentionally assistant-friendly:
+ * - `missingClaims` tells UI/voice flows what is still required
+ * - `normalizedClaims` shows the post-derivation claim set
+ * - `derived` explains which values were filled automatically
+ */
+export function validateLegalOrganizationOnboardingClaims(claims, options = {}) {
+    const normalizedClaims = { ...(claims || {}) };
+    const errors = [];
+    const missingClaims = [];
+    const allowExplicitAlternateNameForTenantId = options.allowExplicitAlternateNameForTenantId === true;
+    const identifierValue = normalizeOptionalString(normalizedClaims[ClaimsOrganizationSchemaorg.identifierValue]);
+    const taxId = normalizeOptionalString(normalizedClaims[ClaimsOrganizationSchemaorg.taxId]);
+    const explicitAlternateName = normalizeOptionalString(normalizedClaims[ClaimsOrganizationSchemaorg.alternateName]);
+    let finalIdentifierValue = identifierValue;
+    let identifierValueFromTaxId = false;
+    let alternateNameFromIdentifierValue = false;
+    if (!finalIdentifierValue && taxId) {
+        finalIdentifierValue = taxId;
+        normalizedClaims[ClaimsOrganizationSchemaorg.identifierValue] = taxId;
+        identifierValueFromTaxId = true;
+    }
+    if (!finalIdentifierValue) {
+        missingClaims.push(ClaimsOrganizationSchemaorg.identifierValue, ClaimsOrganizationSchemaorg.taxId);
+        errors.push({
+            code: 'MISSING_IDENTIFIER_OR_TAX_ID',
+            message: 'Legal organization onboarding requires Organization.identifier.value or Organization.taxID.',
+            claimPaths: [
+                ClaimsOrganizationSchemaorg.identifierValue,
+                ClaimsOrganizationSchemaorg.taxId,
+            ],
+        });
+    }
+    if (!explicitAlternateName && finalIdentifierValue) {
+        normalizedClaims[ClaimsOrganizationSchemaorg.alternateName] = finalIdentifierValue;
+        alternateNameFromIdentifierValue = true;
+    }
+    if (explicitAlternateName
+        && finalIdentifierValue
+        && !allowExplicitAlternateNameForTenantId
+        && explicitAlternateName !== finalIdentifierValue) {
+        errors.push({
+            code: 'EXPLICIT_ALTERNATE_NAME_NOT_ALLOWED',
+            message: 'Explicit Organization.alternateName is not allowed unless it matches Organization.identifier.value or the caller enables allowExplicitAlternateNameForTenantId.',
+            claimPaths: [
+                ClaimsOrganizationSchemaorg.alternateName,
+                ClaimsOrganizationSchemaorg.identifierValue,
+            ],
+        });
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        missingClaims,
+        normalizedClaims,
+        derived: {
+            identifierValueFromTaxId,
+            alternateNameFromIdentifierValue,
+        },
+    };
+}

package/dist/utils/license-commercial-search.d.ts

@@ -8,14 +8,14 @@ export declare const LicenseCommercialSearchOperation: Readonly<{
     readonly Offer: "Offer:Search";
     readonly Order: "Order:Search";
 }>;
-export type LicenseOfferSearchDraft = Readonly<{
+export type LicenseOfferSearchState = Readonly<{
     offerId?: string;
     status?: string;
     category?: string;
     customerType?: string;
     additionalClaims: LicenseClaims;
 }>;
-export type LicenseOrderSearchDraft = Readonly<{
+export type LicenseOrderSearchState = Readonly<{
     acceptedOfferId?: string;
     invoiceId?: string;
     paymentMethod?: string;
@@ -43,13 +43,13 @@ export type LicenseOrderRecord = Readonly<{
  */
 export declare class LicenseOfferSearchEditor {
     private draft;
-    constructor(initial?: Partial<LicenseOfferSearchDraft>);
+    constructor(initial?: Partial<LicenseOfferSearchState>);
     setOfferId(value: string): this;
     setStatus(value: string): this;
     setCategory(value: string): this;
     setCustomerType(value: string): this;
     mergeClaims(claims: LicenseClaims): this;
-    getDraft(): LicenseOfferSearchDraft;
+    getState(): LicenseOfferSearchState;
     buildSearchEntry(): {
         type: string;
         request: {
@@ -72,13 +72,13 @@ export declare class LicenseOfferSearchEditor {
  */
 export declare class LicenseOrderSearchEditor {
     private draft;
-    constructor(initial?: Partial<LicenseOrderSearchDraft>);
+    constructor(initial?: Partial<LicenseOrderSearchState>);
     setAcceptedOfferId(value: string): this;
     setInvoiceId(value: string): this;
     setPaymentMethod(value: string): this;
     setStatus(value: string): this;
     mergeClaims(claims: LicenseClaims): this;
-    getDraft(): LicenseOrderSearchDraft;
+    getState(): LicenseOrderSearchState;
     buildSearchEntry(): {
         type: string;
         request: {

package/dist/utils/license-commercial-search.js

@@ -68,7 +68,7 @@ export class LicenseOfferSearchEditor {
         });
         return this;
     }
-    getDraft() {
+    getState() {
         return cloneOfferSearchDraft(this.draft);
     }
     buildSearchEntry() {
@@ -131,7 +131,7 @@ export class LicenseOrderSearchEditor {
         });
         return this;
     }
-    getDraft() {
+    getState() {
         return cloneOrderSearchDraft(this.draft);
     }
     buildSearchEntry() {