gdc-common-utils-ts 2.0.10 → 2.0.11

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/package.json

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