@trustvc/trustvc 2.9.1 → 2.11.0

package/dist/esm/index.js

@@ -1,6 +1,8 @@
 export { v4ComputeInterfaceId, v4ComputeTitleEscrowAddress, v4ContractAddress, v4Contracts, v4EncodeInitParams, v4GetEventFromReceipt, v4RoleHash, v4SupportInterfaceIds, v4Utils } from './token-registry-v4';
 export { v5ComputeInterfaceId, v5ContractAddress, v5Contracts, v5EncodeInitParams, v5GetEventFromReceipt, v5RoleHash, v5SupportInterfaceIds, v5Utils } from './token-registry-v5';
 export { DocumentStore__factory, TransferableDocumentStore__factory, deployDocumentStore, documentStoreGrantRole, documentStoreIssue, documentStoreRevoke, documentStoreRevokeRole, documentStoreTransferOwnership, getRoleString } from './document-store';
+export * from './transaction';
+export { cancelTransaction } from './transaction';
 export * from './token-registry-functions';
 export * from './core';
 export * from './open-attestation';

package/dist/esm/open-attestation/decrypt.js

@@ -0,0 +1,28 @@
+import forge from 'node-forge';
+import { ENCRYPTION_PARAMETERS, decodeDocument } from './utils';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const decryptString = /* @__PURE__ */ __name(({ cipherText, tag, iv, key, type }) => {
+  if (type !== ENCRYPTION_PARAMETERS.version) {
+    throw new Error(`Expecting version ${ENCRYPTION_PARAMETERS.version} but got ${type}`);
+  }
+  const keyBytestring = forge.util.hexToBytes(key);
+  const cipherTextBytestring = forge.util.decode64(cipherText);
+  const ivBytestring = forge.util.decode64(iv);
+  const tagBytestring = forge.util.decode64(tag);
+  const decipher = forge.cipher.createDecipher("AES-GCM", keyBytestring);
+  decipher.start({
+    iv: ivBytestring,
+    tagLength: ENCRYPTION_PARAMETERS.tagLength,
+    tag: forge.util.createBuffer(tagBytestring, "raw")
+  });
+  decipher.update(forge.util.createBuffer(cipherTextBytestring, "raw"));
+  const success = decipher.finish();
+  if (!success) {
+    throw new Error("Error decrypting message");
+  }
+  return decodeDocument(decipher.output.data);
+}, "decryptString");
+
+export { decryptString };

package/dist/esm/open-attestation/encrypt.js

@@ -0,0 +1,41 @@
+import forge from 'node-forge';
+import { encodeDocument, ENCRYPTION_PARAMETERS, generateEncryptionKey } from './utils';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const generateIv = /* @__PURE__ */ __name((ivLengthInBits = ENCRYPTION_PARAMETERS.ivLength) => {
+  const iv = forge.random.getBytesSync(ivLengthInBits / 8);
+  return forge.util.encode64(iv);
+}, "generateIv");
+const makeCipher = /* @__PURE__ */ __name((encryptionKey = generateEncryptionKey()) => {
+  const iv = generateIv();
+  const cipher = forge.cipher.createCipher(
+    ENCRYPTION_PARAMETERS.algorithm,
+    forge.util.hexToBytes(encryptionKey)
+  );
+  cipher.start({
+    iv: forge.util.decode64(iv),
+    tagLength: ENCRYPTION_PARAMETERS.tagLength
+  });
+  return { cipher, encryptionKey, iv };
+}, "makeCipher");
+const encryptString = /* @__PURE__ */ __name((document, key) => {
+  if (typeof document !== "string") {
+    throw new Error("encryptString only accepts strings");
+  }
+  const { cipher, encryptionKey, iv } = makeCipher(key);
+  const buffer = forge.util.createBuffer(encodeDocument(document));
+  cipher.update(buffer);
+  cipher.finish();
+  const encryptedMessage = forge.util.encode64(cipher.output.data);
+  const tag = forge.util.encode64(cipher.mode.tag.data);
+  return {
+    cipherText: encryptedMessage,
+    iv,
+    tag,
+    key: encryptionKey,
+    type: ENCRYPTION_PARAMETERS.version
+  };
+}, "encryptString");
+
+export { encryptString };

