gdc-common-utils-ts 2.0.9 → 2.0.11

package/README.md

@@ -136,6 +136,7 @@ If you need the canonical explanation of how DIDComm envelope, batch body,
 entry types, FHIR-like resources, and `resource.meta.claims` fit together,
 read first:
 
+- [`docs/101-ID_TOKEN.md`](docs/101-ID_TOKEN.md)
 - [`docs/101-COMMUNICATION_LAYERING.md`](docs/101-COMMUNICATION_LAYERING.md)
 - [`docs/101-BUNDLE_EDITOR_READER.md`](docs/101-BUNDLE_EDITOR_READER.md)
 - [`docs/101-CLINICAL-IPS.md`](docs/101-CLINICAL-IPS.md)

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

@@ -0,0 +1,60 @@
+import type { ClassicPublicJwk } from '../interfaces/Cryptography.types';
+/**
+ * Legacy JOSE signature algorithms still commonly used by BFF, controller, and
+ * test fixtures before a runtime switches to post-quantum signers.
+ *
+ * Notes:
+ * - `ES384` maps to the NIST P-384 curve
+ * - `ES256K` maps to the secp256k1 curve often used by wallet-oriented flows
+ *
+ * Post-quantum deterministic key generation remains available through
+ * `ICryptography.generateKeyPairMlDsa(...)` and
+ * `ICryptography.generateKeyPairMlKem(...)`.
+ */
+export type DeterministicEcJwkAlgorithm = 'ES256K' | 'ES384';
+/**
+ * Deterministic EC signing material derived from a stable textual seed.
+ *
+ * This helper exists for:
+ * - reproducible tests
+ * - local/live demos
+ * - external-signing examples where auditors must regenerate the same public
+ *   JWK without importing PEM files or depending on random key generation
+ *
+ * Important:
+ * - the derived private key is deterministic for the same
+ *   `seed + purpose + alg`
+ * - ECDSA signatures generated later may still differ across crypto providers,
+ *   so callers should normally assert signature verification rather than the
+ *   full compact token bytes
+ */
+export type DeterministicEcJwkPair = {
+    publicJwk: ClassicPublicJwk & {
+        use: 'sig';
+        kid: string;
+    };
+    privateJwk: ClassicPublicJwk & {
+        use: 'sig';
+        kid: string;
+        d: string;
+    };
+    alg: DeterministicEcJwkAlgorithm;
+    seed: string;
+    purpose: string;
+};
+/**
+ * Derives one reproducible EC JWK pair from a stable seed string.
+ *
+ * @param input.seed Stable textual seed chosen by the caller.
+ * @param input.purpose Logical namespace such as `virtual-bff`, `controller`,
+ * or `demo-host`.
+ * @param input.alg JOSE algorithm/curve family. Defaults to `ES384`.
+ *
+ * @see RFC 7517 JSON Web Key (JWK)
+ * @see RFC 7518 JSON Web Algorithms (JWA)
+ */
+export declare function deriveDeterministicEcJwkPair(input: {
+    seed: string;
+    purpose: string;
+    alg?: DeterministicEcJwkAlgorithm;
+}): DeterministicEcJwkPair;

package/dist/utils/deterministic-jwk.js

