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

package/dist/encryption/named-keys.d.ts

@@ -1,6 +1,6 @@
-import { E as EncryptionCrypto, I as InlineEncryptedEnvelope, J as Json } from '../types-Bf91gup6.js';
+import { E as EncryptionCrypto, I as InlineEncryptedEnvelope, J as Json } from '../types-Nvi_RckJ.js';
 import { ParsedKeyResource } from './resource.js';
-import '../types-CSd0RYir.js';
+import '../types-DjAP8dve.js';
 
 /**
  * Named-key client: key admin, descriptor reads, `ensureKey` and key-scoped
@@ -103,6 +103,10 @@ interface NamedKeyInvocationInput {
 interface NamedKeyClientConfig {
     host: string;
     crypto: EncryptionCrypto;
+    /** Write TCW2 wraps; disabled by default. */
+    keyWrapV2?: boolean;
+    /** Require TCW2 incoming network-key wraps, not signed receiver responses. Disabled by default. */
+    requireKeyWrapV2?: boolean;
     fetch: typeof fetch;
     /** Network used when a call does not name one. */
     defaultNetworkId: () => string;
@@ -130,6 +134,7 @@ interface KeyCallOptions {
     networkId?: string;
 }
 interface KeyEncryptOptions extends KeyCallOptions {
+    keyWrapV2?: boolean;
     aad?: Uint8Array;
     metadata?: Record<string, string>;
 }

package/dist/encryption/named-keys.js

@@ -85,9 +85,9 @@ function base64Decode(s) {
 function utf8Encode(s) {
   return new TextEncoder().encode(s);
 }
-function canonicalHashHex(sha256, value) {
+function canonicalHashHex(sha2562, value) {
   const canonical = canonicalize(value);
-  return hexEncode(sha256(utf8Encode(canonical)));
+  return hexEncode(sha2562(utf8Encode(canonical)));
 }
 
 // src/encryption/networkId.ts
@@ -135,6 +135,26 @@ function parseNetworkId(networkId) {
   }
   return { networkId, ownerDid, name };
 }
+function parseEncryptionResource(resource) {
+  const networkSeparator = resource.lastIndexOf(":");
+  const nameAndPath = resource.slice(networkSeparator + 1);
+  const pathSeparator = nameAndPath.indexOf("/");
+  const name = pathSeparator === -1 ? nameAndPath : nameAndPath.slice(0, pathSeparator);
+  const networkId = pathSeparator === -1 ? resource : `${resource.slice(0, networkSeparator + 1)}${name}`;
+  const parsed = parseNetworkId(networkId);
+  if (pathSeparator === -1) return parsed;
+  const keyPath = nameAndPath.slice(pathSeparator + 1);
+  const segments = keyPath.split("/");
+  const prefix = keyPath.endsWith("/");
+  if (keyPath.length === 0 || /[\u0000-\u001f\u007f\\]/.test(keyPath) || segments.some(
+    (segment, index) => segment === "." || segment === ".." || segment.length === 0 && !(prefix && index === segments.length - 1)
+  )) {
+    throw new NetworkIdError(
+      `encryption resource has an invalid keyPath (got ${JSON.stringify(resource)})`
+    );
+  }
+  return { ...parsed, keyPath };
+}
 var ENCRYPTION_NETWORK_URN_PREFIX = URN_PREFIX;
 
 // src/encryption/receiverKey.ts
@@ -170,6 +190,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) {
@@ -180,6 +202,152 @@ function encryptionError(input) {
   };
 }
 
+// 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);
+}
+
 // src/encryption/response.ts
 function canonicalSignedResponse(response) {
   const { nodeSignature: _drop, ...rest } = response;
@@ -223,7 +391,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({
@@ -280,7 +448,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({
@@ -303,11 +471,31 @@ 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);
 }
 
+// src/encryption/envelope.ts
+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 ?? {}
+    });
+  }
+}
+
 // src/encryption/resource.ts
 import { pkhDid } from "@tinycloud/bootstrap";
 var SEGMENT_SOURCE = "[a-z0-9][a-z0-9._-]{0,63}";
@@ -390,7 +578,7 @@ function assertPath(path, what) {
     );
   }
 }
