gdc-common-utils-ts 1.9.0 → 1.11.0

package/README.md

@@ -142,6 +142,8 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - This is the preferred first scope to teach when the backend only needs subject-scoped read access.
 - [`getOrganizationCredentialFromVpToken(...)`, `getLegalRepresentativeCredentialFromVpToken(...)`](src/utils/vp-token.ts)
   - Extract typed VC objects from a VP token when GW/SDK flows carry canonical proof only in `vp_token`.
+- [`docs/VP_TOKEN_101.md`](docs/VP_TOKEN_101.md)
+  - Step-by-step guide for building the canonical compact `vp_token` string from organization and representative VCs.
 - [`validateCommunicationResourceFhirR4(...)`](src/utils/communication-fhir-r4.ts)
   - Validates FHIR R4 `Communication` resources.
 - [`transformCommunicationClaimsToResourceFhirR4(...)`](src/utils/communication-fhir-r4.ts)

package/dist/constants/cryptography.d.ts

@@ -14,6 +14,29 @@ export declare const CommunicationKeyPurposes: {
     readonly CommunicationSignature: "comm_sig";
     readonly VerifiableCredentialSignature: "vc_sign";
 };
+/**
+ * Classical JOSE signature algorithms currently recognized across GDC VP/JWT
+ * examples and gateway trust adapters.
+ *
+ * Notes:
+ * - `ES256K` is the JOSE name for ECDSA over `secp256k1`
+ * - `ES384` remains the common P-384 legacy example in current GW fixtures
+ */
+export declare const ClassicalJoseSignatureAlgorithms: {
+    readonly Es256: "ES256";
+    readonly Es256K: "ES256K";
+    readonly Es384: "ES384";
+};
+/**
+ * JOSE signature algorithms accepted by shared VP/JWT helpers.
+ *
+ * This intentionally covers both:
+ * - classical ECDSA JOSE algorithms (`ES256`, `ES256K`, `ES384`)
+ * - post-quantum ML-DSA JOSE algorithm labels already used by GW
+ *
+ * Use this type when a helper builds or documents a JWS/JWT/VP proof header.
+ */
+export type JoseSignatureAlgorithm = typeof ClassicalJoseSignatureAlgorithms[keyof typeof ClassicalJoseSignatureAlgorithms] | MldsaAlg;
 /**
  * Default post-quantum signing algorithms used for communication bootstrap.
  */

package/dist/constants/cryptography.js

@@ -15,6 +15,19 @@ export const CommunicationKeyPurposes = {
     CommunicationSignature: 'comm_sig',
     VerifiableCredentialSignature: 'vc_sign',
 };
+/**
+ * Classical JOSE signature algorithms currently recognized across GDC VP/JWT
+ * examples and gateway trust adapters.
+ *
+ * Notes:
+ * - `ES256K` is the JOSE name for ECDSA over `secp256k1`
+ * - `ES384` remains the common P-384 legacy example in current GW fixtures
+ */
+export const ClassicalJoseSignatureAlgorithms = {
+    Es256: 'ES256',
+    Es256K: 'ES256K',
+    Es384: 'ES384',
+};
 /**
  * Default post-quantum signing algorithms used for communication bootstrap.
  */

package/dist/constants/index.d.ts

@@ -14,4 +14,5 @@ export * from './network';
 export * from './sectors';
 export * from './smart';
 export * from './service-capabilities';
+export * from './urn';
 export * from './verifiable-credentials';

package/dist/constants/index.js

@@ -14,4 +14,5 @@ export * from './network.js';
 export * from './sectors.js';
 export * from './smart.js';
 export * from './service-capabilities.js';
+export * from './urn.js';
 export * from './verifiable-credentials.js';

package/dist/constants/schemaorg.d.ts

@@ -6,6 +6,29 @@ export declare enum ClaimsServiceSchemaorg {
     termsOfService = "org.schema.Service.termsOfService",
     url = "org.schema.Service.url"
 }
+/**
+ * Canonical claim names used by the current GDC profile when a VC models a
+ * `schema.org/SoftwareApplication`.
+ *
+ * Contract note:
+ * - `material` is the public cryptographic material of the software
+ *   application in the current GDC profile, typically the communication
+ *   signing key id bound by ICA to the software/application instance
+ * - when that identifier is expressed as a JWK thumbprint, RFC 7638 defines
+ *   the canonical thumbprint calculation over the public signing /
+ *   verification JWK and RFC 9278 defines the canonical URN form
+ *   `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
+ * - the controller-side signature belongs to the prior ICA registration step,
+ *   not to every later app-service operational proof
+ */
+export declare enum ClaimsSoftwareApplicationSchemaorg {
+    id = "org.schema.SoftwareApplication.id",
+    name = "org.schema.SoftwareApplication.name",
+    url = "org.schema.SoftwareApplication.url",
+    sameAs = "org.schema.SoftwareApplication.sameAs",
+    /** Communication signing key id bound by the ICA-issued SoftwareApplication VC. */
+    material = "org.schema.SoftwareApplication.material"
+}
 /**
  * Defines the canonical claim names for the 'org.schema' context,
  * based on Schema.org vocabulary.
@@ -39,6 +62,16 @@ export declare enum ClaimsOrganizationSchemaorg {
     email = "org.schema.Organization.email",
     /** Public contact phone */
     telephone = "org.schema.Organization.telephone",