@@ -0,0 +1,97 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { createECDH, createHash } from 'crypto';
+const EC_CURVE_BY_ALG = {
+    ES256K: {
+        alg: 'ES256K',
+        nodeCurve: 'secp256k1',
+        jwkCrv: 'secp256k1',
+        coordinateBytes: 32,
+    },
+    ES384: {
+        alg: 'ES384',
+        nodeCurve: 'secp384r1',
+        jwkCrv: 'P-384',
+        coordinateBytes: 48,
+    },
+};
+function sha256Base64Url(input) {
+    return createHash('sha256').update(input, 'utf8').digest('base64url');
+}
+/**
+ * Expands an arbitrary text seed into enough bytes for one EC private scalar.
+ *
+ * Each block includes both a deterministic `attempt` and `counter`, so callers
+ * can keep retrying reproducible candidates until the target curve accepts one.
+ */
+function expandSeedBytes(seed, purpose, size, attempt) {
+    const chunks = [];
+    let counter = 0;
+    while (Buffer.concat(chunks).length < size) {
+        chunks.push(createHash('sha512')
+            .update(seed, 'utf8')
+            .update(':', 'utf8')
+            .update(purpose, 'utf8')
+            .update(':', 'utf8')
+            .update(String(attempt), 'utf8')
+            .update(':', 'utf8')
+            .update(String(counter), 'utf8')
+            .digest());
+        counter += 1;
+    }
+    return Buffer.concat(chunks).subarray(0, size);
+}
+/**
+ * Derives one reproducible EC JWK pair from a stable seed string.
+ *
+ * @param input.seed Stable textual seed chosen by the caller.
+ * @param input.purpose Logical namespace such as `virtual-bff`, `controller`,
+ * or `demo-host`.
+ * @param input.alg JOSE algorithm/curve family. Defaults to `ES384`.
+ *
+ * @see RFC 7517 JSON Web Key (JWK)
+ * @see RFC 7518 JSON Web Algorithms (JWA)
+ */
+export function deriveDeterministicEcJwkPair(input) {
+    const alg = input.alg ?? 'ES384';
+    const curve = EC_CURVE_BY_ALG[alg];
+    for (let attempt = 0; attempt < 256; attempt += 1) {
+        const candidate = expandSeedBytes(input.seed, input.purpose, curve.coordinateBytes, attempt);
+        try {
+            const ecdh = createECDH(curve.nodeCurve);
+            ecdh.setPrivateKey(candidate);
+            const privateKey = ecdh.getPrivateKey();
+            const publicKey = ecdh.getPublicKey(undefined, 'uncompressed');
+            const x = publicKey.subarray(1, 1 + curve.coordinateBytes);
+            const y = publicKey.subarray(1 + curve.coordinateBytes, 1 + (curve.coordinateBytes * 2));
+            const kid = `${input.purpose}-${alg.toLowerCase()}-${sha256Base64Url(`${input.seed}:${input.purpose}:${alg}`).slice(0, 16)}`;
+            return {
+                alg,
+                seed: input.seed,
+                purpose: input.purpose,
+                publicJwk: {
+                    kty: 'EC',
+                    crv: curve.jwkCrv,
+                    alg,
+                    use: 'sig',
+                    kid,
+                    x: x.toString('base64url'),
+                    y: y.toString('base64url'),
+                },
+                privateJwk: {
+                    kty: 'EC',
+                    crv: curve.jwkCrv,
+                    alg,
+                    use: 'sig',
+                    kid,
+                    x: x.toString('base64url'),
+                    y: y.toString('base64url'),
+                    d: privateKey.toString('base64url'),
+                },
+            };
+        }
+        catch {
+            // Retry the next deterministic candidate until the curve accepts it.
+        }
+    }
+    throw new Error(`Could not derive a valid ${alg} key from deterministic seed '${input.seed}'.`);
+}

package/dist/utils/index.d.ts

@@ -19,6 +19,7 @@ export * from './did-resolution';
 export * from './dataspace-discovery';
 export * from './dataspace-discovery-defaults';
 export * from './dataspace-protocol';
+export * from './deterministic-jwk';
 export * from './employee';
 export * from './evidence-blockchain-references';
 export * from './didcomm';
@@ -63,6 +64,7 @@ export * from './invoice-bundle';
 export * from './ips-bundle-claims';
 export * from './interoperable-resource-operation';
 export * from './jwt';
+export * from './jwt-signer';
 export * from './jwk-thumbprint';
 export * from './legal-organization-onboarding';
 export * from './legal-organization-verification-transaction';

package/dist/utils/index.js

@@ -19,6 +19,7 @@ export * from './did-resolution.js';
 export * from './dataspace-discovery.js';
 export * from './dataspace-discovery-defaults.js';
 export * from './dataspace-protocol.js';
+export * from './deterministic-jwk.js';
 export * from './employee.js';
 export * from './evidence-blockchain-references.js';
 export * from './didcomm.js';
