@psavelis/enterprise-blockchain 0.1.0 → 1.1.1

package/dist/integrations/besu-client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/integrations/besu-client/index.ts"],"names":[],"mappings":"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"}

package/dist/integrations/besu-client/index.js

@@ -0,0 +1,276 @@
+import { Contract, Interface, JsonRpcProvider, NonceManager, Wallet, } from "ethers";
+import consortiumRegistryArtifact from "../../../../../contracts/ConsortiumOrderRegistry.json";
+import { getOptionalEnv, getNumberEnv, getRequiredEnv } from "../shared/env.js";
+import { CircuitBreaker, BESU_RETRY_POLICY, BESU_NON_RETRYABLE, withRetry, } from "../shared/retry.js";
+import { createTracer, withSpan, TelemetryAttributes, } from "../../shared/telemetry.js";
+import { extractErrorMessage, extractErrorCode, isInsufficientFunds, isNonceTooLow, } from "./error-mapper.js";
+const tracer = createTracer("besu-client");
+const consortiumInterface = new Interface(consortiumRegistryArtifact.abi);
+export class BesuProfileFactory {
+    createProfileFromEnv(env = process.env) {
+        const profile = {
+            rpcUrl: getRequiredEnv("BESU_RPC_URL", env),
+            chainId: getNumberEnv("BESU_CHAIN_ID", 1337, env),
+            contractAddress: getRequiredEnv("BESU_CONTRACT_ADDRESS", env),
+        };
+        const walletPrivateKey = getOptionalEnv("BESU_WALLET_PRIVATE_KEY", env);
+        if (walletPrivateKey) {
+            profile.walletPrivateKey = walletPrivateKey;
+        }
+        const privacyGroupId = getOptionalEnv("BESU_PRIVACY_GROUP_ID", env);
+        if (privacyGroupId) {
+            profile.privacyGroupId = privacyGroupId;
+        }
+        return profile;
+    }
+    createProfile(profile) {
+        if (!profile.rpcUrl.startsWith("http")) {
+            throw new Error("BesuRpcProfile.rpcUrl must be an HTTP(S) URL");
+        }
+        if (profile.chainId <= 0) {
+            throw new Error("BesuRpcProfile.chainId must be a positive integer");
+        }
+        return profile;
+    }
+}
+export class BesuProviderFactory {
+    createProvider(profile) {
+        return new JsonRpcProvider(profile.rpcUrl, profile.chainId);
+    }
+    createSigner(profile) {
+        if (!profile.walletPrivateKey) {
+            throw new Error("walletPrivateKey is required to create a Besu signer");
+        }
+        return new Wallet(profile.walletPrivateKey, this.createProvider(profile));
+    }
+    createManagedSigner(profile) {
+        return new NonceManager(this.createSigner(profile));
+    }
+    createContract(profile, runner) {
+        const resolvedRunner = runner ?? this.createProvider(profile);
+        return new Contract(profile.contractAddress, consortiumRegistryArtifact.abi, resolvedRunner);
+    }
+}
+export class BesuGasEstimator {
+    providerFactory;
+    constructor(providerFactory) {
+        this.providerFactory = providerFactory;
+    }
+    async estimateGas(profile, tx, gasLimitOverride) {
+        return withSpan(tracer, "besu.estimateGas", async (span) => {
+            span.setAttribute(TelemetryAttributes.BLOCKCHAIN_PLATFORM, "besu");
+            span.setAttribute("besu.chain_id", profile.chainId);
+            if (gasLimitOverride !== undefined) {
+                span.setAttribute("besu.gas_limit_override", gasLimitOverride.toString());
+                return gasLimitOverride;
+            }
+            try {
+                const gasEstimate = await this.providerFactory
+                    .createProvider(profile)
+                    .estimateGas(tx);
+                span.setAttribute("besu.gas_estimate", gasEstimate.toString());
+                return gasEstimate;
+            }
+            catch (err) {
+                const msg = extractErrorMessage(err);
+                span.setAttribute(TelemetryAttributes.ERROR_MESSAGE, msg);
+                if (isInsufficientFunds(err)) {
+                    throw new Error(`Besu gas estimation failed — sender account has insufficient funds: ${msg}`, { cause: err });
+                }
+                throw new Error(`Besu gas estimation failed: ${msg}`, { cause: err });
+            }
+        });
+    }
+}
+export class BesuTransactionBuilder {
+    buildAnchorOrderTransaction(profile, order, auditProof, gasLimit) {
+        const tx = {
+            to: profile.contractAddress,
+            chainId: profile.chainId,
+            data: consortiumInterface.encodeFunctionData("anchorOrder", [
+                order.id,
+                order.buyer,
+                order.supplier,
+                auditProof,
+            ]),
+        };
+        if (gasLimit !== undefined) {
+            tx.gasLimit = gasLimit;
+        }
+        return tx;
+    }
+    buildAudienceViewTransaction(profile, view, gasLimit) {
+        if (!profile.privacyGroupId) {
+            throw new Error("privacyGroupId is required to build a Besu private transaction");
+        }
+        const proofArg = typeof view.auditProof === "string"
+            ? view.auditProof
+            : JSON.stringify(view.auditProof);
+        const tx = {
+            to: profile.contractAddress,
+            chainId: profile.chainId,
+            data: consortiumInterface.encodeFunctionData("publishAudienceView", [
+                view.orderId,
+                view.audience,
+                JSON.stringify(view.data),
+                proofArg,
+            ]),
+        };
+        if (gasLimit !== undefined) {
+            tx.gasLimit = gasLimit;
+        }
+        return {
+            privacyGroupId: profile.privacyGroupId,
+            transaction: tx,
+        };
+    }
+}
+export class BesuTransactionSender {
+    async sendTransaction(signer, tx) {
+        return withSpan(tracer, "besu.sendTransaction", async (span) => {
+            span.setAttribute(TelemetryAttributes.BLOCKCHAIN_PLATFORM, "besu");
+            if (tx.to && typeof tx.to === "string") {
+                span.setAttribute("besu.to", tx.to);
+            }
+            if (tx.chainId)
+                span.setAttribute("besu.chain_id", Number(tx.chainId));
+            try {
+                const response = await signer.sendTransaction(tx);
+                span.setAttribute(TelemetryAttributes.BLOCKCHAIN_TX_ID, response.hash);
+                return response.hash;
+            }
+            catch (err) {
+                const msg = extractErrorMessage(err);
+                span.setAttribute(TelemetryAttributes.ERROR_MESSAGE, msg);
+                if (isNonceTooLow(err)) {
+                    throw new Error(`Besu NONCE_TOO_LOW — another transaction from this account was mined first. ` +
+                        `Retry with a fresh nonce or use createManagedSigner() for automatic sequencing.`, { cause: err });
+                }
+                if (isInsufficientFunds(err)) {
+                    throw new Error(`Besu INSUFFICIENT_FUNDS — the sender account cannot cover gas × gasPrice. ` +
+                        `Fund the account or lower gasLimit.`, { cause: err });
+                }
+                throw err;
+            }
+        });
+    }
+}
+export class BesuHealthChecker {
+    providerFactory;
+    constructor(providerFactory) {
+        this.providerFactory = providerFactory;
+    }
+    async checkHealth(profile) {
+        return withSpan(tracer, "besu.checkHealth", async (span) => {
+            span.setAttribute(TelemetryAttributes.BLOCKCHAIN_PLATFORM, "besu");
+            span.setAttribute("besu.chain_id", profile.chainId);
+            const start = Date.now();
+            try {
+                const provider = this.providerFactory.createProvider(profile);
+                const [blockNumber, network] = await Promise.all([
+                    provider.getBlockNumber(),
+                    provider.getNetwork(),
+                ]);
+                const latencyMs = Date.now() - start;
+                span.setAttribute("besu.healthy", true);
+                span.setAttribute("besu.block_number", blockNumber.toString());
+                span.setAttribute("besu.latency_ms", latencyMs);
+                return {
+                    healthy: true,
+                    blockNumber: BigInt(blockNumber),
+                    chainId: Number(network.chainId),
+                    latencyMs,
+                };
+            }
+            catch (err) {
+                const latencyMs = Date.now() - start;
+                const errorMsg = extractErrorMessage(err);
+                span.setAttribute("besu.healthy", false);
+                span.setAttribute("besu.latency_ms", latencyMs);
+                span.setAttribute(TelemetryAttributes.ERROR_MESSAGE, errorMsg);
+                return {
+                    healthy: false,
+                    latencyMs,
+                    error: errorMsg,
+                };
+            }
+        });
+    }
+}
+/**
+ * Resilient Besu client with circuit breaker and retry support.
+ *
+ * Circuit breaker prevents cascading failures when Besu RPC is unavailable.
+ * Retry policy handles transient errors (SERVER_ERROR, TIMEOUT) with backoff.
+ *
+ * NOTE: sketch only — do not store key material as plain strings in production
+ */
+export class BesuEthersClientSketch {
+    profileFactory = new BesuProfileFactory();
+    providerFactory = new BesuProviderFactory();
+    txBuilder = new BesuTransactionBuilder();
+    txSender = new BesuTransactionSender();
+    healthChecker = new BesuHealthChecker(this.providerFactory);
+    circuitBreaker;
+    constructor(circuitBreakerOptions) {
+        this.circuitBreaker = new CircuitBreaker(circuitBreakerOptions, "besu-rpc");
+    }
+    createProfileFromEnv(env) {
+        return this.profileFactory.createProfileFromEnv(env);
+    }
+    createProfile(profile) {
+        return this.profileFactory.createProfile(profile);
+    }
+    createProvider(profile) {
+        return this.providerFactory.createProvider(profile);
+    }
+    createSigner(profile) {
+        return this.providerFactory.createSigner(profile);
+    }
+    createManagedSigner(profile) {
+        return this.providerFactory.createManagedSigner(profile);
+    }
+    createContract(profile, runner) {
+        return this.providerFactory.createContract(profile, runner);
+    }
+    async estimateGas(profile, tx, gasLimitOverride) {
+        if (gasLimitOverride !== undefined) {
+            return gasLimitOverride;
+        }
+        return this.circuitBreaker.execute(() => withRetry(async () => {
+            try {
+                return await this.createProvider(profile).estimateGas(tx);
+            }
+            catch (err) {
+                const msg = extractErrorMessage(err);
+                if (isInsufficientFunds(err)) {
+                    throw new Error(`Besu gas estimation failed — sender account has insufficient funds: ${msg}`, { cause: err });
+                }
+                throw new Error(`Besu gas estimation failed: ${msg}`, {
+                    cause: err,
+                });
+            }
+        }, BESU_RETRY_POLICY, BESU_NON_RETRYABLE, extractErrorCode, "besu.estimateGas"));
+    }
+    buildAnchorOrderTransaction(profile, order, auditProof, gasLimit) {
+        return this.txBuilder.buildAnchorOrderTransaction(profile, order, auditProof, gasLimit);
+    }
+    buildAudienceViewTransaction(profile, view, gasLimit) {
+        return this.txBuilder.buildAudienceViewTransaction(profile, view, gasLimit);
+    }
+    sendTransaction(signer, tx) {
+        return this.txSender.sendTransaction(signer, tx);
+    }
+    async checkHealth(profile) {
+        // Health checks bypass circuit breaker to allow probing during recovery
+        return this.healthChecker.checkHealth(profile);
+    }
+    /** Get circuit breaker state for monitoring dashboards. */
+    getCircuitBreakerHealth() {
+        return this.circuitBreaker.getHealthStatus();
+    }
+    /** Reset circuit breaker (use after resolving underlying issues). */
+    resetCircuitBreaker() {
+        this.circuitBreaker.reset();
+    }
+}