package/dist/esm/open-attestation/index.js

@@ -3,3 +3,5 @@ export * from './types';
 export * from './utils';
 export * from './verify';
 export * from './wrap';
+export { encryptString } from './encrypt';
+export { decryptString } from './decrypt';

package/dist/esm/open-attestation/utils.js

@@ -1,6 +1,41 @@
+import forge from 'node-forge';
 import { utils } from '@tradetrust-tt/tradetrust';
 export { SUPPORTED_SIGNING_ALGORITHM, SchemaId, getData as getDataV2, isSchemaValidationError, obfuscateDocument, validateSchema } from '@tradetrust-tt/tradetrust';
 
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const ENCRYPTION_PARAMETERS = Object.freeze({
+  algorithm: "AES-GCM",
+  keyLength: 256,
+  // Key length in bits
+  ivLength: 96,
+  // IV length in bits: NIST suggests 12 bytes
+  tagLength: 128,
+  // GCM authentication tag length in bits, see link above for explanation
+  version: "OPEN-ATTESTATION-TYPE-1"
+  // Type 1 using the above params without compression
+});
+const generateEncryptionKey = /* @__PURE__ */ __name((keyLengthInBits = ENCRYPTION_PARAMETERS.keyLength) => {
+  if (!Number.isInteger(keyLengthInBits) || ![128, 192, 256].includes(keyLengthInBits)) {
+    throw new Error("keyLengthInBits must be one of 128, 192, or 256");
+  }
+  const encryptionKey = forge.random.getBytesSync(keyLengthInBits / 8);
+  return forge.util.bytesToHex(encryptionKey);
+}, "generateEncryptionKey");
+const encodeDocument = /* @__PURE__ */ __name((document) => {
+  const bytes = forge.util.encodeUtf8(document);
+  const standard = forge.util.encode64(bytes);
+  const s = standard.replace(/\+/g, "-").replace(/\//g, "_");
+  const trim = s.endsWith("==") ? 2 : s.endsWith("=") ? 1 : 0;
+  return trim ? s.slice(0, -trim) : s;
+}, "encodeDocument");
+const decodeDocument = /* @__PURE__ */ __name((encoded) => {
+  let normalized = encoded.replace(/-/g, "+").replace(/_/g, "/");
+  const pad = normalized.length % 4;
+  if (pad) normalized += "=".repeat(4 - pad);
+  const decoded = forge.util.decode64(normalized);
+  return forge.util.decodeUtf8(decoded);
+}, "decodeDocument");
 const {
   isTransferableAsset,
   isDocumentRevokable,
@@ -17,4 +52,4 @@ const {
   getTemplateURL
 } = utils;
 
-export { diagnose, getAssetId, getDocumentData, getIssuerAddress, getTemplateURL, isDocumentRevokable, isRawV2Document, isRawV3Document, isSignedWrappedV2Document, isSignedWrappedV3Document, isTransferableAsset, isWrappedV2Document, isWrappedV3Document };
+export { ENCRYPTION_PARAMETERS, decodeDocument, diagnose, encodeDocument, generateEncryptionKey, getAssetId, getDocumentData, getIssuerAddress, getTemplateURL, isDocumentRevokable, isRawV2Document, isRawV3Document, isSignedWrappedV2Document, isSignedWrappedV3Document, isTransferableAsset, isWrappedV2Document, isWrappedV3Document };

package/dist/esm/transaction/cancel.js

@@ -0,0 +1,55 @@
+import { BigNumber } from 'ethers';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const GAS_PRICE_SCALE_WHEN_FROM_HASH = 2;
+const cancelTransaction = /* @__PURE__ */ __name(async (signer, options) => {
+  if (!signer.provider) {
+    throw new Error("Provider is required on signer");
+  }
+  const { nonce, gasPrice, transactionHash } = options;
+  let transactionNonce = nonce;
+  let transactionGasPrice = gasPrice;
+  if (transactionHash) {
+    if (typeof signer.provider.getTransaction !== "function") {
+      throw new Error("Provider does not support getTransaction");
+    }
+    const tx = await signer.provider.getTransaction(transactionHash);
+    if (!tx) {
+      throw new Error(`Transaction not found: ${transactionHash}`);
+    }
+    const txNonce = tx.nonce;
+    const txGasPrice = tx.gasPrice;
+    if (txGasPrice == null) {
+      throw new Error(
+        "Transaction uses EIP-1559 (no gasPrice). Cancel by providing --nonce and --gas-price explicitly."
+      );
+    }
+    transactionNonce = String(txNonce);
+    const scaled = typeof txGasPrice === "bigint" ? txGasPrice * BigInt(GAS_PRICE_SCALE_WHEN_FROM_HASH) : BigNumber.from(txGasPrice).mul(GAS_PRICE_SCALE_WHEN_FROM_HASH);
+    transactionGasPrice = String(scaled);
+  }
+  if (!transactionNonce || !transactionGasPrice) {
+    throw new Error(
+      "Provide either (--nonce and --gas-price) or --transaction-hash to cancel the pending transaction"
+    );
+  }
+  const address = await signer.getAddress();
+  if (!/^\d+$/.test(transactionNonce)) {
+    throw new Error("Invalid nonce: expected a non-negative integer");
+  }
+  if (!/^\d+$/.test(transactionGasPrice) || transactionGasPrice === "0") {
+    throw new Error("Invalid gasPrice: expected a positive integer string in wei");
+  }
+  const nonceNum = Number(transactionNonce);
+  const txResponse = await signer.sendTransaction({
+    to: address,
+    value: 0,
+    nonce: nonceNum,
+    gasPrice: transactionGasPrice,
+    gasLimit: 21e3
+  });
+  return txResponse.hash;
+}, "cancelTransaction");
+
+export { cancelTransaction };

package/dist/esm/transaction/index.js

@@ -0,0 +1 @@
+export { cancelTransaction } from './cancel';

package/dist/types/index.d.ts

@@ -19,6 +19,7 @@ export { documentStoreTransferOwnership } from './document-store/transferOwnersh
 export { deployDocumentStore } from './deploy/document-store.js';
 export { getRoleString } from './document-store/document-store-roles.js';
 export { DocumentStore__factory, TransferableDocumentStore__factory } from '@trustvc/document-store';
+export { CancelTransactionOptions, CancelTransactionSigner, cancelTransaction } from './transaction/cancel.js';
 export { nominate, transferBeneficiary, transferHolder, transferOwners } from './token-registry-functions/transfer.js';
 export { rejectTransferBeneficiary, rejectTransferHolder, rejectTransferOwners } from './token-registry-functions/rejectTransfers.js';
 export { acceptReturned, rejectReturned, returnToIssuer } from './token-registry-functions/returnToken.js';
@@ -36,10 +37,12 @@ export { EndorsementChain, ParsedLog, TitleEscrowTransferEvent, TitleEscrowTrans
 export { TitleEscrowInterface, checkSupportsInterface, fetchEndorsementChain, getDocumentOwner, getTitleEscrowAddress, isTitleEscrowVersion } from './core/endorsement-chain/useEndorsementChain.js';
 export { DocumentBuilder, RenderMethod, SignOptions, W3CTransferableRecordsConfig, W3CVerifiableDocumentConfig, qrCode } from './core/documentBuilder.js';
 export { signOA } from './open-attestation/sign.js';
-export { KeyPair } from './open-attestation/types.js';
-export { diagnose, getAssetId, getDocumentData, getIssuerAddress, getTemplateURL, isDocumentRevokable, isRawV2Document, isRawV3Document, isSignedWrappedV2Document, isSignedWrappedV3Document, isTransferableAsset, isWrappedV2Document, isWrappedV3Document } from './open-attestation/utils.js';
+export { IEncryptionResults, KeyPair } from './open-attestation/types.js';
+export { ENCRYPTION_PARAMETERS, decodeDocument, diagnose, encodeDocument, generateEncryptionKey, getAssetId, getDocumentData, getIssuerAddress, getTemplateURL, isDocumentRevokable, isRawV2Document, isRawV3Document, isSignedWrappedV2Document, isSignedWrappedV3Document, isTransferableAsset, isWrappedV2Document, isWrappedV3Document } from './open-attestation/utils.js';
 export { verifyOASignature } from './open-attestation/verify.js';
 export { wrapOADocument, wrapOADocumentV2, wrapOADocuments, wrapOADocumentsV2 } from './open-attestation/wrap.js';
+export { encryptString } from './open-attestation/encrypt.js';
+export { decryptString } from './open-attestation/decrypt.js';
 export { openAttestationVerifiers, verifiers, w3cVerifiers } from './verify/verify.js';
 export { i as fragments } from './index-ZZ1UYFI0.js';
 export { OpencertsRegistryCode, OpencertsRegistryVerificationInvalidData, OpencertsRegistryVerificationInvalidDataArray, OpencertsRegistryVerificationValidData, OpencertsRegistryVerificationValidDataArray, OpencertsRegistryVerifierInvalidFragmentV2, OpencertsRegistryVerifierInvalidFragmentV3, OpencertsRegistryVerifierValidFragmentV2, OpencertsRegistryVerifierValidFragmentV3, OpencertsRegistryVerifierVerificationFragment, Registry, RegistryEntry, getOpencertsRegistryVerifierFragment, isValidOpenCert, name, registryVerifier, type, verifyOpenCertSignature } from './open-cert/verify.js';

package/dist/types/open-attestation/decrypt.d.ts

@@ -0,0 +1,12 @@
+import { IEncryptionResults } from './types.js';
+import '@tradetrust-tt/tradetrust';
+import '@tradetrust-tt/tradetrust/dist/types/shared/utils';
+
+/**
+ * Decrypts a given ciphertext along with its associated variables.
+ * @param {IEncryptionResults} encryptionResults - Encryption result object containing cipherText (base64), tag (base64), iv (base64), key (hex), and type.
+ * @returns {string} Decrypted plaintext string.
+ */
+declare const decryptString: ({ cipherText, tag, iv, key, type }: IEncryptionResults) => string;
+
+export { decryptString };

package/dist/types/open-attestation/encrypt.d.ts

@@ -0,0 +1,13 @@
+import { IEncryptionResults } from './types.js';
+import '@tradetrust-tt/tradetrust';
+import '@tradetrust-tt/tradetrust/dist/types/shared/utils';
+
+/**
+ * Encrypts a given string with symmetric AES-GCM.
+ * @param {string} document - Input string to encrypt.
+ * @param {string} [key] - Optional encryption key in hexadecimal (64 chars for 256-bit). If omitted, a key is generated.
+ * @returns {IEncryptionResults} Object with cipherText (base64), iv (base64), tag (base64), key (hex), and type.
+ */
+declare const encryptString: (document: string, key?: string) => IEncryptionResults;
+
+export { encryptString };

package/dist/types/open-attestation/index.d.ts

@@ -1,8 +1,10 @@
 export { signOA } from './sign.js';
-export { KeyPair } from './types.js';
-export { diagnose, getAssetId, getDocumentData, getIssuerAddress, getTemplateURL, isDocumentRevokable, isRawV2Document, isRawV3Document, isSignedWrappedV2Document, isSignedWrappedV3Document, isTransferableAsset, isWrappedV2Document, isWrappedV3Document } from './utils.js';
+export { IEncryptionResults, KeyPair } from './types.js';
+export { ENCRYPTION_PARAMETERS, decodeDocument, diagnose, encodeDocument, generateEncryptionKey, getAssetId, getDocumentData, getIssuerAddress, getTemplateURL, isDocumentRevokable, isRawV2Document, isRawV3Document, isSignedWrappedV2Document, isSignedWrappedV3Document, isTransferableAsset, isWrappedV2Document, isWrappedV3Document } from './utils.js';
 export { verifyOASignature } from './verify.js';
 export { wrapOADocument, wrapOADocumentV2, wrapOADocuments, wrapOADocumentsV2 } from './wrap.js';
+export { encryptString } from './encrypt.js';
+export { decryptString } from './decrypt.js';
 export { OpenAttestationDocument, SUPPORTED_SIGNING_ALGORITHM, SchemaId, SignedWrappedDocument, WrappedDocument, getData as getDataV2, isSchemaValidationError, obfuscateDocument, v2, v3, validateSchema, __unsafe__use__it__at__your__own__risks__wrapDocument as wrapOADocumentV3, __unsafe__use__it__at__your__own__risks__wrapDocuments as wrapOADocumentsV3 } from '@tradetrust-tt/tradetrust';
 export { DiagnoseError } from '@tradetrust-tt/tradetrust/dist/types/shared/utils';
 import '@ethersproject/abstract-signer';

package/dist/types/open-attestation/types.d.ts

@@ -5,5 +5,12 @@ type KeyPair = {
     public: string;
     private: string;
 };
+interface IEncryptionResults {
+    cipherText: string;
+    iv: string;
+    tag: string;
+    key: string;
+    type: string;
+}
 
-export type { KeyPair };
+export type { IEncryptionResults, KeyPair };

package/dist/types/open-attestation/utils.d.ts

@@ -7,6 +7,37 @@ import * as _tradetrust_tt_tradetrust_dist_types_2_0_types from '@tradetrust-tt/
 import * as _tradetrust_tt_tradetrust_dist_types___generated___schema_2_0 from '@tradetrust-tt/tradetrust/dist/types/__generated__/schema.2.0';
 import * as _tradetrust_tt_tradetrust_dist_types_shared_utils__types_diagnose from '@tradetrust-tt/tradetrust/dist/types/shared/utils/@types/diagnose';
 
+/**
+ * Default options for OA document encryption (AES-GCM).
+ * {@link https://crypto.stackexchange.com/questions/26783/ciphertext-and-tag-size-and-iv-transmission-with-aes-in-gcm-mode/26787|here}
+ */
+declare const ENCRYPTION_PARAMETERS: Readonly<{
+    readonly algorithm: "AES-GCM";
+    readonly keyLength: 256;
+    readonly ivLength: 96;
+    readonly tagLength: 128;
+    readonly version: "OPEN-ATTESTATION-TYPE-1";
+}>;
+/**
+ * Generates a random key represented as a hexadecimal string.
+ * @param {number} [keyLengthInBits] - Key length in bits.
+ * @returns {string} Hexadecimal-encoded encryption key.
+ */
+declare const generateEncryptionKey: (keyLengthInBits?: number) => string;
+/**
+ * Encode document string to URL-safe base64 (base64url: UTF-8 then base64 with +→-, /→_, no padding).
+ * Safe for use in query strings and JSON without further encoding.
+ * @param {string} document - Plain text document to encode.
+ * @returns {string} Base64url-encoded string.
+ */
+declare const encodeDocument: (document: string) => string;
+/**
+ * Decode base64url-encoded document string back to UTF-8.
+ * Accepts both base64url (no padding, - and _) and standard base64 for backwards compatibility.
+ * @param {string} encoded - Base64- or base64url-encoded string to decode.
+ * @returns {string} Decoded UTF-8 plain text.
+ */
+declare const decodeDocument: (encoded: string) => string;
 declare const isTransferableAsset: (document: any) => boolean;
 declare const isDocumentRevokable: (document: any) => boolean;
 declare const getAssetId: (document: any) => string;
@@ -39,4 +70,4 @@ declare const diagnose: ({ version, kind, document, debug, mode, }: {
 }) => utils.DiagnoseError[];
 declare const getTemplateURL: (document: any) => string | undefined;
 
-export { diagnose, getAssetId, getDocumentData, getIssuerAddress, getTemplateURL, isDocumentRevokable, isRawV2Document, isRawV3Document, isSignedWrappedV2Document, isSignedWrappedV3Document, isTransferableAsset, isWrappedV2Document, isWrappedV3Document };
+export { ENCRYPTION_PARAMETERS, decodeDocument, diagnose, encodeDocument, generateEncryptionKey, getAssetId, getDocumentData, getIssuerAddress, getTemplateURL, isDocumentRevokable, isRawV2Document, isRawV3Document, isSignedWrappedV2Document, isSignedWrappedV3Document, isTransferableAsset, isWrappedV2Document, isWrappedV3Document };

package/dist/types/transaction/cancel.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Transaction Cancel Module
+ *
+ * Cancels a pending transaction by replacing it with a 0-value transaction to self
+ * using the same nonce and a higher gas price (e.g. 2x when using --transaction-hash).
+ * @see https://info.etherscan.com/how-to-cancel-ethereum-pending-transactions/
+ */
+interface CancelTransactionOptions {
+    /** Pending transaction nonce (use with gasPrice, or use transactionHash instead) */
+    nonce?: string;
+    /** Gas price higher than the pending transaction (use with nonce) */
+    gasPrice?: string;
+    /** Pending transaction hash; nonce and gas price will be fetched and gas price increased by 100% */
+    transactionHash?: string;
+}
+/** Signer with provider, compatible with ethers v5 and v6. */
+interface CancelTransactionSigner {
+    getAddress(): Promise<string>;
+    provider: {
+        getTransaction?(hash: string): Promise<unknown>;
+    } | null;
+    sendTransaction(tx: Record<string, unknown>): Promise<{
+        hash: string;
+    }>;
+}
+/**
+ * Cancels a pending transaction by sending a 0-value transaction to self with the same nonce
+ * and a higher gas price. Supports both ethers v5 and v6 signers via a unified transaction object.
+ * @param {CancelTransactionSigner} signer - Signer with provider (ethers v5 or v6)
+ * @param {CancelTransactionOptions} options - Either (nonce + gasPrice) or transactionHash
+ * @returns {Promise<string>} The replacement transaction hash
+ * @throws If neither (nonce and gasPrice) nor transactionHash is provided
+ * @throws If provider is not available on signer
+ */
+declare const cancelTransaction: (signer: CancelTransactionSigner, options: CancelTransactionOptions) => Promise<string>;
+
+export { type CancelTransactionOptions, type CancelTransactionSigner, cancelTransaction };

package/dist/types/transaction/index.d.ts

@@ -0,0 +1 @@
+export { CancelTransactionOptions, CancelTransactionSigner, cancelTransaction } from './cancel.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trustvc/trustvc",
-  "version": "2.9.1",
+  "version": "2.11.0",
   "description": "TrustVC library",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -131,6 +131,7 @@
     "ethersV6": "npm:ethers@^6.14.4",
     "js-sha3": "^0.9.3",
     "node-fetch": "^2.7.0",
+    "node-forge": "^1.3.3",
     "ts-chacha20": "^1.2.0"
   },
   "devDependencies": {
@@ -149,6 +150,7 @@
     "@types/lodash": "^4.17.16",
     "@types/mocha": "^10.0.10",
     "@types/node": "^18.19.86",
+    "@types/node-forge": "^1.3.14",
     "@types/node-fetch": "^2.6.12",
     "@vitest/coverage-v8": "^1.6.1",
     "concurrently": "^9.2.0",