@@ -63,6 +64,7 @@ export * from './invoice-bundle.js';
 export * from './ips-bundle-claims.js';
 export * from './interoperable-resource-operation.js';
 export * from './jwt.js';
+export * from './jwt-signer.js';
 export * from './jwk-thumbprint.js';
 export * from './legal-organization-onboarding.js';
 export * from './legal-organization-verification-transaction.js';

package/dist/utils/jwt-signer.d.ts

@@ -0,0 +1,80 @@
+import { type JoseSignatureAlgorithm } from '../constants/cryptography';
+import type { ICryptography } from '../interfaces/ICryptography';
+import type { PublicJwk, ClassicPublicJwk } from '../interfaces/Cryptography.types';
+export type JwtSignerMode = 'deterministic' | 'random';
+export type JwtSignerMaterial = {
+    kind: 'classic-ec';
+    publicJwk: ClassicPublicJwk & {
+        kid: string;
+        use: 'sig';
+    };
+    privateJwk: ClassicPublicJwk & {
+        kid: string;
+        use: 'sig';
+        d: string;
+    };
+} | {
+    kind: 'ml-dsa';
+    publicJwk: PublicJwk & {
+        kid: string;
+        use?: string;
+    };
+    secretKeyBytes: Uint8Array;
+};
+export type PreparedJwtSigningInput = {
+    protectedHeader: Record<string, unknown>;
+    encodedHeader: string;
+    encodedPayload: string;
+    signingInput: string;
+    signingBytes: Uint8Array;
+};
+export interface JwtSigner {
+    getMode(): JwtSignerMode;
+    getAlgorithm(): JoseSignatureAlgorithm;
+    getPurpose(): string;
+    getPublicJwk(): PublicJwk;
+    getPrivateMaterial(): JWKLikePrivateMaterial;
+    getKid(): string;
+    getThumbprint(): string;
+    getThumbprintUri(): string;
+    prepareJwt(input: {
+        payload: Record<string, unknown>;
+        header?: Record<string, unknown>;
+        typ?: string;
+        kid?: string;
+    }): PreparedJwtSigningInput;
+    buildCompact(signatureBase64Url: string, prepared: Pick<PreparedJwtSigningInput, 'encodedHeader' | 'encodedPayload'>): string;
+    buildUnsignedJwt(payload: Record<string, unknown>, options?: Readonly<{
+        nowSeconds?: number;
+        ttlSeconds?: number;
+        nonce?: string;
+    }>): string;
+}
+export type JWKLikePrivateMaterial = (ClassicPublicJwk & {
+    kid: string;
+    use: 'sig';
+    d: string;
+}) | Uint8Array;
+export type CreateJwtSignerOptions = {
+    alg: JoseSignatureAlgorithm;
+    purpose: string;
+    seed?: string | Uint8Array;
+    cryptography?: Pick<ICryptography, 'generateKeyPairMlDsa'>;
+};
+/**
+ * Creates one high-level JWT signer façade for docs, tests, BFF helpers, and
+ * controller/wallet flows.
+ *
+ * Contract:
+ * - if `seed` is provided, the signer runs in deterministic mode
+ * - if `seed` is omitted, the signer generates fresh random material
+ *
+ * This helper intentionally exposes a small integrator-facing surface:
+ * - get the public JWK / kid / thumbprint
+ * - prepare the exact `header.payload` signing input
+ * - assemble the final compact JWT afterwards
+ *
+ * It does not hide the real external-signing step. That step still belongs to
+ * a KMS, HSM, wallet, or trusted issuer.
+ */
+export declare function createJwtSigner(options: CreateJwtSignerOptions): Promise<JwtSigner>;

package/dist/utils/jwt-signer.js