+    /**
+     * Public cryptographic material of the organization in VC/profile payloads.
+     *
+     * When represented as a JWK thumbprint identifier:
+     * - RFC 7638 defines the canonical thumbprint calculation over the public
+     *   signing / verification JWK
+     * - RFC 9278 defines the canonical URN form
+     *   `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
+     */
+    hasCredentialMaterial = "org.schema.Organization.hasCredential.material",
     /** Individual/family owner email used by subject-index registration flows. */
     ownerEmail = "org.schema.Organization.owner.email",
     /** Individual/family owner telephone used by subject-index registration flows. */
@@ -139,8 +172,3 @@ export declare enum ICAOIdentityParams {
 }
 export declare const indexedPersonAttributeList: string[];
 export declare const fullPersonParamsSchemaorg: ParameterData[];
-/**
- * Canonical schema.org `Service` flat claims commonly used by GW tenant and
- * individual onboarding flows.
- */
-export declare const fullServiceParamsSchemaorg: ParameterData[];

package/dist/constants/schemaorg.js

@@ -8,6 +8,30 @@ export var ClaimsServiceSchemaorg;
     ClaimsServiceSchemaorg["termsOfService"] = "org.schema.Service.termsOfService";
     ClaimsServiceSchemaorg["url"] = "org.schema.Service.url";
 })(ClaimsServiceSchemaorg || (ClaimsServiceSchemaorg = {}));
+/**
+ * Canonical claim names used by the current GDC profile when a VC models a
+ * `schema.org/SoftwareApplication`.
+ *
+ * Contract note:
+ * - `material` is the public cryptographic material of the software
+ *   application in the current GDC profile, typically the communication
+ *   signing key id bound by ICA to the software/application instance
+ * - when that identifier is expressed as a JWK thumbprint, RFC 7638 defines
+ *   the canonical thumbprint calculation over the public signing /
+ *   verification JWK and RFC 9278 defines the canonical URN form
+ *   `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
+ * - the controller-side signature belongs to the prior ICA registration step,
+ *   not to every later app-service operational proof
+ */
+export var ClaimsSoftwareApplicationSchemaorg;
+(function (ClaimsSoftwareApplicationSchemaorg) {
+    ClaimsSoftwareApplicationSchemaorg["id"] = "org.schema.SoftwareApplication.id";
+    ClaimsSoftwareApplicationSchemaorg["name"] = "org.schema.SoftwareApplication.name";
+    ClaimsSoftwareApplicationSchemaorg["url"] = "org.schema.SoftwareApplication.url";
+    ClaimsSoftwareApplicationSchemaorg["sameAs"] = "org.schema.SoftwareApplication.sameAs";
+    /** Communication signing key id bound by the ICA-issued SoftwareApplication VC. */
+    ClaimsSoftwareApplicationSchemaorg["material"] = "org.schema.SoftwareApplication.material";
+})(ClaimsSoftwareApplicationSchemaorg || (ClaimsSoftwareApplicationSchemaorg = {}));
 /**
  * Defines the canonical claim names for the 'org.schema' context,
  * based on Schema.org vocabulary.
@@ -42,6 +66,16 @@ export var ClaimsOrganizationSchemaorg;
     ClaimsOrganizationSchemaorg["email"] = "org.schema.Organization.email";
     /** Public contact phone */
     ClaimsOrganizationSchemaorg["telephone"] = "org.schema.Organization.telephone";
+    /**
+     * Public cryptographic material of the organization in VC/profile payloads.
+     *
+     * When represented as a JWK thumbprint identifier:
+     * - RFC 7638 defines the canonical thumbprint calculation over the public
+     *   signing / verification JWK
+     * - RFC 9278 defines the canonical URN form
+     *   `urn:ietf:params:oauth:jwk-thumbprint:sha-256:<base64url>`
+     */
+    ClaimsOrganizationSchemaorg["hasCredentialMaterial"] = "org.schema.Organization.hasCredential.material";
     /** Individual/family owner email used by subject-index registration flows. */
     ClaimsOrganizationSchemaorg["ownerEmail"] = "org.schema.Organization.owner.email";
     /** Individual/family owner telephone used by subject-index registration flows. */
@@ -224,35 +258,3 @@ export const fullPersonParamsSchemaorg = [
     },
     */
 ];
-/**
- * Canonical schema.org `Service` flat claims commonly used by GW tenant and
- * individual onboarding flows.
- */
-export const fullServiceParamsSchemaorg = [
-    {
-        name: ClaimsServiceSchemaorg.category,
-        type: 'token',
-        value: undefined,
-    },
-    {
-        name: ClaimsServiceSchemaorg.identifier,
-        type: 'uri',
-        value: undefined,
-        unique: true,
-    },
-    {
-        name: ClaimsServiceSchemaorg.serviceType,
-        type: 'token',
-        value: undefined,
-    },
-    {
-        name: ClaimsServiceSchemaorg.termsOfService,
-        type: 'uri',
-        value: undefined,
-    },
-    {
-        name: ClaimsServiceSchemaorg.url,
-        type: 'uri',
-        value: undefined,
-    },
-];

