@fairmint/canton-node-sdk 0.0.234 → 0.0.236

package/build/src/utils/external-signing/canton-ed25519-signer.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CANTON_ED25519_SIGNING_REQUEST_TTL_MS = exports.DEFAULT_CANTON_ED25519_SIGNING_REQUEST_TTL_MS = exports.CantonEd25519SigningPurpose = void 0;
+exports.signAndVerifyCantonEd25519Payload = signAndVerifyCantonEd25519Payload;
+exports.normalizeCantonEd25519Signature = normalizeCantonEd25519Signature;
+const errors_1 = require("../../core/errors");
+const canton_protocol_1 = require("./canton-protocol");
+exports.CantonEd25519SigningPurpose = {
+    EXTERNAL_PARTY_TOPOLOGY: 'external-party-topology',
+    INTERACTIVE_SUBMISSION: 'interactive-submission',
+};
+exports.DEFAULT_CANTON_ED25519_SIGNING_REQUEST_TTL_MS = 5 * 60 * 1000;
+exports.MAX_CANTON_ED25519_SIGNING_REQUEST_TTL_MS = 15 * 60 * 1000;
+/** Calls an external signer and independently verifies its response against the signer's declared public key. */
+async function signAndVerifyCantonEd25519Payload(options) {
+    const purpose = validateSigningPurpose(options.purpose);
+    const operationId = validateRequiredString('operationId', options.operationId);
+    const synchronizerId = validateRequiredString('synchronizerId', options.synchronizerId);
+    const payloadHex = normalizeHexPayload(options.payloadHex);
+    const requestTtlMs = validateRequestTtlMs(options.requestTtlMs ?? exports.DEFAULT_CANTON_ED25519_SIGNING_REQUEST_TTL_MS);
+    const now = options.now ?? Date.now;
+    const issuedAtMs = validateTimestamp(now());
+    const issuedAt = new Date(issuedAtMs).toISOString();
+    const expiresAt = new Date(issuedAtMs + requestTtlMs).toISOString();
+    const context = options.context === undefined ? undefined : normalizeSigningContext(options.context);
+    const publicKeyBase64 = (0, canton_protocol_1.normalizeEd25519PublicKeyForCanton)(options.signer.publicKeyBase64);
+    const publicKeyFingerprint = (0, canton_protocol_1.assertCantonPartyMatchesPublicKey)({
+        partyId: options.partyId,
+        publicKeyBase64,
+    });
+    const request = {
+        purpose,
+        operationId,
+        partyId: options.partyId,
+        publicKeyBase64,
+        publicKeyFingerprint,
+        synchronizerId,
+        payloadHex,
+        payloadBase64: (0, canton_protocol_1.hashHexToBase64)(payloadHex),
+        issuedAt,
+        expiresAt,
+        ...(context !== undefined ? { context } : {}),
+    };
+    const signatureBase64 = normalizeCantonEd25519Signature(await waitForCantonSigner(options.signer, request, requestTtlMs, options.signal));
+    if (validateTimestamp(now()) >= issuedAtMs + requestTtlMs) {
+        throw new errors_1.ValidationError('Canton Ed25519 signing request expired before the signer completed', {
+            operationId,
+            expiresAt,
+        });
+    }
+    (0, canton_protocol_1.assertEd25519Signature)({
+        publicKeyBase64,
+        payload: Buffer.from(payloadHex, 'hex'),
+        signatureBase64,
+        failureMessage: 'External Canton signer returned an invalid Ed25519 signature',
+    });
+    return { request, signatureBase64 };
+}
+async function waitForCantonSigner(signer, request, requestTtlMs, externalSignal) {
+    if (externalSignal?.aborted) {
+        throw signingAborted(request.operationId);
+    }
+    const controller = new AbortController();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            externalSignal?.removeEventListener('abort', onAbort);
+            callback();
+        };
+        const onAbort = () => {
+            // Preserve a signer result that settled before abort but whose promise handler is already queued.
+            queueMicrotask(() => finish(() => reject(signingAborted(request.operationId))));
+            controller.abort();
+        };
+        const timeout = setTimeout(() => {
+            controller.abort();
+            finish(() => reject(new errors_1.ValidationError('Canton Ed25519 signing request expired before the signer completed', {
+                operationId: request.operationId,
+                expiresAt: request.expiresAt,
+            })));
+        }, requestTtlMs);
+        externalSignal?.addEventListener('abort', onAbort, { once: true });
+        if (externalSignal?.aborted) {
+            onAbort();
+            return;
+        }
+        queueMicrotask(() => {
+            if (settled || controller.signal.aborted) {
+                finish(() => reject(signingAborted(request.operationId)));
+                return;
+            }
+            let pending;
+            try {
+                pending = signer.signCantonPayload(request, { signal: controller.signal });
+            }
+            catch (error) {
+                finish(() => reject(error));
+                return;
+            }
+            Promise.resolve(pending).then((signature) => finish(() => resolve(signature)), (error) => finish(() => reject(error)));
+        });
+    });
+}
+function signingAborted(operationId) {
+    return new errors_1.ValidationError('Canton Ed25519 signing request was aborted', { operationId });
+}
+/** Normalizes supported signer outputs into canonical, padded base64. */
+function normalizeCantonEd25519Signature(signature) {
+    if ('signatureBase64' in signature) {
+        return encodeSignatureBytes(decodeBase64Signature(signature.signatureBase64));
+    }
+    if ('signatureHex' in signature) {
+        return encodeSignatureBytes(decodeHexSignature(signature.signatureHex));
+    }
+    return encodeSignatureBytes(Buffer.from(signature.signatureBytes));
+}
+function decodeBase64Signature(value) {
+    const normalized = value.trim().replace(/-/g, '+').replace(/_/g, '/');
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(normalized) || normalized.length % 4 === 1) {
+        throw invalidCantonEd25519Signature();
+    }
+    const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), '=');
+    const decoded = Buffer.from(padded, 'base64');
+    if (decoded.toString('base64').replace(/=+$/, '') !== normalized.replace(/=+$/, '')) {
+        throw invalidCantonEd25519Signature();
+    }
+    return decoded;
+}
+function decodeHexSignature(value) {
+    const normalized = value.trim().replace(/^0x/i, '');
+    if (!/^[0-9a-fA-F]+$/.test(normalized) || normalized.length % 2 !== 0) {
+        throw invalidCantonEd25519Signature();
+    }
+    return Buffer.from(normalized, 'hex');
+}
+function encodeSignatureBytes(signature) {
+    if (signature.length !== 64) {
+        throw invalidCantonEd25519Signature(signature.length);
+    }
+    return signature.toString('base64');
+}
+function invalidCantonEd25519Signature(actualLength) {
+    return new errors_1.ValidationError('External Canton signer must return a 64-byte Ed25519 signature', {
+        ...(actualLength !== undefined ? { actualLength } : {}),
+        expectedLength: 64,
+    });
+}
+function normalizeHexPayload(value) {
+    const normalized = value.trim();
+    if (!/^(?:[0-9a-fA-F]{2})+$/.test(normalized)) {
+        throw new errors_1.ValidationError('payloadHex must be non-empty, even-length hexadecimal bytes', { payloadHex: value });
+    }
+    return normalized.toLowerCase();
+}
+function validateRequiredString(name, value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new errors_1.ValidationError(`${name} is required`, { [name]: value });
+    }
+    return normalized;
+}
+function validateRequestTtlMs(value) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value > exports.MAX_CANTON_ED25519_SIGNING_REQUEST_TTL_MS) {
+        throw new errors_1.ValidationError(`requestTtlMs must be a positive safe integer no greater than ${exports.MAX_CANTON_ED25519_SIGNING_REQUEST_TTL_MS}`, { requestTtlMs: value, maxRequestTtlMs: exports.MAX_CANTON_ED25519_SIGNING_REQUEST_TTL_MS });
+    }
+    return value;
+}
+function validateTimestamp(value) {
+    const latestIssuedAtMs = 8640000000000000 - exports.MAX_CANTON_ED25519_SIGNING_REQUEST_TTL_MS;
+    if (!Number.isSafeInteger(value) || value < 0 || value > latestIssuedAtMs) {
+        throw new errors_1.ValidationError('now must return a non-negative, valid Unix timestamp in milliseconds', { now: value });
+    }
+    return value;
+}
+function normalizeSigningContext(context) {
+    if (typeof context !== 'object' || context === null || Array.isArray(context)) {
+        throw new errors_1.ValidationError('Canton signing context must be an object of primitive JSON values');
+    }
+    const entries = [];
+    for (const [key, value] of Object.entries(context)) {
+        if (!key.trim()) {
+            throw new errors_1.ValidationError('Canton signing context keys must not be empty');
+        }
+        if (value !== null &&
+            typeof value !== 'string' &&
+            typeof value !== 'boolean' &&
+            (typeof value !== 'number' || !Number.isFinite(value))) {
+            throw new errors_1.ValidationError('Canton signing context values must be primitive JSON values', { key });
+        }
+        entries.push([key, value]);
+    }
+    // Object.fromEntries defines `__proto__` as an own data property instead of invoking Object.prototype's setter.
+    return Object.fromEntries(entries);
+}
+function validateSigningPurpose(value) {
+    if (value !== exports.CantonEd25519SigningPurpose.EXTERNAL_PARTY_TOPOLOGY &&
+        value !== exports.CantonEd25519SigningPurpose.INTERACTIVE_SUBMISSION) {
+        throw new errors_1.ValidationError('Unsupported Canton Ed25519 signing purpose', { purpose: value });
+    }
+    return value;
+}
+//# sourceMappingURL=canton-ed25519-signer.js.map