@@ -0,0 +1,134 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { randomBytes } from 'crypto';
+import { ClassicalJoseSignatureAlgorithms, JwkKeyUses } from '../constants/cryptography.js';
+import { Content } from './content.js';
+import { buildJwtCompact, buildUnsignedJwt, prepareJwtBytesForSignature, prepareJwtForSignature, } from './jwt.js';
+import { computeRfc7638JwkThumbprint, toJwkThumbprintSha256Urn, } from './jwk-thumbprint.js';
+import { deriveDeterministicEcJwkPair, } from './deterministic-jwk.js';
+function isClassicEcAlg(alg) {
+    return alg === ClassicalJoseSignatureAlgorithms.Es384 || alg === ClassicalJoseSignatureAlgorithms.Es256K;
+}
+function resolveMode(seed) {
+    return seed === undefined ? 'random' : 'deterministic';
+}
+function resolveSeedString(seed) {
+    if (typeof seed === 'string')
+        return seed;
+    if (seed instanceof Uint8Array)
+        return Content.bytesToRawBase64UrlSafe(seed);
+    return randomBytes(32).toString('base64url');
+}
+/**
+ * Creates one high-level JWT signer façade for docs, tests, BFF helpers, and
+ * controller/wallet flows.
+ *
+ * Contract:
+ * - if `seed` is provided, the signer runs in deterministic mode
+ * - if `seed` is omitted, the signer generates fresh random material
+ *
+ * This helper intentionally exposes a small integrator-facing surface:
+ * - get the public JWK / kid / thumbprint
+ * - prepare the exact `header.payload` signing input
+ * - assemble the final compact JWT afterwards
+ *
+ * It does not hide the real external-signing step. That step still belongs to
+ * a KMS, HSM, wallet, or trusted issuer.
+ */
+export async function createJwtSigner(options) {
+    const mode = resolveMode(options.seed);
+    const seedText = resolveSeedString(options.seed);
+    const alg = options.alg;
+    let material;
+    if (isClassicEcAlg(alg)) {
+        const pair = deriveDeterministicEcJwkPair({
+            seed: seedText,
+            purpose: options.purpose,
+            alg,
+        });
+        material = {
+            kind: 'classic-ec',
+            publicJwk: pair.publicJwk,
+            privateJwk: pair.privateJwk,
+        };
+    }
+    else {
+        if (!options.cryptography) {
+            throw new Error(`createJwtSigner requires options.cryptography for post-quantum algorithm '${alg}'.`);
+        }
+        const seedBytes = options.seed === undefined
+            ? undefined
+            : options.seed instanceof Uint8Array
+                ? options.seed
+                : Content.stringToBytesUTF8(options.seed);
+        const generated = await options.cryptography.generateKeyPairMlDsa(seedBytes, alg);
+        material = {
+            kind: 'ml-dsa',
+            publicJwk: {
+                ...generated.publicJWKey,
+                use: JwkKeyUses.Signature,
+            },
+            secretKeyBytes: generated.secretKeyBytes,
+        };
+    }
+    const sourcePublicJwk = material.publicJwk;
+    const thumbprintJwk = sourcePublicJwk;
+    const thumbprint = computeRfc7638JwkThumbprint(thumbprintJwk);
+    const thumbprintUri = toJwkThumbprintSha256Urn(thumbprintJwk);
+    const keyId = thumbprintUri;
+    const publicJwk = {
+        ...sourcePublicJwk,
+        kid: keyId,
+    };
+    const privateMaterial = material.kind === 'classic-ec'
+        ? {
+            ...material.privateJwk,
+            kid: keyId,
+        }
+        : material.secretKeyBytes;
+    return {
+        getMode() {
+            return mode;
+        },
+        getAlgorithm() {
+            return alg;
+        },
+        getPurpose() {
+            return options.purpose;
+        },
+        getPublicJwk() {
+            return publicJwk;
+        },
+        getPrivateMaterial() {
+            return privateMaterial;
+        },
+        getKid() {
+            return keyId;
+        },
+        getThumbprint() {
+            return thumbprint;
+        },
+        getThumbprintUri() {
+            return thumbprintUri;
+        },
+        prepareJwt(input) {
+            const protectedHeader = {
+                alg,
+                typ: input.typ ?? 'JWT',
+                ...(input.header || {}),
+                kid: keyId,
+            };
+            const prepared = prepareJwtForSignature(protectedHeader, input.payload);
+            return {
+                protectedHeader,
+                ...prepared,
+                signingBytes: prepareJwtBytesForSignature(protectedHeader, input.payload),
+            };
+        },
+        buildCompact(signatureBase64Url, prepared) {
+            return buildJwtCompact(prepared.encodedHeader, prepared.encodedPayload, signatureBase64Url);
+        },
+        buildUnsignedJwt(payload, optionsForUnsigned) {
+            return buildUnsignedJwt(payload, optionsForUnsigned);
+        },
+    };
+}

