@hsuite/smart-engines-sdk 3.4.0 → 3.4.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 3.4.1 — 2026-06-01
+
+**Patch release** restoring 3 subpath exports that the 3.4.0 publish dropped despite being present in source:
+
+- `./pqc-verify-envelope` (landed in #981, 2026-05-29 — before the 3.4.0 release)
+- `./ipfs-access-key` (landed in #987, 2026-05-30)
+- `./k8s-secret-reader` (landed in #985, 2026-05-30)
+
+Root cause: SDK build config (`tsup.config.mjs` `entry` map + `package.json#scripts.build:dts` invocations) was never updated when the 3 new subpath dirs were added — only the root + `nestjs` + `pqc-verify` entry points were declared in the release commit (`ed4b9bf8`). 3.4.0 shipped with the missing dist artifacts, leaving consumers importing those subpaths with module-not-found errors.
+
+The build config and `package.json#exports` have since been updated on `develop` (merge `d76ef2e4`), but no version bump was published. This 3.4.1 release publishes those fixes.
+
+No source API change. No breaking change. Safe to bump from 3.4.0 to 3.4.1.
+
+### Regression guard
+
+`libs/smartengine-sdk/src/__tests__/dist-exports.spec.ts` asserts that every subpath in `package.json#exports` resolves to files that exist in `dist/` after `yarn build`. Reproduces the 3.4.0 failure mode when a `dist/<name>/` subdir is missing.
+
 ## 3.4.0 — 2026-05-31
 
 **Production-readiness arc.** Closes the audit gap identified after 3.3.0 shipped: ~55 of ~110 third-party-facing server endpoints were wrapped; this release brings coverage to ~95/110 (the remaining ~15 are intentionally internal — operator / DKG ceremony / harbor admin). SDK test suite grew from 477 → 637 (+160 tests).

package/dist/index.d.ts

@@ -25202,6 +25202,42 @@ export type VerifyResult = {
 	readonly thresholdMet?: boolean;
 };
 export declare function verifyPqcAttestation(cert: unknown, payload: unknown, registrySnapshot?: ValidatorRegistrySnapshot): Promise<VerifyResult>;
+export type EnvelopeVersionLiteral = "kyber-aes-v1" | "aes-v0";
+export type SchemaValidationResult = {
+	ok: true;
+	version: EnvelopeVersionLiteral;
+} | {
+	ok: false;
+	reason: string;
+};
+export declare function validateEnvelopeSchema(envelope: unknown): SchemaValidationResult;
+export declare const KYBER_MIN_TIMESTAMP_MS = 1704067200000;
+export type VerificationDetails = {
+	version: string;
+	kemAlgorithm?: "ml-kem-768" | "ml-kem-1024";
+	recipientPkFingerprint?: string;
+	kdfLabel?: string;
+	encryptedAt?: number;
+	schemaValid: boolean;
+	base64Valid: boolean;
+	timestampPlausible: boolean;
+};
+export type EnvelopeVerificationResult = {
+	valid: true;
+	version: EnvelopeVersionLiteral;
+	details: VerificationDetails;
+} | {
+	valid: false;
+	reason: string;
+	details?: Partial<VerificationDetails>;
+};
+export type VerifyEnvelopeOptions = {
+	expectedLabel?: string;
+	expectedRecipientPkFingerprint?: string;
+	minTimestamp?: number;
+	maxTimestamp?: number;
+};
+export declare function verifyPqcEnvelope(envelope: unknown, options?: VerifyEnvelopeOptions): Promise<EnvelopeVerificationResult>;
 
 declare namespace bitcoin {
 	export { btcToSatoshis, satoshisToBtc, validateBitcoinAddress };
@@ -25221,8 +25257,8 @@ declare namespace solana {
 declare namespace stellar {
 	export { stroopsToXlm, validateStellarAddress, xlmToStroops };
 }
-declare namespace pqcVerify {
-	export { FetchRegistryOptions, PqcCertV1, PqcCertV1Schema, PqcCertV1Signer, ValidatorRegistrySnapshot, VerifyResult, fetchRegistrySnapshot, parsePqcCert, verifyPqcAttestation };
+declare namespace pqcVerifyEnvelope {
+	export { EnvelopeVerificationResult, EnvelopeVersionLiteral, KYBER_MIN_TIMESTAMP_MS, SchemaValidationResult, VerificationDetails, VerifyEnvelopeOptions, validateEnvelopeSchema, verifyPqcEnvelope };
 }
 declare namespace discovery {
 	export { ClusterDiscoveryClient, ClusterDiscoveryConfig, ClusterEndpointsView, ClusterInfo, DiscoveryClient, DiscoveryClusterEndpoints, DiscoveryClusterRecord, DiscoveryNodeRecord, DiscoveryPlatformImageEnvelope, DiscoveryPlatformImageManifest, DiscoveryVerifyResult, MIRROR_NODE_URLS, MirrorNodeClient, MirrorNodeConfig, MirrorNodeError, PlatformImagesClient, TopicMessage, TopicMessagesResponse, ValidatorDiscoveryClient, ValidatorDiscoveryConfig, ValidatorInfo, ValidatorMetadata, ValidatorNetworkEndpoints };
@@ -25266,6 +25302,9 @@ declare namespace personhood {
 declare namespace baas {
 	export { AgentBalance, AgentEvent, AgentFundRequest, AgentInfo, AgentOperation, AgentRegisterRequest, AgentRules, AgentRulesValidationResult, AgentStatus, AgentTradeRequest, AgentWithdrawRequest, AgentsClient, AuthenticateOptions, BaasAppListResponse, BaasAuthConfig, BaasAuthResult, BaasChallengeRequest, BaasChallengeResponse, BaasChannelConfig, BaasClient, BaasClientConfig, BaasConnectToClusterConfig, BaasDeleteResult, BaasDeployRequest, BaasDeployResponse, BaasDocument, BaasEndpoints, BaasError, BaasErrorDetails, BaasErrorResponse, BaasFileInfo, BaasFileMetadata, BaasFindResult, BaasFunctionDeployRequest, BaasFunctionDeployResult, BaasFunctionInfo, BaasFunctionLog, BaasFunctionLogOptions, BaasFunctionResources, BaasFunctionResult, BaasFunctionRuntime, BaasHistoryOptions, BaasInitRequest, BaasInitResponse, BaasInsertResult, BaasMerkleProof, BaasMessage, BaasPresenceInfo, BaasPresenceMember, BaasPublishResult, BaasQueryOptions, BaasRevokeKekResponse, BaasRollbackRequest, BaasRotateKekResponse, BaasRuntimeStatus, BaasService, BaasSessionInfo, BaasSetWebhookResponse, BaasStateTransition, BaasStorageUsage, BaasSupportedChain, BaasTriggerType, BaasUpdateResult, BaasUploadFrontendResponse, BaasUploadResult, BaasVerifyRequest, ChannelSubscription, CreateAccountRequest$1 as BaasCreateAccountRequest, CreateAgentRequest, CreateTokenRequest$1 as CreateTokenRequest, CreateTopicRequest, DatabaseClient, DatabaseStatsResponse, DbComparisonOperator, DbDocument, DbQuery, DeployedApp, DeployedAppInfo, DeployedAppLimits, DeployedAppStatus, DeployedAppUsage, DeploymentClient, DeprecateRuleResponse, DocumentProofResponse, EntitiesClient, EntityCreationResult, EntityInfo, EntityType$1 as BaasEntityType, FunctionsClient, LaunchpadEntityRequest, LaunchpadEntityResult, ListEntitiesFilter, ListEntitiesResponse, ListRulesFilter, ListRulesResponse, MessageHandler, MessagingClient, PublishRuleResponse, RulesClient, SimulateRuleRequest, StateRootResponse, StateTransitionsResponse, StorageClient, ValidationResult, VersionHistoryResponse, validateAgentRules };
 }
+declare namespace pqcVerify {
+	export { FetchRegistryOptions, PqcCertV1, PqcCertV1Schema, PqcCertV1Signer, ValidatorRegistrySnapshot, VerifyResult, fetchRegistrySnapshot, parsePqcCert, verifyPqcAttestation };
+}
 
 export {
 	RetryConfig as ResilienceRetryConfig,
@@ -25281,6 +25320,7 @@ export {
 	operator,
 	personhood,
 	pqcVerify,
+	pqcVerifyEnvelope,
 	resources,
 	settlement,
 	subscription,

package/dist/index.js

@@ -123,12 +123,12 @@ var require_lib = __commonJS({
       if (lengths.length > 0 && !lengths.includes(b.length))
         throw new Error("Uint8Array expected of length " + lengths + ", got length=" + b.length);
     }
-    function isArrayOf(isString, arr) {
+    function isArrayOf(isString2, arr) {
       if (!Array.isArray(arr))
         return false;
       if (arr.length === 0)
         return true;
-      if (isString) {
+      if (isString2) {
         return arr.every((item) => typeof item === "string");
       } else {
         return arr.every((item) => Number.isSafeInteger(item));
@@ -11104,6 +11104,251 @@ async function verifyPqcAttestation(cert, payload, registrySnapshot) {
   };
 }
 
+// src/pqc-verify-envelope/index.ts
+var pqc_verify_envelope_exports = {};
+__export(pqc_verify_envelope_exports, {
+  KYBER_MIN_TIMESTAMP_MS: () => KYBER_MIN_TIMESTAMP_MS,
+  validateEnvelopeSchema: () => validateEnvelopeSchema,
+  verifyPqcEnvelope: () => verifyPqcEnvelope
+});
+
+// src/pqc-verify-envelope/envelope-schema-validator.ts
+var KEM_CT_LEN = {
+  "ml-kem-768": 1088,
+  "ml-kem-1024": 1568
+};
+var AES_IV_LEN = 12;
+var AES_TAG_LEN = 16;
+var KDF_SALT_LEN = 16;
+function tryDecodeBase64(s) {
+  if (typeof s !== "string" || s.length === 0) return null;
+  try {
+    const buf = Buffer.from(s, "base64");
+    if (buf.toString("base64").replace(/=+$/, "") !== s.replace(/=+$/, "")) {
+      return null;
+    }
+    return new Uint8Array(buf);
+  } catch {
+    return null;
+  }
+}
+function isString(v) {
+  return typeof v === "string";
+}
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.length > 0;
+}
+function isFiniteNumber(v) {
+  return typeof v === "number" && Number.isFinite(v);
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function validateEnvelopeSchema(envelope) {
+  if (!isPlainObject(envelope)) {
+    return { ok: false, reason: "envelope must be a JSON object" };
+  }
+  const version = envelope.version;
+  if (version === "kyber-aes-v1") {
+    return validateKyberAesV1(envelope);
+  }
+  if (version === "aes-v0") {
+    return validateAesV0(envelope);
+  }
+  return {
+    ok: false,
+    reason: `unknown envelope version: ${JSON.stringify(version)}`
+  };
+}
+function validateKyberAesV1(env) {
+  const kemAlgorithm = env.kemAlgorithm;
+  if (kemAlgorithm !== "ml-kem-768" && kemAlgorithm !== "ml-kem-1024") {
+    return {
+      ok: false,
+      reason: `kemAlgorithm must be 'ml-kem-768' or 'ml-kem-1024'`
+    };
+  }
+  if (!isNonEmptyString(env.kemCiphertext)) {
+    return { ok: false, reason: "kemCiphertext must be a non-empty base64 string" };
+  }
+  const kemCtBytes = tryDecodeBase64(env.kemCiphertext);
+  if (!kemCtBytes) {
+    return { ok: false, reason: "kemCiphertext is not valid base64" };
+  }
+  const expectedKemLen = KEM_CT_LEN[kemAlgorithm];
+  if (kemCtBytes.length !== expectedKemLen) {
+    return {
+      ok: false,
+      reason: `kemCiphertext length ${kemCtBytes.length} != expected ${expectedKemLen} for ${kemAlgorithm}`
+    };
+  }
+  if (!isString(env.recipientPkFingerprint) || !/^[0-9a-f]{32}$/i.test(env.recipientPkFingerprint)) {
+    return {
+      ok: false,
+      reason: "recipientPkFingerprint must be a 32-char hex string (16-byte sha384 prefix)"
+    };
+  }
+  if (env.aesAlgorithm !== "aes-256-gcm") {
+    return { ok: false, reason: `aesAlgorithm must be 'aes-256-gcm'` };
+  }
+  if (!isNonEmptyString(env.aesIv)) {
+    return { ok: false, reason: "aesIv must be a non-empty base64 string" };
+  }
+  const ivBytes = tryDecodeBase64(env.aesIv);
+  if (!ivBytes) return { ok: false, reason: "aesIv is not valid base64" };
+  if (ivBytes.length !== AES_IV_LEN) {
+    return {
+      ok: false,
+      reason: `aesIv length ${ivBytes.length} != expected ${AES_IV_LEN} (AES-GCM 96-bit nonce)`
+    };
+  }
+  if (typeof env.aesCiphertext !== "string") {
+    return { ok: false, reason: "aesCiphertext must be a base64 string" };
+  }
+  if (env.aesCiphertext.length > 0) {
+    const ctBytes = tryDecodeBase64(env.aesCiphertext);
+    if (!ctBytes) return { ok: false, reason: "aesCiphertext is not valid base64" };
+  }
+  if (!isNonEmptyString(env.aesAuthTag)) {
+    return { ok: false, reason: "aesAuthTag must be a non-empty base64 string" };
+  }
+  const tagBytes = tryDecodeBase64(env.aesAuthTag);
+  if (!tagBytes) return { ok: false, reason: "aesAuthTag is not valid base64" };
+  if (tagBytes.length !== AES_TAG_LEN) {
+    return {
+      ok: false,
+      reason: `aesAuthTag length ${tagBytes.length} != expected ${AES_TAG_LEN} (AES-GCM 128-bit tag)`
+    };
+  }
+  if (env.kdfAlgorithm !== "hkdf-sha384") {
+    return { ok: false, reason: `kdfAlgorithm must be 'hkdf-sha384'` };
+  }
+  if (!isNonEmptyString(env.kdfSalt)) {
+    return { ok: false, reason: "kdfSalt must be a non-empty base64 string" };
+  }
+  const saltBytes = tryDecodeBase64(env.kdfSalt);
+  if (!saltBytes) return { ok: false, reason: "kdfSalt is not valid base64" };
+  if (saltBytes.length !== KDF_SALT_LEN) {
+    return {
+      ok: false,
+      reason: `kdfSalt length ${saltBytes.length} != expected ${KDF_SALT_LEN}`
+    };
+  }
+  if (!isNonEmptyString(env.kdfLabel)) {
+    return { ok: false, reason: "kdfLabel must be a non-empty string" };
+  }
+  if (env.kdfLabel.length > 256) {
+    return {
+      ok: false,
+      reason: `kdfLabel length ${env.kdfLabel.length} exceeds 256-char limit`
+    };
+  }
+  if (!isFiniteNumber(env.encryptedAt)) {
+    return { ok: false, reason: "encryptedAt must be a finite number (millis epoch)" };
+  }
+  return { ok: true, version: "kyber-aes-v1" };
+}
+function validateAesV0(env) {
+  if (!isNonEmptyString(env.aesIv)) {
+    return { ok: false, reason: "aesIv must be a non-empty base64 string" };
+  }
+  const ivBytes = tryDecodeBase64(env.aesIv);
+  if (!ivBytes) return { ok: false, reason: "aesIv is not valid base64" };
+  if (ivBytes.length !== AES_IV_LEN) {
+    return {
+      ok: false,
+      reason: `aesIv length ${ivBytes.length} != expected ${AES_IV_LEN} (AES-GCM 96-bit nonce)`
+    };
+  }
+  if (typeof env.aesCiphertext !== "string") {
+    return { ok: false, reason: "aesCiphertext must be a base64 string" };
+  }
+  if (env.aesCiphertext.length > 0) {
+    const ctBytes = tryDecodeBase64(env.aesCiphertext);
+    if (!ctBytes) return { ok: false, reason: "aesCiphertext is not valid base64" };
+  }
+  if (!isNonEmptyString(env.aesAuthTag)) {
+    return { ok: false, reason: "aesAuthTag must be a non-empty base64 string" };
+  }
+  const tagBytes = tryDecodeBase64(env.aesAuthTag);
+  if (!tagBytes) return { ok: false, reason: "aesAuthTag is not valid base64" };
+  if (tagBytes.length !== AES_TAG_LEN) {
+    return {
+      ok: false,
+      reason: `aesAuthTag length ${tagBytes.length} != expected ${AES_TAG_LEN} (AES-GCM 128-bit tag)`
+    };
+  }
+  return { ok: true, version: "aes-v0" };
+}
+
+// src/pqc-verify-envelope/verify-pqc-envelope.ts
+var KYBER_MIN_TIMESTAMP_MS = 17040672e5;
+async function verifyPqcEnvelope(envelope, options = {}) {
+  const schema = validateEnvelopeSchema(envelope);
+  if (!schema.ok) {
+    return {
+      valid: false,
+      reason: `schema-invalid: ${schema.reason}`,
+      details: { schemaValid: false, base64Valid: false, timestampPlausible: false }
+    };
+  }
+  const env = envelope;
+  const version = schema.version;
+  const details = {
+    version,
+    schemaValid: true,
+    base64Valid: true,
+    // computed below for kyber-aes-v1; legacy has no encryptedAt so treat as plausible.
+    timestampPlausible: true
+  };
+  if (version === "kyber-aes-v1") {
+    details.kemAlgorithm = env.kemAlgorithm;
+    details.recipientPkFingerprint = env.recipientPkFingerprint;
+    details.kdfLabel = env.kdfLabel;
+    details.encryptedAt = env.encryptedAt;
+    const minTs = options.minTimestamp ?? KYBER_MIN_TIMESTAMP_MS;
+    const maxTs = options.maxTimestamp ?? Date.now();
+    const ts = details.encryptedAt;
+    if (ts < minTs) {
+      details.timestampPlausible = false;
+      return {
+        valid: false,
+        reason: `timestamp-before-minimum: encryptedAt=${ts} < min=${minTs}`,
+        details
+      };
+    }
+    if (ts > maxTs) {
+      details.timestampPlausible = false;
+      return {
+        valid: false,
+        reason: `timestamp-in-future: encryptedAt=${ts} > max=${maxTs}`,
+        details
+      };
+    }
+    if (options.expectedLabel !== void 0) {
+      if (details.kdfLabel !== options.expectedLabel) {
+        return {
+          valid: false,
+          reason: `label-mismatch: expected='${options.expectedLabel}' actual='${details.kdfLabel}'`,
+          details
+        };
+      }
+    }
+    if (options.expectedRecipientPkFingerprint !== void 0) {
+      const a = (details.recipientPkFingerprint ?? "").toLowerCase();
+      const b = options.expectedRecipientPkFingerprint.toLowerCase();
+      if (a !== b) {
+        return {
+          valid: false,
+          reason: `recipient-pk-fingerprint-mismatch: expected='${b}' actual='${a}'`,
+          details
+        };
+      }
+    }
+  }
+  return { valid: true, version, details };
+}
+
 // src/rules/atoms/index.ts
 var atom = {
   timeRange: (cfg) => ({
@@ -12543,6 +12788,7 @@ exports.HistoricalBalanceClient = HistoricalBalanceClient;
 exports.HistoricalBalanceClientError = HistoricalBalanceClientError;
 exports.IPFSClient = IPFSClient;
 exports.KNOWN_NETWORKS = KNOWN_NETWORKS;
+exports.KYBER_MIN_TIMESTAMP_MS = KYBER_MIN_TIMESTAMP_MS;
 exports.KeyConditionSchema = KeyConditionSchema;
 exports.MIRROR_NODE_URLS = MIRROR_NODE_URLS;
 exports.MessagingClient = MessagingClient;
@@ -12637,6 +12883,7 @@ exports.operator = operator_exports;
 exports.parsePqcCert = parsePqcCert;
 exports.personhood = personhood_exports;
 exports.pqcVerify = pqc_verify_exports;
+exports.pqcVerifyEnvelope = pqc_verify_envelope_exports;
 exports.resilientFetch = resilientFetch;
 exports.resolveNetwork = resolveNetwork;
 exports.resources = resources_exports;
@@ -12655,7 +12902,9 @@ exports.tradingAgent = tradingAgent;
 exports.utilityToken = utilityToken;
 exports.validate = validate;
 exports.validateAgentRules = validateAgentRules;
+exports.validateEnvelopeSchema = validateEnvelopeSchema;
 exports.verifyPqcAttestation = verifyPqcAttestation;
+exports.verifyPqcEnvelope = verifyPqcEnvelope;
 exports.vestingSchedule = vestingSchedule;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map