package/build/src/utils/external-signing/canton-ed25519-signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canton-ed25519-signer.js","sourceRoot":"","sources":["../../../../src/utils/external-signing/canton-ed25519-signer.ts"],"names":[],"mappings":"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"}

package/build/src/utils/external-signing/execute-external-transaction.d.ts

@@ -1,6 +1,22 @@
 import { type LedgerJsonApiClient } from '../../clients/ledger-json-api';
 import { type InteractiveSubmissionExecuteRequest, type InteractiveSubmissionExecuteResponse } from '../../clients/ledger-json-api/schemas/api/interactive-submission';
 export type PartySignature = InteractiveSubmissionExecuteRequest['partySignatures']['signatures'][number];
+/** Immutable compatibility value. Use the factory below when building a submission request. */
+export declare const DEFAULT_INTERACTIVE_SUBMISSION_DEDUPLICATION_PERIOD: Readonly<{
+    DeduplicationDuration: Readonly<{
+        value: Readonly<{
+            duration: "30s";
+        }>;
+    }>;
+}>;
+/** Returns an isolated default deduplication period for one interactive submission. */
+export declare function createDefaultInteractiveSubmissionDeduplicationPeriod(): {
+    DeduplicationDuration: {
+        value: {
+            duration: string;
+        };
+    };
+};
 export interface ExecuteExternalTransactionOptions {
     readonly ledgerClient: LedgerJsonApiClient;
     readonly userId: string;

package/build/src/utils/external-signing/execute-external-transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute-external-transaction.d.ts","sourceRoot":"","sources":["../../../../src/utils/external-signing/execute-external-transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EACL,KAAK,mCAAmC,EACxC,KAAK,oCAAoC,EAC1C,MAAM,kEAAkE,CAAC;AAG1E,MAAM,MAAM,cAAc,GAAG,mCAAmC,CAAC,iBAAiB,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1G,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;IACpD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mCAAmC,CAAC,qBAAqB,CAAC,CAAC;CAC3F;AAED,MAAM,WAAW,uCAAuC;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,oCAAoC,CAAC,CAE/C;AAED;;;;;GAKG;AACH,wBAAsB,iCAAiC,CACrD,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,uCAAuC,CAAC,CAclD"}
+{"version":3,"file":"execute-external-transaction.d.ts","sourceRoot":"","sources":["../../../../src/utils/external-signing/execute-external-transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EACL,KAAK,mCAAmC,EACxC,KAAK,oCAAoC,EAC1C,MAAM,kEAAkE,CAAC;AAG1E,MAAM,MAAM,cAAc,GAAG,mCAAmC,CAAC,iBAAiB,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1G,+FAA+F;AAC/F,eAAO,MAAM,mDAAmD;;;;;;EAIoB,CAAC;AAErF,uFAAuF;AACvF,wBAAgB,qDAAqD,IAAI;IACvE,qBAAqB,EAAE;QAAE,KAAK,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CACxD,CAMA;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;IACpD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mCAAmC,CAAC,qBAAqB,CAAC,CAAC;CAC3F;AAED,MAAM,WAAW,uCAAuC;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,oCAAoC,CAAC,CAE/C;AAED;;;;;GAKG;AACH,wBAAsB,iCAAiC,CACrD,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,uCAAuC,CAAC,CAclD"}

package/build/src/utils/external-signing/execute-external-transaction.js

@@ -1,8 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INTERACTIVE_SUBMISSION_DEDUPLICATION_PERIOD = void 0;
+exports.createDefaultInteractiveSubmissionDeduplicationPeriod = createDefaultInteractiveSubmissionDeduplicationPeriod;
 exports.executeExternalTransaction = executeExternalTransaction;
 exports.executeExternalTransactionAndWait = executeExternalTransactionAndWait;
 const canton_response_utils_1 = require("../canton-response-utils");
+/** Immutable compatibility value. Use the factory below when building a submission request. */
+exports.DEFAULT_INTERACTIVE_SUBMISSION_DEDUPLICATION_PERIOD = Object.freeze({
+    DeduplicationDuration: Object.freeze({
+        value: Object.freeze({ duration: '30s' }),
+    }),
+});
+/** Returns an isolated default deduplication period for one interactive submission. */
+function createDefaultInteractiveSubmissionDeduplicationPeriod() {
+    return {
+        DeduplicationDuration: {
+            value: { duration: exports.DEFAULT_INTERACTIVE_SUBMISSION_DEDUPLICATION_PERIOD.DeduplicationDuration.value.duration },
+        },
+    };
+}
 /**
  * Executes an interactive submission after offline signing (`interactiveSubmissionExecute`).
  *
@@ -35,11 +51,7 @@ function buildExecuteExternalTransactionRequest(options) {
         preparedTransaction: options.preparedTransaction,
         hashingSchemeVersion: options.hashingSchemeVersion ?? 'HASHING_SCHEME_VERSION_V2',
         submissionId: options.submissionId,
-        deduplicationPeriod: options.deduplicationPeriod ?? {
-            DeduplicationDuration: {
-                value: { duration: '30s' },
-            },
-        },
+        deduplicationPeriod: options.deduplicationPeriod ?? createDefaultInteractiveSubmissionDeduplicationPeriod(),
         partySignatures: {
             signatures: [...options.partySignatures],
         },

package/build/src/utils/external-signing/execute-external-transaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"execute-external-transaction.js","sourceRoot":"","sources":["../../../../src/utils/external-signing/execute-external-transaction.ts"],"names":[],"mappings":";;;;AAKA,oEAA6E;AAmB7E;;;;;GAKG;AACI,KAAK,qCACV,OAA0C;IAE1C,OAAO,OAAO,CAAC,YAAY,CAAC,4BAA4B,CAAC,sCAAsC,CAAC,OAAO,CAAC,CAAC,CAAC;AAC5G,CAAC;AAED;;;;;GAKG;AACI,KAAK,4CACV,OAA0C;IAE1C,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,eAAe,CACpD,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,2CAA2C,EAC9E,sCAAsC,CAAC,OAAO,CAAC,EAC/C;QACE,WAAW,EAAE,kBAAkB;QAC/B,kBAAkB,EAAE,IAAI;KACzB,CACF,CAAC;IACF,MAAM,QAAQ,GAAG,IAAA,0CAAkB,EAAC,GAAG,EAAE,UAAU,EAAE,uCAAuC,CAAC,CAAC;IAC9F,OAAO;QACL,QAAQ;QACR,GAAG,EAAE,IAAA,qCAAa,EAAC,GAAG,CAAC;KACxB,CAAC;AACJ,CAAC;AAED,SAAS,sCAAsC,CAC7C,OAA0C;IAE1C,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;QAChD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,IAAI,2BAA2B;QACjF,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI;YAClD,qBAAqB,EAAE;gBACrB,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE;aAC3B;SACF;QACD,eAAe,EAAE;YACf,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;SACzC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"execute-external-transaction.js","sourceRoot":"","sources":["../../../../src/utils/external-signing/execute-external-transaction.ts"],"names":[],"mappings":";;;;;;AAKA,oEAA6E;AAI7E,+FAA+F;AAClF,QAAA,mDAAmD,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/E,qBAAqB,EAAE,MAAM,CAAC,MAAM,CAAC;QACnC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;KAC1C,CAAC;CACH,CAAmF,CAAC;AAErF,uFAAuF;AACvF;IAGE,OAAO;QACL,qBAAqB,EAAE;YACrB,KAAK,EAAE,EAAE,QAAQ,EAAE,QAAA,mDAAmD,CAAC,qBAAqB,CAAC,KAAK,CAAC,QAAQ,EAAE;SAC9G;KACgF,CAAC;AACtF,CAAC;AAiBD;;;;;GAKG;AACI,KAAK,qCACV,OAA0C;IAE1C,OAAO,OAAO,CAAC,YAAY,CAAC,4BAA4B,CAAC,sCAAsC,CAAC,OAAO,CAAC,CAAC,CAAC;AAC5G,CAAC;AAED;;;;;GAKG;AACI,KAAK,4CACV,OAA0C;IAE1C,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,eAAe,CACpD,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,2CAA2C,EAC9E,sCAAsC,CAAC,OAAO,CAAC,EAC/C;QACE,WAAW,EAAE,kBAAkB;QAC/B,kBAAkB,EAAE,IAAI;KACzB,CACF,CAAC;IACF,MAAM,QAAQ,GAAG,IAAA,0CAAkB,EAAC,GAAG,EAAE,UAAU,EAAE,uCAAuC,CAAC,CAAC;IAC9F,OAAO;QACL,QAAQ;QACR,GAAG,EAAE,IAAA,qCAAa,EAAC,GAAG,CAAC;KACxB,CAAC;AACJ,CAAC;AAED,SAAS,sCAAsC,CAC7C,OAA0C;IAE1C,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,mBAAmB,EAAE,OAAO,CAAC,mBAAmB;QAChD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB,IAAI,2BAA2B;QACjF,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,IAAI,qDAAqD,EAAE;QAC3G,eAAe,EAAE;YACf,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;SACzC;KACF,CAAC;AACJ,CAAC"}

package/build/src/utils/external-signing/external-party-details.d.ts

@@ -0,0 +1,3 @@
+/** Reads the first valid party-details record, optionally requiring one exact party id. */
+export declare function readMatchingExternalPartyDetails(source: unknown, partyId?: string): Record<string, unknown> | null;
+//# sourceMappingURL=external-party-details.d.ts.map

package/build/src/utils/external-signing/external-party-details.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-party-details.d.ts","sourceRoot":"","sources":["../../../../src/utils/external-signing/external-party-details.ts"],"names":[],"mappings":"AAEA,2FAA2F;AAC3F,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAYlH"}

package/build/src/utils/external-signing/external-party-details.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readMatchingExternalPartyDetails = readMatchingExternalPartyDetails;
+const utils_1 = require("../../core/utils");
+/** Reads the first valid party-details record, optionally requiring one exact party id. */
+function readMatchingExternalPartyDetails(source, partyId) {
+    if (!(0, utils_1.isRecord)(source))
+        return null;
+    const { partyDetails } = source;
+    const details = Array.isArray(partyDetails) ? partyDetails : [partyDetails];
+    for (const detail of details) {
+        if (!(0, utils_1.isRecord)(detail))
+            continue;
+        const { party } = detail;
+        if (typeof party !== 'string' || !party.trim())
+            continue;
+        if (partyId !== undefined && party !== partyId)
+            continue;
+        return detail;
+    }
+    return null;
+}
+//# sourceMappingURL=external-party-details.js.map

package/build/src/utils/external-signing/external-party-details.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-party-details.js","sourceRoot":"","sources":["../../../../src/utils/external-signing/external-party-details.ts"],"names":[],"mappings":";;;AAAA,4CAA4C;AAE5C,2FAA2F;AAC3F,0CAAiD,MAAe,EAAE,OAAgB;IAChF,IAAI,CAAC,IAAA,gBAAQ,EAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IAChC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IAC5E,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAA,gBAAQ,EAAC,MAAM,CAAC;YAAE,SAAS;QAChC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;QACzB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;YAAE,SAAS;QACzD,IAAI,OAAO,KAAK,SAAS,IAAI,KAAK,KAAK,OAAO;YAAE,SAAS;QACzD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/build/src/utils/external-signing/external-party-lifecycle.d.ts

@@ -0,0 +1,95 @@
+import { type LedgerJsonApiClient } from '../../clients/ledger-json-api';
+import { type PartySynchronizerReadiness } from '../party-readiness';
+export type ExternalPartyOnboardingState = 'not-found' | 'allocated' | 'in-flight' | 'ready' | 'unknown';
+interface ExternalPartyOnboardingStatusBase {
+    readonly state: ExternalPartyOnboardingState;
+    readonly partyId: string;
+    readonly publicKeyFingerprint: string;
+    readonly synchronizerId: string;
+    readonly exists: boolean | null;
+    readonly ready: boolean;
+}
+export interface ExternalPartyNotFoundStatus extends ExternalPartyOnboardingStatusBase {
+    readonly state: 'not-found';
+    readonly exists: false;
+    readonly ready: false;
+    readonly partyDetails: null;
+}
+export interface ExternalPartyInFlightStatus extends ExternalPartyOnboardingStatusBase {
+    readonly state: 'in-flight';
+    readonly exists: true;
+    readonly ready: false;
+    readonly partyDetails: Record<string, unknown>;
+    readonly readiness: PartySynchronizerReadiness;
+}
+export interface ExternalPartyAllocatedStatus extends ExternalPartyOnboardingStatusBase {
+    readonly state: 'allocated';
+    readonly exists: true;
+    readonly ready: false;
+    readonly partyDetails: Record<string, unknown>;
+    readonly readiness: PartySynchronizerReadiness;
+}
+export interface ExternalPartyReadyStatus extends ExternalPartyOnboardingStatusBase {
+    readonly state: 'ready';
+    readonly exists: true;
+    readonly ready: true;
+    readonly partyDetails: Record<string, unknown>;
+    readonly readiness: PartySynchronizerReadiness;
+}
+export interface ExternalPartyUnknownStatus extends ExternalPartyOnboardingStatusBase {
+    readonly state: 'unknown';
+    readonly exists: boolean | null;
+    readonly ready: false;
+    readonly failedAt: 'party-details' | 'readiness';
+    readonly failure: ExternalPartyStatusFailure;
+    readonly partyDetails?: Record<string, unknown>;
+}
+export type ExternalPartyOnboardingStatus = ExternalPartyNotFoundStatus | ExternalPartyAllocatedStatus | ExternalPartyInFlightStatus | ExternalPartyReadyStatus | ExternalPartyUnknownStatus;
+export interface ExternalPartyStatusFailure {
+    readonly name: string;
+    readonly message: string;
+    readonly status?: number;
+    readonly code?: string;
+    readonly context?: unknown;
+}
+export interface ReconcileExternalPartyOnboardingOptions {
+    readonly ledgerClient: LedgerJsonApiClient;
+    readonly partyId: string;
+    readonly publicKeyBase64: string;
+    readonly synchronizerId: string;
+    readonly identityProviderId?: string;
+    readonly participantId?: string;
+    /** Set false when local observation, rather than local submit permission, is the intended terminal state. */
+    readonly expectSubmitReady?: boolean;
+    /** Cancels pending reconciliation reads. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Reconciles external-party visibility and submit readiness without relying on allocation error text.
+ *
+ * `in-flight` means the party is allocated locally but has not yet become submission-capable on the requested
+ * synchronizer. `unknown` preserves transport/API uncertainty instead of incorrectly treating it as absence.
+ */
+export declare function reconcileExternalPartyOnboarding(options: ReconcileExternalPartyOnboardingOptions): Promise<ExternalPartyOnboardingStatus>;
+export type ExternalPartyAllocationFailureKind = 'already-exists' | 'definite-rejection' | 'ambiguous';
+export interface ExternalPartyAllocationFailure {
+    readonly kind: ExternalPartyAllocationFailureKind;
+    readonly definite: boolean;
+    readonly shouldReconcile: boolean;
+    readonly status?: number;
+    readonly code?: string;
+    readonly details: ExternalPartyStatusFailure;
+}
+/** Classifies allocation failures from structured SDK/Canton fields, never from localized error messages. */
+export declare function classifyExternalPartyAllocationFailure(error: unknown): ExternalPartyAllocationFailure;
+export interface ReconcileExternalPartyAllocationFailureOptions extends ReconcileExternalPartyOnboardingOptions {
+    readonly error: unknown;
+}
+export interface ExternalPartyAllocationReconciliation {
+    readonly failure: ExternalPartyAllocationFailure;
+    readonly status: ExternalPartyOnboardingStatus;
+}
+/** Returns one structured allocation failure plus the currently observable party lifecycle state. */
+export declare function reconcileExternalPartyAllocationFailure(options: ReconcileExternalPartyAllocationFailureOptions): Promise<ExternalPartyAllocationReconciliation>;
+export {};
+//# sourceMappingURL=external-party-lifecycle.d.ts.map

package/build/src/utils/external-signing/external-party-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-party-lifecycle.d.ts","sourceRoot":"","sources":["../../../../src/utils/external-signing/external-party-lifecycle.ts"],"names":[],"mappings":"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"}

package/build/src/utils/external-signing/external-party-lifecycle.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcileExternalPartyOnboarding = reconcileExternalPartyOnboarding;
+exports.classifyExternalPartyAllocationFailure = classifyExternalPartyAllocationFailure;
+exports.reconcileExternalPartyAllocationFailure = reconcileExternalPartyAllocationFailure;
+const errors_1 = require("../../core/errors");
+const abort_1 = require("../../core/utils/abort");
+const party_readiness_1 = require("../party-readiness");
+const canton_protocol_1 = require("./canton-protocol");
+const external_party_details_1 = require("./external-party-details");
+const external_party_onboarding_1 = require("./external-party-onboarding");
+/**
+ * Reconciles external-party visibility and submit readiness without relying on allocation error text.
+ *
+ * `in-flight` means the party is allocated locally but has not yet become submission-capable on the requested
+ * synchronizer. `unknown` preserves transport/API uncertainty instead of incorrectly treating it as absence.
+ */
+async function reconcileExternalPartyOnboarding(options) {
+    const publicKeyFingerprint = (0, canton_protocol_1.assertCantonPartyMatchesPublicKey)({
+        partyId: options.partyId,
+        publicKeyBase64: options.publicKeyBase64,
+    });
+    const base = {
+        partyId: options.partyId,
+        publicKeyFingerprint,
+        synchronizerId: options.synchronizerId,
+    };
+    let partyDetails;
+    const createPartyDetailsAbortError = () => reconciliationAborted(options, 'party-details');
+    try {
+        const raw = await (0, abort_1.runWithAbortSignal)(options.signal, createPartyDetailsAbortError, 
+        // Preserve the ledger promise's exact settlement order relative to abort.
+        // eslint-disable-next-line @typescript-eslint/promise-function-async
+        () => options.ledgerClient.getPartyDetails({
+            party: options.partyId,
+            identityProviderId: options.identityProviderId ?? external_party_onboarding_1.DEFAULT_CANTON_IDENTITY_PROVIDER_ID,
+        }));
+        const matched = (0, external_party_details_1.readMatchingExternalPartyDetails)(raw, options.partyId);
+        if (!matched) {
+            return {
+                ...base,
+                state: 'unknown',
+                exists: null,
+                ready: false,
+                failedAt: 'party-details',
+                failure: {
+                    name: 'UnexpectedCantonResponse',
+                    message: 'Canton party details response did not contain the requested party',
+                },
+            };
+        }
+        partyDetails = matched;
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw createPartyDetailsAbortError();
+        if (readErrorStatus(error) === 404) {
+            return {
+                ...base,
+                state: 'not-found',
+                exists: false,
+                ready: false,
+                partyDetails: null,
+            };
+        }
+        return {
+            ...base,
+            state: 'unknown',
+            exists: null,
+            ready: false,
+            failedAt: 'party-details',
+            failure: normalizeStatusFailure(error),
+        };
+    }
+    const createReadinessAbortError = () => reconciliationAborted(options, 'readiness');
+    try {
+        const readiness = await (0, abort_1.runWithAbortSignal)(options.signal, createReadinessAbortError, 
+        // Preserve the readiness promise's exact settlement order relative to abort.
+        // eslint-disable-next-line @typescript-eslint/promise-function-async
+        () => (0, party_readiness_1.checkPartySynchronizerReadiness)({
+            ledgerClient: options.ledgerClient,
+            party: options.partyId,
+            synchronizerId: options.synchronizerId,
+            ...(options.participantId !== undefined ? { participantId: options.participantId } : {}),
+        }));
+        if (readiness.ready) {
+            return {
+                ...base,
+                state: 'ready',
+                exists: true,
+                ready: true,
+                partyDetails,
+                readiness,
+            };
+        }
+        if (options.expectSubmitReady === false) {
+            return {
+                ...base,
+                state: 'allocated',
+                exists: true,
+                ready: false,
+                partyDetails,
+                readiness,
+            };
+        }
+        return {
+            ...base,
+            state: 'in-flight',
+            exists: true,
+            ready: false,
+            partyDetails,
+            readiness,
+        };
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw createReadinessAbortError();
+        return {
+            ...base,
+            state: 'unknown',
+            exists: true,
+            ready: false,
+            failedAt: 'readiness',
+            failure: normalizeStatusFailure(error),
+            partyDetails,
+        };
+    }
+}
+function reconciliationAborted(options, step) {
+    return new errors_1.ValidationError('Canton external-party reconciliation was aborted', {
+        partyId: options.partyId,
+        synchronizerId: options.synchronizerId,
+        step,
+    });
+}
+/** Classifies allocation failures from structured SDK/Canton fields, never from localized error messages. */
+function classifyExternalPartyAllocationFailure(error) {
+    const details = normalizeStatusFailure(error);
+    const alreadyExists = details.status === 409 && details.code === 'ALREADY_EXISTS';
+    if (alreadyExists) {
+        return {
+            kind: 'already-exists',
+            definite: true,
+            shouldReconcile: true,
+            status: 409,
+            code: 'ALREADY_EXISTS',
+            details,
+        };
+    }
+    const definiteAnswer = (0, errors_1.readCantonDefiniteAnswer)(error);
+    const definite = definiteAnswer ??
+        (error instanceof errors_1.ValidationError || error instanceof errors_1.OperationError || (0, errors_1.isDefiniteCantonMutationRejection)(error));
+    return {
+        kind: definite ? 'definite-rejection' : 'ambiguous',
+        definite,
+        shouldReconcile: !definite,
+        ...(details.status !== undefined ? { status: details.status } : {}),
+        ...(details.code !== undefined ? { code: details.code } : {}),
+        details,
+    };
+}
+/** Returns one structured allocation failure plus the currently observable party lifecycle state. */
+async function reconcileExternalPartyAllocationFailure(options) {
+    const failure = classifyExternalPartyAllocationFailure(options.error);
+    const status = await reconcileExternalPartyOnboarding(options);
+    return { failure, status };
+}
+function normalizeStatusFailure(error) {
+    const normalized = (0, errors_1.normalizeCantonError)(error);
+    if (normalized)
+        return toStatusFailure(normalized);
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message };
+    }
+    return { name: 'UnknownError', message: describeUnknownFailure(error) };
+}
+function describeUnknownFailure(error) {
+    if (typeof error === 'string')
+        return error;
+    try {
+        const serialized = JSON.stringify(error);
+        if (typeof serialized === 'string')
+            return serialized;
+    }
+    catch {
+        // Fall through when the thrown value is not JSON-serializable.
+    }
+    try {
+        return String(error);
+    }
+    catch {
+        return 'Unserializable thrown value';
+    }
+}
+function toStatusFailure(details) {
+    return {
+        name: details.name,
+        message: details.message,
+        ...(details.status !== undefined ? { status: details.status } : {}),
+        ...(details.code !== undefined ? { code: details.code } : {}),
+        ...(details.context !== undefined ? { context: details.context } : {}),
+    };
+}
+function readErrorStatus(error) {
+    return (0, errors_1.normalizeCantonError)(error)?.status;
+}
+//# sourceMappingURL=external-party-lifecycle.js.map