gdc-common-utils-ts 1.10.0 → 1.11.0

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. */

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. */

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/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/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;
@@ -112,5 +120,20 @@ export declare function prepareForSignature(header: VpTokenHeader, payload: VpTo
     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

@@ -232,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.10.0",
+  "version": "1.11.0",
   "publishConfig": {
     "access": "public"
   },