package/dist/constants/service-capabilities.d.ts

@@ -14,9 +14,25 @@ export type ServiceCapabilityFamilyValue = typeof ServiceCapabilityFamily[keyof
  * `.rs` and `.cruds` can evolve independently across runtimes.
  */
 export declare const ServiceCapabilityToken: {
+    readonly IndexReader: "indexing.rs";
+    readonly IndexProvider: "indexing.cruds";
+    readonly DigitalTwinReader: "digitaltwin.rs";
+    readonly DigitalTwinProvider: "digitaltwin.cruds";
+    /**
+     * @deprecated Prefer `IndexReader`.
+     */
     readonly IndexingReadSearch: "indexing.rs";
+    /**
+     * @deprecated Prefer `IndexProvider`.
+     */
     readonly IndexingCruds: "indexing.cruds";
+    /**
+     * @deprecated Prefer `DigitalTwinReader`.
+     */
     readonly DigitalTwinReadSearch: "digitaltwin.rs";
+    /**
+     * @deprecated Prefer `DigitalTwinProvider`.
+     */
     readonly DigitalTwinCruds: "digitaltwin.cruds";
 };
 export type ServiceCapabilityTokenValue = typeof ServiceCapabilityToken[keyof typeof ServiceCapabilityToken];
@@ -28,10 +44,18 @@ export type ServiceCapabilityTokenValue = typeof ServiceCapabilityToken[keyof ty
  * - `Reader` maps to read/search capability (`*.rs`)
  */
 export declare const ServiceCapability: {
-    readonly IndexingProvider: "indexing.cruds";
-    readonly IndexingReader: "indexing.rs";
+    readonly IndexProvider: "indexing.cruds";
+    readonly IndexReader: "indexing.rs";
     readonly DigitalTwinProvider: "digitaltwin.cruds";
     readonly DigitalTwinReader: "digitaltwin.rs";
+    /**
+     * @deprecated Prefer `IndexProvider`.
+     */
+    readonly IndexingProvider: "indexing.cruds";
+    /**
+     * @deprecated Prefer `IndexReader`.
+     */
+    readonly IndexingReader: "indexing.rs";
 };
 export type ServiceCapabilityValue = typeof ServiceCapability[keyof typeof ServiceCapability];
 /**

package/dist/constants/service-capabilities.js

@@ -15,9 +15,25 @@ export const ServiceCapabilityFamily = {
  * `.rs` and `.cruds` can evolve independently across runtimes.
  */
 export const ServiceCapabilityToken = {
+    IndexReader: 'indexing.rs',
+    IndexProvider: 'indexing.cruds',
+    DigitalTwinReader: 'digitaltwin.rs',
+    DigitalTwinProvider: 'digitaltwin.cruds',
+    /**
+     * @deprecated Prefer `IndexReader`.
+     */
     IndexingReadSearch: 'indexing.rs',
+    /**
+     * @deprecated Prefer `IndexProvider`.
+     */
     IndexingCruds: 'indexing.cruds',
+    /**
+     * @deprecated Prefer `DigitalTwinReader`.
+     */
     DigitalTwinReadSearch: 'digitaltwin.rs',
+    /**
+     * @deprecated Prefer `DigitalTwinProvider`.
+     */
     DigitalTwinCruds: 'digitaltwin.cruds',
 };
 /**
@@ -28,10 +44,18 @@ export const ServiceCapabilityToken = {
  * - `Reader` maps to read/search capability (`*.rs`)
  */
 export const ServiceCapability = {
-    IndexingProvider: ServiceCapabilityToken.IndexingCruds,
-    IndexingReader: ServiceCapabilityToken.IndexingReadSearch,
-    DigitalTwinProvider: ServiceCapabilityToken.DigitalTwinCruds,
-    DigitalTwinReader: ServiceCapabilityToken.DigitalTwinReadSearch,
+    IndexProvider: ServiceCapabilityToken.IndexProvider,
+    IndexReader: ServiceCapabilityToken.IndexReader,
+    DigitalTwinProvider: ServiceCapabilityToken.DigitalTwinProvider,
+    DigitalTwinReader: ServiceCapabilityToken.DigitalTwinReader,
+    /**
+     * @deprecated Prefer `IndexProvider`.
+     */
+    IndexingProvider: ServiceCapabilityToken.IndexProvider,
+    /**
+     * @deprecated Prefer `IndexReader`.
+     */
+    IndexingReader: ServiceCapabilityToken.IndexReader,
 };
 /**
  * Parses the CSV stored in `org.schema.Service.serviceType`.

package/dist/constants/urn.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Canonical URN prefixes reused across bootstrap and proof examples.
+ *
+ * The JWK thumbprint URI prefix below follows RFC 9278 and is intended for
+ * cases where a key identifier is represented as a normalized URI instead of
+ * as a bare base64url thumbprint value.
+ */
+export declare const UrnPrefixes: Readonly<{
+    readonly JwkThumbprintSha256KeyId: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:";
+}>;
+export type UrnPrefix = typeof UrnPrefixes[keyof typeof UrnPrefixes];

package/dist/constants/urn.js

@@ -0,0 +1,11 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Canonical URN prefixes reused across bootstrap and proof examples.
+ *
+ * The JWK thumbprint URI prefix below follows RFC 9278 and is intended for
+ * cases where a key identifier is represented as a normalized URI instead of
+ * as a bare base64url thumbprint value.
+ */
+export const UrnPrefixes = Object.freeze({
+    JwkThumbprintSha256KeyId: 'urn:ietf:params:oauth:jwk-thumbprint:sha-256:',
+});

package/dist/examples/ica-activation-proof.d.ts

@@ -2,33 +2,42 @@
  * Shared synthetic ICA activation-proof fixtures reused by docs/tests.
  *
  * Contract note:
- * - issuer/holder/audience DIDs, VC subtype names, and representative binding
- *   fields must be imported from this module instead of re-hardcoded inline
+ * - controller-signing/audience ids and VC subtype names must be imported from
+ *   this module instead of re-hardcoded
+ *   inline
  * - the representative `hasCredential.material` shape below reflects the
  *   current `activation-policy` helper contract; if ICA finalizes a different
  *   VC shape, update this module first and then the dependent helpers/tests
+ *
+ * Modeling note:
+ * - this onboarding example intentionally anchors the business subject on the
+ *   organization tax ID rather than on a pre-existing provider DID
+ * - the VP envelope uses a synthetic RFC 7638-style JWK-thumbprint urn and a
+ *   host id, which better matches the initial registration stage than a
+ *   synthetic did:web
+ */
+/**
+ * Synthetic JWK-thumbprint-based signing key id for the organization
+ * controller who signs the initial legal-onboarding VP.
  */
-export declare const EXAMPLE_ICA_VP_ISSUER_DID: "did:web:controller.example.org";
-export declare const EXAMPLE_ICA_VP_AUDIENCE_DID: "did:web:host.example.com";
-export declare const EXAMPLE_ICA_VP_HOLDER_DID: "did:web:controller.example.org";
-export declare const EXAMPLE_ICA_ORGANIZATION_DID: "did:web:org.example.org";
-export declare const EXAMPLE_ICA_REPRESENTATIVE_DID: "did:web:rep.example.org";
-export declare const EXAMPLE_ICA_ORGANIZATION_TAX_ID: "ESB00112233";
-export declare const EXAMPLE_ICA_REPRESENTATIVE_ROLE_CODE: "RESPRSN";
-export declare const EXAMPLE_ICA_REPRESENTATIVE_BINDING_MATERIAL: "controller-sig-kid";
-export declare const EXAMPLE_ICA_ORGANIZATION_CREDENTIAL: Readonly<{
+export declare const EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
+export declare const EXAMPLE_PRESENTATION_AUDIENCE_HOST_ID: "host:node-operator-es";
+export declare const EXAMPLE_ORGANIZATION_TAX_ID: "ESB00112233";
+export declare const EXAMPLE_REPRESENTATIVE_ROLE_CODE: "RESPRSN";
+export declare const EXAMPLE_ORGANIZATION_ID: "ESB00112233";
+export declare const EXAMPLE_ORG_ACTIVATION_ORGANIZATION_CREDENTIAL: Readonly<{
     '@context': string[];
     type: ("VerifiableCredential" | "OrganizationCredential")[];
     credentialSubject: {
-        id: "did:web:org.example.org";
+        id: "ESB00112233";
         taxID: "ESB00112233";
     };
 }>;
-export declare const EXAMPLE_ICA_LEGAL_REPRESENTATIVE_CREDENTIAL: Readonly<{
+export declare const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL: Readonly<{
     '@context': string[];
     type: ("VerifiableCredential" | "LegalRepresentativeCredential")[];
     credentialSubject: {
-        id: "did:web:rep.example.org";
+        id: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
         memberOf: {
             taxID: "ESB00112233";
         };
@@ -38,18 +47,18 @@ export declare const EXAMPLE_ICA_LEGAL_REPRESENTATIVE_CREDENTIAL: Readonly<{
             };
         };
         hasCredential: {
-            material: "controller-sig-kid";
+            material: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
         };
     };
 }>;
-export declare const EXAMPLE_ICA_ACTIVATION_VP_PAYLOAD: Readonly<{
-    iss: "did:web:controller.example.org";
-    sub: "did:web:controller.example.org";
-    aud: "did:web:host.example.com";
+export declare const EXAMPLE_ORG_ACTIVATION_PROOF_VP_PAYLOAD: Readonly<{
+    iss: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
+    sub: "ESB00112233";
+    aud: "host:node-operator-es";
     vp: {
         '@context': "https://www.w3.org/2018/credentials/v1"[];
         type: "VerifiablePresentation"[];
-        holder: "did:web:controller.example.org";
+        holder: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
         verifiableCredential: string[];
     };
 }>;

package/dist/examples/ica-activation-proof.js

@@ -1,67 +1,77 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 // Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 import { ActivationCredentialTypes, W3cCredentialContexts, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
+import { UrnPrefixes } from '../constants/urn.js';
 /**
  * Shared synthetic ICA activation-proof fixtures reused by docs/tests.
  *
  * Contract note:
- * - issuer/holder/audience DIDs, VC subtype names, and representative binding
- *   fields must be imported from this module instead of re-hardcoded inline
+ * - controller-signing/audience ids and VC subtype names must be imported from
+ *   this module instead of re-hardcoded
+ *   inline
  * - the representative `hasCredential.material` shape below reflects the
  *   current `activation-policy` helper contract; if ICA finalizes a different
  *   VC shape, update this module first and then the dependent helpers/tests
+ *
+ * Modeling note:
+ * - this onboarding example intentionally anchors the business subject on the
+ *   organization tax ID rather than on a pre-existing provider DID
+ * - the VP envelope uses a synthetic RFC 7638-style JWK-thumbprint urn and a
+ *   host id, which better matches the initial registration stage than a
+ *   synthetic did:web
+ */
+/**
+ * Synthetic JWK-thumbprint-based signing key id for the organization
+ * controller who signs the initial legal-onboarding VP.
  */
-export const EXAMPLE_ICA_VP_ISSUER_DID = 'did:web:controller.example.org';
-export const EXAMPLE_ICA_VP_AUDIENCE_DID = 'did:web:host.example.com';
-export const EXAMPLE_ICA_VP_HOLDER_DID = EXAMPLE_ICA_VP_ISSUER_DID;
-export const EXAMPLE_ICA_ORGANIZATION_DID = 'did:web:org.example.org';
-export const EXAMPLE_ICA_REPRESENTATIVE_DID = 'did:web:rep.example.org';
-export const EXAMPLE_ICA_ORGANIZATION_TAX_ID = 'ESB00112233';
-export const EXAMPLE_ICA_REPRESENTATIVE_ROLE_CODE = 'RESPRSN';
-export const EXAMPLE_ICA_REPRESENTATIVE_BINDING_MATERIAL = 'controller-sig-kid';
-export const EXAMPLE_ICA_ORGANIZATION_CREDENTIAL = Object.freeze({
+export const EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID = `${UrnPrefixes.JwkThumbprintSha256KeyId}Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA`;
+export const EXAMPLE_PRESENTATION_AUDIENCE_HOST_ID = 'host:node-operator-es';
+export const EXAMPLE_ORGANIZATION_TAX_ID = 'ESB00112233';
+export const EXAMPLE_REPRESENTATIVE_ROLE_CODE = 'RESPRSN';
+export const EXAMPLE_ORGANIZATION_ID = EXAMPLE_ORGANIZATION_TAX_ID;
+export const EXAMPLE_ORG_ACTIVATION_ORGANIZATION_CREDENTIAL = Object.freeze({
     '@context': [W3cCredentialContexts.V2, 'https://schema.org'],
     type: [
         W3cCredentialTypes.VerifiableCredential,
         ActivationCredentialTypes.OrganizationCredential,
     ],
     credentialSubject: {
-        id: EXAMPLE_ICA_ORGANIZATION_DID,
-        taxID: EXAMPLE_ICA_ORGANIZATION_TAX_ID,
+        id: EXAMPLE_ORGANIZATION_ID,
+        taxID: EXAMPLE_ORGANIZATION_TAX_ID,
     },
 });
-export const EXAMPLE_ICA_LEGAL_REPRESENTATIVE_CREDENTIAL = Object.freeze({
+export const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL = Object.freeze({
     '@context': [W3cCredentialContexts.V2, 'https://schema.org'],
     type: [
         W3cCredentialTypes.VerifiableCredential,
         ActivationCredentialTypes.LegalRepresentativeCredential,
     ],
     credentialSubject: {
-        id: EXAMPLE_ICA_REPRESENTATIVE_DID,
+        id: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
         memberOf: {
-            taxID: EXAMPLE_ICA_ORGANIZATION_TAX_ID,
+            taxID: EXAMPLE_ORGANIZATION_TAX_ID,
         },
         hasOccupation: {
             identifier: {
-                value: EXAMPLE_ICA_REPRESENTATIVE_ROLE_CODE,
+                value: EXAMPLE_REPRESENTATIVE_ROLE_CODE,
             },
         },
         hasCredential: {
-            material: EXAMPLE_ICA_REPRESENTATIVE_BINDING_MATERIAL,
+            material: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
         },
     },
 });
-export const EXAMPLE_ICA_ACTIVATION_VP_PAYLOAD = Object.freeze({
-    iss: EXAMPLE_ICA_VP_ISSUER_DID,
-    sub: EXAMPLE_ICA_VP_ISSUER_DID,
-    aud: EXAMPLE_ICA_VP_AUDIENCE_DID,
+export const EXAMPLE_ORG_ACTIVATION_PROOF_VP_PAYLOAD = Object.freeze({
+    iss: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
+    sub: EXAMPLE_ORGANIZATION_TAX_ID,
+    aud: EXAMPLE_PRESENTATION_AUDIENCE_HOST_ID,
     vp: {
         '@context': [W3cCredentialContexts.V1],
         type: [W3cCredentialTypes.VerifiablePresentation],
-        holder: EXAMPLE_ICA_VP_HOLDER_DID,
+        holder: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
         verifiableCredential: [
-            JSON.stringify(EXAMPLE_ICA_ORGANIZATION_CREDENTIAL),
-            JSON.stringify(EXAMPLE_ICA_LEGAL_REPRESENTATIVE_CREDENTIAL),
+            JSON.stringify(EXAMPLE_ORG_ACTIVATION_ORGANIZATION_CREDENTIAL),
+            JSON.stringify(EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL),
         ],
     },
 });

package/dist/examples/organization-controller.js

@@ -26,8 +26,8 @@ export const EXAMPLE_ACTIVATE_ORGANIZATION_FROM_ICA_PROOF_INPUT = {
         [ClaimsServiceSchemaorg.identifier]: EXAMPLE_SERVICE_PUBLIC_DID,
         [ClaimsServiceSchemaorg.url]: `https://operator.example.net/acme/cds-${String(EXAMPLE_JURISDICTION).toLowerCase()}/v1/${EXAMPLE_SECTOR}`,
         [ClaimsServiceSchemaorg.serviceType]: serializeServiceCapabilityTokens([
-            ServiceCapabilityToken.IndexingCruds,
-            ServiceCapabilityToken.DigitalTwinReadSearch,
+            ServiceCapabilityToken.IndexProvider,
+            ServiceCapabilityToken.DigitalTwinReader,
         ]),
     },
 };

package/dist/interfaces/Cryptography.types.d.ts

@@ -59,7 +59,15 @@ export interface ClassicPublicJwk {
     x: string;
     y: string;
     kid?: string;
-    alg?: string;
+    /**
+     * JOSE signing algorithm for classical EC keys.
+     *
+     * Examples:
+     * - `ES256` for P-256
+     * - `ES384` for P-384
+     * - `ES256K` for secp256k1
+     */
+    alg?: "ES256" | "ES384" | "ES256K";
     use?: string;
 }
 /**

package/dist/models/index.d.ts

@@ -1,9 +1,3 @@
-/**
- * @fileoverview Barrel export for shared model contracts.
- *
- * @architecture 101
- * Keep this file export-only; shared business logic belongs in dedicated modules.
- */
 export * from './actor-session';
 export * from './aes';
 export * from './auth';
@@ -21,7 +15,6 @@ export * from './crypto';
 export * from './device-license';
 export * from './did';
 export * from './fhir-documents';
-export * from './fhir-related-person';
 export * from './interoperable-claims';
 export * from './indexing';
 export * from './identity-bootstrap';
@@ -41,7 +34,6 @@ export * from './operation-outcome';
 export * from './params';
 export * from './resource-document';
 export * from './relationship-access';
-export * from './related-profile';
 export * from './response';
 export * from './urlPath';
 export * from './verifiable-credential';

package/dist/models/index.js

@@ -1,10 +1,3 @@
-// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-/**
- * @fileoverview Barrel export for shared model contracts.
- *
- * @architecture 101
- * Keep this file export-only; shared business logic belongs in dedicated modules.
- */
 export * from './actor-session.js';
 export * from './aes.js';
 export * from './auth.js';
@@ -22,7 +15,6 @@ export * from './crypto.js';
 export * from './device-license.js';
 export * from './did.js';
 export * from './fhir-documents.js';
-export * from './fhir-related-person.js';
 export * from './interoperable-claims.js';
 export * from './indexing.js';
 export * from './identity-bootstrap.js';
@@ -42,7 +34,6 @@ export * from './operation-outcome.js';
 export * from './params.js';
 export * from './resource-document.js';
 export * from './relationship-access.js';
-export * from './related-profile.js';
 export * from './response.js';
 export * from './urlPath.js';
 export * from './verifiable-credential.js';

package/dist/models/params.d.ts

@@ -95,31 +95,6 @@ export interface ParameterData extends ParamAttribute {
      */
     appliesTo?: string[];
 }
-/**
- * Shared definition for a search parameter that can also be used as an
- * indexable attribute contract.
- *
- * `name` remains the canonical flat claim key that will be stored and queried.
- * The record key in a `SearchParameterCatalog` is the public search-attribute
- * name to expose in APIs or capability statements.
- */
-export interface SearchParameterDefinition extends ParameterData {
-    /**
-     * Optional compatibility aliases accepted on read/normalization before the
-     * canonical `name` is used for indexing.
-     */
-    claimAliases?: readonly string[];
-    /**
-     * Whether this parameter is intended to be indexed for blind queries.
-     * Defaults to `true` when omitted by catalog consumers.
-     */
-    indexed?: boolean;
-}
-/**
- * Per-resource search parameter catalog keyed by the public search attribute
- * name (e.g. `identifier`, `subject`, `status`).
- */
-export type SearchParameterCatalog<TSearchName extends string = string> = Record<TSearchName, SearchParameterDefinition>;
 export interface StringSearchParameter extends ParameterData {
     type: 'string';
     value: string;

package/dist/models/params.js

@@ -1,2 +1,3 @@
 // Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
+// File: crypto-ts/models/params.ts
 export {};

package/dist/utils/index.d.ts

@@ -13,7 +13,6 @@ export * from './didcomm-submit-policy';
 export * from './discovery-normalization';
 export * from './format-converter';
 export * from './fhir-cid';
-export * from './gateway-index-params';
 export * from './communication-fhir-r4';
 export * from './communication-document-reference';
 export * from './communication-identity';
@@ -28,6 +27,5 @@ export * from './normalize';
 export * from './object-convert';
 export * from './normalize-uuid';
 export * from './smart-scope';
-export * from './search-parameter-catalog';
 export * from './activation-request';
 export * from './vp-token';

package/dist/utils/index.js

@@ -13,7 +13,6 @@ export * from './didcomm-submit-policy.js';
 export * from './discovery-normalization.js';
 export * from './format-converter.js';
 export * from './fhir-cid.js';
-export * from './gateway-index-params.js';
 export * from './communication-fhir-r4.js';
 export * from './communication-document-reference.js';
 export * from './communication-identity.js';
@@ -28,6 +27,5 @@ export * from './normalize.js';
 export * from './object-convert.js';
 export * from './normalize-uuid.js';
 export * from './smart-scope.js';
-export * from './search-parameter-catalog.js';
 export * from './activation-request.js';
 export * from './vp-token.js';

package/dist/utils/vp-token.d.ts

@@ -1,5 +1,13 @@
+import { JoseSignatureAlgorithm } from '../constants/cryptography';
+/**
+ * Protected JOSE header used when assembling a compact VP JWT.
+ *
+ * The `alg` field is intentionally typed as a shared JOSE signature algorithm
+ * instead of a free-form string so docs/tests can show the supported values
+ * explicitly, including `ES256K` for secp256k1-based signers.
+ */
 export type VpTokenHeader = {
-    alg: string;
+    alg: JoseSignatureAlgorithm;
     typ?: string;
     kid?: string;
     [key: string]: unknown;
@@ -16,20 +24,47 @@ export type VpTokenPayload = {
         '@context'?: unknown;
         type?: unknown;
         holder?: string;
-        verifiableCredential: string[];
+        verifiableCredential: Array<string | Record<string, unknown>>;
         [key: string]: unknown;
     };
     [key: string]: unknown;
 };
 export type VpCredential = Record<string, unknown>;
+export type VpCredentialInput = string | Record<string, unknown>;
 export declare function generateUuidLike(): string;
 export declare function buildEpochWindow(ttlSeconds?: number): {
     iat: number;
     exp: number;
 };
 export declare function createVP(input?: Partial<VpTokenPayload>): VpTokenPayload;
-export declare function addVC(vpPayload: VpTokenPayload, vcJwt: string): VpTokenPayload;
-export declare function addVCs(vpPayload: VpTokenPayload, vcs: string[]): VpTokenPayload;
+/**
+ * Appends one VC entry to the VP payload.
+ *
+ * Accepted input forms:
+ *
+ * - compact VC JWT/JWS string
+ * - raw JSON VC string
+ * - direct VC JSON object
+ *
+ * Storage rule:
+ *
+ * - string inputs are stored as strings
+ * - object inputs are stored as objects
+ *
+ * This keeps the builder compatible with existing compact-token flows while
+ * also supporting app/runtime code that already holds the VC as parsed JSON.
+ */
+export declare function addVC(vpPayload: VpTokenPayload, vcInput: VpCredentialInput): VpTokenPayload;
+/**
+ * Appends many VC entries to the VP payload.
+ *
+ * Each entry may be:
+ *
+ * - compact VC JWT/JWS string
+ * - raw JSON VC string
+ * - direct VC JSON object
+ */
+export declare function addVCs(vpPayload: VpTokenPayload, vcs: VpCredentialInput[]): VpTokenPayload;
 /**
  * Decodes a compact VP token payload into a JSON object.
  *
@@ -67,12 +102,38 @@ export declare function getOrganizationCredentialFromVpToken(vpToken: string): V
  * @param vpToken Compact VP token or raw JSON string.
  */
 export declare function getLegalRepresentativeCredentialFromVpToken(vpToken: string): VpCredential | undefined;
-export declare function addOrganizationCredential(vpPayload: VpTokenPayload, vc: string): VpTokenPayload;
-export declare function addLegalRepresentativeCredential(vpPayload: VpTokenPayload, vc: string): VpTokenPayload;
+/**
+ * Appends an organization activation credential after validating its VC type.
+ *
+ * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
+ */
+export declare function addOrganizationCredential(vpPayload: VpTokenPayload, vc: VpCredentialInput): VpTokenPayload;
+/**
+ * Appends a legal-representative activation credential after validating its VC
+ * type.
+ *
+ * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
+ */
+export declare function addLegalRepresentativeCredential(vpPayload: VpTokenPayload, vc: VpCredentialInput): VpTokenPayload;
 export declare function prepareForSignature(header: VpTokenHeader, payload: VpTokenPayload): {
     encodedHeader: string;
     encodedPayload: string;
     signingInput: string;
 };
+/**
+ * Returns the UTF-8 bytes of the canonical `base64url(header).base64url(payload)`
+ * signing input.
+ *
+ * This is the exact byte sequence an external wallet, HSM, or KMS must sign
+ * before the caller assembles the final compact VP JWT with
+ * `buildVpTokenCompact(...)`.
+ */
 export declare function prepareBytesForSignature(header: VpTokenHeader, payload: VpTokenPayload): Uint8Array;
+/**
+ * Assembles the final compact VP JWT once the caller already has:
+ *
+ * - the base64url-encoded protected header
+ * - the base64url-encoded VP payload
+ * - the detached signature returned by the external signer, also base64url-encoded
+ */
 export declare function buildVpTokenCompact(encodedHeader: string, encodedPayload: string, signatureBase64Url: string): string;

package/dist/utils/vp-token.js

@@ -37,19 +37,52 @@ export function createVP(input) {
     };
     return base;
 }
-export function addVC(vpPayload, vcJwt) {
-    const v = String(vcJwt || '').trim();
+/**
+ * Appends one VC entry to the VP payload.
+ *
+ * Accepted input forms:
+ *
+ * - compact VC JWT/JWS string
+ * - raw JSON VC string
+ * - direct VC JSON object
+ *
+ * Storage rule:
+ *
+ * - string inputs are stored as strings
+ * - object inputs are stored as objects
+ *
+ * This keeps the builder compatible with existing compact-token flows while
+ * also supporting app/runtime code that already holds the VC as parsed JSON.
+ */
+export function addVC(vpPayload, vcInput) {
+    if (vcInput && typeof vcInput === 'object') {
+        vpPayload.vp.verifiableCredential.push({ ...vcInput });
+        return vpPayload;
+    }
+    const v = String(vcInput || '').trim();
     if (!v)
         return vpPayload;
     vpPayload.vp.verifiableCredential.push(v);
     return vpPayload;
 }
+/**
+ * Appends many VC entries to the VP payload.
+ *
+ * Each entry may be:
+ *
+ * - compact VC JWT/JWS string
+ * - raw JSON VC string
+ * - direct VC JSON object
+ */
 export function addVCs(vpPayload, vcs) {
     for (const vc of vcs || [])
         addVC(vpPayload, vc);
     return vpPayload;
 }
 function decodeVcPayload(vc) {
+    if (vc && typeof vc === 'object') {
+        return vc;
+    }
     const raw = String(vc || '').trim();
     if (!raw)
         return undefined;
@@ -173,9 +206,20 @@ function addTypedVC(vpPayload, vc, acceptedTypes, label) {
     }
     return addVC(vpPayload, vc);
 }
+/**
+ * Appends an organization activation credential after validating its VC type.
+ *
+ * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
+ */
 export function addOrganizationCredential(vpPayload, vc) {
     return addTypedVC(vpPayload, vc, [...ORGANIZATION_ACTIVATION_VC_TYPES], 'Organization');
 }
+/**
+ * Appends a legal-representative activation credential after validating its VC
+ * type.
+ *
+ * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
+ */
 export function addLegalRepresentativeCredential(vpPayload, vc) {
     return addTypedVC(vpPayload, vc, [...REPRESENTATIVE_ACTIVATION_VC_TYPES], 'LegalRepresentative');
 }
@@ -188,10 +232,25 @@ export function prepareForSignature(header, payload) {
         signingInput: `${encodedHeader}.${encodedPayload}`,
     };
 }
+/**
+ * Returns the UTF-8 bytes of the canonical `base64url(header).base64url(payload)`
+ * signing input.
+ *
+ * This is the exact byte sequence an external wallet, HSM, or KMS must sign
+ * before the caller assembles the final compact VP JWT with
+ * `buildVpTokenCompact(...)`.
+ */
 export function prepareBytesForSignature(header, payload) {
     const { signingInput } = prepareForSignature(header, payload);
     return new TextEncoder().encode(signingInput);
 }
+/**
+ * Assembles the final compact VP JWT once the caller already has:
+ *
+ * - the base64url-encoded protected header
+ * - the base64url-encoded VP payload
+ * - the detached signature returned by the external signer, also base64url-encoded
+ */
 export function buildVpTokenCompact(encodedHeader, encodedPayload, signatureBase64Url) {
     return `${encodedHeader}.${encodedPayload}.${String(signatureBase64Url || '').trim()}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "publishConfig": {
     "access": "public"
   },