@psavelis/enterprise-blockchain 0.1.0 → 1.1.1

package/dist/integrations/shared/retry.js

@@ -0,0 +1,315 @@
+/**
+ * Shared retry policy and circuit breaker for integration adapters.
+ *
+ * Each platform adapter configures which error codes are retryable:
+ * - Fabric: UNAVAILABLE, DEADLINE_EXCEEDED gRPC status codes
+ * - Besu: SERVER_ERROR, TIMEOUT JSON-RPC errors (not NONCE_TOO_LOW)
+ * - Corda: HTTP 502/503/504 (not 400/401/403)
+ *
+ * OpenTelemetry instrumentation:
+ * - withRetry() creates spans per attempt with error code attributes
+ * - CircuitBreaker emits state transition metrics
+ */
+import { randomBytes } from "node:crypto";
+import { createTracer, createMeter, TelemetryAttributes, SpanStatusCode, } from "../../shared/telemetry.js";
+const tracer = createTracer("retry-policy");
+const meter = createMeter("circuit-breaker");
+// Metrics
+const retryAttemptCounter = meter.createCounter("retry.attempts", {
+    description: "Number of retry attempts",
+    unit: "1",
+});
+const retrySuccessCounter = meter.createCounter("retry.successes", {
+    description: "Number of successful operations (with or without retries)",
+    unit: "1",
+});
+const retryFailureCounter = meter.createCounter("retry.failures", {
+    description: "Number of operations that failed after all retries",
+    unit: "1",
+});
+const circuitBreakerStateGauge = meter.createObservableGauge("circuit_breaker.state", {
+    description: "Current circuit breaker state (0=closed, 1=half-open, 2=open)",
+    unit: "1",
+});
+const circuitBreakerTransitions = meter.createCounter("circuit_breaker.transitions", {
+    description: "Number of circuit breaker state transitions",
+    unit: "1",
+});
+export const DEFAULT_RETRY_POLICY = {
+    maxAttempts: 3,
+    baseDelayMs: 500,
+    maxDelayMs: 10_000,
+    retryableErrors: [],
+};
+// ── Platform-specific retry policies ────────────────────────────────
+export const FABRIC_RETRY_POLICY = {
+    maxAttempts: 4,
+    baseDelayMs: 500,
+    maxDelayMs: 8_000,
+    retryableErrors: ["UNAVAILABLE", "DEADLINE_EXCEEDED"],
+};
+export const BESU_RETRY_POLICY = {
+    maxAttempts: 3,
+    baseDelayMs: 1_000,
+    maxDelayMs: 15_000,
+    retryableErrors: ["SERVER_ERROR", "TIMEOUT"],
+};
+/** Non-retryable Besu errors (fail immediately). */
+export const BESU_NON_RETRYABLE = ["NONCE_TOO_LOW", "INSUFFICIENT_FUNDS"];
+export const CORDA_RETRY_POLICY = {
+    maxAttempts: 3,
+    baseDelayMs: 1_000,
+    maxDelayMs: 10_000,
+    retryableErrors: ["502", "503", "504", "TIMEOUT"],
+};
+/** Non-retryable Corda HTTP status codes. */
+export const CORDA_NON_RETRYABLE = ["400", "401", "403"];
+// ── Retry with exponential backoff ──────────────────────────────────
+export function isRetryable(errorCode, policy, nonRetryable = []) {
+    if (nonRetryable.includes(errorCode))
+        return false;
+    return policy.retryableErrors.includes(errorCode);
+}
+export function computeDelay(attempt, policy) {
+    // Use cryptographically secure randomness to prevent timing attacks
+    // that could exploit predictable backoff patterns
+    const randomByte = randomBytes(1)[0];
+    const jitter = (randomByte % 30) / 100 + 0.85; // ±15%
+    const delay = Math.min(policy.baseDelayMs * Math.pow(2, attempt) * jitter, policy.maxDelayMs);
+    return Math.round(delay);
+}
+export async function withRetry(fn, policy, nonRetryable = [], extractErrorCode = defaultExtractErrorCode, operationName = "operation") {
+    if (policy.maxAttempts < 1) {
+        throw new Error("RetryPolicy.maxAttempts must be >= 1");
+    }
+    return tracer.startActiveSpan(`retry.${operationName}`, {
+        attributes: {
+            [TelemetryAttributes.RETRY_MAX_ATTEMPTS]: policy.maxAttempts,
+        },
+    }, async (parentSpan) => {
+        let lastError;
+        for (let attempt = 0; attempt < policy.maxAttempts; attempt++) {
+            const attemptSpan = tracer.startSpan(`retry.attempt`, {
+                attributes: {
+                    [TelemetryAttributes.RETRY_ATTEMPT]: attempt + 1,
+                    [TelemetryAttributes.RETRY_MAX_ATTEMPTS]: policy.maxAttempts,
+                },
+            });
+            try {
+                retryAttemptCounter.add(1, {
+                    [TelemetryAttributes.RETRY_ATTEMPT]: attempt + 1,
+                });
+                const result = await fn();
+                attemptSpan.setStatus({ code: SpanStatusCode.OK });
+                attemptSpan.end();
+                parentSpan.setStatus({ code: SpanStatusCode.OK });
+                parentSpan.setAttribute("retry.total_attempts", attempt + 1);
+                parentSpan.end();
+                retrySuccessCounter.add(1, {
+                    "retry.total_attempts": attempt + 1,
+                });
+                return result;
+            }
+            catch (err) {
+                lastError = err;
+                const code = extractErrorCode(err);
+                attemptSpan.setAttribute(TelemetryAttributes.RETRY_ERROR_CODE, code);
+                attemptSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: err instanceof Error ? err.message : String(err),
+                });
+                if (err instanceof Error) {
+                    attemptSpan.recordException(err);
+                }
+                attemptSpan.end();
+                if (!isRetryable(code, policy, nonRetryable)) {
+                    parentSpan.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: `Non-retryable error: ${code}`,
+                    });
+                    parentSpan.setAttribute("retry.total_attempts", attempt + 1);
+                    parentSpan.setAttribute(TelemetryAttributes.RETRY_ERROR_CODE, code);
+                    parentSpan.end();
+                    retryFailureCounter.add(1, {
+                        [TelemetryAttributes.RETRY_ERROR_CODE]: code,
+                        "retry.retryable": false,
+                    });
+                    throw err;
+                }
+                if (attempt < policy.maxAttempts - 1) {
+                    const delay = computeDelay(attempt, policy);
+                    parentSpan.addEvent("retry.backoff", {
+                        [TelemetryAttributes.RETRY_DELAY_MS]: delay,
+                        [TelemetryAttributes.RETRY_ATTEMPT]: attempt + 1,
+                    });
+                    await sleep(delay);
+                }
+            }
+        }
+        parentSpan.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: `All ${policy.maxAttempts} attempts exhausted`,
+        });
+        parentSpan.setAttribute("retry.total_attempts", policy.maxAttempts);
+        parentSpan.end();
+        retryFailureCounter.add(1, {
+            "retry.retryable": true,
+            "retry.exhausted": true,
+        });
+        throw lastError;
+    });
+}
+export const DEFAULT_CIRCUIT_BREAKER_OPTIONS = {
+    failureThreshold: 5,
+    cooldownMs: 30_000,
+};
+export class CircuitBreaker {
+    state = "closed";
+    consecutiveFailures = 0;
+    lastFailureTime = 0;
+    options;
+    name;
+    constructor(options = {}, name = "default") {
+        this.options = { ...DEFAULT_CIRCUIT_BREAKER_OPTIONS, ...options };
+        this.name = name;
+        // Register observable gauge for this circuit breaker
+        circuitBreakerStateGauge.addCallback((result) => {
+            const stateValue = this.state === "closed" ? 0 : this.state === "half-open" ? 1 : 2;
+            result.observe(stateValue, {
+                "circuit_breaker.name": this.name,
+            });
+        });
+    }
+    getState() {
+        if (this.state === "open") {
+            const elapsed = Date.now() - this.lastFailureTime;
+            if (elapsed >= this.options.cooldownMs) {
+                this.transitionTo("half-open");
+            }
+        }
+        return this.state;
+    }
+    async execute(fn) {
+        const currentState = this.getState();
+        if (currentState === "open") {
+            throw new Error(`Circuit breaker is OPEN — requests blocked for ${this.options.cooldownMs}ms cooldown`);
+        }
+        // In half-open state, only allow one probe request through.
+        // Immediately transition to open so concurrent callers are blocked
+        // (prevents thundering herd after cooldown).
+        if (currentState === "half-open") {
+            this.transitionTo("open");
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (err) {
+            this.onFailure();
+            throw err;
+        }
+    }
+    transitionTo(newState) {
+        if (this.state !== newState) {
+            const previousState = this.state;
+            this.state = newState;
+            circuitBreakerTransitions.add(1, {
+                "circuit_breaker.name": this.name,
+                "circuit_breaker.from_state": previousState,
+                "circuit_breaker.to_state": newState,
+            });
+        }
+    }
+    onSuccess() {
+        this.consecutiveFailures = 0;
+        this.transitionTo("closed");
+    }
+    onFailure() {
+        this.consecutiveFailures++;
+        this.lastFailureTime = Date.now();
+        if (this.consecutiveFailures >= this.options.failureThreshold) {
+            this.transitionTo("open");
+        }
+    }
+    /** Reset the circuit to closed state. Useful for testing. */
+    reset() {
+        this.transitionTo("closed");
+        this.consecutiveFailures = 0;
+        this.lastFailureTime = 0;
+    }
+    /** Get health status for Kubernetes probes or monitoring. */
+    getHealthStatus() {
+        const currentState = this.getState();
+        return {
+            state: currentState,
+            healthy: currentState === "closed",
+            consecutiveFailures: this.consecutiveFailures,
+            lastFailureTime: this.lastFailureTime > 0
+                ? new Date(this.lastFailureTime).toISOString()
+                : null,
+            cooldownRemainingMs: currentState === "open"
+                ? Math.max(0, this.options.cooldownMs - (Date.now() - this.lastFailureTime))
+                : 0,
+        };
+    }
+}
+/**
+ * Health checker for integration clients.
+ * Combines circuit breaker state with active endpoint probing.
+ */
+export class IntegrationHealthChecker {
+    name;
+    circuitBreaker;
+    probe;
+    constructor(name, circuitBreaker, probe) {
+        this.name = name;
+        this.circuitBreaker = circuitBreaker;
+        this.probe = probe;
+    }
+    async check() {
+        const circuitHealth = this.circuitBreaker.getHealthStatus();
+        const status = {
+            name: this.name,
+            healthy: circuitHealth.healthy,
+            circuitBreaker: circuitHealth,
+            lastCheckTime: new Date().toISOString(),
+        };
+        // If circuit is open, don't probe (would fail anyway)
+        if (!circuitHealth.healthy || !this.probe) {
+            return status;
+        }
+        // Active probe to verify endpoint is reachable
+        const start = Date.now();
+        try {
+            await this.probe();
+            status.latencyMs = Date.now() - start;
+        }
+        catch (err) {
+            status.healthy = false;
+            status.latencyMs = Date.now() - start;
+            status.error =
+                err instanceof Error ? err.message : "Unknown probe failure";
+        }
+        return status;
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+function defaultExtractErrorCode(err) {
+    if (err && typeof err === "object") {
+        const e = err;
+        if (typeof e.code === "string")
+            return e.code;
+        // gRPC-js ServiceError.code is a number (e.g., 14 for UNAVAILABLE)
+        if (typeof e.code === "number")
+            return String(e.code);
+        if (typeof e.status === "number")
+            return String(e.status);
+        if (typeof e.statusCode === "number")
+            return String(e.statusCode);
+    }
+    return "UNKNOWN";
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/mpc/adapters.d.ts

@@ -0,0 +1,36 @@
+/**
+ * MPC Module Infrastructure Adapters
+ *
+ * These adapters implement the ports defined in ports.ts using Node.js crypto.
+ * They live in the infrastructure layer and are injected into domain services.
+ *
+ * @see modules/mpc/src/ports.ts
+ */
+import type { RandomnessProvider, CommitmentProvider } from "./ports.js";
+/**
+ * Node.js crypto implementation of RandomnessProvider.
+ *
+ * Uses Node.js crypto module for cryptographically secure randomness.
+ * This is the default adapter for production use.
+ */
+export declare class NodeRandomnessProvider implements RandomnessProvider {
+    randomBytes(length: number): Buffer;
+    randomInt(min: number, max: number): number;
+}
+/**
+ * Node.js crypto implementation of CommitmentProvider.
+ *
+ * Uses SHA-256 for commitments and timing-safe comparison.
+ */
+export declare class NodeCommitmentProvider implements CommitmentProvider {
+    commitShare(partyId: string, shareIndex: number, value: number | bigint, nonce: string): string;
+    sha256hex(data: string): string;
+    timingSafeCompare(a: string, b: string): boolean;
+}
+/**
+ * Default instances for convenience.
+ * Domain code should prefer dependency injection over these singletons.
+ */
+export declare const defaultRandomnessProvider: NodeRandomnessProvider;
+export declare const defaultCommitmentProvider: NodeCommitmentProvider;
+//# sourceMappingURL=adapters.d.ts.map

package/dist/mpc/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../src/mpc/adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGzE;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAInC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;CAG5C;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D,WAAW,CACT,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,KAAK,EAAE,MAAM,GACZ,MAAM;IAIT,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI/B,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;CAGjD;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,wBAA+B,CAAC;AACtE,eAAO,MAAM,yBAAyB,wBAA+B,CAAC"}

package/dist/mpc/adapters.js

@@ -0,0 +1,46 @@
+/**
+ * MPC Module Infrastructure Adapters
+ *
+ * These adapters implement the ports defined in ports.ts using Node.js crypto.
+ * They live in the infrastructure layer and are injected into domain services.
+ *
+ * @see modules/mpc/src/ports.ts
+ */
+import { randomBytes as nodeRandomBytes, randomInt as nodeRandomInt, } from "node:crypto";
+import { commitShare, sha256hex, timingSafeCompare } from "./crypto.js";
+/**
+ * Node.js crypto implementation of RandomnessProvider.
+ *
+ * Uses Node.js crypto module for cryptographically secure randomness.
+ * This is the default adapter for production use.
+ */
+export class NodeRandomnessProvider {
+    randomBytes(length) {
+        return nodeRandomBytes(length);
+    }
+    randomInt(min, max) {
+        return nodeRandomInt(min, max);
+    }
+}
+/**
+ * Node.js crypto implementation of CommitmentProvider.
+ *
+ * Uses SHA-256 for commitments and timing-safe comparison.
+ */
+export class NodeCommitmentProvider {
+    commitShare(partyId, shareIndex, value, nonce) {
+        return commitShare(partyId, shareIndex, value, nonce);
+    }
+    sha256hex(data) {
+        return sha256hex(data);
+    }
+    timingSafeCompare(a, b) {
+        return timingSafeCompare(a, b);
+    }
+}
+/**
+ * Default instances for convenience.
+ * Domain code should prefer dependency injection over these singletons.
+ */
+export const defaultRandomnessProvider = new NodeRandomnessProvider();
+export const defaultCommitmentProvider = new NodeCommitmentProvider();

package/dist/mpc/crypto.d.ts

@@ -0,0 +1,2 @@
+export { sha256hex, commitShare, timingSafeCompare } from "../shared/index.js";
+//# sourceMappingURL=crypto.d.ts.map

package/dist/mpc/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/mpc/crypto.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/mpc/crypto.js

@@ -0,0 +1,2 @@
+// Re-export shared crypto primitives so existing intra-module imports keep working.
+export { sha256hex, commitShare, timingSafeCompare } from "../shared/index.js";

package/dist/mpc/dsa.d.ts

@@ -0,0 +1,134 @@
+/**
+ * ML-DSA (Dilithium) — Digital Signature Algorithm
+ *
+ * Classical signature schemes (ECDSA, RSA) rely on the hardness of the
+ * discrete logarithm and integer factorisation problems.  Shor's algorithm,
+ * running on a sufficiently large cryptographically-relevant quantum computer
+ * (CRQC), solves both in polynomial time — meaning historical signatures could
+ * be forged retroactively ("harvest-now, forge-later" threat to long-lived
+ * documents and trade rails).
+ *
+ * ML-DSA is the NIST-standardised Digital Signature Algorithm designed to
+ * replace ECDSA.  It is based on the Module-Lattice problem (MLWE / MSIS),
+ * which has no known quantum speedup beyond Grover's algorithm.
+ *
+ * Standard: NIST FIPS 204 (finalised August 2024)
+ * Reference: https://csrc.nist.gov/pubs/fips/204/final
+ *
+ * Noble API note (differs from ML-KEM):
+ *   sign(message, secretKey)       — message is the FIRST argument
+ *   verify(signature, message, publicKey)
+ *
+ * This module wraps @noble/post-quantum, a pure-TypeScript implementation with
+ * zero native-code dependencies, which makes it platform-portable and easy to
+ * audit.
+ */
+/**
+ * ML-DSA parameter sets standardised in FIPS 204.
+ *
+ * The number (44 / 65 / 87) refers to the module dimension:
+ * - 44 → NIST Level 2 (~AES-128, comparable to P-256/ES256)
+ * - 65 → NIST Level 3 (~AES-192, comparable to P-384/ES384)
+ * - 87 → NIST Level 5 (~AES-256, comparable to P-521/ES512)
+ *
+ * NIST recommends ML-DSA-65 as the general-purpose choice for new systems.
+ * ML-DSA-87 is appropriate for root CAs and long-lived documents (30+ years).
+ */
+export type MlDsaParams = "ml-dsa-44" | "ml-dsa-65" | "ml-dsa-87";
+/**
+ * Public key, secret key, and signature lengths (in bytes) for each
+ * parameter set.  Useful for validation and test assertions.
+ *
+ * Note: Noble's secretKey representation includes expanded key material;
+ * hence sk lengths are larger than the FIPS 204 §7 algebraic key sizes.
+ */
+export declare const ML_DSA_SIZES: Record<MlDsaParams, {
+    publicKey: number;
+    secretKey: number;
+    signature: number;
+}>;
+export interface DsaKeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+    /** Which ML-DSA parameter set this keypair belongs to. */
+    params: MlDsaParams;
+}
+export interface DsaSignatureResult {
+    /** The raw ML-DSA signature bytes to send alongside the message. */
+    signature: Uint8Array;
+    /**
+     * SHA-256 hex digest of the signature's hex encoding.
+     *
+     * Computed as: sha256hex(Buffer.from(signature).toString("hex"))
+     *
+     * This means the hash is over the hex-encoded string representation of the
+     * signature bytes, not the raw bytes directly. Suitable for on-chain
+     * commitments or audit logs.
+     */
+    auditCommitment: string;
+}
+export interface DsaAuditRecord {
+    params: MlDsaParams;
+    /**
+     * SHA-256 of the public key's hex encoding — stable identifier for the signer's keypair.
+     * Computed as: sha256hex(Buffer.from(publicKey).toString("hex"))
+     */
+    publicKeyHash: string;
+    /**
+     * SHA-256 of the signature's hex encoding — unique per signing event.
+     * Same as auditCommitment from DsaSignatureResult.
+     */
+    signatureHash: string;
+    /**
+     * SHA-256 of the message's hex encoding — proves which message was signed.
+     * Computed as: sha256hex(Buffer.from(message).toString("hex"))
+     */
+    messageHash: string;
+    /** ISO-8601 timestamp of the signing event. */
+    timestamp: string;
+    /** Byte length of the signature. */
+    signatureLength: number;
+    /** Whether the signature verified correctly at audit time. */
+    verifiedAtAudit: boolean;
+}
+export declare class MlDsaSigner {
+    #private;
+    /**
+     * Generate a new ML-DSA keypair.
+     *
+     * The public key is shared with anyone who needs to verify your signatures.
+     * The secret key must be stored securely — ideally in an HSM or
+     * hardware-backed key store.
+     */
+    generateKeyPair(params: MlDsaParams): DsaKeyPair;
+    /**
+     * Sign a message.
+     *
+     * @param message   - Raw bytes of the message to sign.
+     * @param secretKey - The signer's ML-DSA secret key.
+     * @param params    - Parameter set that was used to generate the keypair.
+     * @returns Signature bytes and an audit commitment hash.
+     */
+    sign(message: Uint8Array, secretKey: Uint8Array, params: MlDsaParams): DsaSignatureResult;
+    /**
+     * Verify a signature.
+     *
+     * @param message   - The original message bytes.
+     * @param signature - The signature to verify.
+     * @param publicKey - The signer's ML-DSA public key.
+     * @param params    - Parameter set used to generate the keypair.
+     * @returns `true` if the signature is valid, `false` otherwise.
+     *
+     * This method never throws on invalid signature bytes — it returns `false`.
+     * This ensures it cannot be used as an oracle for timing attacks.
+     */
+    verify(message: Uint8Array, signature: Uint8Array, publicKey: Uint8Array, params: MlDsaParams): boolean;
+    /**
+     * Produce an on-chain-ready audit record for a signing event.
+     *
+     * The returned object contains only hashes — no secret material — and is
+     * safe to store in a ledger or audit log.
+     */
+    auditRecord(message: Uint8Array, result: DsaSignatureResult, publicKey: Uint8Array, params: MlDsaParams): DsaAuditRecord;
+}
+//# sourceMappingURL=dsa.d.ts.map

package/dist/mpc/dsa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsa.d.ts","sourceRoot":"","sources":["../../src/mpc/dsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAMlE;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAC/B,WAAW,EACX;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAK5D,CAAC;AAMF,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,UAAU,CAAC;IACtB,SAAS,EAAE,UAAU,CAAC;IACtB,0DAA0D;IAC1D,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,SAAS,EAAE,UAAU,CAAC;IACtB;;;;;;;;OAQG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,eAAe,EAAE,OAAO,CAAC;CAC1B;AAMD,qBAAa,WAAW;;IACtB;;;;;;OAMG;IACH,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU;IAMhD;;;;;;;OAOG;IACH,IAAI,CACF,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,EACrB,MAAM,EAAE,WAAW,GAClB,kBAAkB;IAQrB;;;;;;;;;;;OAWG;IACH,MAAM,CACJ,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,EACrB,SAAS,EAAE,UAAU,EACrB,MAAM,EAAE,WAAW,GAClB,OAAO;IAUV;;;;;OAKG;IACH,WAAW,CACT,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,UAAU,EACrB,MAAM,EAAE,WAAW,GAClB,cAAc;CA2BlB"}

package/dist/mpc/dsa.js

@@ -0,0 +1,127 @@
+/**
+ * ML-DSA (Dilithium) — Digital Signature Algorithm
+ *
+ * Classical signature schemes (ECDSA, RSA) rely on the hardness of the
+ * discrete logarithm and integer factorisation problems.  Shor's algorithm,
+ * running on a sufficiently large cryptographically-relevant quantum computer
+ * (CRQC), solves both in polynomial time — meaning historical signatures could
+ * be forged retroactively ("harvest-now, forge-later" threat to long-lived
+ * documents and trade rails).
+ *
+ * ML-DSA is the NIST-standardised Digital Signature Algorithm designed to
+ * replace ECDSA.  It is based on the Module-Lattice problem (MLWE / MSIS),
+ * which has no known quantum speedup beyond Grover's algorithm.
+ *
+ * Standard: NIST FIPS 204 (finalised August 2024)
+ * Reference: https://csrc.nist.gov/pubs/fips/204/final
+ *
+ * Noble API note (differs from ML-KEM):
+ *   sign(message, secretKey)       — message is the FIRST argument
+ *   verify(signature, message, publicKey)
+ *
+ * This module wraps @noble/post-quantum, a pure-TypeScript implementation with
+ * zero native-code dependencies, which makes it platform-portable and easy to
+ * audit.
+ */
+import { ml_dsa44, ml_dsa65, ml_dsa87 } from "@noble/post-quantum/ml-dsa.js";
+import { sha256hex } from "./crypto.js";
+// ---------------------------------------------------------------------------
+// Wire-format byte lengths (empirically verified against @noble/post-quantum)
+// ---------------------------------------------------------------------------
+/**
+ * Public key, secret key, and signature lengths (in bytes) for each
+ * parameter set.  Useful for validation and test assertions.
+ *
+ * Note: Noble's secretKey representation includes expanded key material;
+ * hence sk lengths are larger than the FIPS 204 §7 algebraic key sizes.
+ */
+export const ML_DSA_SIZES = {
+    "ml-dsa-44": { publicKey: 1312, secretKey: 2560, signature: 2420 },
+    "ml-dsa-65": { publicKey: 1952, secretKey: 4032, signature: 3309 },
+    "ml-dsa-87": { publicKey: 2592, secretKey: 4896, signature: 4627 },
+};
+// ---------------------------------------------------------------------------
+// MlDsaSigner class
+// ---------------------------------------------------------------------------
+export class MlDsaSigner {
+    /**
+     * Generate a new ML-DSA keypair.
+     *
+     * The public key is shared with anyone who needs to verify your signatures.
+     * The secret key must be stored securely — ideally in an HSM or
+     * hardware-backed key store.
+     */
+    generateKeyPair(params) {
+        const dsa = this.#suite(params);
+        const { publicKey, secretKey } = dsa.keygen();
+        return { publicKey, secretKey, params };
+    }
+    /**
+     * Sign a message.
+     *
+     * @param message   - Raw bytes of the message to sign.
+     * @param secretKey - The signer's ML-DSA secret key.
+     * @param params    - Parameter set that was used to generate the keypair.
+     * @returns Signature bytes and an audit commitment hash.
+     */
+    sign(message, secretKey, params) {
+        const dsa = this.#suite(params);
+        // Noble ML-DSA API: sign(message, secretKey)
+        const signature = dsa.sign(message, secretKey);
+        const auditCommitment = sha256hex(Buffer.from(signature).toString("hex"));
+        return { signature, auditCommitment };
+    }
+    /**
+     * Verify a signature.
+     *
+     * @param message   - The original message bytes.
+     * @param signature - The signature to verify.
+     * @param publicKey - The signer's ML-DSA public key.
+     * @param params    - Parameter set used to generate the keypair.
+     * @returns `true` if the signature is valid, `false` otherwise.
+     *
+     * This method never throws on invalid signature bytes — it returns `false`.
+     * This ensures it cannot be used as an oracle for timing attacks.
+     */
+    verify(message, signature, publicKey, params) {
+        try {
+            const dsa = this.#suite(params);
+            // Noble ML-DSA API: verify(signature, message, publicKey)
+            return dsa.verify(signature, message, publicKey);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Produce an on-chain-ready audit record for a signing event.
+     *
+     * The returned object contains only hashes — no secret material — and is
+     * safe to store in a ledger or audit log.
+     */
+    auditRecord(message, result, publicKey, params) {
+        const verified = this.verify(message, result.signature, publicKey, params);
+        return {
+            params,
+            publicKeyHash: sha256hex(Buffer.from(publicKey).toString("hex")),
+            signatureHash: result.auditCommitment,
+            messageHash: sha256hex(Buffer.from(message).toString("hex")),
+            timestamp: new Date().toISOString(),
+            signatureLength: result.signature.length,
+            verifiedAtAudit: verified,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    #suite(params) {
+        switch (params) {
+            case "ml-dsa-44":
+                return ml_dsa44;
+            case "ml-dsa-65":
+                return ml_dsa65;
+            case "ml-dsa-87":
+                return ml_dsa87;
+        }
+    }
+}