@tinycloud/sdk-services 3.11.0-beta.2 → 3.12.0-beta.10

package/dist/encryption/index.js

@@ -10,6 +10,10 @@ var ErrorCodes = {
   /** HTTP 401: a delegation the cited one rests on was revoked. */
   AUTH_DELEGATION_ANCESTOR_REVOKED: "AUTH_DELEGATION_ANCESTOR_REVOKED",
   NETWORK_ERROR: "NETWORK_ERROR",
+  NODE_NOT_RESPONDING: "NODE_NOT_RESPONDING",
+  NODE_IDENTITY_MISMATCH: "NODE_IDENTITY_MISMATCH",
+  PARTIAL_NODE_WRITE: "PARTIAL_NODE_WRITE",
+  RESOURCE_NOT_ROUTED: "RESOURCE_NOT_ROUTED",
   TIMEOUT: "TIMEOUT",
   ABORTED: "ABORTED",
   INVALID_INPUT: "INVALID_INPUT",
@@ -206,6 +210,34 @@ function networkDiscoveryKey(name) {
 var ENCRYPTION_NETWORK_URN_PREFIX = URN_PREFIX;
 var NETWORK_NAME_PATTERN = NETWORK_NAME_RE;
 
+// src/resourceRouting.ts
+var ROUTING_FAILURE_CODES = {
+  NODE_NOT_RESPONDING: true,
+  PARTIAL_NODE_WRITE: true,
+  NODE_IDENTITY_MISMATCH: true,
+  RESOURCE_NOT_ROUTED: true,
+  DECRYPTION_DEPENDENCY_UNAVAILABLE: true,
+  registry_unavailable: true,
+  node_not_found: true,
+  node_registry_entry_exists: true
+};
+function isRoutingFailureCode(code) {
+  return Object.prototype.hasOwnProperty.call(ROUTING_FAILURE_CODES, code);
+}
+function routingFailure(error) {
+  if (typeof error === "object" && error !== null && "code" in error && "message" in error && typeof error.code === "string" && typeof error.message === "string" && isRoutingFailureCode(error.code)) {
+    const candidate = "meta" in error ? error.meta : void 0;
+    let meta = typeof candidate === "object" && candidate !== null && !Array.isArray(candidate) ? candidate : void 0;
+    if (error.code === "NODE_NOT_RESPONDING" && "hosts" in error && Array.isArray(error.hosts)) {
+      meta = { ...meta, hosts: error.hosts };
+    } else if (error.code === "PARTIAL_NODE_WRITE" && "succeeded" in error && Array.isArray(error.succeeded) && "failed" in error && Array.isArray(error.failed)) {
+      meta = { ...meta, succeeded: error.succeeded, failed: error.failed };
+    }
+    return { code: error.code, message: error.message, ...error instanceof Error ? { cause: error } : {}, ...meta ? { meta } : {} };
+  }
+  return void 0;
+}
+
 // src/errors.ts
 var RequestTimeoutError = class extends Error {
   constructor(timeoutMs) {
@@ -248,6 +280,8 @@ var capabilityServices = new Set(
   CAPABILITY_REGISTRY.map(({ service }) => service.slice("tinycloud.".length))
 );
 function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
+  const routing = routingFailure(error);
+  if (routing) return { ...routing, service };
   if (error instanceof Error) {
     if (isRequestTimeoutError(error)) {
       return timeoutError(service, error.timeoutMs, error);
@@ -659,9 +693,9 @@ function utf8Encode(s) {
 function utf8Decode(b) {
   return new TextDecoder().decode(b);
 }
-function canonicalHashHex(sha256, value) {
+function canonicalHashHex(sha2562, value) {
   const canonical = canonicalize(value);
-  return hexEncode(sha256(utf8Encode(canonical)));
+  return hexEncode(sha2562(utf8Encode(canonical)));
 }
 
 // src/encryption/types.ts
@@ -695,6 +729,8 @@ function defaultEncryptionMessage(input) {
       return input.message ?? input.cause.message;
     case "INVALID_INPUT":
       return input.message;
+    default:
+      return input.message ?? input.code;
   }
 }
 function encryptionError(input) {
@@ -759,6 +795,8 @@ async function discoverNetwork(input) {
         return { ok: true, data: { descriptor: validated.data, source: "node" } };
       }
     } catch (err2) {
+      const routing = routingFailure(err2);
+      if (routing) return { ok: false, error: encryptionError(routing) };
     }
   }
   if (input.wellKnown !== void 0) {
@@ -776,6 +814,8 @@ async function discoverNetwork(input) {
         };
       }
     } catch (err2) {
+      const routing = routingFailure(err2);
+      if (routing) return { ok: false, error: encryptionError(routing) };
     }
   }
   return {
@@ -865,6 +905,160 @@ function ensureNetworkUsableForDecrypt(descriptor) {
   };
 }
 
+// src/encryption/keyWrap.ts
+import { gcm } from "@noble/ciphers/aes";
+import { x25519 } from "@noble/curves/ed25519";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha256";
+import { randomBytes } from "@noble/hashes/utils";
+var KEY_WRAP_V2_ALG = "x25519-hkdf-aes256gcm/v2";
+var MAGIC = utf8Encode("TCW2");
+var INFO = utf8Encode("tinycloud.encryption.key-wrap/v2");
+var MAX_HEADER = 65536;
+function concat(...parts) {
+  const result = new Uint8Array(parts.reduce((length, part) => length + part.length, 0));
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+  return result;
+}
+function equal(a, b) {
+  if (a.length !== b.length) return false;
+  let difference = 0;
+  for (let i = 0; i < a.length; i++) difference |= a[i] ^ b[i];
+  return difference === 0;
+}
+function decode32(value) {
+  if (typeof value !== "string") throw new Error("Invalid key wrap encoding");
+  const decoded = base64Decode(value);
+  if (decoded.length !== 32 || base64Encode(decoded) !== value) throw new Error("Invalid key wrap encoding");
+  return decoded;
+}
+function isWellFormed(value) {
+  for (let i = 0; i < value.length; i++) {
+    const unit = value.charCodeAt(i);
+    if (unit >= 55296 && unit <= 56319) {
+      const next = value.charCodeAt(++i);
+      if (!(next >= 56320 && next <= 57343)) return false;
+    } else if (unit >= 56320 && unit <= 57343) return false;
+  }
+  return true;
+}
+function validateContext(context) {
+  if (context.purpose !== "network-key" && context.purpose !== "receiver-key" || typeof context.networkId !== "string" || typeof context.keyPath !== "string" || !isWellFormed(context.networkId) || !isWellFormed(context.keyPath) || !Number.isSafeInteger(context.keyVersion) || context.keyVersion <= 0 || !context.metadata || typeof context.metadata !== "object" || Array.isArray(context.metadata) || Object.entries(context.metadata).some(([key, value]) => !isWellFormed(key) || typeof value !== "string" || !isWellFormed(value))) {
+    throw new Error("Invalid key wrap context");
+  }
+  if (context.networkId !== "") {
+    const resource = parseEncryptionResource(context.keyPath === "" ? context.networkId : `${context.networkId}/${context.keyPath}`);
+    if (resource.networkId !== context.networkId || (resource.keyPath ?? "") !== context.keyPath || context.keyPath.endsWith("/")) {
+      throw new Error("Invalid key wrap resource");
+    }
+  }
+}
+function isKeyWrapV2(wrapped) {
+  return wrapped.length >= 4 && MAGIC.every((byte, index) => wrapped[index] === byte);
+}
+function readKeyWrapV2(wrapped) {
+  if (!isKeyWrapV2(wrapped) || wrapped.length < 8) throw new Error("Invalid v2 key wrap frame");
+  const length = new DataView(wrapped.buffer, wrapped.byteOffset, wrapped.byteLength).getUint32(4);
+  if (length === 0 || length > MAX_HEADER || wrapped.length < 8 + length + 12 + 16) throw new Error("Invalid v2 key wrap length");
+  const bytes = wrapped.subarray(8, 8 + length);
+  const header = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  const fields = ["v", "alg", "kdf", "aead", "salt", "ephemeralPublicKey", "recipientPublicKey", "purpose", "networkId", "keyPath", "keyVersion", "metadata"].sort();
+  if (!header || typeof header !== "object" || Array.isArray(header) || Object.keys(header).sort().join(",") !== fields.join(",") || header.v !== 2 || header.alg !== KEY_WRAP_V2_ALG || header.kdf !== "hkdf-sha256" || header.aead !== "aes-256-gcm") {
+    throw new Error("Invalid v2 key wrap header");
+  }
+  validateContext(header);
+  decode32(header.salt);
+  decode32(header.ephemeralPublicKey);
+  decode32(header.recipientPublicKey);
+  if (!equal(bytes, utf8Encode(canonicalize({ ...header })))) throw new Error("Non-canonical v2 key wrap header");
+  const end = 8 + length;
+  return { header, aad: wrapped.subarray(0, end), nonce: wrapped.subarray(end, end + 12), ciphertext: wrapped.subarray(end + 12) };
+}
+function assertKeyWrapContext(header, expected) {
+  validateContext(expected);
+  for (const field of ["purpose", "networkId", "keyPath", "keyVersion"]) {
+    if (header[field] !== expected[field]) throw new Error("Key wrap context mismatch");
+  }
+  if (canonicalize(header.metadata) !== canonicalize(expected.metadata)) throw new Error("Key wrap metadata mismatch");
+}
+function deriveKey(secret, ephemeral, recipient, salt) {
+  const shared = x25519.getSharedSecret(secret, ephemeral);
+  if (shared.every((byte) => byte === 0)) throw new Error("Invalid key agreement");
+  try {
+    return hkdf(sha256, shared, salt, concat(INFO, ephemeral, recipient), 32);
+  } finally {
+    shared.fill(0);
+  }
+}
+function sealKeyV2(recipientPublicKey, plaintext, context) {
+  validateContext(context);
+  if (recipientPublicKey.length !== 32) throw new Error("Invalid recipient public key");
+  const secret = randomBytes(32);
+  const ephemeral = x25519.getPublicKey(secret);
+  const salt = randomBytes(32);
+  const header = {
+    ...context,
+    v: 2,
+    alg: KEY_WRAP_V2_ALG,
+    kdf: "hkdf-sha256",
+    aead: "aes-256-gcm",
+    salt: base64Encode(salt),
+    ephemeralPublicKey: base64Encode(ephemeral),
+    recipientPublicKey: base64Encode(recipientPublicKey)
+  };
+  const bytes = utf8Encode(canonicalize({ ...header }));
+  if (bytes.length > MAX_HEADER) throw new Error("Key wrap header too large");
+  const prefix = new Uint8Array(8);
+  prefix.set(MAGIC);
+  new DataView(prefix.buffer).setUint32(4, bytes.length);
+  const aad = concat(prefix, bytes);
+  const nonce = randomBytes(12);
+  let key;
+  try {
+    const shared = x25519.getSharedSecret(secret, recipientPublicKey);
+    try {
+      if (shared.every((byte) => byte === 0)) throw new Error("Invalid key agreement");
+      key = hkdf(sha256, shared, salt, concat(INFO, ephemeral, recipientPublicKey), 32);
+    } finally {
+      shared.fill(0);
+    }
+    return concat(aad, nonce, gcm(key, nonce, aad).encrypt(plaintext));
+  } finally {
+    secret.fill(0);
+    key?.fill(0);
+  }
+}
+function openKeyV2(recipientPrivateKey, wrapped, expected) {
+  const { header, aad, nonce, ciphertext } = readKeyWrapV2(wrapped);
+  assertKeyWrapContext(header, expected);
+  const recipient = x25519.getPublicKey(recipientPrivateKey);
+  if (!equal(recipient, decode32(header.recipientPublicKey))) throw new Error("Key wrap recipient mismatch");
+  const key = deriveKey(recipientPrivateKey, decode32(header.ephemeralPublicKey), recipient, decode32(header.salt));
+  try {
+    return gcm(key, nonce, aad).decrypt(ciphertext);
+  } finally {
+    key.fill(0);
+  }
+}
+function assertKeyWrapAlgorithm(wrapped, alg, requireV2 = false) {
+  if (alg !== "x25519-aes256gcm/v1" && alg !== KEY_WRAP_V2_ALG) throw new Error("Unsupported key wrap algorithm");
+  if (requireV2 && alg !== KEY_WRAP_V2_ALG) throw new Error("V2 network key wrap required");
+  if (isKeyWrapV2(wrapped) !== (alg === KEY_WRAP_V2_ALG)) throw new Error("Key wrap algorithm mismatch");
+  if (alg === KEY_WRAP_V2_ALG) readKeyWrapV2(wrapped);
+}
+function decryptColumn(decrypt, key, blob, expectedFormat, strictEncryption = false) {
+  if (expectedFormat === "legacy-plaintext") {
+    if (strictEncryption) throw new Error("Legacy plaintext is disabled");
+    return blob;
+  }
+  if (expectedFormat !== "encrypted" || blob.length < 1 + 12 + 16 || blob[0] !== 1) throw new Error("Invalid encrypted column frame");
+  return decrypt(key, blob.subarray(1));
+}
+
 // src/encryption/envelope.ts
 function encryptToNetwork(crypto, input) {
   const parsedResource = parseEncryptionResource(
@@ -873,11 +1067,20 @@ function encryptToNetwork(crypto, input) {
   if (parsedResource.keyPath !== input.keyPath || input.keyPath?.endsWith("/")) {
     throw new NetworkIdError("keyPath must name an exact encryption key");
   }
-  const alg = input.alg ?? DEFAULT_ENCRYPTION_ALG;
+  const alg = input.keyWrapV2 ? KEY_WRAP_V2_ALG : DEFAULT_ENCRYPTION_ALG;
+  if (input.alg !== void 0 && input.alg !== alg) {
+    throw new Error("Algorithm does not match keyWrapV2");
+  }
   const keyVersion = input.keyVersion ?? DEFAULT_KEY_VERSION;
   const symmetricKey = crypto.randomBytes(32);
   const ciphertext = crypto.authEncrypt(symmetricKey, input.plaintext, input.aad);
-  const wrapped = crypto.sealToNetworkKey(input.networkPublicKey, symmetricKey);
+  const wrapped = input.keyWrapV2 ? sealKeyV2(input.networkPublicKey, symmetricKey, {
+    purpose: "network-key",
+    networkId: input.networkId,
+    keyPath: input.keyPath ?? "",
+    keyVersion,
+    metadata: input.metadata ?? {}
+  }) : crypto.sealToNetworkKey(input.networkPublicKey, symmetricKey);
   const encryptedSymmetricKey = base64Encode(wrapped);
   const encryptedSymmetricKeyHash = canonicalHashHex(
     crypto.sha256,
@@ -897,7 +1100,7 @@ function encryptToNetwork(crypto, input) {
   };
   return { envelope, symmetricKey };
 }
-function validateEnvelope(crypto, envelope) {
+function validateEnvelope(crypto, envelope, requireKeyWrapV2 = false) {
   if (envelope === null || typeof envelope !== "object") {
     return {
       ok: false,
@@ -974,9 +1177,28 @@ function validateEnvelope(crypto, envelope) {
       })
     };
   }
+  try {
+    validateEnvelopeKeyWrap(e, requireKeyWrapV2);
+  } catch {
+    return { ok: false, error: encryptionError({ code: "INVALID_ENVELOPE", message: "Envelope key wrap context is invalid" }) };
+  }
   return { ok: true, data: e };
 }
+function validateEnvelopeKeyWrap(envelope, requireKeyWrapV2 = false) {
+  const wrapped = base64Decode(envelope.encryptedSymmetricKey);
+  assertKeyWrapAlgorithm(wrapped, envelope.alg, requireKeyWrapV2);
+  if (envelope.alg === KEY_WRAP_V2_ALG) {
+    assertKeyWrapContext(readKeyWrapV2(wrapped).header, {
+      purpose: "network-key",
+      networkId: envelope.networkId,
+      keyPath: envelope.keyPath ?? "",
+      keyVersion: envelope.keyVersion,
+      metadata: envelope.metadata ?? {}
+    });
+  }
+}
 function decryptEnvelopeWithKey(crypto, envelope, symmetricKey) {
+  validateEnvelopeKeyWrap(envelope);
   const ciphertext = base64Decode(envelope.ciphertext);
   const aad = envelope.aad !== void 0 ? base64Decode(envelope.aad) : void 0;
   return crypto.authDecrypt(symmetricKey, ciphertext, aad);
@@ -1266,7 +1488,7 @@ function verifyDecryptResponse(input) {
       })
     };
   }
-  if (response.alg !== request.alg) {
+  if (response.alg !== "x25519-aes256gcm/v1" && response.alg !== KEY_WRAP_V2_ALG) {
     return {
       ok: false,
       error: encryptionError({
@@ -1323,7 +1545,7 @@ function verifyDecryptResponse(input) {
       })
     };
   }
-  if (facts.encryptedSymmetricKeyHash !== response.encryptedSymmetricKeyHash || facts.receiverPublicKeyHash !== response.receiverPublicKeyHash || facts.networkId !== response.networkId || facts.targetNode !== response.targetNode || facts.alg !== response.alg || facts.keyVersion !== response.keyVersion) {
+  if (facts.encryptedSymmetricKeyHash !== response.encryptedSymmetricKeyHash || facts.receiverPublicKeyHash !== response.receiverPublicKeyHash || facts.networkId !== response.networkId || facts.targetNode !== response.targetNode || facts.alg !== request.alg || facts.keyVersion !== response.keyVersion) {
     return {
       ok: false,
       error: encryptionError({
@@ -1346,8 +1568,13 @@ function verifyDecryptResponse(input) {
   }
   return { ok: true, data: response };
 }
-function openWrappedKey(crypto, receiverPrivateKey, response) {
+function openWrappedKey(crypto, receiverPrivateKey, response, expected) {
   const wrapped = base64Decode(response.wrappedKey);
+  assertKeyWrapAlgorithm(wrapped, response.alg);
+  if (response.alg === KEY_WRAP_V2_ALG) {
+    if (!expected) throw new Error("V2 response requires expected key context");
+    return openKeyV2(receiverPrivateKey, wrapped, expected);
+  }
   return crypto.openWithReceiverKey(receiverPrivateKey, wrapped);
 }
 
@@ -1360,6 +1587,14 @@ function encOk(data) {
 function encErr(error) {
   return { ok: false, error };
 }
+function decryptionError(input) {
+  const unavailable = input.code === "NODE_NOT_RESPONDING" || input.code === "TRANSPORT_ERROR" && input.cause.name !== "AbortError";
+  return encryptionError(unavailable ? {
+    ...input,
+    code: "DECRYPTION_DEPENDENCY_UNAVAILABLE",
+    message: "The decryption service isn't responding right now. Please try again."
+  } : input);
+}
 var EncryptionService = class extends BaseService {
   constructor(config) {
     super();
@@ -1401,12 +1636,15 @@ var EncryptionService = class extends BaseService {
         networkPublicKey,
         plaintext,
         ...options?.aad !== void 0 ? { aad: options.aad } : {},
-        alg: options?.alg ?? descriptor.alg,
+        keyWrapV2: options?.keyWrapV2 ?? this._config.keyWrapV2 ?? false,
+        ...options?.alg !== void 0 ? { alg: options.alg } : {},
         keyVersion: options?.keyVersion ?? descriptor.keyVersion,
         ...options?.metadata !== void 0 ? { metadata: options.metadata } : {}
       });
       return encOk(result.envelope);
     } catch (error) {
+      const routing = routingFailure(error);
+      if (routing) return encErr(encryptionError(routing));
       return encErr(
         encryptionError({
           code: "TRANSPORT_ERROR",
@@ -1418,7 +1656,7 @@ var EncryptionService = class extends BaseService {
   async decryptEnvelope(envelope, capabilityProof, options) {
     try {
       this.assertActive();
-      const validated = validateEnvelope(this.crypto, envelope);
+      const validated = validateEnvelope(this.crypto, envelope, this._config.requireKeyWrapV2 ?? false);
       if (!validated.ok) return validated;
       if (options?.aad !== void 0 && validated.data.aad !== base64Encode(options.aad)) {
         return encErr(
@@ -1433,12 +1671,12 @@ var EncryptionService = class extends BaseService {
         descriptor = options.descriptor;
       } else {
         const discovered = await this.discoverNetwork(envelope.networkId);
-        if (!discovered.ok) return discovered;
+        if (!discovered.ok) return encErr(decryptionError(discovered.error));
         descriptor = discovered.data;
       }
       const usable = ensureNetworkUsableForDecrypt(descriptor);
       if (!usable.ok) return usable;
-      const targetNode = options?.targetNode ?? descriptor.members[0]?.nodeId;
+      const targetNode = this._config.resolveTargetNode ? await this._config.resolveTargetNode(envelope.networkId) : options?.targetNode ?? descriptor.members[0]?.nodeId;
       if (targetNode === void 0) {
         return encErr(
           encryptionError({
@@ -1447,6 +1685,9 @@ var EncryptionService = class extends BaseService {
           })
         );
       }
+      if (this._config.resolveTargetNode && (options?.targetNode !== void 0 && options.targetNode !== targetNode || !descriptor.members.some((member) => member.nodeId === targetNode))) {
+        return encErr(encryptionError({ code: "INVALID_INPUT", message: "Encryption destination does not match the registry" }));
+      }
       const receiverKey = generateRandomReceiverKey({ crypto: this.crypto });
       const receiverPublicKey = base64Encode(receiverKey.publicKey);
       const receiverPublicKeyHash = canonicalHashHex(
@@ -1505,6 +1746,8 @@ var EncryptionService = class extends BaseService {
         });
         this.assertActive();
       } catch (error) {
+        const routing = routingFailure(error);
+        if (routing) return encErr(decryptionError(routing));
         if (error instanceof DecryptTransportResponseError) {
           return encErr(
             encryptionError(
@@ -1521,7 +1764,7 @@ var EncryptionService = class extends BaseService {
           );
         }
         return encErr(
-          encryptionError({
+          decryptionError({
             code: "TRANSPORT_ERROR",
             cause: toError(error)
           })
@@ -1539,7 +1782,8 @@ var EncryptionService = class extends BaseService {
       const symmetricKey = openWrappedKey(
         this.crypto,
         receiverKey.privateKey,
-        verified.data
+        verified.data,
+        { purpose: "receiver-key", networkId: body.networkId, keyPath: body.keyPath ?? "", keyVersion: body.keyVersion, metadata: {} }
       );
       const plaintext = decryptEnvelopeWithKey(
         this.crypto,
@@ -1548,6 +1792,8 @@ var EncryptionService = class extends BaseService {
       );
       return encOk(plaintext);
     } catch (error) {
+      const routing = routingFailure(error);
+      if (routing) return encErr(decryptionError(routing));
       return encErr(
         encryptionError({
           code: "INVALID_RESPONSE",
@@ -1576,8 +1822,11 @@ export {
   ENCRYPTION_SERVICE_SHORT,
   ENVELOPE_VERSION,
   EncryptionService,
+  KEY_WRAP_V2_ALG,
   NETWORK_NAME_PATTERN,
   NetworkIdError,
+  assertKeyWrapAlgorithm,
+  assertKeyWrapContext,
   base64Decode,
   base64Encode,
   buildCanonicalDecryptRequest,
@@ -1589,6 +1838,7 @@ export {
   canonicalSignedResponse,
   canonicalize,
   checkDecryptInvocationInput,
+  decryptColumn,
   decryptEnvelopeWithKey,
   deriveSignedReceiverKey,
   discoverNetwork,
@@ -1598,11 +1848,15 @@ export {
   generateRandomReceiverKey,
   hexDecode,
   hexEncode,
+  isKeyWrapV2,
   isNetworkId,
   networkDiscoveryKey,
+  openKeyV2,
   openWrappedKey,
   parseEncryptionResource,
   parseNetworkId,
+  readKeyWrapV2,
+  sealKeyV2,
   utf8Decode,
   utf8Encode,
   validateEnvelope,