-function parseEncryptionResource(uri) {
+function parseEncryptionResource2(uri) {
   if (typeof uri !== "string" || !uri.startsWith(ENCRYPTION_NETWORK_URN_PREFIX)) {
     throw new EncryptionResourceError(
       "not_encryption_urn",
@@ -451,7 +639,7 @@ function canonicalNetworkId(networkId) {
   return parsed.networkId;
 }
 function parseBuilt(resource, networkId) {
-  if (parseEncryptionResource(resource).networkId !== networkId) {
+  if (parseEncryptionResource2(resource).networkId !== networkId) {
     throw new EncryptionResourceError(
       "malformed",
       `built resource does not round-trip (got ${JSON.stringify(resource)})`
@@ -550,7 +738,7 @@ function mapNodeKeyError(status, text, context) {
 function requireKeyTarget(resource) {
   let parsed;
   try {
-    parsed = parseEncryptionResource(resource);
+    parsed = parseEncryptionResource2(resource);
   } catch (error) {
     throw new NamedKeyError(
       "INVALID_KEY_TARGET",
@@ -852,16 +1040,21 @@ var NamedKeyClient = class {
     const { crypto } = this.config;
     const symmetricKey = crypto.randomBytes(32);
     const ciphertext = crypto.authEncrypt(symmetricKey, plaintext, options?.aad);
-    const wrapped = crypto.sealToNetworkKey(
-      base64Decode(descriptor.publicEncryptionKey),
-      symmetricKey
-    );
+    const keyWrapV2 = options?.keyWrapV2 ?? this.config.keyWrapV2 ?? false;
+    const publicKey = base64Decode(descriptor.publicEncryptionKey);
+    const wrapped = keyWrapV2 ? sealKeyV2(publicKey, symmetricKey, {
+      purpose: "network-key",
+      networkId: descriptor.networkId,
+      keyPath: descriptor.keyPath,
+      keyVersion: descriptor.keyVersion,
+      metadata: options?.metadata ?? {}
+    }) : crypto.sealToNetworkKey(publicKey, symmetricKey);
     const encryptedSymmetricKey = base64Encode(wrapped);
     return {
       v: NAMED_KEY_ENVELOPE_VERSION,
       networkId: descriptor.networkId,
       keyPath: descriptor.keyPath,
-      alg: descriptor.alg ?? DEFAULT_ENCRYPTION_ALG,
+      alg: keyWrapV2 ? KEY_WRAP_V2_ALG : DEFAULT_ENCRYPTION_ALG,
       keyVersion: descriptor.keyVersion,
       encryptedSymmetricKey,
       encryptedSymmetricKeyHash: canonicalHashHex(crypto.sha256, encryptedSymmetricKey),
@@ -906,6 +1099,13 @@ var NamedKeyClient = class {
     return results;
   }
   async decryptRoot(envelope) {
+    if (this.config.requireKeyWrapV2) {
+      try {
+        validateEnvelopeKeyWrap(envelope, true);
+      } catch (error) {
+        throw new NamedKeyError("INVALID_ENVELOPE", "Envelope key wrap context is invalid", { cause: error });
+      }
+    }
     if (this.config.decryptRoot === void 0) {
       throw new NamedKeyError("DECRYPT_FAILED", "no root-key decrypt path is configured");
     }
@@ -942,6 +1142,11 @@ var NamedKeyClient = class {
         "envelope.encryptedSymmetricKeyHash does not match encryptedSymmetricKey"
       );
     }
+    try {
+      validateEnvelopeKeyWrap(e, this.config.requireKeyWrapV2 ?? false);
+    } catch (error) {
+      throw new NamedKeyError("INVALID_ENVELOPE", "Envelope key wrap context is invalid", { cause: error });
+    }
     return e;
   }
   async decryptKey(envelope) {
@@ -1003,7 +1208,13 @@ var NamedKeyClient = class {
     if (!verified.ok) {
       throw new NamedKeyError("INVALID_RESPONSE", safeEcho(verified.error.message), { cause: verified.error });
     }
-    const symmetricKey = openWrappedKey(crypto, receiverKey.privateKey, verified.data);
+    const symmetricKey = openWrappedKey(crypto, receiverKey.privateKey, verified.data, {
+      purpose: "receiver-key",
+      networkId: body.networkId,
+      keyPath: body.keyPath,
+      keyVersion: body.keyVersion,
+      metadata: {}
+    });
     try {
       return crypto.authDecrypt(
         symmetricKey,