package/dist/utils/jwt.d.ts

@@ -51,6 +51,53 @@ export declare function encodeSignature(signatureBytes?: Uint8Array): string;
  * @returns A compact JWT string.
  */
 export declare function compactJWT(header: object, payload: object, signatureBytes?: Uint8Array): Promise<string>;
+/**
+ * Prepares the JOSE compact-signing input for an externally signed JWT/JWS.
+ *
+ * This helper is intended for BFF, wallet, Expo/native, or server-side flows
+ * where the signing key lives in an external KMS/HSM and the application must:
+ *
+ * 1. build the protected header and JWT payload locally
+ * 2. obtain the canonical `base64url(header).base64url(payload)` string
+ * 3. sign that exact byte sequence with the external signer
+ * 4. assemble the final compact JWS/JWT by appending the returned signature
+ *
+ * References:
+ * - RFC 7515 (JWS), Compact Serialization
+ * - RFC 7519 (JWT)
+ * - OpenID Connect Core 1.0 (`id_token` profile claims such as `email`)
+ *
+ * Note:
+ * - this helper only prepares the compact signing input
+ * - it does not verify that the payload is a particular profile such as
+ *   `vp_token`, `id_token`, or `private_key_jwt`
+ */
+export declare function prepareJwtForSignature(header: object, payload: object): {
+    encodedHeader: string;
+    encodedPayload: string;
+    signingInput: string;
+};
+/**
+ * Returns the UTF-8 bytes of the canonical compact JWT/JWS signing input.
+ *
+ * This is the exact byte sequence that an external signer must sign before the
+ * caller assembles the final compact JWT string with
+ * `buildJwtCompact(...)`.
+ */
+export declare function prepareJwtBytesForSignature(header: object, payload: object): Uint8Array;
+/**
+ * Assembles the final compact JWT/JWS once the caller already has:
+ *
+ * - the base64url-encoded protected header
+ * - the base64url-encoded payload
+ * - the detached signature returned by the external signer, also base64url-encoded
+ *
+ * This helper is profile-agnostic. It can be used for:
+ * - OpenID Connect `id_token`
+ * - `vp_token`
+ * - other compact JWS/JWT profiles that follow RFC 7515 / RFC 7519
+ */
+export declare function buildJwtCompact(encodedHeader: string, encodedPayload: string, signatureBase64Url: string): string;
 /**
  * Builds an unsigned compact JWT with `alg=none`.
  *

package/dist/utils/jwt.js

@@ -152,6 +152,62 @@ export async function compactJWT(header, payload, signatureBytes) {
     const encodedSignature = encodeSignature(signatureBytes);
     return `${encodedHeader}.${encodedPayload}.${encodedSignature}`;
 }
+/**
+ * Prepares the JOSE compact-signing input for an externally signed JWT/JWS.
+ *
+ * This helper is intended for BFF, wallet, Expo/native, or server-side flows
+ * where the signing key lives in an external KMS/HSM and the application must:
+ *
+ * 1. build the protected header and JWT payload locally
+ * 2. obtain the canonical `base64url(header).base64url(payload)` string
+ * 3. sign that exact byte sequence with the external signer
+ * 4. assemble the final compact JWS/JWT by appending the returned signature
+ *
+ * References:
+ * - RFC 7515 (JWS), Compact Serialization
+ * - RFC 7519 (JWT)
+ * - OpenID Connect Core 1.0 (`id_token` profile claims such as `email`)
+ *
+ * Note:
+ * - this helper only prepares the compact signing input
+ * - it does not verify that the payload is a particular profile such as
+ *   `vp_token`, `id_token`, or `private_key_jwt`
+ */
+export function prepareJwtForSignature(header, payload) {
+    const encodedHeader = encodeHeader(header);
+    const encodedPayload = Content.objectToRawBase64UrlSafe(payload);
+    return {
+        encodedHeader,
+        encodedPayload,
+        signingInput: `${encodedHeader}.${encodedPayload}`,
+    };
+}
+/**
+ * Returns the UTF-8 bytes of the canonical compact JWT/JWS signing input.
+ *
+ * This is the exact byte sequence that an external signer must sign before the
+ * caller assembles the final compact JWT string with
+ * `buildJwtCompact(...)`.
+ */
+export function prepareJwtBytesForSignature(header, payload) {
+    const { signingInput } = prepareJwtForSignature(header, payload);
+    return new TextEncoder().encode(signingInput);
+}
+/**
+ * Assembles the final compact JWT/JWS once the caller already has:
+ *
+ * - the base64url-encoded protected header
+ * - the base64url-encoded payload
+ * - the detached signature returned by the external signer, also base64url-encoded
+ *
+ * This helper is profile-agnostic. It can be used for:
+ * - OpenID Connect `id_token`
+ * - `vp_token`
+ * - other compact JWS/JWT profiles that follow RFC 7515 / RFC 7519
+ */
+export function buildJwtCompact(encodedHeader, encodedPayload, signatureBase64Url) {
+    return `${encodedHeader}.${encodedPayload}.${String(signatureBase64Url || '').trim()}`;
+}
 /**
  * Builds an unsigned compact JWT with `alg=none`.
  *

package/dist/utils/vp-token.js

@@ -1,5 +1,4 @@
-// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
-import { Content } from './content.js';
+import { buildJwtCompact, prepareJwtBytesForSignature, prepareJwtForSignature } from './jwt.js';
 import { ORGANIZATION_ACTIVATION_VC_TYPES, REPRESENTATIVE_ACTIVATION_VC_TYPES, W3cCredentialContexts, W3cCredentialTypes, } from '../constants/verifiable-credentials.js';
 function fallbackId() {
     const rand = Math.random().toString(36).slice(2, 10);
@@ -224,13 +223,7 @@ export function addLegalRepresentativeCredential(vpPayload, vc) {
     return addTypedVC(vpPayload, vc, [...REPRESENTATIVE_ACTIVATION_VC_TYPES], 'LegalRepresentative');
 }
 export function prepareForSignature(header, payload) {
-    const encodedHeader = Content.objectToRawBase64UrlSafe(header);
-    const encodedPayload = Content.objectToRawBase64UrlSafe(payload);
-    return {
-        encodedHeader,
-        encodedPayload,
-        signingInput: `${encodedHeader}.${encodedPayload}`,
-    };
+    return prepareJwtForSignature(header, payload);
 }
 /**
  * Returns the UTF-8 bytes of the canonical `base64url(header).base64url(payload)`
@@ -241,8 +234,7 @@ export function prepareForSignature(header, payload) {
  * `buildVpTokenCompact(...)`.
  */
 export function prepareBytesForSignature(header, payload) {
-    const { signingInput } = prepareForSignature(header, payload);
-    return new TextEncoder().encode(signingInput);
+    return prepareJwtBytesForSignature(header, payload);
 }
 /**
  * Assembles the final compact VP JWT once the caller already has:
@@ -252,5 +244,5 @@ export function prepareBytesForSignature(header, payload) {
  * - the detached signature returned by the external signer, also base64url-encoded
  */
 export function buildVpTokenCompact(encodedHeader, encodedPayload, signatureBase64Url) {
-    return `${encodedHeader}.${encodedPayload}.${String(signatureBase64Url || '').trim()}`;
+    return buildJwtCompact(encodedHeader, encodedPayload, signatureBase64Url);
 }

package/package.json

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