package/dist/integrations/besu-client/ports.d.ts

@@ -0,0 +1,44 @@
+import type { Contract, JsonRpcProvider, NonceManager, TransactionRequest, Wallet } from "ethers";
+import type { PurchaseOrder, SharedOrderView } from "../../privacy/domain/entities.js";
+export interface BesuRpcProfile {
+    rpcUrl: string;
+    chainId: number;
+    contractAddress: string;
+    walletPrivateKey?: string;
+    privacyGroupId?: string;
+}
+export interface BesuPrivateTransactionRequest {
+    transaction: TransactionRequest;
+    privacyGroupId: string;
+}
+export interface IBesuProfileFactory {
+    createProfileFromEnv(env?: NodeJS.ProcessEnv): BesuRpcProfile;
+    createProfile(profile: BesuRpcProfile): BesuRpcProfile;
+}
+export interface IBesuProviderFactory {
+    createProvider(profile: BesuRpcProfile): JsonRpcProvider;
+    createSigner(profile: BesuRpcProfile): Wallet;
+    createManagedSigner(profile: BesuRpcProfile): NonceManager;
+    createContract(profile: BesuRpcProfile): Contract;
+}
+export interface IBesuGasEstimator {
+    estimateGas(profile: BesuRpcProfile, tx: TransactionRequest, gasLimitOverride?: bigint): Promise<bigint>;
+}
+export interface IBesuTransactionBuilder {
+    buildAnchorOrderTransaction(profile: BesuRpcProfile, order: PurchaseOrder, auditProof: string, gasLimit?: bigint): TransactionRequest;
+    buildAudienceViewTransaction(profile: BesuRpcProfile, view: SharedOrderView, gasLimit?: bigint): BesuPrivateTransactionRequest;
+}
+export interface IBesuTransactionSender {
+    sendTransaction(signer: NonceManager, tx: TransactionRequest): Promise<string>;
+}
+export interface IBesuHealthChecker {
+    checkHealth(profile: BesuRpcProfile): Promise<BesuHealthStatus>;
+}
+export interface BesuHealthStatus {
+    healthy: boolean;
+    blockNumber?: bigint;
+    chainId?: number;
+    latencyMs: number;
+    error?: string;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/integrations/besu-client/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../../src/integrations/besu-client/ports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,MAAM,EACP,MAAM,QAAQ,CAAC;AAChB,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,6BAA6B;IAC5C,WAAW,EAAE,kBAAkB,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,oBAAoB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,cAAc,CAAC;IAC9D,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAAC;CACxD;AAED,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe,CAAC;IACzD,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC;IAC9C,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,YAAY,CAAC;IAC3D,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,QAAQ,CAAC;CACnD;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CACT,OAAO,EAAE,cAAc,EACvB,EAAE,EAAE,kBAAkB,EACtB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,2BAA2B,CACzB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,aAAa,EACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,kBAAkB,CAAC;IAEtB,4BAA4B,CAC1B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,eAAe,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,6BAA6B,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC,eAAe,CACb,MAAM,EAAE,YAAY,EACpB,EAAE,EAAE,kBAAkB,GACrB,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/integrations/besu-client/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/integrations/corda-gateway/index.d.ts

@@ -0,0 +1,37 @@
+import { type CircuitBreakerOptions } from "../shared/retry.js";
+import type { CordaGatewayProfile, CordaGatewayRequest, ICordaFlowInvoker, ICordaProfileFactory, ICordaRequestBuilder, ProviderClearancePayload } from "./ports.js";
+export type { CordaGatewayProfile, CordaGatewayRequest, ProviderClearancePayload, } from "./ports.js";
+export declare class CordaProfileFactory implements ICordaProfileFactory {
+    createProfileFromEnv(env?: NodeJS.ProcessEnv): CordaGatewayProfile;
+    createProfile(profile: CordaGatewayProfile): CordaGatewayProfile;
+}
+export declare class CordaRequestBuilder implements ICordaRequestBuilder {
+    buildIssueClearanceRequest(profile: CordaGatewayProfile, payload: ProviderClearancePayload): CordaGatewayRequest;
+}
+export declare class CordaFlowInvoker implements ICordaFlowInvoker {
+    invokeFlow(request: CordaGatewayRequest): Promise<Response>;
+}
+/**
+ * Resilient Corda gateway client with circuit breaker and retry support.
+ *
+ * Circuit breaker prevents cascading failures when Corda REST API is unavailable.
+ * Retry policy handles transient HTTP errors (502, 503, 504, TIMEOUT).
+ *
+ * NOTE: sketch only — use a secrets manager or token provider in production
+ */
+export declare class CordaGatewayClientSketch implements ICordaProfileFactory, ICordaRequestBuilder, ICordaFlowInvoker {
+    private readonly profileFactory;
+    private readonly requestBuilder;
+    private readonly flowInvoker;
+    private readonly circuitBreaker;
+    constructor(circuitBreakerOptions?: Partial<CircuitBreakerOptions>);
+    createProfileFromEnv(env?: NodeJS.ProcessEnv): CordaGatewayProfile;
+    createProfile(profile: CordaGatewayProfile): CordaGatewayProfile;
+    buildIssueClearanceRequest(profile: CordaGatewayProfile, payload: ProviderClearancePayload): CordaGatewayRequest;
+    invokeFlow(request: CordaGatewayRequest): Promise<Response>;
+    /** Get circuit breaker state for monitoring dashboards. */
+    getCircuitBreakerHealth(): import("../shared/retry.js").CircuitBreakerHealth;
+    /** Reset circuit breaker (use after resolving underlying issues). */
+    resetCircuitBreaker(): void;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/integrations/corda-gateway/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/integrations/corda-gateway/index.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,qBAAqB,EAC3B,MAAM,oBAAoB,CAAC;AAM5B,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAIpB,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,oBAAoB,CAClB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,mBAAmB;IAStB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB;CAGjE;AAED,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,0BAA0B,CACxB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,wBAAwB,GAChC,mBAAmB;CAgBvB;AAmID,qBAAa,gBAAiB,YAAW,iBAAiB;IAClD,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;CAkClE;AAED;;;;;;;GAOG;AACH,qBAAa,wBACX,YAAW,oBAAoB,EAAE,oBAAoB,EAAE,iBAAiB;IAExE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;gBAEpC,qBAAqB,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC;IAOlE,oBAAoB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,mBAAmB;IAIlE,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB;IAIhE,0BAA0B,CACxB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,wBAAwB,GAChC,mBAAmB;IAItB,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAY3D,2DAA2D;IAC3D,uBAAuB;IAIvB,qEAAqE;IACrE,mBAAmB,IAAI,IAAI;CAG5B"}

package/dist/integrations/corda-gateway/index.js

@@ -0,0 +1,234 @@
+import { getNumberEnv, getRequiredEnv } from "../shared/env.js";
+import { CircuitBreaker, CORDA_RETRY_POLICY, CORDA_NON_RETRYABLE, withRetry, } from "../shared/retry.js";
+import { createTracer, withSpan, TelemetryAttributes, } from "../../shared/telemetry.js";
+const tracer = createTracer("corda-gateway");
+export class CordaProfileFactory {
+    createProfileFromEnv(env = process.env) {
+        return {
+            baseUrl: getRequiredEnv("CORDA_GATEWAY_BASE_URL", env),
+            network: getRequiredEnv("CORDA_GATEWAY_NETWORK", env),
+            bearerToken: getRequiredEnv("CORDA_GATEWAY_TOKEN", env),
+            timeoutMs: getNumberEnv("CORDA_GATEWAY_TIMEOUT_MS", 10000, env),
+        };
+    }
+    createProfile(profile) {
+        return profile;
+    }
+}
+export class CordaRequestBuilder {
+    buildIssueClearanceRequest(profile, payload) {
+        return {
+            method: "POST",
+            url: `${profile.baseUrl}/api/v1/networks/${profile.network}/flows/IssueProviderClearanceFlow`,
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${profile.bearerToken}`,
+            },
+            body: JSON.stringify({
+                clientRequestId: `${payload.providerId}-${payload.scheduledAt}`,
+                command: payload.approved ? "ApproveClearance" : "RejectClearance",
+                payload,
+            }),
+            timeoutMs: profile.timeoutMs,
+        };
+    }
+}
+import { lookup } from "node:dns/promises";
+/**
+ * Check if an IP address is in a private/reserved range.
+ * Covers IPv4 private ranges, loopback, link-local, and IPv6 equivalents.
+ */
+function isPrivateIP(ip) {
+    // IPv4 private/reserved patterns
+    const ipv4PrivatePatterns = [
+        /^127\./, // loopback
+        /^10\./, // Class A private
+        /^172\.(1[6-9]|2\d|3[01])\./, // Class B private
+        /^192\.168\./, // Class C private
+        /^169\.254\./, // link-local
+        /^0\./, // current network
+        /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./, // carrier-grade NAT
+        /^192\.0\.0\./, // IETF protocol assignments
+        /^192\.0\.2\./, // TEST-NET-1
+        /^198\.51\.100\./, // TEST-NET-2
+        /^203\.0\.113\./, // TEST-NET-3
+        /^224\./, // multicast
+        /^240\./, // reserved
+        /^255\.255\.255\.255$/, // broadcast
+    ];
+    // IPv6 private/reserved patterns
+    const ipv6PrivatePatterns = [
+        /^::1$/, // loopback
+        /^::$/, // unspecified
+        /^::ffff:127\./, // IPv4-mapped loopback
+        /^::ffff:10\./, // IPv4-mapped Class A
+        /^::ffff:172\.(1[6-9]|2\d|3[01])\./, // IPv4-mapped Class B
+        /^::ffff:192\.168\./, // IPv4-mapped Class C
+        /^fc/, // unique local (fc00::/7)
+        /^fd/, // unique local (fc00::/7)
+        /^fe80:/, // link-local
+        /^ff/, // multicast
+    ];
+    const lowerIp = ip.toLowerCase();
+    for (const pattern of ipv4PrivatePatterns) {
+        if (pattern.test(lowerIp))
+            return true;
+    }
+    for (const pattern of ipv6PrivatePatterns) {
+        if (pattern.test(lowerIp))
+            return true;
+    }
+    return false;
+}
+/**
+ * Validates that a URL is safe to fetch (SSRF protection).
+ * - Must be HTTPS protocol
+ * - Must not resolve to private/internal IP addresses (prevents DNS rebinding)
+ * - Uses explicit allowlist approach for gateway hosts in production
+ *
+ * IMPORTANT: This performs DNS resolution to prevent DNS rebinding attacks where
+ * an attacker-controlled DNS name initially resolves to a public IP but later
+ * resolves to a private IP (e.g., 127.0.0.1, 10.x.x.x, etc.)
+ *
+ * @throws Error if URL fails validation
+ */
+async function validateGatewayUrl(urlString) {
+    const url = new URL(urlString);
+    // Require HTTPS for production gateway connections
+    if (url.protocol !== "https:") {
+        throw new Error(`SSRF protection: Corda gateway URL must use HTTPS, got ${url.protocol}`);
+    }
+    const hostname = url.hostname.toLowerCase();
+    // Quick check: block obviously private hostnames before DNS lookup
+    if (hostname === "localhost") {
+        throw new Error(`SSRF protection: Corda gateway URL must not target private networks`);
+    }
+    // Resolve hostname to IP address(es) and check each one
+    // This prevents DNS rebinding attacks where a hostname initially resolves
+    // to a public IP but later resolves to a private IP
+    try {
+        // Resolve both IPv4 and IPv6 addresses
+        const results = await Promise.allSettled([
+            lookup(hostname, { family: 4 }),
+            lookup(hostname, { family: 6 }),
+        ]);
+        // Collect all resolved addresses
+        const addresses = [];
+        for (const result of results) {
+            if (result.status === "fulfilled") {
+                addresses.push(result.value.address);
+            }
+        }
+        // If no addresses resolved, the hostname is invalid
+        if (addresses.length === 0) {
+            throw new Error(`SSRF protection: Could not resolve hostname ${hostname}`);
+        }
+        // Check all resolved IPs against private ranges
+        for (const ip of addresses) {
+            if (isPrivateIP(ip)) {
+                throw new Error(`SSRF protection: Corda gateway URL must not target private networks (resolved to ${ip})`);
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("SSRF protection:")) {
+            throw err;
+        }
+        throw new Error(`SSRF protection: DNS resolution failed for ${hostname}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    return url;
+}
+export class CordaFlowInvoker {
+    async invokeFlow(request) {
+        return withSpan(tracer, "corda.invokeFlow", async (span) => {
+            span.setAttribute(TelemetryAttributes.BLOCKCHAIN_PLATFORM, "corda");
+            span.setAttribute("corda.method", request.method);
+            span.setAttribute("corda.timeout_ms", request.timeoutMs);
+            // Validate URL before making the request (SSRF protection)
+            // This performs DNS resolution to prevent DNS rebinding attacks
+            const validatedUrl = await validateGatewayUrl(request.url);
+            try {
+                const response = await fetch(validatedUrl.toString(), {
+                    method: request.method,
+                    headers: request.headers,
+                    body: request.body,
+                    signal: AbortSignal.timeout(request.timeoutMs),
+                });
+                span.setAttribute("corda.response_status", response.status);
+                if (!response.ok) {
+                    const errorMsg = `Corda gateway error: ${response.status} ${response.statusText}`;
+                    span.setAttribute(TelemetryAttributes.ERROR_MESSAGE, errorMsg);
+                    throw new Error(errorMsg);
+                }
+                return response;
+            }
+            catch (err) {
+                if (err instanceof Error) {
+                    span.setAttribute(TelemetryAttributes.ERROR_MESSAGE, err.message);
+                }
+                throw err;
+            }
+        });
+    }
+}
+/**
+ * Resilient Corda gateway client with circuit breaker and retry support.
+ *
+ * Circuit breaker prevents cascading failures when Corda REST API is unavailable.
+ * Retry policy handles transient HTTP errors (502, 503, 504, TIMEOUT).
+ *
+ * NOTE: sketch only — use a secrets manager or token provider in production
+ */
+export class CordaGatewayClientSketch {
+    profileFactory = new CordaProfileFactory();
+    requestBuilder = new CordaRequestBuilder();
+    flowInvoker = new CordaFlowInvoker();
+    circuitBreaker;
+    constructor(circuitBreakerOptions) {
+        this.circuitBreaker = new CircuitBreaker(circuitBreakerOptions, "corda-gateway");
+    }
+    createProfileFromEnv(env) {
+        return this.profileFactory.createProfileFromEnv(env);
+    }
+    createProfile(profile) {
+        return this.profileFactory.createProfile(profile);
+    }
+    buildIssueClearanceRequest(profile, payload) {
+        return this.requestBuilder.buildIssueClearanceRequest(profile, payload);
+    }
+    invokeFlow(request) {
+        return this.circuitBreaker.execute(() => withRetry(() => this.flowInvoker.invokeFlow(request), CORDA_RETRY_POLICY, CORDA_NON_RETRYABLE, extractHttpErrorCode, "corda.invokeFlow"));
+    }
+    /** Get circuit breaker state for monitoring dashboards. */
+    getCircuitBreakerHealth() {
+        return this.circuitBreaker.getHealthStatus();
+    }
+    /** Reset circuit breaker (use after resolving underlying issues). */
+    resetCircuitBreaker() {
+        this.circuitBreaker.reset();
+    }
+}
+/**
+ * Extract HTTP error codes for retry policy decisions.
+ */
+function extractHttpErrorCode(err) {
+    if (err instanceof Error) {
+        // Check for timeout errors
+        if (err.name === "TimeoutError" || err.message.includes("timeout")) {
+            return "TIMEOUT";
+        }
+        // Extract HTTP status from error message (e.g., "Corda gateway error: 502 Bad Gateway")
+        const statusMatch = err.message.match(/(\d{3})/);
+        if (statusMatch?.[1]) {
+            return statusMatch[1];
+        }
+    }
+    if (err && typeof err === "object") {
+        const e = err;
+        if (typeof e.status === "number")
+            return String(e.status);
+        if (typeof e.statusCode === "number")
+            return String(e.statusCode);
+    }
+    return "UNKNOWN";
+}

package/dist/integrations/corda-gateway/ports.d.ts

@@ -0,0 +1,33 @@
+export interface CordaGatewayProfile {
+    baseUrl: string;
+    network: string;
+    bearerToken: string;
+    timeoutMs: number;
+}
+export interface CordaGatewayRequest {
+    method: "POST";
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+    timeoutMs: number;
+}
+export interface ProviderClearancePayload {
+    providerId: string;
+    facility: string;
+    jurisdiction: string;
+    scheduledAt: string;
+    requiredCredentials: string[];
+    approved: boolean;
+    reasons: string[];
+}
+export interface ICordaProfileFactory {
+    createProfileFromEnv(env?: NodeJS.ProcessEnv): CordaGatewayProfile;
+    createProfile(profile: CordaGatewayProfile): CordaGatewayProfile;
+}
+export interface ICordaRequestBuilder {
+    buildIssueClearanceRequest(profile: CordaGatewayProfile, payload: ProviderClearancePayload): CordaGatewayRequest;
+}
+export interface ICordaFlowInvoker {
+    invokeFlow(request: CordaGatewayRequest): Promise<Response>;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/integrations/corda-gateway/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../../src/integrations/corda-gateway/ports.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,oBAAoB,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,mBAAmB,CAAC;IACnE,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CAAC;CAClE;AAED,MAAM,WAAW,oBAAoB;IACnC,0BAA0B,CACxB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,wBAAwB,GAChC,mBAAmB,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC7D"}

package/dist/integrations/corda-gateway/ports.js

@@ -0,0 +1 @@
+export {};